# 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（改返回字段名） | ⚠️ 改返回结构，需评估 |

---

## 四、结论

1. **核心价值已落地**：`actual_signed_summary` 聚合、签单口径统一、stage 字典校验、total/hasMore、字段注释（fieldDescriptions）均已满足，Agent "1~2 次调用出数"的目标基本达成。
2. **最大缺口集中在 `crm_opportunity_search` 的过滤/排序/投影增强（C2/C3/C5）**：这是让 LLM 少拉数据、精准取数的关键，且**全部为兼容式新增、不动现有逻辑**，风险最低。
3. **批量详情（D）**：可做成可选 `ids` 分支，保留现有单 `id` 路径，兼容。
4. **P2 一致性项（G 系列）多为"新增分支/新增防御"**，不改合法调用结果，但会改变非法输入或返回结构的形态，建议按需逐个评估，避免一次全做引入回归。

---

## 五、后续落地建议（按优先级，均不动现有逻辑）

**第一批（推荐，P0 + 低风险）：**
1. `crm_opportunity_search` 补齐 `stageIn`/日期区间/金额区间/`hasActualSignedAmount` 过滤 → 减少 Agent 拉取量
2. 增白名单 `sort` 排序 → 让 Agent 直接取 Top N
3. 增可选 `fields` 投影 → 控制返回体，避免上下文膨胀
4. `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+ 条测试不回退。

---

*本报告为只读审计结果，未对任何现有代码/数据库做修改。字段转载与口径说明如需进一步细化，欢迎在此基础上继续。*