Status Payment Settlement Source Map

This pass records source behavior as naming evidence only. Source table names, numeric ids, Korean status labels, provider payload keys, and UI flags stay in adapters, compatibility catalogs, import scripts, or source evidence. Modern contracts, commands, projections, and folders should use the ubiquitous names below.

Ubiquitous Names

Modern name	Use for
`ReservationLifecycleStateCatalog`	Versioned compatibility map from source reservation status ids to stable lifecycle states, display groups, and allowed command families.
`ReservationLifecycleDisplayProjection`	Customer, branch, HQ, and caregiver-facing lifecycle text, color, disabled reason, and next-action metadata.
`ReservationLifecycleTransitionRule`	Accepted transition rule for customer request, operator approval, payment callback, virtual-account timeout, cron, settlement, and completion paths.
`VirtualAccountPaymentLifecycle`	Issued account, notice sent, waiting, deposit closed, expiring soon, expired, and reservation-status impact.
`PreReservationPaymentLifecycle`	Pre-reservation deposit, waiting deposit, conversion, cancellation, and refund/benefit side effects.
`SourcePaymentCompatibilityCatalog`	Adapter-owned map for source payment type/status rows and hardcoded legacy payment-status ids.
`PaymentProductPlan`	Sellable or operator-billable product: customer deposit, customer balance, service balance, pre-reservation, gift coupon, and change-payment.
`PaymentCloseoutEvent`	Idempotent provider-paid event with amount, method, ledger purpose, charge snapshot, and settlement-continuation request.
`PaymentRefundStatusMapping`	Adapter-owned source-to-ledger mapping for paid, unpaid, waiting, refunded, and provider-cancelled payment rows.
`PaymentRefundIntent`	Ledger-backed refund command input, amount balance, policy explanation, provider capability, and operator override.
`PaymentChangeAdjustment`	Mother-payable correction amount, coupon allocation, operator completion, and settlement-continuation state.
`ServiceBalancePaymentCloseout`	Reservation service-balance receivable setup, zero-balance auto-completion, and caregiver receipt-state initialization.
`CaregiverServiceBalanceReceiptCloseout`	Branch-paid and caregiver-confirmed receipt state for each caregiver recipient, replacing source primary/sub-only flags.
`BranchSettlementSourceStatusMap`	Adapter-owned compatibility map for legacy branch settlement board status, board flags, and line acknowledgement flags.
`BranchSettlementStatement`	Branch/HQ monthly board with frozen line items, status, actor commands, and transition audit.
`SettlementLineAcknowledgement`	Per-line acknowledgement for reservation payment, coupon, cancelled gift coupon commission, delivery, membership due, and manual rows.
`SettlementCompletionReview`	Completion decision from line acknowledgements and branch/HQ flags.
`SettlementTransitionAudit`	Append-only settlement transition with actor, command kind, expected revision, before/after status, and source board id evidence.
`ReservationExternalSettlementCounterpartyStatus`	Reservation-scoped completion projection replacing source `DANBEE_STATUS_FL`, `CENTRAL_STATUS_FL`, and other-office side flags.
`InterOfficeSettlement`	Other-office settlement by reservation, customer branch, service branch, period, line direction, and acknowledgement side.
`PrintableDocumentCatalog`	Customer-visible and admin/export-only document definitions with service eligibility and readiness gates.
`PrintableTemplateVersionManifest`	Versioned template-file manifest for legacy numeric document ids, renderer, paper format, and output format.
`PrintableDocumentAccessGrant`	Actor-scoped document access grant with expiry, revocation, signed handoff, and audit.
`CustomerReceiptArtifact`	Receipt access tied to payment/refund ledger state, provider pointer, optional rendered fallback, and grant state.
`PrintableDocumentBundle`	Stored bundle artifact referencing rendered artifact ids, missing-item diagnostics, and zip metadata.
`CaregiverCandidateSnapshot`	Frozen candidate card with score, grade, branch, pet/schedule exclusions, distance, transport, and ranking policy.
`CaregiverAssignmentDecision`	Final branch/HQ assignment decision with selected candidate snapshot, actor, reason, policy version, and impacted contract/payout facts.
`CaregiverTravelEvidence`	Distance, public-transport duration, provider result, fallback reason, freshness, and ranking priority.
`CareTeamCompensationSlot`	Compensation input per care-team assignment key, role, handoff order, service days, grade, and rate rule.
`CaregiverPayoutPolicyProfile`	Versioned payout policy for weekend/holiday additions, voucher add-ons, tax election, service balance override, and custom pay.
`CaregiverPayoutInstruction`	Frozen payable instruction with amount, tax, bank destination reference, memo, payout status, and audit.
`CaregiverPayoutAcknowledgement`	Branch deposit acknowledgement and caregiver payout receipt acknowledgement facts used by settlement-continuation guards, separated from receipt-state projections and reservation status.

Source Status Lifecycle

Evidence inspected:

source-refs/sanmopia-admin/application/config/constants.php:116-160
source-refs/sanmopia_web/application/config/constants.php:48-92
source-refs/sanmopia-manager/application/config/constants.php:111-132
source-refs/sanmopia_web/application/models/Reservation_model.php:990-1112
source-refs/sanmopia_web/application/models/Reservation_model.php:1452-1514
source-refs/sanmopia_web/application/models/Reservation_model.php:2960-3025
source-refs/sanmopia_web/application/models/Reservation_model.php:3261-3272

Source behavior to preserve as facts:

Source reservation ids span draft/writing, reservation, consultation, date-prepared, date-confirmed, in-progress, settlement, done, change request, cancellation request, cancelled, extension request, extension, stop request, stopped, virtual-account waiting, pre-reservation, pre-reservation waiting, virtual-account expired/cancelled, pre-reservation cancelled, and offline.
Customer display collapses some numeric states into different visible labels, messages, and colors. Display state is not the same concept as lifecycle state.
Customer cancellation can become immediate cancellation when timing rules match, then triggers refund, coupon restore, and benefit cancellation side effects.
Customer change and stop requests write request rows and status changes but do not complete downstream calendar, report, refund, or settlement work.
Virtual-account expiry scans waiting reservations and writes a source status change plus change-log evidence.
Stopped-service reporting still infers stop day from change-log text.

Modern migration requirement:

ReservationLifecycleStateCatalog owns source id compatibility and maps each source id to stable state code, display bucket, command family, and actor visibility. Generated contracts must not expose raw ids.
ReservationLifecycleTransitionRule owns customer request, operator, payment-callback, virtual-account deadline, cron, and settlement/completion transitions. Source ids become rule inputs, not rule names.
ReservationLifecycleDisplayProjection owns visible text, color, prompt, disabled reason, command target, and required facts for each actor.
ServiceSuspensionInterval owns stop/resume facts. Reports, documents, refunds, matching, and settlement must not parse change-log text.

Payment And Refund Mappings

Evidence inspected:

source-refs/sanmopia_web/application/models/Constdata_model.php:29-68
source-refs/sanmopia_web/application/models/Payment_model.php:101-230
source-refs/sanmopia_web/application/models/Payment_model.php:327-380
source-refs/sanmopia_web/application/models/Payment_model.php:383-440
source-refs/sanmopia_web/application/models/Reservation_model.php:2960-2981
source-refs/sanmopia_web/application/models/Payment_model.php:512-705
source-refs/sanmopia_web/application/models/Payment_model.php:740-845
source-refs/sanmopia_web/application/models/Payment_model.php:856-900
source-refs/sanmopia_web/application/models/Reservation_model.php:1418-1449
source-refs/sanmopia_web/application/views/mypage/reservation_receipt.php:35-128
source-refs/sanmopia-admin/application/views/reservation_status/pre_reservation_detail.php:90-118
source-refs/sanmopia-admin/application/controllers/Reservation.php:1023-1088
source-refs/sanmopia-admin/application/controllers/Manager.php:980-1135
source-refs/sanmopia-admin/application/models/Reservation_model.php:2453-2535
source-refs/sanmopia-admin/application/models/Reservation_model.php:2568-2625
source-refs/sanmopia-admin/application/models/Reservation_model.php:3095-3148
source-refs/sanmopia-admin/application/models/Reservation_model.php:3507-3555
source-refs/sanmopia-admin/application/models/Reservation_model.php:5559-5595
source-refs/sanmopia-admin/application/libraries/Kcppayment.php:31-60

Source behavior to preserve as facts:

Payment type/status ids are read from LIST_PAYMENT_TYPE_TB and LIST_PAYMENT_STATUS_TB by source value names, but source code also hardcodes PAYMENT_STATUS_LIST_ID_FK values: 0 unpaid/manual-pending, 1 paid, 2 refunded, and virtual-account waiting 3. The virtual-account deadline scan filters payment status 3 while reservation status is source 14.
Initial payment creates customer deposit, customer balance, and service-balance rows with different status defaults and status changes.
Source service-balance closeout creates a branch-manager service-balance receivable row. A zero service-balance amount auto-completes branch payment and caregiver receipt confirmation, while a positive amount starts as payment required. Later manager actions split branch-paid/awaiting caregiver confirmation from caregiver-confirmed receipt, with separate main/sub source columns that modern code must replace with caregiver-recipient slots.
Virtual-account issue changes payment rows to waiting and can also change the reservation lifecycle state to waiting.
Virtual-account deposit callback closes voucher deposit, voucher balance, pre-reservation deposit, or normal deposit differently, including different reservation-state and communication side effects.
Full refund loops provider contexts, calls the gateway refund path, and marks payment rows refunded after provider success.
Pre-reservation payment changes reservation status, pre-reservation flag, price index, payment version, coupon usage, and shopping-mall benefit facts.
Admin pre-reservation status editing is not the same as ordinary cancellation: the detail selector exposes only source statuses 9, 15, 16, 17, and 19, while source status 18 remains defined as pre-reservation cancelled but is not selectable in that screen. The inspected refund trigger runs when the posted status is 9.
Admin pre-reservation refund lookup is hardcoded to payment type id 6 and paid status id 1, extracts KCP method/order/transaction context, and calls KCP refund. Needs source confirmation: the inspected pre-reservation refund path does not update the payment row to refund status 2, unlike the normal cancellation refund loops.
Change-payment creates the latest adjustment row, deletes unpaid prior rows, then stores provider context and deposit time after payment.
Customer receipt view accepts paid or refunded source statuses and builds a provider receipt URL from stored provider context.

Modern migration requirement:

SourcePaymentCompatibilityCatalog maps source payment type/status rows, source value names, hardcoded unpaid/paid/refund/waiting ids, and source table families at adapter/import boundaries only.
PaymentProductPlan owns payment product meaning. ReservationPaymentPurpose remains ledger obligation language, not product catalog language.
PaymentCloseoutEvent owns provider-paid state, deposited time, finalized charge snapshot, communication route, and settlement-continuation request.
PaymentRefundStatusMapping, PaymentRefundIntent, and PaymentLedger own refund state; UI or PHP-compatible rows must not set refund truth.
PreReservationCancellationRefundCommand must disambiguate source status 9 cancellation, source status 18 pre-reservation cancelled, and source pre-reservation waiting/cancelled display states before invoking provider refund or ledger mutation.
ServiceBalancePaymentCloseout must initialize service-balance receivable and CaregiverServiceBalanceReceiptCloseout rows from backend-owned caregiver recipient slots. Source payment type id 3, PAYMENT_STATUS_ID_FK, SUB_PAYMENT_STATUS_ID_FK, BALANCE_PRICE_PAYMENT_FL, and SUB_BALANCE_PRICE_PAYMENT_FL remain adapter/storage evidence only.
CaregiverPayoutAcknowledgement is the settlement guard fact. The receipt state projection is an operational view and must not be the only source of payout receipt truth. Runtime proof on 2026-07-13 added POST /caregiver-payout-acknowledgements/caregiver-receipts so the payment continuation guard can observe caregiver receipt acknowledgement before branch/HQ settlement completion.
2026-07-05 backend foundation: source payment type ids 1, 2, 3, 6 and pre-reservation collection status ids 0, 1 are now isolated in source_reservation_payment_acl.py. PreReservationRefundPolicy receives ReservationPaymentPurpose and PreReservationPaymentCollectionState, so source numeric payment flags no longer enter the domain refund policy.
2026-07-05 backend foundation: ServiceBalanceBook.plan_payment_closeout and CloseReservationServiceBalanceHandler now model positive-balance waiting state, zero-balance automatic receipt completion, and any number of caregiver recipients without copying source primary/sub flag columns into contracts.
PreReservationDetailCommit should separate status, contact/address, service date, payment-date display, and reservation-date-regeneration effects. A broad admin save must not remain the authority for payment/refund state.
VirtualAccountPaymentLifecycle owns issue/deposit/expiry states and exposes progress through workflow/status projections.
CustomerReceiptArtifact owns provider receipt pointers and rendered receipt fallback behind signed access grants.

Branch And Head-Office Settlement

Evidence inspected:

source-refs/sanmopia-admin/application/controllers/Calculate.php:138-315
source-refs/sanmopia-admin/application/controllers/Calculate.php:337-430
source-refs/sanmopia-admin/application/controllers/Calculate.php:434-498
source-refs/sanmopia-admin/application/models/Payment_model.php:26-32
source-refs/sanmopia-admin/application/models/Payment_model.php:96-175
source-refs/sanmopia-admin/application/models/Payment_model.php:392-620
source-refs/sanmopia-admin/application/models/Payment_model.php:768-980
source-refs/sanmopia-admin/application/models/Payment_model.php:2370-2523
source-refs/sanmopia-admin/application/models/Payment_model.php:2977-3052
source-refs/sanmopia-admin/application/models/Payment_model.php:4265-4416
source-refs/sanmopia-admin/static/js/calculate_detail.js:220-337
source-refs/sanmopia-admin/static/js/calculate_detail.js:930-1140

Source behavior to preserve as facts:

Settlement row status values are board-local lifecycle flags, not reservation statuses. The source meanings are no branch deposit yet, branch deposit waiting for HQ confirmation, settled, arrears deposit waiting for HQ confirmation, and arrears.
2026-07-05 backend foundation: branch settlement board source status codes 0, 1, 2, 3, and 4 are isolated in branch_settlement_status_acl.py. BranchSettlementBoardStatus no longer exposes persisted-code conversion methods, so STATUS_FL remains an adapter concern instead of domain lifecycle language.
2026-07-05 backend foundation: external settlement counterparty source status codes 0 and 1 are isolated in external_settlement_counterparty_status_acl.py. The domain ExternalSettlementCounterpartyCompletionState no longer maps raw persisted codes directly.
HQ request and branch acknowledgement share one broad action path with selected reservation ids, payment types, coupon ids, cancelled gift coupon ids, membership/delivery flags, manual rows, messages, memo, branch id, board id, actor type, and period.
Board completion depends on cancelled gift coupon commission, membership due, delivery fee, detail row acknowledgements, coupon row acknowledgements, and manual rows.
UI JavaScript still recomputes result amount from delivery, membership, coupon commission, manual rows, and status flags.
Branch/HQ history readers recompute unpaid buckets and display statuses from board rows, detail rows, coupon rows, manual rows, and mutable branch rows.
Inter-office settlement updates status by actor side and calculates fee from posted total/result amounts.

Modern migration requirement:

BranchSettlementStatement owns statement status as a modern state machine: deposit_requested, branch_deposit_acknowledged, head_office_approved, arrears_deposit_acknowledged, and arrears_pending. Source STATUS_FL stays adapter evidence.
ReservationExternalSettlementCounterpartyStatus owns counterparty completion state. Source DANBEE_STATUS_FL, CENTRAL_STATUS_FL, OTHER_OFFICE_STATUS_FL, BRANCH_TYPE, and source payment status 1 stay application/import adapter evidence.
RequestSettlementDeposit, AcknowledgeBranchSettlementDeposit, ApproveHeadquartersSettlement, RequestSettlementArrearsDeposit, and AcknowledgeSettlementArrearsDeposit stay separate commands with actor kind, expected revision, idempotency key, and audit.
SettlementLineAcknowledgement owns reservation-payment, coupon, cancelled-gift-coupon-commission, membership, delivery, and manual line state.
SettlementCompletionReview owns the completion/arrears decision from frozen line facts. Browser amount recalculation becomes diagnostic only.
SettlementTransitionAudit must carry source board id evidence and real actor context; source log rows that omit board linkage are insufficient.
InterOfficeSettlement owns service branch, customer branch, period, line direction, fee basis, and side-specific acknowledgement state.

Documents And Receipts

Evidence inspected:

source-refs/sanmopia-admin/application/config/constants.php:219-257
source-refs/sanmopia_web/application/views/mypage/reservation_document.php:38-139
source-refs/sanmopia_web/application/controllers/api/ReservationDocument.php:9-55
source-refs/sanmopia_web/application/models/User_model.php:461-489
source-refs/sanmopia_web/application/views/mypage/reservation_receipt.php:35-128
source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:18-39
source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:3914-4199
source-refs/sanmopia-admin/application/models/Spreadsheet_model.php:4284-4412

Source behavior to preserve as facts:

Legacy document ids cover contracts, fee agreements, welfare plans, deposit calculations, privacy consent, primary/sub service records, voucher receipt, notices, daily reports, monitoring survey, reservation list, terms, integrated bundle, consultation report, settlement export, and voucher service-end notice.
Customer document page chooses document lists by service type and shows voucher end notice near service end or stopped state.
Customer document download uses a two-hour token and live cross-service PDF generation.
Admin document export renders spreadsheets, copies static PDFs, generates zip files in request time, writes temporary files, and deletes them after download.
Some templates are already PDFs; most spreadsheet templates are converted to PDF through a network conversion service.
Receipt view exposes provider order/transaction identifiers and opens the provider receipt URL in the browser.

Modern migration requirement:

PrintableDocumentCatalog owns document eligibility, actor visibility, service-type gates, readiness reasons, and receipt/document separation.
PrintableTemplateVersionManifest maps legacy numeric ids and template files to modern document kind, template version, renderer, paper format, and output format. Numeric ids stay import/evidence only.
PrintableDocumentAccessGrant replaces token-only URLs with actor, document kind, format, expiry, revocation, signed URL handoff, and access audit.
PrintableRenderRequest persists render status, snapshot hash, template version, output object, checksum, and retry state.
PrintableDocumentBundle references stored render artifact ids and reports missing or ineligible documents before building a zip.
CustomerReceiptArtifact follows payment/refund ledger state and hides raw provider identifiers from public contracts.

Caregiver Matching And Payout

Evidence inspected:

source-refs/sanmopia-admin/application/models/Matching_model.php:44-124
source-refs/sanmopia-admin/application/models/Matching_model.php:144-177
source-refs/sanmopia-admin/application/models/Matching_model.php:233-284
source-refs/sanmopia-admin/application/models/Matching_model.php:724-862
source-refs/sanmopia-admin/application/models/Matching_model.php:866-907
source-refs/sanmopia-manager/application/helpers/salary_helper.php:8-227
source-refs/sanmopia-manager/application/models/Reservation_model.php:13-82
source-refs/sanmopia-manager/application/models/Reservation_model.php:352-410
source-refs/sanmopia-manager/application/models/Reservation_model.php:488-516
source-refs/sanmopia-admin/application/models/Reservation_manager_salary_model.php:21-52
source-refs/sanmopia-admin/application/models/Reservation_manager_salary_model.php:112-180
source-refs/sanmopia-admin/application/config/constants.php:272-274

Source behavior to preserve as facts:

Candidate ranking sums preference and personality scores, filters by active matching data, schedule check, pet allergy, branch, caregiver class, search string, random tie seed, and optional distance re-sort.
Transport-time path reads cached rows, can call public-transport provider for missing data, but final sort still uses score priority.
Candidate detail modal mixes reservation, caregiver, displayed score, preferences, distance, and transport data at click time.
Caregiver pay list uses reservation status buckets, then recalculates salary on every read from current reservation, role, assistant slot, add-ons, weekend/holiday options, service-balance override, voucher add-ons, custom pay, and tax choice.
Tax/memo persistence stores only reservation, caregiver, tax type, memo, and update date; missing rows default tax to four-insurance and memo to blank.
Main and assistant payout acknowledgement update different payment rows/flags, while assistant reads depend on source SORT and shared payment rows.

Modern migration requirement:

CaregiverCandidateSnapshot freezes score components, eligibility filters, exclusion reasons, branch scope, grade, distance, transport evidence, tie seed, and policy version before display or final assignment.
CaregiverTravelEvidence records provider result, fallback reason, distance, duration, freshness, and score-vs-travel priority. It is not the assignment decision.
CaregiverAssignmentDecision copies selected snapshot evidence and records actor, reason, branch scope, override, replacement link, and impacted contract or payout facts.
CareTeamCompensationSlot keys payout input by assignment key, role, handoff order, grade snapshot, service days, attendance facts, and rate rule.
CaregiverPayoutPolicyProfile owns tax election, four-insurance/normal-income handling, voucher add-ons, Saturday/holiday additions, custom service balance, primary custom pay, and assistant custom pay.
Backend implementation now anchors this in domain/pricing_settlement/features/caregiver_compensation/caregiver_payout_policy_profile.py and exposes CaregiverPayoutPolicyDecisionSnapshot through application and TS/schema contracts. Slot identity is assignment_key + role + handoff_order, so assistant handoff slots cannot collide on reservation/caregiver id alone.
CaregiverPayoutInstruction and CaregiverPayoutAcknowledgement replace read-time salary recomputation and source row mutation with frozen amount, tax, memo, destination, branch deposit, caregiver receipt, exception, repair, actor, and idempotency state.

Checklist Merge Notes

Use this page to refine existing checklist rows instead of adding duplicate rows. Existing anchors already cover these areas:

reservation_operations / ReservationStateTransitionCatalog
pricing_settlement / customer_payment_instruction
pricing_settlement / payment_refund
pricing_settlement / payment_change_adjustment
pricing_settlement / settlement_statement
pricing_settlement / settlement_data_room
document_reporting / printable_template_version_manifest
document_reporting / printable_document
caregiver_assignment / caregiver_candidate_ordering_policy
caregiver_assignment / assignment_decision_evidence
pricing_settlement / caregiver_compensation
pricing_settlement / caregiver_payout_statement

When implementing, update those rows with the modern names above and keep source ids, source labels, and source tables as evidence-only compatibility inputs.