再次提交一下代码

This commit is contained in:
andy
2026-07-17 13:13:47 +07:00
parent f4d86248d4
commit 980a3a2535
41 changed files with 1699 additions and 187 deletions

View File

@@ -9,6 +9,8 @@
## 2. 文档清单
- `general-development-guidelines.md`:通用开发协作规范。
- `ai-native-software-engineering-standard.md`AI-NSES 通用标准,定义 AI 协作项目的文档结构、职责和开发闭环。
- `ai-native-templates/`AI-NSES 模板目录,供新项目初始化时复制使用。
- `frontend-development-guidelines.md`:通用前端开发规范,不包含具体业务项目规则。
- `backend-development-guidelines.md`:通用后端开发规范,不包含具体业务项目规则。
- `backend-base-structure-pagination-guidelines.md`后端基础结构、ID、审计字段、分页和 Mapper 规范。
@@ -24,4 +26,5 @@
- 前端是否仍使用 Vue、TypeScript、Vite 和 PrimeVue。
- 是否需要 SuperAgent、AgentBus 或其他外部系统接入。
- 根目录 `AGENTS.md` 是否已经引用本目录下的规范。
- 是否需要按 AI-NSES 建立 `CONTEXT.md``PROJECT_STATE.md` 和项目文档索引。
- 当前项目专属业务规则是否已经放在项目自己的文档目录,而不是混入本目录。

View File

@@ -0,0 +1,276 @@
# AI-Native Software Engineering Standard (AI-NSES)
| 项 | 内容 |
| --- | --- |
| Version | 0.1 |
| Scope | 可复用软件工程标准 |
| Audience | 人类开发者、产品人员、架构师、AI Agent |
## 1. Purpose
AI-NSES 是一套面向 AI 协作开发的软件工程标准。
它不属于某一个具体项目,而是描述:
- 项目应该如何组织。
- 文档应该如何维护。
- AI Agent 应该如何工作。
- 开发流程应该如何闭环。
目标是让任何新的 AI Agent 在几分钟内理解项目,而不依赖历史聊天记录。
## 2. Design Philosophy
### Documentation First
复杂软件首先是知识,其次才是代码。代码是项目知识的一种实现形式。
### Context Driven
Prompt 是临时的Context 是长期资产。重要知识应该沉淀在仓库,而不是沉淀在聊天记录里。
### Living Documentation
文档不是一次性产物。文档随着项目成长,开发结束时文档也应该同步结束。
### AI as Team Member
AI 不是单纯的代码生成器而是项目成员。它可以参与需求分析、产品设计、架构设计、开发、Review 和维护。
## 3. Core Principle
Build a project that teaches AI.
Do not teach AI every day.
中文说明:让项目成为 AI 的长期记忆,而不是每次都重新解释项目。
## 4. Recommended Project Structure
```text
project/
├── AGENTS.md
├── CONTEXT.md
├── PROJECT_STATE.md
├── docs/
│ ├── domain/
│ ├── architecture/
│ ├── workflows/
│ ├── adr/
│ ├── specs/
│ └── guidelines/
├── src/
└── tests/
```
中文说明:实际项目可以使用 `client/``server/``backend/``frontend/` 等目录,只要在 `CONTEXT.md` 或项目架构文档中说明映射关系即可。
## 5. Document Responsibilities
### AGENTS.md
读者:所有 AI Agent。
职责:规定 Agent 如何工作包括默认工作流程、Debug 原则、Spec 原则、文档更新原则和 Review 原则。
更新频率:极低。
### CONTEXT.md
读者:人类成员和 AI Agent。
职责:介绍项目整体背景,包括产品目标、技术栈、系统组成、当前模块和当前开发方向。
更新频率:低。
### PROJECT_STATE.md
读者:人类成员和 AI Agent。
职责:记录当前项目状态,包括当前 Sprint、当前 Feature、当前 Priority、Known Issues 和 Next Steps。
更新频率:高。建议每完成一个 Feature 或 Checkpoint 更新一次。
### docs/domain/
读者:产品、业务、开发和 AI Agent。
职责:记录业务知识。建议一个业务对象一个文档,例如 `Guest.md``Hotel.md``Order.md``Reservation.md``Email.md``Task.md``PMS.md`
内容包括定义、生命周期、业务规则和关系。禁止记录实现细节。
更新频率:低。
### docs/architecture/
读者:架构、开发和 AI Agent。
职责:记录系统设计,例如 `ARCHITECTURE.md``DATABASE.md``EVENTS.md``MODULES.md`
重点描述模块边界、系统通信、数据库、事件和部署边界。
更新频率:低。
### docs/workflows/
读者:产品、业务、开发和 AI Agent。
职责:记录业务流程,例如 Email Processing、Reservation Sync、Task Generation、Webhook Processing。
重点描述输入、输出、状态流转、异常和补偿。
更新频率:中。
### docs/adr/
读者:架构、开发和 AI Agent。
职责:记录重要架构决策。每个重要设计决策一份文档。
建议格式:背景、为什么、备选方案、最终选择、影响。
规则ADR 永远追加,不覆盖历史。
### docs/specs/
读者:产品、开发、测试和 AI Agent。
职责:记录具体功能规格。每一个 Feature 对应一个 Spec。
生命周期Draft -> Approved -> Implemented -> Archived。
规则Spec 完成以后保留,不删除。
### docs/guidelines/
读者:开发、测试和 AI Agent。
职责:记录长期规范,例如 API、UI、CODING、TESTING、SECURITY。
更新频率:极低。
## 6. Knowledge Layers
### Long-term Knowledge
生命周期:整个项目。
包括 Vision、Domain、Architecture、Guidelines。
### Medium-term Knowledge
生命周期:一个版本或一个阶段。
包括 Workflow、ADR、Spec。
### Short-term Knowledge
生命周期:一个 Sprint 或一个开发周期。
包括 Current Sprint、Known Issues、Next Steps、Backlog。
## 7. Stable vs Dynamic Documents
长期稳定:
- `AGENTS.md`
- `CONTEXT.md`
- `docs/domain/`
- `docs/architecture/`
- `docs/guidelines/`
中期演进:
- `docs/workflows/`
- `docs/adr/`
- `docs/specs/`
高频更新:
- `PROJECT_STATE.md`
中文说明:这样可以避免整个仓库每天发生无意义变化,也能让新 Agent 快速判断哪些文档代表长期事实,哪些文档代表当前状态。
## 8. Feature Lifecycle
任何 Feature 默认按以下顺序推进:
```text
Idea
-> Requirement
-> Discussion
-> Specification
-> Implementation
-> Verification
-> Documentation Update
-> Done
```
Documentation Update 属于 Definition of Done不能跳过。
## 9. AI Working Principles
- AI 应先理解,再开发。
- 复杂需求默认先讨论,不立即编码。
- 复杂功能默认先 Spec不直接实现。
- Bug 默认先定位,不猜测修复。
- UI 默认保持一致性,不过度设计。
- 代码修改前先确认目标、边界和验收标准。
- 涉及接口、安全、权限、数据模型或外部系统时,先读相关契约文档。
## 10. Documentation Rules
所有文档必须回答一个问题:
未来的新 Agent 为什么需要阅读它?
如果回答不了,就不要创建,也不要维护。
文档应该小、独立、易维护。
不要维护一个 8000 行的 `DOMAIN.md`。应该按对象拆分成 `Order.md``Guest.md``Hotel.md``Email.md``Task.md`
## 11. Documentation Update Rules
完成 Feature 后必须检查:
- Domain 是否需要更新。
- Architecture 是否需要更新。
- Workflow 是否需要更新。
- ADR 是否需要新增。
- Spec 是否需要改为 Implemented 或补充结果。
- Project State 是否需要更新。
- 安全、权限、接口契约是否需要同步。
如果没有文档变化,应明确说明:
```text
No documentation changes required.
```
不要为了修改而修改文档。
## 12. Success Criteria
一个新的 AI Agent 进入项目后,阅读以下有限文档即可开始工作:
```text
AGENTS.md
-> CONTEXT.md
-> PROJECT_STATE.md
-> 相关 Domain
-> 相关 Workflow
-> 相关 Spec 或 ADR
```
无需阅读整个代码库。
无需依赖历史聊天记录。
## 13. Scope
AI-NSES 不限制编程语言、框架、数据库或 AI 模型。
它适用于 Codex、Claude Code、Gemini CLI、Cursor以及未来任何 AI Agent。
它描述的是软件工程,不是某个具体工具。

View File

@@ -0,0 +1,40 @@
# ADR-编号 标题
| 项 | 内容 |
| --- | --- |
| 状态 | Proposed / Accepted / Superseded |
| 日期 | YYYY-MM-DD |
| 决策人 | 按实际填写 |
## 1. 背景
说明为什么需要做这个决策。
## 2. 约束
- 约束 1
- 约束 2
## 3. 备选方案
### 方案 A
说明优点和缺点。
### 方案 B
说明优点和缺点。
## 4. 最终选择
说明最终选择哪个方案。
## 5. 影响
- 正面影响:
- 负面影响:
- 后续动作:
## 6. 历史说明
ADR 只追加,不覆盖历史。如果未来决策变化,新建 ADR 或标记被替代。

View File

@@ -0,0 +1,39 @@
# 项目协作与开发规范
## 1. 文档入口
- 项目背景:`CONTEXT.md`
- 当前状态:`PROJECT_STATE.md`
- 项目文档索引:`docs/README.md` 或项目自定义索引
- 通用开发规范:按项目实际路径填写
## 2. 工作方式
- 先确认目标、边界和验收标准,再改代码或文档。
- 每次只做一个明确 checkpoint。
- 不修改与当前任务无关的用户变更。
- 不回滚用户自己的改动,除非用户明确要求。
- 遇到不确定的技术栈、接口契约、权限边界或数据模型,先确认再继续。
## 3. 文档更新原则
完成 Feature 后必须检查:
- Domain 是否需要更新。
- Architecture 是否需要更新。
- Workflow 是否需要更新。
- ADR 是否需要新增。
- Spec 是否需要更新状态。
- Project State 是否需要更新。
如果没有变化,明确说明:
```text
No documentation changes required.
```
## 4. 测试与验证
- 修改后运行对应模块已有检查命令。
- 如果检查命令尚未配置或因环境问题无法运行,必须明确说明原因。
- 不假装测试通过。

View File

@@ -0,0 +1,31 @@
# 架构说明
## 1. 系统目标
说明系统架构服务的产品目标和主要约束。
## 2. 模块边界
| 模块 | 职责 | 不负责 |
| --- | --- | --- |
| | | |
## 3. 依赖方向
说明模块之间的依赖方向,避免双向依赖和跨层直连。
## 4. 数据边界
说明数据库、缓存、文件存储、消息队列和外部系统的数据边界。
## 5. 安全边界
说明鉴权、授权、租户隔离、审计和敏感数据处理方式。
## 6. 关键决策
列出相关 ADR 链接。
## 7. 演进计划
说明后续可能调整的方向和触发条件。

View File

@@ -0,0 +1,50 @@
# 项目上下文
## 1. 项目目标
说明项目要解决什么问题、主要服务谁、成功后用户会得到什么价值。
## 2. 当前系统组成
| 模块 | 中文说明 |
| --- | --- |
| `frontend/``client/` | 前端应用,负责展示、交互和调用本项目后端。 |
| `backend/``server/` | 后端服务,负责业务规则、数据、权限、安全和外部系统适配。 |
| `docs/` | 项目文档、规范、需求和架构说明。 |
## 3. 技术栈
### 后端
- 语言:
- 框架:
- 数据库:
- 构建工具:
- 测试工具:
### 前端
- 框架:
- 构建工具:
- UI 组件:
- 测试工具:
## 4. 业务领域
列出核心业务对象,例如用户、订单、任务、酒店、邮件、支付、库存等。
## 5. 外部系统
列出外部系统、调用方向、鉴权方式和接口契约位置。
## 6. 当前开发方向
说明当前阶段最重要的开发目标和不做的事情。
## 7. 新 Agent 阅读顺序
1. `AGENTS.md`
2. `CONTEXT.md`
3. `PROJECT_STATE.md`
4. 项目文档索引
5. 与当前任务相关的 Domain、Workflow、Spec、ADR

View File

@@ -0,0 +1,27 @@
# 业务对象名称
## 1. 定义
说明这个业务对象是什么,不是什么。
## 2. 生命周期
说明对象从创建到结束的主要状态。
## 3. 业务规则
- 规则 1
- 规则 2
- 规则 3
## 4. 关系
说明它和其他业务对象的关系。
## 5. 禁止混淆
列出容易和它混淆的概念。
## 6. 非目标
说明本文不记录实现细节、表结构或接口字段。实现细节应放在 Architecture、Spec 或代码中。

View File

@@ -0,0 +1,39 @@
# 项目当前状态
| 项 | 内容 |
| --- | --- |
| 最近更新 | YYYY-MM-DD |
| 当前分支 | 按实际填写 |
| 当前阶段 | 按实际填写 |
| 当前重点 | 按实际填写 |
## 1. 当前 Feature 或 Checkpoint
- 名称:
- 状态Draft / In Progress / Blocked / Ready for Review / Done
- 目标:
- 验收标准:
## 2. 当前优先级
1. 第一优先级:
2. 第二优先级:
3. 第三优先级:
## 3. 已确认事实
- 记录对后续开发有影响的当前事实。
- 只写仍然有效的事实,不写长篇历史。
## 4. Known Issues
- 记录当前已知问题、风险和待验证点。
## 5. Next Steps
- 下一步最小动作。
- 下一个建议 checkpoint。
## 6. 文档同步提醒
完成 Feature 后检查 Domain、Architecture、Workflow、ADR、Spec、Project State 是否需要更新。

View File

@@ -0,0 +1,21 @@
# AI-NSES 模板目录
本目录保存可复制到新项目的 AI-NSES 文档模板。
使用方式:
1. 复制需要的模板到新项目对应位置。
2. 删除模板中的示例说明。
3. 补充项目真实信息。
4. 在项目 `AGENTS.md` 和项目文档索引中加入入口。
模板清单:
- `AGENTS.template.md`AI Agent 协作入口模板。
- `CONTEXT.template.md`:项目背景入口模板。
- `PROJECT_STATE.template.md`:项目当前状态模板。
- `DOMAIN_OBJECT.template.md`:业务对象文档模板。
- `WORKFLOW.template.md`:业务流程文档模板。
- `ADR.template.md`:架构决策记录模板。
- `SPEC.template.md`:功能规格模板。
- `ARCHITECTURE.template.md`:架构说明模板。

View File

@@ -0,0 +1,49 @@
# Feature Spec 标题
| 项 | 内容 |
| --- | --- |
| 状态 | Draft / Approved / Implemented / Archived |
| 日期 | YYYY-MM-DD |
| 负责人 | 按实际填写 |
## 1. 背景
说明为什么要做这个功能。
## 2. 目标
- 目标 1
- 目标 2
## 3. 非目标
- 不做事项 1
- 不做事项 2
## 4. 用户与场景
说明谁会使用这个能力,在哪些场景使用。
## 5. 业务规则
- 规则 1
- 规则 2
## 6. 接口或交互契约
说明请求、响应、权限、安全、审计和兼容性要求。
## 7. 验收标准
- Given / When / Then
- Given / When / Then
## 8. 测试范围
- 单元测试:
- 集成测试:
- 手工验证:
## 9. 文档更新
完成后检查 Domain、Architecture、Workflow、ADR、Project State 是否需要更新。

View File

@@ -0,0 +1,37 @@
# 业务流程名称
## 1. 目标
说明这个流程要完成什么业务目标。
## 2. 触发条件
说明流程从哪里开始。
## 3. 输入
| 输入 | 中文说明 | 来源 |
| --- | --- | --- |
| | | |
## 4. 输出
| 输出 | 中文说明 | 去向 |
| --- | --- | --- |
| | | |
## 5. 正常流程
1. 步骤一。
2. 步骤二。
3. 步骤三。
## 6. 异常与补偿
- 异常:
- 补偿:
- 审计:
## 7. 边界
说明哪些事情属于本流程,哪些事情不属于本流程。

View File

@@ -17,7 +17,10 @@
| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `../../AGENTS.md` | 当前有效 | 项目协作入口,记录 agent 工作方式、分支、目录、前后端边界、安全和测试要求。 |
| `../../CONTEXT.md` | 当前有效 | 项目长期上下文入口,记录产品目标、技术栈、系统组成、业务领域和外部系统边界。 |
| `../../PROJECT_STATE.md` | 当前有效 | 项目当前状态入口,记录当前 checkpoint、优先级、Known Issues 和 Next Steps允许高频更新。 |
| `../../README.md` | 当前有效 | 项目根说明记录目录、启动命令、健康检查、Debug EML 和 MCP 基础说明。 |
| `ai-native-adoption.md` | 当前有效 | 本项目采用 AI-NSES 的路径说明,记录标准目录与当前目录的映射关系。 |
| `backend-development-guidelines.md` | 当前有效 | 当前项目后端专属规范。 |
| `backend-time-design.md` | 当前有效 | 当前项目时间设计说明,记录数据库 UTC、API `Z` 时间、酒店时区展示和本地日期边界。 |
| `security-access-control-boundary.md` | 当前有效 | 当前项目接口暴露、权限码、酒店隔离和审计边界总表;新增或修改接口时必须同步。 |
@@ -25,6 +28,14 @@
| `frontend-backend/README.md` | 当前有效 | 前后端协作入口,记录接口契约来源、字段白名单和当前后置事项。 |
| `go-live-notes.md` | 当前有效 | 当前项目上线注意事项记录上线前检查、环境变量、安全、AgentBus、验证和回滚。 |
## AI-NSES 与可复用规范
| 文档 | 状态 | 中文说明 |
| --- | --- | --- |
| `../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/README.md` | 当前有效 | 可复用迁移规范总索引。 |
## 需求与方案
| 文档 | 状态 | 中文说明 |
@@ -75,6 +86,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` 为准。
- M002 V1 只作为历史参考V2 记录当前阶段实现;后续 M002 新开发以 `requirements/M002-order-task-workflow-v3.md` 为开发基线。
- 前端展示 / 编辑字段以 2026-07-11 P0 冻结基线中的前端字段表、0712 字段控件说明和 `requirements/M002-task-field-control-contract-v1.md` 为白名单和控件契约基线;后端完整校验和 OPERA 映射仍以任务卡完整矩阵、0711 runtime 契约和后端规则为准。
- 时间点语义以 `backend-time-design.md` 为准;数据库时间点按 UTC 理解API 返回带 `Z` 的 UTC 时间,页面再按酒店或用户时区展示。

View File

@@ -0,0 +1,80 @@
# 本项目 AI-NSES 落地说明
## 1. 目标
本文说明 TH Hotel Simple 如何采用 AI-Native Software Engineering Standard (AI-NSES)。
本次落地只建立文档标准化入口,不搬迁现有历史文档,不删除已有文档,不改变代码结构。
## 2. 当前采用方式
AI-NSES 推荐目录和本项目当前目录的映射如下:
| AI-NSES 角色 | 本项目当前位置 | 中文说明 |
| --- | --- | --- |
| Agent 工作规则 | `AGENTS.md` | 当前项目协作、开发、安全、分支和测试规则。 |
| 项目长期上下文 | `CONTEXT.md` | 产品目标、系统组成、技术栈、业务领域和外部系统边界。 |
| 项目当前状态 | `PROJECT_STATE.md` | 当前 checkpoint、优先级、已确认事实、Known Issues 和 Next Steps。 |
| 项目文档索引 | `docs/project/README.md` | 当前项目专属文档总索引和权威来源说明。 |
| 通用规范 | `docs/import/reusable/` | 可复制到后续项目的通用标准、开发规范和模板。 |
| 当前项目需求 / Spec | `docs/project/requirements/` | 当前阶段仍沿用既有目录保存功能需求和方案。 |
| 当前项目集成契约 | `docs/project/integrations/` | SuperAgent、AgentBus 和 MCP 对接资料。 |
| 当前项目安全边界 | `docs/project/security-access-control-boundary.md` | 接口暴露、权限、酒店隔离和审计边界总表。 |
| 当前项目前后端协作 | `docs/project/frontend-backend/` | 前后端字段、接口和调试页面协作入口。 |
## 3. 暂不搬迁的原因
当前项目已经有大量历史需求、集成契约、前后端协作文档和导入资料。
如果一次性把这些文档搬到 `docs/domain/``docs/architecture/``docs/workflows/``docs/specs/`,会带来以下风险:
- 历史链接失效。
- 当前开发基线不容易判断。
- 大量文件移动会干扰代码 Review。
- 新 Agent 反而需要同时理解旧路径和新路径。
因此当前阶段采用“入口标准化 + 索引映射”的方式。
## 4. 后续演进原则
- 新增重要 Feature 时,优先形成独立 Spec。
- 新增重要架构决策时,新增 ADR不覆盖历史。
- 新增稳定业务概念时,再补 Domain 文档。
- 新增跨模块流程时,再补 Workflow 文档。
- 只有当迁移能降低理解成本时,才考虑移动旧文档。
- `PROJECT_STATE.md` 是唯一允许高频更新的顶层项目状态文档。
## 5. Agent 默认阅读顺序
新的 Agent 进入项目后,默认先读:
1. `AGENTS.md`
2. `CONTEXT.md`
3. `PROJECT_STATE.md`
4. `README.md`
5. `docs/project/README.md`
6. 当前任务相关的需求、集成、安全或前后端协作文档
涉及接口、权限、审计、酒店隔离或敏感数据返回时,必须阅读 `docs/project/security-access-control-boundary.md`
## 6. Feature Definition of Done
功能完成前需要确认:
- 代码或文档是否满足本次验收标准。
- 对应测试或基础检查是否运行。
- `PROJECT_STATE.md` 是否需要更新。
- 需求、Spec、Workflow、ADR 或集成契约是否需要更新。
- 安全、权限、酒店隔离和审计边界是否受影响。
如果没有文档变化,应在交付说明中明确:
```text
No documentation changes required.
```
## 7. 给后续 Agent 的一句话
本项目的长期记忆应优先来自仓库文档,而不是历史聊天记录。
遇到聊天记录和仓库文档不一致时,先以 `AGENTS.md``CONTEXT.md``PROJECT_STATE.md``docs/project/README.md` 中的当前有效文档为准;如果仍有冲突,再向用户确认。

View File

@@ -12,6 +12,8 @@ Runtime、Planner、Memory 或通用工具调用框架。
当前项目时间存储、接口返回、酒店时区展示和本地业务日期边界统一参考 `docs/project/backend-time-design.md`
当前项目接口暴露、权限、酒店隔离和审计边界统一参考 `docs/project/security-access-control-boundary.md`。新增或修改 Controller、第三方入口、调试入口或 worker 触发入口时,必须同步检查该文档。
## 2. 技术栈
`server/pom.xml` 为准,当前后端技术栈如下:
@@ -278,7 +280,45 @@ Secret 只能通过 `.env`、环境变量或部署平台 Secret 注入。仓库
- 后端 Secret 不得放入前端 `VITE_*`
- 生产环境应拆分 ConfigMap / 非敏感环境变量与 Secret / 密钥管理系统。
## 14. API 设计规范
## 14. 接口暴露、权限和审计边界
新增或修改后端入口前,必须先判定接口分类:
```text
PUBLIC
FRONTEND_USER
FRONTEND_ADMIN
FRONTEND_DEBUG
THIRD_PARTY_SUPERAGENT
THIRD_PARTY_AGENTBUS
THIRD_PARTY_MCP
INTERNAL_ONLY
```
中文说明:
| 分类 | 中文含义 | 后端落地要求 |
| --- | --- | --- |
| `PUBLIC` | 公开基础接口 | 只能返回健康、登录等非敏感信息,不返回业务数据和配置细节 |
| `FRONTEND_USER` | 普通业务前端接口 | 目标状态必须登录、权限码和酒店访问权控制 |
| `FRONTEND_ADMIN` | 系统管理后台接口 | 必须登录、管理权限码和管理审计 |
| `FRONTEND_DEBUG` | Debug、Demo、Replay、Probe 等调试接口 | 必须有环境开关、受控 access key 或管理权限,生产默认关闭或严格限制 |
| `THIRD_PARTY_SUPERAGENT` | SuperAgent 服务到服务接口 | 使用 HMAC、timestamp、nonce、body hash 等机器鉴权,不使用用户 Bearer token |
| `THIRD_PARTY_AGENTBUS` | AgentBus 实时入口 | 使用 AgentBus Token、入库幂等和受控 dispatch不直接改业务状态 |
| `THIRD_PARTY_MCP` | MCP 工具入口 | 使用 Bearer Token 和工具级能力限制,不暴露无关业务接口 |
| `INTERNAL_ONLY` | 后端内部能力 | 不提供外部 HTTP 入口,只能通过 Service、Port、Worker 或 Adapter 内部调用 |
落地规则:
- Controller 方法新增前必须明确调用方、鉴权方式、权限码、酒店隔离方式、敏感字段返回边界和审计要求。
- 前端业务接口最终应使用登录态、权限码和酒店访问权;第三方机器接口不得误用用户登录态。
- 后端内部 Adapter、Repository、Mapper、Secret、外部系统 client、raw payload 和原始附件读取能力不得直接暴露给前端或第三方。
- 邮件正文、HTML、附件 URL、AI 原始 payload、trace、调试错误摘要等敏感数据返回前必须确认调用方和审计策略。
- 写接口必须明确 actor 来源前端用户写操作使用当前登录用户SuperAgent、MCP、AgentBus 使用机器身份。
- 新增或变更接口必须同步更新 `docs/project/security-access-control-boundary.md`。影响前端时同步更新 `docs/project/frontend-backend/backend-to-frontend-notes.md`,影响 SuperAgent / MCP / AgentBus 时同步更新对应集成契约文档。
- 新增接口权限时必须执行 `docs/project/security-access-control-boundary.md` 中“新增接口权限固定流程”:定义权限码、补启动同步、补内置角色矩阵、后端强制校验、前端权限类型和交互同步、系统设置可分配、补测试和文档。
## 15. API 设计规范
- API 返回稳定代码,不返回中文或英文文本作为前端业务判断依据。
- 动态表单字段使用稳定 `fieldKey` 和可国际化 `labelKey`
@@ -287,7 +327,7 @@ Secret 只能通过 `.env`、环境变量或部署平台 Secret 注入。仓库
- 外部写操作结果不明确时,禁止盲目重试。
- 调试接口必须默认关闭,并使用独立访问密钥。
## 15. 测试与检查命令
## 16. 测试与检查命令
后端最低检查:
@@ -308,7 +348,7 @@ cd server
如果命令尚未配置或因环境问题无法运行,必须明确说明,不能假装通过。
## 16. Git 与协作流程
## 17. Git 与协作流程
- 改动前说明目标、范围和将修改的文件。
- 每次只处理一个模块或一个纵向切片。
@@ -318,11 +358,13 @@ cd server
- 修改后运行项目已配置的检查命令。
- Git commit message 使用中文,清楚说明本次提交的业务或技术变更。
## 17. 后端提交前检查清单
## 18. 后端提交前检查清单
- [ ] 是否遵守 platform / workflows / integrations 分层?
- [ ] 是否已在 `docs/project/security-access-control-boundary.md` 中登记或更新接口分类、鉴权方式、权限码、酒店隔离和审计要求?
- [ ] 模块内部是否遵守 `control` / `service` / `service.impl` / `domain` / `mapper` / `repository` / `common.dto` / `common.request` / `common.result` / `common.enums` 目录规则?
- [ ] Controller 是否没有直接访问 Mapper 或外部 Adapter
- [ ] 第三方接口是否没有误用用户登录权限,前端接口是否没有直接暴露 Secret、raw payload 或外部系统调用能力?
- [ ] Request、Result、DTO 是否放在 `common.request``common.result``common.dto`,而不是混在 `service` 或临时 `application` 包?
- [ ] `control``service``service.impl``repository` 方法是否有中文注释?
- [ ] Mapper 自定义语义化方法是否按复杂度合理补充中文注释,且未为了 MyBatis-Plus 自带继承方法强行加无意义注释?

View File

@@ -40,9 +40,9 @@
| `POST /api/reservation/tasks/{taskId}/manual-review-resolutions` | 已完成第一版 | 可以 | 只用于 type-known manual review第一版 `confirmed_order_id` 必须等于当前任务订单,不开放普通任务任意切换订单。 |
| `GET /api/source-messages` | 已完成安全摘要列表 | 可以 | 不能替代邮件会话全文接口。 |
| `GET /api/source-messages/{id}` | 已完成单条安全摘要 | 可以 | 不能替代邮件会话全文接口。 |
| `GET /api/source-messages/{id}/original` | 已完成单封原文受控读取 | 谨慎接入 | 只能读单封邮件,不能返回同一 conversation 全量邮件。 |
| `GET /api/source-messages/{id}/original` | 已完成单封原文权限读取 | 谨慎接入 | 必须带 Bearer token需要同时拥有 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ`只能读单封邮件,不能返回同一 conversation 全量邮件。 |
| `GET /api/reservation/orders` | 已完成第一版 | 可以 | 默认查询全部订单状态;`open_task_count` 排除 `COMPLETED``FAILED`。 |
| `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版,已补 `html_body_sanitized``html_render_mode` | 可以 | 返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要;前端不传原文读取 key页面展示优先使用 `html_body_sanitized`。 |
| `GET /api/source-messages/{sourceMessageId}/conversation` | 已完成第一版,已补 `html_body_sanitized``html_render_mode` | 可以 | 必须带 Bearer token需要同时拥有 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ`返回完整 text/html、后端清洗后的 HTML、媒体外链和关联订单 / 任务摘要;前端不传原文读取 key页面展示优先使用 `html_body_sanitized`。 |
| `POST /api/system/reservation/demo-data` | 已完成 | 仅本地 / test 联调可用 | 默认关闭,必须后端配置访问口令;不能作为生产页面接口。 |
| `POST /api/system/debug/eml-superagent-runs` | 已完成第一版 | 仅 dev/test Debug 页面可用 | 默认关闭,必须后端配置访问口令、阿里云 OSS 和 SuperAgent Open API第一版只展示 SuperAgent 结果,不创建订单和任务;已能识别旧 S000/S999 和新结构化 S10/S99。 |
| `GET /api/source-message-conversations/{externalConversationId}` | 未发现后端实现 | 不可以 | 历史讨论过的候选路径,当前不提供;前端统一使用 `GET /api/source-messages/{sourceMessageId}/conversation`。 |
@@ -378,10 +378,11 @@ GET /api/source-message-conversations/{externalConversationId}
中文说明:
- 该接口已经完成权限收口:请求必须带 `Authorization: Bearer <access_token>`,当前用户必须同时拥有 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ`,后端会按 SourceMessage 实际所属酒店校验访问权。
- “全部邮件”指同一个 `externalConversationId` 下的历史邮件、当前邮件和后续回复,不是只展示任务对应的单封来源邮件。
- 邮件会话详情页需要展示完整正文或清洗后的 HTML、附件、内联图片、发件人展示值、发送 / 接收时间、主题和关联订单 / 任务。
- 前端不在页面上做业务截断或隐藏但仍只调用本项目后端接口不直接访问邮箱、AgentBus、数据库或外部附件 URL Secret。
- 如果后端仍需要审计原文读取,应由后端在该业务接口内部处理;前端不保存 `X-TH-Hotel-Source-Original-Read-Key` 一类受控访问 key。
- 原文读取审计由后端在该业务接口内部处理actor 使用当前登录用户稳定 ID;前端不保存或传递 `X-TH-Hotel-Source-Original-Read-Key` 一类受控访问 key。
- 2026-07-08 后端已新增 `html_body_sanitized``html_render_mode`;前端页面展示邮件 HTML 时应优先使用 `html_body_sanitized``html_body` 只作为原始内容兼容字段,不建议生产直渲。
- 第一版仅处理 HTML 内容清洗;附件和内联图片 URL 来自本系统 OSS 服务,暂不做额外拦截或代理转换。

View File

@@ -294,8 +294,6 @@ AGENTBUS_SUPERAGENT_DISPATCH_ENABLED=false
AGENTBUS_SUPERAGENT_DISPATCH_WORKER_ENABLED=false
AGENTBUS_REPLY_MODE=NONE
AUTH_DEV_BOOTSTRAP_DEFAULT_HOTEL_ID=HOTEL-DEV
SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY=
SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
```
变量说明:
@@ -322,10 +320,7 @@ SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY=
| `SUPERAGENT_OPEN_API_SSE_RECOVERY_MAX_ATTEMPTS` | 否 | SSE 断流恢复最大次数,默认 `5`。 |
| `AUTH_DEV_BOOTSTRAP_DEFAULT_HOTEL_ID` | 否 | dev 初始化平台酒店M005 后 AgentBus 捕获运行时从 `platform_hotel` 唯一 `ACTIVE` 酒店解析系统酒店,不再依赖 `AGENTBUS_DEFAULT_HOTEL_ID`。 |
| `AGENTBUS_REPLY_MODE` | 否 | 调试回复模式。真实客户渠道应保持 `NONE`。 |
| `SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY` | | dev 原文读取接口的临时受控访问 key后续可替换为正式权限体系。 |
| `SOURCE_MESSAGE_TEST_ORIGINAL_READ_ACCESS_KEY` | 是 | test 原文读取接口的临时受控访问 key。 |
| `SOURCE_MESSAGE_PROD_ORIGINAL_READ_ACCESS_KEY` | 是 | prod 原文读取接口的临时受控访问 key只能通过生产 Secret 注入。 |
| `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY` | 是 | 旧通用原文读取 key仅作为兼容兜底。 |
| `SOURCE_MESSAGE_*_ORIGINAL_READ_ACCESS_KEY` | | 已废弃。SourceMessage 原文 / 会话正文读取已迁移到前端 Bearer 登录 + `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ` + 酒店访问权,不再配置原文读取 key。 |
### 5.2 WebSocket 连接
@@ -599,10 +594,6 @@ MessageEvent
- `DEERFLOW_OPEN_API_KEY`
- `SUPERAGENT_PROBE_ACCESS_KEY`
- `AGENTBUS_WS_TOKEN`
- `SOURCE_MESSAGE_DEV_ORIGINAL_READ_ACCESS_KEY`
- `SOURCE_MESSAGE_TEST_ORIGINAL_READ_ACCESS_KEY`
- `SOURCE_MESSAGE_PROD_ORIGINAL_READ_ACCESS_KEY`
- `SOURCE_MESSAGE_ORIGINAL_READ_ACCESS_KEY`
- `SOURCE_MESSAGE_REPLAY_ACCESS_KEY`
- 数据库密码
- 任何真实客户渠道 Token

View File

@@ -219,7 +219,7 @@ SOURCE_MESSAGE_READ
// 邮件来源记录读取权限:允许查看列表和摘要详情
SOURCE_MESSAGE_ORIGINAL_READ
// 邮件原文读取权限允许读取正文、HTML、正文图片 URL 和附件 URL
// 邮件原文读取附加权限:需叠加 SOURCE_MESSAGE_READ允许读取正文、HTML、正文图片 URL 和附件 URL
```
## 6. Success Metrics
@@ -233,7 +233,7 @@ SOURCE_MESSAGE_ORIGINAL_READ
- 重复投递去重成功率:重复外部邮件不会重复创建 SourceMessage。
- 查询可用性:可以按时间、状态、外部邮件 ID、外部邮件链 ID 查询本项目已接收邮件。
- 原文读取可控性:只有具备 `SOURCE_MESSAGE_ORIGINAL_READ` 权限的调用方可以读取原文和媒体 URL。
- 原文读取可控性:只有同时具备 `SOURCE_MESSAGE_READ` `SOURCE_MESSAGE_ORIGINAL_READ` 权限的调用方可以读取原文和媒体 URL。
### Guardrail Metrics
@@ -310,10 +310,10 @@ so that 后续业务功能可以在需要时展示完整邮件上下文
Acceptance Criteria:
- Given 调用方具备 `SOURCE_MESSAGE_ORIGINAL_READ` 权限
- Given 调用方同时具备 `SOURCE_MESSAGE_READ` `SOURCE_MESSAGE_ORIGINAL_READ` 权限
When 调用邮件原文读取接口
Then 返回 `textBody``htmlBody``inlineImages[]``attachments[]`
- Given 调用方不具备 `SOURCE_MESSAGE_ORIGINAL_READ` 权限
- Given 调用方不具备 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ` 任一权限
When 调用邮件原文读取接口
Then 系统拒绝访问
- Given 原文接口返回 `htmlBody`
@@ -347,9 +347,9 @@ Acceptance Criteria:
### Dependencies
- AgentBus payload 字段稳定性:依赖 `source.external_message_id``source.external_conversation_id``body.text``body.html``inline_images[]``attachments[]`
- 权限体系:需要后续确认 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ` 如何落到角色
- 审计体系:需要记录原文读取行为,具体表结构可与平台审计能力统一设计
- HTML 安全展示:前端展示 HTML 前必须 sanitize后端接口文档也要明确该约束
- 权限体系:已落地 `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ`,内置角色映射以 M003 和当前代码为准
- 审计体系:原文读取已使用 `platform_source_message_original_access_audit` 独立记录
- HTML 安全展示:后端已返回 `html_body_sanitized` / `html_render_mode`,前端生产展示优先使用清洗字段
### Risks & Mitigations
@@ -358,7 +358,7 @@ Acceptance Criteria:
- Risk重复投递 payload 内容不同,覆盖原始事实会破坏追溯。
Mitigation幂等命中后不覆盖原 payload差异通过安全摘要或后续 attempt 记录表达。
- Risk邮件原文或媒体 URL 在列表、日志、错误响应中过度暴露。
Mitigation列表只返回安全摘要原文接口独立权限;日志和错误响应脱敏。
Mitigation列表只返回安全摘要原文接口必须同时校验摘要读取和原文读取权限;日志和错误响应脱敏。
- Risk业务模块直接依赖 AgentBus DTO。
Mitigation业务模块只依赖 SourceMessage ID 和平台接口AgentBus DTO 只留在 `integrations.messaging.agentbus`
- RiskHTML 原文直接渲染带来安全问题。
@@ -368,10 +368,10 @@ Acceptance Criteria:
| 问题 | 负责人 | 状态 |
| --- | --- | --- |
| 第一个 checkpoint 是否直接实现 `/api/source-messages/{id}/original` 原文读取接口,还是只写接口契约并后置实现? | 产品 / 后端 | Open |
| `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ` 第一阶段如何映射到角色? | 产品 / 后端 | Open |
| 原文读取审计是否使用独立表,还是复用后续统一审计能力? | 后端 | Open |
| HTML sanitize 主要在前端完成,还是后端也提供清洗后的安全 HTML | 前端 / 后端 | Open |
| 第一个 checkpoint 是否直接实现 `/api/source-messages/{id}/original` 原文读取接口,还是只写接口契约并后置实现? | 产品 / 后端 | Closed已实现单封原文读取并补充会话完整正文接口。 |
| `SOURCE_MESSAGE_READ``SOURCE_MESSAGE_ORIGINAL_READ` 第一阶段如何映射到角色? | 产品 / 后端 | Closed内置 `RESERVATION_OPERATOR` 含原文读取权限,`RESERVATION_VIEWER` 仅含安全摘要读取权限;系统管理员拥有全部权限。 |
| 原文读取审计是否使用独立表,还是复用后续统一审计能力? | 后端 | Closed使用 `platform_source_message_original_access_audit` 独立记录原文读取审计。 |
| HTML sanitize 主要在前端完成,还是后端也提供清洗后的安全 HTML | 前端 / 后端 | Closed后端返回 `html_body_sanitized` / `html_render_mode`,前端生产展示优先使用清洗字段。 |
| 是否需要第一阶段支持按正文摘要关键字搜索,还是只按 ID、时间、状态、邮件链查询 | 产品 | Open |
## PRD Self-Assessment

View File

@@ -263,7 +263,7 @@ platform.security
| 权限码 | 中文说明 |
| --- | --- |
| `SOURCE_MESSAGE_READ` | 查看来源消息安全摘要 |
| `SOURCE_MESSAGE_ORIGINAL_READ` | 查看来源消息原文和媒体 URL |
| `SOURCE_MESSAGE_ORIGINAL_READ` | 查看来源消息原文和媒体 URL;必须叠加 `SOURCE_MESSAGE_READ` 使用 |
| `RESERVATION_ORDER_READ` | 查看订单 |
| `RESERVATION_TASK_READ` | 查看任务 |
| `RESERVATION_TASK_EDIT` | 保存任务草稿 |
@@ -289,7 +289,7 @@ platform.security
中文说明:
- `SYSTEM_ADMIN` 用于系统初始化和调试能力,第一版可访问所有启用酒店。
- `RESERVATION_OPERATOR` 需要查看邮件原文和附件外链来处理任务,因此第一版包含 `SOURCE_MESSAGE_ORIGINAL_READ`
- `RESERVATION_OPERATOR` 需要查看邮件原文和附件外链来处理任务,因此第一版同时包含 `SOURCE_MESSAGE_READ` `SOURCE_MESSAGE_ORIGINAL_READ`
- `RESERVATION_VIEWER` 只读查看订单、任务、审计和来源消息安全摘要;不允许保存、确认、执行 OPERA 模拟,也不允许访问 Debug EML。
- `SYSTEM_DEBUG_EML_RUN` 第一版只授予 `SYSTEM_ADMIN`,避免普通业务用户触发 SuperAgent 调试链路。
- 启动初始化会按上表同步内置角色权限矩阵:矩阵中新增的权限会补齐,矩阵中移除的旧关系会清理。后续如果管理后台允许人工改内置角色,需要先重新确认“代码矩阵”和“后台配置”的优先级。
@@ -477,9 +477,9 @@ Authorization: Bearer <access_token>
后续强制鉴权时应按接口分批启用:
1. 查询类接口先要求登录和酒店权限。
1. 查询类接口先要求登录和酒店权限。已完成Reservation / SourceMessage 第一批只读查询。
2. 写操作再要求具体操作权限。
3. 邮件原文读取迁移到 `SOURCE_MESSAGE_ORIGINAL_READ`
3. 邮件原文读取迁移到 `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ`。已完成:`/api/source-messages/{id}/original``/api/source-messages/{id}/conversation`
4. OPERA 模拟迁移到 `RESERVATION_OPERA_SIM_EXECUTE`
5. 审计查询迁移到 `RESERVATION_AUDIT_READ`
@@ -519,7 +519,7 @@ Authorization: Bearer <access_token>
| 用户最终确认任务 | 有 token 时记录当前用户;无 token 时继续兼容本地占位 |
| Fallback 转换 | 有 token 时记录当前用户 |
| OPERA 模拟执行 / 重试 | 有 token 时记录当前用户 |
| 邮件原文读取 | 后续从 access-key 迁移到 `SOURCE_MESSAGE_ORIGINAL_READ` 权限 |
| 邮件原文读取 | 从 access-key 迁移到 `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ` 权限,并记录当前登录用户稳定 ID |
第一期不强制改完所有业务审计 actor但需要提供可复用的当前用户上下文接口。
@@ -602,7 +602,7 @@ AUTH_TEST_SESSION_TTL_MINUTES=720
- Reservation 查询接口校验登录和酒店权限。
- Reservation 写接口校验具体权限。
- SourceMessage 原文读取迁移到 `SOURCE_MESSAGE_ORIGINAL_READ`
- SourceMessage 原文读取迁移到 `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ`已完成 CP2后续保持回归。
- 审计 actor 全面迁移到当前用户。
### CP4管理后台接口

View File

@@ -840,7 +840,7 @@ GET /api/admin/audits
- Reservation 查询接口强制登录和酒店权限。
- Reservation 写接口强制具体操作权限。
- SourceMessage 原文读取迁移到 `SOURCE_MESSAGE_ORIGINAL_READ`
- SourceMessage 原文读取迁移到 `SOURCE_MESSAGE_READ` + `SOURCE_MESSAGE_ORIGINAL_READ`。已通过接口权限与酒店隔离收口 CP2 完成
- 业务审计 actor 全面迁移到当前用户。
该阶段和 M003 CP3、M005 酒店上下文统一收口有关,建议单独拆文档和任务。