# 2026-04-14 日志

## 项目：客资管理系统（Customer Lead Management System）

### 需求背景
用户委托开发一个客资管理系统，具备以下功能：
1. **客资派单** - 管理员直接派单给业务员
2. **全民推荐** - 任何人可推荐客户赚取推荐费
3. **推荐人报备** - 注册用户可报备客户
4. **实时跟进** - 实时查看跟进情况和成交状态
5. **多管理员** - 支持多管理员设置
6. **数据统计导出** - 统计报表功能

### 涉及项目
- Java后端: `/Users/gxwebsoft/JAVA/mp-java`
- Vue后台管理: `/Users/gxwebsoft/VUE/mp-vue`
- 小程序端: `/Users/gxwebsoft/VUE/template-10582`

### 状态
- [x] 探索代码结构
- [x] 设计数据库schema
- [x] 设计API接口
- [x] 实施开发

### 实施成果

#### Java后端 (`/Users/gxwebsoft/JAVA/mp-java`)
- SQL脚本: `docs/sql/customer_lead_system.sql`
- Entity: CustomerLeadEntity, LeadDispatch, LeadFollowLog, LeadReferral, LeadStatistics, UserRoleExtend
- Mapper: CustomerLeadMapper, LeadDispatchMapper, LeadFollowLogMapper, LeadReferralMapper
- Service: CustomerLeadService, LeadReferralService
- Controller: CustomerLeadController, LeadReferralController
- 总结文档: `docs/ai/customer-lead-system-summary.md`

#### Vue后台 (`/Users/gxwebsoft/VUE/mp-vue`)
- API: `api/cms/customerLead/index.ts`, `model.ts`
- 页面: `views/cms/customerLead/index.vue`

#### 小程序端 (`/Users/gxwebsoft/VUE/template-10582`)
- API: `api/shop/referral.ts`
- 页面: `dealer/referral/index.tsx`
- 首页入口: 在分销商首页添加「推荐客户」功能

### 编译错误修复（10:14）
1. **Controller层** - `R.ok()` → `ApiResult` + `success()`，两个Controller均继承 `BaseController`
   - `CustomerLeadController`: 去掉 `import R`，改用 `ApiResult` + `extends BaseController`
   - `LeadReferralController`: 同上

2. **Service层** - `userService.getLoginUser()` 方法不存在
   - `CustomerLeadServiceImpl`: 去掉 `UserService` 注入，改用私有 `getLoginUser()` 方法（通过 `SecurityContextHolder` 实现，与 `BaseController` 逻辑一致）
   - `LeadReferralServiceImpl`: 同上；另外修正 `userService.getUserById()` → `userService.getByIdRel()`（`UserService` 仍保留用于按ID查询用户）

**项目规范记录**：
- 返回值用 `ApiResult<T>` + `success()`，Controller继承 `BaseController`
- Service层获取登录用户：`SecurityContextHolder.getContext().getAuthentication().getPrincipal()` 强转 `User`
- 按ID查询用户：`userService.getByIdRel(userId)`（非 `getUserById`）

### 推荐客户模块重构（2026-04-16）
- **包名变更**：`cms.LeadReferralController` → `app.recommendation.LeadReferralController`
- **API路径**：`/lead/referral` → `/app/lead/referral`
- **数据库表前缀**：`cms_contact_lead` → `app_lead_referral`

#### 新建文件清单
| 项目 | 文件 |
|------|------|
| Java后端 | `app/recommendation/entity/LeadReferral.java` |
| | `app/recommendation/entity/ReferrerInfo.java` |
| | `app/recommendation/entity/ReferralSettlement.java` |
| | `app/recommendation/mapper/LeadReferralMapper.java` |
| | `app/recommendation/mapper/ReferrerInfoMapper.java` |
| | `app/recommendation/mapper/ReferralSettlementMapper.java` |
| | `app/recommendation/service/LeadReferralService.java` |
| | `app/recommendation/service/impl/LeadReferralServiceImpl.java` |
| | `app/recommendation/controller/LeadReferralController.java`（小程序端） |
| | `app/recommendation/controller/LeadReferralAdminController.java`（后台管理） |
| | `app/recommendation/param/LeadReferralParam.java` |
| | `resources/db/sql/app_lead_referral.sql` |
| 小程序 | `src/api/app/referral.ts`（新API） |
| | `src/recommendation/index.tsx`（独立推荐页面） |
| | `src/recommendation/index.scss` |
| | `src/dealer/referral/index.tsx`（改用新API） |
| | `src/app.config.ts`（新增recommendation子包路由） |
| Vue后台 | `src/api/app/referral.ts` |
| | `src/views/cms/recommendation/index.vue` |
