# 平台账号管理功能实现

## 📋 变更概述

**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
```

---

## 📞 问题反馈

如有任何问题或需要调整，请告知：
- 业务需求是否准确？
- 接口设计是否合理？
- 角色分配逻辑是否符合预期？
- 是否需要额外功能？