forked from erp-dev/erp
268 lines
6.5 KiB
Markdown
268 lines
6.5 KiB
Markdown
# 企业微信用户绑定 API
|
||
|
||
## 接口说明
|
||
|
||
供企业微信服务端程序调用，将企业微信 OAuth2 获取的 `user_id` 与本系统的员工（Employee）绑定。调用方需提供本系统的用户名和密码进行身份验证，验证通过后完成绑定。
|
||
|
||
## 接口信息
|
||
|
||
- **URL**: `/api/v2/wecom/binduser/`
|
||
- **方法**: `POST`
|
||
- **Content-Type**: `application/json`
|
||
- **认证方式**: 固定密钥，通过 `Authorization` 请求头传入（不使用 Bearer 前缀）
|
||
|
||
## 认证
|
||
|
||
请求必须在 `Authorization` 头中携带预分配的访问密钥（由系统管理员提供）。
|
||
|
||
```
|
||
Authorization: your-access-key
|
||
```
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| wecom_user_id | string | 是 | 企业微信 OAuth2 返回的 user_id，最长 128 字符 |
|
||
| username | string | 是 | 本系统用户名 |
|
||
| password | string | 是 | 本系统用户密码 |
|
||
| force_update | boolean | 否 | 如果该员工已绑定其他企业微信用户，是否强制覆盖。默认 `false` |
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl -X POST "https://your-domain/api/v2/wecom/binduser/" \
|
||
-H "Authorization: your-access-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"wecom_user_id": "zhangsan",
|
||
"username": "zhangsan",
|
||
"password": "mypassword123"
|
||
}'
|
||
```
|
||
|
||
## 响应说明
|
||
|
||
### 绑定成功（200 OK）
|
||
|
||
```json
|
||
{
|
||
"message": "绑定成功",
|
||
"employee_id": 42,
|
||
"employee_name": "张三",
|
||
"wecom_user_id": "zhangsan"
|
||
}
|
||
```
|
||
|
||
### 用户名或密码错误（401 Unauthorized）
|
||
|
||
```json
|
||
{
|
||
"error": "用户名或密码错误"
|
||
}
|
||
```
|
||
|
||
### 用户已被禁用（403 Forbidden）
|
||
|
||
```json
|
||
{
|
||
"error": "该用户已被禁用"
|
||
}
|
||
```
|
||
|
||
### 用户未关联员工（404 Not Found）
|
||
|
||
```json
|
||
{
|
||
"error": "该用户未关联任何员工记录"
|
||
}
|
||
```
|
||
|
||
### 企业微信用户已绑定到其他员工（409 Conflict）
|
||
|
||
```json
|
||
{
|
||
"error": "该企业微信用户已绑定到其他员工: 李四 (ID: 15)"
|
||
}
|
||
```
|
||
|
||
### 员工已绑定其他企业微信用户（409 Conflict）
|
||
|
||
当该员工已有不同的 `wecom_user_id` 且未传 `force_update=true` 时：
|
||
|
||
```json
|
||
{
|
||
"error": "该员工已绑定其他企业微信用户",
|
||
"current_wecom_user_id": "old_wecom_id",
|
||
"hint": "如需覆盖，请传入 force_update=true"
|
||
}
|
||
```
|
||
|
||
### 认证失败（401 Unauthorized）
|
||
|
||
Authorization 头缺失或密钥错误：
|
||
|
||
```json
|
||
{
|
||
"detail": "AGENT_ACCESS_KEY 无效"
|
||
}
|
||
```
|
||
|
||
### 参数验证失败（400 Bad Request）
|
||
|
||
```json
|
||
{
|
||
"wecom_user_id": ["该字段是必填项。"],
|
||
"username": ["该字段是必填项。"],
|
||
"password": ["该字段是必填项。"]
|
||
}
|
||
```
|
||
|
||
## 业务规则
|
||
|
||
1. **一对一约束**：一个企业微信 user_id 只能绑定一个员工，一个员工只能绑定一个企业微信 user_id。
|
||
2. **幂等性**：重复绑定相同的 wecom_user_id 到同一个员工不会报错，返回 200。
|
||
3. **冲突处理**：
|
||
- 如果 `wecom_user_id` 已被其他员工绑定 → 拒绝（409）
|
||
- 如果该员工已绑定不同的 `wecom_user_id` 且 `force_update=false` → 拒绝（409）
|
||
- 如果该员工已绑定不同的 `wecom_user_id` 且 `force_update=true` → 覆盖绑定
|
||
4. **身份验证**：通过 Django 内置认证机制验证用户名和密码，验证通过后通过 `User → Employee` 关系找到对应员工。
|
||
|
||
## 接入流程
|
||
|
||
```
|
||
企业微信用户 → OAuth2 授权 → 获取 wecom user_id
|
||
↓
|
||
调用本接口（传入 wecom_user_id + 本系统 username/password）
|
||
↓
|
||
验证凭据 → 查找 Employee → 写入 wecom_user_id
|
||
↓
|
||
绑定完成，后续可通过 wecom_user_id 识别用户身份
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 密码通过 HTTPS 传输，请确保生产环境使用 TLS。
|
||
2. 该接口不限制调用频率，但建议调用方做适当限流。
|
||
3. 绑定成功后，后续业务可通过 `Employee.wecom_user_id` 字段查找对应员工。
|
||
|
||
---
|
||
|
||
# 企业微信快捷登录 API
|
||
|
||
## 接口说明
|
||
|
||
供企业微信服务端程序调用，通过已绑定的 `wecom_user_id` 快捷获取本系统的 JWT token，无需再次输入用户名密码。
|
||
|
||
前提条件：该 `wecom_user_id` 必须已通过绑定接口（`/api/v2/wecom/binduser/`）完成绑定。
|
||
|
||
## 接口信息
|
||
|
||
- **URL**: `/api/v2/wecom/login/`
|
||
- **方法**: `POST`
|
||
- **Content-Type**: `application/json`
|
||
- **认证方式**: 固定密钥，通过 `Authorization` 请求头传入（与绑定接口相同）
|
||
|
||
## 认证
|
||
|
||
```
|
||
Authorization: your-access-key
|
||
```
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| wecom_user_id | string | 是 | 企业微信 OAuth2 返回的 user_id |
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl -X POST "https://your-domain/api/v2/wecom/login/" \
|
||
-H "Authorization: your-access-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"wecom_user_id": "zhangsan"
|
||
}'
|
||
```
|
||
|
||
## 响应说明
|
||
|
||
### 登录成功（200 OK）
|
||
|
||
```json
|
||
{
|
||
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||
"employee_id": 42,
|
||
"employee_name": "张三",
|
||
"username": "zhangsan"
|
||
}
|
||
```
|
||
|
||
返回的 `access` token 可直接用于后续业务 API 的 `Authorization: Bearer <token>` 认证。
|
||
|
||
### 企业微信用户未绑定（404 Not Found）
|
||
|
||
```json
|
||
{
|
||
"error": "该企业微信用户未绑定本系统员工"
|
||
}
|
||
```
|
||
|
||
### 员工未关联系统用户（404 Not Found）
|
||
|
||
```json
|
||
{
|
||
"error": "该员工未关联系统用户"
|
||
}
|
||
```
|
||
|
||
### 用户已被禁用（403 Forbidden）
|
||
|
||
```json
|
||
{
|
||
"error": "该用户已被禁用"
|
||
}
|
||
```
|
||
|
||
### 认证失败（401 Unauthorized）
|
||
|
||
Authorization 头缺失或密钥错误：
|
||
|
||
```json
|
||
{
|
||
"detail": "AGENT_ACCESS_KEY 无效"
|
||
}
|
||
```
|
||
|
||
### 参数验证失败（400 Bad Request）
|
||
|
||
```json
|
||
{
|
||
"wecom_user_id": ["该字段是必填项。"]
|
||
}
|
||
```
|
||
|
||
## 业务规则
|
||
|
||
1. 该接口仅对已完成绑定的 `wecom_user_id` 有效。
|
||
2. 每次调用都会生成新的 JWT token 对（access + refresh）。
|
||
3. access token 有效期为 7 天（与系统 JWT 配置一致）。
|
||
4. 安全边界依赖 `AGENT_ACCESS_KEY`，请妥善保管该密钥。
|
||
|
||
## 典型使用流程
|
||
|
||
```
|
||
用户首次使用：
|
||
企业微信 OAuth2 → 获取 wecom_user_id
|
||
→ 调用 /api/v2/wecom/binduser/（传 wecom_user_id + username + password）
|
||
→ 绑定完成
|
||
|
||
用户后续登录：
|
||
企业微信 OAuth2 → 获取 wecom_user_id
|
||
→ 调用 /api/v2/wecom/login/（仅传 wecom_user_id）
|
||
→ 获取 JWT token
|
||
→ 使用 token 访问业务 API
|
||
```
|