# ONEID 会员对外接口文档

## 文档说明

本文档单独列出 **与 AIVA 官方 ONEID 会员相关、需要外部系统对接的接口**，主要对象是 **AIVA 小程序服务端**。门店点位客户端（互动网页、播控）请看《互动应用开发接入文档》，不调用本文接口，也不得持有本文凭证。

业务流程见文档中心《用户身份流程》与《身份绑定通信泳道》：http://aiva.docs.vavedigital.com/identity/index.html#identity

| 项目 | 内容 |
| --- | --- |
| 接口地址 | 与业务接口同一域名（测试环境：`https://aiva.dev.vavedigital.com`），路径前缀 `/openapi/v1/identity/` |
| 文档站 | `http://aiva.docs.vavedigital.com` 只是文档站，不是接口地址 |
| 请求格式 | UTF-8 JSON，`Content-Type: application/json`；成功返回 HTTP 200 与业务 JSON，没有统一外层包裹 |
| 错误格式 | 非 2xx 返回 `{"error":"中文说明"}`，按 HTTP 状态判断，不要匹配整句中文 |
| 字段名 | `AgentOSID`（AgentOS 用户编号）、`ONEID`（AIVA 会员编号）。ONEID 不是微信 openid/unionid |
| 时间 | 北京时间 UTC+8 |

## 接口一览

| 编号 | 方向 | 接口 | 用途 |
| --- | --- | --- | --- |
| B02 | AIVA → AgentOS | `POST /openapi/v1/identity/card-binding-context` | 用卡背面太阳码里的 bindScene 查出本卡 AgentOSID |
| B03 | AIVA → AgentOS | `POST /openapi/v1/identity/bindings` | 把本卡 AgentOSID 绑定到会员 ONEID |
| B04 | AIVA → AgentOS | `GET /openapi/v1/identity/binding-requests/:requestId` | 绑定结果没收到时，按原请求号查结果 |
| B05 | AIVA → AgentOS | `GET /openapi/v1/identity/oneids/:oneId/bindings` | 查询一个 ONEID 名下绑定的全部卡 |
| B06 | AIVA → AgentOS | `GET /openapi/v1/identity/oneids/:oneId/data/:resource` | 按 ONEID 汇总读取用户数据 |
| 作品删除 | AIVA → AgentOS | `DELETE /openapi/v1/identity/oneids/:oneId/works/:assetId` | 会员在小程序删除作品后同步删除 AgentOS 中的作品 |
| 批量删除作品 | ONEID 后台 → AgentOS | `POST /openapi/v1/identity/works/batch-delete` | ONEID 后台按 ONEID 或 AgentOSID 删除一个或多个作品（单次最多100个） |
| 作品码查询 | AIVA → AgentOS | `GET /openapi/v1/identity/oneids/:oneId/work-codes/:scene` | 会员扫AI车衣共创作品小程序码后，凭参数查作品 |
| M01 | AgentOS → AIVA | `POST /uc/v1/identity/suncodes`（AIVA 提供） | 导出来宾卡打印图时取背面太阳码；AI车衣共创结果页取作品小程序码 |
| 二维码扫码识别 | AgentOS → AIVA | `POST /uc/v1/user/identityCode/scan/oneid`（AIVA 提供；2026-10-15 起取代 `/scan`） | 点位或作品打印台扫 AIVA 小程序会员码时，换出会员 ONEID |
| 绑定结果推送 | AgentOS → AIVA | `POST /uc/v1/identity/bindings`（AIVA 提供） | 会员首次在点位扫会员码、AgentOS 新建账户后，告诉 AIVA 已绑定 |
| 作品数据推送 | AgentOS → AIVA | `POST /uc/v1/identity/experience-records`（AIVA 提供） | 作品审核通过后，把作品（公开地址、名称等）同步到 AIVA |

## 鉴权与凭证

| 凭证 | 适用接口 | 请求头 | 如何获得 |
| --- | --- | --- | --- |
| AIVA 身份服务凭证 | B02—B05、会员作品删除、批量删除作品、作品码查询 | `Authorization: Bearer <凭证>` | AgentOS 后台“来宾卡管理 → 身份接入与绑定 → 服务设置 → AIVA 服务授权 → 新增授权”创建（需凭证管理权限：超级管理员或平台运维）。凭证由系统自动生成（256比特随机数，64位十六进制字符），加密保存；授权列表默认脱敏显示，由 AgentOS 运营点击“复制”取用后安全交给 AIVA（每次复制记入审计）；到期时间可选“永不过期”或指定时间；可随时撤销，撤销后不再提供复制 |
| 只读用户数据应用凭证 | B06 | `Authorization: Bearer <凭证>` | 与身份服务凭证分开创建、分开授权 |
| AIVA 网关 accessKey / secretKey | M01、二维码扫码识别、绑定结果推送、作品数据推送（AgentOS 调 AIVA） | AgentOS 发出 `timestamp`、`sign`、`accessKey`、`sysCode`（按 AIVA《参数验签方案》签名）；扫码识别另带 `sourceApp` | 由 AIVA 负责人邮件提供，在 AgentOS 后台“用户与来宾卡 → 身份服务设置 → AIVA 网关”统一登记（原页签名“太阳码接口（M01）”），secretKey 加密保存、不回显；扫码识别另需登记 `sourceApp`、`scanSourceApp`（由 AIVA 提供） |

- 身份服务凭证不能读用户数据，只读数据凭证不能写身份，点位设备凭证也不能调用本文接口；用错凭证一律返回 401。
- 租户由凭证决定，门店由卡决定；请求里不能指定租户或门店。
- 凭证只在服务端保存，不要放进小程序前端、日志或二维码。

## 调用流程

**扫卡绑定**

1. 会员用微信扫门店卡背面太阳码，进入 AIVA 小程序，小程序拿到 `bindScene`。
2. 会员在小程序注册或登录，AIVA 得到 ONEID。
3. AIVA 服务端调用 **B02**，用 `bindScene` 换取本卡 `AgentOSID`。
4. AIVA 服务端生成一个请求号，调用 **B03** 绑定。
5. 如果 B03 超时或回复没收到：**不要换请求号**，先调用 **B04** 查原请求结果；查不到就用**同一个请求号**再发一次 B03。
6. 需要展示会员名下的卡或数据时，调用 **B05**、**B06**。

**会员到店点位登录**（2026-10-13 起）

扫码器兼容设置（2026-10-14）：AgentOS“用户与来宾卡 → 身份服务设置 → 扫码器设置”可配置来宾卡大小写兼容、连续同码合并与无回车静默识别；互动客户端读取`GET /api/identity/scan-settings`。仅对来宾卡按当前格式规范化，不转换会员token大小写，不改变32位会员码协议或一次性使用规则。

1. 会员在 AIVA 小程序打开“会员码”，小程序显示 AIVA 会员码（AgentOS 不参与生成）。会员码内容为 **32 位小写十六进制**的临时 token（2026-10-13 AIVA 确认），AgentOS 据此与来宾卡码区分。
2. 点位扫码后，由点位客户端调用 `POST /api/identity/point-login`（见《互动应用开发接入文档》），把二维码内容原样传给 AgentOS。AgentOS 按码的格式识别（2026-10-13）：`…/c/14位短码` 链接或 14 位短码 = 来宾卡；32 位小写十六进制 = AIVA 会员码；两种都不是的直接返回 400 `CODE_INVALID`、不调用 AIVA。
3. AgentOS 调用 AIVA 的 **[二维码扫码识别](#identity-aiva-scan)**，用二维码内容换出 ONEID（会员码只能用一次）。
4. 该 ONEID 已有账户的，登录到会员主账户；首次来访的，AgentOS 自动建账户并关联 ONEID，再调用 **[绑定结果推送](#identity-aiva-binding-push)** 告诉 AIVA。

原“AIVA 服务端申请一次性会员凭据 memberTicket、放进会员码”的方式已于 2026-10-13 删除。

**作品同步到 AIVA**

1. 会员在点位生成作品，作品审核通过后，AgentOS 调用 **[作品数据推送](#identity-aiva-works-push)**，每个作品推一次（账户须已关联 ONEID；只用来宾卡的用户在绑卡后补推）。
2. 会员在小程序删除作品时，AIVA 调用 **会员作品删除**；ONEID 后台运营删除时调用 **批量删除作品**。

## B02 解析绑定参数

会员扫卡背面太阳码进入小程序后，AIVA 服务端先用扫码参数查出这张卡对应的 AgentOSID，再去绑定。

### 解析绑定参数
#### 功能描述

用卡背面太阳码携带的 `bindScene` 查出本卡的 AgentOSID、印刷卡号与卡状态。只查询，不写任何数据。卡已作废或参数不存在时返回 404。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `bindScene` | string | 必填 | 太阳码中的绑定参数，32 个字符 | `Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx` |

#### 请求示例

```bash
curl -X POST "$BASE/openapi/v1/identity/card-binding-context" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"bindScene":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx"}'
```

#### 返回示例（HTTP 200）

```json
{ "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f", "cardNo": "CQ0001023", "status": "activated" }
```

| 返回字段 | 说明 |
| --- | --- |
| `AgentOSID` | 本卡的 AgentOS 用户编号，绑定时原样传给 B03 |
| `cardNo` | 卡面印刷卡号，可展示给会员核对 |
| `status` | 卡状态：`created` 已生码未印制、`printed` 已印制入库、`activated` 已在点位使用、`linked` 已绑定会员（已作废的卡返回 404） |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `bindScene` 缺失、超过 32 字符或含控制字符 | 检查扫码参数是否完整传递 |
| 401 | 凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 404 | 参数不存在，或这张卡已作废 | 提示会员“卡片无效”，不要继续绑定 |

## B03 绑定 AgentOSID 与 ONEID

会员在小程序完成注册或登录后，AIVA 服务端把这张卡绑定到会员的 ONEID。一个会员可以绑定多张卡。

### 绑定 AgentOSID 与 ONEID
#### 功能描述

把本卡 AgentOSID 绑定到已认证会员的 ONEID。每次绑定都是追加：同一个 ONEID 可以绑定多张卡，原来的卡和历史记录保留。绑定成功后，会员的 Token 在同一次操作中归集到该 ONEID 下最早创建的账户（主账户），并留下转出、转入两条流水；注册赠送每个账户只发一次。

同一个请求号原样再发一次，不会重复绑定，直接返回第一次的结果（响应带 `idempotentHit: true`）；同一个请求号改了内容再发，返回 409。调用超时时不要换请求号，先用 B04 查结果。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `AgentOSID` | string ≤64 | 必填 | B02 返回的本卡 AgentOSID | `au_3f9c0d1e2a4b5c6d7e8f` |
| `ONEID` | string ≤64 | 必填 | 已认证会员的 ONEID（区分大小写） | `oneid_example` |
| `bindScene` | string ≤32 | 必填 | 本次扫码的绑定参数，证明这次绑定确实来自扫这张卡；必须与 AgentOSID 属于同一张卡 | `Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx` |
| `requestId` | string ≤64 | 必填 | AIVA 生成的请求号，每次新的绑定用一个新请求号 | `aiva-20261008-0001` |

#### 请求示例

```bash
curl -X POST "$BASE/openapi/v1/identity/bindings" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"AgentOSID":"au_3f9c0d1e2a4b5c6d7e8f","ONEID":"oneid_example","bindScene":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx","requestId":"aiva-20261008-0001"}'
```

#### 返回示例（HTTP 200）

```json
{
  "status": "success",
  "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
  "ONEID": "oneid_example",
  "primaryAgentOSID": "au_1a2b3c4d5e6f7a8b9c0d",
  "linkId": "link_7c2e…"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | `success` 绑定成功；`conflict_uid_bound` 这张卡已绑定别的 ONEID，原绑定不变；`card_disabled` 卡或账户已停用 |
| `primaryAgentOSID` | 该会员的主账户（仅 success 返回） |
| `linkId` | 绑定记录编号；冲突、停用也会返回，用于对账 |
| `idempotentHit` | 仅在同一请求号重发时出现，值为 `true`，表示返回的是第一次的结果 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 缺少字段、超长或含控制字符 | 修正参数 |
| 401 | 凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 404 | `bindScene` 与 `AgentOSID` 不属于同一张卡 | 让会员重新扫卡，不要拼凑参数 |
| 409 | 同一请求号对应了不同内容；该会员关联账户里有未结算的冻结 Token；关联账户中有已停用账户；身份服务未设置注册赠送与有效期 | 请求号冲突时核对是否误用；其余联系 AgentOS 运营处理后再用同一请求号重发 |
| 超时 / 网络中断 | 结果未知 | 先调用 B04 查同一请求号；查不到再用同一请求号重发 B03 |

## B04 查询原绑定请求结果

B03 超时或回复丢失时，用原请求号查询当时的绑定结果，避免重复绑定。

### 查询原绑定请求结果
#### 功能描述

返回该请求号保存的 B03 结果，内容与 B03 返回相同。只能查到本凭证自己提交过的请求。请求没有完成、或因参数错误整体失败时不保存结果，返回 404，此时可以用同一个请求号重新提交 B03。

#### 请求参数（Path）

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `requestId` | string ≤64 | 必填 | B03 使用的原请求号，需 URL 编码 |

#### 请求示例

```bash
curl "$BASE/openapi/v1/identity/binding-requests/aiva-20261008-0001" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{ "status": "success", "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f", "ONEID": "oneid_example", "primaryAgentOSID": "au_1a2b3c4d5e6f7a8b9c0d", "linkId": "link_7c2e…" }
```

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 404 | 没有该请求号的已保存结果（未完成、整体失败或从未提交） | 用同一个请求号重新提交 B03 |

## B05 查询 ONEID 绑定的全部卡

查询一个会员名下已绑定的全部卡与账户，用于小程序展示“我的门店卡”。

### 查询 ONEID 绑定的全部卡
#### 功能描述

分页列出该 ONEID 在本租户关联的全部 AgentOSID，包括卡号、卡状态、来源门店、绑定时间和主账户。按记录编号从小到大排序。

#### 请求参数（Path / Query）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `oneId` | Path | string ≤64 | 必填 | 会员 ONEID，需 URL 编码 |
| `limit` | Query | integer | 可选 | 每页条数 1—500，默认 100 |
| `after` | Query | 数字字符串 | 可选 | 翻页位置，第一页不传或传 `0`，之后传上一页的 `nextAfter` |

#### 请求示例

```bash
curl "$BASE/openapi/v1/identity/oneids/oneid_example/bindings?limit=100" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{
  "items": [
    { "id": "841", "AgentOSID": "au_1a2b…", "origin": "card_preset", "origin_store_id": "CQ-GUANGHUAN", "created_at": "2026-10-01T02:00:00.000Z", "linked_at": "2026-10-06T08:00:00.000Z", "card_no": "CQ0000512", "card_status": "linked", "primaryAgentOSID": "au_1a2b…" }
  ],
  "hasMore": false,
  "nextAfter": null
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items[].AgentOSID` / `card_no` / `card_status` | 关联账户、卡号与卡状态；会员首次在点位扫会员码自动建的账户没有卡号 |
| `items[].origin` / `origin_store_id` | 账户来源（`card_preset` 来宾卡建档、`oneid_auto` 会员首次点位登录自动建档）与来源门店 |
| `items[].primaryAgentOSID` | 该会员主账户 |
| `hasMore` / `nextAfter` | 是否有下一页、下一页位置 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `oneId` 为空或超长；`limit`、`after` 格式不对 | 修正参数 |
| 401 | 凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |

## B06 按 ONEID 汇总数据

按会员汇总读取他在各门店、各张卡上的数据。使用与身份服务不同的“只读用户数据应用凭证”。

### 按 ONEID 汇总数据
#### 功能描述

按数据类别分页汇总该 ONEID 下全部关联账户的数据，每条记录保留它原来属于哪个账户（`agentos_uid`）和哪个门店（`store_id`）。只读，不改任何数据；可读的类别由后台给该应用授权的范围决定。

#### 请求参数（Path / Query）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `oneId` | Path | string ≤64 | 必填 | 会员 ONEID |
| `resource` | Path | string | 必填 | 数据类别：`tags`、`profileContributions`、`interactionAnswers`、`interactionDesigns`、`assets` 等，须在应用授权范围内 |
| `limit` | Query | integer | 可选 | 每页 1—500，默认 100 |
| `cursor` | Query | string | 可选 | 原样传上一页的 `nextCursor` |

#### 请求示例

```bash
curl "$BASE/openapi/v1/identity/oneids/oneid_example/data/tags?limit=50" \
  -H "Authorization: Bearer $USER_DATA_APP_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{
  "schemaVersion": 1,
  "items": [ { "id": "1024", "agentos_uid": "au_3f9c…", "tag_key": "style_tech", "store_id": "CQ-GUANGHUAN", "point_id": "P02", "created_at": "2026-10-06T08:00:00.000Z" } ],
  "hasMore": false,
  "nextCursor": null,
  "consistency": "live-keyset-bounded",
  "asOf": "2026-10-08T02:00:00.000Z",
  "complete": true
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items` | 本页记录；各类别字段见《互动应用开发接入文档》“用户资料字段” |
| `items[].work_name` | 仅 `assets`：作品名称 `{点位名称}_{生成完成时间 yyyyMMddHHmmss 北京时间}`，提交 AIVA 小程序/APP 时使用；点位未填名称或 2026-10-09 前的作品为 `null` |
| `items[].file_size` / `width` / `height` / `duration_ms` | 仅 `assets`：作品基础数据，保存时读作品文件实测——文件大小（字节）；图片宽高（像素，音频为 `null`）；音频时长（毫秒，图片为 `null`）。本功能上线前保存的作品宽高/时长为 `null` |
| `items[].lyrics` / `lyrics_lrc` | 仅 `assets`：AI音乐歌曲的歌词。`lyrics` 为纯文字歌词（含段落标记）；`lyrics_lrc` 为标准逐句 LRC，没有逐句时间时为 `null`；其他作品两项均为 `null`（2026-10-13） |
| `hasMore` / `nextCursor` / `complete` | 分页状态；`complete` 为 true 表示该类别已读完 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `oneId` 格式错误；`limit` 不在 1—500；`cursor` 无效 | 修正参数；去掉 cursor 从第一页重读 |
| 401 | 凭证缺失、无效、过期或已撤销（身份服务凭证在此无效） | 使用只读用户数据应用凭证 |
| 403 | 该应用未被授权读取这个类别 | 联系 AgentOS 运营调整授权范围 |
| 404 | 数据类别不存在 | 修正类别名 |

## 会员作品删除

会员在 AIVA 小程序删除自己的作品后，AIVA 服务端调用本接口，让 AgentOS 同步删除。删除后作品文件立即从存储中删除，作品在小程序、点位、后台作品列表和展示上墙中都不再可见；AgentOS 只保留一条不含作品内容的“已删除”记录，用于 Token 计费对账和审计。

### 删除会员作品
#### 功能描述

删除一个属于该会员的作品（2026-10-09 用户确认）：

- **删除范围**：作品文件本身（图片、音乐音频）立即从存储删除；AI音乐的作品会连同它的封面一起删除。互动作答、画像标签、AI车衣共创的设计数据不删除。
- **归属核对**：作品必须属于该 ONEID 关联的任一账户（任一张已绑定的卡，或会员首次到店自动建的账户）。不属于该会员或不存在的作品，一律返回 404，不透露作品是否存在。
- **审核中、展示中的作品**：照样删除，并同时撤下上墙展示。
- **保留的记录**：作品编号、归属账户、生成任务、删除时间、删除来源（哪个 AIVA 应用）和删除原因；不保留文件，也没有外链。
- **重复删除**：已经删除的作品再次删除，返回 `already_deleted`，不报错。
- **删除失败**：存储里的文件没删掉时整次报错，记录不改，可以用相同参数直接重试。

作品编号 `assetId` 来自 [B06 按 ONEID 汇总数据](#identity-b06)（数据类别 `assets`）返回的 `asset_id`。作品名称见同一数据中的 `work_name`（`{点位名称}_{生成完成时间 yyyyMMddHHmmss 北京时间}`）。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `oneId` | Path | string ≤64 | 必填 | 会员 ONEID，需 URL 编码 | `oneid_example` |
| `assetId` | Path | string ≤64 | 必填 | AgentOS 作品编号 | `ast_8d1f…` |
| `reason` | Body | string ≤200 | 可选 | 删除原因，记录用，不能含换行等控制字符 | `用户在小程序删除` |

#### 请求示例

```bash
curl -X DELETE "$BASE/openapi/v1/identity/oneids/oneid_example/works/ast_8d1f0c2b" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"reason":"用户在小程序删除"}'
```

#### 返回示例（HTTP 200）

```json
{
  "status": "deleted",
  "assetId": "ast_8d1f0c2b",
  "deletedAssetIds": ["ast_8d1f0c2b", "ast_cover_51a9"],
  "deletedAt": "2026-10-09T02:00:00.000Z"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | `deleted` 本次已删除；`already_deleted` 之前已删除，本次没有任何改动 |
| `deletedAssetIds` | 本次一起删除的作品编号（AI音乐会包含封面）；`already_deleted` 时为空数组 |
| `deletedAt` | 删除时间 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `oneId` 或 `assetId` 为空、超长或含控制字符；`reason` 超过200字或含换行 | 修正参数 |
| 401 | 身份服务凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 404 | 作品不存在，或不属于该 ONEID 关联的任何账户 | 核对作品编号与会员；不要换别人的 ONEID 重试 |
| 409 | 作品文件的存储位置与 AgentOS 当前存储配置不一致，未删除 | 联系 AgentOS 运营处理后重试 |
| 503 | 存储中的文件删除失败，作品记录未改动 | 稍后用相同参数重试 |

## ONEID 后台批量删除作品

供 AIVA ONEID 后台系统调用：运营在 ONEID 后台删除某个会员（或某张卡账户）的一个或多个作品时，同步删除 AgentOS 中的作品。删除效果与[会员作品删除](#identity-work-delete)相同：作品文件立即从存储删除，只保留不含内容的“已删除”记录。

### 批量删除作品
#### 功能描述

按 ONEID 或 AgentOSID 删除一个或多个作品（2026-10-12 用户确认）：

- **凭证**：沿用 AIVA 身份服务凭证（与 B02—B05、会员作品删除相同），不需要另配。
- **作品归属**：`ONEID` 与 `AgentOSID` 必须且只能传一个。传 `ONEID` 时，作品须属于该 ONEID 关联的任一账户；传 `AgentOSID` 时，**只认这一个账户的作品**——即使这张卡已绑定 ONEID，同一 ONEID 下其他账户的作品也不能用这个 AgentOSID 删除（要删请传 ONEID）。
- **数量**：`assetIds` 1—100 个，超过直接返回 400；重复的编号只处理一次。
- **逐个处理、逐个返回**：每个作品独立删除，一个删不了不影响其他作品。每个作品的结果为：`deleted` 本次已删除；`already_deleted` 之前已删除；`not_found` 不存在或不属于指定的 ONEID/AgentOSID（不透露作品是否存在）；`failed` 存储文件删除失败或存储位置与当前配置不一致，该作品记录未改动，可原样重试。
- **删除范围**：与会员作品删除相同——AI音乐连同封面一起删除；互动作答、画像标签、AI车衣共创设计数据不删；审核中、展示中的作品照样删除并撤下展示。
- **删除来源**：记录为 ONEID 后台（`aiva_admin:<应用编号>`），与小程序删除区分，用于审计与对账。
- **整体出错**：参数错误整次返回 400、不删任何作品。处理中途遇到服务端异常（5xx）时，已处理的作品保持已删除；用相同参数重试即可，已删除的作品会返回 `already_deleted`。

作品编号来自 [B06 按 ONEID 汇总数据](#identity-b06)（数据类别 `assets`）返回的 `asset_id`。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `ONEID` | string ≤64 | 与 AgentOSID 二选一 | 会员 ONEID（区分大小写） | `oneid_example` |
| `AgentOSID` | string ≤64 | 与 ONEID 二选一 | AgentOS 用户编号；只删这个账户自己的作品 | `au_3f9c0d1e2a4b5c6d7e8f` |
| `assetIds` | string[] | 必填 | 要删除的作品编号，1—100 个，每个 ≤64 字符 | `["ast_8d1f0c2b","ast_51a9e7d0"]` |
| `reason` | string ≤200 | 可选 | 删除原因，记录用，不能含换行等控制字符 | `ONEID后台运营删除` |

#### 请求示例

```bash
curl -X POST "$BASE/openapi/v1/identity/works/batch-delete"   -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"   -H "Content-Type: application/json"   --data '{"ONEID":"oneid_example","assetIds":["ast_8d1f0c2b","ast_51a9e7d0","ast_0000dead"],"reason":"ONEID后台运营删除"}'
```

#### 返回示例（HTTP 200）

```json
{
  "owner": { "type": "ONEID", "id": "oneid_example" },
  "summary": { "deleted": 1, "already_deleted": 1, "not_found": 1, "failed": 0 },
  "results": [
    { "status": "deleted", "assetId": "ast_8d1f0c2b", "deletedAssetIds": ["ast_8d1f0c2b", "ast_cover_51a9"], "deletedAt": "2026-10-12T02:00:00.000Z" },
    { "status": "already_deleted", "assetId": "ast_51a9e7d0", "deletedAssetIds": [], "deletedAt": "2026-10-09T02:00:00.000Z" },
    { "status": "not_found", "assetId": "ast_0000dead", "deletedAssetIds": [], "error": "作品不存在或不属于该会员" }
  ]
}
```

| 返回字段 | 说明 |
| --- | --- |
| `owner` | 本次按哪个身份核对归属：`type` 为 `ONEID` 或 `AgentOSID` |
| `summary` | 各结果的个数 |
| `results[]` | 每个作品的结果，顺序与请求一致（重复编号只出现一次） |
| `results[].status` | `deleted` / `already_deleted` / `not_found` / `failed` |
| `results[].deletedAssetIds` | 本次一起删除的作品编号（AI音乐会包含封面）；非 `deleted` 时为空数组 |
| `results[].deletedAt` | 删除时间（`deleted`、`already_deleted` 时返回） |
| `results[].error` | `not_found`、`failed` 时的中文原因 |

只要参数正确，HTTP 都是 200，请逐个看 `results[].status`；`failed` 的作品稍后用相同参数重试。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | ONEID 与 AgentOSID 都没传或都传了；`assetIds` 不是数组、为空或超过100个；某个编号为空、超长或含控制字符；`reason` 超过200字或含换行 | 修正参数；整次未删除任何作品 |
| 401 | 身份服务凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 5xx | 服务端异常，处理可能中途停止 | 用相同参数重试；已删除的作品返回 `already_deleted` |

## 作品小程序码查询

AI车衣共创互动最终结果页显示作品小程序码（2026-10-09 用户确认：扫码在小程序查看/下载本次作品；2026-10-11 改为按作品生成，与打印无关，不再有作品号码）。**AIVA 后端接口尚未就绪，本节为 AgentOS 拟定方案，收到 AIVA 接口文档后按其契约调整。**小程序码由 AgentOS 调用 [M01](#identity-m01)（请求带 `type:"work"`）生成，`scene` 为 AgentOS 分配的作品码参数；会员扫码进入小程序后，AIVA 服务端凭 `scene` 与当前会员 ONEID 调用本接口取作品编号，再按 [B06](#identity-b06) 或既有作品读取方式展示。

### 按小程序码参数查询作品
#### 功能描述

用小程序码参数查询对应作品。作品必须属于该 ONEID 关联的任一账户；不属于该会员、参数不存在或作品已删除，一律返回 404，不透露作品是否存在。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `oneId` | Path | string ≤64 | 必填 | 扫码会员的 ONEID，需 URL 编码 | `oneid_example` |
| `scene` | Path | string | 必填 | 小程序码参数，`w` 加 30 位十六进制，共32字符 | `w3f9a0c1d2e3f405162738495a6b7c8d` |

#### 请求示例

```bash
curl "$BASE/openapi/v1/identity/oneids/oneid_example/work-codes/w3f9a0c1d2e3f405162738495a6b7c8d" \
  -H "Authorization: Bearer $AIVA_IDENTITY_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{ "assetId": "asset_1c9e…", "workNo": null, "workName": "车衣共创_20261009103015", "storeId": "CQ-GUANGHUAN", "mimeType": "image/png", "createdAt": "2026-10-09T02:30:10.000Z" }
```

| 返回字段 | 说明 |
| --- | --- |
| `assetId` | AgentOS 作品编号 |
| `workNo` | 2026-10-11 起为 `null`（不再分配作品号码）；只有改版前打印单上的旧码才有值 |
| `workName` | 作品名称；点位未填名称时为 null |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `oneId` 为空、超长或含控制字符 | 修正参数 |
| 401 | 身份服务凭证缺失、无效、过期或已撤销 | 联系 AgentOS 运营核对授权 |
| 404 | 参数不存在、作品不属于该会员或已删除 | 提示“作品不存在或不属于当前账号” |

## M01 小程序太阳码生成（AgentOS 调用 AIVA）

方向与其他接口相反：由 **AIVA 提供**、**AgentOS 调用**。AgentOS 后台导出来宾卡打印图时逐张卡取背面太阳码，AI车衣共创结果页取作品小程序码。2026-10-12 起按 AIVA 提供的《aiva-services-api》M01 与《参数验签方案》对接（原文在仓库 `docs/api/AIVA/`）。

**AIVA 网关统一登记（2026-10-13 起）**：AgentOS 调用 AIVA 的四个接口——M01、[二维码扫码识别](#identity-aiva-scan)、[绑定结果推送](#identity-aiva-binding-push)、[作品数据推送](#identity-aiva-works-push)——走同一个 AIVA 网关、同一套签名，在后台“用户与来宾卡 → 身份服务设置 → AIVA 网关”一处登记（原页签名“太阳码接口（M01）”）：M01 完整接口地址（网关地址由它去掉末尾 `/uc/v1/identity/suncodes` 得到，其余接口按 AIVA 文档路径拼在网关地址后）、accessKey / secretKey、sysCode、单次超时、来宾卡与作品码页面路径，以及扫码识别用的 `sourceApp`、`scanSourceApp`。

### 生成小程序太阳码
#### 功能描述

AIVA 按 `path`（小程序页面路径）与 `param`（scene）生成小程序码，上传 TOS 后返回图片地址；AgentOS 再下载该图片。来宾卡：`param` 为该卡的 bindScene（32 字符），扫码进入 AIVA 小程序激活页，用于后续 B02、B03 绑定。AI车衣共创作品码：`param` 为作品码 scene（`w` + 30 位十六进制），页面路径另行登记（AIVA 尚未提供，未登记时作品码直接报错）。

**请求头（网关验签）**

| 请求头 | 必填 | 说明 |
| --- | --- | --- |
| `timestamp` | 必填 | 毫秒时间戳，防重发 |
| `sign` | 必填 | 签名，见下 |
| `accessKey` | 必填 | AIVA 分配的公钥（系统标识），由 AIVA 负责人邮件提供 |
| `sysCode` | 必填 | 系统标识，AIVA 文档默认值 `SD` |
| `msgId` | 否 | 消息编号，AgentOS 每次随机生成，供链路跟踪 |
| `Content-Type` | 必填 | `application/json` |

签名：`sign = SHA-256(请求路径 + "&" + 请求体原文 + "&timestamp=" + timestamp + "&" + secretKey)`，UTF-8，十六进制小写。请求路径取登记接口地址的路径部分；本接口没有 URL 查询参数，参与排序的只有 `timestamp`。已用《参数验签方案》流程图中的样例核对算法一致。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `path` | string | 必填 | 太阳码跳转的小程序页面路径（来宾卡为激活页落地页），在 AgentOS 后台登记 | `pages/card/activate` |
| `param` | string | 必填 | scene，最多 32 字符：来宾卡为 bindScene，作品码为作品码 scene | `Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx` |

#### 请求示例

```bash
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/suncodes" \
  -H "Content-Type: application/json" \
  -H "timestamp: 1791799000000" \
  -H "accessKey: $AIVA_ACCESS_KEY" \
  -H "sysCode: SD" \
  -H "sign: <按上述规则计算>" \
  --data '{"path":"pages/card/activate","param":"Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx"}'
```

#### 返回示例（HTTP 200）

```json
{ "status": true, "errorCode": "", "errorMsg": "", "data": "https://<TOS 域名>/…/suncode.png", "time": 1791799000123, "traceId": "…" }
```

`data` 为太阳码图片地址，AgentOS 随后 GET 下载，须为 PNG 或 JPEG（≤10MB）。

#### 错误情况

| 情况 | AgentOS 的处理 |
| --- | --- |
| 未登记 AIVA 网关，或仍是旧版 Bearer 登记，或缺对应页面路径 | 直接报错并提示去后台“身份服务设置 → AIVA 网关”登记，不调用 |
| 网关返回 `status:false`（如 `CGW_001 签名校验失败`） | 整次导出停止，提示卡号与 `errorCode`、`errorMsg` |
| HTTP 非 2xx、返回不是 JSON、`data` 不是图片地址 | 整次导出停止，提示卡号与对方原文（前 200 字） |
| 图片下载失败或不是 PNG/JPEG | 整次导出停止，提示卡号 |
| 超过登记的单次超时（调用与下载各计一次）或网络中断 | 整次导出停止，提示超时 |

以上情况都不生成占位码、不自动重试；运营处理后重新导出即可。仅导出正面（不调用 M01）不受影响。

## 二维码扫码识别（AgentOS 调用 AIVA）

方向与 B02—B06 相反：由 **AIVA 提供**、**AgentOS 调用**。会员在门店互动点位或作品打印台出示 AIVA 小程序会员码时，AgentOS 用二维码内容向 AIVA 换出会员 ONEID。2026-10-13 起提供，取代原 AgentOS 自己签发的一次性会员凭据（memberTicket，已删除）。**2026-10-15 起 AIVA 把接口由 `/uc/v1/user/identityCode/scan` 换为 `/uc/v1/user/identityCode/scan/oneid`**：请求不变，返回只有 ONEID（不再有昵称、手机号、头像）；旧地址 AgentOS 不再调用。接口原文见仓库 `docs/api/AIVA/aiva-services-api.txt`（原文仍是 `/scan` 及其完整返回字段，以本节为准）；与 [M01](#identity-m01)、[绑定结果推送](#identity-aiva-binding-push)、[作品数据推送](#identity-aiva-works-push) 共用同一个 AIVA 网关登记与签名方式。

### 二维码扫码识别
#### 功能描述

**什么时候调用**

- 互动点位调用扫码登录 `POST /api/identity/point-login`（见《互动应用开发接入文档》“扫码登录”），扫到的码是 AIVA 会员码格式（32 位小写十六进制）时调用本接口，`token` 为扫到的内容。来宾卡正面码（14 位短码或 `…/c/短码` 链接）不调用；两种格式都不是的，AgentOS 直接拒绝，**不会**调用本接口。
- 作品打印台 Pad 登录时规则相同。打印台只读登录，不建账户。

**AgentOS 拿到结果后怎么做**

- 把二维码内容原样作为 `token` 发给 AIVA，AIVA 返回 ONEID。
- 该 ONEID 在 AgentOS 已有账户：登录到该会员的主账户。
- 没有账户（会员首次到店）：自动建账户并关联这个 ONEID，再调用 [绑定结果推送](#identity-aiva-binding-push) 告诉 AIVA。
- 本接口不返回昵称、脱敏手机号、头像（2026-10-15 起）。扫码不再更新这三项：此前已保存的资料保留，仍随点位登录结果返回昵称和头像；之后首次到店的会员没有昵称和头像（返回 `null`）。

**AIVA 的码只能用一次**：AgentOS 不重试。如果 AIVA 已经认出人，但 AgentOS 这边建账户失败，登录直接报错，需要会员在小程序里刷新会员码再扫一次。

**请求头**：网关验签请求头与 [M01](#identity-m01) 相同（`timestamp`、`sign`、`accessKey`、`sysCode`、`msgId`，签名规则见 M01），另加 `sourceApp`。

#### 请求参数（Header / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `sourceApp` | Header | string | 必填 | 调用方应用标识，取后台登记值（由 AIVA 提供） | `<AIVA 提供>` |
| `token` | Body | string | 必填 | 会员码二维码内容，原样传入（最长 2048 字符） | `<二维码内容>` |
| `scanSourceApp` | Body | string | 必填 | 扫码来源应用标识，取后台登记值（由 AIVA 提供） | `<AIVA 提供>` |

#### 请求示例

```bash
curl -X POST "$AIVA_GATEWAY/uc/v1/user/identityCode/scan/oneid" \
  -H "Content-Type: application/json" \
  -H "timestamp: 1791850000000" \
  -H "accessKey: $AIVA_ACCESS_KEY" \
  -H "sysCode: SD" \
  -H "sign: <按 M01 的签名规则计算>" \
  -H "sourceApp: $AIVA_SOURCE_APP" \
  --data '{"token":"<会员码二维码内容>","scanSourceApp":"<AIVA 提供>"}'
```

#### 返回示例（HTTP 200）

```json
{
  "status": true,
  "errorCode": "",
  "errorMsg": "",
  "data": {
    "oneId": "oneid_example"
  },
  "time": 1791850000123,
  "traceId": "…"
}
```

| 返回字段 | AgentOS 的使用 |
| --- | --- |
| `status` | 必须为 `true`，否则按失败处理 |
| `data.oneId` | 会员 ONEID，必须有值（不超过 64 字符、不含控制字符），否则按失败处理 |
| `data` 中的其他字段 | 本接口不返回；即使返回也不使用、不保存 |

#### 错误情况

| 情况 | AgentOS 的处理 |
| --- | --- |
| 后台未登记 AIVA 网关，或仍是旧版 Bearer 登记，或登记的 M01 地址不以 `/uc/v1/identity/suncodes` 结尾（推算不出网关地址），或 `sourceApp` / `scanSourceApp` 未登记 | 不调用 AIVA；点位登录返回 409（`code: AIVA_NOT_CONFIGURED`），提示去“用户与来宾卡 → 身份服务设置 → AIVA 网关”登记 |
| 网关返回 `status:false`（如会员码无效、已用过、已过期，或签名校验失败） | 点位登录返回 502（`code: AIVA_FAILED`），提示中带 AIVA 的 `errorCode`、`errorMsg` 原文 |
| HTTP 非 2xx、返回不是 JSON、超过登记的单次超时或网络中断 | 点位登录返回 502（`code: AIVA_FAILED`），提示带对方原文（前 200 字）或“超时” |
| `data.oneId` 为空、超长或含控制字符 | 点位登录返回 502，提示“没有返回有效的 ONEID” |
| AIVA 识别成功，但 AgentOS 建账户或登录失败 | 点位登录报错；会员码已被 AIVA 用掉，请会员在小程序刷新会员码后重扫 |

以上情况都不改用来宾卡或匿名身份，不自动重试。

## 绑定结果推送（AgentOS 调用 AIVA）

方向：由 **AIVA 提供**、**AgentOS 调用**。会员第一次在门店点位扫 AIVA 会员码、AgentOS 新建账户并关联 ONEID 后，AgentOS 把绑定结果告诉 AIVA（AIVA 文档中的“链路二”）。2026-10-13 起提供。

### 推送绑定结果
#### 功能描述

**什么时候推**：只在会员在互动点位扫 AIVA 会员码、AgentOS **新建账户并关联 ONEID** 之后推一次。以下情况**不推**：

- 会员在小程序扫来宾卡背面太阳码绑卡（[B03](#identity-b03)）：绑定由 AIVA 发起，AIVA 已经知道结果；
- 已有账户的会员再次扫码登录；
- 作品打印台登录（打印台不建账户）。

**怎么推**：AgentOS 在新建账户的同一次数据库操作中先记一条“待发送”推送记录，登录完成后再发送，所以推送失败不影响登录和后续体验。AIVA 以 `linkId` 判断是否重复：同一个 `linkId` 重发多次只算一次。失败后的处理见 [推送失败与后台重推](#aiva-push-retry)。

请求头与 [M01](#identity-m01) 相同（网关验签）。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `oneid` | string | 必填 | 会员 ONEID | `oneid_example` |
| `agentosId` | string | 必填 | 本次新建的 AgentOSID | `au_3f9c0d1e2a4b5c6d7e8f` |
| `linkId` | string | 必填 | AgentOS 绑定记录编号；AIVA 以它防重复 | `link_7c2e…` |
| `cardNo` | string | 可选 | 这条路没有卡，固定为 `null` | `null` |
| `bindScene` | string | 可选 | 这条路没有太阳码参数，固定为 `null` | `null` |
| `primaryAgentosId` | string | 可选 | 该会员的主账户（最早创建的账户）；首次建档时通常就是 `agentosId` | `au_3f9c0d1e2a4b5c6d7e8f` |

#### 请求示例

```bash
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/bindings" \
  -H "Content-Type: application/json" \
  -H "timestamp: 1791850000000" \
  -H "accessKey: $AIVA_ACCESS_KEY" \
  -H "sysCode: SD" \
  -H "sign: <按 M01 的签名规则计算>" \
  --data '{"oneid":"oneid_example","agentosId":"au_3f9c0d1e2a4b5c6d7e8f","linkId":"link_7c2e0a91","cardNo":null,"bindScene":null,"primaryAgentosId":"au_3f9c0d1e2a4b5c6d7e8f"}'
```

#### 返回示例（HTTP 200）

```json
{ "status": true, "errorCode": "", "errorMsg": "", "data": {}, "time": 1791850000123, "traceId": "…" }
```

HTTP 2xx、返回 JSON 且 `status` 为 `true` 时，AgentOS 把这条推送记为“已发送”。

#### 错误情况

| 情况 | AgentOS 的处理 |
| --- | --- |
| 网关返回 `status:false`、HTTP 非 2xx、返回不是 JSON、超时或网络中断 | 立即用同一内容（同一 `linkId`）再发一次；仍失败则标“失败”，记下 AIVA 的 `errorCode`、`errorMsg` 或对方原文，并发出后台告警 |
| 后台未登记 AIVA 网关（或登记不全） | 同上记为失败，原因写明去哪登记；登记后在后台“AIVA 推送记录”重推 |

会员登录、体验都不受推送结果影响。

## 作品数据推送（AgentOS 调用 AIVA）

方向：由 **AIVA 提供**、**AgentOS 调用**。会员在门店点位生成的作品，审核通过后由 AgentOS 同步一份到 AIVA 小程序后台。2026-10-13 起提供。

### 推送作品数据
#### 功能描述

**什么时候推**：作品保存到 AgentOS 并且**审核通过之后**，每个作品单独推一次。

- 2026-10-13 起，未登记内容安全或审核服务临时不可用时作品直接按通过处理，所以通常生成后马上推；内容安全判定不通过的作品不保存，也不推。
- 作品所属账户**必须已关联 ONEID**（AIVA 对 ONEID 为空的推送不保存）。只用来宾卡、还没在小程序绑定的用户，作品先不推；等他通过 [B03](#identity-b03) 绑卡成功后，AgentOS 把这张卡之前已通过、还没推过的作品补推。后台定时任务也会定期补上漏推的作品。
- 只推本功能上线后生成的作品（上线前的作品不推）。已删除的作品不推；已推过的作品被删除时，由 AIVA 调用[会员作品删除](#identity-work-delete)或[批量删除作品](#identity-work-batch-delete)同步删除。

**推哪些作品**

| 互动 | 推送 | 不推 |
| --- | --- | --- |
| AIVA面基 | 助手形象图 | 打招呼图 |
| AI音乐 | 歌曲（带封面地址 `coverUrl` 与歌词 `lyric`） | 封面不单独推 |
| AI图片生成 | 最终旅程图 | 身份图、过程图 |
| AI车衣共创 | 最终成片图：AI 共创与 DIY 都推**纸膜打印图**（2026-10-15 起；AI 共创作品编号、名称不变，`url` 为对应纸膜图的地址） | 生成过程图（花纹图、UV 展开贴图）；10-15 之前已推的 AI 共创 UV 贴图不补改 |

AI音乐的歌词还没写好时，这一轮先不推，下一轮再推，避免推出空歌词。

**作品地址**：作品原文件保存在公开读的对象存储，`url` / `coverUrl` 是公开地址，AIVA 可以直接打开（对象名为随机编号，删除作品即删除文件）。

**怎么推**：先记一条“待发送”推送记录再发送，推送内容在记录时固定，重推原样发送。`eventId` 每个作品一个，重推沿用同一个，AIVA 据此不重复处理。失败后的处理见 [推送失败与后台重推](#aiva-push-retry)。

请求头与 [M01](#identity-m01) 相同（网关验签）。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `eventId` | string | 必填 | 推送编号 = 推送时间（北京时间 yyyyMMddHHmmssSSS，17 位）+ 16 位随机码，共 33 位；一条推送记录一个编号，重推不变（2026-10-13 用户确认） | `20261013100015123a1b2c3d4e5f60718` |
| `oneId` | string | 必填 | 会员 ONEID | `oneid_example` |
| `agentosId` | string | 必填 | 作品所属 AgentOSID（可能是会员名下某张卡的账户） | `au_3f9c0d1e2a4b5c6d7e8f` |
| `bindScene` | string | 可选 | 该账户来宾卡的背面绑定参数；会员码自动建档的账户为 `null` | `Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx` |
| `experienceNo` | string | 必填 | AgentOS 体验编号 | `ix_6f1c…` |
| `storeId` / `storeName` | string | 必填 | 门店编号 / 门店名称 | `ST0001` / `重庆光环店` |
| `activityId` | string | 必填 | 点位编号 | `P08` |
| `activityName` | string | 可选 | 门店在后台填写的点位名称；未填写时为 `null` | `AI图片生成` |
| `experienceTime` | string | 必填 | 体验开始时间（ISO 格式，北京时间，带 +08:00） | `2026-10-13T10:00:00.000+08:00` |
| `works` | array | 必填 | 固定只有 1 个作品 | 见下 |
| `works[0].workId` | string | 必填 | AgentOS 作品编号 `assetId` | `asset_3f0a…` |
| `works[0].type` | string | 必填 | `image` 或 `audio` | `image` |
| `works[0].name` | string | 可选 | 作品名称 `{点位名称}_{生成完成时间 yyyyMMddHHmmss 北京时间}`；点位未填名称时为 `null` | `AI图片生成_20261013100015` |
| `works[0].url` | string | 必填 | 作品公开地址 | `https://<公开访问地址>/generated/…/3b9d….png` |
| `works[0].coverUrl` | string | 可选 | AI音乐的封面公开地址；其他作品为 `null` | `https://…/cover.png` |
| `works[0].lyric` | string | 可选 | AI音乐的歌词：有逐句时间时为**标准逐句 LRC**（每行 `[mm:ss.xx]歌词`，由音乐模型对成品音频的逐字字幕生成）；没有时间数据的歌（2026-10-13 之前生成的）为纯文字歌词（含 `[verse]` 等段落标记）；其他作品为 `null`（2026-10-13 用户确认） | `[00:01.12]雪线压着公路的尽头` |
| `works[0].createdAt` | string | 必填 | 作品生成时间（ISO 格式，北京时间，带 +08:00） | `2026-10-13T10:00:15.000+08:00` |

#### 请求示例

```bash
curl -X POST "$AIVA_GATEWAY/uc/v1/identity/experience-records" \
  -H "Content-Type: application/json" \
  -H "timestamp: 1791850000000" \
  -H "accessKey: $AIVA_ACCESS_KEY" \
  -H "sysCode: SD" \
  -H "sign: <按 M01 的签名规则计算>" \
  --data '{"eventId":"20261013100015123a1b2c3d4e5f60718","oneId":"oneid_example","agentosId":"au_3f9c0d1e2a4b5c6d7e8f","bindScene":null,"experienceNo":"ix_6f1c0a2b","storeId":"ST0001","storeName":"重庆光环店","activityId":"P08","activityName":"AI图片生成","experienceTime":"2026-10-13T10:00:00.000+08:00","works":[{"workId":"asset_3f0a9c1e","type":"image","name":"AI图片生成_20261013100015","url":"https://<公开访问地址>/generated/ST0001/3b9d.png","coverUrl":null,"lyric":null,"createdAt":"2026-10-13T10:00:15.000+08:00"}]}'
```

#### 返回示例（HTTP 200）

```json
{ "status": true, "errorCode": "", "errorMsg": "", "data": {}, "time": 1791850000123, "traceId": "…" }
```

HTTP 2xx、返回 JSON 且 `status` 为 `true` 时，AgentOS 把这条推送记为“已发送”。

#### 错误情况

| 情况 | AgentOS 的处理 |
| --- | --- |
| 网关返回 `status:false`、HTTP 非 2xx、返回不是 JSON、超时或网络中断 | 立即用同一内容（同一 `eventId`）再发一次；仍失败则标“失败”，记下 AIVA 的 `errorCode`、`errorMsg` 或对方原文，并发出后台告警 |
| 后台未登记 AIVA 网关（或登记不全） | 同上记为失败，原因写明去哪登记；登记后在后台“AIVA 推送记录”重推 |
| 作品公开地址生成不了（后台“对象存储 → 公开访问地址”未配置） | 不发送，直接记为失败并告警；配置后重推，重推时按当前配置补上地址 |

生成作品、打印、点位体验都不受推送结果影响。

### 推送失败与后台重推

绑定结果推送与作品数据推送的失败处理相同（2026-10-13 用户确认）：

1. **先记录再发送**：每条推送先记“待发送”记录，再发送。服务中途重启导致没发出去的记录，由后台定时任务接着发。
2. **失败立即重发一次**：用完全相同的内容（同一 `linkId` / `eventId`）再发一次，AIVA 据此不会重复处理。
3. **仍失败就停下并告警**：记录标为“失败”，保存 AIVA 返回的 `errorCode`、`errorMsg`（或对方原文），发出后台告警（事件 `aiva.push_failed`，站内信），不再自动重发。
4. **后台手动重推**：后台“用户与来宾卡 → 身份服务设置 → AIVA 推送记录”（需平台账号）列出全部推送，可按类型（绑定 / 作品）和状态（待发送 / 已发送 / 失败）筛选，查看推送内容、尝试次数与失败原因；失败的记录可以单条“重推”或“全部重推”（一次最多 200 条），手动重推只发一次。页签上的红点为失败条数。

推送永远不阻塞业务：登录、生成、打印照常进行。

## 相关后台操作（AgentOS 内部）

以下由 AgentOS 运营在后台操作，不是对外接口，列出供对接时理解数据来源。

### 生成卡背面绑定参数（B01）
#### 功能描述

为一个批次内未作废的卡生成并导出背面绑定参数 `bindScene`。每张卡的参数生成后固定不变（重复调用返回同一个值），与卡正面短码无关，也不能由 AgentOSID 推算。后台“卡批次 → 背面绑定参数”按钮即调用此接口；太阳码图片由 M01 生成。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 来宾卡批次号 |
| （Body） | Body | object | — | 发送空对象 `{}` |

#### 请求示例

```bash
curl -X POST "$BASE/api/admin/card-batches/BATCH_20261001_01/binding-scenes" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <登录响应中的 csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{
  "items": [ { "card_code": "C000123", "card_no": "CQ0001023", "AgentOSID": "au_3f9c…", "bindScene": "Qm9yZGVyU2NlbmVfMDAwMDAwMDAwMDAx" } ],
  "miniProgramCodeGenerated": false,
  "note": "稳定的32字符绑定参数；由AIVA小程序服务生成对应太阳码，此接口不伪造太阳码图片。"
}
```

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 未登录后台或登录已过期 | 重新登录 |
| 403 | 没有“来宾卡导出”权限；缺少 CSRF 令牌 | 联系管理员授权；刷新页面后重试 |
| 404 | 批次不存在或不在本账号的门店范围 | 核对批次号与门店 |

### 导出来宾卡打印图

后台“卡批次 → 导出打印图”：上传正反面卡面模板并登记码的位置，逐卡合成正面会员识别码（`{域名}/c/{离店短码}`）与背面太阳码（M01），打包下载。属于后台功能，不对外提供。

## 联调测试工具

AgentOS 提供网页测试工具：`https://aiva.dev.vavedigital.com/admin/tools/identity-test/`。可以逐个调用本文接口和点位登录接口，也可以按场景一键验证：扫卡首次绑定、重复提交与冲突、无效参数、AIVA 会员码登录与退出（首次来访自动建档）、AIVA 会员码只能使用一次、门店卡登录、不同凭证互不通用、按 ONEID 汇总。其中 S5、S6 两个会员码场景需要手动填入真实的 AIVA 小程序会员码内容（在小程序打开会员码复制二维码内容，只能用一次，且所连环境须已登记 AIVA 网关及 sourceApp / scanSourceApp）；原“AgentOS 会员凭据”相关场景已于 2026-10-13 删除。工具会在所连环境里写入测试用户和绑定，只用于测试环境。

单个接口调试另有 `https://aiva.dev.vavedigital.com/admin/tools/oneid-test/`：覆盖本文中 AIVA 调用 AgentOS 的全部 8 个接口（B02—B06、作品删除、批量删除作品、作品码查询），填写参数时实时显示完整请求（地址、请求头、请求体、curl），发送后显示状态码、耗时、响应头与响应体，并保留本页调用记录；凭证只显示末4位。B03、作品删除、批量删除作品会写入或删除所连环境数据，只用于测试环境。AgentOS 调用 AIVA 的四个接口不在工具中，推送结果请在后台“身份服务设置 → AIVA 推送记录”查看。

AgentOS 调用 AIVA 的接口另有 `https://aiva.dev.vavedigital.com/admin/tools/aiva-test/`（2026-10-13）：需先在同一浏览器登录 AgentOS 后台（平台账号）。可直接调用二维码扫码识别（可临时填写 sourceApp / scanSourceApp，会消耗会员码）、绑定结果推送、作品数据推送与 M01 太阳码，显示 AgentOS 实际发出的请求（凭证脱敏）与 AIVA 原样返回；还列出所有用户的可同步作品，可单个“同步”，或“同步给其他用户”——先为目标用户（AgentOSID 或完整 ONEID，须已关联 ONEID）新增一条作品记录（文件另存一份、记录复制自哪个作品），再推送 AIVA。会向 AIVA 测试环境写数据，只用于测试环境。
