83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# Structured Result Contract
|
|
|
|
## Purpose
|
|
|
|
`structured-result.json` version `3.0` is the daily fact payload consumed by the trusted ARR adapter. It contains every XML source reservation, including filtered, duplicate, invalid, and unmatched rows.
|
|
|
|
`result.json` is the Agent/front-end run result. Do not add database records to it. Do not reconstruct database rows from the XLSX.
|
|
|
|
## Transport boundary
|
|
|
|
- `fetch_oss_file` and its OSS credentials belong to the Agent runtime, not this Skill.
|
|
- The Agent passes the fetched local XML path into the processor.
|
|
- ARR already knows the job/source-file identity from the upload context and binds that identity to this payload after comparing the XML hash.
|
|
- Structured artifact objects contain no local absolute path, OSS key, signed URL, AccessKey, or database credential.
|
|
- Agent-local paths are ephemeral orchestration data and must not be persisted as business facts.
|
|
|
|
## Batch fields
|
|
|
|
The payload includes:
|
|
|
|
- `business_date`
|
|
- `processor_version`
|
|
- `rule_set_sha256`
|
|
- `result_schema_version`
|
|
- `source_rows`
|
|
- `removed_by_rate_code`
|
|
- `removed_as_duplicates`
|
|
- `output_rows`
|
|
- five-outcome reconciliation
|
|
- channel counts
|
|
- path-free XML/daily/result/exception artifact metadata
|
|
- every XML source record in original order
|
|
- structured errors
|
|
|
|
`rule_set_sha256` hashes only resources that determine daily processing: Skill instructions, processor, independent validator, daily contracts/Schemas, price table, and daily template.
|
|
|
|
The structured file does not hash itself, avoiding self-hash recursion.
|
|
|
|
## Outcomes and lineage
|
|
|
|
Allowed outcomes:
|
|
|
|
- `retained`
|
|
- `excluded_rate_code`
|
|
- `duplicate`
|
|
- `validation_failed`
|
|
- `price_unmatched`
|
|
|
|
Duplicates point to an earlier `source_sequence`. `decision_codes` explain deterministic choices.
|
|
|
|
For direct XML:
|
|
|
|
- `source_sequence` is continuous and one-based;
|
|
- `source_location = reservation[N]`;
|
|
- `source_worksheet = null`;
|
|
- `source_row_no = null`.
|
|
|
|
## Finance/booking semantics
|
|
|
|
- `effective_rate_amount` comes from XML/daily `EFFECTIVE_RATE_AMOUNT`.
|
|
- `real_price` comes from the approved price rule.
|
|
- `total_price = real_price * no_of_rooms * nights`.
|
|
- `nights` may be zero; it may not be negative for retained rows.
|
|
- `kb_amount = no_of_rooms * 100` only when `channel_key = DY-AI-Easy-KB`.
|
|
- `room_category_label` remains the Opera actual room category.
|
|
- `group_code_key` comes only from normalized `RES_COMMENT`.
|
|
- Non-empty Group Codes begin with `booking_source_match_status = not_checked`; empty values use `missing_group_code`.
|
|
|
|
ARR performs the later exact booking lookup:
|
|
|
|
```text
|
|
structured group_code_key
|
|
= booking.booking_source_rows.group_code_key
|
|
```
|
|
|
|
It may then expose `booking.booking_source_rows.hotel_raw` as the original booking `type_of_room` text. It must not overwrite `room_category_label`.
|
|
|
|
## Activation boundary
|
|
|
|
`activation_eligible: true` means only that the deterministic file pipeline passed. It does not mean database commit succeeded.
|
|
|
|
ARR must revalidate the Schema and hashes, write file/version/record/channel/lookup rows in one transaction, and switch the current daily version last. A rerun of the same business date creates a new immutable version; only the successful committed version becomes current.
|