junhong_cmp_fiber/openspec/changes/archive/2026-04-18-super-admin-operation-password/tasks.md

1. Redis Key 常量

• 1.1 在 pkg/constants/redis.go 中添加全局操作密码 Redis Key 生成函数 RedisSystemOperationPasswordKey() string，返回固定字符串 "system:operation_password"
• 1.2 运行 lsp_diagnostics 确认 redis.go 无错误

2. DTO 层

• 2.1 新建 internal/model/dto/super_admin_dto.go，定义以下结构体：
  • SetOperationPasswordRequest：字段 Password（validate:"required,min=6,max=50"）、ConfirmPassword（validate:"required"），含 description 标签
  • OperationPasswordStatusResponse：字段 IsSet bool，含 description 标签
• 2.2 运行 lsp_diagnostics 确认 super_admin_dto.go 无错误

3. OperationPassword Service

• 3.1 新建 internal/service/operation_password/service.go，实现以下方法：
  • Set(ctx, password string) error：bcrypt 哈希后写入 Redis（永久存储，无 TTL）
  • IsSet(ctx) bool：查询 Redis key 是否存在
  • Verify(ctx, inputPassword string) error：从 Redis 读取哈希值，用 bcrypt.CompareHashAndPassword 对比；key 不存在时返回"操作密码未设置，请联系超级管理员"，密码错误时返回"操作密码错误"
  • Service 结构体通过构造函数注入 *redis.Client
• 3.2 运行 lsp_diagnostics 确认 operation_password/service.go 无错误

4. SuperAdmin Handler

• 4.1 新建 internal/handler/admin/super_admin.go，实现以下接口：
  • SetOperationPassword（POST /api/admin/super-admin/operation-password）：检查 user_type == UserTypeSuperAdmin，验证两次密码一致，调用 operationPasswordService.Set()
  • GetOperationPasswordStatus（GET /api/admin/super-admin/operation-password/status）：检查 user_type == UserTypeSuperAdmin，调用 IsSet() 返回状态
  • 添加 Handler 方法中文注释（含 HTTP 方法和路径）
• 4.2 运行 lsp_diagnostics 确认 super_admin.go 无错误

5. Bootstrap 注册

• 5.1 在 internal/bootstrap/services.go 中注册 OperationPasswordService（注入 Redis 客户端）
• 5.2 在 internal/bootstrap/handlers.go 中注册 SuperAdminHandler（注入 OperationPasswordService）
• 5.3 在路由文件中注册两个新接口（POST /api/admin/super-admin/operation-password 和 GET /api/admin/super-admin/operation-password/status），路由需经过 admin 认证中间件
• 5.4 运行 lsp_diagnostics 确认 bootstrap 和路由文件无错误

6. 文档生成器更新

• 6.1 在 cmd/api/docs.go 和 cmd/gendocs/main.go 的 Handlers 结构体中注册 SuperAdminHandler（参考现有 handler 注册方式）

7. 修改 AgentRecharge 操作密码验证逻辑

• 7.1 在 internal/service/agent_recharge/service.go 的 OfflinePay 方法中，将操作密码验证从"查询当前用户账号 + bcrypt 对比登录密码"改为"调用 operationPasswordService.Verify(ctx, req.OperationPassword)"
• 7.2 在 agent_recharge/service.go 的 Service 结构体中注入 operationPasswordService，在构造函数中传入
• 7.3 在 internal/bootstrap/services.go 中更新 AgentRechargeService 的构造调用，传入 OperationPasswordService
• 7.4 运行 lsp_diagnostics 确认 agent_recharge/service.go 和 bootstrap 相关文件无错误

8. 接口验证

• 8.1 调用 GET /api/admin/super-admin/operation-password/status，验证返回 {"is_set": false}（初始状态）
• 8.2 调用 POST /api/admin/super-admin/operation-password（传入合法密码），验证返回 200
• 8.3 调用 GET /api/admin/super-admin/operation-password/status，验证返回 {"is_set": true}
• 8.4 调用 OfflinePay 接口传入旧登录密码，验证返回"操作密码错误"（旧密码已失效）
• 8.5 调用 OfflinePay 接口传入新设置的操作密码，验证正常通过
• 8.6 使用非超级管理员账号调用设置接口，验证返回 403