Manager And Customer Portal Gap Mining

Scope: source mining for the caregiver web app and customer reservation portal. Legacy PHP is behavior evidence only. The migration target is DDD/CQRS feature slices with modern ubiquitous names, Supabase-backed projections, Restate-owned workflow state, and portal state built from contracts instead of source status numbers.

Ubiquitous Names

Use these names when cutting backend, contract, and frontend work:

CaregiverWorkScheduleProjection: caregiver-visible proceeding/completed assignments, service period, role, active block, and customer contact policy.
CaregiverAssignmentAccessWindow: time-bounded read access for schedule detail, report history, and payout detail after service end.
CaregiverServiceDayAttendance: one caregiver, one reservation assignment, one service date, one attendance event with idempotency and audit evidence.
CaregiverReportObligation: generated first/progress/last report duty tied to service calendar, assignment term, notification, and submission lock state.
CaregiverServiceRecordSubmission: health/service record for a service day, separate from the narrative daily report.
CustomerReservationPortalProjection: mother-facing reservation state, payment summary, assigned-caregiver visibility, report tasks, document access, and allowed customer actions.
CustomerReservationChangeIntent: customer request for schedule change, extension, cancellation, service stop, payment change, or address/contact correction.
CaregiverPayoutStatement: caregiver-facing final pay view with frozen quote basis, withholding, overrides, bank reference, and receipt status.
CaregiverPerformanceSeason: modern replacement for yearly ranking/cache behavior such as WinTheRace.
MatchingOptimizationInput: score, distance, transit time, schedule availability, pet constraint, grade, branch scope, and policy version captured before recommendation.

Portal Component Flow

flowchart LR
  Mother[Mother/customer portal]
  Caregiver[Caregiver portal]
  BranchManager[Branch manager]

  CustomerProjection[CustomerReservationPortalProjection]
  ScheduleProjection[CaregiverWorkScheduleProjection]
  Attendance[CaregiverServiceDayAttendance]
  Obligation[CaregiverReportObligation]
  Report[DailyCareReportSubmission]
  ServiceRecord[CaregiverServiceRecordSubmission]
  Payout[CaregiverPayoutStatement]
  Matching[MatchingOptimizationInput]
  Assignment[CaregiverAssignmentDecision]
  Docs[PrintableDocumentAccessGrant]
  Workflow[Restate workflow state]
  Storage[(Supabase Storage)]

  Mother --> CustomerProjection
  CustomerProjection --> Docs
  CustomerProjection --> Workflow
  Mother -->|change/extend/cancel intent| Workflow

  Caregiver --> ScheduleProjection
  ScheduleProjection --> Attendance
  ScheduleProjection --> Obligation
  Obligation --> Report
  ScheduleProjection --> ServiceRecord
  Caregiver --> Payout

  BranchManager --> Matching
  Matching --> Assignment
  Assignment --> ScheduleProjection
  Report --> Docs
  ServiceRecord --> Docs
  Docs --> Storage

Source Evidence And Migration Gaps

Caregiver Schedule And Detail Access

Source behavior:

Caregiver schedule tabs load assignments by signed-in manager and proceeding or completed type. Evidence: source-refs/sanmopia-manager/application/controllers/Schedule.php:14-24.
Detail access checks whether the reservation belongs to the caregiver, loads delivery data, manager profile, preference memo, voucher add-price data, main-caregiver service/report data, and sub-caregiver service/report data. Evidence: source-refs/sanmopia-manager/application/controllers/Schedule.php:27-75.
Source blocks detail access 90 days after service end by redirecting back to the proceeding schedule list. Evidence: source-refs/sanmopia-manager/application/controllers/Schedule.php:45-49.

Modern gap:

CaregiverWorkScheduleProjection must be assignment-scoped, not reservation table scoped. It should include contract assignment key, role, handoff order, service period, visible customer contact fields, delivery facts, report task count, service-record task count, attendance state, payout state, and access expiry.
CaregiverAssignmentAccessWindow must decide when detail, report, service record, and payout reads expire. Do not hardcode “90 days” in a portal view.
Main and assistant caregiver views must share one read model with role-scoped visibility instead of separate PHP branches.

Attendance And Customer Notification

Source behavior:

Attendance submit accepts a reservation id, checks login, rejects if the same manager has any attendance row for today, inserts one attendance row, then sends a customer push notification. Evidence: source-refs/sanmopia-manager/application/controllers/Attendance.php:18-79.
Eligibility is derived from today’s manager notifications. If there is no normal notification row, source checks extra Saturday/holiday work dates. Evidence: source-refs/sanmopia-manager/application/models/Attendance_model.php:19-49.
Assistant caregiver eligibility is recovered through the sub-caregiver table and returns a synthetic read flag from attendance existence. Evidence: source-refs/sanmopia-manager/application/models/Attendance_model.php:52-95.
Duplicate detection is keyed by caregiver and calendar date, not by reservation assignment, service date, or contract assignment key. Evidence: source-refs/sanmopia-manager/application/models/Attendance_model.php:97-109.

Modern gap:

CaregiverServiceDayAttendance must be keyed by reservation booking, contract assignment key, caregiver profile, role, and service date. It should have idempotency key, source obligation id, created actor, correction reason, device/app evidence when available, and notification outbox status.
Attendance should be generated from CaregiverReportObligation or service calendar due work, not from notification rows as the source of truth.
Customer push is a side effect through communication delivery. It should read an attendance-accepted event and write dispatch audit, not run inline inside the attendance transaction.

Caregiver Daily Report And Service Record

Source behavior:

Caregiver report entry validates login, ownership by notification/reservation, unread notification status, report type, and preference data before rendering questions. Evidence: source-refs/sanmopia-manager/application/controllers/Report.php:5-55.
Report questions are loaded from DB by day type: first day, progress day, or last day. Answers can be selected-list answers or essay text. Evidence: source-refs/sanmopia-manager/application/models/Report_model.php:12-66.
Report save writes answer rows, then marks the notification as read. Evidence: source-refs/sanmopia-manager/application/controllers/Report.php:64-108 and source-refs/sanmopia-manager/application/models/Report_model.php:68-101.
Service records are a separate caregiver flow in the manager portal and are later consumed by printable output. Evidence: source-refs/sanmopia-manager/application/controllers/Service.php:58-180 and source-refs/sanmopia-manager/application/models/Service_model.php:1-136.

Modern gap:

CaregiverReportObligation should own due date, question-set kind, notification dispatch status, read/submitted state, and lock policy.
DailyCareReportSubmission should reference the obligation and definition version. Marking a notification as read cannot be the canonical completion state.
CaregiverServiceRecordSubmission must stay separate because it contains service-day health/recovery facts, duplicate policy, correction history, and an explicit attendance outbox key. Source primary rows use MANAGER_SERVICE_TB; sub rows use MANAGER_SUB_SERVICE_TB, but schedule readers also reference mismatched SUB_MANAGER_SERVICE_TB names. Duplicate source checks use reservation/date only, not caregiver/role/handoff. Evidence: source-refs/sanmopia-manager/application/models/Service_model.php:20-52, source-refs/sanmopia-manager/application/models/Service_model.php:76-135, source-refs/sanmopia-manager/application/models/Reservation_model.php:539-554.
Schedule UI must render backend-owned action availability. Source view code counts writable service/report links and hides sub-caregiver visibility behind hardcoded manager id 1; controller also owns a 90-day access window. Evidence: source-refs/sanmopia-manager/application/views/schedule/schedule_info.php:210-268, source-refs/sanmopia-manager/application/controllers/Schedule.php:44-49.
Route/date construction must be backend-owned. Source routes expose /service/{notifyIndex}, while the controller needs notifyIndex and notifyDate; only the schedule view passes both. Evidence: source-refs/sanmopia-manager/application/config/routes.php:56-57, source-refs/sanmopia-manager/application/views/notify/notify_main.php:51-57, source-refs/sanmopia-manager/application/views/home/main.php:253-258, source-refs/sanmopia-manager/application/views/schedule/schedule_info.php:227-230.
Notification read state must stay separate from attendance. Source Notify_model::updateReadNotify can create primary and first sub-manager attendance rows as a hidden side effect of reading a notification. Evidence: source-refs/sanmopia-manager/application/models/Notify_model.php:380-437.
Document rendering should consume frozen report and service-record snapshots for A4 output.

Customer Reservation Portal State

Source behavior:

Customer reservation pages split proceeding, completed, detail, report, sub-report, receipt, document, and change-payment screens. Evidence: source-refs/sanmopia_web/application/controllers/MyReservation.php:21-376.
Customer reservation API accepts separate commands for birth info, service start date, reservation request, continuation, expected end date, Saturday/holiday calculation, and delivery data. Evidence: source-refs/sanmopia_web/application/controllers/api/Reservation.php:14-451.
Customer document download uses a tokenized API path. Evidence: source-refs/sanmopia_web/application/controllers/api/ReservationDocument.php:9-55.
Customer-authored daily report APIs save service-day review and final-day caregiver rating. Evidence: source-refs/sanmopia_web/application/controllers/api/Report.php:11-115.

Modern gap:

CustomerReservationPortalProjection must be the only mother-facing reservation summary. It should expose customer-actionable state, allowed actions, report tasks, receipt/document access, assigned caregiver visibility, and payment summary without leaking settlement board ids, gateway payloads, branch memo, workflow internals, or raw status codes.
CustomerReservationChangeIntent must route every customer request through Restate workflow and stage/actor policy: schedule change, extension, cancellation, service stop, payment change, delivery data correction, and birth/contact correction.
Document and receipt buttons should use PrintableDocumentAccessGrant and signed Supabase Storage handoff, not live PDF generation or direct gateway receipt URLs as the only durable proof.

Smart Matching And Optimization Inputs

Source behavior:

Smart matching stores religion, pet constraints, isolation flag, ranked preferences, caregiver personality answers, and free-text preference memo. Evidence: source-refs/sanmopia_web/application/models/Smart_matching_model.php:12-290.
Customer-side matching combines preference and personality scores, excludes pet-allergy caregivers when pet info exists, filters branch and grade, and can reorder by cached transit time. Evidence: source-refs/sanmopia_web/application/models/Manager_matching_model.php:16-146.
Recommendation-by-reservation filters active/non-deleted matching data, schedule availability, branch, grade, search text, random tie seed, and then reorders by distance when service address coordinates exist. Evidence: source-refs/sanmopia_web/application/models/Manager_matching_model.php:167-317.

Modern gap:

MatchingOptimizationInput should persist every input used for candidate ranking: preference score, personality score, distance, transit time, provider result, pet exclusion, grade filter, branch scope, schedule availability, policy version, and randomization seed.
CaregiverCandidateSnapshot should be created from those inputs before a branch actor makes a CaregiverAssignmentDecision.
Use an OSS optimizer when moving beyond deterministic ranking. Candidate generation can stay deterministic first, then introduce OR-Tools or another constraint solver for multi-reservation assignment optimization.

Caregiver Payout And Performance View

Source behavior:

Caregiver pay detail recalculates salary from voucher add-ons, additional days, service balance, custom main/sub salary, and tax mode at read time. Evidence: source-refs/sanmopia-manager/application/helpers/salary_helper.php:8-227, source-refs/sanmopia-manager/application/views/pay_info_detail.php:165-263, and source-refs/sanmopia-manager/application/models/Reservation_manager_salary_model.php:21-181.
Caregiver ranking loads a yearly Redis cache, sorts by all-grade score, and computes tie-aware ranking for the signed-in caregiver. Evidence: source-refs/sanmopia-manager/application/models/Win_the_race_model.php:28-108.

Modern gap:

CaregiverPayoutStatement should read frozen compensation quote and payout instruction facts. Amounts shown after closeout must not recalculate from current policy rows.
CaregiverTaxElection, CaregiverSalaryOverride, and SubCaregiverCompensationShare should be explicit facts linked to the contract assignment key.
CaregiverPerformanceSeason should replace yearly cache keys with versioned season, metric rules, scorecard facts, manual adjustments, and publish state.

Feature-Level Work Queue

Backend: expose CaregiverWorkScheduleProjection read API with assignment access window and role-scoped visibility.
Backend: harden CaregiverServiceDayAttendance with reservation assignment key, service date, idempotency, and communication outbox.
Backend/contract: split CaregiverReportObligation, DailyCareReportSubmission, and CaregiverServiceRecordSubmission read and command contracts.
Backend/contract: create CustomerReservationPortalProjection and CustomerReservationChangeIntent contracts.
Backend: persist MatchingOptimizationInput and CaregiverCandidateSnapshot before assignment decisions.
Backend/frontend: expose CaregiverPayoutStatement from frozen payout instructions; never recompute closed amounts from current policy.
Docs: add every migrated portal command to the source feature checklist with source evidence, modern name, actor, status, and verification command.