Unified_Authentication_Platform/frontend/public/docs/account_sync.md

统一认证平台 - 账号同步 (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 或 english_name 且不为空，则更新用户信息；否则保留原值。
   • 建立或更新该用户与当前应用的映射 (mapped_key, mapped_email)。
2. 删除模式 (DELETE):
   • 仅删除该用户在当前应用下的映射关系。
   • 不删除平台上的用户账号。

Request Body

Field	Type	Required	Description
mobile	string	Yes	用户手机号 (平台唯一标识)
name	string	Conditional	用户姓名 (新建用户必填，已有用户选填)
english_name	string	Conditional	英文名/拼音 (新建用户必填，全局唯一)
mapped_key	string	No	外部系统用户ID
mapped_email	string	No	外部系统邮箱
is_active	boolean	No	映射状态 (默认 true)
sync_action	string	No	操作类型: UPSERT (增改, 默认) 或 DELETE (删除映射)

示例 1: 新增或更新用户 (UPSERT)

curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "name": "张三",
           "english_name": "zhangsan",
           "mapped_key": "user_1001",
           "mapped_email": "zhangsan@example.com",
           "sync_action": "UPSERT"
         }'

示例 2: 删除映射 (DELETE)

curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "sync_action": "DELETE"
         }'

Response (200)

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

4. 错误码

• 400 Bad Request: 参数错误、姓名/英文名已存在、映射关系冲突。
• 403 Forbidden: Token 无效。