再次提交一下代码
This commit is contained in:
@@ -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` 和项目文档索引。
|
||||
- 当前项目专属业务规则是否已经放在项目自己的文档目录,而不是混入本目录。
|
||||
|
||||
276
docs/import/reusable/ai-native-software-engineering-standard.md
Normal file
276
docs/import/reusable/ai-native-software-engineering-standard.md
Normal 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。
|
||||
|
||||
它描述的是软件工程,不是某个具体工具。
|
||||
40
docs/import/reusable/ai-native-templates/ADR.template.md
Normal file
40
docs/import/reusable/ai-native-templates/ADR.template.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# ADR-编号 标题
|
||||
|
||||
| 项 | 内容 |
|
||||
| --- | --- |
|
||||
| 状态 | Proposed / Accepted / Superseded |
|
||||
| 日期 | YYYY-MM-DD |
|
||||
| 决策人 | 按实际填写 |
|
||||
|
||||
## 1. 背景
|
||||
|
||||
说明为什么需要做这个决策。
|
||||
|
||||
## 2. 约束
|
||||
|
||||
- 约束 1:
|
||||
- 约束 2:
|
||||
|
||||
## 3. 备选方案
|
||||
|
||||
### 方案 A
|
||||
|
||||
说明优点和缺点。
|
||||
|
||||
### 方案 B
|
||||
|
||||
说明优点和缺点。
|
||||
|
||||
## 4. 最终选择
|
||||
|
||||
说明最终选择哪个方案。
|
||||
|
||||
## 5. 影响
|
||||
|
||||
- 正面影响:
|
||||
- 负面影响:
|
||||
- 后续动作:
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
ADR 只追加,不覆盖历史。如果未来决策变化,新建 ADR 或标记被替代。
|
||||
39
docs/import/reusable/ai-native-templates/AGENTS.template.md
Normal file
39
docs/import/reusable/ai-native-templates/AGENTS.template.md
Normal 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. 测试与验证
|
||||
|
||||
- 修改后运行对应模块已有检查命令。
|
||||
- 如果检查命令尚未配置或因环境问题无法运行,必须明确说明原因。
|
||||
- 不假装测试通过。
|
||||
@@ -0,0 +1,31 @@
|
||||
# 架构说明
|
||||
|
||||
## 1. 系统目标
|
||||
|
||||
说明系统架构服务的产品目标和主要约束。
|
||||
|
||||
## 2. 模块边界
|
||||
|
||||
| 模块 | 职责 | 不负责 |
|
||||
| --- | --- | --- |
|
||||
| | | |
|
||||
|
||||
## 3. 依赖方向
|
||||
|
||||
说明模块之间的依赖方向,避免双向依赖和跨层直连。
|
||||
|
||||
## 4. 数据边界
|
||||
|
||||
说明数据库、缓存、文件存储、消息队列和外部系统的数据边界。
|
||||
|
||||
## 5. 安全边界
|
||||
|
||||
说明鉴权、授权、租户隔离、审计和敏感数据处理方式。
|
||||
|
||||
## 6. 关键决策
|
||||
|
||||
列出相关 ADR 链接。
|
||||
|
||||
## 7. 演进计划
|
||||
|
||||
说明后续可能调整的方向和触发条件。
|
||||
50
docs/import/reusable/ai-native-templates/CONTEXT.template.md
Normal file
50
docs/import/reusable/ai-native-templates/CONTEXT.template.md
Normal 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
|
||||
@@ -0,0 +1,27 @@
|
||||
# 业务对象名称
|
||||
|
||||
## 1. 定义
|
||||
|
||||
说明这个业务对象是什么,不是什么。
|
||||
|
||||
## 2. 生命周期
|
||||
|
||||
说明对象从创建到结束的主要状态。
|
||||
|
||||
## 3. 业务规则
|
||||
|
||||
- 规则 1:
|
||||
- 规则 2:
|
||||
- 规则 3:
|
||||
|
||||
## 4. 关系
|
||||
|
||||
说明它和其他业务对象的关系。
|
||||
|
||||
## 5. 禁止混淆
|
||||
|
||||
列出容易和它混淆的概念。
|
||||
|
||||
## 6. 非目标
|
||||
|
||||
说明本文不记录实现细节、表结构或接口字段。实现细节应放在 Architecture、Spec 或代码中。
|
||||
@@ -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 是否需要更新。
|
||||
21
docs/import/reusable/ai-native-templates/README.md
Normal file
21
docs/import/reusable/ai-native-templates/README.md
Normal 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`:架构说明模板。
|
||||
49
docs/import/reusable/ai-native-templates/SPEC.template.md
Normal file
49
docs/import/reusable/ai-native-templates/SPEC.template.md
Normal 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 是否需要更新。
|
||||
@@ -0,0 +1,37 @@
|
||||
# 业务流程名称
|
||||
|
||||
## 1. 目标
|
||||
|
||||
说明这个流程要完成什么业务目标。
|
||||
|
||||
## 2. 触发条件
|
||||
|
||||
说明流程从哪里开始。
|
||||
|
||||
## 3. 输入
|
||||
|
||||
| 输入 | 中文说明 | 来源 |
|
||||
| --- | --- | --- |
|
||||
| | | |
|
||||
|
||||
## 4. 输出
|
||||
|
||||
| 输出 | 中文说明 | 去向 |
|
||||
| --- | --- | --- |
|
||||
| | | |
|
||||
|
||||
## 5. 正常流程
|
||||
|
||||
1. 步骤一。
|
||||
2. 步骤二。
|
||||
3. 步骤三。
|
||||
|
||||
## 6. 异常与补偿
|
||||
|
||||
- 异常:
|
||||
- 补偿:
|
||||
- 审计:
|
||||
|
||||
## 7. 边界
|
||||
|
||||
说明哪些事情属于本流程,哪些事情不属于本流程。
|
||||
@@ -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 时间,页面再按酒店或用户时区展示。
|
||||
|
||||
80
docs/project/ai-native-adoption.md
Normal file
80
docs/project/ai-native-adoption.md
Normal 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` 中的当前有效文档为准;如果仍有冲突,再向用户确认。
|
||||
@@ -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 自带继承方法强行加无意义注释?
|
||||
|
||||
@@ -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 服务,暂不做额外拦截或代理转换。
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`。
|
||||
- Risk:HTML 原文直接渲染带来安全问题。
|
||||
@@ -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
|
||||
|
||||
@@ -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:管理后台接口
|
||||
|
||||
@@ -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 酒店上下文统一收口有关,建议单独拆文档和任务。
|
||||
|
||||
Reference in New Issue
Block a user