forked from wangziqi/gongxue-base
113 lines
2.8 KiB
Markdown
113 lines
2.8 KiB
Markdown
# 修复学生导入：姓名与账号字段 — 设计文档
|
||
|
||
> 日期：2026-07-10
|
||
> 状态：已确认
|
||
> 关联：PRD 钉钉集成批次 2
|
||
|
||
---
|
||
|
||
## 1. 背景
|
||
|
||
`batchImportStudents` 创建 Student 时：
|
||
- `name` 填的是占位符 `dd_${dingUserId}`
|
||
- `phone` 未设置
|
||
|
||
正确行为：
|
||
- `name` = 钉钉用户真实姓名
|
||
- `phone` = 钉钉用户手机号；无手机号时填 `dt_${dingUserId}`
|
||
|
||
## 2. 方案：前端传用户信息
|
||
|
||
前端组织架构树已有 `{ userid, name, mobile }` 数据（来自 `getDeptUsers`），导入时直接传给后端，零额外钉钉 API 调用。
|
||
|
||
## 3. 改动清单
|
||
|
||
### 3.1 后端 DTO
|
||
|
||
**文件：** `apps/server/src/classes/dto/class.dto.ts`
|
||
|
||
`BatchImportStudentsDto`:
|
||
|
||
```typescript
|
||
// 旧
|
||
export class BatchImportStudentsDto {
|
||
dingUserIds: string[];
|
||
}
|
||
|
||
// 新
|
||
export class BatchImportStudentsDto {
|
||
@IsArray() @ArrayNotEmpty()
|
||
users: Array<{ dingUserId: string; name: string; mobile?: string }>;
|
||
}
|
||
```
|
||
|
||
`CreateClassDto.dingUserIds` 同改为 `users` 字段。
|
||
|
||
### 3.2 后端 Service
|
||
|
||
**文件：** `apps/server/src/classes/classes.service.ts`
|
||
|
||
`batchImportStudents` 签名改为：
|
||
|
||
```typescript
|
||
async batchImportStudents(classId: number, users: Array<{
|
||
dingUserId: string; name: string; mobile?: string;
|
||
}>): Promise<{ imported: number; skipped: number }>
|
||
```
|
||
|
||
创建 Student 时：
|
||
|
||
```typescript
|
||
this.studentRepo.create({
|
||
name: u.name,
|
||
phone: u.mobile || `dt_${u.dingUserId}`,
|
||
status: 'active',
|
||
})
|
||
```
|
||
|
||
`create()` 方法中 `dingUserIds` → `users` 透传。
|
||
|
||
### 3.3 后端 Controller
|
||
|
||
**文件：** `apps/server/src/classes/classes.controller.ts`
|
||
|
||
`batchImportStudents` 端点传参改为：
|
||
|
||
```typescript
|
||
return this.service.batchImportStudents(+id, dto.users);
|
||
```
|
||
|
||
### 3.4 前端
|
||
|
||
**文件：** `apps/admin/src/pages/IntegrationConfig/index.tsx`
|
||
|
||
`handleJoinClass` 和 `handleCreateClass`：从 `checkedKeys` 反查 `orgTree` 提取完整用户信息，不再只传 ID。
|
||
|
||
```typescript
|
||
// 旧
|
||
const userIds = checkedKeys.filter(...).map(k => k.replace('user-', ''));
|
||
api.post('/classes/.../import', { dingUserIds: userIds });
|
||
|
||
// 新
|
||
const checkedUsers = extractCheckedUsers(checkedKeys, orgTree);
|
||
api.post('/classes/.../import', { users: checkedUsers });
|
||
```
|
||
|
||
`extractCheckedUsers` 工具函数遍历 `orgTree`，匹配 `checkedKeys` 中的 user 节点，返回 `{ dingUserId, name, mobile }[]`。
|
||
|
||
## 4. 不改的
|
||
|
||
- `DingTalkService.syncOneUser` / `syncAll` — 不受影响
|
||
- `Student` entity — 字段不变
|
||
- 数据库 schema — 不变
|
||
- `StudentDingMapping` — 不受影响
|
||
|
||
## 5. 验收标准
|
||
|
||
1. 导入新用户后，Student.name 为真实姓名，非 `dd_xxx`
|
||
2. 有手机号的用户，Student.phone = 手机号
|
||
3. 无手机号的用户，Student.phone = `dt_<dingUserId>`
|
||
4. 已存在 mapping 的用户跳过，不重复创建
|
||
5. 班级创建时传入 `users` 同样生效
|
||
6. `tsc --noEmit` 编译通过
|