Admin Analytics And System Gap Mining

Admin Analytics And System Gap Mining

Scope: source-mining continuation for admin analytics, report tables, export handoff, price load history, and system administration. Legacy source names below are evidence anchors only; modern work should use the ubiquitous names in this page.

Ubiquitous Names

• BusinessReportCatalog: stable report definitions, audience scope, columns, dimensions, measures, filters, and default period.
• BusinessReportSnapshot: immutable report result for chart, table, and export readers.
• BusinessReportRefreshRequest: command that creates or refreshes one snapshot from current source facts.
• BusinessReportExportRequest: export lifecycle, format, artifact metadata, signed download handoff, failure reason, and repair history.
• OperatorReportTable: authenticated table reader with column visibility, sort, filter, pagination, row drill-through, and Korean labels.
• BranchAccessAnalytics: branch-operator login count, browser/device bucket, IP, and access timestamp analytics.
• MemberActivityAnalytics: member signup, visit duration, reservation conversion, age band, device, and pet-profile analytics.
• CaregiverRecognitionReport: caregiver ranking output used by performance-recognition operations.
• PriceCatalogImportExecution: price workbook load command, source artifact, parser issue list, changed row count, actor, and import result.
• ServiceCalendarHolidayPublication: holiday date/type facts used by service calendar and reservation planning.
• ServiceCalendarHolidayAudit: append-only add, edit, delete, duplicate rejection, actor, reason, and published-at history.

flowchart LR
  Operator[Headquarters or branch operator] --> ReportCatalog[BusinessReportCatalog]
  ReportCatalog --> Refresh[BusinessReportRefreshRequest]
  Refresh --> Snapshot[BusinessReportSnapshot]
  Snapshot --> Chart[Dashboard chart]
  Snapshot --> Table[OperatorReportTable]
  Snapshot --> Export[BusinessReportExportRequest]
  Export --> Storage[(business-report-exports)]
  Export --> Download[Signed download handoff]

  PriceWorkbook[Price workbook artifact] --> Import[PriceCatalogImportExecution]
  Import --> PriceCatalog[Published price catalog entries]
  Import --> ImportHistory[Import execution history]

  HolidayEditor[Holiday editor] --> HolidayPublication[ServiceCalendarHolidayPublication]
  HolidayPublication --> CalendarPolicy[Service calendar policy]
  HolidayEditor --> HolidayAudit[ServiceCalendarHolidayAudit]

Source Evidence Summary

• Admin analytics screens route by report index to sales, visitor, branch access, member, caregiver recognition, and performance pages. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:18-70.
• Chart requests accept posted branch, period, report type, and sort values, then dispatch mutable calculations. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:74-105.
• Table requests accept DataTables draw/start/length/order/search plus datatable_type, map column indexes to source SQL fields, and dispatch by posted sort value. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:107-264.
• The only constructor gate is login; the old admin-only redirect is commented. Branch scope is mostly a posted filter and a post-query removal of the all-branch row. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:6-15, source-refs/sanmopia-admin/application/controllers/Statistics.php:27-40, source-refs/sanmopia-admin/application/controllers/Statistics.php:423-430, and source-refs/sanmopia-admin/application/controllers/Statistics.php:507-514.
• Performance charts are seven separate metric reads: default service-day reservations, unassigned caregiver reservations, consultation request, change request, unconfirmed service balance, rebooking, and first booking. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:283-371, source-refs/sanmopia-admin/application/models/Statistics_model.php:24-62, and source-refs/sanmopia-admin/application/models/Statistics_model.php:166-235.
• Sales charts read payment dates, voucher and normal payment rows, government support, payment fees, coupon amounts, and offline status rows. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:433-499 and source-refs/sanmopia-admin/application/models/Statistics_model.php:1062-1217.
• Member and visitor analytics combine age bands, reservation status buckets, device/browser buckets, visit duration, shopping-mall duration, and pet profile facts. Evidence: source-refs/sanmopia-admin/application/controllers/Statistics.php:374-416, source-refs/sanmopia-admin/application/models/Statistics_model.php:1220-1268, source-refs/sanmopia-admin/application/models/Statistics_model.php:2140-2188, and source-refs/sanmopia-admin/application/models/Statistics_model.php:2191-2461.
• Branch access analytics use branch login logs, browser buckets, IP, and timestamp detail rows, while excluding one hardcoded branch id. Evidence: source-refs/sanmopia-admin/static/js/statistics/officeManager.js:179-399 and source-refs/sanmopia-admin/application/models/Statistics_model.php:1971-2137.
• Caregiver recognition analytics reuse the performance endpoint before loading a caregiver ranking table. Evidence: source-refs/sanmopia-admin/static/js/statistics/supermanager.js:183-315 and source-refs/sanmopia-admin/application/models/Statistics_model.php:647-741.
• Sales table loading works around timeout risk by slicing the selected date range into 30-day calls, merging rows in browser state, then rendering a local table. Evidence: source-refs/sanmopia-admin/static/js/statistics/sales.js:626-693 and source-refs/sanmopia-admin/static/js/statistics/sales.js:704-1227.
• Source table UX is jQuery DataTables with custom Enter-key search. Evidence: source-refs/sanmopia-admin/static/js/statistics/performance.js:335-724, source-refs/sanmopia-admin/static/js/statistics/visitor.js:224-335, source-refs/sanmopia-admin/static/js/statistics/user.js:218-350, and source-refs/sanmopia-admin/application/models/Datatable_model.php:18-116.
• No statistics export route was found in the requested source files; the bundled DataTables build includes Buttons but the statistics views load basic table scripts without explicit export controls. Evidence: source-refs/sanmopia-admin/static/js/datatables.js:1-10, source-refs/sanmopia-admin/application/views/statistics/sales.php:98-152, and source-refs/sanmopia-admin/application/views/table/statistics/*.
• Requested source path source-refs/sanmopia-admin/application/controllers/Load.php is absent from the evidence tree. The nearby load-history evidence is a misnamed holiday information method plus the price workbook CLI load command. Evidence: source-refs/sanmopia-admin/application/controllers/ManageSystem.php:33-40, source-refs/sanmopia-admin/application/controllers/cli/Price.php:13-17, and source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:5337-5400.
• Price workbook load mutates normal/voucher price tables, coupon gifts, additional options, consume-type rows, voucher special/live-in price rows, and price-version rows inside one transaction, while writing progress only to stdout. Evidence: source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:4807-4981, source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:4983-5335, and source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:5337-5400.
• Holiday administration renders an editable table, loads one holiday by date, adds new holiday types implicitly, rejects duplicate dates, and deletes rows without an explicit actor audit. Evidence: source-refs/sanmopia-admin/application/controllers/ManageSystem.php:12-69, source-refs/sanmopia-admin/application/controllers/ajax/ManageSystem.php:14-31, source-refs/sanmopia-admin/application/models/Manage_system_model.php:10-181, source-refs/sanmopia-admin/static/js/manage_system/holiday_list.js:1-107, and source-refs/sanmopia-admin/application/views/table/manage_system/table_holiday_list.php:1-45.
• The holiday list controller detects branch users but leaves the branch branch empty, and the calendar Ajax endpoint returns only date values for a range. Evidence: source-refs/sanmopia-admin/application/controllers/ManageSystem.php:21-30 and source-refs/sanmopia-admin/application/controllers/ajax/ManageSystem.php:20-30.

Missing Feature Queue

• BusinessReportCatalog. Status: Pending. Need one catalog of report definitions for performance, sales, member activity, visitor activity, branch access, and caregiver recognition. Source strings such as datatableForSales or column names such as FEE_PRICE remain adapter evidence, not contract names.
• ScopedBusinessReportReadPolicy. Status: Partial. Snapshot tables and export tables exist, but each report still needs branch/HQ scope proof, row-level visibility tests, and hardcoded branch exclusion replacement.
• PerformanceDashboardSnapshot. Status: Pending. Need source-parity measures for unassigned caregiver, consultation request, change request, unconfirmed service balance, rebooking, first booking, stop, extension, and cancellation ratio. Stop metrics must distinguish status 12 stop-requested from status 13 stopped, preserve normal/voucher split, and share the stopped-voucher >=3 service-day eligibility rule with settlement.
• SalesRevenueSnapshot. Status: Partial. Existing business-report storage can hold snapshots, but source parity still needs deposited-date period semantics, voucher/normal payment separation, coupon deduction, offline status rows, fee basis, revenue, row drill-through reservation ids, and the 30-day timeout workaround replaced by backend refresh.
• MemberActivityAnalytics. Status: Pending. Need member signup, reservation conversion, cancellation, visit duration, shopping duration, device/browser, age band, and pet-profile read models with privacy-safe masking rules.
• BranchAccessAnalytics. Status: Pending. Need branch login detail rows, browser/device normalization, IP visibility policy, branch scope, and export handoff without hardcoded branch ids.
• CaregiverRecognitionReport. Status: Partial. Performance-recognition backend exists elsewhere, but report-table parity still needs ranking snapshot, caregiver profile/grade fields, branch scope, and operator UI.
• OperatorReportTable. Status: Pending. Replace jQuery DataTables draw, sort, and search payloads with Sanmopia contracts plus OSS table UI. Enter-key search can stay as UX behavior, not API protocol.
• BusinessReportExportRequest. Status: Partial. Snapshot/export tables and storage foundation exist, but report-specific export buttons, artifact build workers, retry/cancel/repair state, signed-download refresh, and history UI remain missing for admin analytics beyond settlement exports.
• BusinessReportRefreshSchedule. Status: Pending. Need scheduled and operator-triggered refresh jobs with period, report kind, source revision, calculation version, failure reason, and idempotency key.
• PriceCatalogImportExecution. Status: Partial. Import batches and private workbook storage exist, but load-history UX, CLI/stdout capture, actor attribution, changed-row counts, issue list, replay/rollback policy, and normal/private-care coverage remain incomplete.
• ServiceCalendarHolidayPublication. Status: Partial. Holiday rows and planning snapshots exist. Backend now exposes POST /service-calendar-holiday-change-decisions so add/modify/delete from the legacy global holiday table is treated as create/revise/withdraw policy intent; duplicate observed dates return requires_policy_revision with existing policy ids instead of trusting UI alerts or raw date CRUD. Remaining work: operator UI, branch-specific closure command execution, provider import, and publish/recalculate workflow binding.
• ServiceCalendarHolidayAudit. Status: Partial. Backend now records append-only holiday publication and branch override revisions with actor, reason, idempotency key, expected revision, effective date, provider source reference, and source fingerprint. Supabase persists audit snapshots and revision rows in sanmopia_service_calendar_holiday_audits and sanmopia_service_calendar_holiday_audit_revisions; SpiceDB-protected API commands expose headquarters publication and branch override writes through contract JSON schemas. Backend now also exposes POST /service-calendar-holiday-impact-previews, backed by the Supabase RPC sanmopia_list_service_calendar_holiday_impact_candidates, so operators can preview affected reservation plans, branch ids, service dates, and downstream follow-up impact kinds before publication or branch override repair. Backend also exposes POST /service-calendar-holiday-change-decisions to bind the source duplicate-date add/edit/delete behavior to a policy decision read model. Remaining work: import execution from the OSS holidays provider, operator repair/history UI, and execution binding after decisions are accepted.
• BranchServiceClosurePolicy. Status: Pending. The source holiday admin has only global holiday rows and an empty branch-user branch. Modern service calendar needs branch-scoped closures, emergency closure ranges, partial-day operations if later introduced, valid period, approval state, and affected reservation/caregiver-assignment warning before publication.
• SourceEvidencePathReconciliation. Status: Pending. Correct the requested missing Load.php evidence owner in source maps or create a note that load-history evidence now resolves through price import execution and service-calendar holiday loading.

Acceptance Proof Needed

• Contract tests for every report kind, scope, period, column, row drill-through, and export format.
• Backend tests proving report snapshots are immutable after source facts or price policy change.
• RLS and authorization tests for headquarters operators, branch operators, and private member/device/IP fields.
• Frontend report table tests for sorting, searching, pagination, empty states, branch selector behavior, drill-through links, export status, retry, and signed-download expiry.
• Price import history tests for accepted workbook, parser issue, duplicate price row, changed row, failed transaction, replay, and operator-visible result.
• Service-calendar administration tests for add, edit, duplicate date, delete, branch closure, national holiday seed, affected reservation warning, and audit read model.