forked from wangziqi/gongxue-base
391 lines
9.7 KiB
Markdown
391 lines
9.7 KiB
Markdown
# 修复学生导入姓名与账号 — 实现计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 修复批量导入学生时 name 填占位符 `dd_xxx`、phone 未设置的问题，改为使用前端传入的真实姓名和手机号。
|
||
|
||
**Architecture:** 前端已有钉钉用户 name/mobile 数据，导入时随请求传给后端，后端直接用于创建 Student，零额外钉钉 API 调用。
|
||
|
||
**Tech Stack:** NestJS + TypeORM + React + Ant Design
|
||
|
||
## Global Constraints
|
||
|
||
- 不改 Student entity / 数据库 schema
|
||
- 不改 DingTalkService
|
||
- 不改 StudentDingMapping
|
||
- `tsc --noEmit` 编译通过
|
||
|
||
---
|
||
|
||
### Task 1: 后端 DTO — 字段改名
|
||
|
||
**Files:**
|
||
- Modify: `apps/server/src/classes/dto/class.dto.ts`
|
||
|
||
**Interfaces:**
|
||
- Consumes: nothing
|
||
- Produces: `CreateClassDto.users`, `BatchImportStudentsDto.users`
|
||
|
||
- [ ] **Step 1: 改 BatchImportStudentsDto**
|
||
|
||
`class.dto.ts` 第 136-141 行：
|
||
|
||
```typescript
|
||
export class BatchImportStudentsDto {
|
||
@IsArray()
|
||
@IsString({ each: true })
|
||
@ArrayNotEmpty()
|
||
dingUserIds: string[];
|
||
}
|
||
```
|
||
|
||
改为：
|
||
|
||
```typescript
|
||
export class BatchImportStudentsDto {
|
||
@IsArray()
|
||
@ArrayNotEmpty()
|
||
@ValidateNested({ each: true })
|
||
@Type(() => ImportUserItem)
|
||
users: ImportUserItem[];
|
||
}
|
||
|
||
export class ImportUserItem {
|
||
@IsString() @IsNotEmpty()
|
||
dingUserId: string;
|
||
|
||
@IsString() @IsNotEmpty()
|
||
name: string;
|
||
|
||
@IsOptional() @IsString()
|
||
mobile?: string;
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 改 CreateClassDto**
|
||
|
||
第 43-46 行，`dingUserIds` 字段：
|
||
|
||
```typescript
|
||
@IsArray()
|
||
@IsString({ each: true })
|
||
@IsOptional()
|
||
dingUserIds?: string[];
|
||
```
|
||
|
||
改为：
|
||
|
||
```typescript
|
||
@IsOptional()
|
||
@IsArray()
|
||
@ValidateNested({ each: true })
|
||
@Type(() => ImportUserItem)
|
||
users?: ImportUserItem[];
|
||
```
|
||
|
||
- [ ] **Step 3: 补 import**
|
||
|
||
文件头部 import 行（第 1 行），追加 `ValidateNested`：
|
||
|
||
```typescript
|
||
import { IsOptional, IsString, IsNotEmpty, IsInt, IsArray, IsDateString, IsEnum, ArrayNotEmpty, ValidateNested } from 'class-validator';
|
||
```
|
||
|
||
- [ ] **Step 4: 编译验证**
|
||
|
||
```bash
|
||
cd apps/server && npx tsc --noEmit 2>&1 | head -20
|
||
```
|
||
|
||
预期：Pass（如果后续 Task 没改完会有 type error，属于预期）
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add apps/server/src/classes/dto/class.dto.ts
|
||
git commit -m "feat: change dingUserIds to users array with name/mobile in DTOs"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: 后端 Service — 使用真实 name 和 phone
|
||
|
||
**Files:**
|
||
- Modify: `apps/server/src/classes/classes.service.ts:96-191`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `BatchImportStudentsDto.users`, `CreateClassDto.users` (from Task 1)
|
||
- Produces: updated `batchImportStudents` signature
|
||
|
||
- [ ] **Step 1: 改 create() 方法**
|
||
|
||
第 96-128 行，两处 `dingUserIds` → `users`：
|
||
|
||
```typescript
|
||
async create(dto: CreateClassDto) {
|
||
const { studentIds, teachers, users, ...classData } = dto;
|
||
…
|
||
// batch import students by dingUserIds
|
||
if (users?.length) {
|
||
await this.batchImportStudents(saved.id, users);
|
||
}
|
||
…
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 改 batchImportStudents 签名和逻辑**
|
||
|
||
第 131-191 行：
|
||
|
||
```typescript
|
||
async batchImportStudents(classId: number, users: Array<{
|
||
dingUserId: string; name: string; mobile?: string;
|
||
}>): Promise<{ imported: number; skipped: number }> {
|
||
const classEntity = await this.classRepo.findOne({ where: { id: classId } });
|
||
if (!classEntity) throw new NotFoundException('班级不存在');
|
||
|
||
if (users.length === 0) return { imported: 0, skipped: 0 };
|
||
|
||
const dingUserIds = users.map(u => u.dingUserId);
|
||
|
||
// 1. Fetch all existing ding mappings in one query
|
||
const existingMappings = await this.studentDingMappingRepo.find({
|
||
where: { dingUserId: In(dingUserIds) },
|
||
});
|
||
const dingToStudentId = new Map(existingMappings.map(m => [m.dingUserId, m.studentId]));
|
||
|
||
// 2. Batch create students for new dingUserIds
|
||
const newUsers = users.filter(u => !dingToStudentId.has(u.dingUserId));
|
||
if (newUsers.length > 0) {
|
||
const newStudents = newUsers.map(u =>
|
||
this.studentRepo.create({
|
||
name: u.name,
|
||
phone: u.mobile || `dt_${u.dingUserId}`,
|
||
status: 'active',
|
||
})
|
||
);
|
||
const savedStudents = await this.studentRepo.save(newStudents);
|
||
|
||
const newMappings = savedStudents.map((s, i) =>
|
||
this.studentDingMappingRepo.create({ dingUserId: newUsers[i].dingUserId, studentId: s.id })
|
||
);
|
||
await this.studentDingMappingRepo.save(newMappings);
|
||
|
||
for (let i = 0; i < newUsers.length; i++) {
|
||
dingToStudentId.set(newUsers[i].dingUserId, savedStudents[i].id);
|
||
}
|
||
}
|
||
|
||
// 3. Fetch existing class-student links in one query
|
||
const allStudentIds = Array.from(dingToStudentId.values());
|
||
… // 不变
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 3: 编译验证**
|
||
|
||
```bash
|
||
cd apps/server && npx tsc --noEmit 2>&1 | head -20
|
||
```
|
||
|
||
预期：Pass
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add apps/server/src/classes/classes.service.ts
|
||
git commit -m "fix: use real name and phone from frontend when importing students"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: 后端 Controller — 传参修正
|
||
|
||
**Files:**
|
||
- Modify: `apps/server/src/classes/classes.controller.ts:93-98`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `BatchImportStudentsDto.users` (from Task 1)
|
||
- Produces: nothing new
|
||
|
||
- [ ] **Step 1: 改 controller 传参**
|
||
|
||
第 97 行：
|
||
|
||
```typescript
|
||
return this.service.batchImportStudents(+id, dto.users);
|
||
```
|
||
|
||
- [ ] **Step 2: 编译验证**
|
||
|
||
```bash
|
||
cd apps/server && npx tsc --noEmit 2>&1 | head -20
|
||
```
|
||
|
||
预期：Pass
|
||
|
||
- [ ] **Step 3: Commit**
|
||
|
||
```bash
|
||
git add apps/server/src/classes/classes.controller.ts
|
||
git commit -m "fix: pass dto.users instead of dto.dingUserIds in controller"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: 前端 — 传用户信息而非仅 ID
|
||
|
||
**Files:**
|
||
- Modify: `apps/admin/src/pages/IntegrationConfig/index.tsx`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `orgTree` (state), `checkedKeys` (state)
|
||
- Produces: updated API call payloads
|
||
|
||
- [ ] **Step 1: 写 extractCheckedUsers 工具函数**
|
||
|
||
在 `handleJoinClass` 上方插入：
|
||
|
||
```typescript
|
||
const extractCheckedUsers = useCallback((): Array<{ dingUserId: string; name: string; mobile?: string }> => {
|
||
const result: Array<{ dingUserId: string; name: string; mobile?: string }> = [];
|
||
const walk = (nodes: DingOrgTreeNodeExt[]) => {
|
||
for (const node of nodes) {
|
||
for (const u of node.users) {
|
||
if (checkedKeys.includes(`user-${u.userid}`)) {
|
||
result.push({ dingUserId: u.userid, name: u.name, mobile: u.mobile || undefined });
|
||
}
|
||
}
|
||
walk(node.children);
|
||
}
|
||
};
|
||
walk(orgTree);
|
||
return result;
|
||
}, [checkedKeys, orgTree]);
|
||
```
|
||
|
||
- [ ] **Step 2: 改 handleJoinClass**
|
||
|
||
第 212-231 行，旧代码：
|
||
|
||
```typescript
|
||
const handleJoinClass = async () => {
|
||
if (selectedClassId === null) return message.warning('请先选择一个班级');
|
||
const userIds = checkedKeys
|
||
.filter((k) => String(k).startsWith('user-'))
|
||
.map((k) => String(k).replace('user-', ''));
|
||
if (userIds.length === 0) return message.warning('请勾选要导入的用户');
|
||
|
||
setImporting(true);
|
||
try {
|
||
const res = await api.post<ImportResult>(`/classes/${selectedClassId}/students/import`, { dingUserIds: userIds });
|
||
message.success(`导入 ${res.imported} 人，跳过 ${res.skipped} 人`);
|
||
setCheckedKeys([]);
|
||
setSelectedClassId(null);
|
||
} catch (e: unknown) {
|
||
const err = e as { message?: string };
|
||
message.error(err?.message || '导入失败');
|
||
} finally {
|
||
setImporting(false);
|
||
}
|
||
};
|
||
```
|
||
|
||
改为：
|
||
|
||
```typescript
|
||
const handleJoinClass = async () => {
|
||
if (selectedClassId === null) return message.warning('请先选择一个班级');
|
||
const users = extractCheckedUsers();
|
||
if (users.length === 0) return message.warning('请勾选要导入的用户');
|
||
|
||
setImporting(true);
|
||
try {
|
||
const res = await api.post<ImportResult>(`/classes/${selectedClassId}/students/import`, { users });
|
||
message.success(`导入 ${res.imported} 人，跳过 ${res.skipped} 人`);
|
||
setCheckedKeys([]);
|
||
setSelectedClassId(null);
|
||
} catch (e: unknown) {
|
||
const err = e as { message?: string };
|
||
message.error(err?.message || '导入失败');
|
||
} finally {
|
||
setImporting(false);
|
||
}
|
||
};
|
||
```
|
||
|
||
- [ ] **Step 3: 改 handleCreateClass**
|
||
|
||
第 233-251 行：
|
||
|
||
```typescript
|
||
const handleCreateClass = async () => {
|
||
try {
|
||
const values = await classForm.validateFields();
|
||
const users = extractCheckedUsers();
|
||
await api.post('/classes', { ...values, users });
|
||
message.success('班级创建成功');
|
||
setClassModalOpen(false);
|
||
classForm.resetFields();
|
||
setCheckedKeys([]);
|
||
fetchClasses();
|
||
} catch (e: unknown) {
|
||
const err = e as { message?: string };
|
||
message.error(err?.message || '创建失败');
|
||
} finally {
|
||
setImporting(false);
|
||
}
|
||
};
|
||
```
|
||
|
||
（关键变更：`dingUserIds: userIds` → `users`，删除手动的 `.filter().map()` 逻辑）
|
||
|
||
- [ ] **Step 4: 前端编译验证**
|
||
|
||
```bash
|
||
cd apps/admin && npx tsc --noEmit 2>&1 | head -20
|
||
```
|
||
|
||
预期：Pass
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add apps/admin/src/pages/IntegrationConfig/index.tsx
|
||
git commit -m "fix: pass user name and mobile to backend when importing students"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: 端到端验证
|
||
|
||
- [ ] **Step 1: 后端全量编译**
|
||
|
||
```bash
|
||
cd apps/server && npx tsc --noEmit
|
||
```
|
||
|
||
预期：0 errors
|
||
|
||
- [ ] **Step 2: 前端全量编译**
|
||
|
||
```bash
|
||
cd apps/admin && npx tsc --noEmit
|
||
```
|
||
|
||
预期：0 errors
|
||
|
||
- [ ] **Step 3: 后端测试**
|
||
|
||
```bash
|
||
cd apps/server && npm test 2>&1 | tail -20
|
||
```
|
||
|
||
预期：现有测试全部通过
|
||
|
||
- [ ] **Step 4: Commit（如有遗漏）**
|
||
|
||
```bash
|
||
git status
|
||
```
|