shiyuyun/wyndham-ARR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: prepare ARR for controlled public deployment

Browse Source
This commit is contained in:
Wyndham ARR
2026-07-29 16:38:05 +08:00
commit a701de9f0e
271 changed files with 48472 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
.project-docs/20-architecture/data-flow.md Normal file
View File

@@ -0,0 +1,24 @@
# Data Flow
## Primary Flows
| Flow | Source | Destination | Notes |
|---|---|---|---|
| XML ingestion | User upload | Agent processing | Upload is the user's only required action for this flow. |
| Structured result commit | Agent output | PostgreSQL Finance facts | Independent validation/replay must succeed before commit. |
| Automatic monthly trigger | Successful database commit | Monthly-report worker/program | Month and cutoff values are derived internally, not supplied by the user. |
| Monthly workbook build | Committed Finance facts | XLSX artifact | `TOTAL PRICE` cells use `REAL PRICE × NIGHTS × NO_OF_ROOMS` formulas. |
## State Ownership
- PostgreSQL owns accepted/current Finance facts and processing state.
- Generated XLSX files are artifacts derived from a pinned database snapshot; they are not an alternative fact source.
## External Interfaces
- User-facing: XML upload, processing status, and controlled report download.
- Internal: Agent structured-result submission and automatic report-task dispatch after commit.
## Last Updated
2026-07-29

27
.project-docs/20-architecture/module-map.md Normal file
View File

@@ -0,0 +1,27 @@
# Module Map
## Source Layout
| Path | Responsibility | Owner Notes |
|---|---|---|
| `arr_web/` | Upload portal and business API | Manual monthly request code conflicts with ADR-001. |
| `arr_mcp/` | Direct Agent-result submission and ingestion boundary | Post-commit trigger should originate at or after this boundary, not before it. |
| `arr_ingestion/`, `arr_processing/` | Validate and persist structured processing results | Keep deterministic replay and transaction semantics. |
| `monthly_reports/` | Database-backed monthly workbook generation | Needs formula-cell output and automatic orchestration integration. |
| `database/` | Finance facts, views, guards and migrations | Database total remains useful for integrity checks. |
| `Dockerfile`, `compose.yaml` | Reproducible single-server Web/MCP runtime | Compose explicitly enables XML processing; source defaults remain fail-closed. |
| `deploy/` | Caddy TLS/auth boundary, production env template and operator runbook | Only Caddy publishes host ports; never commit the real production env file. |
| `tests/` | Regression and acceptance coverage | Add post-commit trigger and formula-cell assertions when implementation is authorized. |
## Dependency Direction
- Upload/Agent/ingestion writes validated facts; report modules depend on committed facts and must not call back into XML parsing.
- Public traffic enters through Caddy; Web and MCP stay on the internal Compose network and use separate browser/MCP authentication boundaries.
## Risky Or Sensitive Areas
- Commit-to-trigger atomicity/idempotency, monthly snapshot selection, XLSX formula preservation, and PII-safe result metadata.
## Last Updated
2026-07-29

33
.project-docs/20-architecture/system-overview.md Normal file
View File

@@ -0,0 +1,33 @@
# System Overview
## Current Architecture
The ARR system accepts an Opera XML upload, stores the private source artifact, invokes an Agent for deterministic processing, validates the returned structured result, and commits accepted Finance facts to PostgreSQL. Downstream analytics and report programs consume those committed facts. The accepted target flow automatically triggers monthly processing after the commit; the current manual monthly UI/API remains a known implementation gap.
## Main Components
| Component | Responsibility | Notes |
|---|---|---|
| `arr_web` | XML upload, job status, controlled downloads and business APIs | The existing manual monthly-generation request is not the accepted primary flow. |
| SuperAgent + deterministic processing skill | Convert XML to the approved structured result | Must not decide user-facing report parameters. |
| `arr_mcp` / ingestion service | Independently validate/replay and atomically commit accepted structured results | Automatic downstream trigger begins only after commit success. |
| PostgreSQL Finance facts | Authoritative current and retained daily facts | Source of truth for downstream reports. |
| `monthly_reports` | Generate monthly XLSX from committed database facts | Internal month/cutoff inputs are allowed; `TOTAL PRICE` must be an XLSX formula. |
| `channel_analytics` / `company_reports` | Additional read/report consumers | Must not change the monthly-report trigger contract. |
| Caddy + Compose deployment boundary | Terminate HTTPS, authenticate Web users, keep Web/MCP ports internal and start the explicit processing profile | MCP still performs its own bearer check and DNS-rebinding Host validation. |
## Important Boundaries
- XML processing and Finance fact validation happen before the monthly-report trigger.
- The user-facing upload workflow does not collect monthly report year, month, or cutoff date.
- Monthly processing reads validated database facts rather than repeating Agent business logic.
- Database `total_price` may support validation, but the exported `TOTAL PRICE` cell must remain a formula.
- Public deployment enables XML processing only through the explicit Compose command and requires `processing_ready=true`; it does not change local/application defaults.
## Related Decisions
- [ADR-001](../10-decisions/ADR-001-automatic-monthly-trigger-and-total-price-formula.md)
## Last Updated
2026-07-29