gitea-admin/nocobase-mcp

Fork 0

Files

T

nac 76e4cbf58a feat: add team-aware CRM queries and project tracking

2026-08-14 11:00:13 +00:00

13 KiB

Raw Blame History

团队 CRM 查询与项目追踪设计

目标

在保持现有只读 CRM MCP 和受控项目写入兼容的前提下，增加：

基于 CRM 正式团队关系的查询；
团队与成员双层客户、跟进和项目统计；
长期未跟进客户查询，并明确标注当前 NocoBase 不支持的闭环能力；
客户归属、实际记录人、参与人员等角色的明确区分；
CRM 项目完整跟进时间线；
北京时间、完整分页、稳定 JSON 解析和数据质量提示。

本设计以 2026-07-24 从目标 NocoBase 读取的集合和字段元数据为依据。元数据盘点未读取或修改业务记录。

已确认的数据模型

团队与用户

团队集合为 t_team_management（团队管理）。

业务含义	字段	类型	目标
团队名	`f_team_name`	string	-
团队负责人	`tdgl_manager`	belongsToMany	`users`
团队成员	`tdgl_team_members`	belongsToMany	`users`

users 中存在反向关系：

yh_belong_teams：所属团队；
yh_managed_team：管理的团队；
yh_status：员工状态。

员工状态中已确认：

标签	内部值
正式员工	`nkluuumb1r1`
实习生	`n7cnn29kzo1`
已离职	`bpsfm63uc8i`
交接中	`yv6pkhjxtfz`
临时员工	`4g6m1y5uy1s`

“正式团队成员”定义为：

用户出现在团队的 tdgl_team_members 关系中；
用户的 yh_status 等于 nkluuumb1r1。

负责人可以有多人，不应在 MCP 中强制压缩为单个负责人。

系统另有 departments 树形部门集合。部门和 CRM 团队是两套不同关系，首版团队查询以 t_team_management 为准，不用部门关系替代团队关系。

客户角色

客户集合为 t_nt3pjadelqi。

字段	标题	建议语义
`kehu_manage_person`	管理人	管理或权限相关人员，不代表客户归属
`kehu_followup_person`	跟进人	客户归属人员
`kehu_lookup_people`	可查看人	ACL 可见人员，不代表业务协同
`createdBy`	创建人	数据创建者，不代表客户负责人

上述前三个字段均可能包含多人。客户归属以 kehu_followup_person 为准。MCP 不应将 kehu_manage_person 或 kehu_lookup_people 计为客户归属或协同贡献，也不应把 createdBy 当作客户负责人。

由于 kehu_followup_person 是多值关系，接口使用复数 customer_owners，不能从列表顺序推断唯一主负责人。

跟进角色与分类

跟进集合为 t_07667a5evtr。

字段	标题	建议语义
`createdBy`	创建人	跟进记录提交人
`gjjl_followup_person`	参与跟进人员	明确的参与人员
`gjjl_client`	客户	关联客户
`gjjl_client_contacts`	客户联系人	关联联系人
`f_gjjl_projects`	相关项目	关联 CRM 项目
`f_srysmjkwfq1`	跟进时间	业务发生时间
`gjjl_followup_type`	跟进类型	沟通方式
`f_19iplxz0nds`	跟进内容	跟进正文
`f_hskl7gjvos9`	状态	记录状态

已确认的跟进方式：

邮件
电话
视频会议
拜访/请客
审厂/来访
论坛/大会
代理跟进情况代填

已确认的跟进状态为“审批中、OK、迟交、无效”。它更接近记录审批或提交质量状态，不能直接解释为下一步事项的完成状态。

首版角色输出必须同时保留：

record_creator：createdBy，只表示记录提交人；
participants：gjjl_followup_person；
customer_owners：关联客户的 kehu_followup_person；
customer_management_users：关联客户的 kehu_manage_person，仅作为补充信息；
team_managers：命中团队的 tdgl_manager。

createdBy 不一定是实际跟进人，因此不得用于实际跟进贡献统计。实际跟进贡献只按 gjjl_followup_person 统计；多人参与时每位参与人各获得一次参与贡献，同时团队总跟进记录按记录 ID 去重。record_creator 仅用于审计和数据质量检查。

CRM 项目

CRM 项目集合为 t_projects，与现有 MCP 项目写入使用同一集合。

已确认关系：

客户：f_projects_client / 外键 client_ID；
联系人：f_projects_contacts；
跟进记录：f_projects_followup_records；
项目进展：f_projects_progress；
项目情况更新：f_u28gm9h2uzl；
附件：f_projects_attachments。

项目进展为：

询价阶段
已报价
送样
已定点
SOP
终止

项目情况更新集合为 t_qxeepjvi39s，包含：

项目：f_k37rbpi4vye；
更新日期：f_6g9fw5oqef9；
更新内容：f_ei16g0ihwwd；
附件：f_6pk5pv17i27；
创建人：createdBy。

当前没有独立的报价、样品、测试或定点事件集合映射。首版只能使用项目阶段和项目情况更新正文展示这些信息，不能可靠统计每类业务事件的数量或状态。

另一套项目管理模型

系统还存在：

market_pm（项目管理）；
project_updates（项目节点）。

这套模型有项目负责人、预计完成时间、项目状态，以及节点负责人、节点状态和节点预计完成时间，但没有已确认的客户关系，也没有与 t_projects 的关联字段。

因此：

t_projects 是 CRM 项目查询的权威来源；
market_pm / project_updates 作为独立的任务型项目模型；
在没有稳定关联键之前，两套项目不得按名称自动合并；
如后续需要统一展示，返回值必须带 project_source，例如 crm 或 management。

当前数据模型缺口

跟进记录中没有已确认的以下结构化字段：

下一步事项；
事项责任人；
截止日期；
完成状态；
完成时间；
优先级；
风险类型。

因此“逾期未完成事项”和“无下一步的重点项目”不能仅凭现有跟进记录准确计算。

本项目不得修改 NocoBase 数据模型，因此不新增行动项集合，也不增加跟进字段。以下能力明确跳过：

精确查询逾期未完成事项；
按行动项完成状态统计；
权威判断跟进是否存在下一步；
权威判断下一步责任人和截止日期。

不从跟进正文推断权威的下一步、风险或逾期状态。

报价、样品、测试等完整链路同样需要结构化事件模型。项目阶段只能表示当前状态，不能还原每次状态变化的时间和责任人。

配置扩展

建议在 config.json 增加以下可配置映射，默认值采用本次确认字段：

{
  "timezone": "Asia/Shanghai",
  "teams": {
    "resource": "t_team_management",
    "idField": "id",
    "nameField": "f_team_name",
    "managerField": "tdgl_manager",
    "memberField": "tdgl_team_members",
    "userStatusField": "yh_status",
    "formalUserStatusValue": "nkluuumb1r1"
  },
  "roles": {
    "customerOwnerField": "kehu_followup_person",
    "customerManagementField": "kehu_manage_person",
    "customerViewerField": "kehu_lookup_people",
    "followupCreatorField": "createdBy",
    "followupParticipantField": "gjjl_followup_person"
  },
  "crmProjects": {
    "contactField": "f_projects_contacts",
    "followupField": "f_projects_followup_records",
    "updateField": "f_u28gm9h2uzl",
    "updateResource": "t_qxeepjvi39s",
    "updateProjectField": "f_k37rbpi4vye",
    "updateDateField": "f_6g9fw5oqef9",
    "updateContentField": "f_ei16g0ihwwd"
  }
}

不设计或预留会写入 NocoBase 的闭环字段。相关能力在 MCP capability 中明确标为不可用。

MCP 工具设计

团队发现

list_teams(query?, include_members=false, formal_members_only=true)
resolve_team(query)
get_team(team_id, include_members=true, formal_members_only=true)

团队解析规则与负责人解析一致：无匹配或多匹配返回结构化候选结果，不静默选择。

查询工具兼容扩展

现有工具保留原参数，并增加：

list_customers(..., team?, team_id?)
list_followups(..., team?, team_id?, project_id?, followup_type?, record_status?)
crm_overview(..., team?, team_id?)

team 和 team_id 不得同时提供。团队过滤使用正式成员 ID 集合，客户和跟进分别应用对应角色关系，不能把“团队客户”和“团队实际跟进”混成同一口径。

团队统计

team_crm_overview(
  team,
  date_from?,
  date_to?,
  formal_members_only=true,
  include_member_breakdown=true
)

建议返回：

{
  "team": {},
  "period": {},
  "totals": {
    "assigned_customers": 0,
    "owned_customers": 0,
    "followup_records": 0,
    "active_customers": 0,
    "active_projects": 0
  },
  "by_member": [],
  "by_customer": [],
  "by_followup_type": [],
  "by_project_stage": [],
  "contribution_basis": {
    "participant": "gjjl_followup_person"
  }
}

同一条多人参与的跟进：

团队总量只计一次；
成员贡献中每位参与人各计一次；
返回 unique_followups 和 participation_count，防止将两种口径混淆。

项目追溯

get_project(project_id, include_contacts=true, include_followups=true)
get_project_timeline(project_id, date_from?, date_to?)
list_projects(customer_id?, team?, stage?, updated_since?)

时间线事件来源：

项目创建与阶段；
项目情况更新；
关联跟进记录；
联系人；
附件元数据。

每个事件返回 event_type、occurred_at、actors、source_resource 和 source_id。

长期未跟进客户

现有模型可以支持：

list_stale_customers(team?, owner?, inactive_days=30, as_of?)

该工具仅依据客户最后一次有效跟进时间计算。以下工具不实现：

list_action_items
list_overdue_action_items

不得以跟进记录的“迟交”状态代替行动项逾期状态。

时间、分页与统计规则

北京时间

服务内部使用带时区的 datetime；
NocoBase UTC 时间转换到 Asia/Shanghai；
dateOnly 保持日期不做时区偏移；
输出统一为 ISO 8601，例如 2026-07-24T15:30:00+08:00；
响应增加 "timezone": "Asia/Shanghai"。

分页

保持现有 limit、offset 参数兼容，但修复任意 offset：

不再直接用 offset // limit + 1 近似；
读取覆盖目标窗口的底层页并在服务层精确切片；
返回 limit、offset、total、has_more、next_offset；
内部全量统计循环读取所有页；
设置独立的最大扫描记录数和超时保护，超过时返回明确的截断警告。

聚合

团队总量按记录 ID 去重；
成员贡献保留参与次数；
所有聚合返回统计口径；
“无效”跟进不计入有效贡献；“审批中、OK、迟交”保留并分别展示；
不再使用固定 50 个分组作为完整统计结果。

JSON 与元数据稳定性

nb 输出解析需要支持 stdout 混入非 JSON 日志的情况：

继续设置 NB_CLI_LOG_DISABLED=1 和 NB_SKIP_STARTUP_UPDATE=1；
首先尝试对完整 stdout 执行 json.loads；
失败时使用 json.JSONDecoder.raw_decode 定位完整顶层 JSON 对象；
仅接受唯一、完整的 JSON 对象；
其余文本作为已脱敏诊断信息，不进入正常 MCP 数据；
无法可靠定位时返回 nb_invalid_json，不返回部分业务数据；
API Token 必须同时从命令、stdout 和 stderr 中脱敏。

数据质量提示

查询响应增加统一的 data_quality_warnings，包括：

客户有多个归属跟进人；
跟进没有参与人员，无法归属实际贡献；
跟进没有客户或项目；
项目更新没有业务日期；
项目阶段有变化但没有结构化事件记录；
团队成员不是正式员工；
统计因扫描上限被截断。

兼容与实施顺序

第一阶段：基础稳定性

北京时间转换；
精确分页和全量聚合；
JSON 日志混入容错；
统一响应元数据和测试。

第二阶段：团队查询

团队配置、解析和成员发现；
客户与跟进增加团队过滤；
分离客户归属跟进人、管理人、记录创建人和参与人员；
团队整体与成员贡献统计。

第三阶段：CRM 项目时间线

CRM 项目只读查询；
关联客户、联系人、跟进和项目情况更新；
长期未跟进客户查询。

现有工具名、参数和默认紧凑输出保持兼容。新字段只做增量添加；团队和项目查询工具为新工具。现有 stdio 模式继续只读，HTTP 写入范围仍只限当前项目字段和附件操作。

已确认业务决策

客户归属以 kehu_followup_person（跟进人）为准。
createdBy 不一定是实际跟进人，只作为记录提交人展示。
不修改 NocoBase 数据模型；现有模型不支持的闭环能力直接跳过。

实施时采用的默认口径

实际跟进贡献按 gjjl_followup_person（参与跟进人员）统计。
正式成员只包含 yh_status = nkluuumb1r1，排除实习、离职、交接中和临时员工。
t_projects 作为 CRM 项目权威表；不与 market_pm 按名称自动合并。
团队统计默认排除“无效”跟进；“审批中、OK、迟交”保留并分别展示。
长期未跟进默认阈值为 30 天，允许调用方覆盖。

13 KiB Raw Blame History Unescape Escape