hzhub/docs/crm-api-contract-v3.md

CRM 线索中心模块 API 契约（V3 - 员工门户）

基础信息

• 服务归属: hzhub-system (端口 8083)
• API前缀: /crm/lead (通过 Gateway 路由 /crm/** → hzhub-system)
• 前端项目: hzhub-portal-employee (员工门户)
• 响应格式: R<T> (org.hzhub.common.core.domain.R)
• 分页格式: TableDataInfo<T> (org.hzhub.common.mybatis.core.page.TableDataInfo)

---

接口列表

1. 线索列表查询

接口: GET /crm/lead/list

请求参数 (Query):

{
  "companyName": "XX贸易",        // 公司名称（模糊查询）
  "mobile": "13800000000",        // 手机号
  "intentLevel": "high",          // AI意向等级（字典：crm_intent_level）
  "riskLevel": "low",             // 风险等级（字典：crm_risk_level）
  "ownerUserId": 12345,           // 负责人ID
  "leadStatus": "following",      // 线索状态（字典：crm_lead_status）
  "sourceType": "activity",       // 来源类型（字典：crm_lead_source）
  "customerCode": "C001",         // ERP客户编码
  "pageNum": 1,                   // 页码
  "pageSize": 10                  // 每页大小
}

响应: TableDataInfo<CrmLeadVo>

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "leadId": 1001,
      "tenantId": "000000",
      "customerCode": "C001",         // ERP客户编码
      "companyName": "XX贸易有限公司",
      "contactName": "张三",
      "mobile": "138****0000",         // 脱敏
      "wechat": "zhangsan",
      "province": "广东省",
      "city": "深圳市",
      "regionId": 100,
      "regionName": "华南区",          // 翻译
      "sourceType": "activity",
      "sourceTypeName": "活动",        // 翻译
      "industry": "食品",
      "industryName": "食品行业",      // 翻译
      "storeCount": 20,
      "intentLevel": "high",
      "intentLevelName": "高意向",     // 翻译
      "aiScore": 85.5,
      "riskLevel": "low",
      "riskLevelName": "低风险",       // 翻译
      "ownerUserId": 12345,
      "ownerUserName": "李四",         // 翻译
      "leadStatus": "following",
      "leadStatusName": "跟进中",      // 翻译
      "nextFollowTime": "2026-05-20 14:00:00",
      "createBy": 1,
      "createByName": "系统管理员",    // 翻译
      "createTime": "2026-05-15 10:00:00"
    }
  ],
  "total": 100
}

---

2. 线索详情查询

接口: GET /crm/lead/{leadId}

路径参数: leadId (Long)

响应: R<CrmLeadVo>

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "leadId": 1001,
    "customerCode": "C001",
    "companyName": "XX贸易有限公司",
    "contactName": "张三",
    "mobile": "13800000000",           // 未脱敏
    // ... 其他字段同列表
  }
}

---

3. 新增线索

接口: POST /crm/lead

请求体: CrmLeadBo

{
  "customerCode": "C001",             // ERP客户编码（可选）
  "companyName": "XX贸易有限公司",
  "contactName": "张三",
  "mobile": "13800000000",
  "wechat": "zhangsan",
  "province": "广东省",
  "city": "深圳市",
  "regionId": 100,                    // 关联 sys_dept
  "sourceType": "activity",
  "activityName": "春季招商会",
  "referrerName": "王五",
  "industry": "食品",
  "companyScale": "50-100人",
  "storeCount": 20,
  "remark": "意向强烈，希望尽快对接"
}

业务逻辑:

1. 如果提供 customerCode，调用 hzhub-erp:8082/erp/dynamic/v1/customer/detail 拉取ERP客户信息
2. 自动填充客户基础信息（companyName, contactName, mobile等）
3. 校验手机号是否重复（同租户内）
4. 调用 LangChain4j AI服务分析意向等级（hzhub-ai:6039/ai/analyze/intent - 第二阶段实现）
5. 根据区域规则（sys_dept）分配销售（owner_user_id - 可选）
6. 返回成功消息

响应: R<Void>

{
  "code": 200,
  "msg": "新增成功"
}

---

4. 编辑线索

接口: PUT /crm/lead

请求体: CrmLeadBo

{
  "leadId": 1001,
  "companyName": "XX贸易（已改名）",
  "contactName": "张三",
  "mobile": "13800000000",
  // ... 其他可编辑字段
}

响应: R<Void>

{
  "code": 200,
  "msg": "修改成功"
}

---

5. 删除线索

接口: DELETE /crm/lead/{leadIds}

路径参数: leadIds (String，逗号分隔，如 "1001,1002,1003")

响应: R<Void>

{
  "code": 200,
  "msg": "删除成功"
}

---

6. 分配线索

接口: PUT /crm/lead/assign

请求体:

{
  "leadId": 1001,
  "ownerUserId": 12345               // 新负责人ID（关联 sys_user）
}

响应: R<Void>

{
  "code": 200,
  "msg": "分配成功"
}

---

7. 获取跟进记录列表

接口: GET /crm/lead/follow/{leadId}

路径参数: leadId (Long)

响应: R<List<CrmLeadFollowVo>>

{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "followId": 2001,
      "leadId": 1001,
      "followType": "phone",
      "followTypeName": "电话",        // 翻译
      "content": "客户表达了合作意向，希望了解招商政策",
      "aiSummary": "客户意向高，关注返点政策",
      "nextFollowTime": "2026-05-20 14:00:00",
      "followUserId": 12345,
      "followUserName": "李四",        // 翻译
      "createTime": "2026-05-15 15:00:00"
    }
  ]
}

---

8. 添加跟进记录

接口: POST /crm/lead/follow

请求体: CrmLeadFollowBo

{
  "leadId": 1001,
  "followType": "phone",
  "content": "与客户沟通了具体合作细节，客户对返点政策满意",
  "nextFollowTime": "2026-05-20 14:00:00"
}

业务逻辑:

1. 保存跟进记录
2. 调用 LangChain4j AI生成摘要（hzhub-ai:6039/ai/summarize - 第二阶段实现）
3. 更新线索的 nextFollowTime

响应: R<Void>

{
  "code": 200,
  "msg": "跟进成功"
}

---

9. 线索转经销商（第二阶段实现）

接口: POST /crm/lead/convert

请求体:

{
  "leadId": 1001,
  "dealerName": "XX贸易",
  "dealerCode": "DL20260001",
  "customerCode": "C001"             // ERP客户编码（可选）
}

响应: R<Void>

{
  "code": 200,
  "msg": "转化成功"
}

---

数据字典定义

crm_lead_source（线索来源）

字典值	字典标签	备注
activity	活动	线下招商活动
referral	推荐	客户推荐
website	网站	官网咨询
exhibition	展会	行业展会
wecom	企业微信	企业微信咨询
erp	ERP客户	从ERP客户转化
other	其他	其他来源

crm_lead_status（线索状态）

字典值	字典标签	备注
new	新线索	刚录入，未分配
following	跟进中	已分配，正在跟进
converted	已转化	已转为经销商
invalid	已作废	线索无效

crm_intent_level（AI意向等级）

字典值	字典标签	AI评分范围
high	高意向	>= 80
medium	中意向	60-80
low	低意向	< 60

crm_risk_level（风险等级）

字典值	字典标签	备注
high	高风险	需重点关注
medium	中风险	需持续跟踪
low	低风险	正常跟进

crm_follow_type（跟进方式）

字典值	字典标签
phone	电话
wecom	企业微信
visit	拜访
email	邮件
other	其他

---

前端类型定义（TypeScript - 员工门户）

// CrmLeadVo
export interface CrmLeadVo {
  leadId: number;
  tenantId: string;
  customerCode?: string;              // ERP客户编码
  companyName: string;
  contactName: string;
  mobile: string;
  wechat?: string;
  province?: string;
  city?: string;
  regionId?: number;
  regionName?: string;
  sourceType?: string;
  sourceTypeName?: string;
  activityName?: string;
  referrerName?: string;
  industry?: string;
  industryName?: string;
  companyScale?: string;
  storeCount?: number;
  intentLevel?: string;
  intentLevelName?: string;
  aiScore?: number;
  riskLevel?: string;
  riskLevelName?: string;
  ownerUserId?: number;
  ownerUserName?: string;
  leadStatus: string;
  leadStatusName?: string;
  convertedDealerId?: number;
  nextFollowTime?: string;
  remark?: string;
  createBy: number;
  createByName?: string;
  createTime: string;
  updateBy?: number;
  updateByName?: string;
  updateTime?: string;
}

// CrmLeadBo
export interface CrmLeadBo {
  leadId?: number;
  customerCode?: string;              // ERP客户编码（可选）
  companyName: string;
  contactName: string;
  mobile: string;
  wechat?: string;
  province?: string;
  city?: string;
  regionId?: number;
  sourceType?: string;
  activityName?: string;
  referrerName?: string;
  industry?: string;
  companyScale?: string;
  storeCount?: number;
  ownerUserId?: number;
  remark?: string;
}

// CrmLeadFollowVo
export interface CrmLeadFollowVo {
  followId: number;
  leadId: number;
  followType: string;
  followTypeName?: string;
  content: string;
  aiSummary?: string;
  nextFollowTime?: string;
  followUserId: number;
  followUserName?: string;
  createTime: string;
}

// CrmLeadFollowBo
export interface CrmLeadFollowBo {
  followId?: number;
  leadId: number;
  followType: string;
  content: string;
  nextFollowTime?: string;
}

// TableDataInfo（员工门户已定义）
export interface TableDataInfo<T> {
  code: number;
  msg: string;
  rows: T[];
  total: number;
}

// R（员工门户已定义）
export interface R<T> {
  code: number;
  msg: string;
  data?: T;
}

---

注意事项（员工门户适配）

1. 多租户支持: 所有查询自动过滤租户ID（TenantEntity）
2. 数据权限: 根据 sys_dept 层级进行数据隔离
3. 敏感字段脱敏: mobile 字段在列表查询时脱敏
4. 字段翻译: 字典字段、用户ID、部门ID 自动翻译为名称
5. 操作日志: 新增、编辑、删除操作记录日志
6. 防重复提交: 新增操作防重复
7. 逻辑删除: 使用 @TableLogic，删除时不物理删除
8. ERP关联: 如果提供 customerCode，自动拉取ERP客户信息
9. 无需Sa-Token注解: 员工门户权限由Gateway统一控制

---

ERP集成接口（hzhub-erp）

获取ERP客户详情

接口: GET /erp/dynamic/v1/customer/detail

请求参数: customerCode

响应: R<CustomerVO>

CustomerVO（员工门户已定义）:

interface CustomerVO {
  customerCode: string;
  customerName: string;
  contactName: string;
  salesAreaName: string;
  brandName: string;
  phone: string;
  province: string;
  city: string;
  // ... 其他字段见 hzhub-portal-employee/src/api/erp/index.ts
}

---

开发优先级

• P0（必须实现）: 接口1-8（基础CRUD + 跟进）
• P1（第二阶段）: 接口9（线索转经销商）+ AI意向识别 + AI摘要生成
• P2（第三阶段）: AI风险分析 + AI预测模型