shiyuyun/Wyndham-RSVN-0918
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7fae427e33dd94a2ea996e0308b82a6264ae0c6b
Wyndham-RSVN-0918/docs/project/requirements/C03-v2-layer3-standard-contract-thin-integration-change-request-v1.md
T
鲨鱼辣椒 31849411a8
verify / booking-verify (push) Has been cancelled
Details
建立5178独立项目基线
2026-09-08 15:03:45 +08:00

18 KiB
Raw Blame History

C03-v2 / Layer 3 标准契约与 QBD 薄联调 Change Request v1

Supersession notice（2026-08-11）：本文继续作为旧 booking-layer3-contracts-v2-draft 技术试验与迁移来源保留；其中 Parser 多状态 contribution、独立 action signal/issue 及 MISSING / UNRESOLVED / AMBIGUOUS / CONFLICT 公共输出已被 ADR-008 和 M012-qbd-liantai-parser-output-contract-v1.md 取代，不得作为新 Parser 实现依据。

项 内容
状态 DRAFT — thin-integration only；不得视为 APPROVED
日期 2026-08-10
唯一长期契约名称 booking-layer3-contracts-v2
当前工作版本 booking-layer3-contracts-v2-draft
目标 让程序 Parser、解析 Agent、Layer 3 合并器与下游 Agent 使用同一套材料事实语言
影响范围 Additive DTO / Static Fixtures / Contract Tests / Handoff Docs
明确不接入 真实 Agent、AgentBus、数据库、Context/Booking Agent、任务卡、PMS/Opera

1. 背景

当前仓库的 Layer 3 主契约仍围绕“Parser 发现少量可恢复字段后，按需调用字段 Recovery Agent”设计，核心输出是 RecoveryPatchSet 和旧 EffectiveFactView。用户最新确认的目标架构已经变为 message-level Parsing Agent：程序 Parser 完成 Current 附件确定性解析后，每封邮件都调用解析 Agent；Agent 理解 Current 正文、全部 History 正文和 Parser 已提取事实，并在 Parser 失败、不适用或歧义时承担受控的 Current 附件兜底。

该变化不能通过重命名旧 RecoveryPatchSet 完成。Parser 与 Agent 可以有不同的运行状态外壳，但必须向 Layer 3 合并器交付同一个目标、事实、证据、动作信号、关系与问题核心。

本 Change Request 只建立 booking-layer3-contracts-v2 的 DRAFT 技术骨架和静态薄联调证据，不修改旧 ADR 或 canonical docs，不接生产运行链路。

2. 目标

  1. 建立唯一公共 Layer3ContributionCoreV2，由 Parser 与解析 Agent 原样复用，禁止两套字段字典。
  2. 统一表达 message、Current attachment、producer run、target、group code、raw/normalized value、CURRENT/BEFORE/AFTER、材料动作信号、evidence、relationship、unresolved/ambiguity/conflict 与 provenance。
  3. 让 Parser 与 Agent 外壳分别表达自身运行状态，同时携带 contract、semantic catalog、parser、parser profile、agent profile 等版本。
  4. 建立 EffectiveFactViewV2 DRAFT：只汇总材料事实、材料动作信号、关系、冲突和 evidence，不产出最终业务事件或执行动作。
  5. 用静态 fixture 验证 QBD New、Update、Cancel、Allotment 与扩展矩阵的结构一致性、引用完整性、History 边界和 Parser 不可覆盖规则。
  6. 分别给 Parser 任务与解析 Agent 任务提供最小、明确的后续修改清单。

3. 非目标

  • 不修改 QBD Parser 的选行、日期、富文本、价格或动作业务规则。
  • 不修改解析 Agent Prompt、Skill 或 reference，不调用真实 SuperAgent。
  • 不冻结最终 JSON Schema，不把 DRAFT 类型或 fixture 标记为 APPROVED。
  • 不接 AgentBus worker、数据库 artifact、Context Agent、Booking Agent、TaskCard、库存、PMS 或 Opera。
  • 不在 Layer 3 判断最终事件、任务卡数量、FIT/GROUP、GRPA1、Rate Code、库存或 PMS 动作。
  • 普通 New/Update/Cancel 只使用 QBD_CORE_CONTRACT_HANDOFF_READY 已确认的业务语义；Cancel 脱敏正向 fixture 不得冒充真实 Current 有色 Cancel 样本验收。
  • 不原地改写 ADR-001、ADR-003、ADR-004 或 .project-docs canonical architecture；正式 supersede 必须另行评审。

4. 用户与主要场景

4.1 直接使用者

  • 程序 Parser：交付 Current 附件中的确定性观察。
  • 解析 Agent：交付 Current 正文理解、Parser facts 引用、必要时的 Current 附件兜底结果和 History 辅助证据。
  • Layer 3 合并器：不做业务事件判断，只进行引用校验、相同贡献归并、冲突并列和有效视图投影。
  • Context/Booking Agent：未来只消费 EffectiveFactViewV2 中的材料事实，不再推断 Parser/Agent 私有结构。

4.2 QBD 最低验收矩阵

编号 场景 本 DRAFT 状态
QBD-01 普通 New Booking Confirmed business slice；契约仍为DRAFT
QBD-02 普通 Update Booking Confirmed business slice；契约仍为DRAFT
QBD-03 普通 Cancel/CXL 规则已确认；正向fixture因缺真实Current正样本保持DRAFT
QBD-04 Allotment actual New 与 source→actual Confirmed slice
QBD-05 Allotment 附件内普通 Update Confirmed slice
QBD-06 同一 Current Excel 有逐行 New/Update/Cancel Confirmed business rule；fixture保持DRAFT
QBD-07 正文仅邮件级 UPDATE/AMEND 概括 Confirmed business rule；不得覆盖附件逐行动作
QBD-08 正文与附件对同一目标真正冲突 Conflict rule confirmed；fixture保持DRAFT并必须并列复核
QBD-09 History 辅助理解但不触发新业务 Contract confirmed
QBD-10 Parser 失败/歧义时 Current 附件受控兜底 Contract与QBD职责已确认；真实Agent尚未实现

5. 概念门禁与业务所有权

5.1 Layer 3 可以表达

  • 材料中出现的目标及角色；
  • 材料中的来源事实、raw value、normalized value 与字段状态；
  • CURRENT、BEFORE、AFTER 等材料状态；
  • 正文或附件中出现的动作信号，以及 signal 的 message/target/relationship scope；
  • source→actual 等材料关系；
  • unresolved、ambiguity、conflict；
  • 可定位 evidence 和 Parser/Agent/merger provenance。

5.2 Layer 3 禁止表达

  • 最终 New/Update/Cancel 业务事件判定；
  • 任务卡数量、部门、执行顺序或 TaskCard payload；
  • FIT/GROUP、GRPA1、canonical Rate Code、库存结论；
  • PMS/Opera 操作或执行成功状态。

ActionSignalV2 是材料中的文字/逐行信号，不是最终业务事件。SOURCE_PRICE 是材料原值，不是 Rate Code 或最终房价解释。

5.3 普通 New/Update/Cancel 的 DRAFT 门禁

解析 Agent planning 已在 readiness 报告之后继续推进，并输出 QBD_CORE_CONTRACT_HANDOFF_READY：普通 New、Update、Cancel 的七段业务交接已经完成。因此本次 fixture 可以使用已确认的QBD核心语义，并继续验证：

  • 三类材料信号可以进入同一核心；
  • 目标/evidence/provenance 引用完整；
  • 未确认字段保持 UNRESOLVED；
  • Cancel 必须由 Current 明确 CANCEL、CXL 或取消语义支撑。

New与Update已有真实Current材料支撑，可标记为业务确认切片；Cancel尚无“本次有色Current Cancel”真实正样本，正向fixture必须标记为synthetic DRAFT。全部fixture仍使用DRAFT contract version，不得自行补充最终事件、任务数量、字段继承或下游执行规则。

6. DRAFT 契约结构

ParserResultEnvelopeV2                  ParsingAgentResultEnvelopeV2
├── fixture_status                      ├── fixture_status
├── parser_result_id                    ├── agent_result_id
├── message_ref                         ├── message_ref
├── attachment_ref                      ├── run_ref
├── run_ref                             ├── run_status
├── attachment_parse_status             ├── versions
├── versions                            └── contribution_core
└── contribution_core                              │
               └──────────────┬────────────────────┘
                              ▼
                  Layer3ContributionCoreV2
                  ├── targets
                  ├── facts
                  ├── action_signals
                  ├── relationships
                  ├── issues
                  └── evidence
                              │
                              ▼
                    EffectiveFactViewV2
                    ├── targets
                    ├── effective_facts
                    ├── action_signals
                    ├── relationships
                    ├── issues/conflicts
                    ├── evidence
                    └── source_result_refs

6.1 Identity

  • MessageRefV2：source_message_id + source_revision。
  • AttachmentRefV2：Current attachment 的稳定 logical ID、content hash 和 media type；文件名只允许作为 Current attachment 描述字段，不作为业务触发依据。
  • ProducerRunRefV2：run ID、producer type、attempt 与 started-at；不能用当前时间参与业务 target/fact/evidence 稳定 ID。
  • TargetV2：稳定 target ID、角色、可选 group code、证据引用与 provenance。

6.2 公共字段语言

SemanticRoleV2 只定义中立材料角色。本 DRAFT 首批包括：

  • GROUP_CODE
  • STAY_ARRIVAL、STAY_DEPARTURE、NIGHTS
  • SOURCE_ROOM_TYPE、ROOM_QUANTITY、SOURCE_PRICE
  • DETAIL_RAW

新增业务角色必须通过同一 semantic catalog 演进；Parser 与 Agent 不得各自新增同义字段。动作不占用fact role，只能使用独立 ActionSignalV2，避免同一材料动作出现两种长期表达。

6.3 Fact

每条 FactContributionV2 至少包含：

  • fact/contribution ID 与 target ID；
  • semantic role、稳定 fact_path、value type、status；
  • CURRENT/BEFORE/AFTER/MIXED material state；
  • raw value 与 normalized value；
  • evidence refs；
  • producer provenance。

MISSING、UNRESOLVED、AMBIGUOUS、CONFLICT 必须显式表达，不得用空字符串或省略对象代替。 fact_path 用于区分同一 target 下多个 stay segment、room item 或备注槽位，不能把两个合法明细误判为同字段冲突。

6.4 Action signal

动作使用独立 ActionSignalV2，不能塞进最终 event 字段。signal 必须声明：

  • MESSAGE、TARGET 或 RELATIONSHIP scope；
  • raw signal 与可选 normalized signal；
  • 可选 target ref；
  • evidence 与 provenance。

邮件级 UPDATE/AMEND 只能表达邮件总体语气，不能覆盖 Current Excel 的逐行 New/Update/Cancel signals。

6.5 Relationship

RelationshipV2 用稳定的 from_target_id 和 to_target_id 表达材料关系。本 DRAFT 已确认 ALLOTMENT_SOURCE_TO_ACTUAL；关系端点必须存在，且 relation evidence 不能仅来自 History。

6.6 Evidence

Evidence 使用顶层 registry 和 ID 引用，不在每个事实中复制原材料。允许的 scope：

  • CURRENT_BODY
  • CURRENT_ATTACHMENT
  • HISTORY_BODY

Locator 为结构化字段，可表达正文字符 span、Sheet/row/cell/rich-text span 与 formatting signature。禁止把 History attachment、History 文件名、时间、hash、附件内容或历史解析结果放入 v2 输入/输出。

6.7 Provenance 与版本

每个 target/fact/signal/relationship/issue 都声明 producer type、producer run ID、source result ID 与 mode。mode 至少区分：

  • PARSER_EXTRACTION
  • CURRENT_BODY_INTERPRETATION
  • CURRENT_ATTACHMENT_FALLBACK
  • LAYER3_DETERMINISTIC_MERGE

顶层 VersionBundleV2 显式携带 contract、semantic catalog、evidence schema、ID algorithm、parser、parser profile、parser rule bundle 与 agent profile 版本；未运行的一侧使用显式 sentinel，不用空值让下游猜测。

7. 合并不变量

  1. Parser 的确定性 artifact 不可变；合并器不能修改或删除 Parser contribution。
  2. Parser 与 Agent 对同一 target + semantic role + material state 给出不同 resolved value 时，两者并列保留，并形成 CONFLICT issue；有效槽位不得静默选择 Agent 值。
  3. 相同值可以合并为一个 effective fact，但必须保留所有 source contribution refs 与 evidence refs。
  4. Agent 的 Current body 解释可以新增 source target、动作信号和 relationship；不能通过邮件级概括覆盖附件逐行 signal。
  5. History evidence 只能辅助解释 Current；History-only target/fact/action/relationship 必须被拒绝。
  6. Current 附件 fallback 在 Parser PARTIAL 时只覆盖获准的未解析槽位，在 FAILED、NOT_APPLICABLE 或 AMBIGUOUS 时只读取本地系统显式授权的 Current 附件材料；没有可用附件材料时只保留正文事实和附件问题。全部 fallback 贡献必须用 CURRENT_ATTACHMENT_FALLBACK provenance 标记。
  7. EffectiveFactViewV2 仍属于 Layer 3，不得新增最终 event、FIT/GROUP、Rate Code、inventory 或 execution 字段。

8. QBD Allotment 确认切片

真实样本必须由 fixture 表达以下已确认事实，不再解释其业务含义：

  • source target 的 group_code = LTQ260812，证据来自 Current 正文；
  • source 动作信号 DEDUCT，证据来自 Current 正文；
  • Current workbook rows 135–141 是 7 个独立 actual New targets；
  • 建立 7 条 ALLOTMENT_SOURCE_TO_ACTUAL relationship；
  • rows 118、121 是两个独立普通 Update targets，不关联 source；
  • K 列 2300 THB 只作为 DETAIL_RAW 原样保留，不产出 SOURCE_PRICE；
  • 划线内容支持 BEFORE，未划线内容支持 AFTER；
  • 只有划线且没有有效 AFTER 时为 unresolved/review，不推断 Cancel；
  • Cancel 只能由 Current 明确 CANCEL、CXL 或取消语义支持。

9. Fixture 与测试设计

每个 scenario fixture 同时包含：

  1. 零到多个按 Current attachment 分列的 Parser 输出适配结果；
  2. 解析 Agent 预期输出；
  3. Layer 3 合并后的 EffectiveFactViewV2；
  4. scenario 级 fixture_status 与说明。

测试必须覆盖：

  • Parser/Agent 都反序列化到同一个 Layer3ContributionCoreV2；
  • New、Update、Cancel、Allotment 的公共契约一致性；
  • QBD-01 至 QBD-10 场景标签均被 fixture 覆盖；
  • target/evidence/result/contribution/relationship 引用完整；
  • History-only 不能触发 target、fact、action 或 relationship；
  • Current attachment fallback 的状态与 provenance 门禁；
  • Parser 与 Agent 真冲突时 Parser 值未被 Agent 静默覆盖；
  • Allotment 的 7 actual、7 relationship、2 independent Update 和 K 列 raw detail；
  • fixture 中不存在 Layer 4/5/6 禁止字段。

测试不启动 Spring，不调用外部服务，不访问数据库，不打开真实 XLSX/EML。

10. 兼容与正式 supersede 建议

本 DRAFT 是 additive 新版本，不修改 booking-contracts-v1 的既有含义。后续正式评审应：

  1. 新建 ADR，supersede ADR-001 的 field-only 调用条件、Recovery input 和 PatchSet/old EffectiveView 总模型，同时迁移 Parser 不可变、稳定 identity/evidence、本地验证等安全原则。
  2. 部分 supersede ADR-004 的“只有 MANUAL_EML/有 task 才调用”产品语义，保留 AgentBus callback 不同步等待、必须 worker 化的运行安全要求。
  3. 将 ADR-003 限定为 legacy Field Recovery Skill packaging；新 Parsing Agent Prompt/Skill 另行交付。
  4. 保留 ADR-002 的 Layer 3/4 分层，但把 Layer 3 下游入口升级为 EffectiveFactViewV2，并明确 Layer 3 不判断 FIT/GROUP。
  5. QBD普通 New/Update/Cancel 七段业务交接已经完成；仍需Prompt/Skill、其他场景业务交接、运行接线和生产回归验收后，才讨论将 contract 从 DRAFT 提升为 APPROVED。

11. 需求追踪

需求 交付物 当前状态
公共 core 与不同 producer 外壳 Layer3ContractsV2.java Implemented as DRAFT
Parser/Agent/Effective 静态 fixture server/src/test/resources/booking/layer3/v2/qbd/ 7 fixtures implemented
QBD 最低矩阵与引用校验 Layer3ContractsV2ThinIntegrationTest.java 9 focused tests passed
Parser 不可静默覆盖 Conflict fixture + test Passed
Parser 最小修改清单 C03-v2-parser-minimal-modification-list-v1.md Generated；not implemented
Agent 最小修改清单 C03-v2-parsing-agent-minimal-modification-list-v1.md Generated；not implemented
真实 Agent/运行时接线 后续独立 CR Out of scope
QBD普通 N/U/C 七段业务语义 QBD_CORE_CONTRACT_HANDOFF_READY Complete for this thin integration

12. 开放问题

  • QBD核心三类七段业务交接已经完成；全局 Parsing Agent 的 Trace、Rooming List、Payment、General、Risk 等场景仍在业务发现中，不进入本次薄联调。
  • SemanticRoleV2 的最终 catalog 发布与兼容策略，等待更多渠道共同评审。
  • message-level Parsing Agent 的最终 Prompt/Skill/profile version，尚未创建。
  • per-attachment batch 外壳、worker 调用顺序、artifact 存储与 Context/Booking Agent 消费方式，均需后续独立实现。
  • v1 artifact 到 v2 contribution 的生产 adapter 与历史重放策略，需在运行接线前另行设计。
  • 普通 Cancel 仍需补一份真实“本次 Current 有色 Cancel/CXL”正样本；它不阻塞 v0.1 实现输入，但阻塞该场景的真实样本验收闭环。

以上开放问题不阻塞本次静态 DRAFT 薄联调，但阻塞 production approval 与真实链路接入。

13. QBD 解析 Agent v0.1 实现输入门槛

结论：READY_FOR_IMPLEMENTATION_INPUT（QBD core / DRAFT）。

本 Change Request 已提供 v0.1 实施所需的业务与契约输入：QBD普通 New/Update/Cancel/Allotment 七段语义、唯一公共 core、Producer 外壳、五态职责、History与fallback边界、目标/evidence/provenance/冲突规则、预期输出fixture、契约测试和解析Agent最小修改清单。

该结论只允许后续独立任务开始设计/实现 QBD 解析Agent v0.1 的 Prompt、Skill、profile与provider schema；本次没有实施这些资产。它不表示 booking-layer3-contracts-v2 已APPROVED，也不授权真实Agent smoke、AgentBus/数据库/下游接线或production rollout。真实Current有色Cancel正样本是后续验收补强项，不是开始v0.1实现的业务阻塞项。

Reference in new issue View Git Blame Copy Permalink