junhong_cmp_fiber/openspec/changes/archive/2026-01-14-add-platform-account-management/tasks.md

实现任务清单

1. 准备工作

• 1.1 阅读现有账号管理代码（Handler/Service/Store）
• 1.2 确认现有 DTO 定义和验证规则
• 1.3 确认现有路由注册模式

2. Model 层（DTO 定义）

• 2.1 在 internal/model/account_dto.go 中新增 UpdatePasswordRequest
  • 字段：new_password (必填，8-32位)
• 2.2 在 internal/model/account_dto.go 中新增 UpdateStatusRequest
  • 字段：status (必填，0 或 1)
• 2.3 在 internal/model/account_dto.go 中新增 PlatformAccountListRequest
  • 复用 AccountListRequest，移除 user_type 字段
• 2.4 修改 AssignRolesRequest
  • 将 role_ids 验证规则从 required,min=1 改为 omitempty
  • 允许空数组

3. Service 层（业务逻辑）

• 3.1 在 internal/service/account/service.go 中新增 UpdatePassword 方法
  • 验证账号存在
  • 验证密码格式
  • bcrypt 哈希新密码
  • 更新数据库
  • 设置 Updater 字段
• 3.2 在 internal/service/account/service.go 中新增 UpdateStatus 方法
  • 验证账号存在
  • 验证状态值（0 或 1）
  • 更新数据库
  • 设置 Updater 字段
• 3.3 在 internal/service/account/service.go 中新增 ListPlatformAccounts 方法
  • 自动筛选 user_type IN (1, 2)
  • 支持 username, phone, status 筛选
  • 支持分页
  • 返回账号列表 + 总数
• 3.4 修改 AssignRoles 方法
  • 支持 roleIDs 为空数组（清空所有角色）
  • 超级管理员（user_type=1）禁止分配角色，返回错误
  • 空数组时删除所有现有角色
  • 非空数组时保持现有逻辑

4. Handler 层（HTTP 处理）

• 4.1 在 internal/handler/admin/account.go 中新增 UpdatePassword 方法
  • 解析路径参数 id
  • 解析请求 body (UpdatePasswordRequest)
  • 调用 service.UpdatePassword
  • 返回 response.Success(c, nil)
• 4.2 在 internal/handler/admin/account.go 中新增 UpdateStatus 方法
  • 解析路径参数 id
  • 解析请求 body (UpdateStatusRequest)
  • 调用 service.UpdateStatus
  • 返回 response.Success(c, nil)
• 4.3 在 internal/handler/admin/account.go 中新增 ListPlatformAccounts 方法
  • 解析查询参数 (PlatformAccountListRequest)
  • 调用 service.ListPlatformAccounts
  • 返回 response.SuccessWithPagination(c, accounts, total, req.Page, req.PageSize)

5. 路由注册

• 5.1 在 internal/routes/account.go 中新增 registerPlatformAccountRoutes 函数
  • 注册 GET /api/admin/platform-accounts → h.ListPlatformAccounts
  • 注册 POST /api/admin/platform-accounts → h.Create（复用现有）
  • 注册 GET /api/admin/platform-accounts/:id → h.Get（复用现有）
  • 注册 PUT /api/admin/platform-accounts/:id → h.Update（复用现有）
  • 注册 DELETE /api/admin/platform-accounts/:id → h.Delete（复用现有）
  • 注册 PUT /api/admin/platform-accounts/:id/password → h.UpdatePassword
  • 注册 PUT /api/admin/platform-accounts/:id/status → h.UpdateStatus
  • 注册 POST /api/admin/platform-accounts/:id/roles → h.AssignRoles（复用现有）
  • 注册 GET /api/admin/platform-accounts/:id/roles → h.GetRoles（复用现有）
  • 注册 DELETE /api/admin/platform-accounts/:id/roles/:role_id → h.RemoveRole（复用现有）
• 5.2 在 internal/routes/router.go 中调用 registerPlatformAccountRoutes

6. 错误码定义

• 6.1 检查 pkg/errors/codes.go 中是否有所需错误码
  • CodeAccountNotFound (已有)
  • CodeInvalidPassword (已有)
  • CodeInvalidParam (已有)
  • CodeUnauthorized (已有)
• 6.2 如需新增，添加错误码和消息

7. 常量定义

• 7.1 检查 pkg/constants/constants.go 中状态常量
  • StatusDisabled = 0 (已有)
  • StatusEnabled = 1 (已有)
  • UserTypeSuperAdmin = 1 (已有)
  • UserTypePlatform = 2 (已有)

8. 单元测试

• 8.1 为 UpdatePassword 方法编写单元测试
  • 测试成功场景
  • 测试账号不存在场景
  • 测试密码格式错误场景
• 8.2 为 UpdateStatus 方法编写单元测试
  • 测试启用/禁用场景
  • 测试账号不存在场景
  • 测试无效状态值场景
• 8.3 为 ListPlatformAccounts 方法编写单元测试
  • 测试自动筛选 user_type IN (1,2)
  • 测试分页功能
  • 测试筛选条件（username, phone, status）
• 8.4 为修改后的 AssignRoles 方法编写测试
  • 测试空数组清空角色场景
  • 测试超级管理员禁止分配角色场景
  • 测试平台用户分配角色场景

9. 集成测试

• 9.1 编写 API 集成测试（tests/integration/platform_account_test.go）
  • 测试平台账号列表查询
  • 测试新增平台账号
  • 测试修改密码接口
  • 测试启用/禁用接口
  • 测试角色分配（含空数组场景）
• 9.2 测试超级管理员保护逻辑
  • 超级管理员出现在列表中
  • 超级管理员禁止分配角色

10. 文档更新

• 10.1 更新 OpenAPI 文档（如果使用 openapi-generation）
• 10.2 在 docs/ 目录创建功能总结文档
  • 接口列表
  • 请求/响应示例
  • 错误码说明
  • 注意事项（超级管理员保护、角色清空等）

11. 验证与清理

• 11.1 运行所有单元测试：go test ./internal/service/account/...
• 11.2 运行集成测试：go test ./tests/integration/...
• 11.3 使用 openspec validate add-platform-account-management --strict 验证提案
• 11.4 代码格式化：gofmt -w .
• 11.5 静态检查：go vet ./...

12. 部署准备

• 12.1 确认无数据库迁移需求
• 12.2 确认向后兼容（现有接口不受影响）
• 12.3 准备发布说明（新增接口列表、使用示例）