From 79fb1aef2d8290c3c6b6242ec4782c6cc6f5477c Mon Sep 17 00:00:00 2001 From: andy Date: Fri, 24 Jul 2026 10:05:28 +0700 Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84AI-NSES=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=B2=BB=E7=90=86=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 7 +- CONTEXT.md | 6 +- PROJECT_STATE.md | 20 ++- README.md | 3 +- ...ai-native-software-engineering-standard.md | 78 ++++++++- .../AGENT_HANDOFF.template.md | 57 ++++++ .../CHANGE_REQUEST.template.md | 61 +++++++ .../reusable/ai-native-templates/README.md | 2 + .../ai-native-templates/SPEC.template.md | 38 +++- docs/project/README.md | 7 +- docs/project/ai-native-adoption.md | 8 +- docs/project/ai-nses-project-overlay.md | 162 ++++++++++++++++++ 12 files changed, 424 insertions(+), 25 deletions(-) create mode 100644 docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md create mode 100644 docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md create mode 100644 docs/project/ai-nses-project-overlay.md diff --git a/AGENTS.md b/AGENTS.md index 03dd9e4..a10234a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ - 当前项目状态入口位于 `PROJECT_STATE.md`。 - 当前项目专属文档总索引位于 `docs/project/README.md`。 - 当前项目 AI-NSES 落地说明位于 `docs/project/ai-native-adoption.md`。 +- 当前项目 AI-NSES 补充规则位于 `docs/project/ai-nses-project-overlay.md`，用于 V4 需求门禁、核心概念守门、需求追踪和 agent 交接。 - 当前项目专属后端规范位于 `docs/project/backend-development-guidelines.md`。 - 当前项目时间设计说明位于 `docs/project/backend-time-design.md`。 - 当前项目接口暴露、权限和审计边界位于 `docs/project/security-access-control-boundary.md`。 @@ -38,6 +39,7 @@ - 遇到不确定的技术栈、目录、接口契约或数据模型，先确认再继续。 - 新项目初始化或技术栈升级前，必须检查前端、后端、构建工具、测试工具和运行时版本兼容性。 - 输出分层结构、目录树、数据模型、字段映射或接口示例时，必须补充中文说明，不能只依赖英文命名表达业务含义。 +- 新增或变更重要 V4 需求时，必须先按 `docs/project/ai-nses-project-overlay.md` 形成或更新模板化 Spec / Change Request，再安排后端、前端或测试 agent 开发；简单 bugfix 可不新建完整 Spec，但必须说明目标、范围和验证方式。 - 完成 Feature 或 checkpoint 后，必须按 AI-NSES 检查 Domain、Architecture、Workflow、ADR、Spec、Project State 和安全边界文档是否需要更新；如果没有文档变化，明确说明 `No documentation changes required.`。 ## 3. 分支与提交 @@ -150,8 +152,9 @@ Coding agent 开始任务前应先读取： 3. `PROJECT_STATE.md` 4. `README.md`，如果存在 5. `docs/project/README.md` -6. `docs/` 中与当前任务相关的文档 -7. 当前代码结构和最近 Git 状态 +6. `docs/project/ai-nses-project-overlay.md` +7. `docs/` 中与当前任务相关的文档 +8. 当前代码结构和最近 Git 状态 涉及接口、权限、审计、酒店隔离或敏感数据返回的改动，开始前必须阅读 `docs/project/security-access-control-boundary.md`，完成后同步更新该文档和相关前后端或第三方契约。 diff --git a/CONTEXT.md b/CONTEXT.md index e010aa1..aa10104 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -75,10 +75,13 @@ TH Hotel Simple 是一个前后端分离的酒店业务协同项目。 - `CONTEXT.md` 说明项目长期背景。 - `PROJECT_STATE.md` 记录当前阶段状态。 - `docs/project/README.md` 作为当前项目专属文档索引。 +- `docs/project/ai-nses-project-overlay.md` 记录本项目在 AI-NSES 之上的需求门禁、V4 核心概念守门、需求追踪和 agent 交接规则。 - `docs/import/reusable/` 保存可迁移到其他项目的通用规范。 业务开发仍以 `docs/project/requirements/` 和 `docs/project/integrations/` 下的当前有效文档为准。 +新增重要 V4 需求时，应先按项目级 Overlay 形成或更新模板化 Spec / Change Request，再安排后端、前端或测试 agent 开工；现有 M002 V4 大文档继续作为字段、接口、安全和实现契约。 + ## 7. 新 Agent 阅读顺序 1. `AGENTS.md` @@ -86,6 +89,7 @@ TH Hotel Simple 是一个前后端分离的酒店业务协同项目。 3. `PROJECT_STATE.md` 4. `README.md` 5. `docs/project/README.md` -6. 与当前任务相关的需求、接口、安全、前后端协作或集成文档 +6. `docs/project/ai-nses-project-overlay.md` +7. 与当前任务相关的需求、接口、安全、前后端协作或集成文档 涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须额外阅读 `docs/project/security-access-control-boundary.md`。 diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 9e79001..7b9d6cf 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -2,24 +2,25 @@ | 项 | 内容 | | --- | --- | -| 最近更新 | 2026-07-22 | +| 最近更新 | 2026-07-24 | | 当前分支 | `feature/huangting` | -| 当前阶段 | M002 V4 入站、多卡模型、持久化基线、入站写入、查询接口、卡片确认、复核解阻、目录校验、订单详情 V4 总览、DB 目录、Lookup API、前端 lookup 接入、目录管理后台 CP1 前后端、订单列表 V4 继续处理入口 / open count 收口、V4 业务审计查询、停止旧任务双写、Debug EML V4 profile 对齐、Room Information 后端展示模型与前端业务化展示、V4 任务详情 smoke 修复、Rooming List 确认自动 DEF 后端联动、Rooming List 前端轻量事项卡、Room Information 复核 pointer 与任务详情安全边界修复、Room Information 复核 pointer 运行时规则收口、复核 pointer 部署证明与运行时 trace、OWNER RATE Room Type / Rate Code 目录口径、Payment 附件预览后端安全摘要与前端预览接入、Trace 卡后端字段契约收口、Trace 确认态字段刷新、Rooming List 事项确认卡文档口径、V4 复核态卡片交互和字段白名单文档口径、V4 工作台 / 订单详情 / 任务详情普通酒店员工用户化展示与 polish 收口、订单事项办理页克制业务办理台视觉 polish，以及 SuperAgent MCP 入站诊断链路第一版 | +| 当前阶段 | M002 V4 入站、多卡模型、持久化基线、入站写入、查询接口、卡片确认、复核解阻、目录校验、订单详情 V4 总览、DB 目录、Lookup API、前端 lookup 接入、目录管理后台 CP1 前后端、订单列表 V4 继续处理入口 / open count 收口、V4 业务审计查询、停止旧任务双写、Debug EML V4 profile 对齐、Room Information 后端展示模型与前端业务化展示、V4 任务详情 smoke 修复、Rooming List 确认自动 DEF 后端联动、Rooming List 前端轻量事项卡、Room Information 复核 pointer 与任务详情安全边界修复、Room Information 复核 pointer 运行时规则收口、复核 pointer 部署证明与运行时 trace、OWNER RATE Room Type / Rate Code 目录口径、Payment 附件预览后端安全摘要与前端预览接入、Trace 卡后端字段契约收口、Trace 确认态字段刷新、Rooming List 事项确认卡文档口径、V4 复核态卡片交互和字段白名单文档口径、V4 工作台 / 订单详情 / 任务详情普通酒店员工用户化展示与 polish 收口、订单事项办理页克制业务办理台视觉 polish、SuperAgent MCP 入站诊断链路第一版，以及 AI-NSES v0.2 / TH Hotel 项目级 Overlay 文档治理规则 | | 当前重点 | M002 V4 已停止普通业务入站双写旧 `workflow_reservation_task`，V4 后新业务主线只写 V4 order task / cards / source notification；Debug EML V4 smoke 默认复用实时 AgentBus V4 Open API subject，避免误走历史 Debug V2/V3 profile。开发阶段不维护 V2/V3 旧任务兼容，测试数据可重建，生产迁移策略后续上线前单独设计。`GET /api/reservation/orders` 可返回 V4 下一步订单任务、卡片、动作类型、动作状态、V4 open 数和统一展示字段 `open_work_item_count`；旧 `open_task_count` / `next_processable_task_id` 仅作历史诊断兼容。Room Information 已完成后端稳定展示模型和前端业务化展示：`GET /api/reservation/order-tasks/{orderTaskId}` 在 `display_payload.room_information` 返回 New / Update / Cancel 的 `current_values`、`proposed_values`、`final_values`、`change_summary[]`，前端只消费该展示模型和 `fields[]`，不再从 Agent raw payload、`business_fields` 或 `target_order` 自行推导；如果卡片 payload 已经是稳定 `room_information.final_values` 结构，后端会按稳定模型归一化查询和复核；Nights、Breakfast 和 Group Booking Status 均以后端派生值为准；确认和复核写入稳定 `confirmed_payload_json.room_information.final_values`，不回写 Agent 原始 `target_order`、Adult、邮件正文或附件 URL；接口对前端暴露的 `fields[].write_target` 使用 `confirmed_payload` / `review_resolution.field_overrides` 这类安全语义，不暴露内部列名；查询侧 `fields[].editable` 和命令侧 `review-resolution` 复核 pointer 校验已共用同一套 Room Information 字段策略。Trace 卡后端契约已收口：普通事项内容字段统一为 `trace_items[].text`，不使用 `content`；`department_code` 第一版只允许 `FO`、`HSK`、`FO+HSK`，任务详情字段会返回 `options_source=reservation_v4_trace_department_fixed` 和 `fixed_options[]` 三个固定选项；`EXTRA_BED.target_room_type_code` 只校验当前酒店 Room Type 目录存在，暂不校验当前订单已有房型；确认和复核共用同一套 Trace 字段白名单，`display_payload` / `confirmed_payload` 不返回 `target_order`、邮件正文、附件 URL、raw evidence 或 AI 原始 payload。复核 pointer 拒绝前会记录 `review_pointer_policy=m002_v4_review_pointer_runtime_fix_v1`，包含 order task、card、incoming pointer、query-side editable pointers、command-side allowed pointers、validation error pointers 和 reject reason，但不记录 payload、邮件正文或附件 URL。V4 任务详情 smoke 修复已完成：页面顺序固定为 Basic Information、业务卡、SourceMessage Display；来源邮件卡位于页面底部，只通过 SourceMessage conversation 接口定位当前触发邮件并默认折叠正文；Basic Information 和普通业务卡的展示 / 确认 payload 不再返回 Agent `target_order`，普通业务卡还会移除邮件 HTML、raw evidence、附件原始 URL 和 PMS 原始响应等敏感字段；Basic Information 的 Market Code / Source Code 前端已改为可编辑字段，普通业务页不再展示字段下方 control hint、lookup 空目录提示或“只读”胶囊。Rooming List 卡确认时已实现 Group 自动置 `DEF`：如同订单存在可更新的已确认 Room Information 快照，后端会覆盖其 `group_booking_status=DEF` 并写 `V4_ROOMING_LIST_AUTO_DEF` 审计；刷新任务详情时 `display_payload` 和 `confirmed_payload` 均以 DEF 后的确认快照为准；当前订单详情 `order_overview` 不返回 Group Booking Status 字段；如没有可更新投影，Rooming List 确认仍成功，只写安全审计提示，不临时创建不完整 Room Information。V4 任务详情已支持 ROOMING_LIST 轻量事项卡：页面只显示 “Rooming List / 房表事项”、目标订单线索、人工处理说明和确认按钮，不展示 rows、名单明细、附件预览、导入 / 生成入口、AI payload、邮件正文或附件 URL；PENDING_CONFIRM 确认只提交 `version`，成功后完全使用后端刷新详情，不由前端自行设置 `group_booking_status=DEF`。OWNER RATE `RATECODE (2)` 已确认第一阶段 Room Type 稳定集合为 `RM2`、`RM3`、`RM4`、`SU1`、`SU2`、`SU3`，不建立 Account -> Room Type 关系；Rate Code 第一阶段暂不建立 Account 适用关系，Q.B.D 与 LIAN TAI 的 40 个规范化 Rate Code 仅作为当前酒店级 `RATE_CODE` 目录候选维护。Payment 卡已在 `display_payload.payment_attachments[]` 返回付款凭证附件安全摘要，字段只包含附件 ID、文件名、类型、大小、是否图片、是否理论可预览 / 下载和可选 `external_media_id`，前端在 V4 任务详情 Payment 卡中按当前触发 SourceMessage 的 conversation 附件匹配缩略图、大图预览和非图片下载，匹配优先 `external_media_id` / `externalMediaId`，其次 `attachment_id`，不按文件名猜测；`attachment_ids[]` 第一版仍只读，前端不增删或替换附件集合，Payment 确认只提交 `version`，不提交附件 ID、附件 URL 或完整附件对象；真实 URL 仍只来自 SourceMessage 原文权限链路，权限不足或 conversation 失败时降级展示不可预览 / 不可下载。已确认 `REVIEW_REQUIRED` 仍是原业务卡复核态，页面按钮统一叫“确认卡片”，复核态允许编辑当前卡 `fields[]` 白名单内业务字段，问题字段红字提示。后续可继续做测试机 V4 smoke 复测、OWNER RATE 目录导入、真实 PMS / OPERA / OHIP 同步或 SuperAgent 目录供给方案。 | ## 1. 当前 Checkpoint -- 名称：`M002-V4-reservation-workflow-user-facing-polish-frontend` -- 状态：Done，前端已完成测试机 smoke 暴露的 V4 用户化残留收口，并完成订单事项办理页“克制的业务办理台”视觉 polish；默认页面继续保持普通酒店员工视角，不作为 V4 模型 / Task Card 调试视图展示。 -- 目标：`/reservation/tasks` 顶部导航使用“预订事项”；`/reservation/orders/{orderId}` 使用“订单总览”；`/reservation/order-tasks/{orderTaskId}` 使用“订单事项办理”。V4 Room Information 业务类型从 `NEW_BOOKING` / `UPDATE_BOOKING` / `CANCEL_BOOKING` 映射为“新预订 / 修改预订 / 取消预订”等用户文案；普通业务卡默认隐藏 lookup stale / warning 等目录技术提示；订单事项办理页首屏摘要突出订单线索、来源邮件、事项状态和卡片进度；每张事项卡的标题、提示、字段、消息和“确认卡片”按钮保持清晰层级，窄屏下主按钮仍在卡片动作区右侧。 -- 边界：本 checkpoint 不改后端接口、不改 V4 确认 / 复核 / Payment / Rooming List / Trace / Room Information 提交契约；技术字段继续用于路由、并发和提交，但默认主信息层级不展示 `V4`、`ORDER_TASK`、`SOURCE_NOTIFICATION`、Task Card、JSON Pointer、payload、内部状态码、version、route、order task ID、card ID、SourceMessage ID、adapter 诊断或附件 URL。 -- 联调备注：如后续需要更自然的用户标题、下一步动作短句、订单摘要短句、业务分类字段或调试区权限标记，建议后端补充 `display_title` / `next_step_label` / `summary_text` / debug visibility 标记，前端不要从 AI 原始 payload 自行拼装。 +- 名称：`TH-Hotel-AI-NSES-overlay-v1` +- 状态：Done，已把通用 AI-NSES 升级为 v0.2，并新增 TH Hotel 项目级 Overlay。后续 V4 重要需求不再只散落追加到 M002 大文档，必须先形成或更新模板化 Spec / Change Request，再安排后端、前端或测试 agent 开工。 +- 目标：通用标准补 Definition of Ready、Definition of Done、Change Request、Traceability Matrix 和 Agent Handoff；项目级 Overlay 补 V4 需求门禁、核心概念守门、前后端 / 测试追踪表、后端 / 前端 / 测试 agent 交接规则和文档同步清单。 +- 边界：本 checkpoint 只改文档流程和入口索引，不改业务代码、不改变 M002 V4 已实现接口、不改变 SuperAgent 入站 JSON、不改变权限、酒店隔离、审计或安全脱敏业务规则。 +- 联调备注：后续如继续新增 Payment、Trace、Rooming List、Room Information、订单详情或任务列表体验需求，应先在 `docs/project/requirements/` 形成模板化 Spec / Change Request；现有 M002 V4 大文档继续作为字段、接口、安全和实现契约。 ## 2. 当前优先级 1. 先把 AI-NSES 的入口文档落地，让新 Agent 不依赖聊天记录也能理解项目。 2. 保持 `docs/project/README.md`、`CONTEXT.md`、`PROJECT_STATE.md` 三个入口之间一致。 3. 后续开发继续以当前有效的 M002 V4 字段契约、M002 V4 CP2 多卡模型设计、M002 V3 / P0.1 历史实现说明、字段控件契约、SuperAgent 契约和安全边界文档为准。 +4. 后续新增重要 V4 需求时，先按 `docs/project/ai-nses-project-overlay.md` 形成或更新模板化 Spec / Change Request，并维护需求追踪表。 ## 3. 已确认事实 @@ -34,6 +35,7 @@ - 现有历史文档暂不按 AI-NSES 目录大搬迁，先通过索引和采用说明建立映射关系。 - `docs/import/` 下按日期导入的资料是输入材料，不等同于当前权威开发契约；当前开发应优先看 `docs/project/README.md` 标记为当前有效或权威契约的文档。 - 后续每完成一个 Feature 或 Checkpoint，需要更新本文件，避免项目状态继续沉淀在聊天记录里。 +- AI-NSES v0.2 和 TH Hotel 项目级 Overlay 已落地；但近期 M002 V4 新增需求仍需要后续专项整理成模板化 Spec / Change Request，避免继续只散落在当前有效大文档中。 - M010 Rooming List Excel 生成后端 CP1 和前端 V1 已实现：前端 `/reservation/rooming-lists/new` 上传来源名单并下载后端同步生成的 `.xlsx`，第一版不落库、不上传 OSS。CP2 已实现：来源 Excel `旅游日期` 派生 Arrival / Departure，Adults 由系统按分房结果计算，目标默认值区域只保留 Payment Type / Nationality，Payment Type 默认 `BTQR` 且当前允许 `BTQR` / `CA`，Nationality 只允许 `KR` / `CHN`。 - M011 Booking Excel 附件预处理 CP1/CP2/CP3 已实现：后端可排除人员名单类 Excel，按最近 6 个月候选窗口选择实际存在的最新 3 个业务月，抽取 Booking Update / 附加费表高亮行业务 JSON；Debug EML 和 AgentBus dispatch 在各自 include 开关与总开关同时启用时，会在调用 SuperAgent 前追加 `attachment_extractions[]`。测试机 AgentBus 增强已开启；生产链路仍默认关闭，生产开启需单独确认。 - M002 V4 CP1 当前已完成入站解析和现有任务链路过渡适配；M002 V4 CP2 已完成订单任务与多卡领域模型设计；M002 V4 CP3 已完成 V4 订单任务、多卡和 S10/S99 来源通知表结构与 Repository 基线；M002 V4 CP4 已完成入站写入新模型；M002 V4 CP5 已完成前端查询接口并补齐订单详情 `v4_order_tasks[]` 时间线；M002 V4 CP6 已完成普通卡片确认和 S10/S99 来源通知 ack；M002 V4 CP7 已完成 `REVIEW_REQUIRED` 卡复核解阻和复核场景订单归属确认；M002 V4 CP8 已完成目录校验、V4 卡片 `fields[]` 字段白名单、确认写入白名单收口和嵌套业务字段目录校验；M002 V4 CP11 已完成数据库目录、初始化种子、启动补种子、Account / Room Type / Rate Code lookup API，并把 V4 入站、确认、复核目录校验切换到当前酒店数据库目录；M002 V4 CP12 已完成前端 lookup 接入第一版和 V4 订单任务时间线消费；M002 V4 CP13 目录管理后台 CP1 已完成前后端列表、新增、启用 / 停用闭环；M002 V4 CP14 已完成订单列表 V4 继续处理入口字段和前端入口消费，`GET /api/reservation/orders` 返回 V4 下一步订单任务、卡片、动作类型、动作状态、V4 open 数和统一展示计数 `open_work_item_count`，前端按 V4 优先跳转，并按 `open_work_item_count` 展示待处理数量；V4 业务审计查询已补齐订单任务审计和来源通知 ack 审计两个只读接口；订单详情已补齐并完成前端接入 V4 `order_overview`、`next_v4_action`、`related_source_messages[]` 和 `v4_order_tasks[].cards[]`；V4 普通业务入站已停止双写旧 `workflow_reservation_task`；MCP `th_hotel_submit_task_results` 已收口为 M002 V4-only，旧 V2/V3 submit payload 返回 `MCP_SUBMIT_V4_REQUIRED`，不再影响 SuperAgent 输出契约；Room Information 后端展示模型和前端业务化展示第一版已完成；Rooming List 确认触发 Group Booking Status 自动置 `DEF` 已完成，前端轻量事项确认卡也已完成；Payment 附件安全摘要后端和前端预览接入均已完成。OWNER RATE Room Type / Rate Code 目录口径已落文档；真实 PMS 同步和 SuperAgent 目录机器接口仍未完成。 @@ -43,7 +45,8 @@ - 后续如继续做 M002 V4，可优先进行测试机联调，或推进真实 PMS / OPERA / OHIP 目录同步、`workflow_reservation_catalog_sync_run` checkpoint 和 SuperAgent 目录供给方案。 - SuperAgent 通过 MCP 提交时，排障优先查询 `platform_superagent_mcp_call_diagnostic`，对比 `arguments_json`、`adapted_payload_json`、`mapping_diagnostics_json` 和业务 batch / transition，判断问题来自 SuperAgent 原始参数、MCP adapter 还是业务入站层；V4-only 模式下 `mapping_diagnostics_json` 通常为空对象，若错误码为 `MCP_SUBMIT_V4_REQUIRED`，说明 SuperAgent 仍按旧 V2/V3 schema 输出；旧 V2/V3 被拒也会入本诊断表但不会进入业务写入 Service；V4 `source_message.conversation_id` 可缺省；该诊断表不作为业务事实来源，不进入普通前端接口。 -- 后续新增重要功能时，优先在 `docs/project/requirements/` 或未来 `docs/specs/` 中形成 Spec，再实现代码。 +- 后续新增重要功能时，优先在 `docs/project/requirements/` 或未来 `docs/specs/` 中形成 Spec，再实现代码；V4 相关需求必须按 `docs/project/ai-nses-project-overlay.md` 补核心概念守门、需求追踪表和 agent 交接边界。 +- 建议下一轮文档 checkpoint：`M002-V4-requirement-spec-template-alignment`，把近期 Payment、Trace、Rooming List、Room Information、多房型、用户化展示和单卡可操作态测试数据整理为模板化 V4 增量需求 Spec / Change Request。 - M010 CP2 字段收口已完成；预览、历史记录、OSS 下载、订单 / 任务预填或客户字段目录化仍后置，需单独开前后端 checkpoint。 - M011 CP4 暂不推进；当前停留在 CP3 边界，只增强 SuperAgent 输入，不直接落订单、任务或长期解析历史。后续如确实需要运营查询或长期追踪，再单独设计 Excel 解析批次 / 行级持久化表。 @@ -58,6 +61,7 @@ - Spec 或需求文档是否需要更新状态。 - `PROJECT_STATE.md` 是否需要更新。 - 接口、安全、权限、审计和酒店隔离文档是否需要同步。 +- 需求追踪表、Change Request 和 agent handoff 是否需要更新。 如果没有文档变化，明确说明： diff --git a/README.md b/README.md index 740afd9..eae5e3a 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,9 @@ TH Hotel Simple 是一个前后端分离的酒店业务协同项目。当前后 3. `PROJECT_STATE.md`：当前 checkpoint、优先级、Known Issues 和 Next Steps。 4. `docs/project/README.md`：当前项目专属文档总索引。 5. `docs/project/ai-native-adoption.md`：本项目如何采用 AI-NSES。 +6. `docs/project/ai-nses-project-overlay.md`：本项目在 AI-NSES 之上的需求门禁、V4 核心概念守门、需求追踪和 agent 交接规则。 -可复用 AI-NSES 标准位于 `docs/import/reusable/ai-native-software-engineering-standard.md`，模板目录位于 `docs/import/reusable/ai-native-templates/`。 +可复用 AI-NSES 标准位于 `docs/import/reusable/ai-native-software-engineering-standard.md`，模板目录位于 `docs/import/reusable/ai-native-templates/`。通用标准保持可迁移；TH Hotel 的 V4 需求门禁和项目私有规则以项目级 Overlay 为准。 ## 目录说明 diff --git a/docs/import/reusable/ai-native-software-engineering-standard.md b/docs/import/reusable/ai-native-software-engineering-standard.md index 8baafdc..651efcf 100644 --- a/docs/import/reusable/ai-native-software-engineering-standard.md +++ b/docs/import/reusable/ai-native-software-engineering-standard.md @@ -2,7 +2,7 @@ | 项 | 内容 | | --- | --- | -| Version | 0.1 | +| Version | 0.2 | | Scope | 可复用软件工程标准 | | Audience | 人类开发者、产品人员、架构师、AI Agent | @@ -137,10 +137,12 @@ project/ 职责：记录具体功能规格。每一个 Feature 对应一个 Spec。 -生命周期：Draft -> Approved -> Implemented -> Archived。 +生命周期：Draft -> Approved -> Implemented -> Superseded / Archived。 规则：Spec 完成以后保留，不删除。 +如果既有项目已经有 `docs/project/requirements/` 等历史目录，可以通过项目级 adoption 文档建立映射；但新增重要 Feature 仍应使用 Spec 模板的结构表达背景、目标、非目标、业务规则、接口或交互契约、验收标准和测试范围。 + ### docs/guidelines/ 读者：开发、测试和 AI Agent。 @@ -208,6 +210,70 @@ Idea Documentation Update 属于 Definition of Done，不能跳过。 +### 8.1 Definition of Ready + +进入实现前，复杂 Feature 或会影响跨模块协作的变更必须满足： + +- 需求来源明确，知道是谁提出、解决什么问题。 +- 目标和非目标明确，避免实现时扩大范围。 +- 受影响的用户、业务流程、接口、数据模型、权限、安全、审计或外部系统边界已经列出。 +- 前端、后端、测试或第三方系统的分工已经明确。 +- 验收标准已经可测试，至少有主要 Given / When / Then 场景。 +- 未确认问题已经列出；如果问题影响业务规则或安全边界，应先确认再实现。 + +简单 bugfix 或纯内部重构可以不用新建完整 Spec，但仍应在任务说明中写清目标、范围和验证方式。 + +### 8.2 Definition of Done + +Feature 完成前必须确认： + +- 实现满足本次 Spec、Change Request 或任务说明。 +- 相关自动化测试、类型检查、lint、构建或手工验证已经运行，或明确说明无法运行的原因。 +- 受影响的需求、Spec、Workflow、Domain、ADR、接口契约、安全边界和 Project State 已同步。 +- 对外或跨团队契约发生变化时，调用方文档和测试说明已同步。 +- 没有把 Secret、真实客户数据、构建产物、临时文件或无关本地变更纳入交付。 + +### 8.3 Change Request + +当一个已 Approved 或 Implemented 的 Spec 发生需求变更时，优先新增或更新 Change Request，而不是把讨论散落到聊天记录中。 + +Change Request 至少说明： + +- 变更背景。 +- 原规则。 +- 新规则。 +- 影响范围。 +- 迁移或兼容策略。 +- 前端、后端、测试和文档待办。 +- 验收标准。 + +小变更可以直接追加到原 Spec 的“变更记录”章节；跨前后端、权限、安全、数据模型或第三方契约的变更应单独成文。 + +### 8.4 Traceability Matrix + +复杂 Feature 应维护需求追踪表，用于连接需求、实现、测试和文档。 + +推荐字段： + +| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 | +| --- | --- | --- | --- | --- | --- | +| 示例需求 | Pending / Done / N/A | Pending / Done / N/A | Pending / Done / Blocked | Spec / Contract / README | Draft / Approved / Implemented | + +追踪表可以放在 Spec、Project State 或专项 checkpoint 文档中；关键是让新 Agent 能快速判断“文档写了但代码没做、代码做了但文档没写、后端做了但前端没做、前端需要但后端没做”。 + +### 8.5 Agent Handoff + +给 AI Agent 分派任务时，建议使用统一交接结构： + +- 背景：为什么做。 +- 目标：本次必须完成什么。 +- 边界：本次不做什么。 +- 必读文档：从入口文档到具体 Spec / Contract。 +- 影响范围：后端、前端、测试、第三方、数据、权限、安全、审计。 +- 验收标准：可执行或可观察的检查项。 +- 允许写操作：是否允许改代码、改文档、造数据、点确认按钮或清理测试数据。 +- 输出要求：代码位置、测试结果、文档更新清单、风险和下一步建议。 + ## 9. AI Working Principles - AI 应先理解，再开发。 @@ -217,6 +283,7 @@ Documentation Update 属于 Definition of Done，不能跳过。 - UI 默认保持一致性，不过度设计。 - 代码修改前先确认目标、边界和验收标准。 - 涉及接口、安全、权限、数据模型或外部系统时，先读相关契约文档。 +- 涉及跨 agent 协作时，先确认 Spec、Change Request 或 handoff 是否足够清楚。 ## 10. Documentation Rules @@ -230,6 +297,8 @@ Documentation Update 属于 Definition of Done，不能跳过。 不要维护一个 8000 行的 `DOMAIN.md`。应该按对象拆分成 `Order.md`、`Guest.md`、`Hotel.md`、`Email.md`、`Task.md`。 +通用标准只规定文档职责和流程。具体项目可以新增 Project Overlay，记录本项目专属的需求门禁、核心概念、交付格式和安全边界；Overlay 不应反向污染通用标准。 + ## 11. Documentation Update Rules 完成 Feature 后必须检查： @@ -241,6 +310,8 @@ Documentation Update 属于 Definition of Done，不能跳过。 - Spec 是否需要改为 Implemented 或补充结果。 - Project State 是否需要更新。 - 安全、权限、接口契约是否需要同步。 +- Traceability Matrix 是否需要更新。 +- Change Request 是否需要关闭、合并到 Spec 或标记为 Superseded。 如果没有文档变化，应明确说明： @@ -258,6 +329,7 @@ No documentation changes required. AGENTS.md -> CONTEXT.md -> PROJECT_STATE.md +-> 项目级 Overlay 或 Adoption 文档 -> 相关 Domain -> 相关 Workflow -> 相关 Spec 或 ADR @@ -274,3 +346,5 @@ AI-NSES 不限制编程语言、框架、数据库或 AI 模型。 它适用于 Codex、Claude Code、Gemini CLI、Cursor，以及未来任何 AI Agent。 它描述的是软件工程，不是某个具体工具。 + +具体项目如果有更强的安全、合规、业务流程或多 agent 协作要求，应通过项目级 Overlay 补充，不直接把项目私有业务规则写入本通用标准。 diff --git a/docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md b/docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md new file mode 100644 index 0000000..d40c8bd --- /dev/null +++ b/docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md @@ -0,0 +1,57 @@ +# Agent Handoff 标题 + +## 1. 背景 + +说明本次任务从哪里来，要解决什么问题。 + +## 2. 目标 + +- 必须完成事项 1： +- 必须完成事项 2： + +## 3. 边界 + +- 不做事项 1： +- 不做事项 2： + +## 4. 必读文档 + +1. `AGENTS.md` +2. `CONTEXT.md` +3. `PROJECT_STATE.md` +4. 项目文档索引 +5. 本次相关 Spec / Change Request / Contract + +## 5. 影响范围 + +| 范围 | 是否影响 | 说明 | +| --- | --- | --- | +| 后端 | 是 / 否 | | +| 前端 | 是 / 否 | | +| 数据库 | 是 / 否 | | +| 权限 / 安全 / 审计 | 是 / 否 | | +| 第三方系统 | 是 / 否 | | +| 测试数据 | 是 / 否 | | +| 文档 | 是 / 否 | | + +## 6. 验收标准 + +- Given / When / Then： +- Given / When / Then： + +## 7. 允许操作 + +- 是否允许改代码： +- 是否允许改文档： +- 是否允许造测试数据： +- 是否允许执行写操作： +- 是否允许清理数据： + +## 8. 输出要求 + +- 完成内容： +- 未完成内容： +- 代码或文档位置： +- 测试命令和结果： +- 风险： +- 下一步建议： diff --git a/docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md b/docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md new file mode 100644 index 0000000..91f202a --- /dev/null +++ b/docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md @@ -0,0 +1,61 @@ +# Change Request 标题 + +| 项 | 内容 | +| --- | --- | +| 状态 | Draft / Approved / Implemented / Superseded / Archived | +| 日期 | YYYY-MM-DD | +| 提出人 | 按实际填写 | +| 关联 Spec | 路径或编号 | +| 影响范围 | Backend / Frontend / Test / Docs / Security / Integration | + +## 1. 变更背景 + +说明为什么要改，当前问题是什么。 + +## 2. 原规则 + +- 原规则 1： +- 原规则 2： + +## 3. 新规则 + +- 新规则 1： +- 新规则 2： + +## 4. 影响范围 + +| 范围 | 是否影响 | 说明 | +| --- | --- | --- | +| 用户流程 | 是 / 否 | | +| 后端接口 | 是 / 否 | | +| 前端交互 | 是 / 否 | | +| 数据模型 | 是 / 否 | | +| 权限 / 安全 / 审计 | 是 / 否 | | +| 第三方契约 | 是 / 否 | | +| 测试数据 / 迁移 | 是 / 否 | | + +## 5. 兼容和迁移 + +- 是否兼容旧数据： +- 是否需要数据清理： +- 是否影响生产： +- 回滚或恢复方式： + +## 6. 验收标准 + +- Given / When / Then： +- Given / When / Then： + +## 7. Agent 待办 + +| Agent / 角色 | 待办 | 验证 | +| --- | --- | --- | +| 后端 | | | +| 前端 | | | +| 测试 | | | +| 文档 | | | + +## 8. 文档更新 + +- 需要更新的文档： +- 不需要更新的文档及原因： diff --git a/docs/import/reusable/ai-native-templates/README.md b/docs/import/reusable/ai-native-templates/README.md index 2ddf52a..b399d16 100644 --- a/docs/import/reusable/ai-native-templates/README.md +++ b/docs/import/reusable/ai-native-templates/README.md @@ -18,4 +18,6 @@ - `WORKFLOW.template.md`：业务流程文档模板。 - `ADR.template.md`：架构决策记录模板。 - `SPEC.template.md`：功能规格模板。 +- `CHANGE_REQUEST.template.md`：已确认需求的变更请求模板。 +- `AGENT_HANDOFF.template.md`：给后端、前端、测试或文档 agent 的任务交接模板。 - `ARCHITECTURE.template.md`：架构说明模板。 diff --git a/docs/import/reusable/ai-native-templates/SPEC.template.md b/docs/import/reusable/ai-native-templates/SPEC.template.md index 386da21..68478f6 100644 --- a/docs/import/reusable/ai-native-templates/SPEC.template.md +++ b/docs/import/reusable/ai-native-templates/SPEC.template.md @@ -2,9 +2,11 @@ | 项 | 内容 | | --- | --- | -| 状态 | Draft / Approved / Implemented / Archived | +| 状态 | Draft / Approved / Implemented / Superseded / Archived | | 日期 | YYYY-MM-DD | | 负责人 | 按实际填写 | +| 需求来源 | 用户 / 客户 / 业务方 / 内部发现 | +| 关联 Change Request | 可为空 | ## 1. 背景 @@ -24,26 +26,50 @@ 说明谁会使用这个能力，在哪些场景使用。 -## 5. 业务规则 +## 5. Definition of Ready + +- 需求来源已确认： +- 目标和非目标已确认： +- 影响范围已确认： +- 权限、安全、审计和数据边界已确认： +- 前后端 / 测试分工已确认： +- 未确认问题已列出： + +## 6. 业务规则 - 规则 1： - 规则 2： -## 6. 接口或交互契约 +## 7. 接口或交互契约 说明请求、响应、权限、安全、审计和兼容性要求。 -## 7. 验收标准 +## 8. 需求追踪表 + +| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 | +| --- | --- | --- | --- | --- | --- | +| 需求 1 | Pending / Done / N/A | Pending / Done / N/A | Pending / Done / Blocked | | Draft / Approved / Implemented | + +## 9. 验收标准 - Given / When / Then： - Given / When / Then： -## 8. 测试范围 +## 10. 测试范围 - 单元测试： - 集成测试： - 手工验证： -## 9. 文档更新 +## 11. Definition of Done + +- 实现满足 Spec： +- 测试已运行或说明无法运行原因： +- 需求追踪表已更新： +- Project State 已更新： +- 接口、安全、权限、审计、集成契约已同步： +- 无 Secret、真实数据、构建产物或无关本地变更： + +## 12. 文档更新 完成后检查 Domain、Architecture、Workflow、ADR、Project State 是否需要更新。 diff --git a/docs/project/README.md b/docs/project/README.md index da9ecd3..1e672a3 100644 --- a/docs/project/README.md +++ b/docs/project/README.md @@ -21,6 +21,7 @@ | `../../PROJECT_STATE.md` | 当前有效 | 项目当前状态入口，记录当前 checkpoint、优先级、Known Issues 和 Next Steps；允许高频更新。 | | `../../README.md` | 当前有效 | 项目根说明，记录目录、启动命令、健康检查、Debug EML 和 MCP 基础说明。 | | `ai-native-adoption.md` | 当前有效 | 本项目采用 AI-NSES 的路径说明，记录标准目录与当前目录的映射关系。 | +| `ai-nses-project-overlay.md` | 当前有效 | 本项目在通用 AI-NSES 之上的补充规则，记录 V4 需求门禁、核心概念守门、需求追踪和 agent 交接规则。 | | `backend-development-guidelines.md` | 当前有效 | 当前项目后端专属规范。 | | `backend-time-design.md` | 当前有效 | 当前项目时间设计说明，记录数据库 UTC、API `Z` 时间、酒店时区展示和本地日期边界。 | | `security-access-control-boundary.md` | 当前有效 | 当前项目接口暴露、权限码、酒店隔离和审计边界总表；新增或修改接口时必须同步。 | @@ -32,8 +33,8 @@ | 文档 | 状态 | 中文说明 | | --- | --- | --- | -| `../import/reusable/ai-native-software-engineering-standard.md` | 当前有效 | 可复制到其他项目的 AI-NSES 通用标准，定义项目文档结构、文档职责、Feature 生命周期和 AI 工作原则。 | -| `../import/reusable/ai-native-templates/README.md` | 当前有效 | AI-NSES 模板目录索引，包含 AGENTS、CONTEXT、PROJECT_STATE、Domain、Workflow、ADR、Spec 和 Architecture 模板。 | +| `../import/reusable/ai-native-software-engineering-standard.md` | 当前有效 | 可复制到其他项目的 AI-NSES 通用标准，定义项目文档结构、文档职责、Feature 生命周期、Ready / Done、Change Request、Traceability 和 Agent Handoff。 | +| `../import/reusable/ai-native-templates/README.md` | 当前有效 | AI-NSES 模板目录索引，包含 AGENTS、CONTEXT、PROJECT_STATE、Domain、Workflow、ADR、Spec、Change Request、Agent Handoff 和 Architecture 模板。 | | `../import/reusable/README.md` | 当前有效 | 可复用迁移规范总索引。 | ## 需求与方案 @@ -99,7 +100,7 @@ - SuperAgent 对外 HTTP 接口以 `integrations/superagent-api-contract.md` 为权威来源。 - SuperAgent MCP 文档以 `integrations/superagent-mcp/` 为对外交付资料包，但字段语义应跟随 HTTP 总契约。 - 接口暴露、权限、酒店隔离和审计边界以 `security-access-control-boundary.md` 为总检查清单；具体 SuperAgent / MCP / AgentBus 请求响应契约仍以 `integrations/` 下对应文档为准。 -- AI-NSES 的通用标准以 `../import/reusable/ai-native-software-engineering-standard.md` 为复用来源；本项目采用方式以 `ai-native-adoption.md` 为准。 +- AI-NSES 的通用标准以 `../import/reusable/ai-native-software-engineering-standard.md` 为复用来源；本项目采用方式以 `ai-native-adoption.md` 为准；V4 需求门禁、核心概念守门、需求追踪和 agent 交接规则以 `ai-nses-project-overlay.md` 为本项目补充。 - M002 V1 只作为历史参考；V2 记录当前阶段实现；后续 M002 新开发以 `requirements/M002-order-task-workflow-v3.md` 为开发基线。 - 2026-07-18 导入的业务基线已形成 `requirements/M002-v4-agent-callback-field-contract.md` 字段契约；M002 V4 入站解析 CP1 已落地，V4 订单任务 + 多卡领域模型设计和关键业务决策见 `requirements/M002-v4-order-task-card-domain-model-cp2.md`；M002 V4 CP3 已落地 V4 订单任务、任务卡、来源通知表结构和 Repository 基线，CP4 已落地普通 V4 业务包和 S10/S99 来源通知入站写入新模型，CP5 已落地工作台、订单任务和来源通知查询接口，CP6/CP7 已落地卡片确认、S10/S99 ack 和复核解阻，CP11 已落地 DB 目录与 lookup API，CP12 已落地前端 lookup 接入，CP13 已落地目录管理后台 CP1，CP14 已落地订单列表 V4 继续处理入口，CP15 已落地 V4 业务审计查询，CP15.1 已落地订单详情 V4 总览后端补齐且前端已接入，Room Information 后端展示模型第一版、前端业务化展示和 Rooming List 确认自动 DEF 后端联动已落地；已确认 Rooming List 卡第一版只做事项确认，`REVIEW_REQUIRED` 保持原业务卡内编辑并统一显示“确认卡片”；OWNER RATE Room Type / Rate Code 目录导入口径已落地；V4 工作台 / 订单详情 / 任务详情页默认面向普通酒店员工，技术信息只允许放在高级筛选、折叠区或受控调试模式；真实 PMS / OPERA / OHIP 同步仍后置。 - V3 / 旧任务前端展示和编辑字段仍以 2026-07-11 P0 冻结基线中的前端字段表、0712 字段控件说明和 `requirements/M002-task-field-control-contract-v1.md` 为白名单和控件契约基线；V4 订单任务前端展示和编辑字段以 `requirements/M002-v4-order-task-card-domain-model-cp2.md`、后端返回的 `fields[]` 和 V4 前后端协作文档为准。 diff --git a/docs/project/ai-native-adoption.md b/docs/project/ai-native-adoption.md index fbb1de0..b99ca47 100644 --- a/docs/project/ai-native-adoption.md +++ b/docs/project/ai-native-adoption.md @@ -16,6 +16,7 @@ AI-NSES 推荐目录和本项目当前目录的映射如下： | 项目长期上下文 | `CONTEXT.md` | 产品目标、系统组成、技术栈、业务领域和外部系统边界。 | | 项目当前状态 | `PROJECT_STATE.md` | 当前 checkpoint、优先级、已确认事实、Known Issues 和 Next Steps。 | | 项目文档索引 | `docs/project/README.md` | 当前项目专属文档总索引和权威来源说明。 | +| 项目级 Overlay | `docs/project/ai-nses-project-overlay.md` | 当前项目在 AI-NSES 之上的需求门禁、核心概念守门、V4 文档和 agent 交接规则。 | | 通用规范 | `docs/import/reusable/` | 可复制到后续项目的通用标准、开发规范和模板。 | | 当前项目需求 / Spec | `docs/project/requirements/` | 当前阶段仍沿用既有目录保存功能需求和方案。 | | 当前项目集成契约 | `docs/project/integrations/` | SuperAgent、AgentBus 和 MCP 对接资料。 | @@ -37,10 +38,11 @@ AI-NSES 推荐目录和本项目当前目录的映射如下： ## 4. 后续演进原则 -- 新增重要 Feature 时，优先形成独立 Spec。 +- 新增重要 Feature 时，优先形成独立 Spec；涉及 V4 业务卡、SuperAgent 入站、前后端接口、权限、安全、审计或普通用户页面时，必须按 `docs/project/ai-nses-project-overlay.md` 先形成或更新 Spec / Change Request。 - 新增重要架构决策时，新增 ADR，不覆盖历史。 - 新增稳定业务概念时，再补 Domain 文档。 - 新增跨模块流程时，再补 Workflow 文档。 +- 后端、前端、测试或文档 agent 的任务交接，应使用 AI-NSES handoff 结构，并补充本项目 overlay 要求的影响范围和输出要求。 - 只有当迁移能降低理解成本时，才考虑移动旧文档。 - `PROJECT_STATE.md` 是唯一允许高频更新的顶层项目状态文档。 @@ -53,7 +55,8 @@ AI-NSES 推荐目录和本项目当前目录的映射如下： 3. `PROJECT_STATE.md` 4. `README.md` 5. `docs/project/README.md` -6. 当前任务相关的需求、集成、安全或前后端协作文档 +6. `docs/project/ai-nses-project-overlay.md` +7. 当前任务相关的需求、集成、安全或前后端协作文档 涉及接口、权限、审计、酒店隔离或敏感数据返回时，必须阅读 `docs/project/security-access-control-boundary.md`。 @@ -66,6 +69,7 @@ AI-NSES 推荐目录和本项目当前目录的映射如下： - `PROJECT_STATE.md` 是否需要更新。 - 需求、Spec、Workflow、ADR 或集成契约是否需要更新。 - 安全、权限、酒店隔离和审计边界是否受影响。 +- 如果是 V4 需求，需求追踪表是否已更新，是否符合项目级 overlay 的核心概念守门和 agent 交接规则。 如果没有文档变化，应在交付说明中明确： diff --git a/docs/project/ai-nses-project-overlay.md b/docs/project/ai-nses-project-overlay.md new file mode 100644 index 0000000..c1897aa --- /dev/null +++ b/docs/project/ai-nses-project-overlay.md @@ -0,0 +1,162 @@ +# TH Hotel AI-NSES 项目级补充规则 + +## 文档信息 + +| 项 | 内容 | +| --- | --- | +| 状态 | 当前有效 | +| 日期 | 2026-07-24 | +| 适用范围 | TH Hotel Simple 当前项目的需求、文档、前后端协作、测试和多 agent 交接 | +| 不适用范围 | 可复制到其它项目的通用 AI-NSES 标准本体 | + +## 1. 文档定位 + +本文是 TH Hotel Simple 对 AI-NSES 的项目级 Overlay。 + +通用 AI-NSES 只定义文档分层、Feature 生命周期、Ready / Done、Change Request、Traceability 和 Agent Handoff 的通用机制。本文补充本项目特有的硬规则，尤其用于守住 Reservation V4 中的订单、订单任务、任务卡、SourceMessage、S10/S99 来源通知、SuperAgent 入站、前后端接口边界、权限、审计和酒店隔离。 + +如本文与 `docs/import/reusable/ai-native-software-engineering-standard.md` 冲突，以本文作为本项目补充执行；如本文与具体业务契约冲突，以 `docs/project/README.md` 标记的当前有效或权威契约为准，并更新本文或对应契约消除冲突。 + +## 2. 文档层级 + +本项目当前不整体搬迁旧文档目录。AI-NSES 角色与本项目路径映射如下： + +| 层级 | 本项目路径 | 用途 | +| --- | --- | --- | +| Agent 工作规则 | `AGENTS.md` | 规定所有 agent 的基础工作方式 | +| 长期上下文 | `CONTEXT.md` | 保存产品目标、系统组成、业务领域和外部系统边界 | +| 当前状态 | `PROJECT_STATE.md` | 保存当前 checkpoint、已完成、未完成和下一步 | +| 项目文档索引 | `docs/project/README.md` | 指向当前有效和权威契约 | +| 项目级 Overlay | `docs/project/ai-nses-project-overlay.md` | 本项目需求门禁、概念守门和 agent 交接规则 | +| 当前项目需求 / Spec | `docs/project/requirements/` | 当前阶段保存功能需求、Spec、设计和 Change Request | +| 前后端协作 | `docs/project/frontend-backend/` | 保存接口消费、字段白名单和前后端待办 | +| 安全边界 | `docs/project/security-access-control-boundary.md` | 保存接口分类、权限、酒店隔离、审计和敏感数据边界 | +| 第三方契约 | `docs/project/integrations/` | 保存 SuperAgent、AgentBus、MCP 等机器接口契约 | + +## 3. 需求门禁 + +以下情况必须先形成或更新模板化 Spec / Change Request，再安排后端、前端或测试 agent 开发： + +- 新增或改变 Reservation V4 业务卡类型、卡片字段、字段可编辑性、确认或复核规则。 +- 新增或改变 SuperAgent 入站 JSON、MCP submit、AgentBus dispatch、Debug EML V4 profile 或 SourceMessage 读取边界。 +- 新增或改变订单、订单任务、任务卡、SourceMessage、S10/S99 来源通知之间的关系。 +- 新增或改变前端普通酒店员工页面的主流程、按钮、默认文案、折叠策略、错误态或空态。 +- 新增或改变接口、权限码、酒店隔离、审计、敏感数据返回、附件 URL、邮件正文或 AI payload 脱敏规则。 +- 新增或改变测试机 smoke 样例、允许写操作、数据清理或开发阶段兼容策略。 + +以下情况可以不新建完整 Spec，但仍要在任务说明或原文档变更记录中说明范围和验证： + +- 不改变业务行为的拼写、链接、目录索引或说明性文字修正。 +- 只修复已明确的实现 bug，且不改变接口、数据模型、用户流程、安全或验收口径。 +- 只补测试数据或测试说明，且不改变业务规则。 + +## 4. V4 Spec 最小结构 + +Reservation V4 相关 Spec / Change Request 至少包含： + +1. 背景：这次需求为什么出现，解决哪个业务或联调问题。 +2. 目标：本次必须完成什么。 +3. 非目标：明确不做真实 PMS / OPERA / OHIP、旧 V2/V3 兼容、生产迁移或其它后置事项。 +4. 用户与场景：普通酒店员工、测试人员、SuperAgent 对接方或系统管理员分别如何使用。 +5. 核心概念守门：说明本需求涉及的 Order、Order Task、Task Card、SourceMessage、S10/S99、SuperAgent 入站边界，避免混用。 +6. 后端契约：接口、状态、字段白名单、目录校验、确认 / 复核、审计、权限和酒店隔离。 +7. 前端契约：页面定位、字段展示、可编辑字段、按钮位置、错误态、空态、普通用户文案和技术信息折叠。 +8. 测试与 smoke：需要造哪些数据，允许哪些写操作，哪些安全扫描必须通过。 +9. 需求追踪表：列出每个需求项的后端、前端、测试和文档状态。 +10. 未确认问题：开发前仍需用户确认的问题。 + +## 5. 核心概念守门 + +后续所有 V4 文档和 agent 提示词必须使用以下口径： + +| 概念 | 正确含义 | 禁止混淆 | +| --- | --- | --- | +| Order | 本系统本地订单投影，用于订单总览、订单归属和同订单队列 | 不等同一封邮件，不等同 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 Source Notification | V4 来源通知模型，只表示邮件需要查看或确认已处理 | 不创建订单，不创建业务 Order Task，不阻塞订单队列 | +| SuperAgent 入站 | 外部 Agent 提交的建议、证据和结构化事件 | 不是最终业务事实，不能绕过人工确认、权限、审计和校验 | +| REVIEW_REQUIRED | 原业务卡的复核状态 | 不新增独立复核卡，不等于可以编辑所有字段 | + +## 6. 前后端和测试追踪 + +每个 V4 Spec / Change Request 应维护追踪表： + +| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 | +| --- | --- | --- | --- | --- | --- | +| 示例：Payment 附件安全摘要 | Done / Pending / N/A | Done / Pending / N/A | Passed / Blocked / Not Covered | 需求文档和安全边界 | Draft / Approved / Implemented | + +状态口径： + +- `Pending`：尚未开始或未返回完成证据。 +- `Done`：对应 agent 已完成并说明验证结果。 +- `Passed`：测试 agent 已在目标环境通过。 +- `Blocked`：存在外部前置条件或失败项。 +- `N/A`：本需求不涉及该角色。 + +总揽 agent 盘点时，应优先从追踪表判断： + +- 后端已做但前端未做。 +- 前端需要但后端未做。 +- 文档写了但代码未做。 +- 代码做了但文档未写。 +- 测试未覆盖或只能部分覆盖。 + +## 7. Agent 交接规则 + +给后端 agent 的提示词必须包含： + +- checkpoint 名称。 +- 必读 Spec / Change Request / 现有契约。 +- 后端目标、边界和不做事项。 +- 涉及接口、权限、酒店隔离、审计和脱敏要求。 +- 需要补的测试范围。 +- 输出要求：代码位置、测试命令和结果、文档更新清单、风险和未完成项。 + +给前端 agent 的提示词必须包含： + +- 页面定位和目标用户，特别是普通酒店员工页面不得默认展示技术信息。 +- 可展示字段、可编辑字段、按钮和错误态。 +- 后端接口和字段白名单来源。 +- 不得展示或提交的敏感字段、payload、邮件正文和附件 URL。 +- 需要跑的类型检查、单测、lint 和 build。 + +给测试 agent 的提示词必须包含： + +- checkpoint 名称。 +- 目标环境和版本判断方式。 +- 需要创建或复用的数据类型。 +- 允许执行的写操作，例如确认卡片、复核、ack 或只读验证。 +- 必须记录的 ID、请求摘要、状态变化和安全扫描结果。 +- 通过 / 部分通过 / 未通过的判定标准。 + +## 8. 文档同步规则 + +V4 新需求落地后，至少检查以下文档： + +- `PROJECT_STATE.md` +- `docs/project/README.md` +- 对应 `docs/project/requirements/` Spec 或 Change Request +- `docs/project/frontend-backend/backend-to-frontend-notes.md` +- `docs/project/frontend-backend/frontend-to-backend-api-requests.md` +- `docs/project/security-access-control-boundary.md` +- `docs/project/integrations/superagent-api-contract.md` + +如果某文档不需要更新，交付说明中应明确写 `No documentation changes required.` 并说明原因。涉及接口、安全、权限、审计、酒店隔离或第三方契约时，不能只更新 `PROJECT_STATE.md`。 + +## 9. 当前补救口径 + +M002 V4 已有大量规则落在当前有效大文档中。短期不做大搬迁，避免打断开发和测试。 + +后续建议开 `M002-V4-requirement-spec-template-alignment` 文档 checkpoint，把近期新增需求整理成模板化 Spec / Change Request，包括： + +- Room Information 多房型、展示模型、Nights / Breakfast / Group Booking Status 和复核白名单。 +- Payment 附件安全摘要和前端预览。 +- Rooming List 轻量事项卡和确认自动 DEF。 +- Trace 普通事项和 EXTRA_BED 字段契约。 +- V4 工作台、订单详情和订单事项办理页普通酒店员工用户化展示。 +- 单卡可操作态测试数据和 smoke 追踪表。 + +整理后的 Spec 作为需求入口；现有 M002 V4 大文档继续保留为字段、接口、安全和实现契约。