operations_project/apps/accounts/README_ACCOUNTS.md

# 账户管理模块API文档

## 简介

账户管理模块提供用户注册、登录、信息管理等功能，是系统的基础模块。本文档详细说明了各接口的使用方法、参数要求、注意事项以及可优化的地方。

## 基础URL

所有API都以`/api/accounts/`为前缀。

## 认证方式

除了登录和注册接口外，所有请求都需要在请求头中添加令牌认证信息：

```
Authorization: Token 您的认证令牌
```

## 接口列表

### 1. 用户注册

**URL**: `/api/accounts/register/`  
**方法**: POST  
**权限**: 无需认证

**请求参数**:
```json
{
  "username": "testuser",
  "password": "password123",
  "email": "test@example.com",
  "role": "member",
  "name": "测试用户",
  "department": "技术部",
  "group": "开发组"
}
```

**必填字段**: username, password, email, role, name  
**可选字段**: department, group

**响应结果**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "id": "uuid字符串",
    "username": "testuser",
    "email": "test@example.com",
    "role": "member",
    "department": "技术部",
    "name": "测试用户",
    "group": "开发组",
    "token": "认证令牌",
    "created_at": "2023-05-10 10:00:00"
  }
}
```

**注意事项**:
- `username`必须是唯一的
- `password`长度必须大于等于8位
- `role`必须是以下值之一: admin(管理员), leader(组长), member(组员)
- `email`必须是有效的邮箱格式

### 2. 用户登录

**URL**: `/api/accounts/login/`  
**方法**: POST  
**权限**: 无需认证

**请求参数**:
```json
{
  "username": "testuser",
  "password": "password123"
}
```

**响应结果**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "id": "uuid字符串",
    "username": "testuser",
    "email": "test@example.com",
    "name": "测试用户",
    "role": "member",
    "department": "技术部",
    "group": "开发组",
    "token": "认证令牌"
  }
}
```

**注意事项**:
- 登录成功后，应保存返回的token用于后续请求的认证

### 3. 用户登出

**URL**: `/api/accounts/logout/`  
**方法**: POST  
**权限**: 需要认证

**请求参数**: 无

**响应结果**:
```json
{
  "code": 200,
  "message": "登出成功",
  "data": null
}
```

**注意事项**:
- 登出后，原令牌将失效，需要重新登录获取新令牌

### 4. 获取当前用户信息

**URL**: `/api/accounts/profile/`  
**方法**: GET  
**权限**: 需要认证

**请求参数**: 无

**响应结果**:
```json
{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": "uuid字符串",
    "username": "testuser",
    "email": "test@example.com",
    "name": "测试用户",
    "role": "member",
    "department": "技术部",
    "group": "开发组",
    "date_joined": "2023-05-10 10:00:00"
  }
}
```

### 5. 更新当前用户信息

**URL**: `/api/accounts/profile/`  
**方法**: PUT  
**权限**: 需要认证

**请求参数**:
```json
{
  "name": "新名称",
  "email": "newemail@example.com",
  "department": "新部门",
  "group": "新小组"
}
```

**响应结果**:
```json
{
  "code": 200,
  "message": "用户信息更新成功，已更新字段: name, email, department, group",
  "data": {
    "id": "uuid字符串",
    "username": "testuser",
    "email": "newemail@example.com",
    "name": "新名称",
    "role": "member",
    "department": "新部门",
    "group": "新小组"
  }
}
```

**注意事项**:
- 普通用户只能更新自己的信息，且字段有限
- 请确保email格式正确

### 6. 修改密码

**URL**: `/api/accounts/change-password/`  
**方法**: POST  
**权限**: 需要认证

**请求参数**:
```json
{
  "old_password": "password123",
  "new_password": "newpassword123"
}
```

**响应结果**:
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": {
    "token": "新的认证令牌"
  }
}
```

**注意事项**:
- 修改密码成功后，原令牌将失效，响应中会返回新令牌
- 新密码长度必须大于等于8位

### 7. 验证令牌有效性

**URL**: `/api/accounts/verify-token/`  
**方法**: POST  
**权限**: 需要认证

**请求参数**: 无

**响应结果**:
```json
{
  "code": 200,
  "message": "令牌有效",
  "data": {
    "is_valid": true,
    "user": {
      "id": "uuid字符串",
      "username": "testuser",
      "email": "test@example.com",
      "name": "测试用户",
      "role": "member",
      "department": "技术部",
      "group": "开发组"
    }
  }
}
```

**用途**:
- 在前端启动时验证当前存储的令牌是否有效
- 获取当前用户的基本信息

### 8. 获取用户列表

**URL**: `/api/accounts/users/`  
**方法**: GET  
**权限**: 需要认证（不同角色看到不同范围的用户）

**请求参数**:
- `page`: 页码，默认1
- `page_size`: 每页条数，默认20
- `keyword`: 搜索关键词，可搜索用户名、邮箱、姓名或部门

**响应结果**:
```json
{
  "code": 200,
  "message": "获取用户列表成功",
  "data": {
    "total": 50,
    "page": 1,
    "page_size": 20,
    "users": [
      {
        "id": "uuid字符串",
        "username": "user1",
        "email": "user1@example.com",
        "name": "用户1",
        "role": "member",
        "department": "技术部",
        "group": "开发组",
        "is_active": true,
        "date_joined": "2023-05-01 10:00:00"
      },
      // ...更多用户
    ]
  }
}
```

**注意事项**:
- 管理员可以看到所有用户
- 部门领导只能看到本部门用户
- 普通成员只能看到自己

### 9. 获取用户详情

**URL**: `/api/accounts/users/{用户ID}/`  
**方法**: GET  
**权限**: 需要认证

**请求参数**: 无

**响应结果**:
```json
{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": "uuid字符串",
    "username": "user1",
    "email": "user1@example.com",
    "name": "用户1",
    "role": "member",
    "department": "技术部",
    "group": "开发组"
  }
}
```

**注意事项**:
- 用户ID必须是有效的UUID格式

### 10. 更新用户信息

**URL**: `/api/accounts/users/{用户ID}/update/`  
**方法**: PUT  
**权限**: 需要认证（管理员可更新任何用户，普通用户只能更新自己）

**请求参数** (管理员):
```json
{
  "email": "new@example.com",
  "name": "新名称",
  "role": "leader",
  "department": "新部门",
  "group": "新小组",
  "is_active": true
}
```

**请求参数** (普通用户，仅当更新自己时):
```json
{
  "email": "new@example.com",
  "name": "新名称"
}
```

**响应结果**:
```json
{
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "id": "uuid字符串",
    "username": "user1",
    "email": "new@example.com",
    "name": "新名称",
    "role": "leader",
    "department": "新部门",
    "group": "新小组",
    "is_active": true
  }
}
```

**注意事项**:
- 普通用户只能更新自己的信息，且可更新的字段有限
- 管理员可以更新任何用户的所有信息，包括角色和状态

### 11. 删除用户

**URL**: `/api/accounts/users/{用户ID}/delete/`  
**方法**: DELETE  
**权限**: 需要管理员权限

**请求参数**: 无

**响应结果**:
```json
{
  "code": 200,
  "message": "用户 user1 删除成功",
  "data": null
}
```

**注意事项**:
- 只有管理员可以删除用户
- 不允许删除管理员账户

## 错误响应

所有接口在发生错误时都会返回包含错误代码和错误信息的JSON响应：

```json
{
  "code": 错误代码,
  "message": "错误信息",
  "data": null
}
```

常见错误代码：
- 400: 请求参数错误
- 401: 认证失败
- 403: 权限不足
- 404: 资源不存在
- 500: 服务器内部错误

## 安全建议

1. 使用HTTPS传输所有数据
2. 前端在发送请求前应该对用户输入进行验证
3. 敏感操作应要求用户重新验证身份
4. 定期更换密码和令牌

## 性能优化建议

1. 使用缓存减少数据库查询，特别是对频繁访问的用户信息
2. 对用户列表接口实施合理的分页策略
3. 考虑使用异步任务处理耗时操作，如批量用户导入

## 需要优化的地方

### 功能优化

1. **令牌过期机制**：当前令牌没有过期时间，建议实现令牌自动过期机制，增强安全性
2. **多设备登录支持**：支持一个账号在多设备上同时登录，或提供登录设备管理功能
3. **密码策略增强**：增加密码复杂度要求，如必须包含大小写字母、数字和特殊字符等
4. **第三方登录支持**：添加微信、钉钉等第三方登录支持
5. **两步验证**：添加双因素认证，提高账号安全性

### 代码优化

1. **移除代码冗余**：一些视图函数中有重复的逻辑，应提取为通用函数
2. **统一响应格式**：确保所有接口返回一致的响应格式
3. **完善错误处理**：使用更具体的异常类型，而不是通用Exception
4. **加强参数验证**：使用序列化器进行更严格的参数验证
5. **模型优化**：理清User和UserProfile模型的关系，避免数据冗余

### 文档优化

1. **添加接口版本控制**：为API添加版本号，便于后续升级和维护
2. **完善API文档**：使用Swagger或ReDoc等工具生成更完善的API文档
3. **添加接口示例代码**：为每个接口提供不同语言的调用示例代码

## 测试建议

1. 使用Apifox或Postman创建完整的测试用例集
2. 测试不同角色用户的权限边界
3. 测试异常情况下的错误处理
4. 进行性能测试，确保接口在高负载下仍能正常工作