docs/sprints/SPRINT_13_IMPLEMENTATION_PLAN.md

# Sprint 13 实施计划

**Sprint 周期**: 2026-04-09 至 2026-04-15  
**Sprint 目标**: 集中处理 P2 设计断链问题和功能完善  
**状态**: 📋 规划中

---

## 一、Sprint 目标

基于 Sprint 12 完成的基础建设，Sprint 13 将集中处理 P2 设计断链问题和功能完善，包括：

1. **系统设置页开发**（前后端）
2. **管理员管理页开发**（前端）
3. **全局设备管理页完善**（前端）
4. **设备信任功能完善**（前后端）
5. **前端 Vitest 3 个失败点修复**
6. **批量操作功能开发**（前端）

---

## 二、任务分解

### 2.1 P0 严重断链问题（优先级最高）

#### TASK-1: 系统设置 API 开发
**优先级**: P0 🔴  
**问题编号**: GAP-BE-001  
**工作量**: M（4天）  
**负责人**: 后端开发

**现状**:
- ❌ 系统设置 API 完全缺失

**需求**（基于 PRD 和专家评审）:
- 系统配置项：系统名称、Logo、Favicon、联系方式、版权信息
- 安全配置：密码策略（最小长度、复杂度）、会话超时时间、登录失败限制
- 通知配置：邮件服务器配置、短信服务配置
- 功能开关：注册开关、2FA 强制开关、设备信任开关

**实现步骤**:
1. **Day 1-2: 数据模型和 Repository**
   - 创建 `SystemSetting` domain 模型
   - 创建 `SystemSettingRepository`
   - 数据库迁移脚本

2. **Day 3-4: Service 和 Handler**
   - 创建 `SystemSettingService`
   - 创建 `SystemSettingHandler`
   - API 路由注册

**验收标准**:
- [ ] 所有配置项可 CRUD
- [ ] 配置变更立即生效（或需要重启）
- [ ] 敏感配置（邮件密码等）加密存储
- [ ] `go test ./...` 通过
- [ ] API 文档完整

**API 设计**:
```go
// 系统设置
GET    /api/v1/system/settings          // 获取所有设置
GET    /api/v1/system/settings/:key      // 获取单个设置
PUT    /api/v1/system/settings/:key      // 更新单个设置
POST   /api/v1/system/settings/batch     // 批量更新设置
GET    /api/v1/system/settings/categories // 按分类获取
```

---

#### TASK-2: 系统设置页开发
**优先级**: P0 🔴  
**问题编号**: GAP-FE-002  
**工作量**: M（3天）  
**负责人**: 前端开发

**现状**:
- ❌ 系统设置页完全缺失

**需求**:
- 分组显示：基本设置、安全设置、通知配置、功能开关
- 表单验证：必填项、格式验证
- 实时预览：系统名称、Logo 更改后立即预览
- 安全提示：修改敏感配置需要二次确认

**实现步骤**:
1. **Day 1: 页面结构**
   - 创建 `SystemSettingsPage.tsx`
   - 使用 `PageLayout` 组件
   - 创建表单布局

2. **Day 2: 表单逻辑**
   - 表单状态管理
   - 表单验证
   - API 调用

3. **Day 3: 功能完善**
   - 实时预览
   - 二次确认
   - 错误处理

**验收标准**:
- [ ] 所有设置项可编辑
- [ ] 表单验证正确
- [ ] 实时预览工作
- [ ] `npm run lint` 通过
- [ ] `npm test` 通过

**UI 参考**:
```
┌─────────────────────────────────────────┐
│ 系统设置                                │
├─────────────────────────────────────────┤
│ [基本设置] [安全设置] [通知配置] [开关]  │
├─────────────────────────────────────────┤
│ 基本设置                                │
│ ┌─────────────────────────────────┐   │
│ │ 系统名称: [_______________]     │   │
│ │ Logo:     [选择文件]            │   │
│ │ 联系方式: [_______________]     │   │
│ │ 版权信息: [_______________]     │   │
│ │          [保存] [重置]          │   │
│ └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

---

### 2.2 P0 严重断链问题（优先级高）

#### TASK-3: 管理员管理页开发
**优先级**: P0 🔴  
**问题编号**: GAP-FE-001  
**工作量**: M（3天）  
**负责人**: 前端开发

**现状**:
- ❌ 管理员管理页完全缺失
- ✅ 后端 API 已存在

**需求**:
- 管理员列表（分页、筛选）
- 创建管理员
- 编辑管理员
- 删除管理员
- 权限分配

**实现步骤**:
1. **Day 1: 页面结构**
   - 创建 `AdminsPage.tsx`
   - 使用 `PageLayout` + `TableCard` + `FilterCard`
   - 表格列设计

2. **Day 2: CRUD 操作**
   - 创建 `CreateAdminModal.tsx`
   - 创建 `EditAdminModal.tsx`
   - 删除确认

3. **Day 3: 权限分配**
   - 创建 `PermissionTreeSelector` 组件
   - 权限树显示和选择

**验收标准**:
- [ ] 所有 CRUD 操作正常
- [ ] 权限分配正确
- [ ] 防止删除自己和最后一个管理员
- [ ] `npm run lint` 通过

**API 对接**:
```typescript
// 后端 API 已存在
GET    /api/v1/admin/admins
POST   /api/v1/admin/admins
PUT    /api/v1/admin/admins/:id
DELETE /api/v1/admin/admins/:id
```

---

#### TASK-4: 全局设备管理页开发
**优先级**: P0 🔴  
**问题编号**: GAP-FE-003  
**工作量**: M（3天）  
**负责人**: 前端开发

**现状**:
- ⚠️ 个人设备管理已实现（`ProfileSecurityPage`）
- ❌ 全局设备管理页缺失

**需求**:
- 所有用户设备列表（分页、筛选）
- 设备详情
- 删除设备
- 取消信任设备
- 设备统计（总设备数、受信任设备数、活跃设备数）

**实现步骤**:
1. **Day 1: 页面结构**
   - 创建 `DevicesPage.tsx`
   - 使用 `PageLayout` + `TableCard` + `StatsCard`
   - 表格列设计

2. **Day 2: 设备操作**
   - 设备详情查看
   - 删除设备
   - 取消信任

3. **Day 3: 统计和筛选**
   - 设备统计卡片
   - 高级筛选（用户、设备类型、信任状态）

**验收标准**:
- [ ] 所有操作正常
- [ ] 统计数据准确
- [ ] `npm run lint` 通过

**API 设计**（需后端补充）:
```go
// 需要后端新增
GET    /api/v1/admin/devices               // 获取所有设备（管理员）
GET    /api/v1/admin/devices/:id           // 获取设备详情
DELETE /api/v1/admin/devices/:id           // 删除设备
PUT    /api/v1/admin/devices/:id/trust     // 信任/取消信任
GET    /api/v1/admin/devices/stats         // 设备统计
```

---

#### TASK-5: 登录日志导出功能
**优先级**: P0 🔴  
**问题编号**: GAP-FE-004  
**工作量**: S（1天）  
**负责人**: 前端开发

**现状**:
- ✅ 登录日志页已实现（`LoginLogsPage`）
- ❌ 导出功能缺失

**需求**:
- 导出 CSV
- 导出 Excel
- 支持筛选结果导出

**实现步骤**:
1. 使用 `xlsx` 库（前端已有）
2. 实现 Excel 导出函数
3. 添加导出按钮到 `LoginLogsPage`

**验收标准**:
- [ ] Excel 导出成功
- [ ] CSV 导出成功
- [ ] 导出内容正确

---

### 2.3 P1 中等断链问题

#### TASK-6: 设备信任功能完善
**优先级**: P1 🟡  
**问题编号**: GAP-INT-001  
**工作量**: M（4天）  
**负责人**: 后端 + 前端

**现状**:
- ✅ 设备 CRUD API 已实现
- ✅ 设备信任 API 已实现
- ❌ 登录流程未检查设备信任
- ❌ 前端未采集设备指纹

**后端实现**（2天）:
1. **Day 1: 登录接收设备标识**
   - 修改 `LoginRequest` 添加设备字段
   - 登录时自动记录设备

2. **Day 2: 2FA 检查设备信任**
   - TOTP 验证时检查设备是否已信任
   - 信任设备免 2FA

**前端实现**（2天）:
1. **Day 1: 登录时采集设备指纹**
   - 生成设备指纹（User-Agent + Screen + Timezone）
   - 登录请求携带设备信息

2. **Day 2: "记住此设备"功能**
   - 2FA 验证页面添加"记住此设备"复选框
   - 调用信任设备 API

**验收标准**:
- [ ] 登录时设备自动记录
- [ ] 信任设备免 2FA
- [ ] 信任过期后重新要求 2FA

---

#### TASK-7: 批量操作功能
**优先级**: P1 🟡  
**问题编号**: GAP-FE-005  
**工作量**: M（3天）  
**负责人**: 前端 + 后端

**现状**:
- ❌ 批量操作完全缺失

**需求**:
- 用户批量删除
- 角色批量删除
- 批量分配角色

**后端实现**（1天）:
- 批量删除 API
- 批量更新 API

**前端实现**（2天）:
1. **Day 1: 批量选择 UI**
   - 表格行选择
   - 全选/取消全选
   - 批量操作按钮

2. **Day 2: 批量操作逻辑**
   - 批量删除
   - 批量分配角色

**验收标准**:
- [ ] 批量选择正常
- [ ] 批量删除成功
- [ ] 批量分配角色成功

---

### 2.4 测试修复

#### TASK-8: 前端 Vitest 3 个失败点修复
**优先级**: P1 🟡  
**工作量**: S（2天）  
**负责人**: 前端开发

**现状**:
- ⚠️ Vitest 有 3 个失败点

**行动**:
1. 运行 `npm test` 查看失败详情
2. 逐个修复失败用例
3. 确保所有测试通过

**验收标准**:
- [ ] 所有 Vitest 测试通过
- [ ] 测试覆盖率 ≥ 70%

---

## 三、依赖关系

```
TASK-1 (系统设置 API) ────── TASK-2 (系统设置页)
     │
TASK-3 (管理员管理页) ────── 独立
     │
TASK-4 (设备管理页) ──────── TASK-6 (设备信任)
     │                           │
TASK-5 (登录日志导出) ──────────┘
     │
TASK-7 (批量操作) ─────────── 独立
     │
TASK-8 (Vitest 修复) ──────── 独立
```

**关键路径**:
1. TASK-1 必须先于 TASK-2
2. TASK-6 依赖 TASK-4 的设备管理 API

---

## 四、风险管理

### 4.1 技术风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| 系统设置 API 设计复杂 | 高 | 中 | 参考 Spring Boot Configuration 做法 |
| 设备指纹算法不稳定 | 高 | 中 | 使用成熟的指纹库（如 FingerprintJS） |
| 批量操作性能问题 | 中 | 中 | 使用异步处理和进度反馈 |

### 4.2 进度风险

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|---------|
| 后端 API 开发延期 | 高 | 中 | 优先完成核心 API，细节后续迭代 |
| 前端 UI 开发延期 | 中 | 低 | 使用 Ant Design 组件加速 |

---

## 五、资源分配

### 5.1 人员分配

| 任务 | 后端 | 前端 | 测试 |
|------|------|------|------|
| TASK-1: 系统设置 API | 1人 | - | - |
| TASK-2: 系统设置页 | - | 1人 | - |
| TASK-3: 管理员管理页 | - | 1人 | - |
| TASK-4: 设备管理页 | 0.5人 | 1人 | - |
| TASK-5: 登录日志导出 | - | 0.5人 | - |
| TASK-6: 设备信任完善 | 1人 | 1人 | - |
| TASK-7: 批量操作 | 0.5人 | 1人 | - |
| TASK-8: Vitest 修复 | - | 0.5人 | - |

### 5.2 工作量汇总

- **后端**: 4 人天
- **前端**: 7 人天
- **总计**: 11 人天

---

## 六、验收标准

### 6.1 功能验收

**系统设置**:
- [ ] 所有配置项可 CRUD
- [ ] 配置变更生效
- [ ] 敏感配置加密

**管理员管理**:
- [ ] CRUD 操作正常
- [ ] 权限分配正确
- [ ] 防止删除自己

**设备管理**:
- [ ] 设备列表正常
- [ ] 设备操作正常
- [ ] 统计数据准确

**设备信任**:
- [ ] 设备自动记录
- [ ] 信任设备免 2FA

**批量操作**:
- [ ] 批量选择正常
- [ ] 批量操作成功

### 6.2 质量验收

- [ ] `go test ./...` 通过
- [ ] `go vet ./...` 通过
- [ ] `go build ./cmd/server` 成功
- [ ] `npm run lint` 通过
- [ ] `npm test` 全部通过
- [ ] `npm run build` 成功
- [ ] `npm run e2e:full:win` 通过

### 6.3 文档验收

- [ ] API 文档更新
- [ ] README 更新
- [ ] 部署文档更新

---

## 七、Sprint 检查点

### Sprint 开启（Day 1）
- [ ] Sprint 计划评审
- [ ] 任务分配
- [ ] 开发环境准备

### Sprint 中期（Day 5）
- [ ] 进度检查
- [ ] 问题识别
- [ ] 风险评估

### Sprint 结束（Day 7）
- [ ] 功能验收
- [ ] 质量验收
- [ ] Sprint 回顾
- [ ] 下一 Sprint 准备

---

## 八、Sprint 13 交付物

1. **系统设置功能**
   - 后端 API
   - 前端页面
   - API 文档

2. **管理员管理页**
   - 前端页面
   - 功能文档

3. **设备管理页**
   - 后端 API
   - 前端页面
   - API 文档

4. **设备信任完善**
   - 后端实现
   - 前端实现
   - 测试用例

5. **批量操作功能**
   - 后端 API
   - 前端功能

6. **测试修复**
   - Vitest 全部通过
   - 测试报告

---

**计划制定时间**: 2026-04-02  
**计划制定人**: 高级项目经理  
**审核状态**: 待审核