wyndham-ARR/.project-docs/50-evidence/topics/2026-08-03-company-source-report-traceability.md

Booking Excel to company-report traceability

Scope

The Booking Excel upload page could tell the operator that an identical workbook was already active, but the company-report history and job detail did not show which source was associated with a generated result. This change adds source identity without exposing workbook rows, guest data or full artifact hashes.

Diagnosis

• booking_ingestion/excel_review_postgres.py deduplicates an identical activated artifact and raises BOOKING_EXCEL_SOURCE_ALREADY_ACTIVATED with 这份 Excel 已经启用，无需重复提取.
• /api/company-reports/source already returned a privacy-safe source summary, but the frontend used it only as a readiness boolean.
• POST /api/company-reports/jobs accepted only month and period, and persisted no source metadata in the durable job state. The frontend API helper also discarded error codes, preventing an informational duplicate-upload branch.

Implemented behavior

• The server captures the current active source when a report job is submitted; the browser cannot choose or spoof the source identity.
• New job records expose only source batch id/type, safe filename, activation time, disposition and summary counts.
• The company page shows the current active workbook and summary counts.
• The server still captures the source Excel summary at submission, but the end-user job detail/history no longer renders that provenance. The upload/review panel remains the place where the active Excel source is managed.
• Re-uploading the same active workbook clears the selected file, refreshes the current-source and report-history views, and shows an informational message. It does not create a second extraction or automatically generate a report.
• Report generation remains an explicit month/period action. Upload controls stay blocked while a report job is active, so the submission-time source remains the trace shown for that job.

The later UI simplification intentionally removes only the result/history display; it does not remove the server-side source metadata or change the report's database-backed input behavior.

Verification

• ./.venv/bin/python -m unittest tests.test_arr_web_company_reports tests.test_arr_web: 28 tests passed.
• ./.venv/bin/python -m unittest discover -s tests -p 'test_arr_web*.py': 69 tests passed.
• ./.venv/bin/python -m unittest discover -s tests: 360 tests passed, 10 optional skips.
• node --check arr_web/static/app.js and Python compilation passed.
• git diff --check passed.

The available in-app browser session landed on the login page without an authenticated session. No login, upload, activation, report generation, service restart or business-data mutation was attempted; authenticated browser acceptance remains the deployment follow-up.