junhong_cmp_fiber/openspec/changes/archive/2026-01-14-add-default-admin-init/tasks.md

实现任务清单

1. 实现管理员初始化逻辑

• 1.1 在 internal/service/account/service.go 添加内部创建方法 CreateSystemAccount()

  • 绕过当前用户 ID 检查（系统初始化场景）
  • 接受完整的 Account 结构体
  • 保留用户名和手机号唯一性检查
  • 密码使用 bcrypt 哈希

• 1.2 在 internal/bootstrap/admin.go 添加 initDefaultAdmin() 函数

  • 检查数据库是否存在 user_type = 1 的账号
  • 如果不存在，创建默认管理员账号
  • 读取账号信息的优先级：
    1. 优先使用 config.DefaultAdmin（如果配置了）
    2. 如果配置为空，使用 constants 中的代码默认值
  • 记录初始化成功/跳过日志（包括使用的用户名）

• 1.3 在 internal/bootstrap/bootstrap.go 的 Bootstrap() 函数中调用 initDefaultAdmin()

  • 在所有组件初始化完成后调用
  • 在返回 handlers 前执行
  • 如果初始化失败，记录错误但不中断启动（降级处理）

2. 添加配置和常量

• 2.1 在 pkg/config/config.go 添加 DefaultAdminConfig 结构体

  • 字段：Username、Password、Phone（均为 string）
  • 在 Config 结构体中添加 DefaultAdmin 字段
  • 配置项为可选，不参与 Validate() 验证（允许为空）

• 2.2 在 configs/config.yaml 添加配置示例（注释掉，供参考）

  # default_admin:
  #   username: "admin"
  #   password: "Admin@123456"
  #   phone: "13800000000"
  

• 2.3 在 pkg/constants/constants.go 添加代码默认值常量

  • DefaultAdminUsername = "admin"
  • DefaultAdminPassword = "Admin@123456"
  • DefaultAdminPhone = "13800000000"
  • 添加中文注释说明用途

3. 测试验证

• 3.1 单元测试：测试 CreateSystemAccount() 方法

  • 测试成功创建
  • 测试用户名重复错误
  • 测试手机号重复错误

• 3.2 集成测试：测试启动时管理员初始化

  • 空数据库场景：验证创建成功
  • 已有管理员场景：验证跳过创建
  • 配置文件场景：验证使用配置文件的账号信息
  • 无配置场景：验证使用代码默认值
  • 验证创建的账号可以正常使用（密码验证）

• 3.3 手动测试

  • 启动服务，检查日志输出
  • 使用默认账号登录（如果有登录接口）
  • 验证创建的账号字段正确

4. 文档更新

• 4.1 更新 README.md

  • 添加默认管理员账号说明
  • 说明如何通过配置文件自定义默认账号
  • 提醒首次登录后修改密码

• 4.2 在 docs/ 目录添加功能说明文档

  • 说明默认管理员初始化逻辑
  • 说明安全注意事项
  • 提供手动创建管理员的备用方案（SQL）

验证检查清单

完成所有任务后，确认：

• 空数据库启动时自动创建管理员
• 已有管理员时跳过创建（不报错）
• 日志清晰记录初始化结果
• 所有测试通过（逻辑验证）
• 文档更新完成
• 代码符合项目规范（gofmt、注释、分层）