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

平台账号管理功能实现

📋 变更概述

Change ID: add-platform-account-management

目标：实现专门的平台账号（平台用户 + 超级管理员）管理接口，提供语义清晰的专用操作，并增强角色分配灵活性。

验证状态: ✅ PASSED (openspec validate add-platform-account-management --strict)

---

🎯 功能需求（用户需求）

根据原始需求，需要实现以下接口：

1. ✅ 分页查询列表

   • 查询条件：账号名称
   • 返回值：名称、手机号、创建时间、状态（启用/停用）
   • 包含超级管理员

2. ✅ 新增平台账号

   • 表单参数：名称、手机号（登录账号）、登录密码、状态（启用/禁用）、选择角色（多选）

3. ✅ 编辑平台账号

   • 参考新增接口

4. ✅ 修改密码

   • 表单参数：新密码（无需旧密码）

5. ✅ 启用/禁用接口

   • 独立的状态切换接口

6. ✅ 超级管理员出现在列表中

   • 列表自动包含 user_type IN (1, 2) 的账号

---

🔧 技术实现方案

1. 新增接口列表

核心管理接口

方法	路径	说明	实现方式
GET	/api/admin/platform-accounts	平台账号列表（含超管）	新增 ListPlatformAccounts
POST	/api/admin/platform-accounts	新增平台账号	复用 Create
GET	/api/admin/platform-accounts/:id	获取详情	复用 Get
PUT	/api/admin/platform-accounts/:id	编辑平台账号	复用 Update
DELETE	/api/admin/platform-accounts/:id	删除平台账号	复用 Delete

专用操作接口

方法	路径	说明	实现方式
PUT	/api/admin/platform-accounts/:id/password	修改密码	新增 UpdatePassword
PUT	/api/admin/platform-accounts/:id/status	启用/禁用	新增 UpdateStatus

角色管理接口

方法	路径	说明	实现方式
POST	/api/admin/platform-accounts/:id/roles	分配角色	增强 AssignRoles
GET	/api/admin/platform-accounts/:id/roles	获取角色列表	复用 GetRoles
DELETE	/api/admin/platform-accounts/:id/roles/:role_id	移除单个角色	复用 RemoveRole

2. 新增 DTO

// UpdatePasswordRequest 修改密码请求
type UpdatePasswordRequest struct {
    NewPassword string `json:"new_password" validate:"required,min=8,max=32"`
}

// UpdateStatusRequest 状态切换请求
type UpdateStatusRequest struct {
    Status int `json:"status" validate:"required,min=0,max=1"`
}

// PlatformAccountListRequest 平台账号列表请求
type PlatformAccountListRequest struct {
    Page     int    `json:"page" query:"page" validate:"omitempty,min=1"`
    PageSize int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100"`
    Username string `json:"username" query:"username" validate:"omitempty,max=50"`
    Phone    string `json:"phone" query:"phone" validate:"omitempty,max=20"`
    Status   *int   `json:"status" query:"status" validate:"omitempty,min=0,max=1"`
}

3. 新增 Service 方法

// UpdatePassword 修改密码
func (s *Service) UpdatePassword(ctx context.Context, accountID uint, newPassword string) error

// UpdateStatus 状态切换
func (s *Service) UpdateStatus(ctx context.Context, accountID uint, status int) error

// ListPlatformAccounts 平台账号列表查询（自动筛选 user_type IN (1,2)）
func (s *Service) ListPlatformAccounts(ctx context.Context, req *model.PlatformAccountListRequest) ([]*model.Account, int64, error)

4. 角色分配增强

修改前：

type AssignRolesRequest struct {
    RoleIDs []uint `json:"role_ids" validate:"required,min=1"` // 必填，至少1个
}

修改后：

type AssignRolesRequest struct {
    RoleIDs []uint `json:"role_ids" validate:"omitempty"` // 可选，允许空数组
}

业务逻辑调整：

• ✅ 允许传递空数组 [] 清空所有角色
• ✅ 超级管理员（user_type=1）禁止分配角色，返回错误
• ✅ 平台用户（user_type=2）可分配无限个平台角色

---

📝 API 使用示例

1. 查询平台账号列表

请求：

GET /api/admin/platform-accounts?page=1&page_size=20&username=admin&status=1

响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "username": "admin",
        "phone": "13800000000",
        "user_type": 1,
        "status": 1,
        "created_at": "2025-01-14T10:00:00Z",
        "updated_at": "2025-01-14T10:00:00Z"
      },
      {
        "id": 2,
        "username": "platform_user",
        "phone": "13900000000",
        "user_type": 2,
        "status": 1,
        "created_at": "2025-01-14T11:00:00Z",
        "updated_at": "2025-01-14T11:00:00Z"
      }
    ],
    "total": 2,
    "page": 1,
    "size": 20
  },
  "timestamp": "2025-01-14T10:30:00Z"
}

2. 新增平台账号

请求：

POST /api/admin/platform-accounts
Content-Type: application/json

{
  "username": "new_platform_user",
  "phone": "13700000000",
  "password": "SecurePass@123",
  "user_type": 2
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 3,
    "username": "new_platform_user",
    "phone": "13700000000",
    "user_type": 2,
    "status": 1,
    "created_at": "2025-01-14T12:00:00Z"
  },
  "timestamp": "2025-01-14T12:00:00Z"
}

3. 修改密码

请求：

PUT /api/admin/platform-accounts/3/password
Content-Type: application/json

{
  "new_password": "NewSecurePass@456"
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": null,
  "timestamp": "2025-01-14T12:05:00Z"
}

4. 启用/禁用账号

请求：

PUT /api/admin/platform-accounts/3/status
Content-Type: application/json

{
  "status": 0
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": null,
  "timestamp": "2025-01-14T12:10:00Z"
}

5. 分配角色（支持空数组）

清空所有角色：

POST /api/admin/platform-accounts/3/roles
Content-Type: application/json

{
  "role_ids": []
}

分配多个角色：

POST /api/admin/platform-accounts/3/roles
Content-Type: application/json

{
  "role_ids": [1, 2, 3]
}

响应：

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 10,
      "account_id": 3,
      "role_id": 1,
      "status": 1
    }
  ],
  "timestamp": "2025-01-14T12:15:00Z"
}

6. 超级管理员保护

尝试为超级管理员分配角色（会被拒绝）：

POST /api/admin/platform-accounts/1/roles
Content-Type: application/json

{
  "role_ids": [1]
}

响应：

{
  "code": 1001,
  "msg": "超级管理员不允许分配角色",
  "data": null,
  "timestamp": "2025-01-14T12:20:00Z"
}

---

🔐 业务规则

用户类型筛选

• ✅ 平台账号列表：自动筛选 user_type IN (1, 2)
• ✅ 包含超级管理员：user_type=1 的账号出现在列表中

角色分配规则

用户类型	允许分配角色数量	角色类型限制	是否允许清空角色
超级管理员（1）	❌ 不允许分配	-	❌
平台用户（2）	✅ 无限制	只能分配平台角色（role_type=1）	✅
代理账号（3）	✅ 最多 1 个	只能分配客户角色（role_type=2）	✅
企业账号（4）	✅ 最多 1 个	只能分配客户角色（role_type=2）	✅

密码规则

• ✅ 长度：8-32 位
• ✅ 存储：bcrypt 哈希
• ✅ 修改：无需验证旧密码（管理员重置场景）

状态规则

• ✅ 启用：status=1
• ✅ 禁用：status=0
• ✅ 禁用账号无法登录（认证层拦截）

---

📂 文件清单

提案文件

• openspec/changes/add-platform-account-management/proposal.md - 变更提案
• openspec/changes/add-platform-account-management/tasks.md - 实现任务清单
• openspec/changes/add-platform-account-management/README.md - 本文档

Spec Deltas

• openspec/changes/add-platform-account-management/specs/role-permission/spec.md - 角色分配逻辑调整
• openspec/changes/add-platform-account-management/specs/user-organization/spec.md - 平台账号管理增强

---

✅ 验证结果

$ openspec validate add-platform-account-management --strict
Change 'add-platform-account-management' is valid

验证通过：所有 delta specs 格式正确，需求完整，场景覆盖充分。

---

🚀 下一步

1. 审查提案

请审查以下文件：

• openspec/changes/add-platform-account-management/proposal.md - 确认业务需求和影响范围
• openspec/changes/add-platform-account-management/tasks.md - 确认实现任务清单
• openspec/changes/add-platform-account-management/specs/*/spec.md - 确认需求定义

2. 批准后开始实现

批准后，我将按照 tasks.md 的顺序逐步实现：

1. Model 层（DTO 定义）
2. Service 层（业务逻辑）
3. Handler 层（HTTP 处理）
4. 路由注册
5. 单元测试
6. 集成测试
7. 文档更新

3. 实现完成后归档

实现完成并测试通过后，使用以下命令归档：

openspec archive add-platform-account-management

---

📞 问题反馈

如有任何问题或需要调整，请告知：

• 业务需求是否准确？
• 接口设计是否合理？
• 角色分配逻辑是否符合预期？
• 是否需要额外功能？