feat: prepare ARR for controlled public deployment

company_reports/README.md

@@ -0,0 +1,59 @@
+# Company Reports Downstream Processor
+
+`company_reports` is an ordinary deterministic downstream program. It reads ARR-validated Finance facts and current accepted booking room items, then builds one workbook per company. It does not read XML, call an Agent, or recalculate `REAL PRICE`/`TOTAL PRICE`.
+
+## Data contract
+
+- Finance source: `finance.v_active_daily_facts`, selected by `DEPARTURE` from month start through the requested as-of date.
+- Booking source: `booking.v_current_room_items` and `booking.v_group_room_item_summary`, matched by normalized full Group Code only.
+- Dates/nights come from Finance. Booking data only supplies room type and booked quantity.
+- `Total Booking Price` uses each Finance daily `TOTAL PRICE`; it is not recomputed from booking unit price and is not collapsed across all rows sharing a Group Code.
+- The program splits output by each Finance `(Group Code, ARRIVAL, DEPARTURE)` segment.
+- Report rows/versions are not persisted in PostgreSQL; a deterministic generation identity and source pins protect generation consistency.
+
+Supported companies: `LianTai`, `QBD`, `DY-AI-Easy-KB`, `FengRun`, `HanaTour`.
+
+## Run
+
+```bash
+python3 -m pip install -r requirements-company-reports.txt
+
+export COMPANY_REPORT_DATABASE_URL='postgresql://USER:PASSWORD@HOST:PORT/booking_test'
+export COMPANY_REPORT_NODE_BINARY='/absolute/path/to/node'
+export COMPANY_REPORT_ARTIFACT_TOOL_MODULE='/absolute/path/to/artifact_tool.mjs'
+
+python3 -m company_reports generate \
+  --month 2026-07 \
+  --as-of 2026-07-10
+```
+
+The DSN can fall back to `ARR_DATABASE_URL`; never place a real DSN in source, prompts, output JSON or browser code.
+
+Scheduling convention:
+
+- 11th: as-of 10th;
+- 21st: as-of 20th;
+- 1st of next month: as-of prior natural month end.
+
+## Workbook
+
+Each period sheet has seven columns:
+
+1. `ARRIVAL`
+2. `DEPARTURE`
+3. `NIGHTS`
+4. `BLOCK_CODE`
+5. `RES_COMMENT`
+6. `Booking Room`
+7. `Total Booking Price`
+
+The builder creates a new formula-free workbook, reopens and validates it, then atomically publishes the file. Same-room-type/multiple-price cases are surfaced as a review warning rather than silently merged.
+
+## Tests
+
+```bash
+PYTHONPYCACHEPREFIX=/tmp/company_reports_pycache \
+python3 -m unittest discover -s tests -p 'test_company_reports*.py' -v
+```
+
+All test identifiers are synthetic. The current remote acceptance fixture returns one QBD row, Booking Room `【DBL】1`, from the controlled `<ARR_DB_HOST>:5432/booking_test` database.