完善保险前后端、养殖端小程序

insurance_backend/docs/API认证文档.md

@@ -0,0 +1,222 @@
+# API认证文档
+
+## 概述
+
+保险端口系统API支持两种认证方式：
+1. **JWT令牌认证**：用于Web应用的用户会话认证
+2. **固定令牌认证**：用于API访问的长期认证
+
+## 认证方式
+
+### 1. JWT令牌认证
+
+#### 获取JWT令牌
+```http
+POST /auth/login
+Content-Type: application/json
+
+{
+  "username": "admin",
+  "password": "123456"
+}
+```
+
+#### 响应示例
+```json
+{
+  "code": 200,
+  "status": "success",
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "user": {
+      "id": 1,
+      "username": "admin",
+      "email": "admin@example.com"
+    }
+  }
+}
+```
+
+#### 使用JWT令牌
+在请求头中添加Authorization字段：
+```http
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+### 2. 固定令牌认证
+
+#### 生成固定令牌
+管理员可以为用户生成固定令牌：
+```http
+POST /users/{id}/fixed-token
+Authorization: Bearer <admin_jwt_token>
+```
+
+#### 响应示例
+```json
+{
+  "code": 200,
+  "status": "success",
+  "data": {
+    "token": "ft_1234567890abcdef1234567890abcdef12345678",
+    "message": "固定令牌生成成功"
+  }
+}
+```
+
+#### 使用固定令牌
+在请求头中添加Authorization字段：
+```http
+Authorization: Bearer ft_1234567890abcdef1234567890abcdef12345678
+```
+
+## 固定令牌管理
+
+### 获取令牌信息
+```http
+GET /users/{id}/fixed-token
+Authorization: Bearer <admin_jwt_token>
+```
+
+### 重新生成令牌
+```http
+PUT /users/{id}/fixed-token
+Authorization: Bearer <admin_jwt_token>
+```
+
+### 删除令牌
+```http
+DELETE /users/{id}/fixed-token
+Authorization: Bearer <admin_jwt_token>
+```
+
+## 权限控制
+
+### 权限模型
+系统采用基于角色的权限控制（RBAC），每个用户都有一个角色，角色包含多个权限。
+
+### 权限格式
+权限格式为：`资源:操作`
+- `user:read` - 读取用户信息
+- `user:create` - 创建用户
+- `user:update` - 更新用户信息
+- `user:delete` - 删除用户
+
+### 常用权限列表
+| 权限 | 描述 |
+|------|------|
+| `user:read` | 查看用户信息 |
+| `user:create` | 创建用户 |
+| `user:update` | 更新用户信息 |
+| `user:delete` | 删除用户 |
+| `insurance_applications:read` | 查看保险申请 |
+| `insurance_applications:create` | 创建保险申请 |
+| `insurance_applications:update` | 更新保险申请 |
+| `insurance_applications:delete` | 删除保险申请 |
+| `policies:read` | 查看保单 |
+| `policies:create` | 创建保单 |
+| `policies:update` | 更新保单 |
+| `policies:delete` | 删除保单 |
+| `claims:read` | 查看理赔 |
+| `claims:create` | 创建理赔 |
+| `claims:update` | 更新理赔 |
+| `claims:delete` | 删除理赔 |
+
+## 错误响应
+
+### 401 未授权
+```json
+{
+  "code": 401,
+  "status": "error",
+  "message": "未授权访问",
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### 403 权限不足
+```json
+{
+  "code": 403,
+  "status": "error",
+  "message": "权限不足",
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### 令牌过期
+```json
+{
+  "code": 401,
+  "status": "error",
+  "message": "令牌已过期",
+  "timestamp": "2024-01-01T00:00:00.000Z"
+}
+```
+
+## 安全注意事项
+
+### JWT令牌
+1. JWT令牌有效期为24小时
+2. 令牌包含用户信息和权限
+3. 令牌在服务器端无法撤销，只能等待过期
+
+### 固定令牌
+1. 固定令牌永不过期，除非手动删除
+2. 固定令牌具有与用户相同的权限
+3. 固定令牌应妥善保管，避免泄露
+4. 建议定期更换固定令牌
+
+### 最佳实践
+1. 在生产环境中使用HTTPS
+2. 定期轮换固定令牌
+3. 监控API访问日志
+4. 及时撤销不再使用的令牌
+5. 使用最小权限原则
+
+## 示例代码
+
+### JavaScript (Axios)
+```javascript
+// 使用JWT令牌
+const jwtToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
+const response = await axios.get('/users', {
+  headers: {
+    'Authorization': `Bearer ${jwtToken}`
+  }
+});
+
+// 使用固定令牌
+const fixedToken = 'ft_1234567890abcdef1234567890abcdef12345678';
+const response = await axios.get('/users', {
+  headers: {
+    'Authorization': `Bearer ${fixedToken}`
+  }
+});
+```
+
+### Python (requests)
+```python
+import requests
+
+# 使用JWT令牌
+jwt_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+headers = {'Authorization': f'Bearer {jwt_token}'}
+response = requests.get('http://localhost:3000/users', headers=headers)
+
+# 使用固定令牌
+fixed_token = 'ft_1234567890abcdef1234567890abcdef12345678'
+headers = {'Authorization': f'Bearer {fixed_token}'}
+response = requests.get('http://localhost:3000/users', headers=headers)
+```
+
+### cURL
+```bash
+# 使用JWT令牌
+curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
+     http://localhost:3000/users
+
+# 使用固定令牌
+curl -H "Authorization: Bearer ft_1234567890abcdef1234567890abcdef12345678" \
+     http://localhost:3000/users
+```