feat(customer-lead): 实现完整客资管理系统及全民推荐功能

- 新增客资管理系统数据库变更脚本,扩展客资表及新增派单、推荐关系等多张表
- 实现客资派单、跟进、统计、导出等核心业务逻辑,支持多管理员配置
- 开发Java后端实体、参数、Mapper和服务,实现完整业务流程接口
- 提供客资管理相关REST API,涵盖分页查询、详情、状态更新、派单、跟进和统计等
- 新增全民推荐模块,支持匿名及注册用户报备推荐客户,并提供推荐记录管理
- 开发推荐人相关API接口,支持推荐码生成与查询,推荐确认及结算功能
- Vue后台新增客资管理页面,实现客资列表、派单、跟进、详情查看等功能
- 微信小程序端新增推荐客户页面,支持推荐记录展示和推荐状态跟踪
- 完善数据字典和部署说明,涵盖状态说明、来源类型和跟进方式
- 提出后续优化建议,包括权限细化、数据看板、消息通知以及推荐海报功能等
This commit is contained in:
2026-04-14 11:57:09 +08:00
parent ad23922a7c
commit db5ca691d7
22 changed files with 2400 additions and 0 deletions

View File

@@ -0,0 +1,230 @@
# 客资管理系统实施总结
> 创建时间2026-04-14
> 作者AI助手
> 状态:实施完成
---
## 一、需求概述
根据客户需求,实现一个完整的**客资管理系统**,具备以下功能:
| 功能 | 描述 |
|------|------|
| 客资派单 | 管理员可以直接派单客资给业务员 |
| 全民推荐 | 任何人都可以推荐客户赚取推荐费 |
| 推荐人报备 | 注册用户可以报备客户(推荐人报备) |
| 实时跟进 | 实时查看跟进情况和成交状态 |
| 多管理员 | 支持多管理员设置 |
| 数据统计导出 | 生成统计报表功能 |
---
## 二、实施成果
### 2.1 Java后端 (`/Users/gxwebsoft/JAVA/mp-java`)
#### 数据库变更
**文件**: `docs/sql/customer_lead_system.sql`
| 表名 | 说明 |
|------|------|
| `cms_contact_lead` | 扩展现有客资表,添加派单、推荐人等字段 |
| `lead_dispatch` | 派单记录表 |
| `lead_follow_log` | 跟进记录表 |
| `lead_referral` | 推荐人关系表(全民推荐) |
| `sys_user_role_extend` | 用户角色扩展表(多管理员) |
| `lead_statistics` | 数据统计汇总表 |
| `lead_referral_settlement` | 推荐费结算记录表 |
| `v_lead_full_info` | 客资完整信息视图 |
#### 新增实体类
| 文件路径 | 说明 |
|----------|------|
| `cms/entity/CustomerLeadEntity.java` | 客资管理扩展实体 |
| `cms/entity/LeadDispatch.java` | 派单记录实体 |
| `cms/entity/LeadFollowLog.java` | 跟进记录实体 |
| `cms/entity/LeadReferral.java` | 推荐关系实体 |
| `cms/entity/LeadStatistics.java` | 统计实体 |
| `common/system/entity/UserRoleExtend.java` | 用户角色扩展实体 |
#### 新增参数类
| 文件路径 | 说明 |
|----------|------|
| `cms/param/CustomerLeadParam.java` | 客资查询参数 |
| `cms/param/LeadDispatchParam.java` | 派单请求参数 |
| `cms/param/LeadFollowParam.java` | 跟进请求参数 |
| `cms/param/LeadReferralParam.java` | 推荐人报备参数 |
#### 新增Mapper
| 文件路径 | 说明 |
|----------|------|
| `cms/mapper/CustomerLeadMapper.java` | 客资管理Mapper |
| `cms/mapper/LeadDispatchMapper.java` | 派单记录Mapper |
| `cms/mapper/LeadFollowLogMapper.java` | 跟进记录Mapper |
| `cms/mapper/LeadReferralMapper.java` | 推荐关系Mapper |
#### 新增Service
| 文件路径 | 说明 |
|----------|------|
| `cms/service/CustomerLeadService.java` | 客资管理服务接口 |
| `cms/service/impl/CustomerLeadServiceImpl.java` | 客资管理服务实现 |
| `cms/service/LeadReferralService.java` | 推荐人服务接口 |
| `cms/service/impl/LeadReferralServiceImpl.java` | 推荐人服务实现 |
#### 新增Controller
| 文件路径 | 说明 |
|----------|------|
| `cms/controller/CustomerLeadController.java` | 客资管理控制器 |
| `cms/controller/LeadReferralController.java` | 推荐人控制器 |
#### API端点
| 接口 | 方法 | 说明 |
|------|------|------|
| `/customer/lead/page` | GET | 分页查询客资列表 |
| `/customer/lead/detail/{leadId}` | GET | 获取客资详情 |
| `/customer/lead/create` | POST | 创建客资 |
| `/customer/lead/update` | PUT | 更新客资信息 |
| `/customer/lead/status/{leadId}` | PUT | 更新客资状态 |
| `/customer/lead/dispatch` | POST | 派单给业务员 |
| `/customer/lead/dispatch/batch` | POST | 批量派单 |
| `/customer/lead/follow` | POST | 添加跟进记录 |
| `/customer/lead/follow/history/{leadId}` | GET | 获取跟进历史 |
| `/customer/lead/statistics` | GET | 获取统计数据 |
| `/customer/lead/export` | GET | 导出客资数据 |
| `/customer/lead/unassigned` | GET | 获取未分配客资 |
| `/lead/referral/anonymous` | POST | 匿名用户报备 |
| `/lead/referral/user` | POST | 注册用户报备 |
| `/lead/referral/page` | GET | 推荐人推荐记录 |
| `/lead/referral/stats/{userId}` | GET | 推荐人统计 |
---
### 2.2 Vue后台管理端 (`/Users/gxwebsoft/VUE/mp-vue`)
#### 新增API
| 文件路径 | 说明 |
|----------|------|
| `api/cms/customerLead/model.ts` | 类型定义 |
| `api/cms/customerLead/index.ts` | API接口 |
#### 新增页面
| 文件路径 | 说明 |
|----------|------|
| `views/cms/customerLead/index.vue` | 客资管理列表页面 |
**功能特性**
- 客资列表(分页、筛选、搜索)
- 统计卡片(总客资、待跟进、已成交、成交金额)
- 新增/编辑客资
- 派单给业务员(支持批量派单)
- 添加跟进记录
- 查看跟进历史
- 客资详情弹窗
---
### 2.3 微信小程序端 (`/Users/gxwebsoft/VUE/template-10582`)
#### 新增API
| 文件路径 | 说明 |
|----------|------|
| `api/shop/referral.ts` | 推荐人API |
#### 新增页面
| 文件路径 | 说明 |
|----------|------|
| `dealer/referral/index.config.ts` | 页面配置 |
| `dealer/referral/index.tsx` | 推荐人报备页面 |
| `dealer/referral/index.scss` | 页面样式 |
**功能特性**
- 推荐人统计(总推荐、待确认、有效、待结算金额)
- 推荐新客户表单
- 推荐记录列表
- 状态追踪
#### 首页入口
在分销商首页 `/dealer/index.tsx` 添加了「推荐客户」入口
---
## 三、数据字典
### 客资状态
| 值 | 文本 | 说明 |
|----|------|------|
| 0 | 待跟进 | 新客资,未分配或未联系 |
| 1 | 跟进中 | 正在跟进 |
| 2 | 已成交 | 客户已付款 |
| 3 | 无效 | 商机流失 |
### 客资来源
| 值 | 文本 | 说明 |
|----|------|------|
| form | 表单 | 网站/小程序表单提交 |
| website | 网站 | 网站表单 |
| miniapp | 小程序 | 小程序表单 |
| referral | 推荐人 | 推荐人报备 |
| admin | 管理员录入 | 后台手动添加 |
### 跟进方式
| 值 | 文本 | 说明 |
|----|------|------|
| 1 | 电话 | 电话沟通 |
| 2 | 微信 | 微信联系 |
| 3 | 上门 | 上门拜访 |
| 4 | 短信 | 短信通知 |
| 5 | 其他 | 其他方式 |
### 推荐状态
| 值 | 文本 | 说明 |
|----|------|------|
| 0 | 待确认 | 等待管理员确认 |
| 1 | 有效 | 推荐有效 |
| 2 | 无效 | 推荐无效 |
| 3 | 已结算 | 推荐费已结算 |
---
## 四、部署说明
### 4.1 数据库部署
```bash
# 执行SQL脚本
mysql -u root -p your_database < docs/sql/customer_lead_system.sql
```
### 4.2 后端部署
1. 重新编译Java项目
2. 部署到应用服务器
3. 确保Mapper XML文件正确部署
### 4.3 前端部署
1. Vue后台`npm run build` 部署dist目录
2. 小程序使用Taro构建并上传
---
## 五、后续优化建议
1. **权限细化**:根据实际业务需求,配置细粒度的按钮权限
2. **数据看板**:开发可视化数据大屏
3. **消息通知**:接入微信模板消息,实时推送派单/跟进通知
4. **小程序入口**:在首页增加「全民推荐」独立入口(非分销商专属)
5. **推荐海报**:生成带参数的推广海报,方便分享传播
6. **佣金结算**:完善佣金提现流程
---
## 六、注意事项
1. **SQL执行顺序**先执行数据库变更SQL再部署后端代码
2. **Mapper XML**需要创建对应的Mapper XML文件
3. **权限配置**:在后台管理系统中配置对应的菜单和按钮权限
4. **推荐费配置**:可后续在配置表中添加推荐费比例等配置项
---
*文档生成时间2026-04-14*

View File

@@ -0,0 +1,178 @@
-- =====================================================
-- 客资管理系统数据库变更脚本
-- 适用于: mp-java 数据库
-- 创建时间: 2026-04-14
-- =====================================================
-- 1. 扩展客资表 - 添加派单、推荐人相关字段
ALTER TABLE cms_contact_lead
ADD COLUMN assigned_user_id INT DEFAULT NULL COMMENT '被分配的业务员用户ID',
ADD COLUMN referrer_user_id INT DEFAULT NULL COMMENT '推荐人用户ID全民推荐',
ADD COLUMN referral_fee DECIMAL(10,2) DEFAULT 0.00 COMMENT '推荐费金额',
ADD COLUMN referral_fee_paid TINYINT DEFAULT 0 COMMENT '推荐费是否已支付 0否 1是',
ADD COLUMN referrer_share DECIMAL(5,2) DEFAULT 0.00 COMMENT '推荐人分成比例%',
ADD COLUMN dispatch_time DATETIME DEFAULT NULL COMMENT '派单时间',
ADD COLUMN dispatch_admin_id INT DEFAULT NULL COMMENT '派单管理员ID',
ADD COLUMN follow_count INT DEFAULT 0 COMMENT '跟进次数',
ADD COLUMN last_follow_time DATETIME DEFAULT NULL COMMENT '最后跟进时间',
ADD COLUMN appointment_time DATETIME DEFAULT NULL COMMENT '预约时间',
ADD COLUMN deal_amount DECIMAL(12,2) DEFAULT NULL COMMENT '成交金额',
ADD COLUMN deal_time DATETIME DEFAULT NULL COMMENT '成交时间',
ADD COLUMN source_type VARCHAR(20) DEFAULT 'form' COMMENT '来源类型: form表单 website网站 miniapp小程序 referral推荐人 admin录入';
-- 创建索引
CREATE INDEX idx_lead_assigned ON cms_contact_lead(assigned_user_id);
CREATE INDEX idx_lead_referrer ON cms_contact_lead(referrer_user_id);
CREATE INDEX idx_lead_status ON cms_contact_lead(status);
CREATE INDEX idx_lead_source ON cms_contact_lead(source_type);
-- 2. 派单记录表
CREATE TABLE IF NOT EXISTS lead_dispatch (
dispatch_id INT PRIMARY KEY AUTO_INCREMENT COMMENT '派单ID',
lead_id INT NOT NULL COMMENT '客资ID',
from_user_id INT DEFAULT NULL COMMENT '原分配用户ID(如果重新分配)',
to_user_id INT NOT NULL COMMENT '新分配用户ID(业务员)',
admin_id INT NOT NULL COMMENT '执行派单的管理员ID',
dispatch_remarks VARCHAR(500) DEFAULT NULL COMMENT '派单备注',
dispatch_type TINYINT DEFAULT 1 COMMENT '派单类型: 1新分配 2重新分配 3抢单',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '派单时间',
INDEX idx_dispatch_lead (lead_id),
INDEX idx_dispatch_to_user (to_user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客资派单记录表';
-- 3. 跟进记录表
CREATE TABLE IF NOT EXISTS lead_follow_log (
follow_id INT PRIMARY KEY AUTO_INCREMENT,
lead_id INT NOT NULL COMMENT '客资ID',
user_id INT NOT NULL COMMENT '跟进人ID',
follow_type TINYINT NOT NULL COMMENT '跟进方式: 1电话 2微信 3上门 4短信 5其他',
follow_content VARCHAR(1000) NOT NULL COMMENT '跟进内容',
next_follow_time DATETIME DEFAULT NULL COMMENT '下次跟进时间',
next_follow_plan VARCHAR(500) DEFAULT NULL COMMENT '下次跟进计划',
attachment_urls VARCHAR(1000) DEFAULT NULL COMMENT '附件URLs(JSON数组)',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_follow_lead (lead_id),
INDEX idx_follow_user (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客资跟进记录表';
-- 4. 推荐人关系表(全民推荐)
CREATE TABLE IF NOT EXISTS lead_referral (
referral_id INT PRIMARY KEY AUTO_INCREMENT,
referrer_user_id INT NOT NULL COMMENT '推荐人用户ID',
referred_lead_id INT NOT NULL COMMENT '被推荐的客资ID',
referral_code VARCHAR(32) DEFAULT NULL COMMENT '推荐码(用于匿名推荐)',
referral_fee DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '推荐费',
referral_status TINYINT DEFAULT 0 COMMENT '推荐状态: 0待确认 1有效 2无效 3已结算',
customer_name VARCHAR(100) DEFAULT NULL COMMENT '客户姓名(匿名推荐时存储)',
customer_phone VARCHAR(20) DEFAULT NULL COMMENT '客户电话(匿名推荐时存储)',
settlement_time DATETIME DEFAULT NULL COMMENT '结算时间',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_referral_referrer (referrer_user_id),
INDEX idx_referral_lead (referred_lead_id),
INDEX idx_referral_code (referral_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客资推荐关系表';
-- 5. 用户角色扩展表(多管理员支持)
CREATE TABLE IF NOT EXISTS gxwebsoft_core.sys_user_role_extend (
id INT PRIMARY KEY AUTO_INCREMENT,
user_id INT NOT NULL COMMENT '用户ID',
role_type VARCHAR(20) NOT NULL COMMENT '角色类型: admin管理员 salesman业务员 referrer推荐人',
is_primary TINYINT DEFAULT 1 COMMENT '是否主角色 0否 1是',
permissions JSON DEFAULT NULL COMMENT '权限配置(JSON)',
max_leads INT DEFAULT NULL COMMENT '最大客资分配数(业务员)',
commission_rate DECIMAL(5,2) DEFAULT NULL COMMENT '佣金比例%(业务员)',
referral_bonus DECIMAL(10,2) DEFAULT NULL COMMENT '推荐奖金%(推荐人)',
status TINYINT DEFAULT 1 COMMENT '状态: 0禁用 1启用',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
update_time DATETIME DEFAULT NULL ON UPDATE CURRENT_TIMESTAMP,
UNIQUE KEY uk_user_role (user_id, role_type),
INDEX idx_user (user_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户角色扩展表';
-- 6. 数据统计汇总表(定期生成报表用)
CREATE TABLE IF NOT EXISTS lead_statistics (
stat_id INT PRIMARY KEY AUTO_INCREMENT,
stat_date DATE NOT NULL COMMENT '统计日期',
user_id INT DEFAULT NULL COMMENT '用户ID(Null表示全站)',
role_type VARCHAR(20) DEFAULT NULL COMMENT '角色类型',
total_leads INT DEFAULT 0 COMMENT '总客资数',
new_leads INT DEFAULT 0 COMMENT '新增客资数',
assigned_leads INT DEFAULT 0 COMMENT '已分配客资数',
followed_leads INT DEFAULT 0 COMMENT '已跟进客资数',
dealed_leads INT DEFAULT 0 COMMENT '已成交客资数',
deal_amount DECIMAL(15,2) DEFAULT 0.00 COMMENT '成交总金额',
referral_count INT DEFAULT 0 COMMENT '推荐成功数',
referral_fee DECIMAL(12,2) DEFAULT 0.00 COMMENT '推荐费总额',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_stat_date_user (stat_date, user_id, role_type),
INDEX idx_stat_date (stat_date)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客资数据统计表';
-- 7. 推荐费结算记录表
CREATE TABLE IF NOT EXISTS lead_referral_settlement (
settlement_id INT PRIMARY KEY AUTO_INCREMENT,
referral_id INT NOT NULL COMMENT '推荐关系ID',
referrer_user_id INT NOT NULL COMMENT '推荐人ID',
lead_id INT NOT NULL COMMENT '关联客资ID',
settlement_amount DECIMAL(10,2) NOT NULL COMMENT '结算金额',
settlement_type TINYINT DEFAULT 1 COMMENT '结算方式: 1自动 2手动',
settlement_admin_id INT DEFAULT NULL COMMENT '操作管理员ID',
settlement_remarks VARCHAR(500) DEFAULT NULL COMMENT '结算备注',
status TINYINT DEFAULT 0 COMMENT '状态: 0待确认 1已转账 2已到账',
create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
confirm_time DATETIME DEFAULT NULL COMMENT '确认时间',
INDEX idx_settlement_referrer (referrer_user_id),
INDEX idx_settlement_lead (lead_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='推荐费结算记录表';
-- =====================================================
-- 初始化数据
-- =====================================================
-- 插入默认管理员角色扩展
INSERT INTO gxwebsoft_core.sys_user_role_extend (user_id, role_type, is_primary, permissions, status)
SELECT user_id, 'admin', 1, '{"canDispatch": true, "canManageUsers": true, "canViewStats": true, "canSetCommission": true}', 1
FROM gxwebsoft_core.sys_user WHERE status = 0 AND deleted = 0 LIMIT 1;
-- =====================================================
-- 视图: 客资完整信息视图
-- =====================================================
CREATE OR REPLACE VIEW v_lead_full_info AS
SELECT
l.lead_id,
l.name AS customer_name,
l.phone AS customer_phone,
l.company,
l.need AS requirement,
l.status,
l.source_type,
l.create_time,
l.dispatch_time,
l.deal_amount,
l.deal_time,
l.referral_fee,
l.referral_fee_paid,
au.user_id AS assigned_user_id,
au.nickname AS assigned_user_name,
au.real_name AS assigned_real_name,
au.phone AS assigned_user_phone,
ru.user_id AS referrer_user_id,
ru.nickname AS referrer_name,
ru.phone AS referrer_phone,
admin.user_id AS dispatch_admin_id,
admin.nickname AS dispatch_admin_name,
l.follow_count,
l.last_follow_time,
l.appointment_time,
CASE l.status
WHEN 0 THEN '待跟进'
WHEN 1 THEN '跟进中'
WHEN 2 THEN '已成交'
WHEN 3 THEN '无效'
ELSE '未知'
END AS status_text
FROM cms_contact_lead l
LEFT JOIN gxwebsoft_core.sys_user au ON l.assigned_user_id = au.user_id
LEFT JOIN gxwebsoft_core.sys_user ru ON l.referrer_user_id = ru.user_id
LEFT JOIN gxwebsoft_core.sys_user admin ON l.dispatch_admin_id = admin.user_id
WHERE l.deleted = 0;