hzhub/docs/crm-bug-fix-report.md

# CRM线索管理功能问题修复报告

## 发现的问题

### 问题1：新增线索时缺少手机号格式验证

**问题描述**：
- 后端：CrmLeadBo缺少手机号格式校验注解
- 前端：新建线索表单缺少手机号格式验证

**影响**：
- 用户可以输入任意格式的手机号，导致数据质量下降

---

### 问题2：负责人显示为手机号而非姓名

**问题描述**：
- UserNameTranslationImpl翻译类调用userService.selectUserNameById返回userName（登录账号）
- 应该调用userService.selectNicknameById返回nickName（用户昵称/真实姓名）

**影响**：
- 线索列表负责人列显示登录账号（如admin），而不是用户真实姓名（如管理员）
- 用户期望看到负责人姓名，而非登录账号

---

## 修复方案

### 问题1修复：手机号格式验证

#### 后端修复

**修改文件**：`hzhub-system/src/main/java/org/hzhub/crm/domain/bo/CrmLeadBo.java`

**修改内容**：
```java
// 导入Pattern注解
import jakarta.validation.constraints.Pattern;

// mobile字段添加正则验证
@NotBlank(message = "手机号不能为空")
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
@Size(min = 0, max = 50, message = "手机号长度不能超过{max}个字符")
private String mobile;
```

**正则表达式说明**：
- `^1` - 以1开头
- `[3-9]` - 第二位为3-9
- `\d{9}` - 后面9位为数字
- `$` - 结尾

验证中国手机号格式：13x, 14x, 15x, 16x, 17x, 18x, 19x开头的11位数字

---

#### 前端修复

**修改文件**：`hzhub-portal-employee/src/pages/crm/index.vue`

**修改内容**：

1. **添加手机号验证函数**：
```typescript
// 手机号验证规则
const mobileValidator = (value: string) => {
  if (!value) {
    return '请输入手机号';
  }
  const mobileRegex = /^1[3-9]\d{9}$/;
  if (!mobileRegex.test(value)) {
    return '手机号格式不正确';
  }
  return '';
};
```

2. **修改submitLead方法添加验证**：
```typescript
async function submitLead() {
  if (!leadForm.value.companyName || !leadForm.value.contactName || !leadForm.value.mobile) {
    ElMessage.warning('请填写必填信息');
    return;
  }

  // 验证手机号格式
  const mobileError = mobileValidator(leadForm.value.mobile);
  if (mobileError) {
    ElMessage.warning(mobileError);
    return;
  }

  try {
    await createLead(leadForm.value);
    ElMessage.success('线索创建成功');
    showAddLeadDialog.value = false;
    await loadLeads();
  }
  catch (error: any) {
    ElMessage.error(error?.message || '创建线索失败');
  }
}
```

---

### 问题2修复：负责人显示姓名

#### 后端修复

**修改文件**：`hzhub-ai/hzhub-common/hzhub-common-translation/src/main/java/org/hzhub/common/translation/core/impl/UserNameTranslationImpl.java`

**修改内容**：
```java
@Override
public String translation(Object key, String other) {
    if (key instanceof Long id) {
        // 返回用户昵称而不是登录账号
        return userService.selectNicknameById(id);
    }
    return null;
}
```

**修复说明**：
- 从调用`selectUserNameById`改为调用`selectNicknameById`
- `selectNicknameById`返回用户昵称（真实姓名），而不是登录账号
- 使用缓存`@Cacheable(cacheNames = CacheNames.SYS_NICKNAME)`，性能更好

**影响范围**：
- 所有使用`USER_ID_TO_NAME`翻译的地方都会显示用户昵称
- 包括：createBy, updateBy, ownerUserId, followUserId等字段

---

## 编译和部署

### 编译步骤

```bash
# 1. 编译hzhub-ai（包含translation模块修改）
cd /data/hzhub/hzhub-ai
mvn clean install -DskipTests

# 2. 编译hzhub-system（包含CrmLeadBo修改）
cd /data/hzhub/hzhub-system
mvn clean compile -DskipTests

# 3. 重启所有服务
cd /data/hzhub
./restart-all.sh
```

**编译结果**：
- ✅ hzhub-ai: BUILD SUCCESS (55.753s)
- ✅ hzhub-system: BUILD SUCCESS (19.007s)

---

## 测试验证

### 测试1：手机号格式验证

#### 后端验证测试

使用Postman或curl测试：

```bash
POST http://localhost:8080/crm/lead
Headers:
  Authorization: Bearer {token}
  ClientID: employee-portal
Body:
{
  "companyName": "测试公司",
  "contactName": "张三",
  "mobile": "12345678901",  // 错误格式
  "sourceType": "activity"
}
```

**预期响应**：
```json
{
  "code": 500,
  "msg": "手机号格式不正确"
}
```

#### 前端验证测试

**测试步骤**：
1. 登录员工门户：http://localhost:5137
2. 导航到"销售CRM" → "线索管理"
3. 点击"新建线索"
4. 输入错误手机号：12345678901
5. 点击"创建线索"

**预期结果**：
- 显示提示："手机号格式不正确"
- 表单不提交

---

### 测试2：负责人显示姓名

**测试步骤**：
1. 创建线索并分配负责人
2. 查看线索列表负责人列

**预期结果**：
- 负责人列显示用户真实姓名（如"管理员"）
- 不显示登录账号（如"admin")

**后端验证**：

```sql
-- 查询用户数据
SELECT user_id, user_name, nick_name, phonenumber FROM sys_user WHERE user_id = 1;

-- 预期结果：
-- user_name: admin (登录账号)
-- nick_name: 管理员 (真实姓名)
```

---

## 修复影响范围

### 手机号验证

**影响模块**：
- CRM线索管理（新建、编辑线索）
- 未来可能影响：经销商管理、客户管理

**数据质量提升**：
- 防止错误手机号数据进入系统
- 提升线索数据质量

---

### 负责人显示

**影响模块**：
- CRM线索管理（负责人显示）
- CRM经销商管理（负责人显示）
- 系统通知管理（创建人、更新人显示）
- OSS对象存储（创建人显示）
- 跟进记录（跟进人显示）

**用户体验提升**：
- 显示真实姓名，更符合用户认知
- 避免混淆登录账号和真实姓名

---

## 相关文档

- [CRM线索管理测试指引](docs/crm-testing-guide.md)
- [CRM线索转化测试指引](docs/crm-convert-testing-guide.md)
- [CRM线索分配删除测试指引](docs/crm-assign-delete-testing-guide.md)

---

## 总结

两个问题均已修复：
1. ✅ 手机号格式验证（后端Pattern注解 + 前端验证函数）
2. ✅ 负责人显示姓名（修改UserNameTranslationImpl返回昵称）

请重新测试验证功能。