Partner Benefit Fulfillment Gap Mining

Scope: customer-applied partner benefits such as Momfirst milk analysis, Lovebox, and cleaning/disinfection offers. Legacy source is evidence only. The modern replacement must model a reusable partner benefit lifecycle, not one-off forms, hardcoded recipients, or ad hoc CSV jobs.

Ubiquitous Names

PartnerBenefitCatalog: partner benefit kind, eligibility policy, required applicant fields, delivery-channel rules, and provider contract version.
PartnerBenefitApplication: customer application tied to a reservation booking, selected benefit kind, applicant/contact/shipping facts, consent, and revision.
PartnerBenefitEligibilityDecision: reservation-bound eligibility snapshot with policy version, lifecycle stage, service dates, prior application checks, regional exclusions, and override evidence.
PartnerDeliveryBatch: scheduled external delivery batch with recipient audience, extract query version, artifact format, delivery channel, and retry state.
PartnerDeliverySuppressionReason: reason a candidate was not exported in a scheduled batch.
PartnerResultArtifactGrant: customer-safe result-file access with owner, artifact version, expiry, storage key, and access audit.
PartnerBenefitCancellationLock: cancellation state that prevents deletion after external delivery or provider handoff.

Source Component Flow

flowchart LR
  CleanApi[api/Clean.php]
  MomfirstApi[api/Momfirst.php]
  CleanModel[Clean_model.php]
  MomfirstModel[Momfirst_model.php]
  MomfirstCli[cli/Momfirst.php]
  Download[Clean.php / Momfirst.php download]

  Catalog[PartnerBenefitCatalog]
  Application[PartnerBenefitApplication]
  Eligibility[PartnerBenefitEligibilityDecision]
  Batch[PartnerDeliveryBatch]
  Suppression[PartnerDeliverySuppressionReason]
  ResultGrant[PartnerResultArtifactGrant]
  CancelLock[PartnerBenefitCancellationLock]
  Storage[(Supabase Storage)]
  Communication[CommunicationDelivery]

  CleanApi --> Eligibility --> Application
  MomfirstApi --> Eligibility --> Application
  CleanModel --> Eligibility
  MomfirstModel --> Eligibility
  MomfirstCli --> Batch --> Communication
  Batch --> Suppression
  Application --> CancelLock
  Download --> ResultGrant --> Storage
  Catalog --> Eligibility
  Catalog --> Batch

Source Evidence And Migration Gaps

Benefit Eligibility And Application

Source behavior:

Cleaning application validates login, available reservation, duplicate active application, form fields, and service-start window before inserting a row. Evidence: source-refs/sanmopia_web/application/controllers/api/Clean.php:9-91 and source-refs/sanmopia_web/application/models/Clean_model.php:50-185.
Momfirst validates selected product types from a lookup table, blocks duplicate active applications per type, checks reservation eligibility, then inserts one application per selected product. Evidence: source-refs/sanmopia_web/application/controllers/api/Momfirst.php:10-94 and source-refs/sanmopia_web/application/models/Momfirst_model.php:39-230.
Eligibility contains date windows, status exclusions, duplicate checks, cancelled-booking exclusion, past temporary user exceptions, and commented regional exclusions. Evidence: source-refs/sanmopia_web/application/models/Momfirst_model.php:53-199.

Modern gap:

PartnerBenefitEligibilityDecision should be a policy-versioned decision attached to the reservation booking. Temporary user exceptions and regional exclusions must become auditable overrides or policy rows, never inline ids or hardcoded districts.
PartnerBenefitApplication must support multiple benefit kinds without duplicating flows. Required fields, consent, shipping address, contact, child facts, and provider metadata should come from PartnerBenefitCatalog.

Delivery Batch And External Provider Handoff

Source behavior:

Scheduled Momfirst CLI decides product-specific weekdays, hardcodes a stop date for milk export, writes a temporary CSV, emails provider recipients, deletes the CSV, logs export status, and sends SMS/notification side effects. Evidence: source-refs/sanmopia_web/application/controllers/cli/Momfirst.php:21-170.
Export candidate filtering suppresses rows for not-started service, end-window expiry, insufficient service days, non-terminal status, and special stopped-service cases. Evidence: source-refs/sanmopia_web/application/models/Momfirst_model.php:360-418.
CSV generation strips delimiters, preserves leading zeroes with text prefixes, mixes applicant and reservation facts, and records not-send reasons. Evidence: source-refs/sanmopia_web/application/models/Momfirst_model.php:421-550.

Modern gap:

PartnerDeliveryBatch needs batch id, provider id, benefit kind, schedule policy version, extract query version, generated artifact checksum, recipient policy, delivery attempt state, retry/backoff, and operator repair action.
Provider recipients must be configuration or provider contact records. Direct email addresses and weekday rules do not belong in code.
PartnerDeliverySuppressionReason must be queryable for operator UX and customer support, not buried in an export log side effect.

Cancellation Locks And Result Artifacts

Source behavior:

Momfirst and cleaning cancellation soft-delete application rows, but Momfirst blocks cancellation once export status says the row was sent. Evidence: source-refs/sanmopia_web/application/controllers/api/Momfirst.php:96-137, source-refs/sanmopia_web/application/models/Momfirst_model.php:827-895, and source-refs/sanmopia_web/application/controllers/api/Clean.php:93-128.
Customer result downloads use a document token, reservation ownership check, and a filesystem path under the admin root. Evidence: source-refs/sanmopia_web/application/controllers/Momfirst.php:87-146 and source-refs/sanmopia_web/application/controllers/Clean.php:67-126.

Modern gap:

PartnerBenefitCancellationLock should be derived from delivery batch state, provider acknowledgement, and manual operator locks. Customer-facing disabled reasons must explain the lock without exposing provider internals.
PartnerResultArtifactGrant should use Supabase Storage signed URLs and artifact metadata. Direct filesystem reads from an admin root must disappear.

Implementation Checklist

Contract: define catalog, eligibility decision, application, delivery batch, suppression reason, cancellation lock, and result artifact grant schemas.
Backend: build a reusable partner-benefit domain slice with versioned policies and no product-specific hardcoded ids or recipients.
Backend: add provider delivery batch worker using durable workflow state and artifact storage.
Backend: wire customer cancellation to delivery-state locks and audit.
Frontend: render catalog-driven application forms and cancellation disabled reasons through Nanostores state.
Ops/docs: configure provider recipients, schedules, file format, and retention through SSOT env/config and Starlight docs.