# UAP 系统对接说明（面向自动化阅读）

本文档**独立成篇**，描述如何在业务系统中对接 **Unified Authentication Platform（UAP，统一认证平台）**。阅读者应能仅凭本文完成：配置项填写、登录、SSO、**用户查询与映射同步**、**消息发送**（系统通知与广播）。

### 示例约定

下文示例中：

- `https://api.hnyunzhu.com/api/v1` 表示 `UAP_API_BASE`（生产环境统一认证 API）；
- `app_demo_001`、`your_app_secret`、`eyJhbG...` 等为占位符，需替换为真实值；
- `sign` 为按第 4 节算法计算得到的 **64 位小写十六进制**字符串，示例里用 `deadbeef...` 形式表示，**不能**直接复制使用；
- 时间戳 `1710000000` 仅为示例，调用时需使用当前 Unix 秒。

---

## 1. 两类基础地址

| 变量名 | 含义 | 示例 |
|--------|------|------|
| `UAP_API_BASE` | **HTTP(S) API 根路径**，必须包含版本前缀 `/api/v1` | `https://api.hnyunzhu.com/api/v1` |
| `UAP_WEB_BASE` | **用户浏览器访问的前端站点根**（用于跳转登录页；本部署与 API 同主机） | `https://api.hnyunzhu.com` |

下文所有接口路径均相对于 `UAP_API_BASE` 拼接，例如：`UAP_API_BASE` + `/simple/login` → `https://api.hnyunzhu.com/api/v1/simple/login`。

跳转登录页使用 `UAP_WEB_BASE`：

- PC：`{UAP_WEB_BASE}/login?app_id=<APP_ID>`
- 移动端 H5：`{UAP_WEB_BASE}/mobile/login?app_id=<APP_ID>`

---

## 2. 对接前必填配置

在 UAP 管理后台创建应用后，请收集并安全保存以下信息：

| 配置项 | 说明 |
|--------|------|
| `APP_ID` | 应用对外标识（字符串，如 `app_xxxxxxxx`） |
| `APP_SECRET` | 用于 **HMAC-SHA256 签名**，**仅允许在业务服务端使用**，禁止写入前端或客户端 |
| `APP_ACCESS_TOKEN` | 应用访问令牌，用于 **M2M** 接口（HTTP Header：`X-App-Access-Token`） |
| `REDIRECT_URIS` | 在应用中配置的回调地址列表；Redirect SSO、`sso-login`、`exchange` 等流程依赖合法回调 |

可选：若使用标准 OIDC 协议，还需 OIDC 客户端凭据（本文不展开 OIDC 全流程）。

### 2.1 对接方填写（凭据留空）

实施对接时，请将贵司从 UAP 管理后台获取的值填入下表（可打印或复制后替换正文中的占位符）。**App Secret 仅保存在服务端，勿提交到代码仓库或前端。** 下表中 **API / 前端根地址** 已按当前生产环境填写；若贵司使用独立域名部署，请改为实际地址。

| 项目 | 变量名（本文档） | 填写 |
|------|------------------|------|
| API 根地址 | `UAP_API_BASE` | `https://api.hnyunzhu.com/api/v1` |
| 前端站点根地址 | `UAP_WEB_BASE` | `https://api.hnyunzhu.com` |
| App ID | `APP_ID` |  |
| App Secret | `APP_SECRET` |  |
| Access Token（应用访问令牌） | `APP_ACCESS_TOKEN` |  |

**说明：**

- **App ID**、**App Secret**：用于 Simple Auth 签名、消息接口 `X-App-Id` / `X-Sign` 等。
- **Access Token**：用于 HTTP Header `X-App-Access-Token`，对应 M2M（用户搜索、映射同步等）；**不是** App Secret。
- **`UAP_API_BASE`** 必须包含版本前缀 **`/api/v1`**；**`UAP_WEB_BASE`** 为浏览器访问登录页所用站点根（本部署与 API 同主机时为 `https://api.hnyunzhu.com`）。

---

## 3. 认证方式总览

对接时会遇到**四类**身份校验，请勿混用：

| 方式 | 典型场景 | 请求形式 |
|------|----------|----------|
| **A. JSON Body 签名（Simple Auth）** | `/simple/login`、`/simple/validate`、`/simple/exchange` 等 | Body 内含 `timestamp`、`sign`，用 `APP_SECRET` 对**除 `sign` 外**的参数做 HMAC-SHA256（见第 4 节） |
| **B. HTTP Header 签名（应用调消息接口）** | 服务端代应用调用 `POST /messages/` | Header：`X-App-Id`、`X-Timestamp`、`X-Sign`（签名字符串仅含 `app_id` 与 `timestamp`，见第 4.2 节） |
| **C. 用户 JWT** | 用户已登录 UAP 后调用需身份的接口（如 `POST /auth/login/json`、管理类接口等） | `Authorization: Bearer <access_token>` |
| **D. M2M 访问令牌** | 用户搜索、映射同步、全量用户拉取 | `X-App-Access-Token: <APP_ACCESS_TOKEN>`（部分场景亦支持应用 JWT Bearer，与平台实现一致） |

---

## 4. 签名算法（HMAC-SHA256）

平台校验逻辑与实现一致：**参数键名按 ASCII 升序排列**，拼接为 `key1=value1&key2=value2`（不含 `sign`），再对拼接串做 **HMAC-SHA256**，密钥为 UTF-8 编码的 `APP_SECRET`，结果为小写 **十六进制**字符串。

**时间戳**：`timestamp` 为 Unix 秒级整数；服务端对时间偏差有约 **300 秒**容差。

### 4.1 Simple Auth（JSON Body）

参与签名的键为请求 JSON 中**除 `sign` 以外**的所有键（`None` 值一般应排除，与常见实现一致）；**仅包含实际发送的字段**。各接口以下文「参与签名的字段」为准。

**Python 示例：**

```python
import hmac
import hashlib

def sign_simple_auth(secret: str, params: dict) -> str:
    data = {k: v for k, v in params.items() if k != "sign" and v is not None}
    query_string = "&".join(f"{k}={data[k]}" for k in sorted(data.keys()))
    return hmac.new(
        secret.encode("utf-8"),
        query_string.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
```

### 4.2 消息接口（Header 签名）

仅对两个键签名：`app_id`（即 `X-App-Id` 的值）、`timestamp`（即 `X-Timestamp` 的字符串值，与 Header 中一致）。拼接串为：

`app_id=<APP_ID>&timestamp=<TIMESTAMP>`

对该字符串做 HMAC-SHA256，结果放入 `X-Sign`。

**消息 Header 签名示例（伪代码）：**

- 待签名字符串：`app_id=app_demo_001&timestamp=1710000000`
- `X-Timestamp` 取值与字符串中的 `timestamp` **完全一致**（通常为数字的十进制字符串，如 `"1710000000"`）。

```http
X-App-Id: app_demo_001
X-Timestamp: 1710000000
X-Sign: 1a2b3c4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcd
```

---

## 5. 登录相关接口

### 5.1 `POST /simple/login`（密码登录）

- **Content-Type**：`application/json`
- **说明**：未提供 `app_id` 时为**平台账号登录**（返回用户 JWT）；提供 `app_id` 时为**应用 SSO 登录**（返回 `ticket`）。应用侧若提供 `sign` / `timestamp`，二者须**同时**出现，且服务端会校验签名（推荐服务端调用时始终带签名）。

#### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `app_id` | string \| null | 否 | 不提供：平台登录；提供：应用 SSO，返回 `ticket` |
| `identifier` | string | 是 | 用户标识：手机号、映射 `mapped_key` 或映射邮箱等（平台登录时按手机号查找） |
| `password` | string | 是 | 登录密码 |
| `remember_me` | boolean | 否 | 默认 `false`；为 `true` 时 JWT 有效期延长（**仅平台登录**生效） |
| `timestamp` | int | 条件 | 与 `sign` 同时提供或同时省略；提供时参与签名 |
| `sign` | string | 条件 | HMAC-SHA256 十六进制；**应用 SSO 时推荐必带** |

**应用 SSO 且启用签名时，参与签名的字段为**：`app_id`、`identifier`、`password`、`timestamp`（不含 `remember_me`）。

#### 响应 `200`：`PasswordLoginResponse`

| 字段 | 类型 | 何时出现 | 说明 |
|------|------|----------|------|
| `ticket` | string \| null | 提供 `app_id` 且登录成功 | 临时票据，供 `POST /simple/validate` 使用 |
| `access_token` | string \| null | **未**提供 `app_id` 且登录成功 | 用户 JWT |
| `token_type` | string \| null | 平台登录成功 | 固定为 `bearer` |
| `role` | string \| null | 平台登录成功 | 如 `SUPER_ADMIN`、`DEVELOPER`、`ORDINARY_USER` |

应用 SSO 成功时典型返回：`{ "ticket": "<票据字符串>" }`（无 `access_token`）。

#### 调用与返回示例

**A. 应用 SSO（带签名，返回 `ticket`）**

```http
POST https://api.hnyunzhu.com/api/v1/simple/login HTTP/1.1
Content-Type: application/json

{
  "app_id": "app_demo_001",
  "identifier": "13800138000",
  "password": "UserPassword123",
  "timestamp": 1710000000,
  "sign": "1a2b3c4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcd"
}
```

`sign` 由 `APP_SECRET` 对以下键签名（不含 `sign`）：`app_id`、`identifier`、`password`、`timestamp`。

**响应 `200`：**

```json
{
  "ticket": "TICKET-7f8e9d0a-1234-5678-abcd-ef0123456789"
}
```

**B. 平台登录（无 `app_id`，返回 JWT）**

```http
POST https://api.hnyunzhu.com/api/v1/simple/login HTTP/1.1
Content-Type: application/json

{
  "identifier": "13800138000",
  "password": "UserPassword123",
  "remember_me": false
}
```

**响应 `200`：**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0In0.xxx",
  "token_type": "bearer",
  "role": "ORDINARY_USER"
}
```

**错误示例（密码错误，`401`）：**

```json
{
  "detail": "密码错误"
}
```

#### 常见错误 HTTP 状态与 `detail`（节选）

| 状态码 | 含义（示例） |
|--------|----------------|
| 400 | 用户已禁用、签名无效（应用侧） |
| 401 | 密码错误 |
| 404 | 用户未找到、应用未找到 |

---

### 5.2 `POST /simple/sms-login`（短信验证码登录）

- **Content-Type**：`application/json`
- **说明**：逻辑与 5.1 对称——无 `app_id` 返回平台 JWT；有 `app_id` 返回 `ticket`。签名可选；若带 `sign` 必须同时带 `timestamp`。短信功能需在平台开启（否则可能 `403`）。

#### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mobile` | string | 是 | 手机号 |
| `code` | string | 是 | 短信验证码 |
| `remember_me` | boolean | 否 | 默认 `false`；影响平台登录 JWT 有效期 |
| `app_id` | string \| null | 否 | 不提供：平台登录；提供：应用 SSO，返回 `ticket` |
| `timestamp` | int | 条件 | 与 `sign` 成对出现 |
| `sign` | string | 条件 | 应用 SSO 且启用签名时：**参与签名的字段为** `app_id`、`mobile`、`code`、`timestamp` |

#### 响应 `200`

与 **5.1** 相同，使用 `PasswordLoginResponse`（`ticket` 或 `access_token` + `token_type` + `role`）。

#### 调用与返回示例

**应用 SSO（带签名）**

```http
POST https://api.hnyunzhu.com/api/v1/simple/sms-login HTTP/1.1
Content-Type: application/json

{
  "app_id": "app_demo_001",
  "mobile": "13800138000",
  "code": "123456",
  "timestamp": 1710000000,
  "sign": "2b3c4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcde"
}
```

参与签名的键：`app_id`、`mobile`、`code`、`timestamp`。

**响应 `200`：**

```json
{
  "ticket": "TICKET-8a9b0c1d-2345-6789-bcde-f01234567890"
}
```

**平台短信登录（无 `app_id`）**

```json
{
  "mobile": "13800138000",
  "code": "123456",
  "remember_me": false
}
```

**响应 `200`：**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "role": "ORDINARY_USER"
}
```

#### 常见错误（节选）

| 状态码 | 含义（示例） |
|--------|----------------|
| 400 | 验证码错误或已过期、用户已禁用 |
| 403 | 短信登录功能未开启 |
| 404 | 用户未找到、应用未找到 |

---

### 5.3 `POST /simple/validate`（验证票据）

- **Content-Type**：`application/json`
- **认证**：必须使用 **目标应用**的 `APP_SECRET` 对 Body 签名（`sign` / `timestamp` **必填**）。

#### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `ticket` | string | 是 | 来自登录跳转、`exchange`、`sso-login` 等流程的票据 |
| `app_id` | string | 是 | **消费票据的应用** ID（与为该应用签名的 Secret 一致） |
| `timestamp` | int | 是 | Unix 秒 |
| `sign` | string | 是 | 参与签名的字段为：`ticket`、`app_id`、`timestamp` |

#### 响应 `200`：`TicketValidateResponse`

**票据有效时：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `valid` | bool | `true` |
| `user_id` | int | 平台用户主键 |
| `mobile` | string | 用户手机号 |
| `mapped_key` | string \| null | 该用户在**当前应用**下的映射账号（无映射时为 `null`） |
| `mapped_email` | string \| null | 该用户在**当前应用**下的映射邮箱 |

**票据无效或已消费：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `valid` | bool | `false` |
| `user_id`、`mobile` 等 | — | 一般为 `null` 或省略（以实际 JSON 为准） |

#### 调用与返回示例

参与签名的键：`ticket`、`app_id`、`timestamp`（不含 `sign`）。

```http
POST https://api.hnyunzhu.com/api/v1/simple/validate HTTP/1.1
Content-Type: application/json

{
  "app_id": "app_demo_001",
  "ticket": "TICKET-7f8e9d0a-1234-5678-abcd-ef0123456789",
  "timestamp": 1710000001,
  "sign": "3c4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcdef"
}
```

**响应 `200`（成功）：**

```json
{
  "valid": true,
  "user_id": 1001,
  "mobile": "13800138000",
  "mapped_key": "ext_user_001",
  "mapped_email": "zhangsan@example.com"
}
```

**响应 `200`（票据无效或已使用）：**

```json
{
  "valid": false
}
```

**错误示例（签名错误，`400`）：**

```json
{
  "detail": "签名无效"
}
```

#### 常见错误

| 状态码 | 含义（示例） |
|--------|----------------|
| 400 | 签名无效 |
| 404 | 应用未找到 |

---

### 5.4 平台用户登录（获取 JWT，非 Simple 票据流程）

#### `POST /auth/login/json`

- **Content-Type**：`application/json`

**请求体：**

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mobile` | string | 是 | 用户手机号（平台账号） |
| `password` | string | 是 | 密码 |
| `remember_me` | boolean | 否 | 默认 `false`；`true` 时使用更长有效期 JWT |
| `app_id` | string \| null | 否 | 可选；直接平台登录通常可省略 |

**响应 `200`：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `access_token` | string | 用户 JWT |
| `token_type` | string | 固定为 `bearer` |

**常见错误：** `400`（手机号或密码错误、账户已禁用）、`403`（账户待审核）。

#### 调用与返回示例

**`POST /auth/login/json`**

```http
POST https://api.hnyunzhu.com/api/v1/auth/login/json HTTP/1.1
Content-Type: application/json

{
  "mobile": "13800138000",
  "password": "UserPassword123",
  "remember_me": true
}
```

**响应 `200`：**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

**`POST /auth/login`（表单）**

```http
POST https://api.hnyunzhu.com/api/v1/auth/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded

username=13800138000&password=UserPassword123
```

**响应 `200`：** 与 JSON 登录相同。

**错误示例（`400`）：**

```json
{
  "detail": "手机号或密码错误"
}
```

（`POST /auth/login` 表单字段与响应与上表一致，见上文 HTTP 示例。）

---

## 6. SSO 相关接口

### 6.1 浏览器跳转登录（Redirect SSO）

**非 JSON 接口**，步骤如下：

1. 浏览器访问：`{UAP_WEB_BASE}/login?app_id=<APP_ID>` 或 `{UAP_WEB_BASE}/mobile/login?app_id=<APP_ID>`。
2. 用户在 UAP 登录成功后，浏览器重定向到应用配置的**回调 URL**，查询参数携带 `ticket=<票据>`。
3. 应用**服务端**调用 **`POST /simple/validate`**（见 5.3）换用户信息并建立会话。

**前提**：回调地址必须在应用 `REDIRECT_URIS` 中配置。

#### 调用与返回示例

**浏览器打开登录页（仅说明 URL，无 JSON Body）：**

```
https://api.hnyunzhu.com/login?app_id=app_demo_001
```

**登录成功后，浏览器跳转到应用回调（示例）：**

```
https://biz.example.com/oauth/callback?ticket=TICKET-7f8e9d0a-1234-5678-abcd-ef0123456789
```

业务后端再使用 **5.3** 的 `POST /simple/validate` 换用户信息。

---

### 6.2 `POST /simple/sso-login`（API 获取跳转 URL）

- **Content-Type**：`application/json`
- **说明**：返回业务系统带 `ticket` 的完整 **`redirect_url`**，客户端应**导航**至该 URL。目标应用须存在；**SIMPLE_API** 应用返回 `回调地址?ticket=...`；**OIDC** 应用返回简化后的根 URL（仅 `scheme`+`netloc`），详见下表。

#### 请求头（二选一）

| 模式 | 请求头 / Body |
|------|----------------|
| 会话模式 | `Authorization: Bearer <用户 access_token>`；Body 仅需目标应用 `app_id` |
| 凭据模式 | 无 Bearer；Body 须含 `app_id`、`username`、`password` |

#### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `app_id` | string | 是 | 要进入的**目标应用** ID |
| `username` | string | 条件 | 未带有效 Bearer 时**必填**：手机号、映射 key 或映射邮箱等 |
| `password` | string | 条件 | 未带有效 Bearer 时**必填** |

#### 响应 `200`：`SsoLoginResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `redirect_url` | string | **SIMPLE_API**：`{首个 redirect_uri}?ticket=<票据>`；**OIDC**：回调 URI 解析后的 `scheme://host[:port]`（无路径） |

#### 常见错误

| 状态码 | 含义（示例） |
|--------|----------------|
| 400 | 应用未找到、未配置重定向 URI、用户已禁用、协议不支持等 |
| 401 | 认证失败 |

#### 调用与返回示例

**会话模式（已持有用户 JWT）**

```http
POST https://api.hnyunzhu.com/api/v1/simple/sso-login HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "app_id": "target_app_002"
}
```

**响应 `200`（SIMPLE_API 应用）：**

```json
{
  "redirect_url": "https://biz.example.com/callback?ticket=TICKET-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
}
```

**凭据模式（未登录）**

```http
POST https://api.hnyunzhu.com/api/v1/simple/sso-login HTTP/1.1
Content-Type: application/json

{
  "app_id": "target_app_002",
  "username": "13800138000",
  "password": "UserPassword123"
}
```

**响应 `200`：** 同上，为带 `ticket` 的 `redirect_url`。

---

### 6.3 `POST /simple/exchange`（源应用用户免登进目标应用）

- **Content-Type**：`application/json`
- **签名**：使用**源应用** `APP_SECRET`；`sign` / `timestamp` **必填**。

#### 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `app_id` | string | 是 | **源应用** ID |
| `target_app_id` | string | 是 | **目标应用** ID |
| `user_mobile` | string | 是 | 用户在 UAP 的手机号（须已存在） |
| `timestamp` | int | 是 | Unix 秒 |
| `sign` | string | 是 | 参与签名：`app_id`、`target_app_id`、`user_mobile`、`timestamp` |

#### 响应 `200`：`TicketExchangeResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `ticket` | string | 目标应用可用的票据 |
| `redirect_url` | string | 目标应用首个 `redirect_uri` 拼接 `?ticket=<ticket>` 的完整 URL（若未配置合法 URI，实现中可能回退占位，生产环境应保证配置正确） |

#### 常见错误

| 状态码 | 含义（示例） |
|--------|----------------|
| 400 | 签名无效 |
| 404 | 源应用 / 目标应用 / 用户未找到 |

目标应用收到 `ticket` 后，用**目标应用**的 `app_id` + `APP_SECRET` 调用 **`POST /simple/validate`**。

#### 调用与返回示例

参与签名的键：`app_id`、`target_app_id`、`user_mobile`、`timestamp`（使用**源应用** Secret）。

```http
POST https://api.hnyunzhu.com/api/v1/simple/exchange HTTP/1.1
Content-Type: application/json

{
  "app_id": "source_app_001",
  "target_app_id": "target_app_002",
  "user_mobile": "13800138000",
  "timestamp": 1710000002,
  "sign": "4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcdef01"
}
```

**响应 `200`：**

```json
{
  "ticket": "TICKET-bbbbcccc-dddd-eeee-ffff-000011112222",
  "redirect_url": "https://target.example.com/callback?ticket=TICKET-bbbbcccc-dddd-eeee-ffff-000011112222"
}
```

---

### 6.4 `GET /simple/sso/jump`（通知内嵌 SSO 跳转）

用于消息中配置的跳转：用户点击后，若已在 UAP 登录则带上 Ticket 重定向到应用回调。

#### 查询参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `app_id` | string | 是 | 目标应用 ID |
| `redirect_to` | string | 是 | 登录成功后最终要到达的业务页 URL（经 URL 编码传入） |

#### 响应行为（非 JSON）

| 场景 | HTTP | 说明 |
|------|------|------|
| 当前**未**登录 UAP | `307`/`302` 等 | `RedirectResponse` 到相对路径 `/login?redirect=<当前完整 jump URL>`（依赖网关/前端将用户导向登录页） |
| 当前**已**登录 | `307`/`302` 等 | 重定向到应用 `redirect_uris` 中首个 URI，查询参数包含 `ticket`、`next`（`next` 为 `redirect_to`） |
| 应用不存在 | 404 | `detail` 说明 |
| 未配置回调 | 400 | `detail` 说明 |

#### 调用与返回示例

**请求 URL（`redirect_to` 需 URL 编码）：**

```
GET https://api.hnyunzhu.com/api/v1/simple/sso/jump?app_id=app_demo_001&redirect_to=https%3A%2F%2Foa.example.com%2Fapprove%2F123
```

**已登录时：** HTTP 重定向（`302`/`307`），`Location` 类似：

```
https://biz.example.com/callback?ticket=TICKET-xxx&next=https%3A%2F%2Foa.example.com%2Fapprove%2F123
```

**未登录时：** 重定向到登录页，`Location` 可能类似：

```
/login?redirect=https%3A%2F%2Fapi.hnyunzhu.com%2Fapi%2Fv1%2Fsimple%2Fsso%2Fjump%3Fapp_id%3D...
```

---

## 7. 用户接口（M2M）

以下接口使用 **`X-App-Access-Token: <APP_ACCESS_TOKEN>`**（或实现所支持的应用 JWT），**不使用** Simple Auth 的 Body 签名。

### 7.1 推荐业务流程（查询 → 建用户 / 推映射）

对接方在「把业务账号与平台用户绑定」时，建议按下面顺序操作：

1. **先查询用户**  
   调用 **`GET /users/search`**（见 **7.2**），用手机号、姓名等关键词确认平台是否**已存在**该用户，并记录返回中的 **`id`（平台用户 ID）**、`mobile`、`name` 等。  
   - **能查到**：说明平台已有账号，只需为本应用维护**映射**（`mapped_key`、`mapped_email` 等）。  
   - **查不到**：需先在平台**创建用户**，再推映射。创建方式包括：  
     - 在 **UAP 管理后台**人工新增；或  
     - 若贵司具备超级管理员能力，调用管理端 **`POST /users/`** 创建（需管理员权限）；或  
     - 直接使用 **`POST /apps/mapping/sync`** 的 **`UPSERT`**：当手机号在平台不存在时，可在同一请求中携带 **`name`** 等，由平台**新建用户并建立映射**（见 **7.3**）。

2. **填充本应用账号信息并同步**  
   使用查询到的 **`mobile`**（及必要时 **`name`**）与业务侧 **`mapped_key` / `mapped_email`**，调用 **`POST /apps/mapping/sync`**：  
   - **新增绑定**：`sync_action` 为 **`UPSERT`**（默认），平台会插入或更新**当前应用**下的映射；若本次同时新建了平台用户，响应中 **`new_user_created`** 为 `true`。  
   - **仅改映射**：对已存在用户再次 **`UPSERT`**，可更新 `mapped_key`、`mapped_email`、`is_active` 等；**不可**通过该接口修改已存在用户的姓名、手机号等基础档案（与接口校验一致）。  
   - **解除映射**：`sync_action` 为 **`DELETE`**（仅删映射，不删平台用户）。

3. **全量对账（可选）**  
   需要批量拉取平台用户基础信息时，使用 **`GET /apps/mapping/users`**（见 **7.4**）。

---

### 7.2 `GET /users/search`（用户查询）

- **说明**：按关键词搜索**已激活、未删除**的平台用户，用于在推映射前确认人选。支持 **应用访问令牌** 或用户 JWT。
- **路径**：`GET /users/search`
- **认证**：`X-App-Access-Token: <APP_ACCESS_TOKEN>`，或 `Authorization: Bearer <用户 JWT>`

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `q` | string | 否 | — | 关键词；对**手机号、姓名、英文名**模糊匹配（`ilike`）。不传时返回一批活跃用户（受 `limit` 限制） |
| `limit` | int | 否 | 20 | 最大返回条数 |

**说明**：若使用**用户 JWT** 调用，结果中会**排除当前登录用户本人**；使用 **应用令牌** 时无此排除。

#### 响应 `200`

返回 **JSON 数组**，元素为平台用户对象，主要字段如下：

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 平台用户 ID（可用于发消息时的 `receiver_id` 等） |
| `mobile` | string | 手机号 |
| `name` | string \| null | 姓名 |
| `english_name` | string \| null | 英文名 |
| `status` | string | 如 `ACTIVE` |
| `role` | string \| null | 角色 |
| `created_at` | string | 创建时间 ISO8601 |
| `updated_at` | string | 更新时间 ISO8601 |
| `is_deleted` | int | 是否删除标记 |

#### 调用与返回示例

```http
GET https://api.hnyunzhu.com/api/v1/users/search?q=13800138000&limit=20 HTTP/1.1
X-App-Access-Token: pA9s8d7f6g5h4j3k2l1m0n9o8p7q6r5s4t3u2v1w0
```

**响应 `200` 示例：**

```json
[
  {
    "id": 1001,
    "mobile": "13800138000",
    "name": "张三",
    "english_name": "zhangsan",
    "status": "ACTIVE",
    "role": "ORDINARY_USER",
    "created_at": "2025-01-10T08:00:00",
    "updated_at": "2025-06-01T12:00:00",
    "is_deleted": 0
  }
]
```

---

### 7.3 `POST /apps/mapping/sync`

- **Content-Type**：`application/json`

#### 请求体字段 `UserSyncRequest`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mobile` | string | 是 | 中国大陆手机号，正则 `^1[3-9]\d{9}$`（与平台校验一致） |
| `name` | string \| null | 条件 | **UPSERT 时必填**（非空姓名）；已存在用户时**不可**通过此接口改姓名等基础信息；**DELETE** 可不依赖姓名逻辑（以 `sync_action` 分支为准） |
| `english_name` | string \| null | 否 | 已废弃于 M2M；英文名由平台按规则生成 |
| `password` | string \| null | 否 | 按平台实现（若有） |
| `status` | string \| null | 否 | 按平台实现 |
| `mapped_key` | string | 是 | 外部系统用户 ID，长度 1～100 |
| `mapped_email` | string \| null | 否 | 外部邮箱 |
| `is_active` | boolean \| null | 否 | 映射是否启用；`null` 表示不修改 |
| `sync_action` | string \| null | 否 | `UPSERT`（默认）或 `DELETE` |

#### 响应 `200`：`MappingResponse`

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 映射记录 ID |
| `app_id` | int | 应用**数据库主键**（整数） |
| `user_id` | int | 平台用户 ID |
| `mapped_key` | string \| null | 映射账号 |
| `mapped_email` | string \| null | 映射邮箱 |
| `user_mobile` | string | 用户手机号 |
| `user_status` | string | 用户统一状态描述 |
| `is_active` | bool | 映射是否有效；DELETE 后可能为 `false` |
| `new_user_created` | bool | 是否本次新建了平台用户 |
| `generated_password` | string \| null | 若平台为新用户生成了初始密码，可能返回 |

#### 常见错误

| 状态码 | 含义（节选） |
|--------|----------------|
| 400 | 参数非法、与业务规则冲突（如重复映射、禁止修改字段） |
| 403 | Token 无效 |

#### 调用与返回示例

**UPSERT**

```http
POST https://api.hnyunzhu.com/api/v1/apps/mapping/sync HTTP/1.1
Content-Type: application/json
X-App-Access-Token: pA9s8d7f6g5h4j3k2l1m0n9o8p7q6r5s4t3u2v1w0

{
  "mobile": "13800138000",
  "name": "张三",
  "mapped_key": "ext_user_1001",
  "mapped_email": "zhangsan@partner.com",
  "is_active": true,
  "sync_action": "UPSERT"
}
```

**响应 `200`：**

```json
{
  "id": 501,
  "app_id": 12,
  "user_id": 1001,
  "mapped_key": "ext_user_1001",
  "mapped_email": "zhangsan@partner.com",
  "user_mobile": "13800138000",
  "user_status": "ACTIVE",
  "is_active": true,
  "new_user_created": true,
  "generated_password": null
}
```

**DELETE（仅删除映射）**

```http
POST https://api.hnyunzhu.com/api/v1/apps/mapping/sync HTTP/1.1
Content-Type: application/json
X-App-Access-Token: pA9s8d7f6g5h4j3k2l1m0n9o8p7q6r5s4t3u2v1w0

{
  "mobile": "13800138000",
  "mapped_key": "ext_user_1001",
  "sync_action": "DELETE"
}
```

**响应 `200`：** 结构同 `MappingResponse`，`is_active` 可能为 `false`（见字段表）。

---

### 7.4 `GET /apps/mapping/users`

- **认证**：`X-App-Access-Token`

#### 查询参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `skip` | int | 否 | 0 | 跳过条数 |
| `limit` | int | 否 | 100 | 每页条数 |

#### 响应 `200`：`UserSyncList`

| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | int | 符合条件的用户总数 |
| `items` | array | 用户列表 |

**`items[]` 元素 `UserSyncSimple`：**

| 字段 | 类型 | 说明 |
|------|------|------|
| `mobile` | string | 手机号 |
| `name` | string \| null | 姓名 |
| `english_name` | string \| null | 英文名 |

#### 调用与返回示例

```http
GET https://api.hnyunzhu.com/api/v1/apps/mapping/users?skip=0&limit=100 HTTP/1.1
X-App-Access-Token: pA9s8d7f6g5h4j3k2l1m0n9o8p7q6r5s4t3u2v1w0
```

**响应 `200`：**

```json
{
  "total": 1250,
  "items": [
    {
      "mobile": "13800138000",
      "name": "张三",
      "english_name": "zhangsan"
    },
    {
      "mobile": "13900139000",
      "name": "李四",
      "english_name": "lisi"
    }
  ]
}
```

---

## 8. 消息发送接口（仅 `POST /messages/`）

本节**仅**说明由**应用服务端**调用、使用 **Header 签名**（第 3 节方式 B、第 4.2 节）发送 **`NOTIFICATION`** 的两种形态：

1. **单用户系统通知**（指定一名接收者）  
2. **广播**（向全体活跃用户各发一条）

不涉及用户间私信（`type: MESSAGE`）及用户 JWT 代发，对接方无需关注。

- **路径**：`POST /messages/`
- **Content-Type**：`application/json`

### 8.1 请求头（应用签名）

| Header | 说明 |
|--------|------|
| `Content-Type` | `application/json` |
| `X-App-Id` | 应用字符串 ID，与 `APP_ID` 一致 |
| `X-Timestamp` | Unix 秒（与签名、Body 中逻辑一致） |
| `X-Sign` | 对 `app_id=<X-App-Id>&timestamp=<X-Timestamp>` 的 HMAC-SHA256 十六进制 |

#### `content_type` 取值说明

与后端枚举一致，发送时传**字符串**（大写）。未传时默认 **`TEXT`**。

| 取值 | 含义 | `content` 建议形态 |
|------|------|-------------------|
| `TEXT` | 普通文本通知 | 字符串 |
| `IMAGE` | 图片 | 对象存储中的 **Object Key** 或经平台处理的资源标识；若误传完整 URL，服务端可能尝试抽取 Key |
| `VIDEO` | 视频 | 同上 |
| `FILE` | 文件 | 同上 |
| `USER_NOTIFICATION` | **业务/申请类通知**（会话列表中突出标题、正文可结构化） | **字符串**或 **JSON 对象**；传对象时服务端会序列化为 JSON 字符串存储，客户端常对 `content` 做 `JSON.parse` 解析 |

**与 `auto_sso` 的关系**：当 `auto_sso=true` 且已提供 `target_url`、应用 `app_id` 时，只要 **`type` 为 `NOTIFICATION`** 或 **`content_type` 为 `USER_NOTIFICATION`**，平台都会按同一规则生成 **SSO jump** 形式的 `action_url`（见下文示例）。

**选用建议**：常规系统通知用 `TEXT`；需要「申请单样式」、富文本结构或前端自定义渲染时，可改用 `USER_NOTIFICATION` 并在 `content` 中传结构化数据。

---

### 8.2 单用户系统通知（`type: NOTIFICATION`，非广播）

向**一名**接收者推送。接收人二选一指定：

- **`receiver_id`**：平台用户 ID（整数）；或
- **`app_id` + `app_user_id`**：应用字符串 ID + 该用户在本应用映射中的外部账号。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `type` | string | 是 | 固定 `NOTIFICATION` |
| `title` | string | 是 | 标题，最大 255 字 |
| `content` | string \| object | 是 | 正文；`content_type` 为 `USER_NOTIFICATION` 时可传对象，见 **8.1 `content_type` 取值说明** |
| `content_type` | string | 否 | 默认 `TEXT`；可选：`TEXT`、`IMAGE`、`VIDEO`、`FILE`、`USER_NOTIFICATION`（见 **8.1**） |
| `receiver_id` | int | 条件 | 与 `app_id`+`app_user_id` 二选一 |
| `app_id` | string | 条件 | 与 `app_user_id` 同时出现时用于解析接收人 |
| `app_user_id` | string | 条件 | 接收方在本应用映射中的 ID |
| `action_url` | string \| null | 否 | 自定义跳转；若 `auto_sso` 为 true 可能被平台改写 |
| `action_text` | string \| null | 否 | 按钮文案 |
| `target_url` | string \| null | 否 | `auto_sso=true` 时作为 SSO 目标页，用于生成 jump 链接 |
| `auto_sso` | boolean | 否 | 默认 `false`；为 true 时可生成 `/api/v1/simple/sso/jump?...` 形式的 `action_url` |
| `sender_app_user_id` | string \| null | 否 | 可选，标识应用侧「发起人」映射，用于审计展示 |

**约束**：`is_broadcast` 为 `false` 或不传；须提供 `receiver_id` **或** (`app_id` + `app_user_id`)。

**请求 / 响应示例（按 `app_user_id` 指定接收人，含 SSO 跳转）**

```http
POST https://api.hnyunzhu.com/api/v1/messages/ HTTP/1.1
Content-Type: application/json
X-App-Id: app_demo_001
X-Timestamp: 1710000000
X-Sign: 1a2b3c4d5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcd

{
  "app_id": "app_demo_001",
  "app_user_id": "ext_user_1001",
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "审批提醒",
  "content": "您有一条待办审批",
  "auto_sso": true,
  "target_url": "https://oa.example.com/approve/123",
  "action_text": "去处理"
}
```

```json
{
  "id": 90001,
  "sender_id": null,
  "receiver_id": 1001,
  "app_id": 12,
  "app_name": "演示应用",
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "审批提醒",
  "content": "您有一条待办审批",
  "action_url": "/api/v1/simple/sso/jump?app_id=app_demo_001&redirect_to=https%3A%2F%2Foa.example.com%2Fapprove%2F123",
  "action_text": "去处理",
  "is_read": false,
  "created_at": "2026-04-07T10:00:00",
  "read_at": null
}
```

**补充示例（用平台用户 ID 指定接收人：`receiver_id`）**

```http
POST https://api.hnyunzhu.com/api/v1/messages/ HTTP/1.1
Content-Type: application/json
X-App-Id: app_demo_001
X-Timestamp: 1710000001
X-Sign: <按 X-App-Id 与 X-Timestamp 计算的签名>

{
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "到账提醒",
  "content": "您的订单已支付成功",
  "receiver_id": 1001
}
```

响应体结构与上一示例相同，字段值随请求变化（如 `receiver_id` 为 `1001`）。

**补充示例（`content_type: USER_NOTIFICATION`，结构化 `content` + SSO）**

```http
POST https://api.hnyunzhu.com/api/v1/messages/ HTTP/1.1
Content-Type: application/json
X-App-Id: app_demo_001
X-Timestamp: 1710000002
X-Sign: <按 X-App-Id 与 X-Timestamp 计算的签名>

{
  "app_id": "app_demo_001",
  "app_user_id": "ext_user_1001",
  "type": "NOTIFICATION",
  "content_type": "USER_NOTIFICATION",
  "title": "请假申请待审批",
  "content": {
    "applicant": "张三",
    "days": 3,
    "reason": "年假"
  },
  "auto_sso": true,
  "target_url": "https://oa.example.com/hr/leave/999",
  "action_text": "去审批"
}
```

**响应 `200`（节选）：** `content` 存为 JSON 字符串；`content_type` 为 `USER_NOTIFICATION`；`action_url` 在 `auto_sso` 为 true 时同样可生成 jump 链接。

```json
{
  "type": "NOTIFICATION",
  "content_type": "USER_NOTIFICATION",
  "title": "请假申请待审批",
  "content": "{\"applicant\":\"张三\",\"days\":3,\"reason\":\"年假\"}",
  "action_url": "/api/v1/simple/sso/jump?app_id=app_demo_001&redirect_to=..."
}
```

### 8.3 广播（全员系统通知）

仅应用可调；向平台内**全部活跃用户**各投递一条通知。

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `is_broadcast` | boolean | 是 | 必须为 `true` |
| `type` | string | 是 | 必须为 `NOTIFICATION` |
| `title` | string | 是 | 标题 |
| `content` | string \| object | 是 | 正文 |
| `content_type` | string | 否 | 默认 `TEXT`；可选值见 **8.1**（`USER_NOTIFICATION` 等） |
| `auto_sso` | boolean | 否 | 是否对跳转链接做 SSO 封装 |
| `target_url` | string \| null | 否 | 与 `auto_sso` 配合使用 |
| `action_url` | string \| null | 否 | 自定义跳转（不走 SSO 时） |
| `action_text` | string \| null | 否 | 按钮文案 |

**约束**：不要传 `receiver_id`、`app_user_id`；广播仅支持通知类型。

**请求示例**

```http
POST https://api.hnyunzhu.com/api/v1/messages/ HTTP/1.1
Content-Type: application/json
X-App-Id: app_demo_001
X-Timestamp: 1710000003
X-Sign: 5e6f708192a3b4c5d6e7f8090a1b2c3d4e5f678901234567890abcdef0123

{
  "is_broadcast": true,
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "系统维护",
  "content": "今晚 22:00-24:00 维护"
}
```

**响应 `200`：** 返回 **`MessageResponse`**，与「为全体用户各创建一条通知」中的**第一条**记录对应（便于对接方拿到一条结构化回包）；其余用户的消息结构相同，仅 `id`、`receiver_id` 等不同。若平台无活跃用户则返回 `400`，`detail` 为「没有可发送的活跃用户」。

```json
{
  "id": 90010,
  "sender_id": null,
  "receiver_id": 1001,
  "app_id": 12,
  "app_name": "演示应用",
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "系统维护",
  "content": "今晚 22:00-24:00 维护",
  "action_url": null,
  "action_text": null,
  "is_read": false,
  "created_at": "2026-04-07T10:00:00",
  "read_at": null
}
```

---

### 8.4 成功响应 `MessageResponse`（发送接口共性）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | int | 消息 ID |
| `sender_id` | int \| null | 发送方用户 ID；应用系统通知可能为 `null` |
| `receiver_id` | int | 接收方用户 ID |
| `app_id` | int \| null | 应用**数据库主键**（整数） |
| `app_name` | string \| null | 应用名称 |
| `type` | string | 本文档场景下为 `NOTIFICATION`（平台尚存在其他类型，见 OpenAPI） |
| `content_type` | string | 内容类型：`TEXT`、`IMAGE`、`VIDEO`、`FILE`、`USER_NOTIFICATION` |
| `title` | string | 标题 |
| `content` | string | 正文 |
| `action_url` | string \| null | 跳转链接（系统通知可能存在） |
| `action_text` | string \| null | 按钮文案 |
| `is_read` | bool | 是否已读 |
| `created_at` | datetime | 创建时间 ISO8601 |
| `read_at` | datetime \| null | 已读时间 |

**返回示例（`200 OK`，单条系统通知，与上文发送示例对应）：**

```json
{
  "id": 90001,
  "sender_id": null,
  "receiver_id": 1001,
  "app_id": 12,
  "app_name": "演示应用",
  "type": "NOTIFICATION",
  "content_type": "TEXT",
  "title": "审批提醒",
  "content": "您有一条待办审批",
  "action_url": "/api/v1/simple/sso/jump?app_id=app_demo_001&redirect_to=https%3A%2F%2Foa.example.com%2Fapprove%2F123",
  "action_text": "去处理",
  "is_read": false,
  "created_at": "2026-04-07T10:00:00",
  "read_at": null
}
```

（广播成功时结构相同，通常 `receiver_id` 为本次作为「代表返回」的那条消息对应的用户 ID；`action_url`、`app_id` 等以实际响应为准。）

---

## 9. 调试与规范来源

- **交互式 API 文档**：`https://api.hnyunzhu.com/api/v1/docs`（Swagger）。
- 若本文与线上部署不一致，以**实际 OpenAPI 与接口返回**为准。

---

## 10. 安全要点（摘要）

1. `APP_SECRET` 仅留在服务端；任何含 Secret 的签名不得在浏览器完成。  
2. 区分 `UAP_API_BASE` 与 `UAP_WEB_BASE`。  
3. `APP_ACCESS_TOKEN` 与 JWT 同样属于敏感凭据。  
4. SSO 与 Ticket 流程务必使用 HTTPS 与合法回调域。

---

*文档版本：与当前仓库后端 Schema/路由一致时，API 前缀为 `/api/v1`。*