再次提交一下代码

2026-07-17 13:13:47 +07:00
parent f4d86248d4
commit 980a3a2535
41 changed files with 1699 additions and 187 deletions
--- a/docs/project/README.md
+++ b/docs/project/README.md
@@ -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 时间，页面再按酒店或用户时区展示。
--- a/docs/project/ai-native-adoption.md
+++ b/docs/project/ai-native-adoption.md
@@ -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` 中的当前有效文档为准；如果仍有冲突，再向用户确认。
--- a/docs/project/backend-development-guidelines.md
+++ b/docs/project/backend-development-guidelines.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 自带继承方法强行加无意义注释？
--- a/docs/project/frontend-backend/frontend-to-backend-api-requests.md
+++ b/docs/project/frontend-backend/frontend-to-backend-api-requests.md
@@ -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 服务，暂不做额外拦截或代理转换。

--- a/docs/project/integrations/superagent-agentbus-project-integration-guide.md
+++ b/docs/project/integrations/superagent-agentbus-project-integration-guide.md
@@ -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
--- a/docs/project/requirements/M001-source-message-inbox-prd.md
+++ b/docs/project/requirements/M001-source-message-inbox-prd.md
@@ -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
--- a/docs/project/requirements/M003-identity-access-hotel-menu-v1.md
+++ b/docs/project/requirements/M003-identity-access-hotel-menu-v1.md
@@ -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：管理后台接口
--- a/docs/project/requirements/M006-system-admin-management-console-v1.md
+++ b/docs/project/requirements/M006-system-admin-management-console-v1.md
@@ -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 酒店上下文统一收口有关，建议单独拆文档和任务。