63 lines
3.4 KiB
Markdown
63 lines
3.4 KiB
Markdown
# Error Contract
|
|
|
|
## Atomic invocation
|
|
|
|
Treat one XML invocation as an atomic file-processing unit.
|
|
|
|
On any input, XML, price, routing, write, structured-completeness, or independent-validation error that is not a pure `PRICE_UNMATCHED` review result:
|
|
|
|
- do not return a formal daily workbook;
|
|
- delete candidate daily/structured files from the failed attempt;
|
|
- keep the source XML unchanged;
|
|
- write `异常清单.xlsx`;
|
|
- write failed `result.json` when its requested path is valid;
|
|
- write failed `structured-result.json` when its requested path is valid;
|
|
- set `activation_eligible: false`.
|
|
|
|
The failed structured payload still preserves every parsed reservation and its final outcome. It never references a daily artifact.
|
|
|
|
## Exit codes
|
|
|
|
| Exit | Meaning |
|
|
|---:|---|
|
|
| `0` | Processing and independent validation succeeded |
|
|
| `2` | Business-data failure |
|
|
| `3` | Invocation/input-contract failure |
|
|
| `4` | Unexpected dependency/internal failure |
|
|
|
|
`review_required` is a successful technical exit (`0`), but not a successful business commit: it writes only the two JSON artifacts and has no daily/exception workbook. It is allowed only when `PRICE_UNMATCHED` is the complete actionable error set.
|
|
|
|
## Exception workbook
|
|
|
|
Columns:
|
|
|
|
`ERROR_CODE`, `STAGE`, `SOURCE_LOCATION`, `COMPANY_NAME`, `RATE_CODE`, `EFFECTIVE_RATE_AMOUNT`, `CONFIRMATION_NO`, `MESSAGE`.
|
|
|
|
Write one row per independently actionable error. Leave unavailable fields blank.
|
|
|
|
## Stable error families
|
|
|
|
- `INPUT_*`: path, extension, output isolation, unsafe declaration, or invocation error.
|
|
- `XML_*`: parse/root/structure/date/required-field/value error. Zero nights are valid; negative nights use `XML_NEGATIVE_NIGHTS`.
|
|
- `PRICE_*`: price table, ambiguity, duplicate normalized key, or unmatched candidate.
|
|
- `ROUTING_*`: ambiguous or unusable deterministic `channel_key`.
|
|
- `OUTPUT_*`: missing/malformed output, wrong header/type/value/order/hash/filename, formula, duplicate, or independent replay mismatch.
|
|
- `STRUCTURED_*` / `OUTPUT_STRUCTURED_*`: invalid path-free artifact, outcome reconciliation, derived key, channel fact, or record payload.
|
|
- `INTERNAL_ERROR`: concise unexpected failure without secrets.
|
|
|
|
## Success/failure invariants
|
|
|
|
- `status` is `success`, `review_required`, or `failed`.
|
|
- Output references in `result.json` are basenames, never paths.
|
|
- Success lists daily and structured files, lists no exception file, and has no errors.
|
|
- Failure lists no daily file, lists an exception file, and has at least one error.
|
|
- Review lists no daily or exception file, has only `PRICE_UNMATCHED` errors, candidate/review issue counts, and `activation_eligible: false`.
|
|
- `metrics.channels` is a deterministic array of `{ "worksheet": string, "rows": integer }`.
|
|
- Structured success requires exact artifact metadata, balanced six-outcome counts, no `candidate`/`validation_failed`/`price_unmatched`, and `activation_eligible: true`.
|
|
- Structured failure has `output_rows = 0`, no channel metrics, no daily artifact, a non-empty error array, and `activation_eligible: false`.
|
|
- Never place guest details in the public `message`.
|
|
|
|
## Database boundary
|
|
|
|
This Skill never executes database DDL or DML. ARR may record a `review_required` receipt after its JSON/schema validation, but it may start a Finance transaction only after final success, independent re-hashing and replay. ARR activates a new same-day version only as the last step of that transaction; any final failure must roll back and leave the previous current version unchanged.
|