wyndham-ARR/.project-docs/10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md

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.