40 lines
3.0 KiB
Markdown
40 lines
3.0 KiB
Markdown
# ADR-001: Automatic Monthly Trigger And TOTAL PRICE Formula
|
||
|
||
- Status: Implemented
|
||
- Date: 2026-07-29
|
||
- Source: User correction in the current session
|
||
|
||
## Context
|
||
|
||
Earlier discussion incorrectly treated monthly-report generation as a separate user action and described year, month, or cutoff date as user-submitted values. An earlier report specification also treated generated price cells as static values.
|
||
|
||
## Decision
|
||
|
||
1. The user's workflow begins and ends with uploading the XML.
|
||
2. ARR's frozen processor produces structured data for independent validation and database persistence; the production path has no Agent/MCP dependency.
|
||
3. Only after that structured result is successfully committed does the business system emit `arr.daily_version_committed`; a dedicated worker process consumes it and runs the monthly-report program.
|
||
4. `report_year`, `report_month`, `as_of_date`, or equivalent values may remain as internal execution and audit fields, but the backend must derive them. The worker uses committed retained `ARRIVAL` facts to select the affected month, and the greatest `ARRIVAL` actually included in the snapshot is the report's `as_of_date`/“更新至”. The XML filename and wall clock are never authorities for this value.
|
||
5. The report keeps the `TOTAL PRICE` dimension/field. Each XLSX data-row cell must contain a formula with the business meaning:
|
||
|
||
`TOTAL PRICE = REAL PRICE × NIGHTS × NO_OF_ROOMS`
|
||
|
||
With the current 19-column layout, this is equivalent to `=R2*C2*G2` for row 2 and must fill relatively for later rows.
|
||
6. The monthly page automatically discovers newly published versions. A user must not need a separate refresh action
|
||
after the worker finishes.
|
||
|
||
## Consequences
|
||
|
||
- A manual month/as-of form or endpoint is not the primary product flow and must not be presented as a required user step.
|
||
- The monthly processor may still accept internally supplied month/cutoff arguments through a controlled recovery CLI/API, but the primary page exposes none of them.
|
||
- The dedicated worker leases outbox rows, retries transient publication failures, dead-letters exhausted events, and acknowledges success only after both registered artifacts are active/downloadable.
|
||
- Durable `reporting` metadata records the snapshot identity, Finance daily-version lineage, channel manifest and local artifact identities without duplicating monthly business rows.
|
||
- The implemented workbook writes and reopens one exact row-relative `TOTAL PRICE` formula per data row.
|
||
- The portal uses a visibility-aware, non-overlapping list poll while the monthly tab is open and reloads immediately
|
||
when the tab becomes active again. A transient background error keeps the last good list and retries automatically.
|
||
|
||
## Supersedes
|
||
|
||
- Any conversation or planning note that says the user submits the report year, month, or cutoff date.
|
||
- The intermediate correction that said the user clicks a monthly-report button while the backend derives those values.
|
||
- Any report-output rule requiring `TOTAL PRICE` data cells to be static values or requiring a zero-formula workbook.
|