# 企业微信用户绑定 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
```