cursor-init/prd/M2-基础用户系统-接口设计.md

# M2 - 基础用户系统 - 详细接口设计

## 1. 概述

本文档基于M2阶段的数据库设计和产品需求，提供完整的RESTful API接口设计方案。所有接口遵循以下原则：

- **RESTful规范**：使用标准HTTP方法和状态码
- **统一响应格式**：所有接口返回统一的JSON格式
- **安全性**：JWT认证、权限控制、数据验证
- **高性能**：合理的缓存策略、分页设计
- **版本控制**：API版本化管理

### 基础URL
```
https://api.starzh.com/v1
```

### 统一响应格式
```json
{
  "code": 0,          // 业务状态码，0表示成功
  "message": "success", // 提示信息
  "data": {},         // 响应数据
}
```

### 统一错误码规范
- 0: 成功
- 400xx: 客户端错误（参数错误、验证失败等）
- 401xx: 认证错误
- 403xx: 权限错误
- 404xx: 资源不存在
- 409xx: 资源冲突
- 500xx: 服务器错误

---

## 2. 认证模块 (Authentication)

### 2.1 用户注册

#### 需求描述
允许新用户通过邮箱注册账号，需要邮箱验证激活。支持基本的用户名、密码规则校验。

#### 接口名称
用户注册接口

#### 设计原因
- 提供用户自主注册功能
- 通过邮箱验证确保用户真实性
- 防止恶意注册和垃圾账号

#### 请求类型
POST

#### 接口路径
`/auth/register`

#### 接口参数
```typescript
{
  username: string;     // 用户名，3-50字符，字母开头，仅包含字母数字下划线
  email: string;        // 邮箱地址，需符合邮箱格式
  password: string;     // 密码，8-100字符，必须包含大小写字母和数字
  confirmPassword: string; // 确认密码，需与password一致
  captcha: string;      // 图形验证码
  captchaId: string;    // 验证码ID
}
```

**参数约束原因**：
- username: 限制长度和字符类型，防止特殊字符引起的安全问题
- password: 强密码策略，提高账户安全性
- captcha: 防止机器人批量注册

#### 响应分类
- 成功：201 Created - 注册成功，发送激活邮件
- 失败：
  - 400 Bad Request - 参数验证失败
  - 409 Conflict - 用户名或邮箱已存在

#### 响应格式
```json
// 成功响应
{
  "code": 0,
  "message": "注册成功，请查收邮件激活账号",
  "data": {
    "userId": 1234567890,
    "username": "john_doe",
    "email": "john@example.com",
    "status": "inactive"
  }
}

// 失败响应示例
{
  "code": 40901,
  "message": "用户名已被占用",
  "data": null
}
```

#### 开发思路
1. 参数验证层：使用Elysia的t验证器进行参数校验
2. 业务逻辑层：
   - 验证图形验证码
   - 检查用户名和邮箱唯一性
   - 密码使用bcrypt加密（成本因子12）
   - 生成用户记录（状态为inactive）
   - 生成激活token并存入Redis（24小时过期）
   - 发送激活邮件（异步队列）
3. 数据访问层：使用事务确保数据一致性
4. 日志记录：记录注册操作到sys_operation_logs

---

### 2.2 用户登录

#### 需求描述
支持用户名或邮箱登录，实现登录失败次数限制，防止暴力破解。

#### 接口名称
用户登录接口

#### 设计原因
- 提供安全的身份认证机制
- 支持多种登录方式提升用户体验
- 防止暴力破解攻击

#### 请求类型
POST

#### 接口路径
`/auth/login`

#### 接口参数
```typescript
{
  account: string;      // 用户名或邮箱
  password: string;     // 密码
  captcha?: string;     // 验证码（连续失败3次后必填）
  captchaId?: string;   // 验证码ID
  rememberMe?: boolean; // 记住我，默认false
}
```

#### 响应分类
- 成功：200 OK - 登录成功，返回token
- 失败：
  - 401 Unauthorized - 用户名或密码错误
  - 423 Locked - 账号被锁定

#### 响应格式
```json
// 成功响应
{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "xxxx-xxxx-xxxx",
    "expiresIn": 7200,
    "user": {
      "id": 1234567890,
      "username": "john_doe",
      "nickname": "John",
      "avatar": "https://...",
      "roles": ["user"]
    }
  }
}
```

#### 开发思路
1. 查询用户（支持username或email）
2. 检查账号状态和锁定状态
3. 验证密码
4. 处理登录失败：
   - 增加失败次数
   - 超过5次锁定30分钟
   - 3次失败后要求验证码
5. 登录成功：
   - 清除失败次数
   - 生成JWT token
   - 更新最后登录信息
   - 记录登录日志

---

### 2.3 刷新Token

#### 需求描述
使用refreshToken换取新的accessToken，实现无感续期。

#### 接口名称
Token刷新接口

#### 设计原因
- 短期accessToken + 长期refreshToken模式
- 提高安全性，减少token泄露风险
- 实现用户无感续期体验

#### 请求类型
POST

#### 接口路径
`/auth/refresh`

#### 接口参数
```typescript
{
  refreshToken: string; // 刷新令牌
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "刷新成功",
  "data": {
    "token": "new-access-token",
    "expiresIn": 7200
  }
}
```

#### 开发思路
1. 验证refreshToken有效性
2. 检查用户状态
3. 生成新的accessToken
4. 可选：轮转refreshToken
5. 记录刷新日志

---

### 2.4 账号激活

#### 需求描述
用户通过邮件中的链接或验证码激活账号。

#### 接口名称
账号激活接口

#### 设计原因
- 验证邮箱真实性
- 防止垃圾注册
- 提高用户质量

#### 请求类型
POST

#### 接口路径
`/auth/activate`

#### 接口参数
```typescript
{
  token: string;        // 激活令牌（从邮件链接获取）
  // 或
  email: string;        // 邮箱
  code: string;         // 6位数字激活码
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "账号激活成功",
  "data": {
    "userId": 1234567890,
    "username": "john_doe",
    "status": "active"
  }
}
```

#### 开发思路
1. 验证激活token或激活码
2. 检查是否过期
3. 更新用户状态为active
4. 删除Redis中的激活信息
5. 发送欢迎邮件
6. 记录激活日志

---

### 2.5 退出登录

#### 需求描述
用户主动退出登录，清除token。

#### 接口名称
退出登录接口

#### 设计原因
- 用户主动结束会话
- 清除服务端缓存
- 增强安全性

#### 请求类型
POST

#### 接口路径
`/auth/logout`

#### 请求头
```
Authorization: Bearer <token>
```

#### 响应格式
```json
{
  "code": 0,
  "message": "退出成功",
  "data": null
}
```

#### 开发思路
1. 获取当前token
2. 加入token黑名单（Redis）
3. 清除用户相关缓存
4. 记录退出日志

---

## 3. 用户管理模块 (User Management)

### 3.1 获取当前用户信息

#### 需求描述
获取当前登录用户的详细信息，包括基本信息、角色、权限、组织等。

#### 接口名称
获取当前用户信息接口

#### 设计原因
- 前端需要用户信息进行界面渲染
- 权限控制需要用户角色和权限信息
- 统一的用户信息获取入口

#### 请求类型
GET

#### 接口路径
`/users/me`

#### 请求头
```
Authorization: Bearer <token>
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890,
    "username": "john_doe",
    "email": "john@example.com",
    "mobile": "13800138000",
    "nickname": "John",
    "avatar": "https://...",
    "gender": 1,
    "birthday": "1990-01-01",
    "bio": "Hello world",
    "status": "active",
    "lastLoginAt": "2024-01-01T12:00:00Z",
    "roles": [
      {
        "id": 1,
        "code": "admin",
        "name": "管理员"
      }
    ],
    "permissions": [
      {
        "code": "user:read",
        "name": "查看用户",
        "type": "api"
      }
    ],
    "organizations": [
      {
        "id": 1,
        "name": "技术部",
        "isPrimary": true,
        "position": "工程师"
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "VIP",
        "color": "#ff4d4f"
      }
    ]
  }
}
```

#### 开发思路
1. 从JWT token中获取用户ID
2. 查询用户基本信息
3. 并行查询关联信息：
   - 用户角色（包含权限快照）
   - 用户组织
   - 用户标签
4. 整合权限信息（角色权限去重）
5. 使用Redis缓存（5分钟过期）

---

### 3.2 用户列表查询

#### 需求描述
分页查询用户列表，支持多条件筛选和排序。

#### 接口名称
用户列表查询接口

#### 设计原因
- 管理员需要查看和管理所有用户
- 支持灵活的查询条件满足不同场景
- 分页设计避免大数据量查询

#### 请求类型
GET

#### 接口路径
`/users`

#### 接口参数
```typescript
// Query Parameters
{
  page?: number;         // 页码，默认1
  pageSize?: number;     // 每页数量，默认20，最大100
  keyword?: string;      // 搜索关键词（用户名/邮箱/手机号/昵称）
  status?: string;       // 用户状态
  roleId?: number;       // 角色ID
  organizationId?: number; // 组织ID
  tagId?: number;        // 标签ID
  startDate?: string;    // 注册开始时间
  endDate?: string;      // 注册结束时间
  sortBy?: string;       // 排序字段：createdAt,lastLoginAt
  sortOrder?: string;    // 排序方向：asc,desc
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1234567890,
        "username": "john_doe",
        "email": "john@example.com",
        "mobile": "138****8000",
        "nickname": "John",
        "avatar": "https://...",
        "status": "active",
        "roles": ["admin", "user"],
        "organizations": ["技术部"],
        "tags": ["VIP"],
        "loginCount": 100,
        "lastLoginAt": "2024-01-01T12:00:00Z",
        "createdAt": "2023-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

#### 开发思路
1. 参数验证和权限检查（需要user:read权限）
2. 构建查询条件：
   - 关键词模糊查询
   - 状态精确匹配
   - 关联表过滤（角色、组织、标签）
   - 时间范围查询
3. 执行分页查询（使用索引优化）
4. 批量查询关联信息（减少N+1查询）
5. 数据脱敏（手机号中间4位）

---

### 3.3 创建用户

#### 需求描述
管理员创建新用户，可直接设置角色、组织等信息。

#### 接口名称
创建用户接口

#### 设计原因
- 管理员需要批量创建用户
- 可预设用户角色和组织
- 支持直接激活状态

#### 请求类型
POST

#### 接口路径
`/users`

#### 接口参数
```typescript
{
  username: string;
  email: string;
  password: string;
  mobile?: string;
  nickname?: string;
  status?: string;      // 默认active
  gender?: number;
  birthday?: string;
  bio?: string;
  roleIds?: number[];   // 角色ID数组
  organizationIds?: Array<{
    id: number;
    isPrimary: boolean;
    position?: string;
  }>;                   // 组织信息
  tagIds?: number[];    // 标签ID数组
  sendNotification?: boolean; // 是否发送通知邮件
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "创建成功",
  "data": {
    "id": 1234567890,
    "username": "new_user",
    "email": "new@example.com",
    "status": "active"
  }
}
```

#### 开发思路
1. 权限检查（需要user:create权限）
2. 参数验证（唯一性检查）
3. 使用事务处理：
   - 创建用户记录
   - 分配角色
   - 分配组织
   - 分配标签
4. 发送通知邮件（可选）
5. 记录操作日志

---

### 3.4 更新用户信息

#### 需求描述
更新用户基本信息和关联信息。

#### 接口名称
更新用户信息接口

#### 设计原因
- 支持用户自主修改个人信息
- 管理员可修改用户所有信息
- 分离基本信息和关联信息更新

#### 请求类型
PUT

#### 接口路径
`/users/{userId}`

#### 接口参数
```typescript
{
  email?: string;
  mobile?: string;
  nickname?: string;
  avatar?: string;
  gender?: number;
  birthday?: string;
  bio?: string;
  // 以下字段需要管理员权限
  status?: string;
  roleIds?: number[];
  organizationIds?: Array<{
    id: number;
    isPrimary: boolean;
    position?: string;
  }>;
  tagIds?: number[];
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "更新成功",
  "data": {
    "id": 1234567890,
    "username": "john_doe",
    "email": "john@example.com",
    "updatedAt": "2024-01-01T12:00:00Z"
  }
}
```

#### 开发思路
1. 权限检查：
   - 用户可修改自己的基本信息
   - 管理员可修改所有信息
   - root用户信息限制修改
2. 参数验证（邮箱唯一性等）
3. 使用乐观锁防止并发冲突
4. 更新关联信息时先删后增
5. 清除相关缓存

---

### 3.5 修改密码

#### 需求描述
用户修改自己的密码，需要验证原密码。

#### 接口名称
修改密码接口

#### 设计原因
- 用户自主管理密码
- 增强账户安全性
- 防止未授权修改

#### 请求类型
PUT

#### 接口路径
`/users/me/password`

#### 接口参数
```typescript
{
  oldPassword: string;  // 原密码
  newPassword: string;  // 新密码
  confirmPassword: string; // 确认新密码
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "密码修改成功",
  "data": null
}
```

#### 开发思路
1. 验证原密码正确性
2. 验证新密码符合规则
3. 更新密码（bcrypt加密）
4. 清除所有该用户的token
5. 发送密码修改通知邮件

---

### 3.6 重置密码

#### 需求描述
用户忘记密码时通过邮箱重置。

#### 接口名称
申请重置密码接口

#### 设计原因
- 用户忘记密码的补救措施
- 通过邮箱验证身份
- 防止恶意重置

#### 请求类型
POST

#### 接口路径
`/users/password/reset-request`

#### 接口参数
```typescript
{
  email: string;
  captcha: string;
  captchaId: string;
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "重置邮件已发送",
  "data": null
}
```

#### 开发思路
1. 验证邮箱存在
2. 验证图形验证码
3. 生成重置token（6位数字或链接）
4. 存入Redis（30分钟过期）
5. 发送重置邮件
6. 限制发送频率（1分钟内不可重复）

---

### 3.7 确认重置密码

#### 需求描述
使用重置token设置新密码。

#### 接口名称
确认重置密码接口

#### 请求类型
POST

#### 接口路径
`/users/password/reset-confirm`

#### 接口参数
```typescript
{
  token: string;        // 重置token
  email: string;        // 邮箱
  newPassword: string;  // 新密码
  confirmPassword: string; // 确认密码
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "密码重置成功",
  "data": null
}
```

#### 开发思路
1. 验证token有效性和匹配性
2. 验证新密码规则
3. 更新用户密码
4. 删除重置token
5. 清除用户所有token
6. 发送重置成功通知

---

### 3.8 删除用户

#### 需求描述
软删除用户，保留数据用于审计。

#### 接口名称
删除用户接口

#### 设计原因
- 满足用户注销需求
- 保留数据用于审计
- 支持误删恢复

#### 请求类型
DELETE

#### 接口路径
`/users/{userId}`

#### 响应格式
```json
{
  "code": 0,
  "message": "删除成功",
  "data": null
}
```

#### 开发思路
1. 权限检查（需要user:delete权限）
2. 检查是否为root用户（禁止删除）
3. 检查是否为自己（需要二次确认）
4. 更新deleted_at字段
5. 清除用户所有会话
6. 记录删除操作日志

---

### 3.9 批量操作用户

#### 需求描述
批量启用、禁用、删除用户。

#### 接口名称
批量操作用户接口

#### 设计原因
- 提高管理效率
- 支持批量处理
- 减少重复操作

#### 请求类型
POST

#### 接口路径
`/users/batch`

#### 接口参数
```typescript
{
  userIds: number[];    // 用户ID数组
  action: string;       // 操作类型：enable,disable,delete
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "操作成功",
  "data": {
    "success": 10,
    "failed": 0,
    "errors": []
  }
}
```

#### 开发思路
1. 权限检查
2. 过滤掉root用户
3. 批量执行操作
4. 记录操作结果
5. 返回执行统计

---

## 4. 角色管理模块 (Role Management)

### 4.1 角色树查询

#### 需求描述
查询角色树形结构，支持权限继承展示。

#### 接口名称
角色树查询接口

#### 设计原因
- 角色具有层级关系需要树形展示
- 支持权限继承机制
- 便于理解角色体系

#### 请求类型
GET

#### 接口路径
`/roles/tree`

#### 接口参数
```typescript
{
  status?: string;      // 过滤状态
  withPermissions?: boolean; // 是否包含权限信息
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "code": "super_admin",
      "name": "超级管理员",
      "description": "拥有所有权限",
      "status": "active",
      "isSystem": true,
      "permissionCount": 50,
      "children": [
        {
          "id": 2,
          "code": "admin",
          "name": "管理员",
          "pid": 1,
          "children": []
        }
      ]
    }
  ]
}
```

#### 开发思路
1. 查询所有角色（使用path字段优化）
2. 构建树形结构（递归或迭代）
3. 统计每个角色的权限数量
4. 使用Redis缓存（角色变更时失效）

---

### 4.2 创建角色

#### 需求描述
创建新角色并分配权限，支持角色继承。

#### 接口名称
创建角色接口

#### 设计原因
- 灵活的角色管理支持业务扩展
- 权限继承减少重复配置
- 下级角色权限不能超过上级

#### 请求类型
POST

#### 接口路径
`/roles`

#### 接口参数
```typescript
{
  code: string;         // 角色代码，唯一
  name: string;         // 角色名称
  description?: string; // 角色描述
  pid?: number;         // 父角色ID
  status?: string;      // 状态，默认active
  permissionIds: number[]; // 权限ID数组
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "创建成功",
  "data": {
    "id": 10,
    "code": "editor",
    "name": "编辑员",
    "path": "/1/2/10/",
    "level": 3
  }
}
```

#### 开发思路
1. 权限检查（需要role:create权限）
2. 验证角色代码唯一性
3. 验证父角色存在性
4. 检查权限分配合法性：
   - 获取父角色所有权限
   - 确保新角色权限是父角色权限的子集
5. 使用事务创建：
   - 创建角色记录
   - 计算并设置path和level
   - 分配权限
   - 生成权限快照
6. 清除角色缓存

---

### 4.3 更新角色信息

#### 需求描述
更新角色基本信息，不包括权限。

#### 接口名称
更新角色信息接口

#### 设计原因
- 角色信息可能需要调整
- 分离基本信息和权限更新
- 防止误操作

#### 请求类型
PUT

#### 接口路径
`/roles/{roleId}`

#### 接口参数
```typescript
{
  name?: string;
  description?: string;
  status?: string;
  sortOrder?: number;
}
```

#### 开发思路
1. 权限检查（需要role:update权限）
2. 检查是否为系统角色（限制修改）
3. 更新角色信息
4. 清除角色缓存

---

### 4.4 更新角色权限

#### 需求描述
动态调整角色权限，支持批量操作。

#### 接口名称
更新角色权限接口

#### 设计原因
- 业务变化需要调整权限
- 支持灵活的权限管理
- 保证权限继承一致性

#### 请求类型
PUT

#### 接口路径
`/roles/{roleId}/permissions`

#### 接口参数
```typescript
{
  permissionIds: number[]; // 新的权限ID数组（全量）
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "权限更新成功",
  "data": {
    "roleId": 10,
    "permissionCount": 20,
    "addedCount": 5,
    "removedCount": 3
  }
}
```

#### 开发思路
1. 检查角色是否为系统角色
2. 验证权限合法性（不超过父角色）
3. 对比新旧权限，计算差异
4. 使用事务更新：
   - 删除旧权限关联
   - 创建新权限关联
   - 更新权限快照
5. 级联更新子角色（移除超出的权限）
6. 清除相关用户的权限缓存

---

### 4.5 删除角色

#### 需求描述
删除角色，处理关联关系。

#### 接口名称
删除角色接口

#### 设计原因
- 清理无用角色
- 保持系统整洁
- 防止权限泄露

#### 请求类型
DELETE

#### 接口路径
`/roles/{roleId}`

#### 开发思路
1. 权限检查（需要role:delete权限）
2. 检查是否为系统角色（禁止删除）
3. 检查是否有用户使用该角色
4. 检查是否有子角色
5. 软删除角色
6. 清除相关缓存

---

### 4.6 角色用户查询

#### 需求描述
查询某个角色下的所有用户。

#### 接口名称
角色用户查询接口

#### 设计原因
- 了解角色使用情况
- 便于角色管理
- 支持用户迁移

#### 请求类型
GET

#### 接口路径
`/roles/{roleId}/users`

#### 接口参数
```typescript
{
  page?: number;
  pageSize?: number;
  keyword?: string;
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 123,
        "username": "john_doe",
        "email": "john@example.com",
        "assignedAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 50
    }
  }
}
```

---

### 4.7 角色排序接口

#### 需求描述
支持手动调整角色的显示顺序，保证同级角色按指定顺序展示。

#### 接口名称
角色排序接口

#### 设计原因
- 角色列表需要按重要性排序
- 下拉选择时按业务优先级展示
- 管理员需要控制显示顺序

#### 请求类型
PUT

#### 接口路径
`/roles/sort`

#### 接口参数
```typescript
{
  items: Array<{
    id: number;         // 角色ID
    sortOrder: number;  // 新的排序号
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "排序更新成功",
  "data": {
    "updated": 5
  }
}
```

#### 开发思路
1. 权限检查（需要role:sort权限）
2. 批量更新sortOrder字段
3. 确保同级别角色排序唯一性
4. 清除角色缓存
5. 返回更新结果

---

### 4.8 拖拽排序接口

#### 需求描述
支持前端拖拽方式调整角色顺序，更直观的操作方式。

#### 接口名称
拖拽排序接口

#### 设计原因
- 提供更好的用户体验
- 直观的排序操作
- 减少误操作

#### 请求类型
PUT

#### 接口路径
`/roles/{roleId}/move`

#### 接口参数
```typescript
{
  targetIndex: number;  // 目标位置索引（0开始）
  pid?: number;         // 父级ID，如果跨级移动
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "移动成功",
  "data": {
    "roleId": 10,
    "oldIndex": 2,
    "newIndex": 0,
    "affectedRoles": [8, 9, 10]
  }
}
```

#### 开发思路
1. 计算目标位置的sortOrder值
2. 更新被移动角色的sortOrder
3. 调整其他角色的sortOrder（避免冲突）
4. 如果跨级移动，同时更新pid
5. 清除相关缓存

---

## 5. 权限管理模块 (Permission Management)

### 5.1 权限树查询

#### 需求描述
查询权限树形结构，按类型分组展示。

#### 接口名称
权限树查询接口

#### 设计原因
- 权限具有层级关系（菜单-页面-按钮）
- 便于权限分配时的选择
- 支持不同类型权限的管理

#### 请求类型
GET

#### 接口路径
`/permissions/tree`

#### 接口参数
```typescript
{
  type?: string;        // 权限类型：menu,button,api,data
  status?: string;      // 状态过滤
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "code": "system",
      "name": "系统管理",
      "type": "menu",
      "children": [
        {
          "id": 2,
          "code": "system:user",
          "name": "用户管理",
          "type": "menu",
          "children": [
            {
              "id": 3,
              "code": "user:read",
              "name": "查看用户",
              "type": "api",
              "resource": "user",
              "action": "read"
            }
          ]
        }
      ]
    }
  ]
}
```

#### 开发思路
1. 查询权限列表
2. 按类型分组
3. 构建树形结构
4. 使用Redis缓存

---

### 5.2 创建权限

#### 需求描述
创建新的权限节点。

#### 接口名称
创建权限接口

#### 设计原因
- 新功能需要新权限
- 灵活的权限扩展
- 支持细粒度控制

#### 请求类型
POST

#### 接口路径
`/permissions`

#### 接口参数
```typescript
{
  code: string;         // 权限代码
  name: string;         // 权限名称
  type: string;         // 权限类型
  resource?: string;    // 资源标识
  action?: string;      // 操作标识
  pid?: number;         // 父权限ID
  description?: string; // 描述
  meta?: object;        // 元数据（如图标、路由）
}
```

#### 开发思路
1. 权限检查（需要permission:create权限）
2. 验证权限代码唯一性
3. 验证父权限存在性
4. 创建权限记录
5. 清除权限缓存

---

### 5.3 批量创建权限

#### 需求描述
支持批量导入权限配置。

#### 接口名称
批量创建权限接口

#### 设计原因
- 新模块上线需要批量添加权限
- 提高配置效率
- 支持权限模板导入

#### 请求类型
POST

#### 接口路径
`/permissions/batch`

#### 接口参数
```typescript
{
  permissions: Array<{
    code: string;
    name: string;
    type: string;
    resource?: string;
    action?: string;
    pid?: number;
    description?: string;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "批量创建成功",
  "data": {
    "success": 10,
    "failed": 0,
    "errors": []
  }
}
```

#### 开发思路
1. 批量验证权限代码唯一性
2. 验证父权限存在性
3. 使用事务批量插入
4. 返回执行结果统计
5. 清除权限缓存

---

### 5.4 更新权限

#### 需求描述
更新权限信息。

#### 接口名称
更新权限接口

#### 设计原因
- 权限名称或描述可能需要调整
- 元数据更新（如菜单图标）
- 状态变更

#### 请求类型
PUT

#### 接口路径
`/permissions/{permissionId}`

#### 接口参数
```typescript
{
  name?: string;
  description?: string;
  status?: string;
  meta?: object;
  sortOrder?: number;
}
```

#### 开发思路
1. 权限检查
2. 更新权限信息
3. 清除权限缓存
4. 通知相关角色缓存更新

---

### 5.5 删除权限

#### 需求描述
删除权限节点及其子权限。

#### 接口名称
删除权限接口

#### 设计原因
- 功能下线需要删除权限
- 保持权限体系整洁
- 防止权限泄露

#### 请求类型
DELETE

#### 接口路径
`/permissions/{permissionId}`

#### 开发思路
1. 权限检查（需要permission:delete权限）
2. 检查是否有角色使用该权限
3. 递归删除子权限
4. 清除相关缓存

---

### 5.6 权限检查接口

#### 需求描述
检查当前用户是否拥有特定权限。

#### 接口名称
权限检查接口

#### 设计原因
- 前端动态控制界面元素
- 细粒度的功能控制
- 实时权限验证

#### 请求类型
POST

#### 接口路径
`/permissions/check`

#### 接口参数
```typescript
{
  permissions: string[]; // 权限代码数组
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "user:read": true,
    "user:create": true,
    "user:delete": false
  }
}
```

#### 开发思路
1. 获取当前用户所有权限
2. 批量检查请求的权限
3. 返回权限检查结果

---

### 5.7 权限排序接口

#### 需求描述
调整权限的显示顺序，特别是菜单权限的排序。

#### 接口名称
权限排序接口

#### 设计原因
- 菜单权限需要控制显示顺序
- 影响前端菜单渲染顺序
- 提升用户体验

#### 请求类型
PUT

#### 接口路径
`/permissions/sort`

#### 接口参数
```typescript
{
  items: Array<{
    id: number;
    sortOrder: number;
  }>
}
```

#### 开发思路
1. 权限检查（需要permission:sort权限）
2. 批量更新权限排序
3. 确保同级权限排序唯一
4. 清除权限缓存
5. 通知前端刷新菜单

---

## 6. 组织架构模块 (Organization Management)

### 6.1 组织树查询

#### 需求描述
查询组织架构树，支持人员统计。

#### 接口名称
组织架构树查询接口

#### 设计原因
- 直观展示组织层级关系
- 便于用户分配和管理
- 支持组织人员统计

#### 请求类型
GET

#### 接口路径
`/organizations/tree`

#### 接口参数
```typescript
{
  type?: string;        // 组织类型
  status?: string;      // 状态
  withStats?: boolean;  // 是否包含统计信息
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "code": "ROOT",
      "name": "星撰集团",
      "type": "company",
      "userCount": 100,
      "children": [
        {
          "id": 2,
          "code": "TECH",
          "name": "技术部",
          "type": "department",
          "userCount": 30,
          "leader": {
            "id": 123,
            "name": "张三"
          },
          "children": []
        }
      ]
    }
  ]
}
```

#### 开发思路
1. 查询组织列表
2. 构建树形结构
3. 如需统计：
   - 批量查询用户组织关联
   - 聚合统计各组织人数
4. 查询负责人信息
5. 使用Redis缓存

---

### 6.2 创建组织

#### 需求描述
创建新的组织节点。

#### 接口名称
创建组织接口

#### 设计原因
- 组织架构需要动态调整
- 支持业务扩展
- 灵活的组织管理

#### 请求类型
POST

#### 接口路径
`/organizations`

#### 接口参数
```typescript
{
  code: string;         // 组织代码
  name: string;         // 组织名称
  fullName?: string;    // 组织全称
  type: string;         // 组织类型
  pid?: number;         // 父组织ID
  leaderId?: number;    // 负责人ID
  address?: string;     // 地址
  phone?: string;       // 电话
  description?: string; // 描述
}
```

#### 开发思路
1. 权限检查（需要organization:create权限）
2. 验证组织代码唯一性
3. 验证父组织存在性
4. 创建组织记录
5. 计算path和level
6. 清除组织缓存

---

### 6.3 调整组织架构

#### 需求描述
支持拖拽调整组织层级关系。

#### 接口名称
调整组织架构接口

#### 设计原因
- 组织架构会随业务发展调整
- 支持灵活的组织变更
- 保持数据完整性

#### 请求类型
PUT

#### 接口路径
`/organizations/{organizationId}/move`

#### 接口参数
```typescript
{
  targetPid: number;    // 目标父组织ID
  targetIndex?: number; // 目标位置索引
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "调整成功",
  "data": {
    "id": 10,
    "oldPath": "/1/2/10/",
    "newPath": "/1/3/10/",
    "affectedCount": 5
  }
}
```

#### 开发思路
1. 验证目标组织存在性
2. 检查是否会形成循环
3. 使用事务更新：
   - 更新pid
   - 重新计算path和level
   - 更新所有子组织的path
   - 调整排序
4. 记录组织变更日志
5. 清除相关缓存

---

### 6.4 组织人员管理

#### 需求描述
管理组织内的人员分配。

#### 接口名称
组织人员分配接口

#### 设计原因
- 灵活的人员调动
- 支持批量操作
- 记录调动历史

#### 请求类型
POST

#### 接口路径
`/organizations/{organizationId}/users`

#### 接口参数
```typescript
{
  action: string;       // 操作：add,remove,move
  userIds: number[];    // 用户ID数组
  position?: string;    // 职位（添加时使用）
  isPrimary?: boolean;  // 是否主组织
  targetOrgId?: number; // 目标组织ID（移动时使用）
}
```

#### 开发思路
1. 权限检查
2. 验证用户和组织存在性
3. 执行批量操作：
   - add: 添加用户到组织
   - remove: 从组织移除用户
   - move: 移动到其他组织
4. 记录人员变动日志

---

### 6.5 删除组织

#### 需求描述
删除组织节点，处理人员安置。

#### 接口名称
删除组织接口

#### 设计原因
- 组织调整需要删除节点
- 确保人员妥善安置
- 保持数据完整性

#### 请求类型
DELETE

#### 接口路径
`/organizations/{organizationId}`

#### 接口参数
```typescript
{
  handleUsers?: string; // 人员处理方式：moveToParent,remove
  targetOrgId?: number; // 目标组织ID（自定义迁移时使用）
}
```

#### 开发思路
1. 权限检查（需要organization:delete权限）
2. 检查是否有子组织
3. 处理组织内人员
4. 软删除组织
5. 清除相关缓存

---

### 6.6 组织架构排序接口

#### 需求描述
调整同级组织的显示顺序。

#### 接口名称
组织排序接口

#### 设计原因
- 组织架构显示需要符合实际层级
- 重要部门需要前置显示
- 便于组织管理

#### 请求类型
PUT

#### 接口路径
`/organizations/{pid}/sort`

#### 接口参数
```typescript
{
  items: Array<{
    id: number;
    sortOrder: number;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "组织排序更新成功",
  "data": {
    "parentId": 1,
    "updated": 3
  }
}
```

#### 开发思路
1. 验证所有组织都属于同一父级
2. 批量更新sortOrder
3. 清除组织架构缓存
4. 返回更新结果

---

## 7. 字典管理模块 (Dictionary Management)

### 7.1 字典类型树查询

#### 需求描述
查询字典类型的树形结构，支持分类管理。

#### 接口名称
字典类型树查询接口

#### 设计原因
- 字典类型支持分类管理
- 便于字典的组织和查找
- 区分系统字典和业务字典

#### 请求类型
GET

#### 接口路径
`/dictionaries/types/tree`

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "code": "system",
      "name": "系统字典",
      "isSystem": true,
      "children": [
        {
          "id": 10,
          "code": "user_status",
          "name": "用户状态",
          "itemCount": 4
        }
      ]
    }
  ]
}
```

#### 开发思路
1. 查询所有字典类型
2. 构建树形结构
3. 统计每个类型的字典项数量
4. 使用Redis缓存

---

### 7.2 获取字典项

#### 需求描述
根据字典类型获取所有字典项，支持树形字典。

#### 接口名称
获取字典项接口

#### 设计原因
- 前端下拉框等组件需要字典数据
- 支持动态配置
- 减少硬编码

#### 请求类型
GET

#### 接口路径
`/dictionaries/items`

#### 接口参数
```typescript
{
  typeCode: string;     // 字典类型代码
  tree?: boolean;       // 是否返回树形结构
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "key": "active",
      "value": "active",
      "label": "正常",
      "labelEn": "Active",
      "color": "#52c41a",
      "sortOrder": 1,
      "extra": {}
    }
  ]
}
```

#### 开发思路
1. 根据typeCode查询字典类型
2. 查询该类型下的所有字典项
3. 如果是树形字典，构建树结构
4. 使用Redis缓存（字典变更少）

---

### 7.3 创建字典类型

#### 需求描述
创建新的字典类型。

#### 接口名称
创建字典类型接口

#### 设计原因
- 业务扩展需要新字典
- 灵活的配置管理
- 支持分类组织

#### 请求类型
POST

#### 接口路径
`/dictionaries/types`

#### 接口参数
```typescript
{
  code: string;         // 字典类型代码
  name: string;         // 字典类型名称
  pid?: number;         // 父类型ID
  description?: string; // 描述
  sortOrder?: number;   // 排序号
}
```

#### 开发思路
1. 权限检查（需要dictionary:create权限）
2. 验证代码唯一性
3. 验证父权限存在性
4. 创建字典类型
5. 清除字典缓存

---

### 7.4 批量更新字典项

#### 需求描述
支持批量更新字典项，保持顺序。

#### 接口名称
批量更新字典项接口

#### 设计原因
- 字典项通常需要批量维护
- 保持显示顺序的一致性
- 提高维护效率

#### 请求类型
PUT

#### 接口路径
`/dictionaries/types/{typeId}/items/batch`

#### 接口参数
```typescript
{
  items: Array<{
    id?: number;        // 有ID为更新，无ID为新增
    key: string;
    value: string;
    label: string;
    labelEn?: string;
    pid?: number;
    sortOrder: number;
    status?: string;
    color?: string;
    extra?: object;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "批量更新成功",
  "data": {
    "created": 3,
    "updated": 5,
    "deleted": 2
  }
}
```

#### 开发思路
1. 验证字典类型存在
2. 检查是否为系统字典
3. 验证key在类型内唯一
4. 使用事务处理：
   - 标记删除不在列表中的项
   - 更新已存在的项
   - 创建新项
5. 清除字典缓存

---

### 7.5 导出字典数据

#### 需求描述
导出字典配置用于备份或迁移。

#### 接口名称
导出字典数据接口

#### 设计原因
- 配置备份需求
- 环境间迁移
- 批量导入导出

#### 请求类型
GET

#### 接口路径
`/dictionaries/export`

#### 接口参数
```typescript
{
  typeIds?: number[];   // 指定类型ID，不传则导出全部
  format?: string;      // 导出格式：json,excel
}
```

#### 响应格式
```
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="dictionaries_20240101.json"
```

#### 开发思路
1. 查询指定的字典类型和项
2. 构建导出数据结构
3. 根据格式生成文件
4. 返回文件流

---

### 7.6 字典项排序接口

#### 需求描述
调整字典项的显示顺序，影响下拉框等组件的选项顺序。

#### 接口名称
字典项排序接口

#### 设计原因
- 下拉框选项需要按业务逻辑排序
- 常用选项前置显示
- 提升用户操作效率

#### 请求类型
PUT

#### 接口路径
`/dictionaries/types/{typeId}/items/sort`

#### 接口参数
```typescript
{
  items: Array<{
    id: number;
    sortOrder: number;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "字典项排序更新成功",
  "data": {
    "typeId": 1,
    "updated": 4
  }
}
```

#### 开发思路
1. 验证所有字典项都属于指定类型
2. 批量更新sortOrder
3. 清除字典缓存
4. 返回更新结果

---

## 8. 标签管理模块 (Tag Management)

### 8.1 标签列表查询

#### 需求描述
查询标签列表，支持按类型和使用频率排序。

#### 接口名称
标签列表查询接口

#### 设计原因
- 便于标签的统一管理
- 支持热门标签展示
- 不同类型标签分开管理

#### 请求类型
GET

#### 接口路径
`/tags`

#### 接口参数
```typescript
{
  type?: string;        // 标签类型
  keyword?: string;     // 搜索关键词
  sortBy?: string;      // 排序：usageCount,createdAt
  page?: number;
  pageSize?: number;
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": 1,
        "name": "VIP",
        "type": "user",
        "color": "#ff4d4f",
        "usageCount": 100,
        "description": "VIP用户"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 50
    }
  }
}
```

#### 开发思路
1. 构建查询条件
2. 执行分页查询
3. 根据sortBy排序
4. 返回标签列表

---

### 8.2 创建标签

#### 需求描述
创建新的标签。

#### 接口名称
创建标签接口

#### 设计原因
- 灵活的标签扩展
- 支持自定义标签
- 统一标签管理

#### 请求类型
POST

#### 接口路径
`/tags`

#### 接口参数
```typescript
{
  name: string;         // 标签名称
  type: string;         // 标签类型
  color?: string;       // 标签颜色
  description?: string; // 描述
}
```

#### 开发思路
1. 权限检查（需要tag:create权限）
2. 验证标签名称唯一性（同类型内）
3. 创建标签记录
4. 返回创建结果

---

### 8.3 标签使用统计

#### 需求描述
统计标签使用情况，生成报表。

#### 接口名称
标签使用统计接口

#### 设计原因
- 了解标签使用情况
- 优化标签体系
- 数据分析支持

#### 请求类型
GET

#### 接口路径
`/tags/statistics`

#### 接口参数
```typescript
{
  type?: string;        // 标签类型
  top?: number;         // 返回前N个
  startDate?: string;   // 统计开始时间
  endDate?: string;     // 统计结束时间
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "summary": {
      "totalTags": 50,
      "totalUsage": 1000,
      "avgUsage": 20
    },
    "topTags": [
      {
        "id": 1,
        "name": "VIP",
        "usageCount": 100,
        "percentage": 10
      }
    ],
    "trend": [
      {
        "date": "2024-01-01",
        "count": 20
      }
    ]
  }
}
```

#### 开发思路
1. 统计基础数据
2. 查询热门标签
3. 计算使用趋势
4. 整合返回结果

---

### 8.4 标签智能推荐

#### 需求描述
根据用户特征智能推荐标签。

#### 接口名称
标签推荐接口

#### 设计原因
- 提高标签使用的准确性
- 基于规则引擎自动打标
- 减少人工维护成本

#### 请求类型
POST

#### 接口路径
`/tags/recommend`

#### 接口参数
```typescript
{
  userId: number;       // 用户ID
  type: string;         // 推荐类型
  limit?: number;       // 推荐数量限制
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "recommendations": [
      {
        "tagId": 1,
        "tagName": "活跃用户",
        "confidence": 0.95,
        "reason": "最近30天登录20次"
      }
    ]
  }
}
```

#### 开发思路
1. 获取用户特征数据
2. 执行推荐规则：
   - 活跃度规则（登录次数、最后登录时间）
   - 贡献度规则（内容创作数量）
   - 消费规则（VIP等级）
3. 计算置信度
4. 返回推荐标签列表
5. 记录推荐日志

---

### 8.5 批量打标签

#### 需求描述
为多个用户批量添加或移除标签。

#### 接口名称
批量打标签接口

#### 设计原因
- 提高运营效率
- 支持批量操作
- 灵活的标签管理

#### 请求类型
POST

#### 接口路径
`/tags/batch-assign`

#### 接口参数
```typescript
{
  userIds: number[];    // 用户ID数组
  tagIds: number[];     // 标签ID数组
  action: string;       // 操作：add,remove
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "批量操作成功",
  "data": {
    "success": 50,
    "failed": 0,
    "errors": []
  }
}
```

#### 开发思路
1. 权限检查
2. 验证用户和标签存在性
3. 批量执行操作
4. 更新标签使用统计
5. 返回执行结果

---

### 8.6 标签排序接口

#### 需求描述
调整标签的显示顺序，支持热门标签前置。

#### 接口名称
标签排序接口

#### 设计原因
- 热门标签需要前置显示
- 按业务重要性排序
- 提升标签选择效率

#### 请求类型
PUT

#### 接口路径
`/tags/sort`

#### 接口参数
```typescript
{
  type?: string;        // 标签类型，为空则排序全部
  items: Array<{
    id: number;
    sortOrder: number;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "标签排序更新成功",
  "data": {
    "type": "user",
    "updated": 6
  }
}
```

#### 开发思路
1. 权限检查（需要tag:sort权限）
2. 验证标签类型一致性
3. 批量更新sortOrder
4. 更新标签缓存
5. 返回更新结果

---

## 9. 通用功能接口

### 9.1 图形验证码

#### 需求描述
生成图形验证码，用于注册、登录等场景。

#### 接口名称
获取图形验证码接口

#### 设计原因
- 防止机器人攻击
- 增强系统安全性
- 限制恶意请求

#### 请求类型
GET

#### 接口路径
`/common/captcha`

#### 接口参数
```typescript
{
  type?: string;        // 验证码类型：image,math
  width?: number;       // 图片宽度，默认120
  height?: number;      // 图片高度，默认40
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "captchaId": "xxxx-xxxx-xxxx",
    "captchaImage": "data:image/svg+xml;base64,..."
  }
}
```

#### 开发思路
1. 生成随机验证码文本
2. 生成SVG或图片
3. 存储到Redis（5分钟过期）
4. 返回Base64编码的图片

---

### 9.2 文件上传

#### 需求描述
通用文件上传接口，支持头像等文件上传。

#### 接口名称
文件上传接口

#### 设计原因
- 统一的文件上传入口
- 支持多种文件类型
- 安全的文件处理

#### 请求类型
POST

#### 接口路径
`/common/upload`

#### 请求格式
multipart/form-data

#### 接口参数
```typescript
{
  file: File;           // 文件
  type: string;         // 文件类型：avatar,document,image
  isPublic?: boolean;   // 是否公开访问，默认false
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "上传成功",
  "data": {
    "fileId": "file123456",
    "url": "https://oss.starzh.com/xxx.jpg",
    "size": 102400,
    "name": "avatar.jpg",
    "type": "image/jpeg"
  }
}
```

#### 开发思路
1. 验证文件类型和大小
2. 生成唯一文件名
3. 上传到OSS或本地存储
4. 记录文件信息到数据库
5. 返回文件访问URL

---

### 9.3 邮件发送

#### 需求描述
统一的邮件发送接口，用于系统通知。

#### 接口名称
邮件发送接口（内部接口）

#### 设计原因
- 统一邮件发送逻辑
- 支持模板化
- 便于监控和管理

#### 请求类型
POST

#### 接口路径
`/internal/email/send`

#### 接口参数
```typescript
{
  to: string[];         // 收件人邮箱数组
  template: string;     // 邮件模板ID
  params: object;       // 模板参数
  attachments?: Array<{ // 附件
    filename: string;
    content: string;
  }>;
}
```

#### 开发思路
1. 加载邮件模板
2. 渲染模板内容
3. 调用邮件服务发送
4. 记录发送日志
5. 处理发送失败（重试机制）

---

### 9.4 系统健康检查

#### 需求描述
提供系统健康状态检查接口。

#### 接口名称
健康检查接口

#### 设计原因
- 监控系统状态
- 负载均衡健康检查
- 快速发现问题

#### 请求类型
GET

#### 接口路径
`/health`

#### 响应格式
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "uptime": 3600,
    "services": {
      "database": "ok",
      "redis": "ok",
      "elasticsearch": "ok"
    }
  }
}
```

#### 开发思路
1. 检查数据库连接
2. 检查Redis连接
3. 检查其他服务状态
4. 返回综合健康状态

---

### 9.5 数据导入导出

#### 需求描述
支持批量数据的导入导出功能。

#### 接口名称
数据导出接口

#### 设计原因
- 数据备份需求
- 批量数据处理
- 数据迁移支持

#### 请求类型
POST

#### 接口路径
`/common/export`

#### 接口参数
```typescript
{
  module: string;       // 模块：users,roles,organizations
  format: string;       // 格式：excel,csv,json
  filters?: object;     // 过滤条件
  fields?: string[];    // 导出字段
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "导出任务已创建",
  "data": {
    "taskId": "export-123456",
    "status": "processing"
  }
}
```

#### 开发思路
1. 创建导出任务
2. 异步处理数据查询和转换
3. 生成导出文件
4. 通过WebSocket或轮询通知完成
5. 提供下载链接

---

### 9.6 通用排序接口

#### 需求描述
提供通用的排序接口，支持多种数据类型的排序。

#### 接口名称
通用排序接口

#### 设计原因
- 统一的排序逻辑
- 减少代码重复
- 便于维护和扩展

#### 请求类型
PUT

#### 接口路径
`/common/sort`

#### 接口参数
```typescript
{
  table: string;        // 表名：roles,permissions,organizations,tags
  scopeField?: string;  // 范围字段：pid,typeId等
  scopeValue?: any;     // 范围值
  items: Array<{
    id: number;
    sortOrder: number;
  }>
}
```

#### 响应格式
```json
{
  "code": 0,
  "message": "排序更新成功",
  "data": {
    "table": "roles",
    "scope": "pid=1",
    "updated": 5
  }
}
```

#### 开发思路
1. 验证表名和字段的安全性
2. 权限检查（根据表名动态判断）
3. 构建更新SQL
4. 批量更新排序字段
5. 清除相关缓存
6. 返回更新结果

---

## 10. 安全性设计

### 10.1 认证机制
- **JWT Token认证**
  - AccessToken有效期2小时
  - RefreshToken有效期7天
  - Token黑名单机制
  - 支持多设备登录管理

### 10.2 权限控制
- **基于RBAC的权限模型**
  - 接口级别的权限控制
  - 数据级别的权限过滤
  - 动态权限加载
  - 权限缓存优化

### 10.3 安全措施
- **传输安全**
  - 所有接口强制HTTPS
  - 敏感数据加密传输
  - 防重放攻击（时间戳+nonce）

- **输入验证**
  - 参数类型和格式验证
  - SQL注入防护（参数化查询）
  - XSS防护（输入过滤和转义）
  - 文件上传安全检查

- **访问控制**
  - IP白名单（管理接口）
  - 请求频率限制
  - 并发连接限制
  - 异常行为检测

### 10.4 日志审计
- **操作日志**
  - 记录所有写操作
  - 包含用户、时间、IP、操作内容
  - 敏感操作实时告警

- **安全日志**
  - 登录失败记录
  - 权限拒绝记录
  - 异常请求记录

---

## 11. 性能优化

### 11.1 缓存策略

| 缓存类型 | 缓存内容 | 过期时间 | 更新策略 |
|---------|---------|---------|---------|
| 用户信息缓存 | 基本信息、角色、权限 | 5分钟 | 主动更新+过期刷新 |
| 角色权限缓存 | 角色树、权限快照 | 1小时 | 变更时删除 |
| 字典缓存 | 字典类型和项 | 24小时 | 变更时删除 |
| 验证码缓存 | 图形验证码 | 5分钟 | 使用后删除 |

### 11.2 查询优化
- **索引优化**
  - 基于查询模式设计索引
  - 定期分析慢查询日志
  - 避免全表扫描

- **查询优化**
  - 使用预编译语句
  - 避免N+1查询
  - 合理使用JOIN和子查询
  - 大数据量分页优化

### 11.3 并发控制
- **限流策略**
  - 接口级别限流（令牌桶算法）
  - 用户级别限流
  - IP级别限流

- **资源控制**
  - 数据库连接池管理
  - Redis连接池管理
  - 异步任务队列

### 11.4 异步处理
- **异步任务**
  - 邮件发送
  - 文件处理
  - 数据导入导出
  - 统计计算

---

## 12. 错误处理

### 12.1 错误码规范

| 错误码范围 | 说明 | 示例 |
|-----------|------|------|
| 0 | 成功 | 操作成功 |
| 400xx | 客户端错误 | 40001-参数错误 |
| 401xx | 认证错误 | 40101-未登录 |
| 403xx | 权限错误 | 40301-无权限 |
| 404xx | 资源不存在 | 40401-用户不存在 |
| 409xx | 资源冲突 | 40901-用户名已存在 |
| 423xx | 资源锁定 | 42301-账号被锁定 |
| 429xx | 请求过多 | 42901-请求频率超限 |
| 500xx | 服务器错误 | 50001-内部错误 |
| 503xx | 服务不可用 | 50301-服务维护中 |

### 12.2 错误响应格式
```json
{
  "code": 40001,
  "message": "参数验证失败：用户名长度必须在3-50个字符之间",
  "data": {
    "field": "username",
    "value": "ab",
    "rule": "minLength"
  },
}
```

### 12.3 错误处理最佳实践
- **友好的错误提示**
  - 使用用户能理解的语言
  - 提供解决建议
  - 避免暴露技术细节

- **错误日志记录**
  - 记录完整的错误堆栈
  - 包含请求上下文
  - 分级记录（info/warn/error）

- **错误监控告警**
  - 错误率监控
  - 关键错误实时告警
  - 错误趋势分析

---

## 13. 接口版本管理

### 13.1 版本策略
- **URL版本化**
  - 格式：`/api/v{n}/...`
  - 主版本号变更表示不兼容更新
  - 向后兼容原则

### 13.2 版本迁移
- **废弃通知**
  - 提前3个月通知
  - 响应头添加废弃警告
  - 提供迁移文档

- **版本共存**
  - 新旧版本并行运行
  - 逐步迁移用户
  - 设置旧版本下线时间

---

## 14. 开发规范总结

### 14.1 接口设计原则
- **RESTful规范**
  - 使用标准HTTP方法
  - 资源导向的URL设计
  - 合理使用状态码

- **一致性原则**
  - 统一的命名规范
  - 统一的响应格式
  - 统一的错误处理

### 14.2 最佳实践
- **幂等性设计**
  - GET/PUT/DELETE操作幂等
  - POST操作防重复提交

- **分页设计**
  - 统一分页参数
  - 限制最大返回条数
  - 提供总数统计

- **数据安全**
  - 敏感数据脱敏
  - 防止信息泄露
  - 输入验证和过滤

### 14.3 文档规范
- **接口文档**
  - 使用Swagger自动生成
  - 包含请求和响应示例
  - 说明业务场景

- **变更记录**
  - 记录所有API变更
  - 说明变更原因
  - 提供升级指南

---

## 15. 附录

### 15.1 常用正则表达式
```javascript
// 用户名：3-50位字母数字下划线，字母开头
const USERNAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_]{2,49}$/;

// 邮箱
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

// 手机号（中国大陆）
const MOBILE_REGEX = /^1[3-9]\d{9}$/;

// 强密码：8-100位，包含大小写字母和数字
const PASSWORD_REGEX = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d@$!%*?&]{8,100}$/;
```

### 15.2 时间格式约定
- 统一使用ISO 8601格式
- 示例：`2024-01-01T12:00:00Z`
- 时区：统一使用UTC时间

### 15.3 分页参数约定
- `page`: 页码，从1开始
- `pageSize`: 每页条数，默认20，最大100
- `total`: 总记录数
- `totalPages`: 总页数

---

本接口设计文档为M2基础用户系统的完整API规范，后续开发应严格遵循本文档的设计要求。