# 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 应用引用效果