微信小程序页面迁移校验之前 P5任务处理之前

docs/prd/specs/P5.1-mcp-server-ai-extension.md

@@ -0,0 +1,100 @@
+# P5.1：MCP Server AI 扩展 — mcp-server-ai-extension
+
+> 优先级：P5.1（分批执行，见下方阶段说明）
+> 预估工作量：中等
+> 前置条件：ETL 数据全景文档 ✅ 已完成（`docs/reports/DWD-DOC/`，2026-03-06）、P5 AI 集成层 spec 确定
+
+---
+
+## 分批执行策略（2026-03-07 评审决定）
+
+P5.1 的任务按依赖成熟度分三批：
+
+### 批次 A：立即可执行（无前置依赖）
+- T4：重写 MCP 查库手册 — ETL 库部分（DWD-DOC 已完成，DWS 34 张表全字段）
+
+### 批次 B：P5-A 之后（需 biz 表存在）
+- T1：MCP Server 新增 `zqyy_app` 数据库连接池
+- T2：扩展 MCP 工具支持多数据库路由
+- T3：实现 `zqyy_app` 敏感字段脱敏策略
+- T5：重写 MCP 查库手册 — 业务库部分（auth/biz/public 全字段）
+- T6：补充常用查询模式
+
+### 批次 C：批次 B 完成后
+- T7：手册上传百炼平台并验证 AI 应用引用效果
+
+---
+
+## 需求（Requirements）
+
+### 用户故事
+
+1. 作为 AI 应用（应用 1 通用对话），我需要通过 MCP 工具查询 `etl_feiqiu` 数据仓库，获取会员、订单、助教、财务等运营数据。
+2. 作为 AI 应用（应用 1 通用对话），我需要通过 MCP 工具查询 `zqyy_app` 业务库，获取备注、任务、维客线索、AI 缓存等业务数据。
+3. 作为系统，MCP Server 需要提供完整的数据库查询手册，供百炼平台 AI 应用作为知识库引用。
+
+### 验收标准
+
+- AC1：MCP Server 支持同时连接 `etl_feiqiu`（ETL 六层 Schema）和 `zqyy_app`（auth/biz/public Schema）
+- AC2：`zqyy_app` 连接仅允许只读查询（SELECT），与 `etl_feiqiu` 相同的安全限制
+- AC3：MCP 查库手册覆盖所有可查询表的完整字段说明（每张表列出全部字段）
+- AC4：手册上传百炼平台后，AI 应用可直接参考手册进行查询，无需频繁调用 describe_table
+
+---
+
+## 设计要点
+
+### MCP Server 扩展
+
+当前 MCP Server（`apps/mcp-server/`）仅连接 `etl_feiqiu` 库。需要扩展：
+
+1. **新增 `zqyy_app` 数据库连接**
+   - 使用 `APP_DB_DSN` 环境变量（已在根 `.env` 定义）
+   - 只读连接，与 `etl_feiqiu` 相同的安全策略
+   - 可访问 Schema：`auth`、`biz`、`public`
+
+2. **工具扩展**
+   - 现有 4 个工具（list_tables、describe_table、describe_schemas、query_sql）需支持指定目标数据库
+   - 新增参数 `database`（可选，默认 `etl_feiqiu`，可选 `zqyy_app`）
+   - 或通过 schema 名称自动路由（`ods/dwd/dws/core/meta/app` → etl_feiqiu，`auth/biz/public` → zqyy_app）
+
+3. **权限控制**
+   - `zqyy_app` 的 `auth` schema 中敏感字段（如 `wx_openid`、`phone`）需要在查询结果中脱敏或限制访问
+   - `biz` schema 的 `ai_messages.content` 字段包含对话内容，需考虑隐私保护
+
+### MCP 查库手册重写
+
+当前手册：`docs/mcp/AI-DATABASE-QUERY-MANUAL.md`
+
+> **数据字段权威参考**：手册中涉及的 DWD/DWS 层字段来源、金额口径、业务逻辑，
+> 以 `docs/reports/DWD-DOC/` 校准文档为准（数据快照 2026-03-06）。
+> 核心规则：
+> - `consume_money` 存在三种历史口径混合，不可直接使用；应使用 `items_sum`（= table_charge_money + goods_money + assistant_pd_money + assistant_cx_money + electricity_money）
+> - 收入结构拆分为台桌费、陪打费、超休费、商品费、电费五项，不使用笼统的 `service_fee`
+> - settle_type 映射：1=台桌结账(78.6%)、3=商城订单(21.4%)、5=充值、7=充值退款、6=结算退款
+> - 详见 [consume_money 口径说明](../reports/DWD-DOC/consume/consume-money-caliber.md)、[财务全景](../reports/DWD-DOC/03-financial-panorama.md)、[业务全景](../reports/DWD-DOC/01-business-panorama.md)
+
+重写范围：
+- **保留**：架构流程、六层 Schema 概览、4 个 MCP 工具详解
+- **补充**：DWS 层完整表清单（34 张表按业务域分组，每表全部字段）
+- **新增**：`zqyy_app` 业务库表结构（biz.notes、biz.coach_tasks、biz.member_retention_clue、biz.ai_cache 等）
+- **新增**：常用查询模式（维客线索、任务系统、备注、AI 缓存）
+- **新增**：金额口径说明章节（consume_money 不可用、items_sum 定义、settle_type 映射表）
+- **优化**：补充表的最新数据量统计、查询性能建议
+
+---
+
+## 任务清单
+
+### 批次 A — 立即可执行
+- [ ] T4：重写 MCP 查库手册 — ETL 库部分（DWD/DWS 全字段，基于 DWD-DOC 标杆文档）
+
+### 批次 B — P5-A 之后（依赖 P1 + P4 + P5-A，biz 表已建）
+- [ ] T1：MCP Server 新增 `zqyy_app` 数据库连接池（使用 `APP_DB_DSN`）
+- [ ] T2：扩展 MCP 工具支持多数据库路由（按 schema 名称自动选择连接）
+- [ ] T3：实现 `zqyy_app` 敏感字段脱敏策略
+- [ ] T5：重写 MCP 查库手册 — 业务库部分（auth/biz/public 全字段）
+- [ ] T6：补充常用查询模式（维客线索、任务、备注、AI 缓存）
+
+### 批次 C — 批次 B 完成后
+- [ ] T7：手册上传百炼平台并验证 AI 应用引用效果