8.0 KiB
8.0 KiB
MCP 接口审计报告与整改建议
审计日期：2026-09-16 审计范围：
backend/src/main/java/com/unis/crm/llm/及backend/src/main/resources/mapper/llm/LlmMcpMapper.xml约束：本次审计不修改任何现有逻辑，仅只读核验，输出缺失项与可整改项清单。 基线：对照~/Downloads/scc_mcp_improvement_proposal.md的 A-G 改造项及 6 条验收用例。
一、工具清单（当前暴露给 Agent 的 MCP 工具）
| 工具名 | 作用 | 备注 |
|---|---|---|
crm_opportunity_search |
商机明细列表 | 分页 + total/hasMore |
crm_customer_search |
客户明细列表 | 分页 + total/hasMore |
crm_work_report_search |
日报列表 | 分页 + total/hasMore |
crm_checkin_search |
外勤打卡列表 | 分页 + total/hasMore |
crm_todo_search |
待办列表 | 分页 + total/hasMore |
crm_followup_search |
跟进记录列表 | 分页 + total/hasMore |
crm_expansion_search |
拓客（销售/渠道）列表 | 分页 + total/hasMore |
crm_universal_search |
跨模块通用搜索 | 无 total，定位用 |
crm_entity_detail |
单对象详情 | 仅单 id |
crm_dict_options |
字典选项查询 | 补齐工作职责等 |
crm_metadata_catalog |
元数据目录 | 硬编码 |
crm_report_query |
报表查询 | 多 reportType 聚合 |
crm_report_catalog |
报表目录 | |
crm_org_user_search |
组织/用户查询 | 姓名→ID 映射 |
crm_user_profile |
当前用户资料 |
说明：以上所有列表工具均已统一 total+hasMore 分页字段（既有汇总已落地）。
二、已满足项（核验通过）
| 项 | 状态 | 证据 |
|---|---|---|
A actual_signed_summary 实际签约聚合 |
✅ 完整 | CrmReportQueryToolProvider L233-266：按 stage='S5'+archived_at∈区间+actual_signed_amount，含 definition/dataQuality(s5MissingArchivedAt/s5MissingSignedAmount)/realizationRate，groupBy 支持 none/month/owner/product/source/province |
B sales_performance 签单口径 |
✅ | LlmMcpMapper.xml L891-900：wonCount/wonAmount 按 S5+archived_at+actual_signed_amount |
B opportunity_trend 输赢口径 |
✅ | L961-976：won 按 S5、lost 按 L |
| C1 stage 字典联动校验 | ✅ | OpportunitySearchToolProvider validateStage：非法值报错+合法枚举提示 |
| C4 列表补齐签约字段 | ✅ | LlmMcpMapper.xml L149-154：返回 actualSignedAmount/archivedAt |
| G dashboard_summary 权限 | ✅ | 独立 STATS_PERMISSION 校验 |
| 数据权限注入 | ✅ | 拦截器+指针测试兜底 |
三、缺失项清单（含可整改性评估）
约束说明：以下"可整改性"均在不动现有业务逻辑前提下评估——
- 兼容式新增：默认值=原行为，不影响现有调用，可直接做。
- 低风险扩展：新增参数/字段，对既有合法调用无副作用，可直接做。
- 需谨慎：会改变现有调用返回形态或异常路径，若不做适配会改变行为，需评估。
P0（直接影响"少拉数据、精准取数"，单文件、低风险）
| # | 缺失项 | 现状 | 整改建议 | 可整改性 |
|---|---|---|---|---|
| C2-1 | 多阶段过滤 stageIn |
仅单值 stage = #{stage} |
schema 增 stageIn（多值），SQL 改 in (...)，默认 null 不生效 |
✅ 兼容式新增 |
| C2-2 | 日期区间 archivedFrom/To |
无 | 增字段，SQL 加区间条件，默认 null 不生效 | ✅ 兼容式新增 |
| C2-3 | 日期区间 createdFrom/To |
无 | 同上 | ✅ 兼容式新增 |
| C2-4 | 金额区间 minAmount/maxAmount |
无 | 同上 | ✅ 兼容式新增 |
| C2-5 | 布尔 hasActualSignedAmount |
无 | 增字段，SQL 判 actual_signed_amount is not null，默认 null 不生效 |
✅ 兼容式新增 |
| C3 | 排序 sort（如 -actual_signed_amount） |
无 ORDER BY 口子 | 增白名单 sort 参数，默认 null=现有顺序不动 | ✅ 兼容式新增 |
| C5 | 字段投影 fields + description 截断 |
全列返回 | 增可选 fields（默认 null=全列，兼容）；description 截断建议 120 |
✅ 兼容式新增 |
| D | crm_entity_detail 批量 ids |
仅单 id，返回 found/detail |
增可选 ids 分支，保留单 id 路径不动，回应 found/rows |
✅ 兼容式新增 |
P1（体验/口径自描述，改动较小）
| # | 缺失项 | 现状 | 整改建议 | 可整改性 |
|---|---|---|---|---|
| B-caliber | sales_performance/opportunity_trend 响应无口径说明 |
无 caliber 节点 |
响应层新增 caliber 字段说明各指标口径（不改数据） |
✅ 低风险扩展 |
| E-1 | crm_metadata_catalog 硬编码 8 字段 |
缺 actualSignedAmount/archivedAt 说明 | 新增字段条目+中文+口径说明 | ✅ 低风险扩展 |
| E-2 | crm_dict_options 未回写"被哪些字段使用" |
无使用方信息 | 新增 usage 说明 | ✅ 低风险扩展 |
| F | 归档转 S5 必填校验 | 业务侧未强制 archived_at/actual_signed_amount | 业务侧（非 MCP 模块）校验 | ⚠️ 需谨慎，改业务逻辑 |
P2（一致性与报错策略，改动会改变现有行为，需评估）
| # | 缺失项 | 现状 | 整改建议 | 可整改性 |
|---|---|---|---|---|
| G-1 | groupBy 无校验，非法值静默降级 |
sales_performance 传 month 无感透传 |
增参数白名单校验，非法值报错（新增防御，不改合法调用） | ⚠️ 只改异常路径，合法调用不变 |
| G-2 | customer_summary groupBy=month 未实现 |
落到 industry | 增 month 分支（新增语义） | ⚠️ 新增分支，不改现有分支 |
| G-3 | daily_report_completion groupBy=month 未实现 |
month 静默按日返回(250+行) | 增 month 分支 | ⚠️ 新增分支 |
| G-4 | universal_search 商机行非结构化 |
仍拼接 summary 字符串 | 增独立 actualSignedAmount/archivedAt（新增字段，改返回结构） | ⚠️ 会改通用搜索返回形态，需评估 |
| G-5 | crm_entity_detail 命名混用 |
o.* snake + 别名 camel |
统一 camelCase（改返回字段名） | ⚠️ 改返回结构，需评估 |
四、结论
- 核心价值已落地：
actual_signed_summary聚合、签单口径统一、stage 字典校验、total/hasMore、字段注释（fieldDescriptions）均已满足，Agent "1~2 次调用出数"的目标基本达成。 - 最大缺口集中在
crm_opportunity_search的过滤/排序/投影增强（C2/C3/C5）：这是让 LLM 少拉数据、精准取数的关键，且全部为兼容式新增、不动现有逻辑，风险最低。 - 批量详情（D）：可做成可选
ids分支，保留现有单id路径，兼容。 - P2 一致性项（G 系列）多为"新增分支/新增防御"，不改合法调用结果，但会改变非法输入或返回结构的形态，建议按需逐个评估，避免一次全做引入回归。
五、后续落地建议（按优先级，均不动现有逻辑）
第一批（推荐，P0 + 低风险）：
crm_opportunity_search补齐stageIn/日期区间/金额区间/hasActualSignedAmount过滤 → 减少 Agent 拉取量- 增白名单
sort排序 → 让 Agent 直接取 Top N - 增可选
fields投影 → 控制返回体，避免上下文膨胀 crm_entity_detail增ids批量分支（保留单 id）→ 详情 N 次调用压成 1 次
第二批（P1，口径自描述）：
5. sales_performance/opportunity_trend 响应增 caliber 口径字段
6. crm_metadata_catalog 增 actualSignedAmount/archivedAt 及中文说明
第三批（P2，需逐个评估，改动会触及现有行为边界）：
7. groupBy 白名单校验（非法值报错）
8. customer_summary/daily_report_completion 增 month 分支
9. universal_search 商机结构化为独立字段（改返回形态）
10. 归档必填校验（业务侧，非 MCP 模块）
每一项落地前都应补对应单测，并确认既有 132+ 条测试不回退。
本报告为只读审计结果，未对任何现有代码/数据库做修改。字段转载与口径说明如需进一步细化，欢迎在此基础上继续。