root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
Neo-ZQYY/docs/prd/specs/P5.1-mcp-server-ai-extension.md

5.0 KiB
Raw Permalink Blame History

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 口径说明、财务全景、业务全景

重写范围：

  • 保留：架构流程、六层 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 应用引用效果
Reference in New Issue View Git Blame Copy Permalink