junhong_cmp_fiber/docs/account-management-refactor/迁移指南.md

# 账号管理接口迁移指南

## 概述

本次重构统一了账号管理和认证接口架构，简化了路由结构，前端需要更新所有相关接口调用。

## Breaking Changes

### 1. 账号管理接口路由变更

所有账号管理接口统一为 `/api/admin/accounts/*` 结构，**不再按账号类型区分路由**：

| 旧路由前缀 | 新路由前缀 | 说明 |
|-----------|-----------|------|
| `/api/admin/platform-accounts` | `/api/admin/accounts` | 平台账号 |
| `/api/admin/shop-accounts` | `/api/admin/accounts` | 代理账号 |
| `/api/admin/customer-accounts` | `/api/admin/accounts` | 企业账号（改名） |

**重要变更**：
- ✅ 所有账号类型共享同一套路由
- ✅ 账号类型通过**请求体的 `user_type` 字段**区分（2=平台，3=代理，4=企业）
- ✅ `customer-accounts` 改名为 `enterprise`（命名更准确）

#### 完整路由映射（10个接口）

| 功能 | HTTP 方法 | 旧路径示例（平台账号） | 新路径（统一） |
|------|-----------|---------------------|-------------|
| 创建账号 | POST | `/api/admin/platform-accounts` | `/api/admin/accounts` |
| 查询列表 | GET | `/api/admin/platform-accounts` | `/api/admin/accounts` |
| 获取详情 | GET | `/api/admin/platform-accounts/:id` | `/api/admin/accounts/:id` |
| 更新账号 | PUT | `/api/admin/platform-accounts/:id` | `/api/admin/accounts/:id` |
| 删除账号 | DELETE | `/api/admin/platform-accounts/:id` | `/api/admin/accounts/:id` |
| 修改密码 | PUT | `/api/admin/platform-accounts/:id/password` | `/api/admin/accounts/:id/password` |
| 修改状态 | PUT | `/api/admin/platform-accounts/:id/status` | `/api/admin/accounts/:id/status` |
| 分配角色 | POST | `/api/admin/platform-accounts/:id/roles` | `/api/admin/accounts/:id/roles` |
| 获取角色 | GET | `/api/admin/platform-accounts/:id/roles` | `/api/admin/accounts/:id/roles` |
| 移除角色 | DELETE | `/api/admin/platform-accounts/:id/roles/:role_id` | `/api/admin/accounts/:account_id/roles/:role_id` |

**⚠️ 特别注意**：移除角色接口的路径参数从 `:id` 改为 `:account_id`

### 2. 认证接口路由变更

后台和 H5 认证接口合并为统一的 `/api/auth/*`：

| 功能 | 后台旧路由 | H5 旧路由 | 新路由（统一） |
|------|-----------|----------|-------------|
| 登录 | `/api/admin/login` | `/api/h5/login` | `/api/auth/login` |
| 登出 | `/api/admin/logout` | `/api/h5/logout` | `/api/auth/logout` |
| 刷新Token | `/api/admin/refresh-token` | `/api/h5/refresh-token` | `/api/auth/refresh-token` |
| 获取用户信息 | `/api/admin/me` | `/api/h5/me` | `/api/auth/me` |
| 修改密码 | `/api/admin/password` | `/api/h5/password` | `/api/auth/password` |

**个人客户认证不受影响**：`/api/c/v1/*` 保持不变

## 数据结构变更

### 请求体变更：账号类型通过 user_type 字段区分

创建账号时，必须在请求体中指定 `user_type`：

```json
{
  "username": "test_user",
  "phone": "13800000001",
  "password": "Password123",
  "user_type": 2,       // 必填：2=平台用户，3=代理账号，4=企业账号
  "shop_id": 10,        // 代理账号必填
  "enterprise_id": 5    // 企业账号必填
}
```

查询账号列表时，可通过 `user_type` 参数筛选：
```
GET /api/admin/accounts?user_type=3  // 查询代理账号
GET /api/admin/accounts               // 查询所有账号
```

### 响应体无变化

所有接口的响应体结构保持不变。

## 迁移步骤

### 第一步：批量替换路由

使用编辑器全局搜索替换：

```
# 账号管理路由（所有账号类型统一）
/api/admin/platform-accounts  →  /api/admin/accounts
/api/admin/shop-accounts       →  /api/admin/accounts
/api/admin/customer-accounts   →  /api/admin/accounts

# 认证路由（后台）
/api/admin/login              →  /api/auth/login
/api/admin/logout             →  /api/auth/logout
/api/admin/refresh-token      →  /api/auth/refresh-token
/api/admin/me                 →  /api/auth/me
/api/admin/password           →  /api/auth/password

# 认证路由（H5）
/api/h5/login                 →  /api/auth/login
/api/h5/logout                →  /api/auth/logout
/api/h5/refresh-token         →  /api/auth/refresh-token
/api/h5/me                    →  /api/auth/me
/api/h5/password              →  /api/auth/password
```

### 第二步：更新账号创建逻辑

**旧代码**（根据路由区分账号类型）：
```javascript
// ❌ 错误：通过不同路由创建不同类型账号
const createPlatformAccount = (data) => axios.post('/api/admin/platform-accounts', data);
const createShopAccount = (data) => axios.post('/api/admin/shop-accounts', data);
const createEnterpriseAccount = (data) => axios.post('/api/admin/customer-accounts', data);
```

**新代码**（通过 user_type 区分账号类型）：
```javascript
// ✅ 正确：统一路由，通过 user_type 区分
const createAccount = (data) => axios.post('/api/admin/accounts', {
  ...data,
  user_type: data.user_type, // 2=平台, 3=代理, 4=企业
});

// 使用示例
createAccount({ username: 'test', user_type: 2, ...otherData });  // 创建平台账号
createAccount({ username: 'agent1', user_type: 3, shop_id: 10, ...otherData });  // 创建代理账号
createAccount({ username: 'ent1', user_type: 4, enterprise_id: 5, ...otherData });  // 创建企业账号
```

### 第三步：更新账号查询逻辑

**旧代码**（分别查询不同类型账号）：
```javascript
// ❌ 错误：三个不同的查询接口
const getPlatformAccounts = (params) => axios.get('/api/admin/platform-accounts', { params });
const getShopAccounts = (params) => axios.get('/api/admin/shop-accounts', { params });
const getEnterpriseAccounts = (params) => axios.get('/api/admin/customer-accounts', { params });
```

**新代码**（统一查询，可选筛选）：
```javascript
// ✅ 正确：统一查询接口，通过 user_type 筛选
const getAccounts = (params) => axios.get('/api/admin/accounts', { params });

// 使用示例
getAccounts({ user_type: 2 });  // 查询平台账号
getAccounts({ user_type: 3 });  // 查询代理账号
getAccounts({ user_type: 4 });  // 查询企业账号
getAccounts({});                 // 查询所有账号
```

### 第四步：更新类型定义（如果使用 TypeScript）

```typescript
// 旧类型
type AccountType = 'platform' | 'shop' | 'customer';

// 新类型
type AccountType = 'platform' | 'shop' | 'enterprise';  // customer 改名为 enterprise

// 新增：账号类型值枚举
enum UserType {
  Platform = 2,     // 平台用户
  Agent = 3,        // 代理账号
  Enterprise = 4,   // 企业账号
}
```

### 第五步：测试验证

1. **后台系统**：
   - 登录/登出功能
   - 平台账号 CRUD
   - 代理账号 CRUD
   - 企业账号 CRUD
   - 角色管理功能

2. **H5 系统**：
   - 登录/登出功能
   - 代理账号自助操作
   - 企业账号自助操作

3. **个人客户端**：
   - 确认认证接口不受影响

## 快速迁移示例

### Vue/React 项目

```javascript
// 旧配置
const API = {
  platformAccounts: '/api/admin/platform-accounts',
  shopAccounts: '/api/admin/shop-accounts',
  customerAccounts: '/api/admin/customer-accounts',
  adminLogin: '/api/admin/login',
  h5Login: '/api/h5/login',
}

// 新配置
const API = {
  accounts: '/api/admin/accounts',  // 统一账号管理接口
  login: '/api/auth/login',         // 统一认证接口
  logout: '/api/auth/logout',
  refreshToken: '/api/auth/refresh-token',
  me: '/api/auth/me',
  updatePassword: '/api/auth/password',
}

// 使用示例
const accountAPI = {
  // 创建账号（根据 user_type 区分类型）
  create: (data) => axios.post(API.accounts, data),
  
  // 查询账号列表（可选筛选 user_type）
  list: (params) => axios.get(API.accounts, { params }),
  
  // 获取详情
  get: (id) => axios.get(`${API.accounts}/${id}`),
  
  // 更新账号
  update: (id, data) => axios.put(`${API.accounts}/${id}`, data),
  
  // 删除账号
  delete: (id) => axios.delete(`${API.accounts}/${id}`),
  
  // 其他操作...
};
```

## 常见问题

### Q1：为什么要做这次重构？

**A**：解决以下问题：
1. 接口重复（三种账号类型有三套完全相同的接口）
2. 路由冗余（Handler 逻辑完全一样，却有三套路由）
3. 维护成本高（新增功能需要改三处）
4. 命名混乱（`customer-accounts` 实际管理企业账号）
5. **安全漏洞**（缺少越权检查，代理可以为其他店铺创建账号）

### Q2：是否支持向后兼容？

**A**：**不支持**。这是 Breaking Change，旧接口已完全删除，前端必须同步更新。

### Q3：迁移需要多长时间？

**A**：
- 简单项目：2-4 小时（主要是查找替换 + 测试）
- 复杂项目：1-2 天（需要重构业务逻辑 + 测试回归）

### Q4：后台和 H5 登录接口合并后如何区分？

**A**：不需要区分。后端通过用户类型自动判断：
- 超级管理员、平台用户：只能后台登录
- 代理用户：可以后台和 H5 登录
- 企业用户：只能 H5 登录

### Q5：企业账号有什么特殊限制？

**A**：企业账号**禁止访问账号管理接口**（路由层直接拦截），尝试访问会返回 403 错误。

### Q6：新增了哪些安全功能？

**A**：
1. **三层越权防护**：路由层拦截 + Service 层权限检查 + GORM 自动过滤
2. **操作审计日志**：所有账号操作（创建、更新、删除、角色分配）都被记录
3. **统一错误返回**：越权访问返回"无权限操作该资源或资源不存在"，防止信息泄露

### Q7：如何区分不同账号类型？

**A**：通过 `user_type` 字段区分：
- `user_type: 2` - 平台用户
- `user_type: 3` - 代理账号（需提供 `shop_id`）
- `user_type: 4` - 企业账号（需提供 `enterprise_id`）

## 新增功能

### 1. 企业账号完整功能

企业账号现在支持所有操作（之前只有部分功能）：
- ✅ CRUD 操作
- ✅ 角色管理
- ✅ 密码管理
- ✅ 状态管理

### 2. 代理账号完整功能

代理账号现在支持所有操作（之前缺少角色管理）：
- ✅ CRUD 操作
- ✅ **角色管理**（新增）
- ✅ 密码管理
- ✅ 状态管理

### 3. 统一路由结构

所有账号类型共享同一套接口，简化了前端开发：
- ✅ 减少重复代码
- ✅ 统一接口调用方式
- ✅ 更容易扩展新功能

## 支持

如有问题请联系后端团队或查看以下文档：
- [功能总结](./功能总结.md)
- [API 文档](./API文档.md)
- [OpenAPI 规范](../../docs/admin-openapi.yaml)