# 统一认证平台 - 账号同步 (M2M)

## 1. 概述
用于将外部业务系统（如 OA、CRM）的用户账号关系同步到本平台。支持批量调用。

**Base URL**: `{{API_BASE_URL}}`

## 2. 认证方式
此接口不使用签名算法，而是使用 **App Access Token**。
- **Header**: `X-App-Access-Token: <YOUR_TOKEN>`
- Token 可在平台管理界面的应用详情页查看。

## 3. 同步接口 (Sync)
创建、更新或删除用户映射关系。

- **URL**: `POST /apps/mapping/sync`
- **Content-Type**: `application/json`

### 逻辑
1. **增改模式 (UPSERT)**:
   - 根据 `mobile` 查找用户。
   - **新建用户**: 若用户不存在，必须提供 `name`（姓名）。`english_name`（英文名）可选，如未提供会自动生成并确保唯一性。
   - **已有用户**: **不允许修改** `name`、`mobile`、`english_name` 等用户基本信息。但可以修改映射信息（`mapped_key`、`mapped_email`、`is_active`）。
   - 建立或更新该用户与当前应用的映射 (`mapped_key`, `mapped_email`, `is_active`)。
2. **删除模式 (DELETE)**:
   - 仅删除该用户在当前应用下的映射关系。
   - **不删除**平台上的用户账号。
   - 必须提供 `mapped_key`，且须与平台上该映射记录中的外部账号 **一致**（用于校验）。

### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `mobile` | string | Yes | 用户手机号 (平台唯一标识)，须为 11 位中国大陆手机号（`1[3-9]` 开头） |
| `name` | string | Conditional | 用户姓名 (新建用户必填，已有用户不允许修改) |
| `english_name` | string | Optional | 英文名/拼音 (新建用户可选，如未提供会自动生成；已有用户不允许修改) |
| `mapped_key` | string | Yes | 外部系统用户 ID（映射账号，1～100 字符；可修改） |
| `mapped_email` | string | No | 外部系统邮箱 (可修改) |
| `is_active` | boolean | No | 映射状态 (默认 true，可修改) |
| `sync_action` | string | No | 操作类型: `UPSERT` (增改, 默认) 或 `DELETE` (删除映射) |

### 示例 1: 新增用户 (UPSERT)
```bash
curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "name": "张三",
           "mapped_key": "user_1001",
           "mapped_email": "zhangsan@example.com",
           "sync_action": "UPSERT"
         }'
```
注意：`english_name` 可以不提供，系统会自动生成。

### 示例 2: 更新已有用户的映射信息 (UPSERT)
```bash
curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "mapped_email": "zhangsan_new@example.com",
           "is_active": true,
           "sync_action": "UPSERT"
         }'
```
注意：已有用户不能修改 `name`、`mobile`、`english_name`，只能修改映射信息。

### 示例 3: 删除映射 (DELETE)
```bash
curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "sync_action": "DELETE"
         }'
```
（`mapped_key` 须与当前平台上该用户在本应用下的映射账号一致。）

### Response (200)
```json
{
  "id": 123,           // 映射记录 ID
  "user_id": 456,      // 平台用户 ID
  "user_mobile": "13800138000",
  "mapped_key": "user_1001",
  "is_active": true    // 删除模式下会返回 false
}
```

## 4. 错误码
- `400 Bad Request`: 
  - 参数错误（如手机号格式非法、缺少 `mapped_key`、新建用户未提供 `name`）
  - 已有用户尝试修改 `name`、`mobile` 或 `english_name`
  - 姓名/英文名已存在（新建用户时）
  - 映射关系冲突（`mapped_key` 或 `mapped_email` 已被占用）
  - `DELETE` 时 `mapped_key` 与平台记录不一致，或历史数据缺少外部账号
- `403 Forbidden`: Token 无效。