th-hotel-simple/docs/project/ai-nses-project-overlay.md

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