163 lines
9.2 KiB
Markdown
163 lines
9.2 KiB
Markdown
# 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 大文档继续保留为字段、接口、安全和实现契约。
|