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

Change: 实现平台账号管理接口

Why

当前系统已有通用的账号管理功能，但缺少针对**平台账号（平台用户 + 超级管理员）**的专用管理接口。业务需要：

1. 专门的平台账号列表：筛选出 user_type IN (1, 2) 的账号，包含超级管理员
2. 语义明确的专用接口：密码修改、启用/禁用需要独立端点，而非通过通用 Update 接口
3. 角色分配灵活性：允许清空角色、支持可选角色分配
4. 超级管理员保护：超级管理员在列表中只读显示，禁止编辑角色

现状：

• ✅ 已有账号 CRUD 功能（/internal/handler/admin/account.go）
• ✅ 已有角色分配功能（AssignRoles, GetRoles, RemoveRole）
• ❌ 缺少专门的密码修改接口（当前混在 Update 接口中）
• ❌ 缺少专门的启用/禁用接口（当前混在 Update 接口中）
• ❌ 角色分配要求至少 1 个角色（不允许清空）
• ❌ 没有超级管理员编辑保护

What Changes

1. 新增专用接口

Handler 层新增方法

• UpdatePassword(c *fiber.Ctx) - 修改密码专用接口
• UpdateStatus(c *fiber.Ctx) - 启用/禁用专用接口
• ListPlatformAccounts(c *fiber.Ctx) - 平台账号列表查询（user_type IN (1,2)）

Service 层新增方法

• UpdatePassword(ctx, accountID, newPassword) - 密码修改业务逻辑
• UpdateStatus(ctx, accountID, status) - 状态切换业务逻辑
• ListPlatformAccounts(ctx, req) - 平台账号列表查询（自动筛选 user_type）

新增 DTO

• UpdatePasswordRequest - 密码修改请求（只包含 new_password）
• UpdateStatusRequest - 状态修改请求（只包含 status）
• PlatformAccountListRequest - 平台账号列表请求（移除 user_type 筛选）

2. 优化现有角色分配逻辑

Service 层修改

• AssignRoles 方法增强：
  • 允许 roleIDs 为空数组（清空所有角色）
  • 超级管理员（user_type=1）禁止分配角色，返回错误
  • 平台用户（user_type=2）可分配无限个平台角色（role_type=1）

DTO 修改

• AssignRolesRequest.RoleIDs 改为可选（validate:"omitempty"）

3. 新增路由

// 平台账号专用路由
GET    /api/admin/platform-accounts        // 平台账号列表（含超级管理员）
POST   /api/admin/platform-accounts        // 新增平台账号
GET    /api/admin/platform-accounts/:id    // 获取详情
PUT    /api/admin/platform-accounts/:id    // 编辑平台账号
DELETE /api/admin/platform-accounts/:id    // 删除平台账号

// 专用操作接口
PUT    /api/admin/platform-accounts/:id/password  // 修改密码
PUT    /api/admin/platform-accounts/:id/status    // 启用/禁用

// 角色管理
POST   /api/admin/platform-accounts/:id/roles     // 分配角色（支持空数组）
GET    /api/admin/platform-accounts/:id/roles     // 获取角色列表
DELETE /api/admin/platform-accounts/:id/roles/:role_id  // 移除单个角色

4. 响应格式调整

列表返回字段（符合需求）：

{
  "items": [
    {
      "id": 1,
      "username": "admin",
      "phone": "13800000000",
      "created_at": "2025-01-14T10:30:00Z",
      "status": 1,
      "user_type": 1
    }
  ],
  "total": 10,
  "page": 1,
  "size": 20
}

Impact

受影响的 Specs

• role-permission - 角色分配逻辑调整（允许空数组）
• user-organization - 平台账号管理增强

受影响的代码模块

• internal/handler/admin/account.go - 新增 3 个 Handler 方法
• internal/service/account/service.go - 新增 2 个 Service 方法，修改 AssignRoles
• internal/model/account_dto.go - 新增 2 个 DTO，修改 AssignRolesRequest
• internal/routes/account.go - 新增路由注册

Breaking Changes

无。新增功能向后兼容，现有接口保持不变。

数据库变更

无。复用现有 tb_account 表结构。

迁移计划

无需迁移。新接口与现有接口共存，前端可按需切换。

Risks

1. 角色分配空数组行为：允许清空所有角色可能导致账号无权限

   • 缓解措施：前端二次确认，文档明确说明

2. 超级管理员保护：禁止编辑超级管理员角色可能影响已有流程

   • 缓解措施：仅对 user_type=1 生效，平台用户不受影响

3. 路由命名冲突：新增 /platform-accounts 路由可能与未来规划冲突

   • 缓解措施：遵循 RESTful 规范，路径清晰语义化

Open Questions

1. ✅ 已确认：超级管理员是否需要出现在平台账号列表？ → 是
2. ✅ 已确认：修改密码是否需要旧密码验证？ → 否（管理员重置场景）
3. ✅ 已确认：角色分配是否必填？ → 可选（允许无角色账号）
4. ✅ 已确认：是否允许清空所有角色？ → 是（灵活分配）