unis_crm/MCP字段覆盖清单.md

# MCP 字段覆盖清单

> 说明：本文档用于核对 MCP 接口对数据库字段的覆盖情况，帮助判断是否"已包含全部字段"、缺失了哪些表与字段。
>
> **数据来源**：
> - MCP SQL 查询定义：`backend/src/main/resources/mapper/llm/LlmMcpMapper.xml`（共 77 个查询）
> - MCP 工具描述 / 字段中文映射：`backend/src/main/java/com/unis/crm/llm/tools/`（各 `*ToolProvider.java`）
> - 字段注释映射：`backend/src/main/java/com/unis/crm/llm/tools/support/FieldCommentRegistry.java`
> - 表字段依据：`sql/archive/alter_fill_column_comments_pg17.sql` + 运行时 `*SchemaInitializer` 增量列

---

## 核心结论

**未完全包含全部字段。**但缺口主要集中在**子表实体**和**列表搜索层**，MCP 对**核心业务主表**覆盖较完整（所有 detail 查询使用 `表.*` 返回主表全字段兜底）。

### 关键机制
所有 `xxxDetail` 查询（如 `selectOpportunityDetail`、`selectCustomerDetail`、`selectWorkReportDetail`、`selectCheckinDetail`、`selectSalesExpansionDetail`、`selectChannelExpansionDetail`、`selectCrmExpansionDetail`、`selectTodoDetail`）均使用 `表.*` **返回主表全部字段**。因此：
- 主表字段层面，**详情接口基本全覆盖**；
- 真正的字段缺口集中在 **search/list 列表查询** 以及 **子表实体（followup / contact / comment）**。

---

## A. 各 MCP 实体 → 主表 → 已暴露字段清单

### 1. 工作日报（表 `work_daily_report`）
`searchWorkReports`（XML 50-100）暴露：
> id、userId、userName、reportDate、submitTime、sourceType、status、workContent、tomorrowPlan、score、comment

表字段（alter_fill 194-204）：`id, user_id, report_date, work_content, tomorrow_plan, source_type, submit_time, status, score, created_at, updated_at`

Detail 用 `r.*` 全字段 + `userName / latestScore / latestComment / reviewedAt`。

### 2. 商机（表 `crm_opportunity`）
`searchOpportunities`（XML 132-218）暴露 27 个字段：
> id、opportunityCode、opportunityName、customerId、customerName、ownerUserId、ownerName、preSalesName、operatorName、projectLocation、projectOwnershipLocation、projectOwnershipLocationName、productType、opportunityType、source、isPoc、competitorName、amount、expectedCloseDate、confidence、stage、status、archived、latestProgress、nextPlan、description、actualSignedAmount、archivedAt、updatedAt

Detail 用 `o.*` 全字段 + `customerName / ownerName / followupCount / latestFollowup`。

### 3. 客户（表 `crm_customer`）
`searchCustomers`（XML 1415-1454）暴露：
> id、customerCode、customerName、customerType、industry、province、city、address、source、status、ownerUserId、ownerName、remark、updatedAt

Detail 用 `c.*` 全字段 + `ownerName`。

### 4. 签到（表 `work_checkin`）
`searchCheckins`（XML 1479-1514）暴露：
> id、userId、userName、deptName、checkinDate、checkinTime、bizType、bizId、bizName、locationText、remark、status

Detail 用 `c.*` 全字段 + `userNameResolved`。

### 5. 销售拓客（表 `crm_sales_expansion`）
`searchSalesExpansions`（XML 1619-1665）暴露：
> id、expansionType、name、employeeNo、candidateName、officeName、mobile、email、targetDept、industry、title、employmentStatus、expectedJoinDate、hasDesktopExp、summary、stage、intentLevel、ownerUserId、ownerName、remark、sortTime、updatedAt

Detail 用 `s.*` 全字段。

### 6. 渠道拓客（表 `crm_channel_expansion`）
`searchChannelExpansions`（XML 1689-1744）暴露：
> id、expansionType、name、channelCode、channelName、province、city、officeAddress、channelIndustry、certificationLevel、annualRevenue、staffSize、contactEstablishedDate、contactName、contactTitle、contactMobile、channelAttribute、internalAttribute、hasDesktopExp、expectedSignDate、landedFlag、summary、stage、intentLevel、ownerUserId、ownerName、remark、sortTime、updatedAt

Detail 用 `c.*` 全字段 + `contactCount / followupCount`。

**渠道联系人子表（`crm_channel_expansion_contact`）**：并非完全没有暴露，而是通过 `crm_entity_detail` 的 `channel_expansion` 详情**联查**返回（`CrmEntityDetailToolProvider.java:174` → `selectChannelExpansionContacts`，XML 2206）。返回字段有限：`id, contactName, contactMobile, contactTitle, sortOrder`（仅 5 个）。无独立搜索工具（不能批量查联系人）。字段缺漏见 C2。

### 7. CRM 拓展（表 `crm_crm_expansion`）
`searchCrmExpansions`（XML 1770-1817）暴露：
> id、endUser、officeName、industryAttr、extensionType、purchaseDate、warrantyExpiry、expansionTime、expansionScale、softwarePoints、onlineStatus、contactName、contactPhone、contactTitle、supplierName、h3cContactName、hasExpansionOpportunity、hasMaintenanceOpportunity、ownerUserId、ownerName、remark、sortTime、updatedAt

Detail 用 `ce.*` 全字段。

### 8. 待办（表 `work_todo`）— **全字段覆盖**
`searchTodos`（XML 1241-1279）暴露：
> id、title、bizType、bizId、priority、status、userId、userName、dueDate、createdAt、updatedAt

Detail 用 `t.*`。此表 **无字段缺失**。

### 9. 跟进（两表合并：`crm_opportunity_followup` + `crm_expansion_followup`）
- `searchFollowups`（XML 1841-1927）暴露公共列：
  > bizType、id、bizId、bizName、followupType、content、nextAction、userId、userName、followupTime
- `selectOpportunityFollowups`：id、followupType、content、nextAction、followupUserId、followupUserName、followupTime
- `selectSalesExpansionFollowups` / `selectChannelExpansionFollowups`：id、followupType、content、nextAction、evaluationContent、nextPlan、followupUserId、followupUserName、followupTime

### 10. 组织用户 / 组织 / 角色（表 `sys_user`、`sys_org`、`sys_role`）
- `searchOrgUsers`（XML 1303-1353）暴露：userId、username、displayName、mobile、email、status、orgIds、orgNames、roleCodes、roleNames
- `selectUserProfile`：userId、username、displayName、email、phone、status、platformAdmin、createdAt
- `searchOrganizations`：orgId、orgName、parentId、orgCode、sortOrder、status（**parentId/orgCode/sortOrder 恒为 null**）
- `searchRoles`：roleId、roleName、roleCode、status、userCount

`sys_user` 表字段：`id, user_id, user_code, username, real_name, display_name, mobile, phone, email, org_id, job_title, status, hire_date, avatar_url, password_hash, created_at, updated_at, is_deleted, pwd_reset_required, is_platform_admin`

### 11. 其他（非独立业务主表工具）
- **动态/活动日志** `sys_activity_log`：通过 `universalSearchActivities`（XML 798）通用搜索暴露 `id, title, summary, ownerUserId, ownerName, time`
- **字典**：`selectDictTypes`（2257）、`selectDictOptions`（2279）、`selectColumnComments`（2304）
- **渠道覆盖** `crm_channel_expansion_coverage`：聚合统计 `channelCoverageSummary`（2441）+ **渠道详情已联查 `coverages` 明细**
- **销售所属区域** `crm_sales_expansion_coverage`：**已通过 `crm_entity_detail`(sales_expansion) 联查 `coverages` 明细**
- **日报消息** `work_report_message`：**已通过 `crm_entity_detail`(daily_report) 联查 `messages` 明细**（sender/receiver/content/readAt 等）

---

## B. 缺失的表（数据库有数据，但 MCP 无实体/工具暴露）

| 缺失表 | 说明 | 位置 |
|---|---|---|
| `business_calendar_day` | 工作日历，**完全未暴露** | `sql/init_full_pg17.sql:778` |
| `report_reminder_*` | 日报提醒配置表，MCP 未引用 | `ReportReminderService` |
| `speech_recognition_config` | 语音识别配置表，MCP 未引用 | `SpeechRecognitionSchemaInitializer` |
| `dashboard_analytics_card_config` | 看板分析卡片配置表，MCP 未引用 | `DashboardAnalyticsSchemaInitializer` |
| 数据权限表（`20260701_user_data_scope_user_pg17.sql`） | 权限类，MCP 未暴露（**合理**） | `UserDataScopeSchemaInitializer` |

> 注：`sys_tenant_user`、`sys_user_role`、`cnarea`、`sys_dict_*` 为框架/字典/行政区划辅助表，仅被 join 使用，不算业务实体。核心业务实体（用户/客户/商机/拓客/打卡/日报/待办/跟进/组织/角色）均已覆盖。

---

## C. 缺失的字段

### C1. 主表（已补齐，search/list 层缺失字段）

> 详情接口用 `表.*` 已全覆盖。以下字段在**本轮已补进 search/list 查询**，供 Agent 查阅。

| 实体/表 | search 现返回的补齐字段 | 备注 |
|---|---|---|
| `work_daily_report` | `created_at, updated_at` | 审计字段 |
| `crm_opportunity` | `sales_expansion_id, channel_expansion_id, pre_sales_id, pushed_to_oms, oms_push_time, updated_by, created_at` | 外键 / OMS 集成 / 审计字段 |
| `crm_customer` | `created_at` | 审计字段 |
| `work_checkin` | `longitude, latitude, created_at, updated_at` | 经纬度已在列表返回 |
| `crm_sales_expansion` | `in_progress, created_at` | `in_progress`（是否持续跟进）已返回 |
| `crm_channel_expansion` | `industry`（兼容旧字段）, `registered_capital`, `created_at` | `registered_capital` 注册资金 |
| `crm_crm_expansion` | `supplier_id, h3c_contact_id, created_at` | 外键 / 审计字段（detail `ce.*` 覆盖） |
| `sys_user`（profile / org-user） | `user_code`(工号), `real_name`, `job_title`, `hire_date`, `display_name` | **已补工号/职位/入职日期/姓名**；`password_hash`、`pwd_reset_required` **仍不应暴露**（安全） |

> ⚠️ 待确认：`sys_org` 的 `parent_id / org_code / sort_order` 仍硬编码为 null，因 `sys_org` 属框架表、项目内**未找到建表脚本**，未擅自改动（`searchOrganizations`）。如需返回真实层级字段，需先人工核实 `sys_org` 列名。

### C2. 子表实体（已补齐，缺漏字段现已暴露）

| 子表 | 补齐后暴露的字段 | 说明 |
|---|---|---|
| `crm_expansion_followup` | `visit_start_time`（拜访开始时间）, `source_type`, `source_id`, `created_at`, `updated_at` | searchFollowups、sales/channel followups 均已补 |
| `crm_opportunity_followup` | `source_type`, `source_id`, `created_at`, `updated_at` | selectOpportunityFollowups 已补 |
| `crm_channel_expansion_contact` | `channel_expansion_id, duty, birthday, wecom_added, special_note, sort_order, created_at, updated_at` | selectChannelExpansionContacts 已补全字段 |
| `work_daily_report_comment` | `created_at` | selectWorkReportComments 已补 |
| `crm_channel_expansion_coverage` | `province, city` | 渠道详情 `crm_entity_detail`(channel_expansion) 新增 `coverages` 明细（`selectChannelExpansionCoverages`） |
| `crm_sales_expansion_coverage` | `province, city` | 销售详情 `crm_entity_detail`(sales_expansion) 新增 `coverages` 明细（销售所属区域，`selectSalesExpansionCoverages`），此前完全未暴露 |
| `work_report_message` | `sender_user_id, receiver_user_id, report_date, line_index, biz_type, biz_id, biz_name, content, read_at, created_at` | 日报详情 `crm_entity_detail`(daily_report) 新增 `messages` 明细（`selectWorkReportMessages`），此前完全未暴露 |

> ✅ **「是否加企业微信」维度现已支持统计**：`crm_report_query`(`channel_analytics`) 新增 `contactWecomDistribution` 聚合（按 `crm_channel_expansion_contact.wecom_added`：已加/未加/未填写，含联系人计数、渠道计数）。

---

## D. 备注（低价值 / 安全 / 信息不全）

- **审计字段**：`created_at` / `updated_at`；`crm_opportunity` 另含 `updated_by`。本轮已补进列表层。
- **外键字段**：`customer_id`、`owner_user_id`、`sales_expansion_id`、`channel_expansion_id`、`pre_sales_id`、`followup_user_id`、`operator_user_id`、`reviewer_user_id`、`report_id` 等。
- **安全敏感字段**：`sys_user.password_hash`、`pwd_reset_required` **不应暴露**（MCP 正确未暴露）。
- **OMS 集成字段**：`crm_opportunity.pushed_to_oms`、`oms_push_time`、`updated_by` 已补进列表层。
- **兼容性遗留字段**：`crm_channel_expansion.industry`（兼容旧结构）已补；`oms_project_code` 已在 `OpportunitySchemaInitializer:316` 被 DROP。

### 信息不全待核对项
1. ~~`crm_crm_expansion` 表字段全集未找到建表脚本~~ → **已找到** `sql/20260827.sql`（45-68），字段全集已核验。
2. `sys_org` / `sys_role` / `sys_tenant_user` 的完整建表脚本**未找到**（仅片段注释）；`searchOrganizations` 中 `parentId/orgCode/sortOrder` 被硬编码 null，**待人工核实列名后再补真实值**。
3. `business_calendar_day`、`report_reminder_*`、`speech_recognition_config`、`dashboard_analytics_card_config`、数据权限表仍无独立 MCP 工具（不在本轮范围）。

---

## 结论摘要

- **是否已包含全部字段？** 核心业务主表 + 详情接口（`表.*`）已全覆盖；本轮已把所有明确标识的缺失字段补齐。剩余未处理项：`sys_org` 层级字段（待确认列名）、以及 `business_calendar_day` / 日报提醒 / 语音识别 / 看板卡片等配置类表在 MCP 中无独立工具（配置类，价值低）。
- **本轮已补齐的缺口**：
  1. 子表（真正缺漏）已全补：`crm_expansion_followup.visit_start_time/source_type/source_id`、`crm_channel_expansion_contact` 全部字段（含 `wecom_added`）、`crm_opportunity_followup`、`work_daily_report_comment.created_at`。
  2. 新增 `crm_report_query.channel_analytics` 的 `contactWecomDistribution`：**支持按「是否加企业微信」维度统计**。
  3. 列表层：`work_checkin` 经纬度、`crm_sales_expansion.in_progress`、`registered_capital`、及 `created_at/updated_at` 补齐。
  4. 用户画像：`sys_user.user_code(工号)/real_name/job_title(职位)/hire_date(入职日期)` 已补齐（`selectUserProfile` 与 `searchOrgUsers`）。
  5. 新增 `crm_entity_detail`(crm_expansion) 联查 `contacts`（`crm_crm_expansion_contact` 子表）+ `followups`（biz_type='crm'），此前完全未暴露。
  6. **新增覆盖地市明细**：销售所属区域 `crm_sales_expansion_coverage`、渠道覆盖 `crm_channel_expansion_coverage` 已在销售/渠道详情的 `coverages` 返回（此前销售所属区域完全未暴露）。
  7. **新增日报消息** `work_report_message`：日报详情 `messages` 返回 sender/receiver/content/readAt 等（此前完全未暴露）。
- **待办（非必需）**：`sys_org.parent_id/org_code/sort_order` 待人工核实框架表列名后补真实值。