Company-channel Booking Excel header parse failure

Metadata

Date: 2026-08-11
Status: Parser 2.1.0 compatibility implemented locally and verified; deployment pending
Scope: company-channel Booking-source parser 2.1.0, exact supplied Lian Tai/QBD July and August workbooks, wrong-input controls and existing one-file/full-replacement source lifecycle
Confidence: Fact for all supplied workbooks, synthetic regressions and parser/coordinator behavior; the original rejected request did not durably record its selected filename
Source: spreadsheet metadata/header-only renders, parser/upload/source-lifecycle inspection, exact-parser replay, focused/full tests and read-only PostgreSQL snapshot
Last verified: 2026-08-11 local workspace
Stale trigger: Booking Excel header matching, source-upload persistence or accepted source batch changes

Observed state

The deployed ARR service on public port 8765 remained healthy and protected authenticated APIs normally.
A read-only booking_test snapshot found no review draft, Booking Excel artifact or source batch created after 2026-08-03. Accepted batch 7, july-test.xlsx, remains current with 72 source rows and 72 distinct Group Codes.
ProgramBookingSourceCoordinator.submit parses the workbook before uploading it to object storage or creating a review draft. A header rejection therefore leaves no durable upload identity and cannot replace the current source.

Deterministic reproduction

The exact production function booking_ingestion.excel.parse_excel_bytes was run against four recently modified workbooks without changing them. Each returned:

BOOKING_EXCEL_HEADERS_MISSING — Excel 中未找到同时包含 Tour Code 和โรงแรม的工作表

8.4 (1).xlsx and 各渠道情况-2026年08月-更新至8.5.xlsx contain report-output columns such as BLOCK_CODE and RATE_CODE, not the Booking-source columns. If either was selected, rejection is correct because it is the wrong input type.
The Lian Tai source sheet has Tour Code / 主团号 and วางข้อมูลที่นี่ / 酒店明细.
The QBD source sheet has Tour Code / 主团号 and Raw Hotel Detail / วางข้อมูลที่นี่ / 酒店明细.

The parser normalizes punctuation and whitespace, then requires the entire normalized cell to equal one allowlisted alias. Its Tour Code aliases are TOURCODE, GROUPCODE, GOURPCODE, 团号 and 团队代码; the hotel alias is only the exact Thai โรงแรม. The bilingual cells normalize to concatenated text and match neither set.

An in-memory-only copy of each raw workbook was then given exact Tour Code and โรงแรม headers, with every other cell unchanged:

Lian Tai parsed successfully: 67 source rows, 100 extracted items and 16 pending review items.
QBD parsed successfully: 129 source rows, 252 extracted items and 245 pending review items.

Changing only the hotel header was insufficient because the bilingual Tour Code header also fails exact matching. These results isolate a parser/template compatibility gap rather than corrupt XLSX bytes, database failure or company-report publication failure.

Exact supplied-template compatibility experiment

The user explicitly confirmed that both supplied formats must be accepted. Their exact operational header cells are:

Lian Tai วางข้อมูล(BOOKING AUG.26): A2 = Tour Code / 主团号, D2 = วางข้อมูลที่นี่ / 酒店明细.
QBD 2026年8月｜AUGUST_26: C3 = Tour Code / 主团号, E3 = Raw Hotel Detail / วางข้อมูลที่นี่ / 酒店明细.

A process-memory-only experiment retained exact whole-cell matching and added only the three corresponding normalized aliases: TOURCODE主团号, วางข้อมูลที่นี่酒店明细 and RAWHOTELDETAILวางข้อมูลที่นี่酒店明细.

The unchanged Lian Tai file parsed only its intended source sheet: 67 rows, 100 items and 16 pending.
The unchanged QBD 2026-08-06 file parsed only its intended source sheet: 104 rows, 218 items and 212 pending.
AUTO_CALC, dashboard, summary, guide and daily-usage sheets were not recognized as data sheets.
8.4 (1).xlsx and 各渠道情况-2026年08月-更新至8.5.xlsx remained rejected with BOOKING_EXCEL_HEADERS_MISSING under the same experiment.
The focused current parser/coordinator baseline passed 14/14 tests.

This establishes that broad substring or fuzzy matching is unnecessary. Readable raw alias labels normalized into an exact allowlist are sufficient and preserve the wrong-report-input boundary.

Local implementation and verification

booking_ingestion.excel now reports parser version 2.1.0 and keeps readable raw labels for all approved legacy and bilingual header forms. It normalizes those labels into the pre-existing exact full-cell allowlist; no filename, month, worksheet-name, substring or fuzzy fallback was added.
Missing and duplicate header failures now describe Tour Code/主团号 and 酒店明细 neutrally, and the Web error catalog maps both stable codes into Chinese, English and Thai.
New synthetic parser tests prove both Lian Tai and QBD bilingual forms work at their real offset rows, unrelated AUTO_CALC sheets are ignored, similar-but-longer labels fail, and duplicate recognized labels fail closed. Coordinator tests prove a valid bilingual upload reaches private storage/draft creation while an unrecognized bilingual label reaches neither storage nor draft persistence.
The unchanged supplied files replay under parser 2.1.0 as follows: Lian Tai July 79/111/16, Lian Tai August 67/100/16, QBD July 235/447/432 and QBD August 104/218/212 for rows/extracted items/pending items. The two wrong report-output workbooks remain BOOKING_EXCEL_HEADERS_MISSING. Focused tests and full test discovery pass.

Impact and repair boundary

The failed request stopped before object-store registration and draft persistence, so no Booking source, Finance fact, company report or downstream event changed. The current accepted batch remains available.

The implemented Booking parser 2.1.0 behavior normalizes the three readable full-header labels into the existing exact allowlist, retains all current aliases, adds synthetic Lian Tai/QBD plus wrong-input and ambiguity regressions, and updates neutral error copy/current-contract documentation. The existing rule-set hash already includes aliases and version, and draft/run/parse lineage stores both, so no database migration is needed.

The upload endpoint and UI accept one workbook, and activation switches the singleton full Booking source. Supporting both header formats therefore does not mean that two separate uploads append or remain active together; multi-file merge would be a separate product change. The high QBD pending count also remains an operational review workload after header acceptance. No workbook, database, object-store object or runtime process was changed during implementation; deployment and any real upload/review/activation remain separate authorized actions.

7.1 KiB Raw Blame History Unescape Escape