huangting/th-hotel-simple
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善AI-NSES文档治理规则

Browse Source
This commit is contained in:
andy
2026-07-24 10:05:28 +07:00
parent 5df2910465
commit 79fb1aef2d
12 changed files with 424 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/project/README.md
View File

@@ -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 前后端协作文档为准。

8
docs/project/ai-native-adoption.md
View File

@@ -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 交接规则。
如果没有文档变化，应在交付说明中明确：

162
docs/project/ai-nses-project-overlay.md Normal file
View File

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