21 KiB
21 KiB
M002 V4 增量需求模板化 Spec
| 项 | 内容 |
|---|---|
| 状态 | Implemented |
| 日期 | 2026-07-24 |
| 负责人 | TH Hotel 项目总揽 agent |
| 需求来源 | 2026-07-21 至 2026-07-24 V4 联调、测试机 smoke、用户新增需求确认 |
| 关联 Change Request | 无；本文作为近期 V4 增量需求入口和追踪表 |
1. 背景
M002 V4 近期连续新增了 Room Information 展示模型、Payment 附件预览、Rooming List 轻量事项卡、Trace 专属卡、普通酒店员工用户化展示、多房型展示和单卡可操作态测试数据等需求。
这些内容已经同步到字段契约、领域模型、前后端协作文档、安全边界和项目状态中，但结构上仍是补丁式写入大文档，不利于新 agent 快速判断需求、实现、测试和文档是否一致。
本文按 AI-NSES Spec 模板整理近期 V4 增量需求，作为需求入口。现有 M002 V4 大文档继续作为字段、接口、安全和实现契约。
2. 目标
- 建立近期 V4 增量需求的模板化入口。
- 明确每个需求项的后端、前端、测试和文档状态。
- 固定 Order、Order Task、Task Card、SourceMessage、S10/S99 来源通知和 SuperAgent 入站边界，避免后续 agent 混用概念。
- 明确普通酒店员工页面默认不展示技术信息，技术信息只能进入高级筛选、折叠区或受控调试模式。
- 为后续后端、前端和测试 agent 提示词提供共同基线。
3. 非目标
- 不改业务代码。
- 不改变 SuperAgent V4 JSON 入站字段。
- 不改变当前 V4 查询、确认、复核、ack 接口路径或权限。
- 不推进真实 PMS / OPERA / OHIP。
- 不恢复旧 V2/V3 任务兼容；开发阶段测试数据仍可重建。
- 不把本文变成完整 API 契约；接口细节仍以现有前后端协作文档、安全边界和 SuperAgent 契约为准。
4. 用户与场景
| 用户 / 角色 | 场景 | 期望 |
|---|---|---|
| 普通酒店员工 | 查看待处理预订事项、订单总览和订单事项办理页 | 看到业务语言、待确认事项和确认入口，不被技术字段干扰 |
| 后端 agent | 修改 V4 入站、任务卡模型、确认 / 复核或安全边界 | 先看本文确认需求，再同步领域模型、接口和安全文档 |
| 前端 agent | 实现 V4 任务列表、订单详情和任务详情 UI | 先看本文确认页面定位和可展示字段，再看接口细节 |
| 测试 agent | 测试机 smoke 和造数 | 按本文追踪表覆盖各卡片、写操作、安全扫描和阻塞规则 |
| SuperAgent 对接方 | 输出 V4 JSON | 继续以 V4 Agent 回调字段契约为准，不因展示模型新增字段 |
5. Definition of Ready
- 需求来源已确认：来自 V4 联调和用户在 2026-07-21 至 2026-07-24 的新增需求确认。
- 目标和非目标已确认：本文只整理需求入口，不改变业务代码。
- 影响范围已确认：涉及 M002 V4 需求文档、前后端协作文档、安全边界、项目状态和测试 agent 交接。
- 权限、安全、审计和数据边界已确认：继续以
security-access-control-boundary.md为总边界。 - 前后端 / 测试分工已确认：通过本文追踪表表达。
- 未确认问题已列出：见本文第 12 节。
5.1 模板对齐说明
本文按 docs/import/reusable/ai-native-templates/SPEC.template.md 组织背景、目标、非目标、用户与场景、Definition of Ready、业务规则、接口或交互契约、需求追踪表、验收标准、测试范围、Definition of Done 和文档更新。
Reservation V4 还必须满足 docs/project/ai-nses-project-overlay.md 的项目级补充，因此本文额外保留“核心概念守门”和“未确认问题”两类内容。后续若 V4 需求继续变化，应优先更新本文追踪表；如果变更已经影响已实现口径，再追加 Change Request 或新 Spec。
6. 核心概念守门
| 概念 | 本文口径 | 禁止混淆 |
|---|---|---|
| Order | 本系统本地订单投影，用于订单总览、订单归属和同订单队列 | 不等同一封 SourceMessage，不等同 V4 Order Task，不等同 PMS 最终订单 |
| Order Task | 同一 source_message + order_ref 形成的 V4 业务处理聚合 |
不等同旧 workflow_reservation_task，不直接代表单张卡 |
| Task Card | Order Task 下可独立确认 / 复核 / 锁定的业务卡或来源展示卡 | 不等同整个订单，不等同 SourceMessage |
| SourceMessage | 外部邮件或消息来源事实 | 不等同 SuperAgent 建议，不等同最终订单事实 |
| SourceMessage Display | 普通业务 Order Task 底部来源邮件展示卡 | 不是可确认业务卡，不直接改变订单状态 |
| S10/S99 来源通知 | V4 来源通知模型，只表示邮件需要查看或确认已处理 | 不创建订单，不创建业务 Order Task，不阻塞订单队列 |
| SuperAgent 入站 | 外部 Agent 提交的建议、证据和结构化事件 | 不是最终业务事实，不能绕过人工确认、权限、审计和校验 |
| REVIEW_REQUIRED | 原业务卡的复核状态 | 不新增独立复核卡，不等于允许编辑所有字段 |
7. 业务规则
7.1 Room Information
- 只由
NEW_BOOKING、UPDATE_BOOKING、CANCEL_BOOKING触发；TRACE_RESERVATION_NOTES、ROOMING_LIST、PAYMENT不触发房型信息卡。 - 后端提供
display_payload.room_information稳定展示模型，前端不从 Agent raw payload、business_fields或target_order自行推导。 room_items[]支持多个房型行。每个room_items[].room_type_code必须是单个当前酒店 Room Type 目录 code；RM2/RM3这类组合值必须拆成多行，不作为合法单 code。NEW_BOOKING展示最终值；UPDATE_BOOKING展示当前值、建议值、最终值和change_summary[]；CANCEL_BOOKING从本地订单投影只读展示。nights由后端按酒店本地日期计算；日期变更时差异区也要展示 nights 变化。breakfast_included：Group 固定含早；Fit 按 Rate Code 中RB/RO派生，无法派生时由用户必填确认。- Adult 第一版不展示。
- Group Booking Status 仅 Group 显示，稳定 code 为
TEN、DEF、INQ，显示为TEN-Tentative、DEF-Definite、INQ-Inquiry。New Group 默认TEN，用户可在确认前改选。 - New Booking 最终订单投影字段
group_block_name/fit_name允许编辑，但不回写 Agent 原始target_order.locator_value。
7.2 Payment
- Payment 卡业务事实仍是 Agent 返回的
attachment_ids[]。 - 第一版
attachment_ids[]只读，只展示并确认，不允许前端增删、替换或重新选择附件。 - 后端在
display_payload.payment_attachments[]返回安全摘要，不返回 OSS URL、签名 URL、附件正文或二进制。 - 图片附件在卡片内展示缩略图，点击打开大图预览。
- 非图片附件统一显示文件列表和下载动作，不在卡片内嵌 PDF、Word、Excel 或压缩包预览。
- 图片预览和非图片下载的真实 URL 只能通过
GET /api/source-messages/{sourceMessageId}/conversation原文权限链路取得。 - 已确认允许用户触发图片预览或文件下载时，前端 DOM 的
img[src]或a[href]临时持有 conversation 接口返回的受权限附件 URL；该 URL 仍不得出现在 V4 task detail API、页面可见文本、确认 payload、日志、URL query、localStorage 或错误上报中。 - Payment 确认只提交
version，不提交attachment_ids[]、附件 URL 或完整附件对象。
7.3 Rooming List
- Rooming List 卡第一版只做事项确认。
- 不做名单解析、附件预览、Excel 生成、PMS / OPERA / OHIP 导入。
- 用户点击“确认卡片”表示已人工处理该 Rooming List 事项。
- 如果同订单为 Group 且存在可更新的已确认 Room Information 快照，确认 Rooming List 后后端自动把 Group Booking Status 置为
DEF，并写V4_ROOMING_LIST_AUTO_DEF审计。 - 如果此前 Group Booking Status 是
TEN或INQ，确认 Rooming List 后也强制覆盖为DEF。 - Fit 不显示也不变更 Group Booking Status。
- 独立 Rooming List Excel 生成仍属于 M010
/reservation/rooming-lists/new，不嵌入 V4 Rooming List 卡。
7.4 Trace
- Trace 普通事项正式字段统一为
trace_items[].text，不使用trace_items[].content。 department_code第一版固定为FO、HSK、FO+HSK三个值，不调用 Department lookup，不开放自由文本。GENERAL可编辑trace_items[].text和trace_items[].department_code。EXTRA_BED展示固定动作SET EXTRA BED，可编辑target_room_type_code、extra_bed_room_count和department_code。target_room_type_code只校验当前酒店 Room Type 目录存在，暂不校验当前订单已有房型。extra_bed_room_count必须为正整数。- Trace 确认或复核后，详情刷新应优先显示 confirmed payload 中的最终值，并清空旧 validation errors。
7.5 REVIEW_REQUIRED
REVIEW_REQUIRED是原业务卡的复核态，不新建独立复核卡。- 页面用户可见状态显示为“需要复核”，主按钮仍显示“确认卡片”。
- 前端内部根据
card_status=REVIEW_REQUIRED调用review-resolution，不能调用普通confirm。 - 复核态只允许编辑当前卡
fields[]白名单内editable=true的业务字段。 - 问题字段通过
fields[].validation_errors红字提示；如果后端 400 错误无法映射到可见字段，应展示在卡片动作错误区。
7.6 普通酒店员工用户化展示
/reservation/tasks默认是“待处理预订事项 / 预订事项”列表，不是 V4 工作台调试页。/reservation/orders/{orderId}默认是“订单总览”页，不直接确认、复核或编辑任务卡。/reservation/order-tasks/{orderTaskId}默认是“订单事项办理”页，不是 Task Card 模型调试页。- 技术信息如
order_task_id、card_id、source_message_id、JSON Pointer、payload、route、adapter 诊断、version 等不能出现在默认主信息层级；确需排查时只能进入高级筛选、折叠区或受控调试模式。 - 每张事项卡的主动作按钮放在该事项卡右侧；移动端空间不足时放到卡片底部右对齐。
- SourceMessage Display 固定在业务事项之后，邮件正文默认折叠，用户展开后才读取当前触发该 order task 的 SourceMessage 正文。
7.7 单卡可操作态测试数据
- 测试 agent 可以为每种卡片制造“目标卡单独可操作”的测试数据。
- 造数应使用唯一 runId，不复用旧 SourceMessage 时间线导致阻塞误判。
- 为了让目标业务卡可操作，可以先确认同 order task 内 Basic Information；目标卡本身不得提前确认。
- 每条样例应记录 orderId、orderTaskId、sourceMessageId、目标 cardId、version、卡片状态、允许动作和安全扫描结果。
- 2026-07-24 测试机已完成 6 条 fresh V4 order task 数据集，覆盖 Basic、Room Information、Trace General、Trace Extra Bed Review、Rooming List 和 Payment；只执行造数和必要 Basic 前置确认，未确认目标业务卡、未执行 review-resolution、未 ack。
8. 接口或交互契约
本文不重复完整接口 schema，只固定入口和边界：
- 后端契约：继续由后端负责入站解析、目录校验、状态机、确认 / 复核、审计、酒店隔离、脱敏和安全摘要。
- 前端契约：只消费后端安全展示模型和
fields[]白名单，负责普通酒店员工页面展示、人工确认、复核交互和受控原文读取。 - 测试与 smoke 契约：测试 agent 需要记录版本线索、关键 ID、允许写操作、状态变化、请求摘要和安全扫描结果。
| 能力 | 接口 / 文档 | 契约口径 |
|---|---|---|
| V4 任务详情 | GET /api/reservation/order-tasks/{orderTaskId} |
返回安全展示模型、fields[]、availability；不返回 AI 原始 payload、邮件正文、附件 URL |
| 卡片确认 | POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/confirm |
只确认 PENDING_CONFIRM 卡；业务卡按 fields[] 白名单提交；Payment / Rooming List 第一版只提交 version |
| 复核并确认 | POST /api/reservation/order-tasks/{orderTaskId}/cards/{cardId}/review-resolution |
只处理 REVIEW_REQUIRED 卡；只接收当前卡可编辑 pointer |
| 来源邮件正文 / 附件 URL | GET /api/source-messages/{sourceMessageId}/conversation |
必须有 SOURCE_MESSAGE_READ + SOURCE_MESSAGE_ORIGINAL_READ；写原文读取审计 |
| 订单总览 | GET /api/reservation/orders/{orderId} |
只从已确认 V4 卡片派生 order_overview；办理动作跳 V4 order task |
| 工作台 / 任务列表 | GET /api/reservation/workbench-items、GET /api/reservation/order-tasks、GET /api/reservation/orders |
V4 入口优先；S10/S99 来源通知不挂订单、不进入订单队列 |
| SuperAgent 入站 | docs/project/requirements/M002-v4-agent-callback-field-contract.md、docs/project/integrations/superagent-api-contract.md |
SuperAgent 输出仍是建议和证据，不直接成为最终业务事实 |
| 安全边界 | docs/project/security-access-control-boundary.md |
所有接口继续按登录、权限、酒店隔离、审计和脱敏边界执行 |
9. 需求追踪表
| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 |
|---|---|---|---|---|---|
| Room Information 展示模型 | Done | Done | Passed | M002-v4-order-task-card-domain-model-cp2.md、前后端协作文档 |
Implemented |
Room Information 多 room_items[] 展示 |
Done | Done | Passed | 本文、V4 领域模型、Lookup 文档 | Implemented |
| Nights 后端派生 | Done | Done | Passed | V4 领域模型、Lookup 文档 | Implemented |
| Breakfast 派生：Group 固定含早，Fit 按 RB / RO | Done | Done | Partially Covered | V4 领域模型、Lookup 文档 | Implemented |
| Adult 不展示 | Done | Done | Passed | V4 领域模型、前后端协作文档 | Implemented |
| Group Booking Status：TEN / DEF / INQ 和 Rooming List 自动 DEF | Done | Done | Passed | V4 领域模型、安全边界、审计文档 | Implemented |
| Payment 附件安全摘要和前端预览 | Done | Done | Passed | V4 领域模型、安全边界、前后端协作文档 | Implemented |
Payment attachment_ids[] 只读、确认只提交 version |
Done | Done | Passed | V4 领域模型、前后端协作文档 | Implemented |
| Rooming List 轻量事项确认卡 | Done | Done | Passed | V4 领域模型、Agent 字段契约、前后端协作文档 | Implemented |
| Trace GENERAL / EXTRA_BED 专属卡 | Done | Done | Passed | V4 领域模型、Agent 字段契约、前后端协作文档 | Implemented |
| Trace 确认态字段刷新 | Done | Done | Passed | V4 领域模型、测试机 smoke 记录 | Implemented |
| REVIEW_REQUIRED 原卡复核、按钮显示“确认卡片” | Done | Done | Passed | V4 领域模型、前后端协作文档 | Implemented |
| SourceMessage Display 底部展示、正文默认折叠 | Done | Done | Passed | V4 领域模型、安全边界、前后端协作文档 | Implemented |
| V4 工作台 / 订单详情 / 任务详情普通员工用户化展示 | N/A | Done | Passed | V4 领域模型、前后端协作文档 | Implemented |
| 单卡可操作态测试数据 | N/A | N/A | Passed | 本文第 9.1 节 | Implemented |
| 模板化 Spec 对齐 | N/A | N/A | N/A | 本文、AI-NSES Overlay、项目索引 | Implemented |
9.1 单卡可操作态 Smoke 回填
2026-07-24 测试机数据集 M002-CARD-DEMO-1784726894698 已完成。该数据集用于演示和验证每类目标业务卡处于单卡可操作态，目标卡均未提前确认。
| 样例 | orderId | orderTaskId | sourceMessageId | targetCardId | 目标状态 |
|---|---|---|---|---|---|
| BASIC | 2079921478960455682 |
2079921478968844290 |
2079921475227525122 |
2079921478994010113 |
PENDING_CONFIRM，confirmable=true |
| ROOM | 2079921487558778881 |
2079921487571361794 |
2079921484266250241 |
2079921487625887745 |
PENDING_CONFIRM，confirmable=true |
| TRACE_GENERAL | 2079921506877743106 |
2079921506886131713 |
2079921501228015618 |
2079921506915491842 |
PENDING_CONFIRM，confirmable=true |
| TRACE_EXTRA_BED_REVIEW | 2079921521973043201 |
2079921521985626113 |
2079921516902129666 |
2079921522035957761 |
REVIEW_REQUIRED，reviewable=true |
| ROOMING_LIST | 2079921534555955202 |
2079921534576926722 |
2079921531255037954 |
2079921534610481153 |
PENDING_CONFIRM，confirmable=true |
| PAYMENT | 2079921555439394817 |
2079921555447783426 |
2079921543749869569 |
2079921555477143553 |
PENDING_CONFIRM，confirmable=true |
写操作范围：只执行 ROOM、TRACE_GENERAL、TRACE_EXTRA_BED_REVIEW、ROOMING_LIST、PAYMENT 五条样例的 Basic Information 前置确认，请求体均为 { "version": 0 }；未确认目标业务卡、未执行复核提交、未确认来源通知。
安全结论：6 条 V4 task detail API 均未返回 ai_payload_json、raw_evidence、html_body、text_body、target_order、附件 URL、externalUrl、download_url 或 signedUrl；页面可见文本也未展示上述敏感字段或 URL。Payment 页面在图片预览 / PDF 下载能力中，DOM 属性出现 conversation 接口返回的受权限附件 URL，按第 7.2 节口径允许，不视为 V4 task detail API 或页面可见文本泄漏。
10. 验收标准
- Given 一个新的 V4 需求改变业务卡、接口、页面交互或安全边界，When 分派给后端 / 前端 / 测试 agent，Then 必须先引用本文或后续 Change Request，并列出需求追踪表。
- Given 一个普通酒店员工打开任务列表、订单总览或订单事项办理页，When 页面默认加载，Then 不应在主信息层级展示 V4 模型、JSON Pointer、payload、内部 ID、route 或 adapter 诊断。
- Given Room Information 存在多个
room_items[]，When 打开 V4 任务详情，Then API 和页面都应展示多行房型，不把组合 code 当成单个合法房型。 - Given Payment 卡引用图片和非图片附件，When 打开 V4 任务详情，Then 任务详情 API 只返回附件安全摘要，前端通过 SourceMessage 原文权限链路展示图片预览和非图片下载。
- Given 用户触发 Payment 图片预览或非图片下载，When 浏览器渲染预览或下载入口，Then DOM
src/href可以临时使用 conversation 接口返回的受权限附件 URL，但页面可见文本、V4 task detail API、确认 payload、日志和本地存储仍不得暴露该 URL。 - Given Rooming List 卡被确认且同订单 Group 有可更新 Room Information 快照，When 刷新详情，Then Group Booking Status 显示
DEF-Definite并可查到自动 DEF 审计。 - Given Trace 卡确认或复核成功，When 刷新详情，Then
fields[].value显示已确认值，旧 validation errors 清空。
11. 测试范围
- 单元测试：本文不新增代码测试；后续代码变更仍按对应前后端模块测试要求执行。
- 集成测试：本文不改变接口；已有 smoke 已覆盖主要 V4 卡片链路。
- 手工验证：本次文档 checkpoint 使用
git diff --check验证 Markdown 格式。 - 后续 smoke：单卡可操作态数据集已回填；后续如需要可继续用 fresh runId 造演示数据，避免复用旧 SourceMessage 时间线造成阻塞误判。
12. 未确认问题
QBD_TRAVEL是否后续改为更短的QBD仍未确认；当前继续使用现有 Account code。- Rate Code 第一阶段仍是酒店级目录，不按 Account / booking type 过滤；未来如需求方要求 Account 适用关系，需要另开 Change Request。
- Payment 第一版不支持人工增删或替换附件；未来如要做附件集合编辑，需要新增数组编辑契约和审计口径。
- Trace
target_room_type_code第一版只校验目录存在，不校验当前订单已有房型；未来是否收紧待确认。 - 真实 PMS / OPERA / OHIP 目录同步、价格计算、库存校验和导入执行均后置。
13. Definition of Done
- 实现满足 Spec：本文为文档整理 checkpoint，不改业务实现。
- 测试已运行或说明无法运行原因：运行
git diff --check。 - 需求追踪表已更新：见第 9 节。
- Project State 已更新：本 checkpoint 更新
PROJECT_STATE.md。 - 接口、安全、权限、审计、集成契约已同步：本文不改变接口、安全、权限、审计或 SuperAgent 入站契约；现有契约文档保持权威。
- 无 Secret、真实数据、构建产物或无关本地变更：本文只新增 / 修改文档。
14. 文档更新
本 checkpoint 需要同步：
PROJECT_STATE.mddocs/project/README.mddocs/project/ai-nses-project-overlay.md
本 checkpoint 不需要同步后端代码、前端代码、数据库 migration 或安全边界，因为没有改变业务接口、权限、酒店隔离、审计或敏感数据返回规则。