csxj2026/junhong_cmp_fiber

Files

huang b1195c16df feat(account): 实现平台账号管理功能

- 新增平台账号列表查询接口(自动筛选超级管理员和平台用户)
- 新增密码修改和状态切换专用接口
- 增强角色分配功能,支持空数组清空所有角色
- 新增超级管理员保护机制,禁止分配角色
- 新增完整的集成测试和OpenSpec规范文档

2026-01-14 17:00:30 +08:00

specs

feat(account): 实现平台账号管理功能

2026-01-14 17:00:30 +08:00

proposal.md

feat(account): 实现平台账号管理功能

2026-01-14 17:00:30 +08:00

README.md

feat(account): 实现平台账号管理功能

2026-01-14 17:00:30 +08:00

tasks.md

feat(account): 实现平台账号管理功能

2026-01-14 17:00:30 +08:00

README.md

平台账号管理功能实现

📋 变更概述

Change ID: add-platform-account-management

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

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

🎯 功能需求（用户需求）

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

✅ 分页查询列表
- 查询条件：账号名称
- 返回值：名称、手机号、创建时间、状态（启用/停用）
- 包含超级管理员
✅ 新增平台账号
- 表单参数：名称、手机号（登录账号）、登录密码、状态（启用/禁用）、选择角色（多选）
✅ 编辑平台账号
- 参考新增接口
✅ 修改密码
- 表单参数：新密码（无需旧密码）
✅ 启用/禁用接口
- 独立的状态切换接口
✅ 超级管理员出现在列表中
- 列表自动包含 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 的顺序逐步实现：

Model 层（DTO 定义）
Service 层（业务逻辑）
Handler 层（HTTP 处理）
路由注册
单元测试
集成测试
文档更新

3. 实现完成后归档

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

openspec archive add-platform-account-management

📞 问题反馈

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

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

README.md Unescape Escape

平台账号管理功能实现

📋 变更概述

🎯 功能需求（用户需求）

🔧 技术实现方案

1. 新增接口列表

核心管理接口

专用操作接口

角色管理接口

2. 新增 DTO

3. 新增 Service 方法

4. 角色分配增强

📝 API 使用示例

1. 查询平台账号列表

2. 新增平台账号

3. 修改密码

4. 启用/禁用账号

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

6. 超级管理员保护

🔐 业务规则

用户类型筛选

角色分配规则

密码规则

状态规则

📂 文件清单

提案文件

Spec Deltas

✅ 验证结果

🚀 下一步

1. 审查提案

2. 批准后开始实现

3. 实现完成后归档

📞 问题反馈

README.md