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

完善 DTO 规范：统一 description 标签并添加 AI 助手自动检查指引
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m28s
Details

Browse Source 
- 修复所有 DTO 文件的 description 标签（10 个文件）
  - 枚举字段统一使用中文说明（用户类型、角色类型、权限类型等）
  - 状态字段明确说明 0/1 含义
  - validate 标签与 OpenAPI 标签保持一致

- 在 AGENTS.md 和 CLAUDE.md 添加 DTO 规范章节
  - AI 助手必须执行的 7 项检查清单
  - 常见枚举字段标准值参考
  - 确保未来 AI 助手自动遵循规范

- 创建规范文档
  - docs/code-review-checklist.md（Code Review 检查清单）
  - docs/dto-improvement-summary.md（DTO 改进总结）
  - docs/ai-dto-guidelines-update.md（AI 指引更新说明）

- 重新生成 OpenAPI 文档（375 个 description 标签）

影响：所有 API 字段现在都有清晰的中文说明，前端开发更友好
This commit is contained in:
huang
2026-01-20 15:10:11 +08:00
parent 1bee64fc65
commit 4abbf558e4
18 changed files with 1677 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

511
docs/api/auth.md Normal file
View File

@@ -0,0 +1,511 @@
# B 端认证 API 文档
本文档描述君鸿卡管系统 B 端认证接口（后台管理和 H5），包括登录、登出、Token 刷新、用户信息查询和密码修改功能。
---
## 概述
### 基础信息
- **后台 API 前缀**: `/api/admin`
- **H5 API 前缀**: `/api/h5`
- **认证方式**: Bearer Token (存储在 Redis)
- **Token 类型**:
- Access Token：24 小时有效期，用于 API 访问
- Refresh Token：7 天有效期，用于刷新 Access Token
### 用户类型限制
| 平台 | 允许的用户类型 |
|------|---------------|
| 后台 | SuperAdmin(1)、Platform(2)、Agent(3) |
| H5 | Agent(3)、Enterprise(4) |
---
## 公开接口（无需认证）
### 1. 用户登录
**后台**: `POST /api/admin/login`
**H5**: `POST /api/h5/login`
使用用户名或手机号 + 密码登录，返回访问令牌。
#### 请求体
```json
{
"username": "admin",
"password": "Admin@123456",
"device": "web"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名或手机号 |
| password | string | 是 | 密码 |
| device | string | 否 | 设备标识（web/ios/android） |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"access_token": "550e8400-e29b-41d4-a716-446655440000",
"refresh_token": "660f9500-f39c-52e5-b827-557766551111",
"expires_in": 86400,
"user": {
"id": 1,
"username": "admin",
"phone": "13800000000",
"user_type": 1,
"user_type_name": "超级管理员",
"shop_id": 0,
"enterprise_id": 0
},
"permissions": [
"user:create",
"user:update",
"user:delete",
"role:manage"
]
},
"timestamp": "2026-01-15T16:05:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | 请求参数不完整或格式错误 |
| 1040 | 用户名或密码错误 | 凭证无效 |
| 1011 | 账号已禁用 | 账号被禁用，无法登录 |
| 1041 | 账号已锁定 | 账号被锁定 |
#### cURL 示例
```bash
# 后台登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "Admin@123456",
"device": "web"
}'
# H5 登录
curl -X POST http://localhost:8080/api/h5/login \
-H "Content-Type: application/json" \
-d '{
"username": "agent001",
"password": "password123",
"device": "ios"
}'
```
---
### 2. 刷新访问令牌
**后台**: `POST /api/admin/refresh-token`
**H5**: `POST /api/h5/refresh-token`
使用 Refresh Token 获取新的 Access Token。
#### 请求体
```json
{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| refresh_token | string | 是 | 刷新令牌 |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"access_token": "770a0600-a40d-63f6-c938-668877662222",
"expires_in": 86400
},
"timestamp": "2026-01-15T16:06:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | refresh_token 缺失 |
| 1003 | 无效或过期的令牌 | Refresh Token 无效或已过期 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/refresh-token \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}'
```
---
## 受保护接口（需要认证）
所有受保护接口需在请求头中携带 Access Token：
```
Authorization: Bearer {access_token}
```
---
### 3. 用户登出
**后台**: `POST /api/admin/logout`
**H5**: `POST /api/h5/logout`
撤销当前 Access Token 和 Refresh Token（如果提供）。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 请求体（可选）
```json
{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| refresh_token | string | 否 | 如果提供，同时撤销 Refresh Token |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": null,
"timestamp": "2026-01-15T16:07:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1004 | 未授权访问 | Token 已被撤销 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/logout \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"refresh_token": "660f9500-f39c-52e5-b827-557766551111"
}'
```
---
### 4. 获取当前用户信息
**后台**: `GET /api/admin/me`
**H5**: `GET /api/h5/me`
获取当前登录用户的详细信息和权限列表。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": {
"user": {
"id": 1,
"username": "admin",
"phone": "13800000000",
"user_type": 1,
"user_type_name": "超级管理员",
"shop_id": 0,
"enterprise_id": 0,
"status": 1,
"created_at": "2026-01-01T00:00:00+08:00"
},
"permissions": [
"user:create",
"user:update",
"user:delete",
"role:manage",
"permission:manage"
]
},
"timestamp": "2026-01-15T16:08:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1004 | 未授权访问 | 用户信息查询失败 |
#### cURL 示例
```bash
curl -X GET http://localhost:8080/api/admin/me \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000"
```
---
### 5. 修改密码
**后台**: `POST /api/admin/password`
**H5**: `POST /api/h5/password`
修改当前用户密码，修改成功后所有旧 Token 将失效。
#### 请求头
```
Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000
```
#### 请求体
```json
{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}
```
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| old_password | string | 是 | 当前密码 |
| new_password | string | 是 | 新密码（6-20 位，包含字母和数字） |
#### 响应示例
**成功（200）**:
```json
{
"code": 0,
"message": "操作成功",
"data": null,
"timestamp": "2026-01-15T16:09:00+08:00"
}
```
#### 错误码
| 错误码 | 消息 | 说明 |
|--------|------|------|
| 1001 | 参数验证失败 | 密码格式不符合要求 |
| 1002 | 缺失认证令牌 | 请求头未携带 Authorization |
| 1003 | 无效或过期的令牌 | Access Token 无效或已过期 |
| 1043 | 旧密码错误 | 提供的旧密码不正确 |
#### cURL 示例
```bash
curl -X POST http://localhost:8080/api/admin/password \
-H "Authorization: Bearer 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}'
```
---
## 错误码对照表
### 认证相关错误（1000-1099）
| 错误码 | 消息 | HTTP 状态码 | 说明 |
|--------|------|-------------|------|
| 1001 | 参数验证失败 | 400 | 请求参数不完整或格式错误 |
| 1002 | 缺失认证令牌 | 401 | Authorization 请求头缺失 |
| 1003 | 无效或过期的令牌 | 401 | Token 无效或已过期 |
| 1004 | 未授权访问 | 401 | 无权访问该资源 |
| 1005 | 禁止访问 | 403 | 用户类型不允许访问 |
| 1040 | 用户名或密码错误 | 401 | 登录凭证错误 |
| 1011 | 账号已禁用 | 403 | 账号被管理员禁用 |
| 1041 | 账号已锁定 | 403 | 账号因安全原因被锁定 |
| 1042 | 密码已过期 | 403 | 需要更新密码 |
| 1043 | 旧密码错误 | 400 | 修改密码时提供的旧密码不正确 |
### 服务端错误（2000-2999）
| 错误码 | 消息 | HTTP 状态码 | 说明 |
|--------|------|-------------|------|
| 2001 | 内部服务器错误 | 500 | 服务器内部错误 |
| 2002 | 数据库错误 | 500 | 数据库操作失败 |
| 2003 | Redis 错误 | 500 | Redis 操作失败 |
| 2004 | 服务不可用 | 503 | 服务暂时不可用 |
---
## 使用场景示例
### 场景 1：完整登录流程
```bash
# 1. 用户登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Admin@123456"}' \
| jq
# 响应获取 access_token 和 refresh_token
# {
# "code": 0,
# "data": {
# "access_token": "550e8400-...",
# "refresh_token": "660f9500-..."
# }
# }
# 2. 使用 access_token 访问受保护接口
curl -X GET http://localhost:8080/api/admin/me \
-H "Authorization: Bearer 550e8400-..." \
| jq
# 3. Access Token 过期后，使用 Refresh Token 刷新
curl -X POST http://localhost:8080/api/admin/refresh-token \
-H "Content-Type: application/json" \
-d '{"refresh_token":"660f9500-..."}' \
| jq
# 4. 登出
curl -X POST http://localhost:8080/api/admin/logout \
-H "Authorization: Bearer 550e8400-..." \
-H "Content-Type: application/json" \
-d '{"refresh_token":"660f9500-..."}' \
| jq
```
### 场景 2：修改密码
```bash
# 1. 登录获取 token
TOKEN=$(curl -s -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"Admin@123456"}' \
| jq -r '.data.access_token')
# 2. 修改密码
curl -X POST http://localhost:8080/api/admin/password \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"old_password": "Admin@123456",
"new_password": "NewPassword@2026"
}' \
| jq
# 3. 旧 token 失效，需要重新登录
curl -X POST http://localhost:8080/api/admin/login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"NewPassword@2026"}' \
| jq
```
---
## 安全注意事项
1. **Token 存储**：
- 前端应将 Token 存储在安全位置（如 HttpOnly Cookie 或 secure storage）
- 不要将 Token 暴露在 URL 中
2. **Token 传输**：
- 始终使用 HTTPS 传输 Token
- Token 仅在 Authorization 请求头中传递
3. **密码要求**：
- 长度：6-20 位
- 必须包含字母和数字
- 建议包含特殊字符
4. **Token 生命周期**：
- Access Token：24 小时自动过期
- Refresh Token：7 天自动过期
- 修改密码后所有旧 Token 立即失效
5. **并发登录**：
- 系统支持同一用户多设备同时登录
- 每个设备拥有独立的 Token 对
- 登出只撤销当前设备的 Token
---
## 常见问题
**Q: 如何判断 Access Token 是否过期？**
A: 接口返回 `1003` 错误码时表示 Token 过期，应使用 Refresh Token 刷新。
**Q: Refresh Token 过期后怎么办？**
A: Refresh Token 过期后需要重新登录。
**Q: 修改密码后需要重新登录吗？**
A: 是的，修改密码后所有设备的 Token 都会失效，需要重新登录。
**Q: 后台用户可以使用 H5 接口吗？**
A: 不可以。后台和 H5 有不同的用户类型限制，使用错误的端点会返回 `1005` 错误。
**Q: 如何撤销所有设备的登录状态？**
A: 调用 `/api/admin/password` 修改密码，所有设备的 Token 会自动失效。
---
## 相关文档
- [使用指南](../auth-usage-guide.md) - 如何在代码中集成认证
- [架构说明](../auth-architecture.md) - 认证系统架构设计
- [错误处理指南](../003-error-handling/使用指南.md) - 统一错误处理
---
**文档版本**: v1.0
**最后更新**: 2026-01-15
**维护者**: 君鸿卡管系统开发团队