docs(P19AI1-4,P19AI1-5): 收口AI-1文档矩阵与执行合同

docs/integration-boundaries.md

@@ -1,7 +1,7 @@
-# 集成边界冻结（P19 / P19+IM-1 / P19+ERP-3 / R10）
+# 集成边界冻结（P19 / P19+IM-1 / P19+ERP-3 / R10 / P19+MCP-1 / P19+AI-1）
 
-**快照日期**：2026-03-09
-**当前基线**：`P19+IM-1`、`P19+ERP-1`、`P19+ERP-2` 与 `P19+ERP-3` 已完成；当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配，以及 ERP 主数据 Pull、报销付款凭证切片、采购双阶段 journal / 归档摘要出站、资产台账摘要出站。
+**快照日期**：2026-03-10
+**当前基线**：`P19+IM-1`、`P19+ERP-1`、`P19+ERP-2`、`P19+ERP-3`、`P19+MCP-1` 与 `P19+AI-1` 已完成；当前运行时已落地企微群机器人 + 深链 + Outbox 异步派发的一期协同适配，以及 ERP 主数据 Pull、报销付款凭证切片、采购双阶段 journal / 归档摘要出站、资产台账摘要出站、Postgres MCP 只读工具基线与报销 / 采购 / 资产详情页 AI 只读建议挂件。
 **目标**：在保持核心域稳定的前提下，冻结 ERP / IM / AI / MCP 的长期边界，并记录 IM 一期与 ERP 三期的已实现范围、禁入规则以及 R10 之后的固定主线顺序。
 
 ## 1. 总体原则
@@ -134,6 +134,14 @@
 - 禁止 AI 自动创建、审批、归档业务单据。
 - 禁止 AI 直接修改预算、工作流、资产归属等核心状态。
 
+### 4.4 P19+AI-1 已实现范围
+- 已新增 `GET /api/ai/status` 与三条详情建议接口：`/api/ai/suggestions/reimbursements/:id`、`/api/ai/suggestions/purchase-requests/:id`、`/api/ai/suggestions/assets/:id`。
+- 已新增 `ai.assist` 权限、`ai_assist` feature flag 与 `AI_ASSIST_ENABLED / AI_PROVIDER / AI_BASE_URL / AI_MODEL / AI_TIMEOUT_MS / AI_AUTH_TOKEN` 环境变量；默认仍保持关闭。
+- 已固定 AI 运行时只支持同步只读建议层，不新增 Prisma 表、不使用 Outbox、不接入 MCP 运行时，也不持久化 AI 历史结果。
+- 已固定只读白名单快照：报销不暴露发票号码、付款凭证、姓名工号与明细原文；采购不暴露申请人个人信息、附件原名、长文本 reason 与外部 ERP 编号；资产不暴露 assignee 身份信息与外部 ERP 编号。
+- 已在报销详情、采购详情、资产详情挂载 AI 建议卡片；当权限不足、总闸关闭、feature flag 未命中、上游超时或响应非法时，仅在卡片内降级展示，不影响主体页面渲染与业务动作。
+- 已固定审计动作 `AI_SUGGESTION_REQUESTED`，仅记录 `targetType / targetId / provider / model / promptHash / tokenUsage / featureFlag`，不记录原始 prompt、脱敏前 payload 或上游全文。
+
 ## 5. 事件与通知交付规范
 
 ### 5.1 事件最小结构
@@ -160,25 +168,27 @@
 
 ## 6. MCP 基线
 
-### 6.1 当前结论
-- `P19+IM-1` 阶段 **不启用 MCP**。
-- 当前仓库中 **仍不创建** `docs/mcp-tools.md`，因为尚未进入真实 MCP 使用场景。
+### 6.1 P19+MCP-1 已实现范围
+- 已新增 `docs/mcp-tools.md`，作为项目级 MCP 工具目录与使用边界事实源。
+- 已新增 `.mcp.json.example`，仅提供 `postgres` 只读示例配置，不提交任何真实密钥、PAT 或数据库连接串。
+- 已新增 `scripts/validate-mcp-tools.py`，用于校验工具目录、示例配置与 `AGENTS.md` 引用关系。
+- 已明确当前 shell 中 `codex mcp list --json` 不可作为唯一事实源，因此工具目录固定以官方 package 文档、执行合同与仓库校验脚本共同收口。
 
-### 6.2 首次启用前置条件
-若未来需要启用 MCP，固定顺序如下：
-1. 明确真实用途（数据库只读排障、GitHub PR / Issue / CI 协作等）
-2. 新增 `docs/mcp-tools.md`
-3. 使用 `mcp-tools-catalog` 生成工具目录
-4. 在执行合同中记录启用原因、风险与禁用边界
+### 6.2 当前允许的 MCP 范围
+- `postgres MCP`：当前唯一允许启用的 MCP server，用于只读排障、迁移核对、账本核对。
+- `postgres:query`：固定用于只读 SQL 查询；所有查询必须处于 `READ ONLY` 事务语义下。
+- schema resources：允许读取表结构、字段类型与 schema 元数据，不得反向修改业务数据。
 
-### 6.3 允许的 MCP 范围
-- `postgres MCP`：只读排障、迁移核对、账本核对
-- `github MCP`：PR / Issue / CI 协作
+### 6.3 Deferred candidate
+- `github MCP`：当前仅记录为 deferred candidate，不纳入 enabled servers。
+- 原因：官方 GitHub MCP server 当前暴露读写混合工具集，不满足 `Read-only Tools Baseline`。
+- 若未来需要启用，必须通过新的路线合同显式解锁，并单独治理最小权限 PAT、读写边界与回滚策略。
 
 ### 6.4 禁止事项
+- 禁止提交真实 `.mcp.json`、真实数据库连接串、PAT、API Token 或其他密钥。
 - 禁止在没有 `docs/mcp-tools.md` 的前提下默认启用 MCP。
 - 禁止用 MCP 绕过仓库内已存在的本地验证命令。
-- 禁止将 MCP 用作写生产数据的通道。
+- 禁止将 MCP 用作写生产数据或修改业务状态的通道。
 
 ## 7. 当前阶段明确不做
 - 不新增新的集成总线表结构
@@ -195,9 +205,10 @@
 - 每个 phase 固定遵循：`执行合同 CSV -> 方案批准 -> 开发 -> 测试 -> 文档矩阵收口 -> 合并 main`。
 
 ### 8.2 MCP / AI 前置关系
-- `P19+MCP-1` 是首次真实启用 MCP 的唯一前置 phase；在其完成前，`docs/mcp-tools.md` 仍不得作为已存在事实源引用。
-- `P19+AI-1` 固定在 `P19+MCP-1` 之后启动，继续遵守“AI 只做建议，不直接写库”的硬边界。
-- AI 一期只覆盖采购、报销、资产详情的只读建议工作台，不开放自由聊天、自动审批或 agent 自治。
+- `P19+MCP-1` 已完成，并已把 `docs/mcp-tools.md`、`.mcp.json.example` 与 MCP 校验脚本固化为仓库治理基线。
+- 当前唯一允许启用的 MCP server 为 `postgres`；`github` 继续保持 deferred，不进入 enabled servers。
+- `P19+AI-1` 已在 `P19+MCP-1` 之后完成落地，并继续遵守“AI 只做建议，不直接写库”的硬边界。
+- 当前 AI 一期已覆盖采购、报销、资产详情的只读建议工作台；自由聊天、自动审批与 agent 自治仍明确不做。
 
 ### 8.3 差旅统付主线
 - `P20+TRAVEL-1` 固定负责差旅申请、行程段与 `travel_orders` 入站整合，作为对公统付的前置主数据与流程基线。