csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
- 新增平台账号列表查询接口(自动筛选超级管理员和平台用户)
- 新增密码修改和状态切换专用接口
- 增强角色分配功能,支持空数组清空所有角色
- 新增超级管理员保护机制,禁止分配角色
- 新增完整的集成测试和OpenSpec规范文档
This commit is contained in:
huang
2026-01-14 17:00:30 +08:00
parent 5556b1028c
commit b1195c16df
15 changed files with 1713 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
openspec/changes/archive/2026-01-14-add-platform-account-management/README.md Normal file
View File

@@ -0,0 +1,388 @@
# 平台账号管理功能实现
## 📋 变更概述
**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
```go
// 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 方法
```go
// 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. 角色分配增强
**修改前**：
```go
type AssignRolesRequest struct {
RoleIDs []uint `json:"role_ids" validate:"required,min=1"` // 必填，至少1个
}
```
**修改后**：
```go
type AssignRolesRequest struct {
RoleIDs []uint `json:"role_ids" validate:"omitempty"` // 可选，允许空数组
}
```
**业务逻辑调整**：
- ✅ 允许传递空数组 `[]` 清空所有角色
- ✅ 超级管理员（`user_type=1`）禁止分配角色，返回错误
- ✅ 平台用户（`user_type=2`）可分配无限个平台角色
---
## 📝 API 使用示例
### 1. 查询平台账号列表
**请求**：
```http
GET /api/admin/platform-accounts?page=1&page_size=20&username=admin&status=1
```
**响应**：
```json
{
"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. 新增平台账号
**请求**：
```http
POST /api/admin/platform-accounts
Content-Type: application/json
{
"username": "new_platform_user",
"phone": "13700000000",
"password": "SecurePass@123",
"user_type": 2
}
```
**响应**：
```json
{
"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. 修改密码
**请求**：
```http
PUT /api/admin/platform-accounts/3/password
Content-Type: application/json
{
"new_password": "NewSecurePass@456"
}
```
**响应**：
```json
{
"code": 0,
"msg": "success",
"data": null,
"timestamp": "2025-01-14T12:05:00Z"
}
```
### 4. 启用/禁用账号
**请求**：
```http
PUT /api/admin/platform-accounts/3/status
Content-Type: application/json
{
"status": 0
}
```
**响应**：
```json
{
"code": 0,
"msg": "success",
"data": null,
"timestamp": "2025-01-14T12:10:00Z"
}
```
### 5. 分配角色（支持空数组）
**清空所有角色**：
```http
POST /api/admin/platform-accounts/3/roles
Content-Type: application/json
{
"role_ids": []
}
```
**分配多个角色**：
```http
POST /api/admin/platform-accounts/3/roles
Content-Type: application/json
{
"role_ids": [1, 2, 3]
}
```
**响应**：
```json
{
"code": 0,
"msg": "success",
"data": [
{
"id": 10,
"account_id": 3,
"role_id": 1,
"status": 1
}
],
"timestamp": "2025-01-14T12:15:00Z"
}
```
### 6. 超级管理员保护
**尝试为超级管理员分配角色**（会被拒绝）：
```http
POST /api/admin/platform-accounts/1/roles
Content-Type: application/json
{
"role_ids": [1]
}
```
**响应**：
```json
{
"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` - 平台账号管理增强
---
## ✅ 验证结果
```bash
$ 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. 实现完成后归档
实现完成并测试通过后，使用以下命令归档：
```bash
openspec archive add-platform-account-management
```
---
## 📞 问题反馈
如有任何问题或需要调整，请告知：
- 业务需求是否准确？
- 接口设计是否合理？
- 角色分配逻辑是否符合预期？
- 是否需要额外功能？