fea: business completed

docs/api_v2_wecom_binduser.md

@@ -0,0 +1,267 @@
+# 企业微信用户绑定 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
+```