wyndham-ARR/company_reports/README.md

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.
• A Finance fact with no Group Code remains as its own output row and has blank RES_COMMENT and Booking Room; it is never merged with another no-code fact. A present Group Code keeps its normal stay-segment row and RES_COMMENT, but Booking Room is blank when no current accepted Booking room can be resolved.
• 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 matched 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

python3 -m pip install -r requirements-company-reports.txt

export COMPANY_REPORT_DATABASE_URL='postgresql://USER:PASSWORD@HOST:PORT/booking_test'

python3 -m company_reports generate \
  --month 2026-07 \
  --as-of 2026-07-10

The workbook builder uses Python/openpyxl. The XLSX and result.json are uploaded to the existing private OSS; .web-jobs remains a local persistent queue-state directory. Use the existing ARR_OBJECT_PREFIX, ARR_OSS_REGION, ARR_OSS_BUCKET, optional ARR_OSS_ENDPOINT, and OSS credential settings; no Node.js or private package setting is required. 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

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.