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 待人工核实框架表列名后补真实值。