# 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
```