# AgentOS 互动应用开发接入文档

## 隐私声明与体验须知（2026-10-12）

AIVA面基（含第二台）、AI音乐、灵感探索的点位配置增加 `experienceNotice`（不超过16000字），与 `privacyNotice` 分开编辑和保存。客户端依次展示两页；任一拒绝即退出，未登记文案拒绝开始，不用网页固定文案替代。文本随点位配置版本保存，无新增数据库迁移。

- 面基 Demo 的 config/start 返回两段文案。`:id/consent` 请求 `{accepted, phase:'privacy'|'experience', storeId}`；先确认 privacy，再确认 experience，后者才放行照片处理。会话绑定本店及P02/P02B，确认事件记录配置版本。
- 灵感 Demo config 返回两段文案，沿用 privacy-consent → consent 的顺序；两步完成后才申请摄像头。
- 音乐台 `GET /api/p03/notices`（设备或已鉴权Demo）返回 `{noticeVersion,privacyNotice,experienceNotice}`，按已鉴权租户/门店/实际点位读取。匿名或授权测试读最新保存版本，正式设备读active或单独明确发布告知的版本。`POST /api/p03/chat/start` 须带 `{noticeVersion,privacyAccepted:true,experienceAccepted:true}`；文案更新或缺任一确认返回409，开始DJ会话时保存确认事件。文案版本变化时返回 `code:MUSIC_NOTICE_UPDATED`；客户端须返回重新读取两段文案并取得两次同意，不能重发旧版本或自动同意新版本。读取配置不清空本次已确认版本，退出或新身份/新体验时清除确认。本接口不替代正式互动API的授权策略确认，也不改变计费。

音乐台上机配置提供 `GET/PUT /api/admin/stores/:storeId/points/:pointId/music-notices`，支持P03目录的实际点位（包括D100）。PUT须有point:edit及prompt:edit权限，提交expectedRevision和两段文案；仅追加告知配置修订、标记noticePublished，保留其他配置，不发布旧版音乐流程。跨店/非音乐点位/旧版本拒绝写入，操作留审计。

更新部署后，运营需在各点位后台登记并保存两段文案；参考草稿按钮仅填空白项，须核对后人工保存，不自动写库。

### 面基扫码关联体验（2026-10-12）

P02/P02B的`demo/start`支持播控桥接`userSession`（转发为X-Identity-Session）；后端先核对设备与用户会话，创建记录时事务复核并沿用卡AgentOSID。匿名入口不传用户会话，仍独立建档。客户端不得提交AgentOSID指定归属；失效/跨店会话拒绝，不回退匿名。作品、作答、对话记录归到当前卡，但不代表正式Token扣费、共享画像累计或跨次自动回忆已验收。扫码解析与内存令牌模块为公共基础，本轮只接面基，不改音乐及灵感的身份流程。

### 音乐台现场 Demo（2026-10-12）

已绑定且启用的P03/D100音乐设备无需临时后台测试授权。`GET /api/p03/player-demo` 返回 `enabled:true, expiresAt:null`；`POST /api/p03/player-demo/start` 签发绑定租户、门店、点位和设备的匿名Demo会话，后续请求通过原播控身份桥接传递。保留后台登记的空闲超时、真实模型用量、双告知版本校验和资源隔离；服务器重启后可直接重新开始，无需管理员登录。正式会员身份/Token结算与普通浏览器配对入口不变。旧后台 `POST /api/admin/stores/:id/points/:pointId/player-demo` 返回409提示临时授权已取消，不再伪称可授权或撤销。停用/解绑设备仍拒绝调用。

## AIVA面基双点位免扫码 Demo（2026-10-10）

P02 与 P02B（AIVA面基2）是同一产品目录 P02 的两个独立实例。第二台首次复制本店 P02 最新已保存草稿与点位模型绑定，之后独立修改；不复制点位码、设备凭据、体验和运行回执。P02 保留原配置表；P02B 使用 interaction_config_revision 的独立 point_id，不回退读取 P02。

- `POST /api/admin/stores/:storeId/p02/workspace/copy-second`：`{confirm:true}`。须 point:create、point:edit、model_bind:edit、prompt:edit 权限及门店范围；事务锁定门店，重复创建返回409、不覆盖。
- `/api/admin/stores/:storeId/p02b/workspace` 及 options、overview、records、score、preview、check、tests 与第一台同结构，仅操作 P02B。
- `POST /api/admin/stores/:storeId/:point/workspace/enable-demo`（point 为 p02 或 p02b）：`{confirm:true,reason:"现场测试原因"}`。仅系统管理员；检查 Demo 配置、已配对电脑与播控配置后显式沿现有状态流程启用，允许越过正式链路未完成的发布阻塞，敏感审计留痕。不自动切屏，不代表生产配置发布；测试结束转维护。
- 第一台网页 `/meet/?storeId=<门店>&pointId=P02`，第二台 `pointId=P02B`；播控网页以已鉴权的本机上下文覆盖 URL 点位/门店，不向页面下发设备密钥。
- 第一台 Demo 使用 `/api/p02/demo/`，第二台使用 `/api/p02b/demo/`。config、start、`:id/consent`、start-image、generate、generation-status、greeting-image、chat、tts、finish 语义保持一致；ASR 分别使用 `/api/p02/demo/asr` 与 `/api/p02b/demo/asr`，带 storeId/sessionId。会话随机 ID 必须同时匹配门店与点位，交叉使用返回404。
- EXE 桥接仅新增实际点位的 Demo start 接口；携设备凭据时检查点位、门店与当前播控准入。后续模型长请求和 ASR 使用原 Demo 随机会话，不受播控心跳的短网络超时影响。不增加自动付费重试。
- 两台及其他面基体验合计共用单进程6个在途生图槽；不是每台6路。首图满槽仍429，挥手图保留既有等待与取消规则。次数上限按门店+点位独立计数。单进程，不据此启动多个副本。

依旧是 P02_DEMO_ENABLED 控制的临时匿名 Demo：有真实厂商用量及体验留存（2026-10-13 起作品以原文件存入公开读的对象存储），不等于真实扫码、正式内容审核和业务 Token 结算。切走互动会停止摄像头、录音、ASR和声音，已提交任务不取消；切回保持页面，摄像头由用户点击重新打开。

## 文档说明

版本：2026-10-06。读者：P02、P03、P08、P04 互动应用及现场展示程序的开发者。本文回答“我的页面在什么时机调用什么接口、传什么、拿到什么、下一步怎么走”。示例值均为占位内容，不是默认配置。

## 后台｜AI 音乐上屏配置检查（2026-10-10）

`GET /api/admin/stores/:id/points/:pointId/music-inspection`：后台登录、`point:view` 权限及租户/门店范围校验；只读，不调用厂商、不解密凭据、不创建测试授权、不发布版本、不切换现场画面。

- `sections` 分别返回正式模型/审核配置、已批准点位 P03/D100 的测试模型配置、已登记应用网址及播控运行回报；每项 `state` 为 `pass` / `error` / `pending`，`message` 提供缺项或下一步。正式检查与 `/api/p03/readiness` 共用校验；审核检查读取与实际审核相同的平台参数。
- `providerTested:false`、`clientConfigConfirmed:false`：配置检查不代表真实厂商调用成功，不把播控显示状态冒充模型配置版本回执。真实身份、Token 结算及生成效果仍须联调。
- 当前 `/api/p03` 使用能力绑定，绑定保存后直接供运行接口解析，已有对话可能持有旧模型，应新开体验验证。统一互动接口的版本化问卷发布不是当前上屏链路的应用操作；题目与提示词迁移尚未完成，不据此宣称其已生效。

## 公用｜正式文本与图片任务（2026-10-06）

AIVA面基（P02）、AI音乐（P03）、AI图片生成（P08）、AI车衣共创（P04）调用模型时，都通过本章的“正式任务”接口：客户端提交请求后立即拿到任务号，服务端在后台调用模型，客户端用原任务号查询结果。每次调用先按后台登记的单次上限冻结 Token，结束后按厂商实际用量结算。生成的图片以原文件保存为作品（2026-10-13 起不再加密，存入公开读的对象存储），审核通过后通过本章的作品接口取得公开地址。本章接口全部由互动点位客户端调用，鉴权均为 U（设备凭证 + `X-Identity-Session`）。

### 调用前提与请求号规则

- **归属**：Path 中的 `:id` 是创建体验返回的 `interactionId`。体验必须由**同一台设备、同一个登录会话**创建；换设备或重新扫码登录后，旧体验的任务与作品返回 404（“我的作品”“当前助手”除外，它们按用户读取）。
- **准入**：创建任务前须完成授权、问卷或设计；点位须是 Agent 互动应用（展示点位、普通展示应用返回 409）。**2026-10-13 起不再要求本点位播控电脑正在显示互动应用**（取代 10-10“实际 Agent 画面准入”）：播控关机、重启、断电，或开发者在播控未开机时调试，都可以正常调用。所用模型须在后台“模型”页配置好连接与凭证，并在点位配置里选定（缺少时 409）。**2026-10-13 起**：不再要求登记参数定义或模型版本；模型没填 Token 兑换比例或单次冻结上限时**照常调用、不冻结也不扣 Token**，任务计费的冻结额与结算额为 0，计费说明（`billing.reason`）写明“未计费：模型未填……”，正式运营前须补齐。当前生产发布仍有语音、画像等门禁，联调不绕过门禁（具体门禁清单待确认）。
- **请求号 requestId**：由客户端生成，最长 64 字符，在同一次体验内唯一。同一个请求号原样重发不会重复执行，返回第一次的任务号（`status:"existing"`、`idempotentHit:true`）；同一个请求号换了内容再发返回 409。
- **作品基础数据**（2026-10-09）：作品保存时读作品文件本身实测并保存——图片宽高（像素）、音频时长（毫秒）、文件大小（字节），在作品列表与 B06 `assets` 中返回。读不出（文件异常或格式不支持）时该作品保存失败并报错，不保存空值；本功能上线前保存的作品不补算，宽高/时长为 `null`。
- **作品名称**（2026-10-09）：作品保存时按 `{点位名称}_{生成完成时间 yyyyMMddHHmmss，北京时间}` 生成并固定，如 `AI音乐_20261009103015`。点位名称由门店在后台点位详情填写；未填写时作品名称为空。音乐封面随音乐作品，不单独命名。
- **新请求号 = 新的一次付费调用**。网络错误或结果未知时，客户端只能用原任务号继续查询，不能自动换一个请求号重新生成。
- **文本限制**：所有文本字段不能为空白，不能包含换行、制表符等控制字符，超长返回 400。

### 任务状态与 Token 冻结

创建接口返回的 `status` 只有 `queued`（新任务已登记）和 `existing`（请求号重放）两种；任务的真实进度以查询接口的 `status` 为准：

| 任务 status | 含义 | Token | 客户端处理 |
| --- | --- | --- | --- |
| `prepared` | 已登记，尚未提交厂商 | 已冻结 | 继续查询 |
| `dispatched` | 已提交厂商，等待结果 | 已冻结 | 继续查询 |
| `completed` | 成功 | 按实际用量结算，余量释放；小数 Token 向上取整 | 文本读取 `response`；图片读取 `assetId` 取件 |
| `failed` | 厂商明确失败，或生成图审核未通过 | 冻结全额冲正 | 显示失败态；用户主动再次提交时用新请求号 |
| `cancelled` | 提交厂商前体验已结束，或服务重启时尚未提交 | 冻结全额冲正 | 视为未执行 |
| `unknown` | 结果无法确认：通信中断、厂商返回不符合约定、用量缺失或超过冻结上限、体验结束后才返回、服务重启时已提交未返回 | **保留冻结**，由有权限的运营在后台核对厂商记录后人工“按核对用量结算”或“全额释放” | 显示“结果待核对”，不自动重试 |

`billing.status` 是这次调用的冻结记录状态：`frozen` 冻结中、`settled` 已结算、`reversed` 已冲正（全额释放）、`unknown` 结果未知、`review` 用量待核对（缺用量或超上限）。人工处置后 `billing.status` 变为 `settled` 或 `reversed`，但任务 `status` 仍保持 `unknown`。

**文本任务例外（2026-10-14）**：模型已正常返回、只是计费转待核对（如真实用量费用超过冻结上限）时，任务 `status` 为 `completed`，照常返回 `response`，体验恢复可继续操作（如重新风格对话、保存方案）；`billing.status` 为 `review`，冻结保留待运营人工核对。

任务进行期间体验状态为 `running`，此时不能再提交新任务。任务结束后：成功或明确失败回到提交前的状态（AIVA面基聊天成功后为 `chat`；AI图片生成、AI车衣共创生成图成功后为 `generated`）。**任务为 `unknown` 时体验保持 `running`**，不能再提交任务；访客可以用[结束体验](#api-interaction-end)以“放弃”（`abandoned`）结束（2026-10-08 修复，此前无法结束）。冻结的 Token 不释放，由工作人员在后台核对厂商记录后人工处置；之后迟到的结果不再附加到已结束的体验。

服务端不规定轮询间隔和最长等待（待确认），客户端不要根据自己的轮询超时推断失败。

### 创建文本任务
#### 功能描述

提交一次文本模型调用。**AI车衣共创（2026-10-14）：同一次调用等模型返回后直接给出结果**，返回内容与[查询文本任务](#api-text-task-get)相同（含 `status`、`response`、`billing`），不需要再查询；其他互动立即返回任务号，再用查询接口取结果。

**AI车衣共创要播报这句回复时，请求里带 `speak: true` 即可（2026-10-20）**：响应会多一个 `voice` 字段，内容与[语音合成](#api-tts)的返回一致（含 `audio`），不用先取 `messageId` 再调一次。语音的请求号由文本任务号派生，所以用同一个 `requestId` 重发拿到的是同一条语音，走缓存不重复计费。语音合成失败不影响文本结果：文本照常返回，失败原因放在 `voice.error`（不自动重试）。

各互动可用的用途（purpose）：

| 互动 | purpose | 用途与调用时机 |
| --- | --- | --- |
| AIVA面基（P02） | `intro` | 根据已提交五题生成助手名称与介绍；问卷完成后、体验状态为 `ready` 时调用，不接受客户端正文 |
| AIVA面基（P02） | `chat` | 名片完成后与助手聊天；`text` 为用户输入 |
| AIVA面基（P02） | `suggestions` | 名片完成后生成恰好三条不同的建议问题，不接受客户端正文 |
| AI音乐（P03） | `lyrics` | 正式歌词；须传当前已确认的曲风人声修订号 `revision`，详见 [AI音乐](#p03) |
| AI图片生成（P08） | `guide` | 每题作答后的“助手回复”；授权后、提交全部答案前调用，详见 [旅程引导回复](#p08-guide) |
| AI车衣共创（P04） | `style` | 风格对话：`text` 为用户文字或语音识别结果（1—2000字），模型从全部已启用风格中替用户选一个，返回给用户的回复与风格，详见 [风格对话](#p04-free) |

服务端从本次体验的配置读取提示词与模型。`chat`、`suggestions`、`guide` 会附带后台指定知识库全文与该用户的结构化记忆（见本章末尾）。用户输入文字（`chat` 的 `text`、`guide` 的自由文本）在建任务、冻结 Token **之前**送内容安全审核，未通过时本次不建任务、不冻结；未登记内容安全或审核服务临时不可用时不送审、按通过处理（2026-10-13 确认，见[内容安全](#formal-tasks-moderation)）。

调用成功即已冻结 Token。同一个请求号原样重发不会重复执行，返回第一次的任务号，也不会再次审核。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `requestId` | Body | string | 必填 | 请求号，最长 64 字符，本次体验内唯一 | `guide-q1-001` |
| `purpose` | Body | string | 必填 | 见上表；必须是当前点位支持的用途 | `guide` |
| `text` | Body | string | 视用途 | `chat` 必填，最长 4000 字符；`guide` 自由文本回答，最长 2000 字符，仅该题 `allowText=true` 时可用，与 `optionId` 二选一；`intro`、`suggestions`、`lyrics` 不接受 | `想去海边看日落` |
| `questionId` | Body | string | 视用途 | 仅 `guide`，必填，须为本次配置中的题目 | `q_destination` |
| `optionId` | Body | string | 视用途 | 仅 `guide`，与 `text` 二选一，须为该题配置的选项 | `opt_sea` |
| `revision` | Body | integer | 视用途 | 仅 AI音乐 `lyrics` 必填（≥1，须等于最新已确认修订号）；其他点位传此字段返回 400 | `3` |
| `speak` | Body | boolean | 否 | **仅 AI车衣共创 `style`（2026-10-20）**：传 `true` 时把这句回复的语音随结果一起返回（响应多一个 `voice`），不用再单独调[语音合成](#api-tts)。其他点位传此字段返回 400 | `true` |

Body 只能包含上表字段，多余字段返回 400。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_6f1c/text-tasks" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"guide-q1-001","purpose":"guide","questionId":"q_destination","optionId":"opt_sea"}'
```

#### 返回示例（HTTP 200）

```json
{
  "taskId": "task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10",
  "status": "queued",
  "idempotentHit": false,
  "note": "任务已持久化并冻结；查询原taskId，不用新requestId重试未知调用。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `taskId` | 任务号；之后用它查询结果 |
| `status` | `queued`：新任务已登记；`existing`：请求号重放，返回的是第一次的任务 |
| `idempotentHit` | 是否为请求号重放 |
| `note` | 说明文字，不用于程序判断 |

#### 错误情况

错误响应为 `{"error":"说明"}`，内容安全相关错误另带 `code`（审核未通过另带 `failureKind:"moderation"`）。客户端按 HTTP 状态 + `code` 分支，不匹配中文文案。

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 含未支持字段；purpose 不属于当前点位；requestId、text、questionId、optionId 为空、超长或含控制字符；AI音乐缺 `revision` 或其他点位传了 `revision`；`guide` 未提交或同时提交 optionId 与 text；题目或选项不在本次配置中；该题不允许自由文本；`intro`/`suggestions` 带了 text；请求体不是合法 JSON | 修正请求；不要换请求号重试同一错误 |
| 401 | 设备凭证无效；缺少用户会话、会话过期或已退出、身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备调用 | 联系运维 |
| 404 | 体验不存在，或不是当前设备、当前登录会话创建的 | 检查 interactionId；重新登录后需新开体验 |
| 409 | 会员主账户已变更；同一请求号已用于不同内容；点位不是 Agent 互动应用；当前阶段不允许（如未授权/未答完、`intro` 时状态不是 `ready`、名片完成前调用 `chat`/`suggestions`、`guide` 不在问题阶段或已有运行中任务、AI音乐曲风人声未确认）；授权已撤回；配置缺提示词、未选择文本模型、模型的接口类型/地址/超时不完整；指定知识库不存在、无有效条目或超过 512KiB；结构化记忆条数未登记（`memory.max_tags`/`memory.max_history_items`）；整体上下文超过 512KiB | 按提示处理配置或流程；配置类问题联系运营，不要自动重试 |
| 413 | 请求体超过 100 万字符 | 缩短内容 |
| 422 | `code=CONTENT_REJECTED`：用户输入文字审核未通过（BLOCK/REVIEW） | 显示“审核未通过”，请用户修改后再提交；本次未建任务、未冻结 |
| 409 | 可冻结的 Token 不足（409，`code:"TOKEN_INSUFFICIENT"`，2026-10-08 修复，原为 500） | 提示用户 Token 不足，不要自动重试 |
| 500 | 模型已停用或能力不匹配；加密主密钥未配置等服务端问题 | 显示失败，不要自动重试 |

### 查询文本任务
#### 功能描述

用创建时返回的任务号查询文本任务的进度、结果与 Token 结算情况。只有 `status=completed` 时返回模型正文；其他状态 `response` 为 `null`。任务状态与 Token 规则见 [任务状态与 Token 冻结](#formal-tasks-states)。

各用途的 `response` 格式：

| purpose | response |
| --- | --- |
| `intro` | JSON 字符串 `{"name":"…","description":"…"}`；介绍为 30—45 个可见字符 |
| `suggestions` | JSON 字符串 `{"suggestions":["…","…","…"]}`，恰好三条且各不相同 |
| `chat` / `guide` | 纯文本，不截断 |
| `style` | JSON 字符串。**2026-10-22 起由模型现编风格与 4 个配色**：`{"code","mode":"generated","style_task_id","raw","style_name","style_reply","colors":[{index,name,hex}×4],"reply_text"}`，详见 [风格对话](#p04-free)。模型输出不符合约定时任务失败（`status=failed`，`failure.code=STYLE_PARSE_FAILED`），不补兜底风格、不补默认配色 |
| `lyrics` | JSON 字符串，字段见 [AI音乐](#p03) |

模型返回不符合上述格式（如介绍字数不对、建议不足三条、引导回复为空）时任务记为 `unknown` 并保留冻结，不补模板或固定文案。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `taskId` | Path | string | 必填 | 创建文本任务返回的任务号 | `task_2b7e…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f1c/text-tasks/task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "taskId": "task_2b7e0c3a-9d41-4f7e-8a51-0c6d2f1e9b10",
  "purpose": "guide",
  "status": "completed",
  "messageId": "msg_5a0d7e21-3c8b-4b1f-9e64-2f7a1c0d8e33",
  "response": "海边的日落很适合慢下来，你想和谁一起出发？",
  "usage": { "input_token": 812, "output_token": 46 },
  "providerRequestId": "0217…",
  "billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 3, "reason": "success" },
  "note": "通信未知结果保留冻结，不能自动重试；此同步厂商接口尚无按原请求查询结果的适配器。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `purpose` | 创建时的用途 |
| `status` | `prepared` / `dispatched` / `completed` / `failed` / `cancelled` / `unknown` |
| `messageId` | 本次消息编号。AIVA面基完成名片时作为 `introMessageId`；语音播报时作为要合成的消息 |
| `response` | 仅 `completed` 时有值，格式见上表 |
| `usage` | 厂商返回的用量 `{input_token, output_token}`；未返回时为 `null` |
| `providerRequestId` | 厂商请求号，用于核对；未知时为 `null` |
| `billing.status` | `frozen` / `settled` / `reversed` / `unknown` / `review` |
| `billing.frozenAmount` / `settlementAmount` | 冻结 Token 数；结算 Token 数（结算前为 `null`） |
| `billing.reason` | 结算说明：成功为 `success`，冲正为 `failed`/`cancelled`，未知或待核对为说明文字，人工处置后为核对依据 |
| `note` | 说明文字，不用于程序判断 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话；任务号不存在或不属于该体验 | 检查任务号，不要改用新请求号重新生成 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 创建图片任务
#### 功能描述

提交一次单图生成。不同互动的输入：

| 互动 | 输入 | 前提 |
| --- | --- | --- |
| AIVA面基（P02） | 用户照片 `photo` | 已授权、已提交五题、体验状态为 `ready`；本次体验尚未完成名片（要新形象须“[重新回答](#api-interaction-restart)”新开体验） |
| AI图片生成（P08） | 用户照片 `photo` | 已授权、已提交全部答案、已调用[确认](#api-interaction-confirm)（出发）、状态为 `ready` |
| AI车衣共创（P04） | 用户点“去生成”时选定的风格与配色：默认风格传 `styleId`+`colorId`；AI 生成风格（2026-10-22）传 `styleTaskId`+`colorIndex`（2026-10-14 一次调用：服务端保存方案并开始生成） | 已授权、没有正在进行的生成；参考车图由后台配置，客户端不能传照片；本次体验生成次数不超过后台登记上限（未登记则拒绝），详见 [AI车衣共创](#p04) |

用户照片在建任务、冻结 Token **之前**送内容安全审核：照片以临时对象 + 短时签名链接提交审核，审核结束立即删除，不保存为作品。审核未通过时本次不建任务、不冻结；未登记内容安全或审核服务临时不可用时不送审、按通过处理。

生成图在保存为作品前再审核一次，结论决定任务结果（见 [生成图片审核结论](#formal-tasks-moderation)）。生成图以原文件保存到公开读的对象存储（2026-10-13 起不再加密，对象名为随机编号，审核通过后才给出地址）。同一个请求号原样重发不会重复执行，返回第一次的任务号。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `requestId` | Body | string | 必填 | 请求号，最长 64 字符，本次体验内唯一 | `journey-img-001` |
| `photo` | Body | string | 视互动 | AIVA面基、AI图片生成必填：PNG 或 JPEG 的 data URL（`data:image/png;base64,…` 或 `data:image/jpeg;base64,…`），解码后不超过 5MiB，声明格式须与内容一致；不接受远程 URL。AI车衣共创不能传 | `data:image/jpeg;base64,/9j/4AAQ…` |
| `styleId` | Body | string | 视互动 | AI车衣共创·默认风格必填：已启用风格的编号（`wrap.styles[].id`） | `style_cyber` |
| `colorId` | Body | string | 视互动 | AI车衣共创·默认风格必填：该风格下配色的编号 | `color_blue` |
| `styleTaskId` | Body | string | 视互动 | AI车衣共创·AI 生成风格必填（2026-10-22）：风格对话返回的 `style_task_id`（即该次文本任务的 `taskId`）。风格名与色值由服务端从这次风格对话结果里取，客户端不传 | `task_3f1e…` |
| `colorIndex` | Body | integer | 视互动 | AI车衣共创·AI 生成风格必填：用户选的是第几个配色，0—3，对应返回里 `colors[].index` | `2` |
| `source` | Body | string | 否 | AI车衣共创：风格来源 `preset`（直接点选，默认风格时的默认值）/`text`（打字，AI 生成风格时的默认值）/`voice`（语音） | `voice` |
| `matchTaskId` | Body | string | 否 | AI车衣共创·默认风格：风格对话的 `taskId`，仅用于记录（AI 生成风格请用 `styleTaskId`） | `task_3f1e…` |

Body 只能包含上表字段，多余字段返回 400。AI车衣共创二选一：默认风格 `{styleId,colorId}`，或 AI 生成风格 `{styleTaskId,colorIndex}`，混传返回 400；`styleTaskId` 不是本次体验已完成的风格对话返回 404/409，不是 AI 生成结果（如 2026-10-22 之前的库匹配结果）返回 400。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_6f1c/image-tasks" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"journey-img-001","photo":"data:image/jpeg;base64,/9j/4AAQ..."}'

# AI车衣共创“去生成”
curl -X POST "$BASE/api/interactions/ix_7d3e/image-tasks"   -H "Authorization: Bearer $DEVICE_CREDENTIAL"   -H "X-Identity-Session: $SESSION_TOKEN"   -H "Content-Type: application/json"   --data '{"requestId":"wrap-go-001","styleId":"style_cyber","colorId":"color_blue","source":"voice","matchTaskId":"task_3f1e..."}'
```

AI车衣共创的返回另带 `designRevision`（服务端保存的方案修订号，仅供记录）。

#### 返回示例（HTTP 200）

```json
{
  "taskId": "task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64",
  "status": "queued",
  "idempotentHit": false,
  "note": "（说明文字，内容以实际返回为准）"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `taskId` | 任务号；之后用它查询结果 |
| `status` | `queued`：新任务已登记；`existing`：请求号重放 |
| `idempotentHit` | 是否为请求号重放 |
| `note` | 说明文字，不用于程序判断 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前点位不是 AIVA面基/AI图片生成/AI车衣共创；含未支持字段；requestId 格式错误；AI车衣共创传了 `photo`；请求体不是合法 JSON | 修正请求 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话 | 检查 interactionId |
| 409 | 会员主账户已变更；同一请求号已用于不同内容；点位不是 Agent 互动应用；状态不是 `ready`（未授权、未答完、已有运行中任务、已生成过）；授权已撤回；AI图片生成未确认出发；AIVA面基本次已完成名片；AI车衣共创修订号不是最新已确认、生成次数上限未登记或已用完、参考车图缺失；配置缺图片模型、模型的接口类型/地址/超时不完整；作品留存期限未登记 | 按提示处理流程或联系运营，不要自动重试 |
| 413 | 请求体超过 800 万字符 | 压缩照片后重新提交 |
| 422 | `code=CONTENT_REJECTED`（`failureKind=moderation`）：用户照片审核未通过 | 显示“审核未通过”，请用户重拍；本次未建任务、未冻结 |
| 400 | 照片缺失（`code:"PHOTO_REQUIRED"`）；不是 PNG/JPEG 的 data URL、数据损坏或实际格式与声明不符（`code:"PHOTO_INVALID"`）。2026-10-08 修复，原为 500 | 提示重拍或重新选择照片 |
| 413 | 照片超过 5MiB（`code:"PHOTO_TOO_LARGE"`）；请求体超过 8MiB | 压缩照片后重新提交 |
| 409 | 可冻结的 Token 不足（409，`code:"TOKEN_INSUFFICIENT"`，2026-10-08 修复，原为 500） | 提示用户 Token 不足，不要自动重试 |
| 500 | 模型已停用；存储桶/存储前缀未配置；加密主密钥未配置 | 显示失败，不要自动重试 |

### 查询图片任务
#### 功能描述

用原任务号查询图片任务的进度、作品编号、生成图审核结论与 Token 结算。生成图审核结论对任务的影响：

| 生成图审核 | 任务 status | Token | 作品 |
| --- | --- | --- | --- |
| 通过（`moderation.verdict=pass`） | `completed` | 按实际张数结算 | 自动审核通过，`assetId` 可取件 |
| 未登记内容安全或审核服务临时不可用（2026-10-13 起按通过处理：`verdict=pass`、`decision=SKIPPED`） | `completed` | 按实际张数结算 | 自动审核通过并标记“未审核”，`assetId` 可取件 |
| 未通过（`verdict=rejected`，BLOCK/REVIEW） | `failed`，另带 `failureKind:"moderation"`、`code:"CONTENT_REJECTED"` | 冻结全额冲正 | 不保存，`assetId` 为 `null` |

另外：审核通过但厂商用量缺失或超过冻结上限时，任务为 `unknown`（`billing.status=review`），作品已保存，但要等运营核对结算后才能取件。

**AI车衣共创（2026-10-14）**：`completed` 时直接带两张图的地址，不用再调“读取作品预览”：`uvUrl`（UV 贴图，Pad 做 360° 车模查看用；`assetId`/`uvAssetId` 为其作品编号）与 `paperUrl`（纸膜打印图，`paperAssetId`）。某张图地址取不到时对应 `uvUrlError`/`paperUrlError` 给出原因（如存储访问域名未配置）。

**厂商内容拒绝（2026-10-15）**：火山因版权或敏感内容拒绝出图（如用户要求画布丁狗等版权角色时返回 `OutputImageSensitiveContentDetected.PolicyViolation`）时，AI车衣共创生成与 DIY 改色任务按审核失败结案：`status:"failed"`、`failureKind:"moderation"`、`code:"CONTENT_REJECTED"`，`reason` 写明哪一步、哪种拒绝（如“审核未通过：图片厂商拒绝：生成的图片可能涉及版权或敏感内容（…）（纸膜）”），冻结全额冲正、不计生成次数。前端可提示“换个说法试试”。

**配置版本（2026-10-15）**：返回 `configVersion`（本次体验开始时所用的配置版本，整次体验都用它）与 `latestVersion`（当前最新已应用版本）；两者不同时另带 `configNote` 说明。后台发布新版本后，正在进行的体验仍用旧版本——要看新配置的效果，须重新[读取互动配置](#api-interaction-config)、[确认配置版本](#api-interaction-config-ack)并开始新的体验。

**DIY 确认打印的任务（2026-10-15）**也用本接口查询：`completed` 时 `paperUrl`/`paperAssetId` 为服务端合成的纸膜打印图（DIY 作品），`uvUrl`/`uvAssetId`（以及 `assetId`）为本次上传的手绘 UV（只作记录，不进作品列表、不能打印）。白色底不调模型、没有冻结，`billing` 为 `null`；其他颜色冻结一次图片调用，规则同上（改色图审核不通过 `failed` 并冲正；改色或合成失败 `failed` 并冲正，`reason` 写明原因；通信结果未知 `unknown` 保留冻结）。

```json
{ "taskId": "task_8c4d…", "status": "completed", "assetId": "asset_3f0a…", "uvAssetId": "asset_3f0a…", "paperAssetId": "asset_91bc…",
  "uvUrl": "https://cdn.example.com/generated/…/uv.jpeg", "paperUrl": "https://cdn.example.com/generated/…/paper.jpeg", "billing": { "status": "settled", "frozenAmount": 1200, "settlementAmount": 310 } }
```

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `taskId` | Path | string | 必填 | 创建图片任务返回的任务号 | `task_8c4d…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f1c/image-tasks/task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

成功：

```json
{
  "taskId": "task_8c4d1f02-6b3e-4a7d-9c15-3e2b0a9f7d64",
  "status": "completed",
  "assetId": "asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d",
  "reason": null,
  "moderation": { "verdict": "pass", "decision": "PASS" },
  "billing": { "status": "settled", "frozenAmount": 80, "settlementAmount": 20 },
  "note": "（说明文字，内容以实际返回为准）"
}
```

生成图审核未通过：

```json
{
  "taskId": "task_8c4d…",
  "status": "failed",
  "assetId": null,
  "reason": "内容审核未通过（审核失败）：BLOCK/…",
  "moderation": { "verdict": "rejected", "decision": "BLOCK" },
  "failureKind": "moderation",
  "code": "CONTENT_REJECTED",
  "billing": { "status": "reversed", "frozenAmount": 80, "settlementAmount": 0 },
  "note": "…"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | `prepared` / `dispatched` / `completed` / `failed` / `cancelled` / `unknown` |
| `assetId` | 作品编号；未保存作品时为 `null`。取件见 [读取本次体验作品预览](#api-work-preview) |
| `reason` | 失败、未知或待核对的说明；成功时为 `null` |
| `moderation` | 生成图审核结论 `{verdict, decision}`；`verdict` 为 `pass`/`rejected`，`decision` 为厂商结论（未登记内容安全或审核服务临时不可用而未送审时为 `SKIPPED`）；尚未审核时整个字段为 `null`。2026-10-13 之前暂存的结果可能出现 `unavailable`，同样按通过处理 |
| `failureKind` / `code` | 仅生成图审核未通过且任务 `failed` 时出现，固定为 `moderation` / `CONTENT_REJECTED` |
| `billing.status` | `frozen` / `settled` / `reversed` / `unknown` / `review` |
| `billing.frozenAmount` / `settlementAmount` | 冻结 Token 数；结算 Token 数（结算前为 `null`） |
| `note` | 说明文字，不用于程序判断 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话；任务号不存在或不属于该体验 | 检查任务号 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 完成助手名片
#### 功能描述

AIVA面基专用。把本次体验已审核通过的助手图片和已完成的介绍消息组合成电子名片并保存，体验状态变为 `generated`，之后可以聊天。名片内容（名称、介绍）由服务端从介绍消息读取，客户端不能自报；同时按五题计算主属性并读取后台为该属性登记的音色。

每次体验只能完成一张名片。同样的图片与介绍再次提交返回已保存的名片；换了图片或介绍返回 409。名片完成后，[当前助手](#api-my-assistant)即为这张新名片。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `avatarAssetId` | Body | string | 必填 | 本次图片任务返回的 `assetId`；须已审核通过、未到期 | `asset_3f0a…` |
| `introMessageId` | Body | string | 必填 | 本次 `purpose=intro` 文本任务返回的 `messageId`；须已完成 | `msg_5a0d…` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_6f1c/result/complete" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"avatarAssetId":"asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d","introMessageId":"msg_5a0d7e21-3c8b-4b1f-9e64-2f7a1c0d8e33"}'
```

#### 返回示例（HTTP 200）

```json
{
  "result": {
    "kind": "p02-electronic-card",
    "avatarAssetId": "asset_3f0a…",
    "introMessageId": "msg_5a0d…",
    "name": "星野",
    "description": "热爱探索的伙伴，喜欢在旅途中发现新奇的科技与风景。",
    "tags": ["explorer", "tech"],
    "scores": [{ "tag": "explorer", "count": 3 }, { "tag": "tech", "count": 2 }],
    "scoringRule": "p02-v2-q1-q4-q5-q2-q3",
    "voiceParams": { "voice": "后台登记的音色" },
    "configVersion": 7
  },
  "state": "generated",
  "note": "名片结构已保存。生成图片及介绍需由正式执行服务写入，客户端不能自报模型结果。"
}
```

同一请求再次提交时返回 `{"result":{…},"idempotentHit":true}`（不含 `state`、`note`）。

| 返回字段 | 说明 |
| --- | --- |
| `result.name` / `description` | 助手名称与介绍，来自介绍消息 |
| `result.tags` / `scores` / `scoringRule` | 五题得出的前两个属性、各属性票数与计分规则 |
| `result.voiceParams` | 主属性对应的后台登记音色参数 |
| `result.configVersion` | 本次体验使用的配置版本 |
| `state` | 完成后的体验状态，固定为 `generated` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前点位不是 AIVA面基；缺少 `avatarAssetId` 或 `introMessageId`；主属性未登记音色参数；请求体不是合法 JSON | 修正请求；音色未登记时联系运营 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话 | 检查 interactionId |
| 409 | 会员主账户已变更；本次已完成名片且提交的图片或介绍不同；状态不是 `ready`（未授权、未答完、有运行中任务）；授权已撤回；图片未保存、未审核通过、已到期或不属于该用户；介绍消息未完成或不符合名片格式 | 等任务完成后再提交；不要换图覆盖已完成名片 |
| 413 | 请求体超过 100 万字符 | 修正请求 |

### 读取本次体验作品
#### 功能描述

分页列出本次体验在当前门店产生的作品（生成图、AI音乐音频与封面等），按生成时间倒序。列表包含尚未审核通过的作品，客户端以 `audit_status` 判断能否取件。

#### 请求参数（Path / Query）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `limit` | Query | integer | 可选 | 每页条数 1—200，默认 50 | `20` |
| `offset` | Query | integer | 可选 | 跳过条数，≥0，默认 0 | `0` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f1c/works?limit=20&offset=0" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "items": [
    {
      "asset_id": "asset_3f0a…",
      "work_name": "AI图片生成_20261008101000",
      "agentos_uid": "au_3f9c…",
      "store_id": "CQ-GUANGHUAN",
      "point_id": "P08",
      "interaction_id": "ix_6f1c…",
      "asset_type": "image",
      "asset_subtype": "journey",
      "file_size": 1834211,
      "width": 1248,
      "height": 832,
      "duration_ms": null,
      "audit_status": "approved",
      "is_final": 0,
      "source_task_id": "task_8c4d…",
      "lifecycle_stage": "standard",
      "synced_to_mp_at": null,
      "mp_work_id": null,
      "created_at": "2026-10-08T02:10:00.000Z",
      "expire_at": "2027-01-06T02:10:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items[].asset_id` | 作品编号，用于预览与取件 |
| `items[].work_name` | 作品名称：`{点位名称}_{生成完成时间 yyyyMMddHHmmss 北京时间}`，提交 AIVA 小程序/APP 时使用；点位未填名称时为 `null`，2026-10-09 之前的作品为 `null` |
| `items[].asset_type` / `asset_subtype` | 类型：`image`、`audio`；子类：`avatar_config` 助手形象、`journey` 旅程图片、`car_wrap` 车衣、`music` 音乐、`cover` 音乐封面 |
| `items[].file_size` | 作品文件大小，单位字节（原文件） |
| `items[].width` / `height` | 图片宽高，单位像素；音频为 `null` |
| `items[].duration_ms` | 音频时长，单位毫秒，读音频文件实测（不是厂商返回值）；图片为 `null` |
| `items[].audit_status` | `approved` 可取件（含未登记内容安全或审核服务临时不可用时未送审、按通过处理的作品）；`pending` 待审核 |
| `items[].source_task_id` | 生成该作品的任务号 |
| `items[].lifecycle_stage` / `expire_at` | 留存阶段与到期时间；`deleted` 或已过期不可取件 |
| `total` | 符合条件的总条数 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `limit` 不在 1—200 或 `offset` 小于 0；interactionId 格式错误 | 修正分页参数 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话 | 检查 interactionId |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 读取本次体验作品预览
#### 功能描述

返回某个作品的读取地址。2026-10-13 起四个互动（AIVA面基、AI音乐、AI图片生成、AI车衣共创）的作品都以原文件（`.png`/`.jpg`/`.webp`/`.mp3`/`.wav`）保存在公开读的对象存储，返回 `https://` 公开地址，可以直接放进 `<img src>` 或 `<audio src>`。保护方式：对象名为随机编号、审核通过后才给出地址、删除作品即删除文件。

2026-10-13 之前保存、仍是加密存储的旧作品（运维用 `tools/convert-encrypted-works.js` 转换之前），仍返回需要带设备凭证和用户会话请求头的[取件地址](#api-work-content)（`requiresIdentityHeaders: true`），客户端要用带请求头的请求读取二进制后再显示（例如转成本地 Blob 地址）。客户端按 `requiresIdentityHeaders` 区分两种情况即可。

本接口只检查作品存在、已审核通过、未删除、已保存到当前存储。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `assetId` | Path | string | 必填 | 作品编号 | `asset_3f0a…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f1c/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/preview" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "assetId": "asset_3f0a…",
  "type": "image",
  "url": "https://<对象存储公开访问地址>/generated/…/3b9d….png",
  "accessNote": "平台采用公开读存储；链接期限不是访问控制边界。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `type` | `image` 或 `audio` |
| `url` | 作品的 `https://` 公开地址；仍是加密存储的旧作品为相对路径的取件地址（拼上 `$BASE` 使用） |
| `requiresIdentityHeaders` | 仅加密旧作品返回，值为 `true`，此时读取 `url` 必须带设备凭证与 `X-Identity-Session` |
| `accessNote` | 说明文字 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话；作品不存在或不属于本次体验、本门店 | 检查 assetId |
| 409 | 会员主账户已变更；作品未审核通过；尚未保存到平台存储；存储驱动或存储桶与当前配置不一致；对象存储公开访问地址（后台“对象存储 → 公开访问地址”）未配置 | 待审核时显示“作品审核中”；存储问题联系运维 |
| 410 | 作品已删除 | 显示作品已删除 |

### 读取本次体验作品内容
#### 功能描述

经 AgentOS 鉴权读取作品的原始内容（图片或音频二进制）。主要用于仍是加密存储的旧作品（预览接口返回 `requiresIdentityHeaders: true` 时）；2026-10-13 起的新作品直接用预览返回的公开地址即可，本接口也能读取。每次读取都重新核对：作品归属本次体验与当前用户、授权未撤回、审核已通过、原任务已结算、未删除、文件校验和一致。响应不缓存。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验的 interactionId | `ix_6f1c…` |
| `assetId` | Path | string | 必填 | 作品编号 | `asset_3f0a…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f1c/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/content" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -o work.bin
```

#### 返回示例（HTTP 200）

返回作品二进制内容，不是 JSON。

| 响应头 | 值 |
| --- | --- |
| `Content-Type` | 图片：`image/png` 或 `image/jpeg`；AI音乐音频：`audio/mpeg`、`audio/aac`、`audio/wav`、`audio/ogg`、`audio/flac`、`audio/mp4` 之一 |
| `Content-Length` | 内容字节数 |
| `Cache-Control` | `no-store` |
| `X-Content-Type-Options` | `nosniff` |

#### 错误情况

错误时返回 JSON `{"error":"说明"}`。

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录会话；作品不存在或不属于本次体验、本门店、当前用户 | 检查 assetId |
| 409 | 会员主账户已变更；作品未审核通过；原任务尚未结算（含待核对）；存储配置与原对象不一致；作品大小限制未配置；文件校验和不一致；作品仍是旧版数据库加密存储、尚未转换 | 待审核或待结算时显示“作品处理中”；其余联系运维 |
| 410 | 作品已删除或存储格式无法读取；本次体验授权已撤回 | 显示作品不可用 |
| 502 | 从存储读取失败；作品超过大小限制 | 显示读取失败，可稍后再读 |

### 读取我的作品
#### 功能描述

分页列出当前登录用户在本租户所有门店、所有点位的作品，按生成时间倒序。已绑定 ONEID 时包含该会员全部关联账户的作品，每条保留原账户（`agentos_uid`）与门店。只能读自己的作品，不能自报用户编号。列表包含尚未审核通过的作品。

#### 请求参数（Query）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `limit` | Query | integer | 可选 | 每页条数 1—200，默认 50 | `20` |
| `offset` | Query | integer | 可选 | 跳过条数，≥0，默认 0 | `0` |

#### 请求示例

```bash
curl "$BASE/api/users/me/works?limit=20&offset=0" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "items": [
    {
      "asset_id": "asset_3f0a…",
      "work_name": "AI图片生成_20261008101000",
      "agentos_uid": "au_3f9c…",
      "store_id": "CQ-GUANGHUAN",
      "point_id": "P02",
      "interaction_id": "ix_2d9a…",
      "asset_type": "image",
      "asset_subtype": "avatar_config",
      "file_size": 2410566,
      "width": 1344,
      "height": 1792,
      "duration_ms": null,
      "audit_status": "approved",
      "is_final": 0,
      "source_task_id": "task_1e7c…",
      "lifecycle_stage": "standard",
      "synced_to_mp_at": null,
      "mp_work_id": null,
      "created_at": "2026-10-06T08:00:00.000Z",
      "expire_at": "2027-01-04T08:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items` | 字段含义同 [读取本次体验作品](#api-works-list) |
| `items[].agentos_uid` / `store_id` | 作品原属账户与门店 |
| `total` | 总条数 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `limit` 不在 1—200 或 `offset` 小于 0 | 修正分页参数 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 当前用户不存在 | 回到扫码登录 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 读取我的作品预览
#### 功能描述

与 [读取本次体验作品预览](#api-work-preview) 相同，但按当前用户（含 ONEID 关联账户）跨门店查找作品，不限定体验。新作品返回 `https://` 公开地址；仍是加密存储的旧作品返回的取件地址是 [读取我的作品内容](#api-my-work-content)。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `assetId` | Path | string | 必填 | 作品编号 | `asset_3f0a…` |

#### 请求示例

```bash
curl "$BASE/api/users/me/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/preview" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "assetId": "asset_3f0a…",
  "type": "image",
  "url": "https://<对象存储公开访问地址>/generated/…/3b9d….png",
  "accessNote": "平台采用公开读存储；链接期限不是访问控制边界。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `url` | 作品的 `https://` 公开地址；仍是加密存储的旧作品为相对路径取件地址 |
| `requiresIdentityHeaders` | 仅加密旧作品返回，值为 `true`，此时读取须带设备凭证与 `X-Identity-Session` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 当前用户不存在；作品不存在或不属于当前用户 | 检查 assetId |
| 409 | 会员主账户已变更；作品未审核通过；尚未保存到平台存储；存储驱动或存储桶不一致；对象存储公开访问地址未配置 | 待审核时显示“作品审核中” |
| 410 | 作品已删除 | 显示作品已删除 |

### 读取我的作品内容
#### 功能描述

与 [读取本次体验作品内容](#api-work-content) 相同的核对与返回，但按当前用户（含 ONEID 关联账户）跨门店查找作品，不限定体验。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `assetId` | Path | string | 必填 | 作品编号 | `asset_3f0a…` |

#### 请求示例

```bash
curl "$BASE/api/users/me/works/asset_3f0a9c1e7b2d4c6a8e0f1a2b3c4d5e6f7a8b9c0d/content" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -o work.bin
```

#### 返回示例（HTTP 200）

返回作品二进制内容，不是 JSON。

| 响应头 | 值 |
| --- | --- |
| `Content-Type` | `image/png`、`image/jpeg`，或 AI音乐音频类型（同 [读取本次体验作品内容](#api-work-content)） |
| `Content-Length` | 内容字节数 |
| `Cache-Control` | `no-store` |
| `X-Content-Type-Options` | `nosniff` |

#### 错误情况

错误时返回 JSON `{"error":"说明"}`。

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 当前用户不存在；作品不存在或不属于当前用户 | 检查 assetId |
| 409 | 会员主账户已变更；作品未审核通过；原任务尚未结算；存储配置不一致；作品大小限制未配置；文件校验和不一致；作品仍是旧版数据库加密存储、尚未转换 | 待审核或待结算时显示“作品处理中” |
| 410 | 作品已删除或存储格式无法读取；该作品所在体验的授权已撤回 | 显示作品不可用 |
| 502 | 从存储读取失败；作品超过大小限制 | 显示读取失败，可稍后再读 |

### 当前助手
#### 功能描述

返回当前用户的个人助手：本人及同一 ONEID 关联账户**最新完成**的 AIVA面基名片。历史名片保留；重新回答生成新名片后自动成为当前助手。从未完成过名片时返回 `assistant:null`。最新名片已被清理、授权已撤回或助手图片失效时直接报错，不改用更早的名片或默认形象。任何互动点位都可调用。

助手图片用 `assistant.avatarAssetId` 通过 [读取我的作品预览](#api-my-work-preview) 取件。

#### 请求参数

无。只需请求头中的设备凭证与 `X-Identity-Session`。

#### 请求示例

```bash
curl "$BASE/api/users/me/assistant" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "assistant": {
    "kind": "p02-electronic-card",
    "avatarAssetId": "asset_3f0a…",
    "introMessageId": "msg_5a0d…",
    "name": "星野",
    "description": "热爱探索的伙伴，喜欢在旅途中发现新奇的科技与风景。",
    "tags": ["explorer", "tech"],
    "scores": [{ "tag": "explorer", "count": 3 }, { "tag": "tech", "count": 2 }],
    "scoringRule": "p02-v2-q1-q4-q5-q2-q3",
    "voiceParams": { "voice": "后台登记的音色" },
    "configVersion": 7,
    "interactionId": "ix_2d9a…",
    "sourceAccountId": "au_3f9c…",
    "createdAt": "2026-10-06T08:05:00.000Z"
  },
  "scope": "tenant-user",
  "note": "当前助手取本人及同一ONEID关联账户最新完成的名片；历史名片保留，重新回答生成新名片后自动成为当前助手。"
}
```

从未完成名片时只返回 `{"assistant":null}`。

| 返回字段 | 说明 |
| --- | --- |
| `assistant` | 名片内容，字段同 [完成助手名片](#api-result-complete) 的 `result`；无名片时为 `null` |
| `assistant.interactionId` | 生成该名片的体验 |
| `assistant.sourceAccountId` | 名片原属账户（可能是同一会员的另一张卡） |
| `assistant.createdAt` | 名片完成时间 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 当前用户不存在 | 回到扫码登录 |
| 409 | 会员主账户已变更；最新名片的助手图片已失效、授权已撤回或未审核通过 | 提示助手不可用，可引导用户到 AIVA面基重新生成；不要显示默认形象 |
| 410 | 最新名片内容已按留存策略清理 | 同上 |

### 内容安全（2026-10-06确认，A20）

接入火山引擎内容安全。审核范围：**用户输入文字**（发给模型前）、**用户拍照**（作为生图输入前）、**生成图片**（保存为作品前）；模型生成的文字本期不审。火山返回 BLOCK 与 REVIEW 一律按“审核失败”处理。

**2026-10-13 起（用户确认，取代原“未配置或服务不可用直接报错 503、不放行”）**：后台未登记内容安全（审核接入点、AppId、文本或图片 biztype、凭证、超时、图片审核临时链接有效期任一未登记，或存储不是 TOS），或审核服务临时不可用（通信中断、超时、返回异常）时，用户文字、用户拍照、生成图片都**不送审、按通过处理**：请求照常继续，生成的作品当作已通过（可显示、打印、同步 AIVA 小程序），后台标记为“未审核”（`audit_provider=moderation_skipped`，原因 `not_configured` 未登记 / `unavailable` 服务不可用）。登记内容安全后由内容安全做基础审核。客户端因此不会再收到 `MODERATION_NOT_CONFIGURED` / `MODERATION_UNAVAILABLE`。**注意：正式运营前若未登记内容安全，所有用户内容都未经审核。**

音频作品（AI音乐）不在内容安全审核范围。

> **调试开关（2026-10-11）**：内容安全未开通期间，平台管理员可在后台“安全策略”打开“跳过内容安全审核（调试）”（全平台，手动关闭为止）。打开期间即使已登记内容安全也不送审，不会出现 `CONTENT_REJECTED`：文字、拍照、生成图都按通过处理，作品照常可显示、打印与同步，后台标记为“未审核（调试期跳过）”。客户端不需要为此改代码，但仍须按下表处理审核未通过。

审核相关错误在 `{"error"}` 之外带稳定字段 `code`（审核失败另带 `failureKind:"moderation"`），客户端按 HTTP 状态 + `code` 分支，不匹配中文文案：

| HTTP / code | 含义 | 客户端处理 |
| --- | --- | --- |
| 422 `CONTENT_REJECTED`（failureKind=moderation） | 用户输入文字或照片审核未通过（BLOCK/REVIEW） | 显示“审核未通过”失败态，请用户修改内容后再提交；本次未建任务、未冻结、未写入 |

| 互动 | 入口（审核对象） | 审核时机与失败结果 |
| --- | --- | --- |
| AIVA面基 | [创建文本任务](#api-text-task-create)，purpose=chat 的 text | 建任务、冻结前；422 不建任务 |
| AI图片生成 | [创建文本任务](#api-text-task-create)，purpose=guide 的 text（选项不审） | 同上 |
| AI车衣共创 | [创建文本任务](#api-text-task-create)，purpose=style 的 text | 同上 |
| AIVA面基 / AI图片生成 / AI音乐 | [提交答案](#api-interaction-answers) 中 allowText 题的每条 text | 写入答案前；422 不写入；已提交答案的重放不再审 |
| AI音乐 | PUT lyrics 手动修订的 title + lyrics（确认后会发给音乐模型） | 写入修订前；422 不写入 |
| AIVA面基 / AI图片生成 | [创建图片任务](#api-image-task-create) 的 photo | 建任务、冻结前；照片以临时对象 + 短时签名链接提交火山，审核结束立即删除，不保存为作品 |
| AIVA面基 / AI图片生成 / AI车衣共创 | 生成图片 | 保存为作品前，结论见 [查询图片任务](#api-image-task-get) |
| AI音乐 | 正式封面图 | 保存为封面作品前，见 [AI音乐](#p03)“封面” |
| AI音乐（旧链路） | `/api/p03/chat/:id`、`/api/p03/story/:id` 的 text（及客户端提交的歌名/感觉词；只点选目录歌手/主题不审） | 调用对话模型前；422 不调用模型、不计轮次 |
| AI音乐（旧链路） | `/api/p03/generate` 的 story | 任务内调用任何模型前；审核未通过时 job.state=failed，errorCode=`CONTENT_REJECTED`（error 以“审核未通过”开头） |

生成图片在未登记内容安全或审核服务临时不可用时：按通过处理，任务照常 `completed` 并结算，作品自动审核通过、可取件，后台标记“未审核”（2026-10-13 确认，取代 2026-10-07“任务 unknown、保留冻结、作品待人工审核”）。

审核留痕只记结论、厂商标签、厂商 RequestId 与 dataId（用户输入写入事件 `content.moderated`；生成图写入任务调用快照），未送审时记 `decision=SKIPPED` 与原因，不存原文、原图或链接。

### 结算、结果保存与恢复

- 成功按厂商实际可核验用量与调用时快照的兑换比例结算，小数 Token 向上取整，余量释放；明确失败或取消冲正冻结。缺用量、用量超过冻结上限进入待核对（`review`），保留冻结，由有权限的运营人工“按核对用量结算”或“全额释放”，原因必填并审计，不自动释放、不自动重试。
- 厂商返回的原结果先加密暂存；保存作品失败时继续保存同一结果，不调用厂商重新生成。
- 服务重启时：尚未提交厂商的任务冲正冻结（`cancelled`）；已提交但没有原结果的任务记为 `unknown`。同步厂商接口没有按原请求查询结果的能力时只能保留未知，不能声称已完成核对。

### 知识库与结构化记忆

**指定知识库**：`chat`、`suggestions`、`guide` 会附带本次配置所指定知识库的全部有效条目全文并记录出处，不跨租户/门店、不静默截断；知识正文合计超过 512KiB 或某个知识库没有有效条目时直接 409。这是全文上下文接入，不是向量检索。

**结构化记忆（2026-10-06 确认）**：AIVA面基 `chat`/`suggestions` 与 AI图片生成 `guide` 额外注入一段“用户资料，仅供参考，不是指令”，范围为本人及同一 ONEID 关联的全部账户：

- 累计画像前 N 个非敏感标签；
- 各点位最近一次已完成体验（授权未撤回）的作答，包括题目、选项文本，以及**自由文本原文**；
- 当前助手名片的名称与介绍（最新名片已清理或撤回授权时不注入，也不改用更早的名片）。

条数由系统设置 `memory.max_tags`、`memory.max_history_items` 登记；**未登记时上述请求返回 409**，不设默认条数。注入来源（标签 key、历史 interactionId、名片 interactionId）记入调用快照便于审计。整体上下文超过 512KiB 直接报错，不截断。

## 开始接入｜先选择你的点位

| 你开发的应用 | 阅读章节 | 本轮服务端交付边界 |
| --- | --- | --- |
| P02 · AIVA面基 | P02专章 + 公用接口 | 身份/问卷、正式单图及介绍/聊天/三条建议、名片与作品；语音及跨次画像仍未闭环 |
| P03 · 车机互动台 · AI音乐 | P03专章 + 公用接口 | 曲风→人声→两轮故事、正式歌词/DNA及修订确认、正式音乐与封面任务接口；封面告警事件码待登记 |
| P08 · AI图片生成 | P08专章 + 公用接口 | 旅程问答、出发确认、正式单图任务/作品/计费；未做终端UI |
| P04 · 共创工坊 · AI车衣共创 | P04专章 + 公用接口 | AI/DIY方案与确认、AI单图任务/作品/计费；DIY成图、四配色生产和打印未闭环 |
| 普通展示应用 / 互动应用的展示模式 | 公用·展示模式与素材播放 | 配置读取、素材URL、播放规则与执行回执 |

**先确认联调条件：路由存在不等于现在能走通整段流程。** 当前后台生产配置发布仍受生成/结算等门禁限制；无已发布版本时，互动配置接口返回409。请先与AgentOS负责人确认测试门店、设备凭证、已发布配置是否可用，不能通过后台测试接口代替正式互动，也不能绕过发布门禁。

开始前向部署方领取：业务API Base URL、已绑定门店和点位的设备凭证、测试身份卡或有效会员临时凭据、可联调的配置版本。文档网站 `http://aiva.docs.vavedigital.com` **只是文档站，不是业务API地址**。

点位由设备凭证确定。P02和P08可以使用相同URL，但必须使用各自设备凭证；请求Body不能传pointId来切换点位。

后台配置、模型密钥、素材上传审核由AgentOS运营后台负责；客户端只读取下发内容。AIVA会员认证（AIVA 会员码由 AgentOS 服务端调 AIVA 识别）、作品同步到 AIVA 和集团全量数据同步由可信服务端负责；点位客户端不调用这些接口，AIVA服务端接口见《ONEID 会员对外接口文档》（api-docs/oneid.html）。

## P02｜AIVA面基

AIVA面基（P02）：访客扫码登录、授权拍照、作答5道单选题，服务端据此生成专属助手形象（单张图片）和一段介绍，组成“助手名片”；名片完成后可以文字或语音与助手聊天，助手回复可语音播报。本章先给出页面调用顺序，再说明AIVA面基特有的下发内容、作答格式和名片规则，最后是本章独有的语音接口（语音接口同样供AI图片生成使用）。授权、作答、文本/图片任务等公用接口的字段与错误见各自接口卡片。

### 页面操作与调用顺序

U 表示设备凭证 + 用户会话（`X-Identity-Session`），D 表示只用设备凭证。

| 步骤 | 页面 / 用户操作 | 调用 | 客户端处理 |
| --- | --- | --- | --- |
| 1 | 程序启动 | [读取互动配置](#api-interaction-config)，D | 校验 `pointId` 为 P02；按 `questions` 渲染5道题；保留 `version`、`policy` |
| 2 | 配置应用成功 | [确认配置版本](#api-interaction-config-ack)，D | Body `{version}`；成功后才能用该版本开始体验 |
| 3 | 扫身份码 | [扫码登录](#api-point-login)，D | 保留 `sessionToken`，之后请求都带上 |
| 4 | 开始体验 | [开始体验](#api-interaction-create)，U | Body `{requestId,version}`；保留 `interactionId` |
| 5 | 用户同意 / 拒绝授权 | [确认授权](#api-interaction-consent)，U | 拒绝后本次体验即结束 |
| 6 | 完成全部5题 | [提交作答](#api-interaction-answers)，U | 格式见下方“五题作答格式”；返回本次主属性标签 |
| 7 | （可选）用户确认进入生成 | [确认输入](#api-interaction-confirm)，U | 只登记确认时间，不创建任何生成任务；AIVA面基的生成不要求先调用此接口 |
| 8 | 拍照后生成助手形象 | [创建图片任务](#api-image-task-create)，U | Body `{requestId,photo}`，`photo` 为 PNG/JPEG data URL（≤5MiB）；照片随任务提交，没有单独的照片上传接口 |
| 9 | 等待形象 | [查询图片任务](#api-image-task-get)，U | 用原 `taskId` 轮询到 `completed`，取 `assetId` |
| 10 | 生成介绍 | [创建文本任务](#api-text-task-create)，U | `purpose:"intro"`；须在问卷完成且没有正在运行的任务时调用（与第8步不能同时进行） |
| 11 | 等待介绍 | [查询文本任务](#api-text-task-get)，U | 取 `messageId` 与 `response`（介绍为 `{name,description}` 结构） |
| 12 | 名片完成 | [完成名片](#api-result-complete)，U | Body `{avatarAssetId,introMessageId}`；成功后体验进入 `generated` |
| 13 | 播报介绍 | [语音合成](#api-tts)，U | Body `{requestId,messageId}`，`messageId` 为第11步的介绍消息 |
| 14 | 聊天（文字） | [创建文本任务](#api-text-task-create)，U | `purpose:"chat"` + `text`；`purpose:"suggestions"` 取三条建议问题 |
| 15 | 聊天（语音输入） | [语音识别握手凭据](#api-asr-ticket) → [流式语音识别](#api-asr-ws)，U | 识别出的 `final.text` 由客户端作为第14步的 `text` 提交 |
| 16 | 播报聊天回复 | [语音合成](#api-tts)，U | `messageId` 为已完成的聊天回复 |
| 17 | 查看当前助手 / 作品 | [我的当前助手](#api-my-assistant)、[本次体验作品](#api-works-list)，U | 当前助手取本人及同一ONEID关联账户最新完成的名片 |
| 18 | 聊天页点循环箭头“重新回答” | [重新回答](#api-interaction-restart)，U | 返回新的 `interactionId`，从第5步起重新走一遍 |
| 19 | 结束 / 撤回授权 / 退出 | [结束体验](#api-interaction-end)、[撤回授权](#api-interaction-consent-revoke)、[退出登录](#api-identity-logout) | 结束体验和退出登录是两个操作，按需分别调用 |
| — | 恢复页面状态 | [查询体验](#api-interaction-get)，U | 读取 `state`、`answers`、`messages`；正式任务结果另查原 `taskId` |

### AIVA面基下发内容

公共配置字段见[读取互动配置](#api-interaction-config)。AIVA面基的配置有以下特点：

| 字段 | 内容 | 用法 |
| --- | --- | --- |
| `questions` | 固定5道单选题；每题 `{id,title,allowText:false,options:[{id,label,detail}]}` | 题目文字、选项由后台配置，客户端不写死；不下发选项对应的属性标签 |
| `opening` / `suggestions` | 后台登记的开场白与建议说明文本 | 按设计稿展示 |
| `policy` | 本次使用的授权策略（人像类） | 授权时原样提交 `policyId`、`policyVersion` |
| `stages` | `consent, photo, questions, generation, chat` | 表示流程设计阶段，不是接口清单 |

后台发布配置时校验：必须正好5道单选题、每个选项只映射1个属性、每个属性都在“属性音色映射”中登记了音色（播报用）。助手为静态图片；聊天中的循环箭头是“重新回答”，不是重播。

### 五题作答格式

提交到[提交作答](#api-interaction-answers)的Body：5道题各提交一个 `optionId`，ID 全部取自本次配置；AIVA面基不接受自由文本（`text`），也不接受客户端提交标签或权重。

```json
{"answers":[
  {"questionId":"q1","optionId":"q1_a"},
  {"questionId":"q2","optionId":"q2_c"},
  {"questionId":"q3","optionId":"q3_b"},
  {"questionId":"q4","optionId":"q4_a"},
  {"questionId":"q5","optionId":"q5_d"}
]}
```

成功返回（HTTP 200）：

```json
{"state":"ready","tags":["attr_curious","attr_calm"],"scores":[{"tag":"attr_curious","count":2},{"tag":"attr_calm","count":2},{"tag":"attr_bold","count":1}],"scoringRule":"p02-v2-q1-q4-q5-q2-q3"}
```

| 返回字段 | 说明 |
| --- | --- |
| `tags` | 本次得票最多的两个属性：每题一票；票数相同时按第1、4、5、2、3题的先后决定。第一个为“主属性”，决定播报音色 |
| `scores` | 每个属性的得票数 |
| `scoringRule` | 计分规则编号 |

- 五题选出的属性少于两个时返回400，请运营核对题目映射；服务端不会补造第二个属性。
- 同一份答案原样重发返回第一次的结果并带 `idempotentHit:true`；已提交后改答案返回409，不能覆盖原作答。
- 每次作答的属性贡献全部累计进该用户的共享画像（重复作答累加），客户端无需另行提交。

### 名片与重新回答（2026-10-06确认）

- 名片按“体验”保存：一次体验只生成一张名片。名片完成后，同一体验内不能再生成形象，也不能改答案（409）。
- 用户点“重新回答”调用[重新回答](#api-interaction-restart)：只在本次名片已完成（`state` 为 `generated` 或 `chat`）时可用；名片未完成时应调用[结束体验](#api-interaction-end)；有模型任务正在运行或待核对时返回409。
- 重新回答会在同一事务内结束原体验（结束原因 `user_restart`）并新开一次体验。新体验需重新授权、拍照、作答五题、生成形象和介绍并完成名片，每次模型调用正常计费。
- 原体验的作答、属性贡献和名片都保留；新名片完成后，[我的当前助手](#api-my-assistant)返回新名片。

### 正式语音（AIVA面基与AI图片生成共用，2026-10-06）

以下接口（语音合成、查询语音任务、语音识别握手凭据、流式语音识别、上传录音识别）供AIVA面基、AI图片生成与AI车衣共创的设备使用。AI车衣共创：语音识别（流式或 2026-10-14 新增的[上传录音识别](#api-asr-upload)）用于自由描述；语音合成 2026-10-20 开通，2026-10-22 起可直接传一段文字合成（见[语音合成](#api-tts)）。语音识别用哪种方式由点位配置里选的识别模型决定。其他点位调用返回400/403。AI图片生成的差异见P08章节。

| 前提 | 说明 |
| --- | --- |
| 单次上限 | 系统设置须登记 `voice.tts_max_chars`（单次合成最多字符数）与 `voice.asr_max_sec`（单次识别最长秒数）；未登记返回409 `VOICE_CONFIG_INCOMPLETE`，不使用默认值 |
| 模型与计费 | 本次配置须绑定语音合成（tts）/语音识别（asr）模型，并登记该模型的单次冻结上限与兑换比例（合成按字符 character、识别按秒 second）；缺任一项拒绝调用 |
| 体验状态 | 已授权且授权未撤回、体验未结束、点位处于互动模式 |
| 音色（AIVA面基） | 按本次五题的主属性（`tags` 第一个）取后台“属性音色映射”中的 `voice` 参数；未配置返回409 `VOICE_NOT_CONFIGURED`，不改用其他音色 |
| 可播报内容（AIVA面基） | 本次体验中已完成的介绍（播报名片中的 `description`）和聊天回复；三条建议问题不播报 |
| 语音识别时机（AIVA面基） | 只在名片完成后（聊天阶段）可用；五题只能点击作答 |

计费规则：调用前按单次上限冻结 Token；成功后按实际用量结算、多余部分释放；厂商明确失败则冲正冻结；通信中断、超时或结果无法确认时记为“结果未知”，冻结保留，由运营人工核对后结算或释放，服务端不自动重试。用量折算出现小数 Token 时向上取整。

### 语音合成
#### 功能描述

把本次体验中一条已完成的助手消息合成为语音，同步返回音频（base64）。文字取自服务端已保存的消息，客户端只传消息编号。AIVA面基可播报介绍（`intro`，播报其中的 `description`）和聊天回复（`chat`）；AI图片生成可播报旅程引导回复（`guide`）；AI车衣共创可播报风格对话回复（`style`，2026-10-20 开通）——播的是返回里的 `style_reply` 那一句，不会把风格名和配色念出来（2026-10-22 起模型输出不符合约定时风格对话直接失败，没有可播的回复）。

**AI车衣共创可直接传一段文字（2026-10-22 用户确认，共创工坊提出）**：Body 传 `text` 代替 `messageId`（二选一），前端传什么就念什么，例如页面引导语或前端自己拼的句子。规则：
- 只开给AI车衣共创；AIVA面基、AI图片生成传 `text` 仍返回 400。
- 这段文字**不送内容安全审核**（用户确认），由前端对传入内容负责；服务端只保存文字摘要（哈希），不保存原文。
- 其余与播报消息相同：须在已授权、未结束的体验中调用；去掉首尾空白后的字数不能超过 `voice.tts_max_chars`（超过返回 409 `VOICE_TEXT_TOO_LONG`，不截断）；按字数计费；音色取车衣配置里登记的 `voice.params.voice`；同一 `requestId` 重发返回缓存音频、不重复计费，同一 `requestId` 换了文字返回 409。
- 只想播风格对话的回复时，直接在风格对话请求里带 `speak:true` 更省事（一次调用拿到文字和语音）。

计费：调用前按模型单次上限冻结；超过 `voice.tts_max_chars` 直接拒绝（不截断、不分段）。成功后按本次提交合成的字符数（去掉首尾空白后的字符数）结算；厂商若返回计费字符数则以厂商为准（当前火山接口不返回，`billedCharacters` 恒为 `null`）。

缓存与重发（2026-10-07确认）：合成成功的音频加密缓存到本次体验结束。同一个 `requestId` 原样重发不会再次调用厂商、不再计费，返回第一次的结果和缓存的音频（`idempotentHit:true`）。体验结束（完成、放弃、撤回授权）后重发只返回任务状态，`audio` 为 `null`；需要再播放须换新的 `requestId` 重新合成并计费。缓存由定时任务删除。

调用时机：介绍或聊天回复的文本任务查询到 `completed` 之后。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_6f2c…` |
| `requestId` | Body | string | 必填 | 本次合成请求号，1—64 字符；每次新的播报用新请求号，网络失败时用同一个请求号重发 | `tts-intro-001` |
| `messageId` | Body | string | 二选一 | 要播报的助手消息编号，取自[查询文本任务](#api-text-task-get)返回的 `messageId`，最长 64 字符。AIVA面基、AI图片生成必填 | `msg_9a1d…` |
| `text` | Body | string | 二选一 | **仅AI车衣共创（2026-10-22）**：要念的文字，去掉首尾空白后不能为空、字数不超过 `voice.tts_max_chars`；可以有换行，不能有其他控制字符。与 `messageId` 只能传一个 | `请说出你想要的车衣风格` |

AIVA面基、AI图片生成的 Body 只允许 `requestId`、`messageId`，带其他字段（包括 `text`）返回400；AI车衣共创只允许 `requestId` 加 `messageId`、`text` 其中一个。传 `text` 时响应里的 `messageId` 为 `null`，其余字段相同。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_6f2c/tts" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"tts-intro-001","messageId":"msg_9a1d"}'
```

AI车衣共创直接传文字：

```bash
curl -X POST "$BASE/api/interactions/ix_6f2c/tts" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"tts-wrap-guide-001","text":"请说出你想要的车衣风格"}'
```

#### 返回示例（HTTP 200）

首次合成成功：

```json
{
  "replayCached": true,
  "taskId": "task_0b7e…",
  "status": "completed",
  "messageId": "msg_9a1d",
  "usage": { "characters": 38, "billedCharacters": null },
  "billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": null },
  "audio": { "base64": "SUQzBAAAAAAA…", "mimeType": "audio/mpeg", "durationMs": 5120 },
  "reason": null,
  "note": "音频加密缓存至本次体验结束，同一requestId重放不再计费；体验结束后删除。结果未知时保留冻结待人工核对，不自动重试。"
}
```

同一 `requestId` 重发（体验未结束、缓存可用）：

```json
{
  "taskId": "task_0b7e…",
  "kind": "tts",
  "status": "completed",
  "messageId": "msg_9a1d",
  "usage": { "characters": 38, "billedCharacters": null },
  "providerRequestId": "3c1f…",
  "failureKind": null,
  "reason": null,
  "billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": "success" },
  "idempotentHit": true,
  "audio": { "base64": "SUQzBAAAAAAA…", "mimeType": "audio/mpeg", "durationMs": 5120 },
  "note": "本次体验内缓存的同一合成结果，重放不再计费（用户2026-10-07确认）。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | `completed` 成功；`failed` 厂商明确拒绝，冻结已冲正；`unknown` 结果无法确认（通信中断、超时、响应异常，或合成期间体验已结束），冻结保留待运营核对，不下发音频 |
| `audio` | 成功时为 `{base64,mimeType,durationMs}`：`mimeType` 为 `audio/mpeg` 或 `audio/wav`（取决于后台登记的编码），`durationMs` 厂商未返回时为 `null`；其他情况为 `null` |
| `usage.characters` / `usage.billedCharacters` | 本次提交合成的字符数 / 厂商计费字符数（当前恒为 `null`） |
| `billing` | `status`：`settled` 已结算、`reversed` 已冲正、`unknown` 结果未知保留冻结、`review` 待人工核对（如真实用量费用超过冻结上限，此时 `status` 仍为 `completed` 并下发音频）；`frozenAmount` 冻结 Token；`settlementAmount` 实际扣除 Token |
| `replayCached` | 仅首次响应有：音频缓存是否写入成功；为 `false` 时本次音频照常可用，但之后重发拿不到音频 |
| `idempotentHit` | 仅重发响应有，恒为 `true`；重发响应另带 `kind`、`providerRequestId`、`failureKind`，不带 `replayCached` |
| `reason` | 失败、未知或待核对的原因说明 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | Body 不是对象或带了不允许的字段；`requestId`/`messageId` 为空、超过64字符或含控制字符；AI车衣共创 `messageId` 和 `text` 都没传或都传了、`text` 为空或含控制字符；当前设备不是AIVA面基/AI图片生成/AI车衣共创；该消息类型不能播报（如建议问题） | 修正请求 |
| 401 | 设备凭证无效；缺少用户会话、会话已过期或已退出；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已在后台停用；纯展示点位的设备调用 | 联系运维检查设备 |
| 404 | 体验不存在或不属于当前设备与登录用户；消息不存在或不属于本次体验 | 核对 `interactionId`、`messageId` |
| 409 | 会员主账户已变更；体验已结束；未授权或授权已撤回；消息尚未完成；介绍消息不符合名片格式；同一 `requestId` 已用于另一条消息；`code` 为 `VOICE_CONFIG_INCOMPLETE`（字符上限、模型或接入点未登记）、`VOICE_NOT_CONFIGURED`（音色未登记）、`VOICE_TEXT_TOO_LONG`（超过单次字符上限）、`VOICE_OVER_FREEZE_LIMIT`（按比例费用超过冻结上限；模型未计费时不检查）、`VOICE_REQUEST_REUSED`（同一请求号正被并发处理） | 按 `code` 分支：配置类提示联系运营；`VOICE_REQUEST_REUSED` 改为[查询语音任务](#api-voice-task-get)；其他按页面状态处理，不自动换请求号重试 |
| 409 | 余额不足以冻结单次上限：可冻结的 Token 不足（409，`code:"TOKEN_INSUFFICIENT"`，2026-10-08 修复，原为 500） | 本次未建任务、未冻结；提示 Token 不足，不伪造播报 |
| 500 / 503 | 模型或平台账号已停用；其他服务端错误 | 本次未建任务、未冻结；显示暂不可用，不伪造播报 |

### 查询语音任务
#### 功能描述

查询一次语音合成或语音识别任务的状态、用量与计费，用于网络中断后确认结果、或核对计费。服务端不保存音频和识别原文，此接口的 `audio` 恒为 `null`；需要音频请用原 `requestId` 重发[语音合成](#api-tts)（体验未结束时可取回缓存音频）。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_6f2c…` |
| `taskId` | Path | string | 必填 | 语音合成响应或语音识别 `ready` 消息中的 `taskId`，最长 64 字符 | `task_0b7e…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_6f2c/voice-tasks/task_0b7e" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

语音合成任务：

```json
{
  "taskId": "task_0b7e…",
  "kind": "tts",
  "status": "completed",
  "messageId": "msg_9a1d",
  "usage": { "characters": 38, "billedCharacters": null },
  "providerRequestId": "3c1f…",
  "failureKind": null,
  "reason": null,
  "billing": { "status": "settled", "frozenAmount": 50, "settlementAmount": 4, "reason": "success" },
  "audio": null,
  "note": "语音任务不保存音频与识别原文，只提供状态、用量与计费。"
}
```

语音识别任务的 `kind` 为 `asr`、`messageId` 为 `null`、`usage` 为 `{ "audioSeconds": 6.4 }`（厂商未返回时长时为 `null`）。

| 返回字段 | 说明 |
| --- | --- |
| `kind` | `tts` 语音合成 / `asr` 语音识别 |
| `status` | `prepared` 已冻结未发出、`dispatched` 进行中、`completed` 成功、`failed` 明确失败、`cancelled` 未提交即取消（冲正）、`unknown` 结果未知（冻结保留） |
| `usage` | 合成：`{characters,billedCharacters}`；识别：`{audioSeconds}` |
| `failureKind` | 失败或中断的类别：`vendor` 厂商拒绝、`transport` 通信异常、`client` 客户端断开或会话失效、`config` 配置问题；无则 `null` |
| `billing` | `status` 为 `frozen`/`settled`/`reversed`/`unknown`/`review`；结算后 `reason` 记为结算结果（如 `success`），待核对时为原因说明 |
| `providerRequestId` | 厂商请求编号，供运营核对 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `interactionId` 或 `taskId` 为空、超过64字符或含控制字符 | 修正路径 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不属于当前设备与登录用户；语音任务不存在或不属于本次体验 | 核对 `taskId` |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 语音识别握手凭据
#### 功能描述

浏览器建立 WebSocket 时不能附带 `Authorization` 与 `X-Identity-Session` 请求头，因此先用正常请求头调用本接口，换取一张一次性握手凭据，再把它放在[流式语音识别](#api-asr-ws)地址的 `ticket` 参数里。凭据只对本次体验和本台设备有效，60秒内有效，用一次即作废（握手失败也算用过）。非浏览器客户端可以不用凭据，直接带请求头升级。

本接口只核对设备、会话和体验归属；授权状态、名片是否完成、上限与模型登记等在握手时才检查。凭据保存在服务端内存中，服务重启后失效。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_6f2c…` |
| Body | Body | object | 可选 | 不读取 Body，发送空对象 `{}` 即可 | `{}` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_6f2c/asr-ticket" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{
  "ticket": "9f4c2b…（64位十六进制）",
  "expiresAt": "2026-10-08T10:01:00.000+08:00",
  "singleUse": true,
  "path": "/api/interactions/ix_6f2c/asr"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `ticket` | 一次性握手凭据，只放在 WebSocket 地址参数里，不要写入日志 |
| `expiresAt` | 失效时间（北京时间），签发后60秒 |
| `singleUse` | 恒为 `true` |
| `path` | WebSocket 路径（已编码），拼在业务地址后使用 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `interactionId` 为空、超过64字符或含控制字符 | 修正路径 |
| 401 | 设备凭证无效；会话缺失、过期或已退出 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备；当前设备不是AIVA面基/AI图片生成 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 核对 `interactionId` |
| 409 | 会员主账户已变更 | 重新扫码登录 |
| 429 | 服务端未使用的握手凭据过多（上限1024张） | 稍后再试，不要循环申请 |

### 流式语音识别
#### 功能描述

边说边识别：客户端通过 WebSocket 推送麦克风音频，服务端转发给语音识别厂商并实时回传识别文字。每一轮识别用一个新的 `requestId`。

升级前服务端依次核对：设备、会话、体验归属（租户、门店、点位、设备、用户、会话）、授权未撤回、体验未结束、点位在互动模式、阶段（AIVA面基须名片已完成；AI图片生成须在提交答案前且有允许自由文本的题目）、上限与模型登记，并在同一事务内创建任务、冻结 Token。任一项不通过直接拒绝升级，不连接厂商。连接期间每30秒重新核对会话与体验，失效即断开。

**识别文字只返回客户端，服务端不保存原文、不送模型。** 客户端拿到 `final.text` 后自行作为聊天内容提交（AIVA面基：[创建文本任务](#api-text-task-create) `purpose:"chat"`；AI图片生成：`purpose:"guide"`），由文本入口做内容安全审核和计费。识别为空时不要提交。

计费：握手成功即冻结；收到厂商最终结果后按厂商返回的音频时长（秒）结算。

| 情况 | 结果 |
| --- | --- |
| 正常收到最终结果且有时长 | 按时长结算，多余部分释放 |
| 收到最终结果但厂商未返回时长 | 计费转“待核对”（`review`），冻结保留由运营人工处理，不用本地音频长度推算 |
| 厂商明确拒绝，或与厂商的连接未建立 | 冲正冻结 |
| 还没转发任何音频就断开 | 冲正冻结 |
| 已转发音频后客户端断开、厂商连接中断、会话失效，或说完后在接入点登记的超时内没有最终结果 | 结果未知，冻结保留待运营核对 |

#### 请求参数（Path / Query / 消息）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_6f2c…` |
| `requestId` | Query | string | 必填 | 本轮识别请求号，1—64 字符；每轮必须不同，用过的请求号再用会被拒绝（流式识别不能重放） | `asr-chat-003` |
| `ticket` | Query | string | 浏览器必填 | [语音识别握手凭据](#api-asr-ticket)返回的 `ticket` | `9f4c2b…` |
| `Authorization` / `X-Identity-Session` | Header | string | 非浏览器可选 | 不带 `ticket` 时用请求头鉴权，内容同其他用户会话接口 | `Bearer …` |
| 音频帧 | 客户端消息（二进制） | PCM | 必填 | 16kHz / 16bit / 单声道 PCM，建议每200ms一包；收到 `ready` 之后再发，之前的音频不转发 | — |
| `done` | 客户端消息（文本） | string | 必填 | 说完时发送纯文本 `done`，服务端开始等待最终结果；其他文本消息被忽略 | `done` |

单轮最多接收 `voice.asr_max_sec` 秒音频（按 32000 字节/秒计算），超出部分不转发。

#### 请求示例

```javascript
// 1. 换一次性凭据（$BASE 为 https 地址）
const t = await fetch(`${BASE}/api/interactions/${interactionId}/asr-ticket`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${DEVICE_CREDENTIAL}`, 'X-Identity-Session': SESSION_TOKEN, 'Content-Type': 'application/json' },
  body: '{}'
}).then(r => r.json());

// 2. 建立连接（https 换成 wss）
const ws = new WebSocket(`${BASE.replace(/^http/, 'ws')}${t.path}?requestId=${encodeURIComponent('asr-chat-003')}&ticket=${t.ticket}`);
ws.binaryType = 'arraybuffer';
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === 'ready') startMicrophone(pcm => ws.send(pcm));  // 每200ms一包PCM
  if (m.type === 'final') submitChat(m.text);                    // 作为聊天文本提交
};
// 3. 用户说完
stopMicrophone(); ws.send('done');
```

#### 返回示例（服务端消息，JSON 文本帧）

```json
{ "type": "ready", "taskId": "task_51ac…", "maxSeconds": 30, "audio": { "format": "pcm", "rate": 16000, "bits": 16, "channel": 1 } }
{ "type": "text", "text": "今天适合去", "definite": false, "utterances": [ { "text": "今天适合去", "definite": false } ] }
{ "type": "limit", "maxSeconds": 30, "message": "已达到登记的单次识别最长秒数，停止接收音频并等待最终结果" }
{ "type": "final", "taskId": "task_51ac…", "text": "今天适合去哪里玩？", "utterances": [ { "text": "今天适合去哪里玩？", "definite": true } ], "audioSeconds": 6.4, "billing": { "status": "settled", "frozenAmount": 30, "settlementAmount": 2, "reason": null } }
{ "type": "error", "taskId": "task_51ac…", "outcome": "unknown", "message": "厂商连接在最终结果前关闭，保留冻结待核对", "billing": { "status": "unknown", "frozenAmount": 30, "settlementAmount": null, "reason": null } }
{ "type": "notice", "message": "识别尚未就绪，就绪前的音频未转发" }
```

| 消息 / 字段 | 说明 |
| --- | --- |
| `ready` | 可以开始发音频；`taskId` 可用于[查询语音任务](#api-voice-task-get)；`maxSeconds` 为本轮最长秒数 |
| `text` | 中间结果，可不显示；`definite` 表示是否已确定 |
| `limit` | 已达最长秒数，服务端停止接收并自动等待最终结果 |
| `final` | 最终文字与计费；`audioSeconds` 厂商未返回时为 `null`（此时 `billing.status` 为 `review`）；`billing` 登记失败时为 `null`（冻结保留待核对）。随后服务端以 1000 正常关闭 |
| `error` | 本轮失败或中断；`outcome` 为 `failed`（已冲正）、`cancelled`（未转发音频，已冲正）或 `unknown`（冻结保留） |
| `notice` | 提示性消息（就绪前或结束后发来的音频未转发），每轮最多一次 |

#### 错误情况

握手被拒时，服务端直接返回 HTTP 状态行并关闭连接，**没有响应正文和 `code`**；浏览器只能看到 `onerror` 与关闭码 1006，看不到具体状态，请先确认前置条件（已授权、名片已完成、请求号未用过）。

| HTTP / 关闭码 | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `requestId` 缺失、为空、超过64字符或含控制字符；`interactionId` 格式错误 | 修正请求 |
| 401 | `ticket` 格式错误、已过期、已用过、属于其他体验或其他设备；设备凭证或会话无效 | 重新申请凭据；会话失效时回到扫码登录 |
| 403 | 当前设备不是AIVA面基/AI图片生成；设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 路径不正确；体验不存在或不属于当前设备与登录用户 | 核对 `interactionId` |
| 409 | `requestId` 已用过（`VOICE_REQUEST_REUSED`）；体验已结束；未授权或授权已撤回；AIVA面基名片未完成；AI图片生成不在可语音输入阶段；`voice.asr_max_sec`、识别模型或接入点未登记；按比例最长秒数的费用超过冻结上限（模型未计费时不检查） | 换新 `requestId` 或按页面状态处理；配置类联系运营 |
| 429 | 仅在申请凭据时出现，见上一接口 | 稍后再试 |
| 503 | 其他服务端错误（含余额不足以冻结、模型已停用、数据库异常），握手时一律以503返回 | 显示语音暂不可用，可改用文字输入 |
| 1000 | 已发送 `final`，正常关闭 | 本轮结束 |
| 1008 | 连接期间重新核对失败：会话过期或已退出、身份变化、体验已结束（先发送 `error` 消息） | 停止录音；需要时重新登录或开始新体验 |
| 1011 | 厂商明确拒绝、与厂商连接未建立或中断、说完后超时未收到最终结果（先发送 `error` 消息）；或任务状态已变化（不发送消息） | 显示识别失败，可用新 `requestId` 开始新一轮；`unknown` 结果由运营核对 |

### 上传录音识别
#### 功能描述

录完整段再识别（2026-10-14，按共创工坊开发方案）：客户端把整段录音作为 WAV 文件一次上传，服务端调用火山“录音文件识别极速版”，**一次返回识别文字**。与[流式语音识别](#api-asr-ws)同一地址：`POST` 是上传方式，WebSocket 升级是流式方式，两者并存。

用哪种方式由后台点位配置里选的语音识别模型决定：选“录音文件识别极速版”只能上传，选“大模型流式语音识别”只能流式；用错方式返回 409 `VOICE_MODEL_MISMATCH`，不会自动换用另一种。

前置核对与流式相同：设备、会话、体验归属、授权未撤回、体验未结束、阶段（AIVA面基须名片已完成；AI图片生成须在提交答案前且有允许自由文本的题目；AI车衣共创须开放AI共创、已授权且没有运行中的任务）、单次最长秒数与模型登记。

**录音时长超过后台登记的“单次语音识别最长秒数”（`voice.asr_max_sec`）直接返回 400 `VOICE_TOO_LONG`，不调用厂商、不冻结 Token**；客户端应按最长秒数控制录音。

**识别文字只返回客户端，服务端不保存原文、不送模型。** 客户端拿到 `text` 后自行提交（AIVA面基 `purpose:"chat"`；AI图片生成 `purpose:"guide"`；AI车衣共创 `purpose:"style"`），由文本入口做内容安全审核和计费。识别为空（`text` 为空字符串，`silent:true` 表示厂商判定为静音）时不要提交。

计费：核对通过后冻结；厂商返回结果后按厂商返回的音频时长（秒）结算。

| 情况 | 结果 |
| --- | --- |
| 厂商返回结果且有时长 | 按时长结算，多余部分释放 |
| 厂商返回结果但没有时长 | 计费转“待核对”（`review`），冻结保留由运营人工处理；文字照常返回 |
| 厂商明确拒绝（返回错误状态码） | 冲正冻结，返回 502 `ASR_FAILED` |
| 超时没有收到结果、连接中断、响应里没有识别结果 | 结果未知，冻结保留待运营核对，返回 504 `ASR_UNKNOWN`；不要用同一 `requestId` 重试 |

#### 请求参数

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_6f2c…` |
| `requestId` | 表单字段或 Query | string | 必填 | 本次识别请求号，1—64 字符；每次必须不同，用过的再用返回 409 `VOICE_REQUEST_REUSED`。表单与 Query 都给时须一致 | `asr-style-003` |
| `audio` | 表单文件字段 | file | 必填 | WAV 文件：PCM 16kHz / 16bit / 单声道。也可以不用表单，直接以 `Content-Type: audio/wav` 把 WAV 作为请求体上传（此时 `requestId` 放 Query） | `speech.wav` |

请求体上限 8 MB（传输保护）；实际可识别时长以 `voice.asr_max_sec` 为准。

#### 请求示例

```javascript
const form = new FormData();
form.append('requestId', 'asr-style-003');
form.append('audio', wavBlob, 'speech.wav');   // PCM 16kHz/16bit/单声道 WAV
const r = await fetch(`${BASE}/api/interactions/${interactionId}/asr`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${DEVICE_CREDENTIAL}`, 'X-Identity-Session': SESSION_TOKEN },  // 不要手动设 Content-Type
  body: form
}).then(r => r.json());
// r.text → 作为风格对话 / 聊天文本提交
```

```bash
curl -X POST "$BASE/api/interactions/$IX/asr" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" -H "X-Identity-Session: $SESSION_TOKEN" \
  -F requestId=asr-style-003 -F "audio=@speech.wav;type=audio/wav"
```

#### 返回示例

```json
{ "taskId": "task_51ac…", "text": "我想要炫酷一点的风格", "utterances": [ { "text": "我想要炫酷一点的风格" } ], "silent": false, "audioSeconds": 3.2, "billing": { "status": "settled", "frozenAmount": 600, "settlementAmount": 32, "reason": null } }
```

| 字段 | 说明 |
| --- | --- |
| `taskId` | 语音任务号，可用于[查询语音任务](#api-voice-task-get) |
| `text` | 识别文字；没有有效语音时为空字符串 |
| `utterances` | 分句文字（厂商返回时） |
| `silent` | `true` 表示厂商判定为静音 |
| `audioSeconds` | 厂商返回的音频时长；没返回时为 `null`（此时 `billing.status` 为 `review`） |
| `billing` | 计费结果；登记失败时为 `null`（冻结保留待核对）。模型未计费时 `frozenAmount` 为 0 |

#### 错误情况

错误响应为 `{"error":"…","code":"…"}`；已创建任务的错误另带 `taskId` 与 `billing`。

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `requestId` 缺失或格式错误；不是 WAV、不是 PCM 16kHz/16bit/单声道、没有音频数据；表单没有或有多个 `audio` 字段；表单与 Query 的 `requestId` 不一致；录音超过登记的最长秒数（`VOICE_TOO_LONG`，未调用厂商、未冻结） | 修正录音格式或缩短录音 |
| 401 | 设备凭证或用户会话无效 | 会话失效时回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 核对 `interactionId` |
| 409 | `requestId` 已用过（`VOICE_REQUEST_REUSED`）；点位选的是流式识别模型（`VOICE_MODEL_MISMATCH`）；体验已结束；未授权；不在可语音输入阶段；`voice.asr_max_sec`、识别模型或平台账号未登记（`VOICE_CONFIG_INCOMPLETE`）；按比例最长秒数的费用超过冻结上限（`VOICE_OVER_FREEZE_LIMIT`，模型未计费时不检查） | 换新 `requestId` 或按页面状态处理；配置类联系运营 |
| 413 | 请求体超过 8 MB | 缩短录音 |
| 415 | 不是 `multipart/form-data` 也不是 `audio/wav` | 按上面的方式上传 |
| 502 | 厂商明确拒绝（`ASR_FAILED`），已冲正 | 显示识别失败，可用新 `requestId` 重录 |
| 504 | 结果未知（`ASR_UNKNOWN`），冻结保留待核对 | 显示识别失败，可改用文字输入或用新 `requestId` 重录；不要用同一 `requestId` 重试 |

### 历史问卷读取（不用于正式互动）
#### 功能描述

2026-09-28 首批问卷阶段留下的公开接口：按门店读取旧问卷表中已发布的AIVA面基问卷。**正式互动的题目以[读取互动配置](#api-interaction-config)下发的 `questions` 为准**，本接口读取的旧问卷表与正式配置不同源，后台旧问卷编辑页已改为跳转到点位配置页，返回内容可能已过时。新开发的客户端不要调用；是否下线（待确认）。

#### 请求参数（Query）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` | Query | string | 必填 | 门店编号，不能为空或 `*` | `CQ-GUANGHUAN` |

#### 请求示例

```bash
curl "$BASE/api/p02/questions?storeId=CQ-GUANGHUAN"
```

#### 返回示例（HTTP 200）

```json
{
  "storeId": "CQ-GUANGHUAN",
  "pointId": "P02",
  "version": 3,
  "publishedAt": "2026-09-28T08:00:00.000Z",
  "questions": [ { "id": "q1", "title": "题目示例", "options": [ { "id": "q1_a", "label": "选项示例", "detail": "补充说明" } ] } ]
}
```

| 返回字段 | 说明 |
| --- | --- |
| `version` / `publishedAt` | 旧问卷表中的发布版本与发布时间 |
| `questions` | 题目与选项，不含属性映射 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 未传 `storeId`，或为 `*` | 传入明确门店 |
| 503 | 数据库未配置；门店不存在；AIVA面基点位不存在；旧问卷未发布 | 改用正式互动配置接口 |

## P03｜车机互动台 · AI音乐

### 公开网页 Demo（2026-10-12 用户确认）

此入口独立于下方正式设备与会员协议，不代表正式 Token 结算验收。公开双屏入口为 `/?debug=multiscreen&storeId=<门店编号>`。浏览器点击开始时 POST `/api/p03/public-demo/session`，JSON `{ "storeId": "CQ-GUANGHUAN" }`，无需登录、配对码或临时授权。点位须已启用且模型/告知文案就绪；响应签发 HttpOnly、SameSite=Strict 会话 Cookie，后续 `/api/p03/*` 沿用原 Demo 调用，资源按随机会话隔离。真实模型调用有用量费用；后台与设备权限不开放。

灵感探索公开五屏入口为 `/inspiration/?debug=multiscreen&storeId=<门店编号>`，不传配对码。总览自动建立仅本窗口使用的同步通道，POST `/api/p08/demo/start` 传 `publicPreview:true`，体验配置快照保存该标记；公开体验不广播到现场硬件屏，现场重连也不选取公开体验。用户主动确认隐私告知、浏览器摄像头/麦克风权限仍保留。既有打印提示不等于真实打印。

2026-10-14 灵感探索最终图分层：点位配置 `journeyLayers.enabled=true` 时，`journeyImage` 须选 Seedream 5.0 Flash 或 Pro。先生成完整场景，再以该图为唯一输入拆分底图和最多16个透明PNG图层；两次调用各有任务号与用量，不自动重试或退回单图。拆分档位独立配置为 `1K / 1.5K / 2K / auto`，不接受自定义宽高。接口原有 `imageUrl`、`assetId` 指向服务端按 `bounding_box.absolute` 与 `z_index` 合成的最终JPEG（不包含UI文字）；五屏、打印和小程序共用此作品。分层结果额外返回 `sourceTaskId`、`decompositionUsage`、`layerManifest`（持久资产地址、底图尺寸、各层坐标与层级）。原始场景及图层为非最终资产，不打印、不推小程序；运营在体验记录的 `answers.journeyLayers` 查看清单。先部署新后端，再应用分层配置；旧体验快照不改变。像素合成使用独立worker，运行时需Node>=20.9.0。此链路仍为Demo语义，不宣称正式Token结算。

AI音乐（P03）的访客在车机互动台上先选曲风、再选人声，讲两轮自己的故事，由文本模型写出歌词与“音乐DNA”，访客可以手动改词并确认，最后由后台配置的豆包音乐模型生成正式歌曲，同时生成一张封面。本章接口都由 AI音乐点位客户端调用，鉴权均为设备凭证 + 用户会话（U）；Path 中的 `:id` 为创建体验返回的 interactionId，必须属于当前设备和当前登录用户。AI音乐旧链路 `/api/p03/*`（数字DJ对话、故事对话、旧生成任务等）在服务端继续保留，但不属于本文档的正式接入协议，新客户端不要调用。

### 页面操作与调用顺序

| 步骤 | 页面 / 用户操作 | 调用 | 客户端处理 |
| --- | --- | --- | --- |
| 1 | 程序启动 | [读取互动配置](#api-interaction-config) | 校验 pointId=P03；用 `music.genres`、`music.timbres` 渲染曲风与人声（各为 `{id,label}`），`durationStrategy` 恒为 `content`；`questions` 为故事题；保留 version |
| 2 | 配置应用成功 | [确认配置已应用](#api-interaction-config-ack) | 成功后才能用该版本创建体验 |
| 3 | 访客扫身份码 | [扫码登录](#api-point-login) | 保留 sessionToken；余额显示用 [当前用户](#api-identity-me) |
| 4 | 开始体验 | [创建体验](#api-interaction-create) | 保留 interactionId |
| 5 | 同意授权 | [提交授权](#api-interaction-consent) | AI音乐的授权类型为 interaction；拒绝即结束 |
| 6 | 选曲风 | [保存曲风人声选择](#api-p03-selection-save) | 第一次 `expectedRevision=0`，只传 `genreId` |
| 7 | 选人声 | [保存曲风人声选择](#api-p03-selection-save) | 再传 `genreId`+`timbreId`，`expectedRevision` 用上一步返回的 revision |
| 8 | 讲完两轮故事 | [提交作答](#api-interaction-answers) | 一次提交完整题集；没选人声时返回409；自由文本先过内容安全 |
| 9 | 确认曲风人声 | [确认曲风人声](#api-p03-selection-confirm) | AI音乐不用公用的[确认接口](#api-interaction-confirm)（对 P03 返回400），必须用本接口带修订号确认 |
| 10 | 生成歌词 | [创建正式文本任务](#api-text-task-create) → [查询文本任务](#api-text-task-get) | `purpose=lyrics`，`revision`=已确认的曲风人声修订号；成功后歌词自动写入歌词修订 |
| 11 | 歌词页 | [读取歌词修订](#api-p03-lyrics-get) | 显示最新一条（`items[0]`） |
| 12 | 访客手动改词（可选） | [手动修改歌词](#api-p03-lyrics-save) | 只改曲名和歌词，不调用模型、不计费 |
| 13 | 确认歌词 | [确认歌词](#api-p03-lyrics-confirm) | 确认不会提交音乐模型 |
| 14 | 生成音乐 | [提交正式音乐任务](#api-p03-music-task-create) | 保存返回的 taskId |
| 15 | 等待页 | [查询音乐任务](#api-p03-music-task-get) | 按 taskId 轮询，直到 status 为 completed/failed/cancelled/unknown/save_pending；封面单独看 `cover.status` |
| 16 | 结果未知 / 作品保存待处理 | [核对音乐任务](#api-p03-music-task-check) | 只核对原任务，不换 requestId 重新生成 |
| 17 | 结果页 | [本次作品列表](#api-works-list) | 音频作品审核通过、结算完成后才能取件 |
| 18 | 返回页面 / 离开 | [读取体验](#api-interaction-get)、[结束体验](#api-interaction-end) | 音乐任务运行中或结果未知时结束体验会返回409 |

改曲风或人声：再次保存选择后，本次体验回到“未确认”，须重新确认，并重新生成歌词（新的付费文本任务），旧歌词不能再确认。重新生成歌词：用新的 requestId 再创建一次 `purpose=lyrics` 文本任务，正常计费。音乐明确失败（failed）后，本次体验回到可提交状态，可用新的 requestId 再提交一次音乐任务（重新计费）；结果未知（unknown）时不能这样做。

### 曲风人声与歌词修订规则

| 规则 | 说明 |
| --- | --- |
| 目录来源 | 曲风、人声及其厂商参数映射由后台“互动管理”配置；客户端只拿到 `{id,label}`，不能自报厂商参数。旧版歌手/曲目/固定时长不会自动映射成新选项，带 `artistId` 或 `songs` 的请求直接拒绝 |
| 修订号 | 曲风人声每保存一次 revision 加 1（从 0 开始）；歌词每生成或修改一次 revision 加 1。保存时 `expectedRevision` 必须等于当前最新修订，否则409，客户端应重新读取后再操作 |
| 歌词与偏好绑定 | 每条歌词修订记录生成它时的曲风人声修订号（`selection_revision`）；偏好改过之后，旧歌词不能确认，也不能用于提交音乐 |
| 歌词格式 | 曲名去首尾空白后至多 8 个字符；歌词至多 16000 字符，演唱内容须为中文，英文只允许出现在结构标记 `[verse]` `[chorus]` `[inst]` `[intro]` `[outro]` `[bridge]` `[solo]` `[pre-chorus]` 中 |
| 音乐DNA | 来自正式歌词模型的真实返回：persona、description 和三个不同的关键词；缺失时该歌词任务按结果未知处理，服务端不补本地模板 |
| 状态门禁 | 有模型任务运行中（歌词或音乐）时不能改选择、改词或确认；音乐完成后本次体验不能再改选择、改词或再提交音乐 |

### 保存曲风人声选择
#### 功能描述

保存访客在曲风页、人声页的选择。分两次调用：曲风页只传 `genreId`；人声页再传 `genreId`+`timbreId`（曲风必须重复携带）。每次保存都生成新的修订号，并把本次体验的“已确认”状态清掉，之后需重新[确认曲风人声](#api-p03-selection-confirm)。

调用时机：授权之后、提交故事之前；故事提交后也可以修改（修改后须重新确认并重新生成歌词）。只有本次体验已授权、且处于“作答中”或“已就绪”（没有运行中的任务、音乐未完成）时可以保存。同一个请求号原样重发不会重复执行，返回第一次的结果。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `requestId` | Body | string | 必填 | 本次保存的请求号，1—64 字符，不含控制字符；每次新的选择换一个新号 | `sel-20261008-0001` |
| `expectedRevision` | Body | integer | 必填 | 当前最新修订号，≥0；第一次保存传 0 | `0` |
| `genreId` | Body | string | 必填 | 曲风 id，必须在本次配置的 `music.genres` 中 | `genre_folk` |
| `timbreId` | Body | string | 可选 | 人声 id，必须在本次配置的 `music.timbres` 中；曲风页不传 | `timbre_female_warm` |

#### 请求示例

```bash
curl -X PUT "$BASE/api/interactions/ix_example/music-selection" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"sel-20261008-0002","expectedRevision":1,"genreId":"genre_folk","timbreId":"timbre_female_warm"}'
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 2,
  "design": {
    "genreId": "genre_folk",
    "genre": "民谣",
    "genreModelValue": "Folk",
    "timbreId": "timbre_female_warm",
    "timbre": "温暖女声",
    "timbreModelValue": "Warm",
    "stage": "preferences-complete"
  },
  "state": "questions",
  "confirmed": false
}
```

同一请求号原样重发时返回：

```json
{ "revision": 2, "design": { "genreId": "genre_folk", "stage": "preferences-complete" }, "idempotentHit": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 本次保存后的修订号，下一次保存和确认都用它 |
| `design.genre` / `design.timbre` | 后台配置的显示名称 |
| `design.genreModelValue` / `design.timbreModelValue` | 后台登记的厂商参数映射，仅供展示核对，客户端不要提交 |
| `design.stage` | `genre`：只选了曲风；`preferences-complete`：曲风和人声都已选 |
| `state` | 体验状态：`questions`（还没提交故事或还没选人声）/ `ready`（故事已提交且已选人声，可以确认） |
| `confirmed` | 恒为 `false`，保存后须重新确认 |
| `idempotentHit` | 仅在原样重发时出现，为 `true`；此时只返回 revision 与 design |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是 AI音乐点位；`requestId` 为空、超长或含控制字符；`expectedRevision` 缺失或为负数；`genreId`/`timbreId` 不在本次配置中；请求带旧版 `artistId`/`songs`；请求体不是合法 JSON | 修正参数；目录不匹配时重新读取互动配置 |
| 401 | 设备凭证无效；缺少用户会话、会话过期或已退出；身份卡已作废 | 清除本地会话，回到扫码登录 |
| 403 | 设备已在后台停用；纯展示点位设备调用 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 同一 `requestId` 已用于不同内容；尚未授权，或有任务运行中、音乐已完成、体验已结束；`expectedRevision` 不是最新（“设计已被更新”）；会员主账户已变更 | 修订冲突时先[读取选择](#api-p03-selection-get)再保存；主账户变更时重新扫码登录 |
| 500 | 服务端错误 | 显示失败，不自动换请求号重试 |

### 读取曲风人声选择
#### 功能描述

读取本次体验当前的曲风人声选择、修订号和是否已确认。用于返回页面恢复界面，或保存时遇到修订冲突后重新取最新修订号。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_example/music-selection" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 2,
  "design": {
    "genreId": "genre_folk",
    "genre": "民谣",
    "genreModelValue": "Folk",
    "timbreId": "timbre_female_warm",
    "timbre": "温暖女声",
    "timbreModelValue": "Warm",
    "stage": "preferences-complete"
  },
  "confirmed": true
}
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 当前最新修订号；还没保存过时为 `0` |
| `design` | 当前选择，字段同“保存曲风人声选择”；还没保存过时为 `null` |
| `confirmed` | 本次体验当前是否已确认曲风人声 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是 AI音乐点位；interactionId 格式错误 | 检查设备凭证和路径 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 会员主账户已变更 | 重新扫码登录或联系运营 |

### 确认曲风人声
#### 功能描述

访客确认最新的曲风人声选择。只有已授权、已选人声、故事已提交（体验状态为 `ready`）且所传修订号是最新时才能确认。确认之后才能生成歌词；确认本身不调用任何模型、不计费。已确认的情况下重复调用仍返回确认成功。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `revision` | Body | integer | 必填 | 要确认的曲风人声修订号，必须是最新修订 | `2` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_example/music-selection/confirm" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"revision":2}'
```

#### 返回示例（HTTP 200）

```json
{ "confirmed": true, "revision": 2 }
```

| 返回字段 | 说明 |
| --- | --- |
| `confirmed` | 恒为 `true` |
| `revision` | 已确认的修订号；生成歌词时作为文本任务的 `revision` 传入，提交音乐时作为 `selectionRevision` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `revision` 不是整数；请求体不是合法 JSON | 修正参数 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 不是 AI音乐体验；未授权、故事未提交、有任务运行中或已结束（“请先完成授权与创作输入”）；修订号不是最新（“设计已变化”）；还没选人声；会员主账户已变更 | 修订变化时先[读取选择](#api-p03-selection-get)，让访客确认最新选择 |

### 读取歌词修订
#### 功能描述

读取本次体验的全部歌词修订，最新的排在最前。歌词修订由两种方式产生：歌词文本任务（`purpose=lyrics`）成功后由服务端自动写入；访客[手动修改歌词](#api-p03-lyrics-save)。只能确认最新一条。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_example/lyrics" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "items": [
    {
      "revision": 1,
      "selection_revision": 2,
      "source_task_id": "task_2b8f…",
      "result": {
        "title": "晚风回家路",
        "lyrics": "[verse]\n路灯一盏一盏亮起\n……\n[chorus]\n……",
        "theme": "归途",
        "mood": "温暖",
        "scene": "夜晚的城市公路",
        "dna": { "persona": "夜行的讲述者", "description": "……", "keywords": ["归途", "灯光", "陪伴"] }
      },
      "confirmed_at": null,
      "created_at": "2026-10-08T06:00:00.000Z"
    }
  ],
  "note": "只确认最新歌词修订；修改或重新生成后须重新确认，确认不提交音乐模型。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items[].revision` | 歌词修订号；确认歌词时传 `revision`，提交音乐时作为 `lyricsRevision` |
| `items[].selection_revision` | 生成这条歌词时的曲风人声修订号；与当前已确认修订不一致时不能确认 |
| `items[].source_task_id` | 产生该歌词的文本任务号；手动修改的修订沿用上一条的任务号 |
| `items[].result` | `title` 曲名、`lyrics` 歌词、`theme` 主题、`mood` 情绪、`scene` 场景、`dna` 音乐DNA（persona、description、keywords 三个关键词） |
| `items[].confirmed_at` | 确认时间；未确认为 `null` |
| `items[].created_at` | 修订创建时间 |
| `note` | 服务端说明 |

还没有歌词时 `items` 为空数组。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 不是 AI音乐体验；interactionId 格式错误 | 检查设备凭证和路径 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 会员主账户已变更 | 重新扫码登录或联系运营 |

### 手动修改歌词
#### 功能描述

访客在歌词页手动修改曲名和歌词，生成一条新的歌词修订（未确认）。主题、情绪、场景、音乐DNA 和所属曲风人声修订沿用上一条，不调用生成模型、不计费。

因为改后的曲名和歌词确认后会发给音乐模型，保存前会把“曲名+歌词”送内容安全审核：未通过返回422，审核未配置或不可用返回503，都不写入修订。同一个请求号原样重发不会重复执行（也不再审核），返回第一次的结果。

调用时机：至少已有一条由歌词任务生成的歌词，且没有运行中的任务、音乐尚未完成。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `requestId` | Body | string | 必填 | 本次修改的请求号，1—64 字符 | `lyr-edit-0001` |
| `expectedRevision` | Body | integer | 必填 | 当前最新歌词修订号 | `1` |
| `title` | Body | string | 必填 | 新曲名，去首尾空白后至多 8 个字符 | `晚风回家` |
| `lyrics` | Body | string | 必填 | 新歌词，至多 16000 字符；中文演唱，英文仅限结构标记 | `[verse]\n路灯一盏一盏亮起…` |

只接受以上四个 Body 字段，多传任何字段返回400。

#### 请求示例

```bash
curl -X PUT "$BASE/api/interactions/ix_example/lyrics" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"lyr-edit-0001","expectedRevision":1,"title":"晚风回家","lyrics":"[verse]\n路灯一盏一盏亮起\n[chorus]\n晚风陪我回家"}'
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 2,
  "confirmed": false,
  "result": {
    "title": "晚风回家",
    "lyrics": "[verse]\n路灯一盏一盏亮起\n[chorus]\n晚风陪我回家",
    "theme": "归途",
    "mood": "温暖",
    "scene": "夜晚的城市公路",
    "dna": { "persona": "夜行的讲述者", "description": "……", "keywords": ["归途", "灯光", "陪伴"] }
  }
}
```

同一请求号原样重发时返回：

```json
{ "revision": 2, "idempotentHit": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 新的歌词修订号，确认时使用 |
| `confirmed` | 恒为 `false`，修改后须重新确认 |
| `result` | 修改后的完整歌词结果（曲名、歌词已去首尾空白） |
| `idempotentHit` | 仅在原样重发时出现，为 `true`；此时只返回 revision |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `requestId` 格式错误；`expectedRevision` 不是整数；多传了字段；曲名超过 8 字、歌词为空、超长或含结构标记以外的英文；请求体不是合法 JSON | 提示访客修改内容 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 不是 AI音乐体验，或有任务运行中、音乐已完成、体验已结束；还没有生成过歌词；同一 `requestId` 已用于不同内容（服务端原文“歌词幂等键冲突”，即请求号被重复用于不同内容）；`expectedRevision` 不是最新；会员主账户已变更 | 修订冲突时先[读取歌词修订](#api-p03-lyrics-get)再修改 |
| 413 | 请求体超过 100 万字符 | 缩短内容 |
| 422 | `code=CONTENT_REJECTED`、`failureKind=moderation`：曲名或歌词审核未通过 | 显示“审核未通过”，请访客修改后再提交；本次未写入 |

### 确认歌词
#### 功能描述

访客确认最新一条歌词。必须同时满足：所传修订是最新歌词修订、这条歌词所属的曲风人声修订就是当前最新修订、且曲风人声已确认。确认只做登记，不会提交音乐模型；提交音乐时服务端会再次核对。已确认的修订重复确认仍返回成功。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `revision` | Body | integer | 必填 | 要确认的歌词修订号，必须是最新一条 | `2` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_example/lyrics/confirm" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"revision":2}'
```

#### 返回示例（HTTP 200）

```json
{ "revision": 2, "confirmed": true, "note": "尚未提交音乐模型；音乐任务必须再次校验本修订。" }
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 已确认的歌词修订号，提交音乐时作为 `lyricsRevision` |
| `confirmed` | 恒为 `true` |
| `note` | 服务端说明 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `revision` 不是整数；请求体不是合法 JSON | 修正参数 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 不是 AI音乐体验，或有任务运行中、音乐已完成、体验已结束；还没有歌词或修订号不是最新；歌词所属曲风人声已被改过，或曲风人声尚未确认；会员主账户已变更 | 重新读取选择与歌词；偏好改过时须重新确认偏好并重新生成歌词 |

### 提交正式音乐任务
#### 功能描述

用已确认的歌词和曲风人声提交正式音乐生成。服务端在同一事务里登记音乐任务、按后台登记的单次冻结上限冻结 Token，并同时登记第一次封面任务及其冻结，然后在后台把请求提交给豆包音乐模型（GenSongForTime），只提交一次。接口立即返回 taskId，客户端用[查询音乐任务](#api-p03-music-task-get)看进度。

提交前服务端会逐项核对：本次体验已授权且授权未撤回、曲风人声已确认、所传两个修订号都是最新且歌词已确认、没有运行中的任务、点位处于可接收互动的状态，以及音乐模型、封面模型、查询间隔与最长等待、作品存储与留存等配置都已登记。任何一项不满足都直接拒绝，不冻结、不提交厂商。提交内容与时长算法见下方“正式音乐提交内容与时长”。

同一个请求号原样重发不会重复执行，返回第一次的 taskId（`status=existing`）。网络错误时请用原请求号重发或直接查询原 taskId，不要换新请求号。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `requestId` | Body | string | 必填 | 本次提交的请求号，1—64 字符 | `music-0001` |
| `lyricsRevision` | Body | integer | 必填 | 已确认的最新歌词修订号，≥1 | `2` |
| `selectionRevision` | Body | integer | 必填 | 已确认的最新曲风人声修订号，≥1 | `2` |

只接受以上三个 Body 字段，多传任何字段返回400。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_example/music-tasks" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"music-0001","lyricsRevision":2,"selectionRevision":2}'
```

#### 返回示例（HTTP 200）

```json
{
  "taskId": "task_5d0c2f7e-…",
  "status": "queued",
  "idempotentHit": false,
  "note": "任务已持久化并冻结；查询原taskId。结果未知时只核对原厂商任务，不用新requestId重新生成。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `taskId` | 音乐任务号，保存好，之后查询和核对都用它 |
| `status` | `queued`：本次新建；`existing`：同一请求号原样重发，返回的是第一次的任务（真实进度请查询） |
| `idempotentHit` | 是否为原样重发 |
| `note` | 服务端说明 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是 AI音乐点位；多传字段；`requestId` 格式错误；修订号不是 ≥1 的整数；请求体不是合法 JSON | 修正参数 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 回到开始体验 |
| 409 | 同一 `requestId` 已用于不同修订；点位为展示应用；未授权、曲风人声未确认、已有任务运行中或音乐已完成；授权已撤回；`code=P03_MUSIC_REVISION_CHANGED`：歌词或偏好不是最新或歌词未确认；未选人声；`code=P03_MUSIC_CONFIG_INCOMPLETE`：缺音乐生成要求、音乐或封面模型未绑定、`genAction` 不是 GenSongForTime、模型参数覆盖了正式链路字段、曲风/人声映射不在厂商官方枚举、`music.poll_interval_sec` 或 `music.max_wait_sec` 未登记、封面接入点/超时/b64_json 未登记；作品大小限制或作品留存期限未登记；模型单次冻结上限或兑换比例未登记或版本已变化；会员主账户已变更 | 修订冲突时让访客确认最新歌词；配置类问题显示“配置未完成，请联系工作人员”，不要重试 |
| 409 | 可冻结的 Token 不足（409，`code:"TOKEN_INSUFFICIENT"`，2026-10-08 修复，原为 500） | 提示余额不足，不自动换请求号重试 |
| 500 | 加密主密钥或结果暂存目录不可用；模型平台账号停用或模型已停用；存储配置缺失等服务端错误 | 显示失败，不自动换请求号重试 |

### 查询音乐任务
#### 功能描述

按 taskId 读取音乐任务的当前状态、失败分类、封面状态与 Token 冻结结算情况。只读，不触发任何厂商调用；服务端自己会按后台登记的查询间隔查询原厂商任务。轮询直到 `status` 不再是 prepared/dispatched/submitted；音乐完成后封面可能仍在生成，继续轮询到 `cover.status` 不是 `pending`。

状态与提示码的含义见下方“音乐任务状态与提示码”。`completed` 表示音频已保存为作品（2026-10-13 起以原文件存入公开读的对象存储；音频不在内容安全审核范围，保存即为已通过，可直接取件）。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `taskId` | Path | string | 必填 | 提交音乐任务返回的 taskId | `task_5d0c2f7e-…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_example/music-tasks/task_5d0c2f7e-example" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "taskId": "task_5d0c2f7e-…",
  "status": "completed",
  "code": null,
  "lyricsRevision": 2,
  "selectionRevision": 2,
  "providerTaskRecorded": true,
  "failure": null,
  "reason": null,
  "assetId": "asset_9a1f…",
  "submittedAt": "2026-10-08T06:00:02.000Z",
  "deadlineAt": "2026-10-08T06:10:02.000Z",
  "checkedAt": "2026-10-08T06:01:32.000Z",
  "cover": { "status": "completed", "assetId": "asset_3c7e…", "reason": null, "placeholder": false },
  "billing": { "status": "settled", "frozenAmount": 300, "settlementAmount": 124, "reason": "success" },
  "note": "completed不等于审核通过；unknown只能核对原厂商任务，不用新requestId重新生成。"
}
```

厂商明确失败时的示例片段：

```json
{
  "status": "failed",
  "code": "P03_MUSIC_CONTENT_REJECTED",
  "failure": { "kind": "moderation", "errorNumber": "300062" },
  "reason": "内容未通过审核：……",
  "assetId": null,
  "billing": { "status": "reversed", "frozenAmount": 300, "settlementAmount": 0, "reason": "failed" }
}
```

结果未知时的示例片段：

```json
{
  "status": "unknown",
  "code": "P03_MUSIC_RESULT_UNKNOWN",
  "providerTaskRecorded": true,
  "reason": "超过已登记最长等待仍未确认结果；保留冻结，只能按原厂商TaskID核对，不重新提交",
  "billing": { "status": "unknown", "frozenAmount": 300, "settlementAmount": null, "reason": "厂商结果未知；保留冻结，核对原任务，不自动重试" }
}
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | 音乐任务状态：`prepared` / `dispatched` / `submitted` / `save_pending` / `completed` / `failed` / `cancelled` / `unknown` |
| `code` | 终端提示码；进行中和完成时为 `null`，其余见“音乐任务状态与提示码” |
| `lyricsRevision` / `selectionRevision` | 本任务使用的歌词与曲风人声修订号 |
| `providerTaskRecorded` | 是否已登记厂商任务号；为 `false` 且结果未知时无法核对，只能由工作人员处理 |
| `failure` | 仅 `failed` 时有值：`kind` 为 `moderation`（审核/版权拒绝）、`vendor`（厂商失败）或 `config`（接入配置问题，如缺 AK/SK）；`errorNumber` 为厂商错误编号（可能为 `HTTP_4xx` 形式或 `null`） |
| `reason` | 失败、未知或保存待处理的原因说明文本，不要用于程序判断 |
| `assetId` | 音频作品编号；未保存时为 `null` |
| `submittedAt` / `deadlineAt` / `checkedAt` | 厂商受理时间、最长等待截止时间、最近一次查询原厂商任务的时间 |
| `cover.status` | 封面状态：`pending` 生成中 / `completed` 已保存 / `placeholder` 两次失败，界面用自身占位图 / `skipped` 音乐失败或已取消，不再生成 |
| `cover.assetId` / `cover.reason` / `cover.placeholder` | 封面作品编号；失败原因；是否应显示占位图 |
| `billing.status` | 音乐任务的冻结状态：`frozen` 冻结中 / `settled` 已结算 / `reversed` 已冲正退回 / `unknown` 结果未知保留冻结 / `review` 用量待核对保留冻结 |
| `billing.frozenAmount` / `billing.settlementAmount` | 冻结的 Token；实际扣除的 Token（未结算时为 `null`） |
| `billing.reason` | 结算说明 |
| `note` | 服务端说明 |

`billing` 只反映音乐本身；封面每次尝试单独冻结与结算，不在此显示。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录；任务不受影响，重新登录后无法再查询本次体验 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前登录；taskId 不属于本次体验 | 检查 taskId |
| 409 | 会员主账户已变更 | 联系运营或重新扫码登录 |

### 核对音乐任务
#### 功能描述

在结果未知（unknown）或作品保存待处理（save_pending）时，让服务端再核对一次原任务。按当前状态处理：

| 当前状态 | 服务端动作 |
| --- | --- |
| `save_pending` | 用加密暂存的同一结果继续保存作品；再次失败时仍为 save_pending 并更新原因 |
| `submitted` | 如服务端轮询中断，则恢复按登记间隔查询原厂商任务号 |
| `unknown` 且已有厂商任务号 | 按原厂商任务号查询一次：仍在生成→保持 unknown；厂商成功→保存作品并结算（可变为 completed）；厂商失败→failed 并冲正冻结；查询出错→返回502，状态不变。两次查询之间必须间隔后台登记的 `music.poll_interval_sec` |
| `unknown` 但没有厂商任务号 | 无法核对，返回409，只能由工作人员核对厂商记录 |
| 其他状态，或已有作品 | 不做任何动作，直接返回当前状态 |

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 本次体验 interactionId | `ix_example` |
| `taskId` | Path | string | 必填 | 原音乐任务号 | `task_5d0c2f7e-…` |

Body 不需要任何字段，可不传或传 `{}`。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_example/music-tasks/task_5d0c2f7e-example/check" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

返回结构与[查询音乐任务](#api-p03-music-task-get)完全相同，例如核对后仍未确认：

```json
{
  "taskId": "task_5d0c2f7e-…",
  "status": "unknown",
  "code": "P03_MUSIC_RESULT_UNKNOWN",
  "lyricsRevision": 2,
  "selectionRevision": 2,
  "providerTaskRecorded": true,
  "failure": null,
  "reason": "超过已登记最长等待仍未确认结果；保留冻结，只能按原厂商TaskID核对，不重新提交",
  "assetId": null,
  "submittedAt": "2026-10-08T06:00:02.000Z",
  "deadlineAt": "2026-10-08T06:10:02.000Z",
  "checkedAt": "2026-10-08T06:12:40.000Z",
  "cover": { "status": "completed", "assetId": "asset_3c7e…", "reason": null, "placeholder": false },
  "billing": { "status": "unknown", "frozenAmount": 300, "settlementAmount": null, "reason": "厂商结果未知；保留冻结，核对原任务，不自动重试" },
  "note": "completed不等于审核通过；unknown只能核对原厂商任务，不用新requestId重新生成。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| 全部字段 | 同“查询音乐任务”；以返回的 `status` 为准更新界面 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | interactionId 格式错误；请求体不是合法 JSON | 检查路径与请求体 |
| 401 | 设备凭证或用户会话无效、过期；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前登录；taskId 不属于本次体验 | 检查 taskId |
| 409 | `code=P03_MUSIC_RESULT_UNKNOWN`、`outcome=unknown`：提交结果未确认且没有厂商任务号，无法查询；`code=P03_MUSIC_SAVE_PENDING`：原结果暂存缺失；会员主账户已变更 | 显示“结果待核对，请等待工作人员处理”，不要换请求号重新提交 |
| 429 | `code=P03_MUSIC_CHECK_TOO_FREQUENT`：距上次查询不足登记的查询间隔 | 稍后再核对 |
| 502 | `code=P03_MUSIC_RESULT_UNKNOWN`、`outcome=unknown`：按原厂商任务号查询出错，状态不变 | 显示结果待核对，稍后可再核对 |

### 音乐任务状态与提示码

| status | 含义 | Token 冻结 | 客户端处理 |
| --- | --- | --- | --- |
| `prepared` / `dispatched` | 已登记并冻结，正在提交厂商 | 冻结中 | 继续轮询 |
| `submitted` | 厂商已受理，服务端按登记间隔查询原厂商任务号 | 冻结中 | 继续轮询 |
| `save_pending` | 厂商已成功，作品保存失败，服务端用同一结果继续保存 | 冻结中 | 提示“作品保存待处理”，可调用核对 |
| `completed` | 音频已保存为作品（原文件存入公开读的对象存储；音频不在内容安全审核范围，保存即为已通过） | 按成品秒数结算 | 进入结果页，可直接取件 |
| `failed` | 厂商或审核明确失败 | 已冲正退回 | 按 code 提示；访客可修改后用新请求号重新提交（重新计费） |
| `cancelled` | 提交厂商前体验已结束或服务重启 | 已冲正退回 | — |
| `unknown` | 提交结果不明、超过最长等待仍无结果、互动结束后才返回结果，或作品已保存但用量待核对 | 保留冻结，由有权限的运营在后台核对厂商记录后人工“按核对用量结算”或“全额释放” | 提示“结果待核对”；只能调用核对，不能换请求号重新生成 |

| code | 出现位置 | 触发 | 终端提示建议 |
| --- | --- | --- | --- |
| `P03_MUSIC_CONTENT_REJECTED` | 查询结果（failed） | 厂商歌词版权检测或内容安全拒绝（厂商错误 300061—300064，`failure.kind=moderation`） | 内容未通过，请调整歌词后重新确认 |
| `P03_MUSIC_VENDOR_FAILED` | 查询结果（failed） | 厂商明确失败，`failure.errorNumber` 为厂商错误编号 | 生成失败，显示错误编号 |
| `P03_MUSIC_CONFIG_INCOMPLETE` | 提交返回409；查询结果（failed，`failure.kind=config`，如提交时音乐接入点缺 AK/SK） | 音乐或封面配置未完成 | 配置未完成，请联系工作人员 |
| `P03_MUSIC_RESULT_UNKNOWN` | 查询结果（unknown）；核对返回409/502 | 见上表 unknown | 结果待核对，请等待工作人员处理 |
| `P03_MUSIC_SAVE_PENDING` | 查询结果（save_pending）；核对返回409 | 作品保存失败或原结果暂存缺失 | 作品保存待处理 |
| `P03_MUSIC_CANCELLED` | 查询结果（cancelled） | 提交前体验已结束 | — |
| `P03_MUSIC_REVISION_CHANGED` | 提交返回409 | 歌词或偏好修订不是最新或歌词未确认 | 请确认最新歌词 |
| `P03_MUSIC_CHECK_TOO_FREQUENT` | 核对返回429 | 早于登记的查询间隔 | 稍后再查询 |

查询原厂商任务号出错时，服务端在后台登记的最长等待（`music.max_wait_sec`，从厂商受理起算）内继续按原任务号查询；超过最长等待仍无确定结果才记为 unknown。服务重启时：尚未提交厂商的任务冲正冻结并记 cancelled；已开始提交但没拿到厂商任务号的记 unknown；已有厂商任务号的继续查询。任何情况都不会重新提交或重新生成。

### 正式音乐提交内容与时长

- 模型：使用后台为 AI音乐绑定的豆包音乐模型，型号/版本按后台登记原样提交，不设版本白名单；只接入按时长计费的 GenSongForTime。
- 提交字段：`Lyrics`（已确认歌词）、`ModelVersion`、`Duration`、`SkipCopyCheck=false`（保留厂商歌词版权检测）、`Genre`/`Timbre`（所选曲风人声的厂商参数，须在官方枚举内）、`Prompt`（后台“音乐生成要求”+曲风、人声、主题、情绪、场景）。厂商按版本忽略不支持的字段。
- 时长（2026-10-06 确认沿用旧原型完整公式）：
  1. 目标秒数 = 145 + 故事长度加成 + 曲风偏移，限制在 30—175 秒。故事长度加成 = 本次全部故事回答（去空白）字数 ÷ 4，四舍五入，最多 25 秒。曲风偏移按曲风中文名：民谣 +15、爵士 +12、R&B +8、国风 +8、流行 0、摇滚 −5、电子 −8、嘻哈 −12，其他名称为 0。
  2. 最终秒数 = 已确认歌词字数（去空白，不计以 `[` 开头的结构标记行）÷ 1.6，限制在“目标 −15%（不低于 30 秒）”到“目标 +25%（不高于 180 秒）”之间，四舍五入为整数；歌词字数为 0 时取目标秒数。
  3. 曲风偏移按后台配置的显示名称匹配，名称不是上述八种时偏移为 0。

### 封面

随音乐任务同时生成一张封面：使用 AI音乐绑定的图片模型，提示词为“生成原创歌曲封面，不复刻歌手形象或唱片封面”+后台“歌曲封面的整体要求”+歌词的主题、情绪、场景。每次尝试都是一次独立的正式单图任务，单独冻结、按真实张数结算。

| 情况 | 本次尝试的冻结 | 是否计为一次封面失败 |
| --- | --- | --- |
| 成功且内容安全通过 | 按张数结算；封面作品自动审核通过 | — |
| 厂商明确失败 | 冲正 | 是 |
| 厂商结果不明 | 保留冻结待核对 | 是 |
| 内容安全未通过（BLOCK/REVIEW） | 冲正，不保存 | 是 |
| 未登记内容安全或审核服务临时不可用 | 按通过处理（2026-10-13 确认）：按张数结算，封面作品自动审核通过并标记“未审核” | — |

第一次失败后自动重试一次；第二次仍失败（或重试无法登记），`cover.status=placeholder`，界面显示自身占位图（服务端不生成占位图片），并发出站内告警 `content.cover_failed` 给内容运营和门店运营；告警发送失败只记录，不影响占位处理。音乐失败或取消时未开始的封面不再生成（`skipped`）。封面失败不影响音乐作品保存。

### 结算

音乐按调用时快照的兑换比例与厂商返回的成品时长（秒）计算，小数 Token 向上取整。厂商未返回时长或费用超过冻结上限时，音频照常保存，但任务记为 unknown、冻结保留（`billing.status=review`），由运营人工处置。明确失败、提交前取消冲正冻结；unknown 不自动退款、不自动重试。

### P03剩余边界

- 内容安全代码已接入，但火山内容安全尚未开通、未真实联调：在登记前，手动改词、含自由文本的故事与封面都不送审、按通过处理，封面作品标记“未审核”（2026-10-13 确认）。
- 可冻结 Token 不足时，提交音乐任务返回 409 `code:"TOKEN_INSUFFICIENT"`（2026-10-08 修复，原为 500）。
- 音乐结果为 unknown 时，本次体验保持“运行中”：不能改词、不能再提交音乐；访客可以用[结束体验](#api-interaction-end)以“放弃”结束（2026-10-08 修复，此前返回409），冻结的 Token 留待后台人工核对。
- 服务端不强制“恰好两轮”故事，故事题数以后台配置的 `questions` 为准，须一次提交完整题集。
- 音乐作品集团同步未接入；真实音乐厂商、存储、数据库端到端未联调（沿用原文结论，本轮未重新核对，待确认）。
- 不要把旧原型、后台模型测试接口或旧链路 `/api/p03/*` 当作正式客户端协议。10月6日失败方案已批准：审核/厂商失败分类、未知只核对原任务不重试、停止本地模板歌词及话术，明确失败按已批准账本冲正。

## P08｜AI图片生成

AI图片生成（P08）引导用户回答旅程问题，每答一题由助手实时回复，答完后点击“出发”，用用户照片和全部回答生成一张旅程图片。本点位没有专属接口，全部使用公用的互动会话、正式任务和语音接口；本章说明调用顺序与 AI图片生成特有的规则。

### 页面操作与调用顺序

| 页面 / 用户操作 | 调用 | 关键参数 / 结果 |
| --- | --- | --- |
| 程序启动 | [读取互动配置](#api-interaction-config)，D | 校验 `pointId=P08`，读取 version、questions、policy |
| 配置已应用 | [确认配置已应用](#api-interaction-config-ack)，D | `{version}` → `{confirmed:true,version}` |
| 扫码进入 | [扫码登录](#api-point-login)，D | 获取 sessionToken |
| 开始体验 | [创建体验](#api-interaction-create)，U | `{requestId,version}` → interactionId |
| 采集授权 | [提交授权](#api-interaction-consent)，U | 明确 accepted、policyId、policyVersion；成功后状态为 `questions` |
| 拍照 | 无单独接口 | 照片保留在本机，出发后随生成请求提交；服务端不提供单独的照片上传 |
| 每题作答后“助手回复” | [创建文本任务](#api-text-task-create)（`purpose:"guide"`）→ [查询文本任务](#api-text-task-get) | 见下方“[旅程引导回复](#p08-guide)” |
| 播报助手回复（可选） | [语音合成](#api-tts) → [查询语音任务](#api-voice-task-get) | 只能合成已完成的旅程引导回复 |
| 语音输入自由文本（可选） | [语音识别握手](#api-asr-ticket) | 识别结果作为该题 text 提交 |
| 旅程问答完成 | [提交答案](#api-interaction-answers)，U | 一次提交完整题集；成功后状态为 `ready` |
| 点击“出发” | [确认输入](#api-interaction-confirm)，U | 无 Body；只登记确认，不启动生成 |
| 生成旅程图片 | [创建图片任务](#api-image-task-create) → [查询图片任务](#api-image-task-get) | `{requestId,photo}`；完成后状态为 `generated` |
| 展示图片 | [读取本次体验作品预览](#api-work-preview) → [读取本次体验作品内容](#api-work-content) | 带请求头读取二进制后显示 |
| 结束 / 状态恢复 / 退出 | [结束体验](#api-interaction-end)、[查询体验](#api-interaction-get)、[退出登录](#api-identity-logout) | 须仍持有原设备与原登录会话；生成成功后才能以 `completed` 结束 |

### 自由文本与选择题

只在该题 `allowText=true` 时显示自由输入能力。每题提交 optionId 或 text 二者之一；text 非空、最多 2000 字符。题目和选项来自本次配置，用户输入目的地不等于可以任意增加新 questionId。

```json
{"answers":[{"questionId":"configured_choice_question","optionId":"configured_option"},{"questionId":"configured_text_question","text":"用户明确输入的旅程想法"}]}
```

此例仅演示两类答案混用；实际题数、ID 和自由文本开关均以配置为准。成功返回 `{state:"ready",tags:[...]}`。每条 text 在写入前送内容安全审核：未通过 422 `CONTENT_REJECTED`、未配置/不可用 503 `MODERATION_*`，整份答案均不写入（见“[内容安全](#formal-tasks-moderation)”）。

### 旅程引导回复（2026-10-06确认）

每步“助手回复”由模型实时生成，走 [创建文本任务](#api-text-task-create) 并计费（冻结/结算同公用规则）。请求 Body：

| 字段 | 规则 |
| --- | --- |
| requestId | 必填，最长 64；每次调用使用新的请求号；同一个请求号原样重发不会重复执行，返回第一次的任务 |
| purpose | 固定 `"guide"` |
| questionId | 必填，须为本次配置中的题目 |
| optionId / text | 二者必须且只能提交一个：optionId 须为该题配置选项；text 最多 2000 字，仅该题 allowText=true 时允许，发给模型前送内容安全审核（未开通/不可用直接报错，审核不通过返回 422） |

- 只能在授权后、提交全部 answers 之前、且没有运行中任务时调用（状态为 `questions`）；生成期间状态为 `running`，完成或明确失败后回到 `questions` 再继续作答或提交 answers。answers 最终一次性提交的规则不变。结果为 `unknown` 时体验停留在 `running`，不能继续作答（见 [任务状态与 Token 冻结](#formal-tasks-states)）。
- 服务端从配置读取题目文本，使用 AI图片生成配置的“旅程引导回复”说话方式（chatPrompt）与 chat 绑定模型；上下文为本次体验此前已完成的引导步骤（题目与回答，含自由文本）及回复，并注入结构化记忆（条数未登记时 409）；配置指定了知识库时附带知识全文。
- 结果在 [查询文本任务](#api-text-task-get) 的 `response` 中，为纯文本，不截断；模型未返回正文按“结果不符合约定”记 `unknown` 并保留冻结，不补固定文案。同一题可用新请求号再次调用，每次独立计费。
- 引导步骤会出现在 [查询体验](#api-interaction-get) 的 `messages` 中（purpose=`guide`，`user_text` 为该步题目与回答的 JSON 文本）。

### 出发与生成旅程图片

- 先提交全部答案，再调用 [确认输入](#api-interaction-confirm)（出发），之后调用 [创建图片任务](#api-image-task-create)，`photo` 必填（PNG/JPEG data URL，不超过 5MiB）。未确认出发返回 409。
- 照片在建任务前送内容安全审核，审核期间以临时对象存在，审核结束即删除，不保存为作品。生成提示词由后台配置与本次各题回答（选项文本或自由文本原文）组成。
- 生成图审核通过：任务 `completed`，作品自动审核通过可取件（子类 `journey`），体验状态变为 `generated`，本次体验不能再生成第二张。审核未通过：任务 `failed`、冻结冲正、不保存，体验回到 `ready`，用户可用新请求号再次生成（重新计费）。未登记内容安全或审核服务临时不可用：按通过处理，同“审核通过”，作品标记“未审核”（2026-10-13 确认）。

### AI图片生成正式语音（2026-10-06，A13）

接口、计费与错误同 AIVA面基正式语音。差异：

- [语音合成](#api-tts) 只能合成本次体验已完成的旅程引导回复（purpose=guide）。音色取 AI图片生成配置中后台登记的 `voice.params.voice`（助手播报音色）；未登记返回 409 `VOICE_NOT_CONFIGURED`，不使用默认音色或模型绑定上的音色。
- [语音识别](#api-asr-ticket) 仅在授权后、提交全部 answers 之前（状态 `questions`），且本次配置有允许自由文本的题目时可用；final.text 由客户端作为该题 text 提交到旅程引导回复（purpose=guide），届时做内容安全审核。

### 尚未验收

配置中的 stages 为 `consent, photo, questions, departure-confirmation, focus, generation`，它是页面流程清单，不代表都有对应接口：拍照没有单独上传接口，专注阶段（focus）没有采集或事件接口。专注阶段实际采集、终端 UI 和真实模型联调均未验收。

## P04｜共创工坊 · AI车衣共创

AI车衣共创（P04）：访客授权后选择“AI共创”或“DIY涂鸦”。AI共创（2026-10-10 Agent 配置）：前端从全部已启用风格中随机显示5个，用户点选，或说话/打字由模型从全部已启用风格中替用户选一个（2026-10-21 起不在库中时原样返回，服务端不替换）；配色由用户点选（前端从该风格全部配色中随机显示4种）；确认后服务端按三步生成：文本模型写绘图提示词 → 纸膜（参考图=纸膜模板）→ UV 贴图（参考图=纸膜结果；2026-10-14 起原“侧身效果图”改为 UV 贴图，Pad 做 360° 车模查看）。打印的是纸膜图。DIY 的取色、笔刷、图案与 3D 涂画由前端控制；**2026-10-15 起点“确认打印”时前端上传手绘 UV 图与底色，由服务端合成纸膜打印图**（底色非白色时先由模型改色），既是作品也可打印。打印（2026-10-11 起）改由独立的“作品打印台”完成：用户在打印台扫码查看并打印自己的作品，互动 Pad 不再发起打印。本章说明页面调用顺序、车衣配置、DIY数据结构，以及本章独有的接口。

AI车衣共创不提交问卷 answers，也不调用通用的[确认输入](#api-interaction-confirm)（会返回400）。**2026-10-14 起一个按钮一次调用**：风格对话一次返回风格；“去生成”一次提交风格配色并开始生成；DIY“确认打印”一次上传手绘 UV 与底色（2026-10-15 起服务端合成，立即返回任务号）。原“保存 / 读取 / 确认车衣方案”三个接口已删除。风格对话（2026-10-10 确认，2026-10-21 调整）：无论用户输入什么都由模型从库中选一个风格；**模型给的风格不在库中时原样返回**（带模型原文 `raw`），由前端自己决定怎么处理，服务端不再替换成兜底风格，见[风格对话](#p04-free)。

### 页面操作与调用顺序

| 步骤 | 页面 / 用户操作 | 调用 | 客户端处理 |
| --- | --- | --- | --- |
| 1 | 程序启动 | [读取互动配置](#api-interaction-config)，D | 校验 `pointId` 为 P04；读取 `wrap`、`assets`；保留 `version`、`policy` |
| 2 | 配置应用成功 | [确认配置版本](#api-interaction-config-ack)，D | Body `{version}` |
| 3 | 扫身份码 | [扫码登录](#api-point-login)，D | 保留 `sessionToken` |
| 4 | 隐私协议点“同意”后开始体验 | [开始体验](#api-interaction-create)，U | **2026-10-14 起开始体验即视为用户已同意授权**，不再调用“确认授权”；用户不同意就不要调用开始体验。保留 `interactionId` |
| 6 | AI共创：说话或打字描述（可选；`freeDescription` 为 `disabled` 时不显示输入入口） | [上传录音识别](#api-asr-upload) 或 [流式语音识别](#api-asr-ticket)（语音时，按点位所选识别模型）→ [创建文本任务](#api-text-task-create) `purpose:"style"`，U | **一次调用直接返回结果**（2026-10-14）。**2026-10-22 起由模型现编风格与 4 个配色**：显示 `response.style_reply`、风格名 `response.style_name`，4 个配色按 `response.colors[].hex` 画成色球（没有图标）；请求带 `speak:true` 时语音在 `voice.audio`；保留 `response.style_task_id` 与用户选的 `colors[].index`，作为“去生成”的 `styleTaskId`、`colorIndex`。`status=failed` 且 `failure.code=STYLE_PARSE_FAILED` 表示模型输出不符合约定，提示用户重说或点选默认风格。不说话时直接点选默认风格 |
| 7 | AI共创：选好风格和配色，点“去生成” | [创建图片任务](#api-image-task-create)，U | 默认风格 Body `{requestId,styleId,colorId,source}`；AI 生成风格 Body `{requestId,styleTaskId,colorIndex,source}`。服务端保存方案并开始三步生成（绘图提示词→纸膜→UV 贴图），**立即返回 `taskId`**；任一步失败整次失败、全部退回 Token、不计次数；“上一步”重选风格不需要调用任何接口 |
| 8 | 等待效果图 / 结果页 | [查询图片任务](#api-image-task-get)，U | 用 `taskId` 每隔几秒查一次，通常数十秒出图；完成时直接返回 `uvUrl`（UV 贴图，360° 车模用）与 `paperUrl`（纸膜打印图），不用再读取作品预览；体验进入 `generated`。作品小程序码待定（见[作品小程序码](#api-p04-mini-code)） |
| 9 | DIY：点“确认打印” | [DIY 确认打印](#api-p04-diy-work)，U | **2026-10-15 起**表单上传 `file`（手绘 UV，2048×2048 图片，PNG/JPEG/WebP 等）、`color`（底色 `#RRGGBB`，不传按白色）、`requestId`，**立即返回 `taskId`**；再用[查询图片任务](#api-image-task-get)取结果：完成时 `paperUrl`（纸膜打印图，作品，进小程序、可在作品打印台按 A4 打印）与 `uvUrl`（本次上传的手绘 UV）。白色底几秒内完成、不扣 Token；其他颜色要等模型改色（通常数十秒）、扣一次图片 Token |
| 11 | 修改后再生成 | 回到第6—8步 | 换风格或配色后再点“去生成”，用新的 `requestId`；见下方“再生成与生成次数” |
| 12 | 客户端可观察事件 | [上报观察事件](#api-p04-events)，U | 可选，不调用也不影响任何流程 |
| 12b | ~~去打印（AI共创 / DIY）~~ | （2026-10-11 停用） | 打印改由独立的“作品打印台”完成：用户在打印台扫码、选作品打印，互动 Pad 不再发起打印；[打印并分配作品号码](#api-p04-print-create) 返回 410 `PRINT_MOVED_TO_STATION` |
| 13 | 查看作品 | [本次体验作品](#api-works-list)，U | 已审核、已结算的作品才可取件 |
| 14 | 退出 | [退出登录](#api-identity-logout)，U | **2026-10-14 起只发这一个请求**：服务端顺带结束本次体验（有保存成功的作品记“完成”，没有记“放弃”），不用再调结束体验；仍有任务在执行时该体验不结束，返回 `notEnded` 说明原因。查余额（[当前用户](#api-identity-me)）按需调用即可 |
| — | 恢复页面状态 | [查询体验](#api-interaction-get)，U | 读取 `state` |

### 车衣配置与素材

[读取互动配置](#api-interaction-config)对AI车衣共创除公共字段外另返回：

| 字段 | 类型 / 内容 | 用法 |
| --- | --- | --- |
| `wrap.modes` | string[]，取值 `ai`/`diy` | 只显示已启用的模式 |
| （2026-10-10 移除）`wrap.baseAssetId` | — | 车辆底图已改为后台配置的纸膜/侧身两张模板，不下发给前端（Pad 不显示参考设计稿） |
| `wrap.styles` | array | AI共创**默认风格**（2026-10-22 起作为默认选项）：只下发已启用风格（发布须 ≥5 个），每项 `{id,label,colors}`；`colors` 为该风格的**全部配色**（≥4 种，后台可配 N 种），每项 `{id,label,hex,iconAssetId}`，图标用 `iconAssetId` 在 `assets` 中匹配（透明背景 PNG）。用户点选默认风格与配色时直接使用，不调大模型。不下发提示词、匹配关键词、模板与兜底设置 |
| `wrap.freeStyle` | `{enabled:boolean}` | 2026-10-22：是否允许自由输入由 AI 生成风格（后台开关，旧配置视为开启）。`false` 时不要显示说话/打字入口，风格对话会返回 409 |
| `wrap.display` | `{styles:5,colors:4}` | 前端每次从已启用风格中随机显示的风格数、从配色池随机显示的配色数（随机由前端完成） |
| `wrap.diy.stickers` | array | 后台登记的DIY图案（可为空）：每项 `{id,label,assetId}`，`assetId` 匹配 `assets`；DIY取色与笔刷由前端控制，不再下发色板与画笔尺寸 |
| （2026-10-11 移除）`wrap.print.sharedFolder` | — | 打印改由作品打印台完成，点位不再登记、不再下发打印共享文件夹 |
| `wrap.maxGenerations` | integer 或 null | 单次体验最多生成次数（含首次），后台登记；`null` 为未登记，此时生成请求返回409 |
| `wrap.resources` | object | 车辆资源包：`{version,vehicleModel,paintMask,uvLayout,paperTemplate,storeRole}`，后五项为素材编号，匹配 `assets`（类型分别为 3D模型、图片、图片或JSON、图片或PDF、图片）；2026-10-09 起后台不再配置（DIY 3D资源由互动前端自带），仅旧配置可能仍带此字段，客户端不要依赖 |
| `assets` | array | 本次用到的全部素材：每项 `{asset_id,asset_name,asset_type,mime_type,checksum,cdn_url,width,height}`；`cdn_url` 为已登记的 HTTPS 地址，直接使用，不自行拼路径 |
| `freeDescription` | `"ai_generate"` / `"disabled"` | 2026-10-22 起：文字/语音描述由大语言模型现编风格名与 4 个配色（名称+色值），即使说中默认风格名也现编；后台关闭自由输入时为 `disabled`（取代 `library_match`） |
| `printingImplemented` | `false` | 2026-10-11 起 Pad 不发起打印（改由作品打印台完成）；此前为 `true` |
| `stages` | `consent, mode, design, generation, result` | 流程阶段（2026-10-11 去掉 `print`；2026-10-14 去掉 `design-confirmation`，方案随生成/确认打印一次提交） |

`assets` 保留下划线命名。底图、图案或资源包素材缺失、未审核、不在本门店范围或没有 HTTPS 地址时，读取配置直接报错；客户端不能改用其他图片替代。

### DIY数据结构

**2026-10-15 起 DIY 确认打印不再提交 `design`**：服务端按上传的底色保存方案 `{mode:"diy",baseColor,strokes:[],stickers:[]}`，下表仅作历史结构说明。所有坐标、大小都是相对画布的 0—1 比例。

| design 字段 | 类型 / 限制 | 必填 |
| --- | --- | --- |
| `baseColor` | string，任意 `#RRGGBB` | 是 |
| `strokes` | array，最多200条，可为空数组 | 是 |
| `strokes[].color` | string，任意 `#RRGGBB` | 是 |
| `strokes[].size` | number，0.0001—1（相对画布） | 是 |
| `strokes[].brush` | string，前端笔刷编号，1—64 位字母、数字或 `_.-` | 否 |
| `strokes[].points` | `[x,y][]`，每笔1—500个点，全部笔画合计不超过10000个点；x、y 为 0—1 | 是 |
| `strokes[].opacity` | number，0—1 | 否 |
| `stickers` | array，最多100项，可为空数组 | 是 |
| `stickers[].id` | string，图案编号（前端内置或 `wrap.diy.stickers`），1—64 位字母、数字或 `_.-` | 是 |
| `stickers[].x` / `y` | number，0—1 | 是 |
| `stickers[].scale` | number，0.01—1 | 是 |
| `stickers[].rotation` | number，-360—360 | 是 |
| `stickers[].color` | string，任意 `#RRGGBB`（图案着色） | 否 |

颜色大小写不限，服务端统一保存为大写。

体验结束（完成、放弃、撤回授权）后，服务端清除方案明细：AI方案只保留风格与颜色，DIY方案只保留 `baseColor`，并带 `cleared:true`；笔画、图案不再保留。

### 上报观察事件
#### 功能描述

登记客户端能观察到的操作事件（E01—E11），用于统计分析。服务端只接受白名单字段，不接受原始文字、涂鸦轨迹、URL 等内容；事件不改变生成任务、计费或打印状态，“打印发送”事件也不代表后台已接收或已出纸。各事件的业务含义以AI车衣共创埋点设计为准（待确认）。

同一个 `requestId` 连同相同内容原样重发不会重复登记，返回第一次的事件编号。

| code | 允许的 payload 字段（`creationId` 均必填） |
| --- | --- |
| E01 | `creationId` |
| E02 | `creationId`、`mode`、`source` |
| E03 | `creationId`、`styleId`、`colorId`、`source`、`stage` |
| E04 | `creationId`、`taskId`、`stage`、`observedResult`、`durationMs`、`errorCode` |
| E05 | `creationId`、`count`、`step` |
| E06 | `creationId`、`previousCreationId`、`fromMode`、`toMode`、`step` |
| E07 | `creationId`、`sendId`（必填） |
| E08 | `creationId`、`exitType`、`step`、`durationMs`、`printInitiated` |
| E09 | `creationId`、`tool`（必填）、`count`（必填） |
| E10 | `creationId`、`errorCode`、`source`、`count` |
| E11 | `creationId`、`reminderId`、`step`、`action` |

字段取值：`mode`/`fromMode`/`toMode` 为 `ai`、`diy`；`source` 为 `preset`、`voice`、`text`、`start`、`switch`；`stage` 为 `preset`、`style`、`color`、`effect`；`observedResult` 为 `started`、`success`、`failed`、`cancelled`、`unknown`；`tool` 为 `color`、`brush`、`opacity`、`pattern_select`、`pattern_apply`、`rotate`、`undo`、`reset`；`exitType` 为 `manual`、`after_send`、`idle`；`action` 为 `continue`、`exit`；`count` 为正整数，`durationMs` 为非负整数；`printInitiated` 为布尔值；其余字段为 1—64 位字母、数字或 `_.:-` 组成的编码。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `requestId` | Body | string | 必填 | 事件请求号，1—64 字符 | `evt-0007` |
| `code` | Body | string | 必填 | `E01`—`E11` | `E09` |
| `occurredAt` | Body | string | 必填 | 发生时间，北京时间并带 `+08:00`，可带毫秒 | `2026-10-08T10:00:00+08:00` |
| `payload` | Body | object | 必填 | 按上表的白名单字段 | `{"creationId":"c1","tool":"brush","count":3}` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_7d3e/events" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"evt-0007","code":"E09","occurredAt":"2026-10-08T10:00:00+08:00","payload":{"creationId":"c1","tool":"brush","count":3}}'
```

#### 返回示例（HTTP 200）

```json
{
  "eventId": "obs_4be1…",
  "received": true,
  "source": "point",
  "note": "只登记客户端可观察事件。打印发送不代表后台接收、送达或实际出纸；任务状态以ai_task为准。"
}
```

同一 `requestId` 原样重发：`{"eventId":"obs_4be1…","idempotentHit":true}`。

| 返回字段 | 说明 |
| --- | --- |
| `eventId` | 事件编号，由体验与 `requestId` 决定 |
| `received` | 恒为 `true` |
| `source` | 恒为 `point`（点位上报） |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是AI车衣共创；`requestId` 格式错误；`code` 不在 E01—E11；`occurredAt` 不是带 `+08:00` 的有效北京时间；`payload` 不是对象、含未定义字段、取值无效或缺少必填字段 | 修正事件内容，不要上报原始文本或轨迹 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 核对 `interactionId` |
| 409 | 同一 `requestId` 已用于不同事件内容；会员主账户已变更 | 新事件换新 `requestId` |

### 风格对话（文字 / 语音）

🔴 **2026-10-22 用户确认（共创工坊提出，docs/develops/42）：默认风格与自由输入分开。**
- **默认风格**：`wrap.styles` 里的风格与配色是共创工坊上的默认选项，用户点选时直接用，去生成传 `styleId`+`colorId`，不调大模型。
- **自由输入**：用户说话或打字时，**一律由大模型现编一个风格名和 4 个配色（名称+色值）**，即使用户说中默认风格名（如“赛博朋克”）也现编一套；不再从风格库里匹配（取代 2026-10-10 D1/D2 与 2026-10-21 的“原样返回库匹配结果”）。
- 后台可关闭自由输入（`wrap.freeStyle.enabled=false`，`freeDescription="disabled"`），关闭后风格对话返回 409。

- 文字：调用 [创建文本任务](#api-text-task-create)，Body `{"requestId","purpose":"style","text"}`，`text` 1—2000 字；用户文字先送内容安全审核。可在授权后、没有运行任务时调用（`state` 为 `questions`、`ready`、`generated`），可反复调用（用户回上一步重说），本次配置须开放AI共创并开启自由输入。正常计费。
- 语音：点位选“录音文件识别极速版”时，录完整段用 [上传录音识别](#api-asr-upload) 拿到 `text`；选“大模型流式语音识别”时，先 [语音识别握手凭据](#api-asr-ticket) → [流式语音识别](#api-asr-ws) 拿到 `final.text`。拿到文字后按上一条提交。请求里带 `speak:true` 时这句回复的语音随结果一起返回（`voice.audio`）；播的是 `style_reply`，音色取车衣配置里登记的 `voice.params.voice`，未登记返回 409 `VOICE_NOT_CONFIGURED`。
- 结果（**同一次调用直接返回**）：`status=completed` 时 `response` 为 JSON 字符串：

```json
{"code":0,"mode":"generated","style_task_id":"task_3f1e…","raw":"{\"reply\":\"海边日落很浪漫呀！给你设计一款落日海岸风，暖橙渐变到海蓝，像把黄昏披在车身上。\",\"style\":\"落日海岸\",\"colors\":[…]}","style_name":"落日海岸","style_reply":"海边日落很浪漫呀！给你设计一款落日海岸风，暖橙渐变到海蓝，像把黄昏披在车身上。","colors":[{"index":0,"name":"落日橙","hex":"#F39C4A"},{"index":1,"name":"晚霞珊瑚","hex":"#E8735A"},{"index":2,"name":"海岸蓝","hex":"#2E86C1"},{"index":3,"name":"沙滩金","hex":"#F7DC6F"}],"reply_text":"海边日落很浪漫呀！给你设计一款落日海岸风，暖橙渐变到海蓝，像把黄昏披在车身上。,落日海岸,落日橙#F39C4A,晚霞珊瑚#E8735A,海岸蓝#2E86C1,沙滩金#F7DC6F"}
```

  - `style_name`：模型现编的风格名（2—12 字，服务端校验不超过 16 字）。
  - `style_reply`：给用户看、也是播报的那一句（不含色值）。
  - `colors`：恰好 4 个，按顺序带 `index`（0—3）、`name`（配色名）、`hex`（`#RRGGBB`，大写）。**没有图标**，前端按色值画色球。
  - `style_task_id`：本次风格对话的任务号（与返回外层的 `taskId` 相同）；去生成时传 `styleTaskId`，再传用户选的配色 `colorIndex`。
  - `raw`：模型原文，排查用。`reply_text`：兼容字段，`回复,风格名,配色名#色值×4` 的逗号串（给原来的 `parse_style_and_colors` 用），**不是回复正文**。
- **模型输出不符合约定**（不是 JSON、缺回复、风格名为空或过长、配色不是恰好 4 个、色值不是 `#RRGGBB`、配色名重复）：本次任务 `status=failed`，`failure.code="STYLE_PARSE_FAILED"`，`failure.message` 写明哪一项不符合，不扣 Token；服务端记一条事件日志 `p04.style_parse_failed`（含模型原文），**不补兜底风格、不补默认配色**。前端提示“没听清，请再说一次或选择默认风格”，用户可直接重说（新的 `requestId`）。
- 用户点“去生成”时调用 [创建图片任务](#api-image-task-create)：AI 生成风格提交 `{requestId,styleTaskId,colorIndex,source:"text"|"voice"}`；默认风格提交 `{requestId,styleId,colorId,source:"preset"}`。一次完成保存方案与开始生成。
- 生成时：风格名、配色名与色值都写进绘图提示词（`{color_text}` 形如“海岸蓝（#2E86C1）”），“用户原始想法”由服务端取本次体验中用户在风格对话里说过的话（未说话为空），客户端不用传。
- 画像：默认风格按风格、配色编号记标签；AI 生成风格统一记“风格·AI自由创作”，具体风格名保存在方案里。
- 播报任意一段文字（2026-10-22，共创工坊提出）：调 [语音合成](#api-tts)，Body `{requestId,text}`，前端传什么念什么（如页面引导语）；不送内容安全审核，按字数计费，字数上限为 `voice.tts_max_chars`，音色同上。只播风格对话回复时用 `speak:true` 即可。

### DIY 确认打印（上传手绘 UV，服务端合成纸膜打印图）
#### 功能描述

DIY 页面点“确认打印”时调用一次（2026-10-15，依据共创工坊开发 `ai_align.py`）。前端用 `multipart/form-data` 上传用户在 3D 车模上画好的**手绘 UV 图**与**底色**，服务端：

1. 保存并确认方案（DIY、底色）；手绘 UV 统一转成 PNG；
2. 底色为白色 `#FFFFFF`：直接用后台配置的纸膜底图；其他颜色：由图像模型把纸膜底图的车漆改成该颜色（冻结一次图片调用的 Token；改色图按其他生成图同样做内容审核）；
3. 把手绘 UV 按后台贴合参数切成三块、贴到纸膜的左侧面 / 俯视 / 右侧面，最上层盖光影蒙版；调了模型改色时在右下角空白处加“AI 生成”标识；
4. 纸膜打印图（JPEG）保存为 **DIY 作品**（`asset_subtype=car_wrap_diy`，同步 AIVA 小程序、可在作品打印台按 A4 打印）；手绘 UV 原图保存为本次体验的记录（`car_wrap_diy_uv`，不进作品列表、不能打印、不推送）。

接口**立即返回 `taskId`**，前端用[查询图片任务](#api-image-task-get)取结果（完成时返回 `paperUrl` 与 `uvUrl`）。白色底几秒内完成、不扣 Token；其他颜色通常数十秒。手绘 UV 不做内容审核（2026-10-09 确认 DIY 成图不审）。DIY 不计入“单次体验最多生成次数”。

失败处理：改色明确失败、改色图审核不通过或合成失败 → 任务 `failed`、冻结全额冲正、不出图（不会改用白色出图），可换 `requestId` 重新提交；通信结果未知 → `unknown`、保留冻结待运营核对。同一 `requestId` 原样重发返回原任务、不重复扣 Token。**同一次体验里手绘 UV 与底色都相同的再次提交**（即使 `requestId` 不同，如连点或调试工具自动换号）也返回第一次的任务（`status:"existing"`、`duplicate:true`），不重新合成、不新增作品、不扣 Token；原任务失败或取消的可以重新提交，改过画或颜色照常提交（2026-10-15）。

#### 请求参数（Path / 表单）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `file` | 表单文件 | 图片 | 必填 | 手绘 UV 图，**必须 2048×2048**；格式为常见图片（2026-10-15 起 `image/*`：PNG、JPEG、WebP、GIF（取第一帧）、AVIF、TIFF；不收 SVG），服务端统一转成 PNG 保存与合成；不缩放、不补边，尺寸或格式不对返回 400。**JPEG 等没有透明通道，没画到的部分会整块盖住纸膜底色**，要透出底色请用带透明的 PNG/WebP | `uv.png` |
| `color` | 表单字段 | string | 选填 | 底色 `#RRGGBB`（可省略 `#`）；**不传按白色 `#FFFFFF` 处理**（不改色） | `#1F4FD8` |
| `requestId` | 表单字段 | string | 必填 | 本次提交请求号，1—64 字符 | `diy-submit-001` |

只接受以上三个字段；整个请求不超过 12 MB。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_7d3e/diy-works" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -F "file=@uv.png;type=image/png" \
  -F "color=#1F4FD8" \
  -F "requestId=diy-submit-001"
```

#### 返回示例（HTTP 200）

```json
{ "taskId": "task_5b1e…", "status": "queued", "idempotentHit": false, "designRevision": 3, "note": "（说明文字，内容以实际返回为准）" }
```

| 返回字段 | 说明 |
| --- | --- |
| `taskId` | 任务号，用[查询图片任务](#api-image-task-get)取结果 |
| `status` | `queued`：已开始合成；`existing`：同一 `requestId` 重发，或本次体验已提交过相同内容，返回原任务 |
| `duplicate` | 因内容相同返回原任务时为 `true` |
| `idempotentHit` | 同一 `requestId` 重发时为 `true` |
| `designRevision` | 本次保存的方案修订号 |

查询完成时（`status=completed`）：

```json
{ "taskId": "task_5b1e…", "status": "completed", "assetId": "asset_77c2…", "uvAssetId": "asset_77c2…", "paperAssetId": "asset_e0a4…",
  "uvUrl": "https://cdn.example.com/generated/…/uv.png", "paperUrl": "https://cdn.example.com/generated/…/paper.jpeg", "billing": null }
```

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是AI车衣共创；表单缺少 `file` 或有多个 `file`、含未支持字段；`requestId` 格式错误；`code=UV_INVALID`：手绘 UV 不是 2048×2048，或不是可识别的图片（如 SVG、BMP）；`code=COLOR_INVALID`：`color` 不是 `#RRGGBB`；本次配置未开放 DIY | 修正请求 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 体验不存在或不属于当前设备与登录用户 | 核对 `interactionId` |
| 409 | 未授权或授权已撤回；上一次生成或合成还没结束；体验已结束；同一 `requestId` 已用于不同的 UV 或底色；后台未配置 DIY 纸膜合成设置（底图、光影蒙版、改色提示词） | 按提示处理；同一提交重发用原 `requestId` |
| 413 | 请求体超过 12 MB | 压缩 UV 图（2048×2048 的 PNG/WebP 通常远小于 12 MB） |
| 415 | 不是 `multipart/form-data` | 改用表单上传 |

### 打印并分配作品号码
#### 功能描述

> **2026-10-11 停用**：打印改由独立的“作品打印台”完成（用户在打印台扫码、选作品打印，见 `docs/ux/作品打印台-简版PRD-V0.2.html`），互动 Pad 不再发起打印，本接口一律返回 410 `code=PRINT_MOVED_TO_STATION`。以下为停用前的说明，供已建立的打印单对照。

为一个作品（AI共创侧身作品或 DIY 成图）分配作品号码并建立打印单；AI共创作品由服务端自动换成对应的纸膜图打印（2026-10-10），返回打印共享文件夹地址与建议文件名。打印由前端完成：前端读取作品内容（[作品内容](#api-works-list) 的 content 接口），把作品经局域网写入共享文件夹，再[回报打印结果](#api-p04-print-report)。AgentOS 不连门店局域网。

- 作品号码：门店每天从 `001` 编起（北京时间0点重新开始，同门店所有点位共用，显示至少3位）。号码显示在 iPad 上，用户凭号码到纸膜打印处领取；号码不打印在图纸上（2026-10-09 确认），打印处可按文件名中的号码对应作品。
- 同一作品只分配一次号码：再次请求（换 `requestId` 也一样）返回原打印单与原号码，`idempotentHit:true`。
- 只给可取件的作品分配：审核通过、计费已核对（DIY 无计费）、授权未撤回、未删除未过期。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `requestId` | Body | string | 必填 | 请求号，1—64 字符 | `print-001` |
| `assetId` | Body | string | 必填 | 本次体验的作品编号 | `asset_1c9e…` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_7d3e/print-jobs" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"print-001","assetId":"asset_1c9e"}'
```

#### 返回示例（HTTP 200）

```json
{
  "printJobId": "wpj_5b2a…",
  "assetId": "asset_1c9e",
  "workNo": "023",
  "bizDate": "2026-10-09",
  "sharedFolder": "\\\\192.168.1.20\\车衣打印",
  "fileName": "20261009_023.png",
  "status": "pending",
  "attempts": 0,
  "lastError": null,
  "sentAt": null,
  "createdAt": "2026-10-09T02:30:15.000Z",
  "idempotentHit": false
}
```

| 返回字段 | 说明 |
| --- | --- |
| `workNo` | 作品号码，显示给用户用于领取，不打印在图纸上 |
| `sharedFolder` | 分配号码时本互动后台登记的打印共享文件夹（`\\主机\共享名` 或 `smb://主机/共享名`） |
| `fileName` | 建议写入的文件名：`yyyyMMdd_作品号码.扩展名` |
| `status` | `pending` 待发送 / `sent` 已发送 / `failed` 发送失败 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是AI车衣共创；含未支持字段；`requestId`、`assetId` 为空、超长或含控制字符 | 修正请求 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 体验或作品不存在，或作品不属于本次体验 | 核对编号 |
| 409 | `code=PRINT_NOT_CONFIGURED`：本次配置未登记打印共享文件夹；同一 `requestId` 已用于其他作品；作品未通过审核、计费未核对完成或存储配置不一致 | 配置问题联系运营；作品状态问题等待后再试 |
| 410 | `code=PRINT_MOVED_TO_STATION`（2026-10-11 起一律返回）：打印改由作品打印台完成；作品已删除、已过期或授权已撤回 | 不在 Pad 上发起打印 |

### 回报打印结果
#### 功能描述

> **2026-10-11**：Pad 已不再新建打印单（打印改由作品打印台完成），本接口只用于改版前已建立的打印单。

前端把作品写入共享文件夹后回报结果。写入失败可再次写入并再次回报，号码不变。[查询打印单](#api-p04-print-get)可读取最新状态。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `jobId` | Path | string | 必填 | 打印单编号 `printJobId` | `wpj_5b2a…` |
| `result` | Body | string | 必填 | `sent` 已写入 / `failed` 写入失败 | `sent` |
| `error` | Body | string | 失败必填 | 失败原因，1—255 字；`sent` 时不能传 | `共享文件夹不可写` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/report" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"result":"sent"}'
```

#### 返回示例（HTTP 200）

```json
{ "printJobId": "wpj_5b2a…", "assetId": "asset_1c9e", "workNo": "023", "bizDate": "2026-10-09", "sharedFolder": "\\\\192.168.1.20\\车衣打印", "fileName": "20261009_023.png", "status": "sent", "attempts": 1, "lastError": null, "sentAt": "2026-10-09T02:30:20.000Z", "createdAt": "2026-10-09T02:30:15.000Z" }
```

| 返回字段 | 说明 |
| --- | --- |
| `status` | 最新回报结果 |
| `attempts` | 累计回报次数 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是AI车衣共创；`result` 不是 `sent`/`failed`；`failed` 缺失败原因或 `sent` 带了失败原因 | 修正请求 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 打印单不存在或不属于本次体验 | 核对编号 |

### 查询打印单
#### 功能描述

> **2026-10-11**：Pad 已不再新建打印单（打印改由作品打印台完成），本接口只用于改版前已建立的打印单。

读取打印单与作品号码，用于页面恢复。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `jobId` | Path | string | 必填 | 打印单编号 | `wpj_5b2a…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

与[打印并分配作品号码](#api-p04-print-create)返回结构相同（无 `idempotentHit`）。

| 返回字段 | 说明 |
| --- | --- |
| `workNo` | 作品号码 |
| `status` | `pending` / `sent` / `failed` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 打印单不存在或不属于本次体验 | 核对编号 |

### 下载打印文件
#### 功能描述

> **2026-10-11**：Pad 已不再新建打印单（打印改由作品打印台完成），本接口只用于改版前已建立的打印单。

取得打印单对应的打印文件字节，前端写入打印PC共享文件夹。AI共创作品的打印文件是对应的纸膜图；纸膜图不进入作品列表，只能经打印单取得（Pad 不显示）。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `jobId` | Path | string | 必填 | 打印单编号 | `wpj_5b2a…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/file" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" -o 20261010_023.jpg
```

#### 返回示例（HTTP 200）

图片字节，`Content-Type` 为 `image/jpeg` 或 `image/png`，`Content-Disposition` 带建议文件名（与打印单 `fileName` 一致）。

| 返回字段 | 说明 |
| --- | --- |
| （响应体） | 打印文件本身 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 打印单或作品不存在、不属于本次体验 | 核对编号 |
| 409 | 作品未通过审核或计费未核对完成 | 稍后再试 |
| 410 | 作品已删除、过期或授权已撤回 | 不能打印 |

### 作品小程序码
#### 功能描述

取一个作品的小程序码图片，显示在**互动最终结果页**（AI共创效果图、DIY 完成后），用户扫码在 AIVA 小程序查看/下载该作品。与打印无关：打印由作品打印台完成（用户在打印台扫自己的体验码），不再有作品号码。

- 一个作品一个小程序码参数 `scene`（随机，不含作品编号），重复请求返回同一个 `scene`；图片每次向 AIVA 现取，可直接重复调用。
- 只能取本次体验中可取件的作品：AI共创的侧身效果图（纸膜图不进小程序）或 DIY 成图；须已审核通过、计费已核对、授权未撤回、未删除。
- **AIVA 后端接口尚未就绪（2026-10-11）**：M01 作品码请求体 `{"type":"work","scene"}` 与小程序取作品接口为 AgentOS 拟定，收到 AIVA 接口文档后按其契约调整；联调前本接口会因 M01 未登记返回 409 `SUNCODE_NOT_CONFIGURED`。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `assetId` | Path | string | 必填 | 作品编号（图片任务完成返回的 `assetId`，或 DIY 成图提交返回的作品编号） | `asset_1c9e…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_7d3e/works/asset_1c9e/mini-code"   -H "Authorization: Bearer $DEVICE_CREDENTIAL"   -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{ "assetId": "asset_1c9e…", "scene": "w3f9a…（31字符）", "image": "data:image/png;base64,iVBOR…" }
```

| 返回字段 | 说明 |
| --- | --- |
| `image` | 小程序码图片 data URL，直接显示 |
| `scene` | 小程序码参数（同一作品不变） |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 当前设备不是AI车衣共创；作品是纸膜图等不能进小程序的图片 | 传侧身效果图或 DIY 成图的作品编号 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 作品不存在或不属于本次体验 | 核对编号 |
| 409 | 作品未通过审核或计费未核对完成；`code=SUNCODE_NOT_CONFIGURED`：AIVA 太阳码接口未登记 | 结果页不显示小程序码；后者联系运营登记 |
| 410 | 作品已删除或授权已撤回 | 不显示小程序码 |
| 502 | `code=SUNCODE_FAILED`：AIVA 接口超时、返回错误或非图片 | 显示失败；用户可主动重试 |

### 打印单小程序码（改版前）
#### 功能描述

> **2026-10-11**：新作品改用[作品小程序码](#api-p04-mini-code)按作品取。本接口只对改版前已建立的打印单有效。

生成打印单对应作品的小程序码图片，扫码后在 AIVA 小程序查看/下载本次作品。**AIVA 后端接口尚未就绪（2026-10-09）**：以下 M01 作品码请求方式为 AgentOS 拟定，收到 AIVA 接口文档后按其契约调整，联调前本接口会因 M01 未登记返回409。AgentOS 调用已登记的 AIVA 太阳码接口（M01，请求带 `type:"work"`、`scene`、`workNo`）；小程序凭 `scene` 与会员 ONEID 向 AgentOS 查作品。M01 未登记、调用失败或返回非图片时直接报错，不出占位码；每次调用都会请求 AIVA，前端可自行缓存本次页面的图片。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前体验的 `interactionId` | `ix_7d3e…` |
| `jobId` | Path | string | 必填 | 打印单编号 | `wpj_5b2a…` |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_7d3e/print-jobs/wpj_5b2a/mini-code" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{ "printJobId": "wpj_5b2a…", "workNo": "023", "scene": "w3f9a…（32字符）", "image": "data:image/png;base64,iVBOR…" }
```

| 返回字段 | 说明 |
| --- | --- |
| `image` | 小程序码图片 data URL，直接显示 |
| `scene` | 小程序码参数 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | 打印单不存在或不属于本次体验 | 核对编号 |
| 409 | `code=SUNCODE_NOT_CONFIGURED`：AIVA 太阳码接口未登记 | 页面只显示作品号码，联系运营登记 |
| 502 | `code=SUNCODE_FAILED`：AIVA 接口超时、返回错误或非图片 | 显示失败；用户可主动重试 |

### 再生成与生成次数（2026-10-06确认）

- 点“去生成”即调用[创建图片任务](#api-image-task-create)（默认风格 Body `{requestId,styleId,colorId,source}`；AI 生成风格 Body `{requestId,styleTaskId,colorIndex,source}`），生成成功即保存为作品。DIY 不调用生成模型。
- 生成完成（`state` 为 `generated`）后，同一体验内可换风格或配色再点“去生成”（新的 `requestId`）。每次正常计费，每次结果各自保存为作品。
- 次数上限为配置 `wrap.maxGenerations`（含首次）：排队、执行中、完成和待核对的任务都计入，明确失败或取消（已冲正）的不计；未登记或已达上限返回409。
- 生成中或结果待核对时不能再次生成（返回409“上一次生成还没有结束”）。

### 内容安全与未开放能力

- AI车衣共创审核用户自由描述文字（发给模型前，见[内容安全](#formal-tasks-moderation)）和生成图片；DIY 成图不在已确认的审核范围。生成图片：通过则作品自动审核通过、可取件；不通过（BLOCK/REVIEW）任务失败（`code` 为 `CONTENT_REJECTED`），冲正冻结、不保存、不计入次数上限；未登记内容安全或审核服务临时不可用时按通过处理，作品标记“未审核”（2026-10-13 确认）。详见“公用·正式文本与图片任务·内容安全”。
- 打印（2026-10-11 起）由独立的作品打印台完成，互动 Pad 不再发起打印；AI共创打印的是纸膜图（Pad 不显示）。作品打印台的接口另行提供。
- 内容安全未开通期间，平台可临时打开“跳过内容安全审核（调试）”，见[内容安全](#formal-tasks-moderation)。

## 公用｜连接与鉴权

| 项目 | 内容 |
| --- | --- |
| 本地后端 Base URL | `http://localhost:60662` |
| 生产 Base URL | 部署方提供的HTTPS域名；当前未登记，不猜测生产地址 |
| 完整 URL | Base URL + 本文路径；例如 `http://localhost:60662/api/point-display/config` |
| 普通请求体 | UTF-8 JSON，`Content-Type: application/json` |
| 成功响应 | HTTP 200，直接返回业务JSON；**没有统一的code/data包裹层** |
| 错误响应 | 非2xx，`{"error":"具体错误说明"}`；调用方以HTTP状态判断，不能要求固定数字业务码 |
| 路径变量 | `:id`、`:uid`、`:oneId`等必须替换并用encodeURIComponent编码 |
| 标识符 | 当作字符串保留，区分大小写；导出分页id可能是数字字符串，不转成浮点数 |
| 时间 | 业务按北京时间UTC+8；asOf为带Z的ISO UTC时间，按时区转换展示 |

| HTTP状态 | 常见含义 |
| --- | --- |
| 400 | 参数格式、必填项、枚举或业务校验失败 |
| 401 | 凭证缺失、过期、无效；身份失效时重新登录，不降级匿名 |
| 403 | 权限或数据域未授权 |
| 404 | 资源不存在或不在调用方数据范围 |
| 409 | 修订冲突、流程状态不允许、配置未发布或身份归集受冻结金额阻止 |
| 413 | 请求体/上传文件超过限制 |
| 422 | 内容安全审核未通过（code=CONTENT_REJECTED，见“公用·正式文本与图片任务·内容安全”） |
| 500 / 503 | 服务端错误或依赖未就绪；不伪造成功结果。（2026-10-13 起内容安全未登记或不可用时按通过处理，不再返回 503 `MODERATION_*`） |

错误响应中的 error 是说明文本，不是稳定业务码。下文按场景说明处理方式，不应在代码中硬编码匹配整句中文错误。

### 设备与用户会话请求头

| 标记 | 适用请求 | 请求头 |
| --- | --- | --- |
| D | 展示配置/回执、互动配置/ACK、扫码登录 | `Authorization: Bearer <设备凭证>` |
| U | 当前用户资料、创建和操作互动、注销 | D + `X-Identity-Session: <sessionToken>` |

设备凭证由AgentOS系统生成：每个互动点位一个互动客户端设备（设备编号 `{门店编号}-{点位编号}-APP`），密钥为256比特随机数（64位十六进制字符）；新建门店时随互动点位自动生成，已有点位在后台“点位详情 → 设备接入”点“生成设备凭证”，在同一处默认脱敏显示、点“复制”取用、可“重新生成”（旧密钥立即失效）。一台设备绑定具体门店/点位。**安全提醒**：凭证写在网页的配置文件里时，任何能打开该网页地址的人都能看到，可冒充本点位调用接口；建议互动网页地址只在门店专用局域网可访问（待部署方确认），发现泄露立即在“设备接入”重新生成。用户sessionToken来自扫码登录响应，两者不可互换；不使用后台Cookie，不在客户端持有集团应用密钥。退出后清除本地用户会话和用户画面，不把凭证写入日志。

```bash
curl -X POST "http://localhost:60662/api/identity/point-login" \
  -H "Authorization: Bearer REPLACE_WITH_DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"kind":"card","code":"REPLACE_WITH_CARD_CODE"}'
```

## 公用｜扫码登录、当前用户与退出

点位扫描来宾卡正面码或 AIVA 小程序会员码完成登录，之后用登录得到的用户会话读取当前用户与资料，体验结束时退出。所有接口都由互动点位客户端调用；纯展示点位的设备不能调用。

### 读取扫码器兼容设置

#### 功能描述

进入扫码页时读取，只需设备凭证，无需用户登录；播控接口清单已包含此路径。后台配置位置：用户与来宾卡 → 身份服务设置 → 扫码器设置，全平台共用。保存后重新进入扫码页生效。

`normalizeCardCase`仅兼容来宾卡网址路径及短码大小写（规范为`/c/`与大写14位短码），不转换AIVA会员token大小写；`mergeRepeated`将连续同一码合成一次，混合不同码仍拒绝；`quietSubmit`控制无回车/Tab时是否按静默结束识别；`quietMs`为100—5000毫秒，`keyGapMs`为100—10000毫秒且不小于前者。上述示例为迁移073的初始配置，运行以后台保存值为准，不在客户端用硬编码值替代读取失败。回车、Tab结束始终支持；设置只影响输入兼容，不改变身份接口的码长和鉴权规则。

#### 请求参数

无需Body或查询参数；设备凭证使用Authorization请求头。

#### 请求示例

```bash
curl "$BASE/api/identity/scan-settings" -H "Authorization: Bearer $DEVICE_CREDENTIAL"
```

#### 返回示例

```json
{"normalizeCardCase":true,"mergeRepeated":true,"quietSubmit":true,"quietMs":400,"keyGapMs":1000}
```

#### 错误情况

设备凭证无效返回401；扫码设置未初始化时返回配置错误，请检查迁移073，并前往身份服务设置中的扫码器设置。不得在读取失败时自行假设参数或提交不完整身份码。

### 扫码登录
#### 功能描述

校验访客出示的身份码并建立用户会话（2026-10-13 起）。支持两种码：

- **来宾卡正面码**：离店短码（14 位）或 `…/c/短码` 链接。来宾卡第一次在点位使用时记录激活点位。
- **AIVA 小程序会员码**：会员在 AIVA 小程序打开的会员码，二维码内容原样传入。AgentOS 拿这个码调用 AIVA“二维码扫码识别”接口换出 ONEID（见《ONEID 会员对外接口文档》“二维码扫码识别”：http://aiva.docs.vavedigital.com/api-docs/oneid.html#identity-aiva-scan ）。该 ONEID 在 AgentOS 还没有账户时，本次登录自动建档（`createdUser: true`），并通知 AIVA 绑定结果。2026-10-15 起 AIVA 扫码识别只返回 ONEID，扫码不再更新昵称、头像（此前已保存的保留）。

扫码时可以不传 `kind`，由服务端按码的格式判断（2026-10-13）：

| 扫到的内容 | 判断 |
| --- | --- |
| `http(s)://…/c/{14位短码}` 链接（不带 `?` 参数和 `#`），或 14 位短码本身（数字和大写字母，不含 I、L、O、U） | 来宾卡 |
| 32 位小写十六进制字符串（只含 0—9、a—f），例如 `d610c969d83400e82df17d7bc67c4821` | AIVA 小程序会员码（临时 token，2026-10-13 AIVA 确认 32 位） |
| 其他（印刷卡号、其他网址、乱码等） | 直接返回 400 `code=CODE_INVALID`“无法识别的二维码”，**不会**送 AIVA 识别 |

两种格式长度不重叠（14 位与 32 位），不会互相误判。会员码位数不是 32 位、或含大写字母的，按无法识别处理。已绑定 ONEID 的身份统一登录到该会员的主账户（最早创建的账户）。

**AIVA 会员码只能用一次。** AIVA 识别失败、连不上或 AgentOS 未登记 AIVA 网关时，登录直接失败，不改用其他身份；需要重扫时请会员在小程序里刷新会员码。原 AgentOS 自己签发的一次性会员凭据（`memberTicket`，`kind=member`）已于 2026-10-13 停用。

调用时机：访客在点位开始互动、需要识别身份时。每个点位各自登录，会话不能转交给其他点位。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `kind` | string | 可选 | `card`：来宾卡正面码；`aiva`：AIVA 小程序会员码；不传时由服务端按码的格式判断（推荐不传）。传 `member` 返回 400 | `card` |
| `code` | string | 必填 | 扫到的二维码内容原样传入，最长 2048 字符。来宾卡为 14 位离店短码或包含 `/c/短码` 的完整链接（不接受印刷卡号）；AIVA 会员码为二维码内容本身（32 位小写十六进制）。不要自己判断类型或改写内容 | `https://card.example/c/8K2M4P6R8T0V2X` |

#### 请求示例

```bash
curl -X POST "$BASE/api/identity/point-login" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"code":"https://card.example/c/8K2M4P6R8T0V2X"}'

# AIVA 小程序会员码：二维码内容原样传入，kind 可不传
curl -X POST "$BASE/api/identity/point-login" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"code":"<AIVA 会员码二维码内容>"}'
```

#### 返回示例（HTTP 200）

```json
{
  "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
  "ONEID": "oneid_example",
  "createdUser": false,
  "sessionId": "ids_6b1f…",
  "nickname": "小赛",
  "avatarUrl": "https://<AIVA 头像域名>/avatar.png",
  "sessionToken": "仅在此返回一次的用户会话",
  "expiresIn": 1800
}
```

| 返回字段 | 说明 |
| --- | --- |
| `AgentOSID` | 登录到的账户。已绑定 ONEID 时为该会员的主账户，不一定是这张卡自己的账户 |
| `ONEID` | 会员编号；来宾卡尚未绑定会员时为 `null` |
| `createdUser` | 本次是否自动建档；只有 AIVA 会员首次来访为 `true`，来宾卡登录恒为 `false` |
| `sessionId` | 会话编号，用于排查 |
| `nickname` / `avatarUrl` | 会员昵称与头像地址，是 2026-10-15 之前扫 AIVA 会员码时 AIVA 返回并保存的资料；此后 AIVA 扫码识别只返回 ONEID，不再更新，新会员、只用来宾卡或之前没扫过会员码的为 `null`。有值时可用于界面称呼用户，为 `null` 时不称呼昵称 |
| `sessionToken` | 用户会话，之后放在请求头 `X-Identity-Session`；只返回这一次，不要写入日志 |
| `expiresIn` | 会话有效秒数，由后台“点位登录有效期”设置 |

#### 错误情况

错误返回 `{"error":"中文说明","code":"…"}`，`code` 只在部分错误中出现。

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `code=CODE_INVALID`：既不是来宾卡码也不是 AIVA 会员码（含印刷卡号、链接格式不对、乱码），这种情况不会调用 AIVA；传了 `kind` 但码的格式与之不符；`code` 为空或超长；`kind` 不是 card/aiva；`kind=member`（AgentOS 会员凭据已停用） | 提示“请扫描卡面二维码或 AIVA 小程序会员码”，不要自动重试 |
| 401 | 设备凭证无效；来宾卡不存在或已作废；会员主账户已停用 | 提示身份验证失败 |
| 403 | 设备已在后台停用；纯展示点位的设备调用 | 联系运维检查设备 |
| 409 | 身份关联正在变化；身份服务未设置注册赠送与有效期；该会员关联账户有未结算冻结或已停用账户；AgentOS 后台未登记 AIVA 网关或扫码识别的 sourceApp / scanSourceApp（`code: AIVA_NOT_CONFIGURED`，提示去“用户与来宾卡 → 身份服务设置 → AIVA 网关”登记） | 提示稍后再试或联系运营；关联变化时重新扫码；未登记 AIVA 网关时联系 AgentOS 运营 |
| 502 | 扫 AIVA 会员码时 AIVA 识别失败：会员码无效、已用过或已过期，AIVA 网关返回失败（`error` 中带 AIVA 的 `errorCode` / `errorMsg` 原文），AIVA 连不上、超时或没有返回有效的 ONEID（`code: AIVA_FAILED`） | 请会员在小程序刷新会员码后重扫；不要用同一个码自动重试 |
| 500 / 503 | 服务端错误或依赖未就绪 | 显示登录失败，不进入互动，不改用匿名身份 |

### 当前用户
#### 功能描述

读取当前会话对应的用户编号、会员编号与 Token 账户。界面显示的余额以这里为准，不要把同一会员各张卡的余额自行相加。

#### 请求参数

无。只需请求头中的设备凭证与 `X-Identity-Session`。

#### 请求示例

```bash
curl "$BASE/api/identity/me" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "AgentOSID": "au_3f9c0d1e2a4b5c6d7e8f",
  "ONEID": "oneid_example",
  "account": { "balance": 120, "frozen": 0 }
}
```

| 返回字段 | 说明 |
| --- | --- |
| `AgentOSID` | 当前账户 |
| `ONEID` | 会员编号；未绑定会员时为 `null` |
| `account.balance` / `account.frozen` | 可用 Token 与冻结中的 Token；该账户尚无 Token 账户时不返回 `account` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证无效；缺少会话、会话已过期或已退出；身份卡已作废 | 清除本地会话，回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 409 | 会员主账户已因归集变更 | 主账户变更时请访客重新扫码登录 |

### 当前用户资料（来源明细）
#### 功能描述

按数据类别分页读取当前用户的原始资料。已绑定 ONEID 时包含该会员全部关联账户的数据，每条记录保留它原来属于哪个账户、哪个门店；未绑定时只返回本卡数据。需要“累计画像”结果时请用下一个接口。

#### 请求参数（Path / Query）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `resource` | Path | string | 必填 | `tags` 标签、`profileContributions` 画像来源、`interactionAnswers` 互动作答、`interactionDesigns` 设计方案、`assets` 作品 |
| `limit` | Query | integer | 可选 | 每页条数 1—500，默认 100 |
| `cursor` | Query | string | 可选 | 翻页位置，原样传上一页返回的 `nextCursor`；不要自己拼 |

#### 请求示例

```bash
curl "$BASE/api/identity/profile/tags?limit=50" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（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,
  "primaryAgentOSID": "au_1a2b…",
  "profileMode": "source-evidence",
  "note": "返回所有关联账户的原始贡献与来源；累计画像见 /api/identity/profile-summary。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items` | 本页记录，各类别字段见“用户资料字段”章节 |
| `hasMore` / `nextCursor` | 是否还有下一页、下一页位置 |
| `complete` | 该类别本次分页已读完 |
| `primaryAgentOSID` | 会员主账户 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `limit` 不在 1—500；`cursor` 无效或不属于本次查询 | 去掉 cursor 从第一页重读 |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 404 | `resource` 不是上述五类之一 | 修正类别名 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 累计画像
#### 功能描述

返回当前用户（已绑定 ONEID 时为该会员全部关联账户）的标签累计结果：每次作答的标签贡献全部累计，重复作答累加权重（2026-10-06 确认）。用于在互动中展示或引用用户画像。

#### 请求参数

无。只需请求头中的设备凭证与 `X-Identity-Session`。

#### 请求示例

```bash
curl "$BASE/api/identity/profile-summary" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "primaryAgentOSID": "au_1a2b…",
  "ONEID": "oneid_example",
  "rule": "cumulative_all_answers",
  "accountIds": ["au_1a2b…", "au_3f9c…"],
  "totalContributions": 12,
  "items": [
    { "tagKey": "style_tech", "tagName": "科技感", "category": "风格", "weight": 5, "share": 0.4167, "interactions": 3, "points": ["P02", "P08"], "firstAt": "2026-10-06T08:00:00.000Z", "lastAt": "2026-10-08T01:00:00.000Z" }
  ]
}
```

| 返回字段 | 说明 |
| --- | --- |
| `accountIds` | 参与累计的全部账户 |
| `totalContributions` | 标签贡献总数 |
| `items[].weight` / `share` | 该标签累计权重与占比 |
| `items[].interactions` / `points` | 来自多少次互动、哪些点位 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭证或会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 退出登录
#### 功能描述

撤销当前用户会话。访客结束体验或离开点位时调用；之后该 `sessionToken` 不能再使用。客户端同时清除本地会话和屏幕上的用户信息。

**AI车衣共创（2026-10-14）**：退出时只发这一个请求——服务端顺带结束本会话还在进行的体验：已有保存成功的作品记“完成”（`completed`），没有作品记“放弃”（`abandoned`）；只剩结果待核对的任务时按“放弃”结束（冻结待后台核对）；仍有任务在执行时该体验不结束，在 `notEnded` 里说明原因（会话照常退出）。其他互动退出登录不结束体验，仍需先调用[结束体验](#api-interaction-end)。

#### 请求参数（Body）

无必填字段，发送空对象 `{}` 即可。

#### 请求示例

```bash
curl -X POST "$BASE/api/identity/logout" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{ "loggedOut": true }
```

AI车衣共创另带：

```json
{ "loggedOut": true, "ended": [ { "interactionId": "ix_7d3e…", "state": "completed" } ], "notEnded": [] }
```

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 会话已过期、已退出或设备凭证无效 | 视为已退出，清除本地会话即可 |

### 会员码与跨点位数据

会员码就是 AIVA 小程序里显示的会员码，内容为 32 位小写十六进制的临时 token（2026-10-13 AIVA 确认）。扫到的内容原样作为 `code` 传给扫码登录，不传 `kind`、不要自己解析，也不要传 ONEID 明文；来宾卡码与会员码由服务端按格式识别，识别不了的返回 400 `CODE_INVALID`（不会调用 AIVA），见[扫码登录](#api-point-login)。AgentOS 用它调用 AIVA 换出 ONEID；AIVA 的码只能用一次，登录响应丢失时不能拿原码重发，请会员在小程序刷新会员码后重扫。AgentOS 自己签发的一次性会员凭据 memberTicket（`kind=member`）已于 2026-10-13 停用。

不同点位分别扫码登录；不能把P02的sessionToken转交P03。ONEID多卡关联后的Token归集到最早创建的AgentOSID，界面以me返回账户为准，不自行把各卡余额相加。

读取当前用户共享资料使用profile接口，不调用集团全量用户接口。可选数据域：tags、profileContributions、interactionAnswers、interactionDesigns、assets。返回原始资料不等于画像合并已完成。

### 当前用户资料的分页协议

limit为可选integer，1–500，默认100；cursor可选string，原样传回nextCursor。响应还含primaryAgentOSID、profileMode="source-evidence"和note。

```json
{"schemaVersion":1,"items":[],"hasMore":false,"nextCursor":null,"consistency":"live-keyset-bounded","asOf":"2026-10-02T00:00:00.000Z","complete":true,"note":"响应中的实际说明","primaryAgentOSID":"uid_example","profileMode":"source-evidence"}
```

hasMore=true时继续同一数据域、同一用户和凭证的查询；不要解析或自造cursor。complete只表示该数据域本次分页结束。分页固定主键上界，但每页读取实时值；敏感映射等受导出限制。条目字段见“公用·用户资料字段”。


## ONEID 会员对外接口（已单独成文）

与 AIVA 官方 ONEID 会员相关、供 AIVA 小程序服务端对接的接口（B02—B06 身份绑定、作品删除与作品码查询，以及 AgentOS 调用 AIVA 的太阳码 M01、二维码扫码识别、绑定结果推送、作品数据推送）已单独归类，见《ONEID 会员对外接口文档》：http://aiva.docs.vavedigital.com/api-docs/oneid.html 。点位客户端只使用本文的“扫码登录、当前用户与退出”。

## 公用｜互动配置、授权与会话

本章是 AIVA面基（P02）、AI音乐（P03）、AI图片生成（P08）、AI车衣共创（P04）四个互动共用的“配置 → 开始体验 → 授权 → 作答/确认 → 结束”接口。点位由设备凭证决定，客户端不能自己指定门店或点位。读取配置和确认配置只用设备凭证（D）；其余接口都要再带扫码登录得到的用户会话（U，见[扫码登录](#api-point-login)）。路径中的 `:id` 是“开始体验”返回的 `interactionId`，必须是本设备、本次登录会话创建的体验，否则一律返回 404。纯展示点位的设备不能调用本章任何接口（403）。

### 调用顺序

| 步骤 | 接口 | 说明 |
| --- | --- | --- |
| 1 程序启动 / 配置刷新 | [读取互动配置](#api-interaction-config) | 按返回的题目、授权条款、阶段渲染页面，记下 `version` |
| 2 页面已按该版本准备好 | [确认已应用配置](#api-interaction-config-ack) | 确认后才能用这个版本开始体验 |
| 3 访客扫码 | [扫码登录](#api-point-login) | 拿到 `sessionToken` |
| 4 开始体验 | [开始体验](#api-interaction-create) | 得到 `interactionId`，状态 `consent` |
| 5 展示授权条款 | [提交授权决定](#api-interaction-consent) | 同意后状态 `questions`；拒绝则本次体验直接结束 |
| 6 各互动自己的输入 | 见下表 | |
| 7 结束 | [结束体验](#api-interaction-end)，再退出登录 | AIVA面基名片完成后也可[重新回答](#api-interaction-restart) |

| 互动 | 第 6 步的接口顺序 |
| --- | --- |
| AIVA面基（P02） | [提交问卷答案](#api-interaction-answers)（5 道单选题）→ [确认进入生成](#api-interaction-confirm) → [正式图片任务](#api-image-task-create) → 名片完成 → [正式文本任务](#api-text-task-create) 聊天；详见 [AIVA面基](#p02) |
| AI图片生成（P08） | 作答期间可用[正式文本任务](#api-text-task-create)（旅程引导回复）→ [提交问卷答案](#api-interaction-answers)（可含自由文本）→ [确认进入生成](#api-interaction-confirm)（“出发”）→ [正式图片任务](#api-image-task-create)；详见 [AI图片生成](#p08) |
| AI音乐（P03） | 曲风、人声两轮偏好 → [提交问卷答案](#api-interaction-answers)（故事回答）→ 偏好确认、歌词、音乐任务；不调用通用“确认进入生成”；详见 [AI音乐](#p03) |
| AI车衣共创（P04） | 设计保存与确认 → [正式图片任务](#api-image-task-create)，过程中可上报[观察事件](#api-p04-events)；不调用“提交问卷答案”和通用“确认进入生成”；详见 [AI车衣共创](#p04) |

### 读取互动配置
#### 功能描述

读取本点位当前已应用的互动配置：题目、开场与建议文本、授权条款和流程阶段，以及各互动的专属字段。只下发界面需要的内容；模型凭证、提示词和选项对应的标签不下发。响应带 `Cache-Control: no-store`。

调用时机：程序启动、恢复联网、后台改了配置之后。读到新的 `version` 时，先按新配置准备好页面，再调用[确认已应用配置](#api-interaction-config-ack)。

#### 请求参数

无。只需请求头中的设备凭证。

#### 请求示例

```bash
curl "$BASE/api/interactions/config" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL"
```

#### 返回示例（HTTP 200）

AI图片生成（P08）示例：

```json
{
  "pointId": "P08",
  "version": 7,
  "questions": [
    {
      "id": "q_destination",
      "title": "你想去哪里？",
      "allowText": true,
      "options": [ { "id": "q_destination_sea", "label": "海边", "detail": "后台配置的说明" } ]
    }
  ],
  "opening": "后台配置的开场文本",
  "suggestions": "后台配置的建议文本",
  "policy": {
    "policy_id": "policy_portrait",
    "name": "人像采集授权",
    "kind": "portrait",
    "version": 2,
    "content": { "title": "……", "body": "……" }
  },
  "stages": ["consent", "photo", "questions", "departure-confirmation", "focus", "generation"],
  "result": { "title": "后台固定标题", "subtitle": "后台固定副标题" }
}
```

| 返回字段 | 说明 |
| --- | --- |
| `pointId` | 本设备绑定的点位：P02 / P03 / P04 / P08 |
| `version` | 互动配置版本（整数）。与展示配置的 `revision`、设计修订号不是一回事 |
| `questions` | 题目：`id`、`title`、`allowText`（是否允许自由文本）、`options[]`（`id`、`label`、`detail`）。AI车衣共创不使用 |
| `opening` / `suggestions` | 后台配置的开场文本、建议文本（字符串）。AIVA面基动态三条建议走正式文本任务 |
| `policy` | 授权条款：`policy_id`、`name`、`kind`（AIVA面基/AI图片生成为 `portrait`，AI音乐/AI车衣共创为 `interaction`）、`version`、`content`。提交授权时用 `policy_id` 和 `version` |
| `stages` | 页面流程阶段清单，是设计流程，不是实时状态，也不代表这些阶段都已有接口 |
| `result` | 仅 AI图片生成：结果页标题、副标题（后台固定文案，不调模型） |
| `music` | 仅 AI音乐：`{genres:[{id,label}],timbres:[{id,label}],durationStrategy:"content"}` |
| `wrap` / `assets` / `stages` / `freeDescription` / `printingImplemented` | 仅 AI车衣共创：风格配色与模式、车衣素材清单（含 HTTPS 地址与校验和）、流程阶段、`"ai_generate"`（关闭自由输入时 `"disabled"`）、`false`（2026-10-11 起 Pad 不发起打印）。字段说明见 [AI车衣共创](#p04) |

各互动的 `stages`：AIVA面基 `consent, photo, questions, generation, chat`；AI图片生成如上例；AI音乐 `consent, genre, timbre, story, lyrics, lyrics-confirmation, music, result`；AI车衣共创 `consent, mode, design, design-confirmation, generation, result`。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 本设备绑定的点位不是 P02/P03/P04/P08；AI车衣共创配置引用的车衣素材不存在、未审核、类型不符、缺校验和或缺 HTTPS 地址 | 联系运维核对设备绑定或车衣素材，不进入互动 |
| 401 | 缺少 Bearer 凭证、格式不对或设备凭证无效 | 联系运维更换设备凭证 |
| 403 | 设备已在后台停用；纯展示点位的设备调用 | 联系运维 |
| 409 | 本点位还没有已应用的互动配置；配置引用的授权条款不存在或类型与点位不匹配 | 显示“暂未开放”，稍后重新读取；不要用本地旧题目开始体验 |

### 确认已应用配置
#### 功能描述

告诉 AgentOS：本设备已经按某个配置版本准备好页面。服务端按设备记录最近一次确认的版本；[开始体验](#api-interaction-create)时要求传入的版本既是当前已应用版本，又是本设备已确认的版本。后台发布新版本后，旧确认自动失效，需要重新读取并确认。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `version` | integer | 必填 | 刚读到并已应用的配置版本，必须等于当前已应用版本；不能传字符串 | `7` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/config/ack" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"version":7}'
```

#### 返回示例（HTTP 200）

```json
{ "confirmed": true, "version": 7 }
```

| 返回字段 | 说明 |
| --- | --- |
| `confirmed` | 固定为 `true` |
| `version` | 已记录的确认版本 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；点位不是 P02/P03/P04/P08 | 修正请求 |
| 401 | 设备凭证无效 | 联系运维 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 409 | 没有已应用配置或授权条款异常；`version` 不是当前已应用版本（含缺少或类型不对） | 重新[读取互动配置](#api-interaction-config)，按新版本应用后再确认 |

### 开始体验
#### 功能描述

为当前登录用户在本点位开始一次体验，记下本次使用的配置和授权条款，返回 `interactionId`，初始状态 `consent`（等待授权）。

**AI车衣共创（2026-10-14）**：开始体验即视为用户已同意本次授权条款——服务端按配置里的授权协议版本直接记一条授权，返回 `state:"questions"` 和 `consentId`，不用再调用[提交授权决定](#api-interaction-consent)。前端须在用户点了“同意”之后才调用开始体验，用户不同意就不要开始。

开始前服务端会检查：配置版本是当前已应用且本设备已确认的版本；点位应用类型是 Agent 互动；本设备通过播控运行回报报告“处于应用模式且网页和输出就绪”，并且回报还在运行状态有效期内（见[播控配对与配置下发](#player)）。

同一个用户会话里，同一个 `requestId` 原样重发不会重复开始体验，返回第一次创建的 `interactionId`（带 `idempotentHit: true`）。返回的 `version` 是本次体验所用的配置版本，**整次体验都用这一版**；后台之后再发布新版本不影响正在进行的体验（2026-10-15 起重发时也返回 `version`）。网络失败时用同一个 `requestId` 重试；只有用户真的再开一次体验时才换新的 `requestId`。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `requestId` | string | 必填 | 客户端生成的请求号，1—64 个字符，不能全是空白、不能含换行等控制字符 | `experience-20261008-0001` |
| `version` | integer | 必填 | 当前已应用且已[确认](#api-interaction-config-ack)的配置版本 | `7` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"experience-20261008-0001","version":7}'
```

#### 返回示例（HTTP 200）

首次创建：

```json
{ "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "version": 7, "state": "consent" }
```

同一 `requestId` 重发：

```json
{ "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "idempotentHit": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `interactionId` | 本次体验编号，后续接口路径中的 `:id`；它不是登录会话编号 |
| `version` | 本次体验锁定的配置版本；体验中途后台改配置不影响本次 |
| `state` | 固定为 `consent` |
| `idempotentHit` | 仅重发时出现，表示返回的是第一次的结果 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；`requestId` 缺失、超过 64 字符或含控制字符；点位不是 P02/P03/P04/P08 | 修正请求 |
| 401 | 设备凭证无效；缺少用户会话、会话已过期或已退出；身份卡已作废 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 设备对应的点位不存在 | 联系运维核对设备绑定 |
| 409 | 会员主账户已变更；没有已应用配置或授权条款异常；`version` 不是当前版本（“请先同步并确认最新配置”）；本设备未确认该版本；点位为普通展示应用；同一 `requestId` 已用于不同版本 | 版本问题：重新读取并确认配置；主账户变更：重新扫码 |

### 查询体验
#### 功能描述

读取本次体验的当前状态、已提交的答案和已保存的文本消息。用于页面刷新或断线恢复后对齐进度。正式任务（文本、图片、音乐）的进度请查原任务编号，不要用这里推断任务结果。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 开始体验返回的 `interactionId`，需 encodeURIComponent |

#### 请求示例

```bash
curl "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{
  "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "chat",
  "version": 7,
  "answers": [
    { "questionId": "q1", "title": "周末你更想……", "optionId": "q1_a", "label": "去看展", "tags": ["tag_art"] }
  ],
  "messages": [
    {
      "message_id": "msg_…",
      "purpose": "chat",
      "user_text": "你好",
      "response": "你好，我是你的助手……",
      "regenerates": null,
      "status": "completed",
      "usage_json": { "…": "厂商返回的用量记录，结构以实际为准（待确认）" },
      "created_at": "2026-10-08T02:00:00.000Z"
    }
  ]
}
```

| 返回字段 | 说明 |
| --- | --- |
| `state` | 当前状态，含义见本章“体验状态” |
| `version` | 本次体验锁定的配置版本 |
| `answers` | 已提交的答案；未作答时为 `null`。选项题含 `questionId`、`title`、`optionId`、`label`、`tags`；自由文本题含 `questionId`、`title`、`text`、`tags: []`。按留存策略清理后也为 `null` |
| `messages` | 已保存的文本消息，按创建顺序。字段为数据库原名：`message_id`、`purpose`（如 intro/chat/suggestions/guide/lyrics）、`user_text`、`response`、`regenerates`、`status`、`usage_json`、`created_at`。AI车衣共创体验结束后 `user_text`、`response` 会被清空 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `id` 为空、超过 64 字符或含控制字符 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在，或不属于本设备、本次登录会话 | 不要拿其他会话的编号查询；重新开始体验 |
| 409 | 会员主账户已变更 | 重新扫码登录 |

### 提交授权决定
#### 功能描述

提交访客对授权条款的明确决定。（AI车衣共创 2026-10-14 起不需要调用，开始体验即视为已同意。）同意：记录授权，状态变为 `questions`（AI车衣共创也是 `questions`，但下一步走设计接口，不走问卷）。拒绝：本次体验直接结束，状态 `abandoned`。

已经同意过再提交同意，返回第一次的授权编号（带 `idempotentHit: true`）；已经同意过想撤回，必须调用[撤回授权](#api-interaction-consent-revoke)，不能在这里提交拒绝。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `accepted` | boolean | 必填 | `true` 同意，`false` 拒绝；必须是布尔值 | `true` |
| `policyId` | string | 必填 | 配置中 `policy.policy_id` 的值 | `policy_portrait` |
| `policyVersion` | integer | 必填 | 配置中 `policy.version` 的值 | `2` |

`policyId` / `policyVersion` 必须与本次体验开始时锁定的条款一致，取自[读取互动配置](#api-interaction-config)的实际响应，不要用示例值。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/consent" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"accepted":true,"policyId":"policy_portrait","policyVersion":2}'
```

#### 返回示例（HTTP 200）

同意：

```json
{ "consentId": "cs_9a8b7c6d-…", "state": "questions" }
```

拒绝：

```json
{ "state": "abandoned" }
```

已同意后再次提交同意：

```json
{ "consentId": "cs_9a8b7c6d-…", "idempotentHit": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `consentId` | 授权记录编号 |
| `state` | `questions`：可继续下一步；`abandoned`：本次体验已结束 |
| `idempotentHit` | 已同意过时出现 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；`accepted` 不是布尔值；`id` 格式错误 | 修正请求 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于本次登录 | 重新开始体验 |
| 409 | `policyId`/`policyVersion` 与本次体验不一致；已同意后提交拒绝（应调用撤回授权）；体验已不在等待授权阶段（如已拒绝结束）；会员主账户已变更 | 条款不一致：重新开始体验；阶段不对：按“查询体验”结果继续或重新开始 |

### 撤回授权
#### 功能描述

访客中途撤回授权。服务端标记授权已撤回（已有授权时），并把本次体验结束为 `abandoned`，停止后续人像相关调用。撤回不等于删除全部历史记录，已产生的记录按平台留存策略处理。

代码现状：本接口不检查当前状态，任何状态下调用都会把本次体验改为 `abandoned`（包括已完成的体验），也不检查是否有进行中的模型任务。客户端只在访客明确撤回时调用。

#### 请求参数（Body）

无字段，发送空对象 `{}` 即可。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/consent/revoke" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{ "revoked": true, "note": "停止后续人像调用；原片未在本服务持久化。已产生记录按平台留存策略处理。" }
```

| 返回字段 | 说明 |
| --- | --- |
| `revoked` | 固定为 `true` |
| `note` | 服务端说明文字，展示或记录即可，不要按文字做判断 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `id` 格式错误 | 检查路径 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录；会话失效后无法再撤回，请联系运营处理 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于本次登录 | 不要拿其他会话的编号调用 |
| 409 | 会员主账户已变更 | 重新扫码后再撤回，或联系运营 |

### 提交问卷答案
#### 功能描述

一次性提交本次体验的全部答案（不是逐题提交）。成功后状态变为 `ready`，并把答案对应的标签累计进用户共享画像（重复作答累加，不覆盖以前的贡献）。

各互动差异：

| 互动 | 规则 |
| --- | --- |
| AIVA面基（P02） | 必须是后台配置的 5 道单选题，每题提交 `optionId`，不接受自由文本。服务端按“每题一票、平票按第1、4、5、2、3题顺序”算出排名前两个属性作为 `tags`，另返回 `scores` 与 `scoringRule`；如果 5 个答案只产生 1 种属性，返回 400，不补造第二个标签 |
| AI图片生成（P08） | 选项题提交 `optionId`；`allowText=true` 的题可改为提交 `text` |
| AI音乐（P03） | 必须先完成曲风和人声两轮偏好再提交故事回答；故事题通常为自由文本 |
| AI车衣共创（P04） | 不使用本接口（返回 400），请用设计接口，见 [AI车衣共创](#p04) |

自由文本答案在写入前送内容安全审核（规则见[正式文本与图片任务](#formal-tasks)中的“内容安全”）；审核不通过时不写入任何答案；未登记内容安全或审核服务临时不可用时不送审、按通过处理。

已提交过答案后，再提交完全相同的答案会返回第一次的结果（带 `idempotentHit: true`，不再审核）；提交不同答案会被拒绝，答案一经提交不能修改。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `answers` | array | 必填 | 每道题一项，数量必须等于配置中的题目数，同一题不能重复 | 见下 |
| `answers[].questionId` | string | 必填 | 配置中的题目 `id` | `q1` |
| `answers[].optionId` | string | 二选一 | 该题的选项 `id`；与 `text` 不能同时提交 | `q1_a` |
| `answers[].text` | string | 二选一 | 自由文本，仅 `allowText=true` 的题可用；1—2000 字符，不能全是空白，不能含换行等控制字符 | `想去看极光` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/answers" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"answers":[{"questionId":"q_destination","optionId":"q_destination_sea"},{"questionId":"q_wish","text":"想去看极光"}]}'
```

#### 返回示例（HTTP 200）

AI图片生成 / AI音乐：

```json
{ "state": "ready", "tags": ["tag_sea"] }
```

AIVA面基：

```json
{
  "state": "ready",
  "tags": ["tag_art", "tag_tech"],
  "scores": [ { "tag": "tag_art", "count": 3 }, { "tag": "tag_tech", "count": 2 } ],
  "scoringRule": "p02-v2-q1-q4-q5-q2-q3"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `state` | 首次提交为 `ready`；重发时为体验当前状态 |
| `tags` | 本次计入画像的标签编码。AIVA面基为排名前两个属性；其他互动为所选选项映射的全部标签（自由文本不产生标签） |
| `scores` / `scoringRule` | 仅 AIVA面基：各属性得票与计分规则编号 |
| `idempotentHit` | 重发相同答案时出现 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；答案数量与题目数不符、题目重复或缺题；选项不存在或与 `text` 同时提交；该题不接受自由文本；文本为空、超长或含换行；AIVA面基题目配置不合规或答案未产生两个不同属性；AI车衣共创调用本接口 | 按配置重新组织答案；AIVA面基配置问题请联系运营 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于本次登录 | 重新开始体验 |
| 409 | 尚未授权或不在作答阶段（例如旅程引导回复正在生成）；AI音乐尚未完成曲风和人声两轮偏好；已提交过不同的答案；会员主账户已变更 | 先完成前一步；已提交不同答案时不要覆盖，按“查询体验”结果继续 |
| 413 | 请求体超过 1,000,000 字符 | 缩短内容 |
| 422 | 自由文本审核未通过（`code: "CONTENT_REJECTED"`，`failureKind: "moderation"`） | 显示“审核未通过”，请访客修改后重新提交；本次未写入 |

### 确认进入生成
#### 功能描述

仅 AIVA面基（P02）和 AI图片生成（P08，即点击“出发”）使用：在答案提交后（状态 `ready`）登记访客确认。只记录确认时间，不创建生成任务；之后由客户端调用[正式图片任务](#api-image-task-create)。重复调用保留第一次的确认时间，返回相同结果。

AI音乐与 AI车衣共创使用各自带修订号的确认接口（见 [AI音乐](#p03)、[AI车衣共创](#p04)），调用本接口返回 400。

#### 请求参数（Body）

无。可不带请求体。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/confirm" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN"
```

#### 返回示例（HTTP 200）

```json
{ "confirmed": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `confirmed` | 固定为 `true`，只表示已登记确认 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | AI音乐或 AI车衣共创调用（“创作确认需要提交设计修订号”）；`id` 格式错误 | 改用对应互动的确认接口 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于本次登录 | 重新开始体验 |
| 409 | 状态不是 `ready`（尚未提交答案，或已进入生成）；会员主账户已变更 | 先完成问卷；已在生成时按任务结果继续 |

### 结束体验
#### 功能描述

结束本次体验，标记为完成（`completed`）或放弃（`abandoned`）。只结束体验，不注销身份；访客离开时先在会话仍有效时结束体验，再[退出登录](#api-identity-logout)。

- 有模型任务仍在执行（已建未派发、已派发、已提交厂商或保存中）时不能结束，需先查原任务直到有结论。
- 只剩结果未知（`unknown`）、待后台人工核对的任务时，可以用 `abandoned` 结束（2026-10-08 修复，此前无法结束）；此时不能报 `completed`。冻结的 Token 不释放、任务记录不改，返回带 `pendingReview:true`；之后迟到的结果不再附加到本次体验。
- 标记 `completed` 需已有结果：状态为 `generated`、`chat` 或 `completed`；AI车衣共创只要本次体验已有一个生成完成的作品，即使之后又改了设计，也可以标记完成。
- 已经结束的体验，再次提交相同结束状态返回当前状态；提交不同状态返回 409。
- AI车衣共创结束时清理本次的绘制草稿与临时对话正文，只保留风格配色等最终信息。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `status` | string | 必填 | `completed` 已完成 / `abandoned` 中途放弃 | `completed` |

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/end" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"status":"completed"}'
```

#### 返回示例（HTTP 200）

```json
{ "state": "completed" }
```

| 返回字段 | 说明 |
| --- | --- |
| `state` | 结束后的状态：`completed` 或 `abandoned` |
| `pendingReview` / `note` | 仅在有结果未知的任务时返回：`pendingReview:true`，说明冻结的 Token 待后台人工核对 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；`status` 不是 completed/abandoned；`id` 格式错误 | 修正请求 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 体验不存在或不属于本次登录 | 不要拿其他会话的编号调用 |
| 409 | 模型任务仍在执行；任务结果未知却报 `completed`；尚未生成结果却报 `completed`；体验已以另一种状态结束；会员主账户已变更 | 任务执行中：继续查原任务；结果未知或未生成结果：改报 `abandoned` |

### 重新回答
#### 功能描述

仅 AIVA面基使用（聊天页的循环箭头“重新回答”）。在同一次操作里结束当前体验（状态 `completed`，结束原因 `user_restart`）并开始一次新体验，返回新的 `interactionId`。新体验需要重新授权、作答 5 题、生成新名片，正常计费；原体验的名片、作答和标签贡献都保留，新体验的标签继续累计进画像（2026-10-06 确认）。

- 只能在本次名片已完成（状态 `generated` 或 `chat`）后发起；名片未完成时请用[结束体验](#api-interaction-end)。
- 有模型任务正在执行或待核对时拒绝。
- 开始新体验的检查与[开始体验](#api-interaction-create)相同（配置版本已确认、点位为 Agent 互动、播控处于应用模式且就绪）。
- `requestId` 是新体验的请求号，不能与当前体验的相同。同一 `requestId` 原样重发不会再开一次，返回第一次开出的新体验编号（带 `idempotentHit: true`）。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `id` | Path | string | 必填 | 当前（要结束的）体验编号 |
| `requestId` | Body | string | 必填 | 新体验的请求号，1—64 字符，不含控制字符 |
| `version` | Body | integer | 必填 | 当前已应用且本设备已确认的配置版本 |

请求体只允许这两个字段，多传其他字段返回 400。

#### 请求示例

```bash
curl -X POST "$BASE/api/interactions/ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b/restart" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "X-Identity-Session: $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"requestId":"experience-20261008-0002","version":7}'
```

#### 返回示例（HTTP 200）

```json
{
  "previous": { "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "state": "completed", "closeReason": "user_restart" },
  "interactionId": "ix_7d6c5b4a-…",
  "version": 7,
  "state": "consent",
  "note": "原体验已结束并保留名片与作答；新体验需重新授权并作答后生成新名片，标签贡献累计。"
}
```

同一 `requestId` 重发时：

```json
{
  "previous": { "interactionId": "ix_5b0e8f2a-1c3d-4e5f-8a9b-0c1d2e3f4a5b", "state": "completed", "closeReason": "user_restart" },
  "interactionId": "ix_7d6c5b4a-…",
  "idempotentHit": true
}
```

| 返回字段 | 说明 |
| --- | --- |
| `previous` | 被结束的原体验：编号、状态、结束原因 `user_restart` |
| `interactionId` | 新体验编号，之后的接口都用它 |
| `version` / `state` | 新体验的配置版本与状态 `consent`（重发时不返回） |
| `note` | 服务端说明文字 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 不是 AIVA面基点位；请求体不是对象或含未支持字段；`requestId` 格式错误 | 修正请求 |
| 401 | 设备凭证或用户会话无效 | 回到扫码登录 |
| 403 | 设备已停用；纯展示点位设备 | 联系运维 |
| 404 | 当前体验不存在或不属于本次登录 | 重新开始体验 |
| 409 | 配置版本不是当前版本或本设备未确认；模型任务尚未核对完成；名片尚未完成；`requestId` 已用于其他体验（含与当前体验相同）；同一 `requestId` 已用于不同版本；点位为普通展示应用；会员主账户已变更 | 版本问题：重新读取并确认配置；`requestId` 冲突：换一个新的请求号；名片未完成：使用结束体验 |

### 体验状态

`state` 是服务端记录的实际状态；配置里的 `stages` 是页面流程清单，两者不同，不能用 `stages` 推算实际进度。

| state | 含义 |
| --- | --- |
| `consent` | 已开始，等待授权 |
| `questions` | 已授权，等待作答（AI音乐为偏好与故事阶段；AI车衣共创为设计阶段） |
| `ready` | 答案或设计已提交，可确认并生成 |
| `running` | 有模型任务正在执行或结果待核对（AI图片生成的旅程引导回复生成期间也是此状态，完成后回到 `questions`） |
| `generated` | 已生成结果（如名片完成、AI车衣共创生成完成、AI音乐生成完成） |
| `chat` | AIVA面基已进入聊天 |
| `completed` | 已标记完成，或 AIVA面基“重新回答”后原体验被结束 |
| `abandoned` | 拒绝授权、撤回授权或中途放弃 |

### 退出与撤回的区别

结束体验只结束本次体验，退出登录只注销身份；访客离开时先结束体验，再退出登录。撤回授权会把本次体验标为 `abandoned`，但不代表已删除全部历史记录。

## 公用｜展示模式与素材播放

所有点位（互动点位与纯展示点位）都可以配置普通展示素材。素材上传、审核、播放编排都在 AgentOS 后台完成，现场程序只读取素材地址并播放，不调用后台上传接口。本章是旧版（v1）展示读取与回执接口和设备心跳；2026-10-07 起所有点位统一由中控Pad控制，现场播放应使用[播控配对与配置下发](#player)中的 v2 接口，v1 读取接口对中控点位返回 409（见下方卡片）。

### 播放语义

| 字段 | 值 | 含义 |
| --- | --- | --- |
| applicationType | agent / display | Agent互动应用 / 普通展示应用 |
| mode | agent / display | 现场Agent模式 / 素材展示模式；普通应用只能display |
| playMode | sequential | 按items顺序逐项播放 |
| playMode | shuffle | 客户端每轮打乱清单，每项播放一次后该轮结束 |
| playMode | single | 仅一个条目；多于一项时服务端拒绝 |
| endBehavior | loop / stop | 整单结束后重新播放 / 停止播放 |
| 图片 durationMs | 100–86400000 的整数 | 显示毫秒数，到时进入下一项 |
| 视频 videoEnd | next | 收到视频ended事件后进入下一项 |
| 视频 videoEnd | loop | 持续循环当前视频，不进入下一项，直到新的现场指令 |
| 视频 muted | true / false | 静音 / 开启声音；浏览器自动播放限制需客户端处理并回报失败 |

整单stop表示停止播放器，不擅自切换Agent或改播备用素材。视频单项loop优先于整单结束设置，因为该条目不会结束。网络抖动拉不到配置时维持上一次生效的状态与版本，不把请求失败当作关闭点位；素材加载失败不得静默换图，客户端提交error回执。首次尚无配置时不得编造默认内容。



### 读取展示配置（v1）
#### 功能描述

读取本点位的展示配置：应用类型、现场模式、播放方式、是否可播放，以及带访问地址的素材清单。响应带 `Cache-Control: no-store`。2026-10-13 起不再限制门店营业与点位启用，`canPlay` 恒为 `true`（字段保留供兼容）；`mode=agent` 时也不返回素材，客户端回到 Agent 互动流程。

重要：2026-10-07 确认所有点位统一由中控Pad控制（迁移 052 已把全部点位改为中控控制），本接口遇到中控点位直接返回 409“此点位由中控播控，请使用v2内容清单与运行回报接口”。因此在当前数据下本接口实际只会返回 409；下方返回示例仅说明旧版非中控点位的响应结构。图文素材和“自定义宽高”显示尺寸也只在 v2 提供。

#### 请求参数

无。只需请求头中的设备凭证。

#### 请求示例

```bash
curl "$BASE/api/point-display/config" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 3,
  "applicationType": "agent",
  "mode": "display",
  "playMode": "sequential",
  "endBehavior": "loop",
  "items": [
    {
      "assetId": "asset_main_visual",
      "type": "image",
      "durationMs": 10000,
      "fit": "contain",
      "name": "门店主视觉",
      "url": "https://已配置访问域名/asset/...",
      "mimeType": "image/png",
      "fileSize": 1234,
      "sha256": "64位小写十六进制"
    }
  ],
  "pointId": "P04",
  "pointStatus": "enabled",
  "canPlay": true
}
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 展示配置修订号（整数），回执时原样带回 |
| `applicationType` / `mode` | 应用类型 agent/display；现场模式 agent/display |
| `playMode` / `endBehavior` | 播放方式 sequential/shuffle/single；整单结束 loop/stop |
| `items` | 素材条目。图片含 `durationMs`；视频含 `videoEnd`（loop/next）、`muted`；均含 `fit`、`name`、`url`、`mimeType`、`fileSize`、`sha256` |
| `pointStatus` / `canPlay` | 点位状态（仅供显示）；是否可播放，2026-10-13 起恒为 `true`，不再看门店营业与点位启用 |
| 其他 | 已保存配置中的其他字段（如 `controlOwner`、`runtimeLeaseMs`、`stopBehavior`、`playerPolicy`）会原样带出 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 服务端处理异常（本组路由把无状态码的内部错误按 400 返回，代码现状） | 记录错误，稍后重新读取；不要改播其他素材 |
| 401 | 缺少 Bearer 凭证或设备凭证无效 | 联系运维更换设备凭证 |
| 403 | 设备已在后台停用 | 联系运维 |
| 409 | 点位展示配置尚未保存；点位由中控Pad控制（当前所有点位）；含图文素材或自定义显示尺寸；素材不存在、类型不符、未审核、不在本店范围或缺少有效访问地址 | 中控点位改用 v2 接口；其他情况请后台修正配置，首次无配置时不得编造默认内容 |

### 展示配置回执（v1）
#### 功能描述

展示程序应用某个修订号的配置后，上报“已应用”或“失败及原因”，后台按设备显示。回执是客户端自报，不代表服务端验证过屏幕画面。同一设备只保留最新一条回执。中控播控（v2）使用自己的内容回执接口，见[播控配对与配置下发](#player)。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `revision` | integer | 必填 | 刚应用的配置修订号，必须等于当前已保存的修订号 | `3` |
| `status` | string | 必填 | `applied` 已应用 / `error` 失败 | `applied` |
| `message` | string | 必填 | 说明，0—500 字；成功可传空串，失败写具体原因 | `""` |

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/ack" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"revision":3,"status":"applied","message":""}'
```

#### 返回示例（HTTP 200）

```json
{ "recorded": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `recorded` | 固定为 `true`，回执已记录 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 请求体不是合法 JSON；`revision` 不是整数、`status` 不是 applied/error、`message` 不是字符串或超过 500 字；服务端内部异常（代码现状按 400 返回） | 修正请求 |
| 401 | 设备凭证无效 | 联系运维 |
| 403 | 设备已在后台停用 | 联系运维 |
| 409 | 回执的修订号不是当前已保存的修订号，或配置尚未保存 | 重新读取配置后再回执 |

### 设备心跳
#### 功能描述

用设备凭证自检并刷新设备“最近心跳”时间，返回本设备所属门店与点位。互动点位和纯展示点位的设备都可调用时也可调用。

说明：任何设备接口鉴权成功都会刷新最近心跳，不一定要单独调用本接口；同一设备 30 秒内只写一次库，期间调用仍返回 `recorded: true`。后台按最近心跳超过 10 分钟判定设备离线（2026-10-06 确认）。

#### 请求参数（Body）

无。服务端不读取请求体，可发送空对象 `{}`。

#### 请求示例

```bash
curl -X POST "$BASE/api/devices/heartbeat" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{ "deviceId": "CQ-GUANGHUAN-P04-PLAYER", "storeId": "CQ-GUANGHUAN", "pointId": "P04", "recorded": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `deviceId` / `storeId` / `pointId` | 凭证对应的设备、门店、点位，以此核对本机配置 |
| `recorded` | 固定为 `true` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 缺少 Bearer 凭证、格式不对或设备凭证无效 | 联系运维更换凭证；播控电脑需重新配对 |
| 403 | 设备已在后台停用 | 联系运维 |

### 素材显示尺寸（2026-10-07）

素材规格由CMS上传决定。每个条目的显示尺寸由后台点位素材编排明确选择，随条目下发：

| 字段 | 值 | 含义 |
| --- | --- | --- |
| fit | contain | 默认选项：按输出区域宽高100%等比完整显示，比例不一致留边 |
| fit | cover | 按输出区域宽高100%裁切铺满 |
| fit | custom | 按屏幕百分比自定义宽高，画面居中，区域内等比完整显示；仅v2中控播控（`/api/point-display/v2/manifest`）提供 |
| customSize | `{"widthPct":80,"heightPct":60}` | 仅fit=custom时出现，宽高均为1—100整数（屏幕百分比） |

后台保存时未选显示尺寸的条目按 `contain` 写入（2026-10-07默认值确认），因此下发的条目都带fit；custom缺customSize或数值越界时后台拒绝保存、manifest返回409。v1 [读取展示配置](#api-display-config)遇到custom条目返回409（自定义显示尺寸需使用v2播控客户端）。客户端不得把缺失或无法识别的显示尺寸替换为其他显示方式，应拒绝该清单并回报错误。

v2条目示例：

```json
{"assetId":"素材ID","type":"image","durationMs":5000,"fit":"custom","customSize":{"widthPct":80,"heightPct":60},"name":"门店主视觉","url":"https://已配置访问域名/asset/...","mimeType":"image/png","fileSize":1234,"sha256":"64位小写十六进制"}
```

### 后台保存默认值（2026-10-07确认）

用户确认简化操作：后台保存点位展示配置时，下列字段未填写（缺省或null）即按默认值生效，并把实际取用的值写入已保存配置（客户端读到的始终是明确值，不会出现空值）；后台填写的值优先，非法值仍拒绝。

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| playMode | sequential | 按清单顺序轮播 |
| endBehavior | loop | 重新循环整单 |
| 条目 fit | contain | 等比完整显示 |
| 图片/图文 durationMs | 10000 | 展示10秒 |
| 视频 videoEnd | next | 播放下一项 |
| 视频 muted | false | 开启声音 |
| runtimeLeaseMs（仅中控播控） | 20000 | 运行状态有效期=4倍默认心跳，可容忍连续3次心跳丢失 |
| playerPolicy（仅中控播控） | `{"startup":"wait_for_pad","offline":"play_cached","failure":"report_error","protocol":"ndjson_v1"}` | 控制方选中控Pad即启用，不再人工勾选；传入其他规则值（含旧协议值 `ndjson_hmac_v1`）返回400。2026-10-07“中控通信简化”：协议为局域网明文NDJSON（无签名、无IP白名单，保留同一请求号不重复执行与pointId核对）；已保存的旧协议值由迁移053改写为 `ndjson_v1` 并递增配置修订号 |

控制方（controlOwner）未传时按中控Pad写入，传其他值返回400：所有点位统一由中控Pad控制（2026-10-07确认）。

### 纯展示点位（2026-10-07）

后台可为门店新建多个纯展示点位（如一楼超大屏），点位目录类型为“展示屏”（D01），点位编号以D开头。应用类型固定普通展示（applicationType=display），播控固定由中控Pad发信号切换（controlOwner=central_pad），后台保存不自行切画面；暂不做排期。

展示点位的设备只可调用 `/api/point-display/*`（含v2 manifest/boot/runtime/content-ack）与[设备心跳](#api-device-heartbeat)；调用互动、扫码登录、当前用户、画像等其他设备接口一律返回403。后台停用的设备调用任何设备接口均返回403（设备已在后台停用）。

### 现场模式切换

现场模式切换由运维协调，服务端不会因此结束现有用户互动或处理Token。客户端应执行现场操作安排；新的Agent体验在普通展示应用下会被拒绝；2026-10-13 起不再要求播控正在显示互动应用（见[开始体验](#api-interaction-create)）。

## 公用｜播控配对与配置下发（2026-10-07）

本章供点位PC上的CMS播控软件，以及在后台登记播控的运营、运维人员使用。2026-10-07确认“播控配置简化”：播控首次运行（或本机配置缺失/损坏、AgentOS地址变更、凭据失效）只需输入“AgentOS地址 + 点位码”。身份、点位、规则、运行参数、网页地址、素材域名、接口清单与中控监听参数都由AgentOS下发，播控只读核对。同日确认“中控通信简化”：中控Pad与播控处于专用局域网，取消Pad IP白名单与指令签名，不再下发controllerId、keyId、签名密钥与白名单。互动点位（AIVA面基、AI音乐、AI车衣共创、AI图片生成）与纯展示点位都使用本章接口。旧版展示接口见 [展示配置](#api-display-config)、[展示回执](#api-display-ack)；设备心跳见 [设备心跳](#api-device-heartbeat)。

前置迁移：`051_player_pairing.sql` 未执行前，配对、点位码、播控菜单接口不可用；`053_central_pad_lan_ndjson.sql` 未执行前，中控Pad登记与设备配置下发不可用；`054_player_command.sql` 未执行前，后台播放控制接口不可用。后台保存的内容都不代表现场已生效，播控在下一次同步配置时读取。

### 点位码与绑定规则

| 规则 | 说明 |
| --- | --- |
| 点位码 | 后台点位详情“播控”菜单生成，格式 `PC-` + 20位Crockford Base32（100bit随机熵），永久有效；服务端只存哈希，明文只在生成/重置时显示一次 |
| 输入容忍 | 服务端忽略大小写、空格与短横线分组，并按Crockford规则把O视为0、I/L视为1 |
| 一点位一台 | 同一点位已有绑定的播控电脑时，新电脑使用点位码一律返回409，须后台先“解绑” |
| 重置 | 后台重置点位码后旧码作废，该点位通过配对绑定的播控电脑凭据同时失效（设备接口返回401），须用新码重新配对 |
| 解绑 | 吊销该点位播控电脑的凭据，保留设备记录；之后新电脑可用现有点位码重新配对 |
| 设备凭据 | 配对成功返回一次 `deviceToken`，服务端只存哈希。之后所有设备接口用 `Authorization: Bearer <deviceToken>`；后台不能手工设定播控电脑的凭据 |

### 运行参数默认值与范围（2026-10-07确认）

后台“播控”菜单未登记运行参数、点位展示未登记运行状态有效期时，按下列默认值下发，并在设备配置中以 `runtimeSource` / `runtimeLeaseSource` = `default` 标注；后台登记的值优先。已登记但内容损坏时不用默认值替代，直接报“配置不完整”。

| 参数 | 默认值（毫秒） | 允许范围（毫秒整数） | 默认值理由 |
| --- | --- | --- | --- |
| 运行状态有效期 `runtimeLeaseMs` | 20000 | 5000—300000（在点位展示中登记） | 4倍心跳，可容忍连续3次心跳丢失 |
| 心跳间隔 `heartbeatMs` | 5000 | 1000—60000，且须小于运行状态有效期的一半 | 每5秒回报一次运行状态 |
| 网络超时 `networkMs` | 3000 | 1000—120000 | 小于心跳间隔，避免请求堆叠，断网判定在3秒内完成 |
| 切换超时 `transitionMs` | 10000 | 1000—120000 | 覆盖网页加载与媒体停止确认 |
| 同步间隔 `pollMs` | 30000 | 1000—3600000 | 兼顾内容更新及时性与请求量 |
| 中控监听端口 | 9850 | 1024—65535（在“门店中控Pad”登记，全店统一） | — |

四项运行参数的取值范围与播控客户端现有校验一致；代码注释标注该范围本身仍待用户确认（待确认）。播控规则在选中控Pad时固定为 `{"startup":"wait_for_pad","offline":"play_cached","failure":"report_error","protocol":"ndjson_v1"}`：由中控Pad控制切换、断网时使用最后一次同步的配置与素材播放、失败如实报错、局域网明文NDJSON协议。

**打开后画面**（2026-10-10，后台“点位详情 → 播控”按点位设置，随设备配置 `startupScreen` 下发）：`wait_for_pad` 等待中控指令（从未设置过即为此值）、`play_cms` 自动播放展览内容（后台最新保存的版本；断网启用时按离线规则播放最后同步的版本）、`app` 自动打开互动应用（仅登记了网页地址的Agent互动点位可选；断网时打不开，报错）。播控每次启用（程序打开自动启用、运维手动启用）后执行一次，与中控指令走同一切换流程；之后中控Pad与后台随时可以切换。自动显示失败照常报错并留本机审计，不改播其他内容、不自动重试。需播控 0.2.0 及以上版本；旧版播控忽略此项，仍等待中控指令。

### 播控接入顺序

1. 连接向导：调用 [播控配对](#api-player-pair) 换取设备凭据，再调用 [读取设备配置](#api-player-device-profile)，运维逐项核对后确认。
2. 每次启动：调用 [登记启动](#api-player-boot) 取得本次启动序号，读取 [内容清单](#api-player-manifest)，下载素材并校验SHA-256后用 [内容回执](#api-player-content-ack) 回报 `ready`；随后监听中控端口，再按设备配置 `startupScreen` 显示打开后画面（`wait_for_pad` 时画面等待中控指令）。
3. 运行中：每个心跳间隔调用 [运行回报](#api-player-runtime)（这就是播控的“心跳”）；心跳成功后调用 [领取后台指令](#api-player-commands-pull)，执行后用 [回报指令结果](#api-player-commands-result) 回报。每个同步间隔重新读取设备配置，`profileRevision` 变化时自动应用。
4. 断网：使用最后一次同步的配置、中控监听端口与素材继续播放；运行回报与内容回执按发生顺序排队，恢复后按序补报。断网时不能切到互动应用。

每次设备鉴权成功都会刷新该设备的最近心跳时间（30秒内不重复写入），后台据此判断设备是否离线。

### 播放控制（后台指令）说明（2026-10-07确认）

运维可在任何时候于后台或中控Pad操作，同一点位以最后一条指令为准。后台不能直连现场局域网：后台写入指令，播控在每次运行回报成功后领取并执行，再回报结果。指令写入后 **30秒** 内未被领取即作废（`expired`，播控可能离线），播控恢复联网后不会补执行旧指令。

| 指令 action | 后台显示 | 说明 |
| --- | --- | --- |
| `play_cms` | 立即播放展览内容 | 播放后台最新保存的展示配置版本（写入时记入 `contentRevision`）；播控未缓存该版本时先同步并做SHA-256校验再播放，失败如实报错，不改播旧版本；正在播放同一版本且处于暂停时，等同“继续” |
| `app` | 切换应用模式 | 仅互动（Agent）点位，且已在“播控”菜单登记网页地址 |
| `pause` | 暂停 | 定格当前画面（视频停在当前帧、图片停止轮播）；只用于展览模式，应用模式下播控回报失败 |
| `resume` | 继续播放 | 从暂停位置接着播 |
| `exit` | 退出播放 | 停止展览与互动输入/采集，关闭播控全部播放窗口（展览与互动网页）；播控程序、心跳与中控监听继续运行。之后 `play_cms` 或 `app` 会重新打开窗口（互动网页重新加载并完成握手）。屏幕上未完成的体验画面不再保留，AgentOS侧互动记录不因此结束 |

切换画面不结束现有互动、不取消生成任务、不改变Token（与中控Pad切换规则相同）。播控处于“本地接管”时，后台指令与Pad指令一样被拒绝（播控回报失败，原因 `LOCAL_LOCKED`）。

| 指令状态 status | 含义 |
| --- | --- |
| `pending` | 等待播控领取 |
| `delivered` | 已送达播控，执行中 |
| `applied` | 已执行 |
| `failed` | 执行失败，`message` 为原因 |
| `expired` | 30秒内未被领取，作废（提示“未送达”） |
| `superseded` | 尚未领取时被同点位的新指令取代 |

### 播控配对
#### 功能描述

播控电脑凭后台生成的点位码换取设备凭据。服务端为该点位登记一台播控设备（设备类型 `player_pc`，设备编号 `{storeId}-{pointId}-PLAYER`；同编号设备已存在且未绑定时复用），并在同一事务写入配对留痕。

调用时机：首次运行、本机配置缺失或损坏、修改AgentOS地址、设备接口返回401（凭据失效）后重新连接时。请求结果未知（如网络中断）时不要换电脑重试，先在后台“播控”菜单核对是否已绑定。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `pointCode` | string | 必填 | 后台生成的点位码；忽略大小写、空格与短横线分组 | `PC-8K2M4P6R8T0V2X4Z6B9D` |
| `machineName` | string | 必填 | 本机计算机名，去掉首尾空格后1—64字、不含控制字符，仅用于后台核对 | `P02-PLAYER-PC` |

#### 请求示例

```bash
curl -X POST "$BASE/api/player/pair" \
  -H "Content-Type: application/json" \
  --data '{"pointCode":"PC-8K2M4P6R8T0V2X4Z6B9D","machineName":"P02-PLAYER-PC"}'
```

#### 返回示例（HTTP 201）

```json
{
  "tenantId": "t_saisi",
  "storeId": "CQ-GUANGHUAN",
  "pointId": "P02",
  "deviceId": "CQ-GUANGHUAN-P02-PLAYER",
  "deviceToken": "dt_只返回这一次的设备凭据"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `tenantId` / `storeId` / `pointId` | 点位码对应的租户、门店、点位 |
| `deviceId` | 本次登记的播控设备编号 |
| `deviceToken` | 设备凭据，之后放在 `Authorization: Bearer`；只返回这一次，立即加密保存，不要写入日志 |

响应带 `Cache-Control: no-store`。

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `BAD_REQUEST` | 请求体不是对象；点位码为空；机器名缺失、超过64字或含控制字符 | 修正输入后重新连接 |
| 400 | `POINT_CODE_FORMAT` | 点位码格式错误（不是 `PC-` 加20位字母数字） | 提示核对点位码 |
| 401 | `POINT_CODE_INVALID` | 点位码不存在或已被重置 | 提示向后台索取当前点位码 |
| 409 | `POINT_ALREADY_BOUND` | 该点位已有绑定的播控电脑 | 请后台“播控”菜单先解绑，再连接 |
| 409 | `DEVICE_DISABLED` | 该点位的播控设备已在后台停用 | 请后台在“设备与打印”恢复设备后再配对 |
| 409 | `DEVICE_ID_CONFLICT` | 播控设备编号已被其他门店/点位或其他类型设备占用 | 请后台核对设备台账 |
| 409 | `DEVICE_ID_INVALID` | 门店/点位编号拼出的设备编号不合规（须3—64位字母数字及 `._-`） | 请后台核对门店/点位编号 |

错误响应体为 `{"error":"中文说明","code":"错误码"}`，不自动重试。

### 读取设备配置
#### 功能描述

返回播控运行所需的全部只读配置：身份、点位、规则、运行参数、网页地址、素材域名、接口清单与中控监听参数。播控以 `profileRevision` 判断配置是否变化，变化时自动应用；网页地址变化需退出并重新打开播控才生效。

任一必需项缺失时整体返回409并逐条列出缺失项，不下发残缺配置。运行参数、运行状态有效期、中控监听端口未登记时按默认值下发（见上文“运行参数默认值与范围”）；网页地址、素材域名等其他项不设默认值。

#### 请求参数

无。只需请求头中的设备凭据。

#### 请求示例

```bash
curl "$BASE/api/point-display/v2/device-profile" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{
  "profileRevision": "9f2c4e7a…（64位十六进制）",
  "tenant": { "id": "t_saisi" },
  "store": { "id": "CQ-GUANGHUAN", "name": "重庆光环店" },
  "point": { "id": "P02", "name": "AIVA面基", "location": "一楼东侧", "catalogId": "P02", "category": "interaction", "applicationType": "agent", "controlOwner": "central_pad" },
  "device": { "id": "CQ-GUANGHUAN-P02-PLAYER" },
  "protocol": "ndjson_v1",
  "policies": { "startup": "wait_for_pad", "offline": "play_cached", "failure": "report_error" },
  "runtimeLeaseMs": 20000,
  "runtimeLeaseSource": "default",
  "runtime": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
  "runtimeSource": "default",
  "startupScreen": "wait_for_pad",
  "screens": [{ "key": "main", "name": "主屏", "width": null, "height": null, "touch": true, "appUrl": "https://p02.example.com/" }],
  "appUrl": "https://p02.example.com/",
  "apiPaths": ["/api/identity/point-login", "/api/identity/me", "/api/interactions/:id", "…"],
  "mediaOrigins": ["https://assets.example.com"],
  "control": { "listenHost": "0.0.0.0", "listenPort": 9850, "protocol": "ndjson_v1", "signing": false }
}
```

| 返回字段 | 说明 |
| --- | --- |
| `profileRevision` | 对下发内容（含 `control`）计算的SHA-256，任一来源变化即变化；按严格相等判断 |
| `store.name` / `point.name` | 门店名；点位优先取门店自定义名，未设置用目录名。`point.location` 可为 `null` |
| `point.category` | 点位目录类别：`display` 为纯展示点位，其他为互动类 |
| `point.applicationType` / `point.controlOwner` | 应用类型 `agent`/`display`；控制方恒为 `central_pad` |
| `protocol` / `policies` | 中控协议与启动、离线、失败规则，取值固定见上文 |
| `runtimeLeaseMs` / `runtimeLeaseSource` | 运行状态有效期及来源 `configured`（已登记）/`default`（按默认值） |
| `runtime` / `runtimeSource` | 网络超时、切换超时、同步间隔、心跳间隔（毫秒）及来源 |
| `startupScreen` | 打开后画面：`wait_for_pad` 等待中控指令 / `play_cms` 自动播放展览内容 / `app` 自动打开互动应用（见上文“打开后画面”） |
| `screens` | 这个点位的屏幕（2026-10-10 多屏）：`key` 屏幕标识（第一块恒为 `main` 主屏）、`name` 名称、`width`/`height` 建议分辨率（像素，未填为 `null`，播控据此自动对应本机屏幕）、`touch` 是否触摸屏、`appUrl` 这块屏的互动网页（主屏＝`appUrl`；其他屏未登记为 `null`，互动时继续播自己的展览素材）。未在后台添加屏幕的点位只有主屏 |
| `appUrl` | 互动点位的正式网页地址（即主屏网页）；纯展示点位恒为 `null` |
| `apiPaths` | 互动网页经播控转发可调用的正式接口（`:param` 匹配单段），清单见下文；纯展示点位为空数组 |
| `mediaOrigins` | 允许下载素材的域名：由存储设置 `storage.public_base_url` 推导，另加当前清单中外部地址素材的域名 |
| `control` | 中控监听参数：本机所有网卡、门店登记端口（未登记按9850）、`ndjson_v1`、恒不签名 |

响应带 `Cache-Control: no-store`。原 `centralPad` 字段已删除。

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 401 | — | 缺少设备凭据或格式不对；凭据无效、已被解绑或点位码重置吊销 | 回到连接向导，用点位码重新配对 |
| 403 | — | 设备已在后台停用 | 联系运维恢复设备 |
| 409 | `PLAYER_PROFILE_INCOMPLETE` | `error` 中逐条列出缺失项：点位展示配置未保存；控制方不是中控Pad；协议与规则未登记，或已保存规则与现行确认值不一致（如迁移053未执行时残留 `ndjson_hmac_v1`）；已登记的运行参数不完整；心跳间隔不小于运行状态有效期的一半；互动点位网页地址未登记；素材访问域名未登记、格式无效或读取失败；素材缺少有效访问地址 | 原样展示后台说明，不允许继续；后台修正后重新读取 |
| 409 | `POINT_MISSING` | 点位或点位目录缺失 | 联系管理员核对点位数据 |

### 登记启动
#### 功能描述

播控每次启动生成一个新的启动编号 `bootId` 并登记，服务端返回本设备递增的启动序号 `bootOrdinal`，后续运行回报必须带上这两个值。首次登记会把本设备的运行状态重置为“未显示、未启用”，事件序号归零，因此旧进程的回报会被拒绝。

同一个 `bootId` 原样重发不会重复登记，返回第一次的序号，也不会再次重置运行状态。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `bootId` | string | 必填 | 本次启动的唯一编号，1—64字、不含控制字符 | `b7c1e0d2-5f3a-4c8e-9a11-2d4f6b8c0e13` |

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/v2/boot" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"bootId":"b7c1e0d2-5f3a-4c8e-9a11-2d4f6b8c0e13"}'
```

#### 返回示例（HTTP 200）

```json
{ "bootOrdinal": 3 }
```

| 返回字段 | 说明 |
| --- | --- |
| `bootOrdinal` | 本设备第几次启动，从1开始递增 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `bootId` 为空、超过64字或含控制字符；请求体不是合法JSON | 修正后重新登记 |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |

### 读取内容清单
#### 功能描述

返回点位当前保存的展示配置版本及已审核素材清单（含下载地址、大小与SHA-256），与当前实际显示模式无关。播控下载并校验全部素材后才能切换到该版本；中控或后台切换前也会先读取一次核验最新版本，读取不到（断网）时按离线规则只播放最后同步的版本。

条目显示尺寸 `fit`、`customSize` 的含义见 [展示模式与素材播放](#display)。

#### 请求参数

无。只需请求头中的设备凭据。

#### 请求示例

```bash
curl "$BASE/api/point-display/v2/manifest" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL"
```

#### 返回示例（HTTP 200）

```json
{
  "schemaVersion": 2,
  "tenantId": "t_saisi",
  "storeId": "CQ-GUANGHUAN",
  "pointId": "D01",
  "deviceId": "CQ-GUANGHUAN-D01-PLAYER",
  "controlOwner": "central_pad",
  "revision": 12,
  "applicationType": "display",
  "runtimeLeaseMs": 20000,
  "playerPolicy": { "startup": "wait_for_pad", "offline": "play_cached", "failure": "report_error", "protocol": "ndjson_v1" },
  "playMode": "sequential",
  "endBehavior": "loop",
  "items": [
    { "assetId": "as_101", "type": "image", "durationMs": 10000, "fit": "contain", "name": "门店主视觉", "url": "https://assets.example.com/asset/…", "mimeType": "image/png", "fileSize": 1234, "sha256": "64位小写十六进制" },
    { "assetId": "as_102", "type": "video", "videoEnd": "next", "muted": false, "fit": "custom", "customSize": { "widthPct": 80, "heightPct": 60 }, "name": "新车宣传片", "url": "https://assets.example.com/asset/…", "mimeType": "video/mp4", "fileSize": 52428800, "sha256": "64位小写十六进制" }
  ]
}
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 展示配置版本号，切换CMS、内容回执与运行回报都引用它 |
| `applicationType` | `agent` 互动点位 / `display` 普通展示 |
| `runtimeLeaseMs` / `playerPolicy` | 运行状态有效期与播控规则 |
| `playMode` / `endBehavior` | 播放方式 `sequential`/`shuffle`/`single`；整单结束 `loop`/`stop` |
| `stopBehavior` | 仅 `endBehavior=stop` 时出现：`hold` 保留末帧 / `blank` 空白 |
| `items[]` | 图片、图文条目带 `durationMs`；视频条目带 `videoEnd`（`loop`/`next`）与 `muted`；图文条目另带 `template`（`caption`）、`title`、`body`；都带 `fit`，`fit=custom` 时带 `customSize` |
| `items[].url` / `fileSize` / `sha256` | 下载地址、字节数与SHA-256；下载后不一致即拒绝该版本 |
| `screens[]` | 每块屏各自的播放清单（2026-10-10 多屏）：`key`、`name`、`width`/`height`、`touch`，以及该屏自己的 `playMode`/`endBehavior`/`stopBehavior`/`items`（结构同上）。顶层 `playMode`/`endBehavior`/`items` 始终等于主屏（`key=main`），旧版播控只播主屏；只有一块屏的点位 `screens` 只有主屏 |

响应带 `Cache-Control: no-store`。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |
| 409 | 点位展示配置未保存或控制方不是中控Pad；素材不存在、类型不符、未审核或不在本店范围；素材缺少有效访问地址；素材缺少SHA-256、文件大小或明确显示尺寸 | 保持当前画面，记录错误并回报 `error` 内容回执；请后台修正 |

### 回报内容状态
#### 功能描述

回报某个内容版本在本机的处理阶段，供后台“点位展示”查看。`applied` 只能在运行回报已报告该版本CMS稳定显示后提交；同一版本已是 `applied` 时，之后定期验证提交的 `cached`/`ready` 不会把它降回“尚未显示”。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `revision` | integer | 必填 | 内容版本号，≥1，须是该点位保存过的版本 | `12` |
| `stage` | string | 必填 | `cached` 已下载 / `ready` 已缓存并通过SHA-256校验 / `applied` 已显示 / `error` 失败 | `ready` |
| `message` | string | 必填 | 说明，0—500字，可为空串 | `素材已缓存并通过SHA-256校验` |

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/v2/content-ack" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"revision":12,"stage":"ready","message":"素材已缓存并通过SHA-256校验"}'
```

#### 返回示例（HTTP 200）

```json
{ "recorded": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `recorded` | 已记录 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `revision` 不是≥1的整数；`stage` 不在四个取值内；`message` 缺失或超过500字 | 修正参数 |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |
| 409 | 内容版本不存在；`applied` 时设备尚未回报此版本CMS稳定显示 | 补报旧回执时被拒绝的记入本机审计后丢弃，不重复提交 |

### 回报运行状态（心跳）
#### 功能描述

回报本机实际显示模式、阶段、内容版本、控制方及输出就绪状态。这是播控的“心跳”：按心跳间隔调用，成功后再领取后台指令。

新互动准入（`admissionAllowed=true`）须同时满足：控制方为中控Pad、应用类型为Agent互动（2026-10-13 起不再看门店营业与点位启用）、最近回报为应用模式稳定显示（`app`/`ready`）且网页与输出就绪、回报未超过运行状态有效期。切换前先回报 `switching` 关闭准入。

服务端拒绝旧进程、乱序和同一序号不同内容的回报。同一序号、内容完全相同的重发不会重复写入，返回已记录结果，也不刷新运行状态有效期。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `bootId` | string | 必填 | 本次启动编号，须与最近一次登记启动一致 | `b7c1e0d2-…` |
| `bootOrdinal` | integer | 必填 | 登记启动返回的序号，≥1 | `3` |
| `deviceSeq` | integer | 必填 | 本次启动内递增的事件序号，≥1 | `42` |
| `actualMode` | string | 必填 | `unset` 未显示 / `app` 互动应用 / `cms` 展览内容 / `unknown` 无法确认 | `cms` |
| `phase` | string | 必填 | `unconfigured` / `switching` / `ready` / `error` | `ready` |
| `contentRevision` | integer \| null | 必填 | CMS模式为实际显示版本；其他模式为最近确认的CMS版本，没有时为 `null` | `12` |
| `owner` | string | 必填 | `pad` 中控控制 / `local` 本地接管 | `pad` |
| `observedAt` | string | 必填 | 实际发生时间，北京时间ISO格式，含毫秒与 `+08:00` | `2026-10-08T10:15:30.123+08:00` |
| `details.appReady` | boolean | 必填 | 互动网页已完成握手 | `false` |
| `details.captureStopped` | boolean | 必填 | 已停止采集 | `true` |
| `details.inputEnabled` | boolean | 必填 | 已开放互动输入；只能在 `app`+`ready` 时为 `true` | `false` |
| `details.outputReady` | boolean | 必填 | 输出组已就绪 | `true` |
| `details.message` | string | 必填 | 状态说明，0—500字 | `输出组已确认目标画面就绪` |
| `details.paused` | boolean | 可选 | 展览已暂停；为 `true` 时须 `cms`+`ready` | `false` |
| `details.closed` | boolean | 可选 | 已退出播放、窗口已关闭；为 `true` 时须 `unset`+`unconfigured` | `false` |
| `details.playerVersion` | string | 可选 | 播控程序版本（0.2.0 起回报），1—32位字母、数字、`.+-`；后台“播控实际状态”显示，未回报为 0.1.0 或更早 | `0.3.0` |
| `details.localIps` | string[] | 可选 | 播控电脑的局域网IP（0.3.0 起，最多8个），供后台“指令对照表”给中控网关配置 | `["10.10.52.81"]` |
| `details.lastCommand` | object | 可选 | 最近一条指令（0.3.0 起）：`at` 北京时间、`source`（`pad` 中控/`admin` 后台/`local` 本机/`startup` 打开后画面）、`text` 指令单词、`ok` 是否执行、`message` 结果说明（≤200字）、`from` 中控来源IP（可空） | `{"at":"2026-10-10T17:42:49.000+08:00","source":"pad","text":"PLAY","ok":true,"message":"已播放展览内容 r12","from":"10.10.52.78"}` |

`phase=ready` 时须 `actualMode` 为 `app` 或 `cms` 且 `outputReady=true`；`app` 另须 `appReady=true`，`cms` 另须 `contentRevision` 不为空。

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/v2/runtime" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"bootId":"b7c1e0d2-5f3a-4c8e-9a11-2d4f6b8c0e13","bootOrdinal":3,"deviceSeq":42,"actualMode":"cms","phase":"ready","contentRevision":12,"owner":"pad","observedAt":"2026-10-08T10:15:30.123+08:00","details":{"appReady":false,"captureStopped":true,"inputEnabled":false,"outputReady":true,"message":"输出组已确认目标画面就绪","paused":false,"closed":false}}'
```

#### 返回示例（HTTP 200）

```json
{ "recorded": true, "deviceSeq": 42, "admissionAllowed": false }
```

| 返回字段 | 说明 |
| --- | --- |
| `recorded` | 已记录 |
| `deviceSeq` | 本次回报的事件序号 |
| `admissionAllowed` | 是否允许互动网页接收新互动；为 `false` 时播控须关闭互动输入 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 字段缺失或取值无效；`observedAt` 不是北京时间ISO格式；`details` 不完整或说明超过500字；`paused`/`closed`/`inputEnabled` 与模式阶段不符；`ready` 缺少对应就绪状态或版本；`playerVersion`、`localIps`、`lastCommand` 格式无效 | 修正后以新序号回报 |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |
| 409 | 启动回报已过期（未登记或 `bootId`/`bootOrdinal` 不是最近一次）；设备绑定已改变；序号小于已记录序号（乱序）；同一序号内容不同；`contentRevision` 不是该点位保存过的版本 | 启动过期时重新登记启动；补报旧回报被拒绝时记入本机审计后丢弃，再以最新状态回报 |

### 领取后台指令
#### 功能描述

领取本点位最新一条未过期、待领取的后台指令。返回即标记为已送达本设备，同一条指令只下发一次；没有指令时返回 `command: null`。领取前服务端先把超过30秒未领取的指令标记为作废。指令含义见上文“播放控制（后台指令）说明”。

#### 请求参数（Body）

无字段，发送空对象 `{}`。

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/v2/commands/pull" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{}'
```

#### 返回示例（HTTP 200）

```json
{ "command": { "commandId": "cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5", "action": "play_cms", "contentRevision": 12 } }
```

| 返回字段 | 说明 |
| --- | --- |
| `command` | 待执行指令；没有时为 `null` |
| `command.commandId` | 指令编号，回报结果时原样带回 |
| `command.action` | `play_cms` / `app` / `pause` / `resume` / `exit` / `prev` / `next` / `home` / `reload`（后四个 2026-10-10 起：上一个/下一个素材、互动回到首页/刷新网页） |
| `command.contentRevision` | `play_cms` 时为后台最新保存的版本号；其他指令为 `null` |

响应带 `Cache-Control: no-store`。

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |
| 网络不可达 | 断网 | 本次不领取；断网期间写入的指令30秒后作废，恢复后不补执行 |

### 回报指令结果
#### 功能描述

回报后台指令的执行结果，后台“播放控制”据此显示“已执行”或“执行失败”及原因。同一结果原样重发不会重复写入，返回第一次的结果；已有结果后改成另一种结果会被拒绝。

#### 请求参数（Body）

| 字段 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `commandId` | string | 必填 | 领取时得到的指令编号，1—64字 | `cmd_3f9c0d1e…` |
| `status` | string | 必填 | `applied` 已执行 / `failed` 执行失败 | `applied` |
| `message` | string | 必填 | 结果说明或失败原因，0—500字 | `已播放展览内容 r12` |

#### 请求示例

```bash
curl -X POST "$BASE/api/point-display/v2/commands/result" \
  -H "Authorization: Bearer $DEVICE_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"commandId":"cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5","status":"applied","message":"已播放展览内容 r12"}'
```

#### 返回示例（HTTP 200）

```json
{ "recorded": true }
```

| 返回字段 | 说明 |
| --- | --- |
| `recorded` | 已记录 |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `commandId` 为空、超过64字或含控制字符；`status` 不是 applied/failed；`message` 缺失或超过500字 | 修正参数 |
| 401 | 设备凭据无效、已被解绑或点位码重置吊销 | 回到连接向导重新配对 |
| 403 | 设备已在后台停用 | 联系运维恢复设备 |
| 404 | 指令不存在或不是本设备领取的指令 | 记入本机审计，不重试 |
| 409 | 指令已有另一种结果，不能改写 | 记入本机审计，不重试 |

### 互动网页可调用的接口清单

设备配置 `apiPaths` 当前下发以下接口（互动点位）；播控只转发清单内的请求，`:param` 匹配单段：

```text
/api/identity/point-login  /api/identity/me  /api/identity/logout  /api/identity/profile/:resource  /api/identity/profile-summary
/api/interactions/config  /api/interactions/config/ack  /api/interactions  /api/interactions/:id
/api/interactions/:id/consent  /api/interactions/:id/consent/revoke  /api/interactions/:id/answers  /api/interactions/:id/confirm
/api/interactions/:id/restart  /api/interactions/:id/end  /api/interactions/:id/events
/api/interactions/:id/text-tasks  /api/interactions/:id/text-tasks/:taskId  /api/interactions/:id/image-tasks  /api/interactions/:id/image-tasks/:taskId
/api/interactions/:id/tts  /api/interactions/:id/voice-tasks/:taskId  /api/interactions/:id/result/complete
/api/interactions/:id/music-selection  /api/interactions/:id/music-selection/confirm  /api/interactions/:id/lyrics  /api/interactions/:id/lyrics/confirm
/api/interactions/:id/music-tasks  /api/interactions/:id/music-tasks/:taskId  /api/interactions/:id/music-tasks/:taskId/check
/api/interactions/:id/works  /api/interactions/:id/works/:assetId/preview  /api/users/me/works  /api/users/me/works/:assetId/preview  /api/users/me/assistant
```

不含：作品原文件二进制（`.../works/:assetId/content`）、语音识别WebSocket票据、AI音乐旧链路 `/api/p03/*`、后台接口与设备心跳（由播控主进程自行调用）。

### 生成或重置点位码
#### 功能描述

为点位生成点位码（互动点位与纯展示点位都可以）。点位码永久有效；已有点位码时须明确选择“重置”并填写原因，重置后旧码作废，同一事务吊销该点位全部已配对播控电脑的凭据，这些电脑须用新码重新配对。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号 | `CQ-GUANGHUAN` |
| `pointId` | Path | string | 必填 | 点位编号 | `P02` |
| `reset` | Body | boolean | 可选 | 尚无点位码时省略（生成）；已有点位码时须为 `true`（重置） | `true` |
| `reason` | Body | string | `reset=true` 时必填 | 重置原因，1—255字、不含控制字符 | `播控电脑更换，旧码外泄` |

#### 请求示例

```bash
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/point-code" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{"reset":true,"reason":"播控电脑更换，旧码外泄"}'
```

#### 返回示例（HTTP 200）

```json
{
  "pointCode": "PC-8K2M4P6R8T0V2X4Z6B9D",
  "reset": true,
  "revokedDeviceIds": ["CQ-GUANGHUAN-P02-PLAYER"],
  "note": "点位码只显示这一次，服务端只保存哈希，请立即抄录。旧码已作废，该点位已连接的播控凭据已同时失效，需用新码重新配对。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `pointCode` | 点位码明文，只返回这一次 |
| `reset` | 本次是否为重置 |
| `revokedDeviceIds` | 因重置被吊销凭据的播控设备；生成时为空数组 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `BAD_REQUEST` | `reset` 不是布尔值 | 修正参数 |
| 400 | `REASON_REQUIRED` | 重置时原因为空、超过255字或含控制字符 | 填写原因 |
| 400 | — | 未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对门店与点位 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `CSRF_INVALID` / `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 缺少或无效CSRF令牌；须先修改初始密码；没有 point:edit 权限 | 刷新页面；修改密码；联系管理员授权 |
| 409 | `POINT_CODE_EXISTS` | 已有点位码但未选择重置 | 确认要作废旧码时改为重置并填写原因 |
| 409 | `POINT_CODE_NOT_GENERATED` | 尚未生成点位码却选择重置 | 改为生成 |

### 查看播控菜单
#### 功能描述

读取点位的播控登记情况：是否已生成点位码（不返回码本身）、已绑定与已吊销的播控电脑、运行参数与网页地址、参数范围与默认值、实际生效的运行状态有效期，以及门店中控监听参数。`settings.runtime` 为 `null` 表示未登记，播控按默认值运行。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号 |
| `pointId` | Path | string | 必填 | 点位编号 |

#### 请求示例

```bash
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player" \
  -H "Cookie: <后台登录会话>"
```

#### 返回示例（HTTP 200）

```json
{
  "pointKind": "interaction",
  "hasPointCode": true,
  "pointCodeCreatedAt": "2026-10-07T06:00:00.000Z",
  "pointCodeCreatedBy": "staff_001",
  "boundDevices": [ { "deviceId": "CQ-GUANGHUAN-P02-PLAYER", "machineName": "P02-PLAYER-PC", "pairedAt": "2026-10-07T06:05:00.000Z", "lastHeartbeatAt": "2026-10-08T02:15:30.000Z", "adminStatus": "active", "revokedAt": null, "revokedReason": null } ],
  "unboundDevices": [],
  "settings": { "revision": 0, "runtime": null, "appUrl": null, "appUrlAllowed": true, "updatedBy": null },
  "runtimeLimits": { "networkMs": { "min": 1000, "max": 120000 }, "transitionMs": { "min": 1000, "max": 120000 }, "pollMs": { "min": 1000, "max": 3600000 }, "heartbeatMs": { "min": 1000, "max": 60000 } },
  "runtimeDefaults": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
  "runtimeNotes": { "runtimeLeaseMs": "运行状态有效期=4倍心跳，可容忍连续3次心跳丢失", "heartbeatMs": "每5秒回报一次运行状态", "networkMs": "小于心跳间隔，避免请求堆叠，断网判定在3秒内完成", "transitionMs": "覆盖网页加载与媒体停止确认", "pollMs": "兼顾内容更新及时性与请求量" },
  "runtimeSource": "default",
  "runtimeLeaseMs": 20000,
  "runtimeLeaseSource": "default",
  "controlOwner": "central_pad",
  "centralPadConfigured": false,
  "control": { "listenHost": "0.0.0.0", "listenPort": 9850, "protocol": "ndjson_v1", "signing": false, "listenPortSource": "default" },
  "note": "点位码永久有效，只在生成/重置时显示一次；同一点位已有绑定时新电脑会被拒绝，须先解绑。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `pointKind` | `interaction` 互动点位 / `display` 纯展示点位 |
| `hasPointCode` / `pointCodeCreatedAt` / `pointCodeCreatedBy` | 是否已生成点位码、生成时间与操作人 |
| `boundDevices` / `unboundDevices` | 当前持有有效凭据的播控电脑 / 已解绑或被重置吊销的播控电脑（含吊销时间与原因） |
| `settings` | 播控设置修订号、已登记运行参数（未登记为 `null`）、网页地址、是否允许填写网页地址（纯展示点位为 `false`） |
| `runtimeLimits` / `runtimeDefaults` / `runtimeNotes` | 参数范围、默认值与默认值理由，页面预填用 |
| `runtimeSource` | 运行参数来源 `configured`/`default` |
| `runtimeLeaseMs` / `runtimeLeaseSource` | 实际生效的运行状态有效期及来源 |
| `controlOwner` | 点位展示配置中的控制方；未保存时为 `null` |
| `centralPadConfigured` / `control` | 门店是否登记中控Pad；下发给播控的中控监听参数及端口来源 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | — | 未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对门店与点位 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 须先修改初始密码；没有 point:view 权限 | 修改密码；联系管理员授权 |
| 409 | `CATALOG_MISSING` | 点位目录缺失 | 联系管理员核对点位数据 |

### 解绑播控电脑
#### 功能描述

吊销该点位已绑定播控电脑的设备凭据，保留设备记录供审计。解绑后旧电脑的设备接口返回401；新电脑可用现有点位码重新配对，无需重置点位码。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号 | `CQ-GUANGHUAN` |
| `pointId` | Path | string | 必填 | 点位编号 | `P02` |
| `reason` | Body | string | 必填 | 解绑原因，1—255字、不含控制字符 | `更换播控电脑` |

#### 请求示例

```bash
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player/unbind" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{"reason":"更换播控电脑"}'
```

#### 返回示例（HTTP 200）

```json
{
  "unbound": true,
  "deviceIds": ["CQ-GUANGHUAN-P02-PLAYER"],
  "note": "设备凭据已吊销，设备记录保留可审计；新电脑可用现有点位码重新配对。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `unbound` | 已解绑 |
| `deviceIds` | 被吊销凭据的播控设备 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `REASON_REQUIRED` | 原因为空、超过255字或含控制字符 | 填写原因 |
| 400 | — | 未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对门店与点位 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `CSRF_INVALID` / `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 缺少或无效CSRF令牌；须先修改初始密码；没有 device:edit 权限 | 刷新页面；修改密码；联系管理员授权 |
| 409 | `PLAYER_NOT_BOUND` | 该点位当前没有已绑定的播控电脑 | 刷新页面核对 |

### 保存播控运行参数与网页地址
#### 功能描述

登记播控的网络超时、切换超时、同步间隔、心跳间隔，以及互动点位的正式网页地址。四项运行参数保存时须一起填写（页面预填默认值）；心跳间隔须小于实际生效的运行状态有效期的一半（有效期未登记时按默认20000毫秒校验）。保存不代表现场已生效，播控在下一次同步配置时读取。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` / `pointId` | Path | string | 必填 | 门店与点位编号 | `CQ-GUANGHUAN` / `P02` |
| `expectedRevision` | Body | integer | 必填 | 读取到的 `settings.revision`，≥0；与当前不一致时拒绝 | `0` |
| `runtime.networkMs` | Body | integer | 必填 | 网络超时，1000—120000 | `3000` |
| `runtime.transitionMs` | Body | integer | 必填 | 切换超时，1000—120000 | `10000` |
| `runtime.pollMs` | Body | integer | 必填 | 同步间隔，1000—3600000 | `30000` |
| `runtime.heartbeatMs` | Body | integer | 必填 | 心跳间隔，1000—60000 | `5000` |
| `appUrl` | Body | string \| null | 可选 | 互动点位网页地址，须 https、≤512字符、不含账号密码；仅开发环境允许 `http://localhost`、`127.0.0.1`、`[::1]`。省略=不变，`null`=清空；纯展示点位只能省略或传 `null` | `https://p02.example.com/` |

#### 请求示例

```bash
curl -X PUT "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/player/settings" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{"expectedRevision":0,"runtime":{"networkMs":3000,"transitionMs":10000,"pollMs":30000,"heartbeatMs":5000},"appUrl":"https://p02.example.com/"}'
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 1,
  "runtime": { "networkMs": 3000, "transitionMs": 10000, "pollMs": 30000, "heartbeatMs": 5000 },
  "appUrl": "https://p02.example.com/",
  "clientApplied": false,
  "note": "播控在下一次同步配置时读取；保存不代表现场已生效。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 新的播控设置修订号 |
| `runtime` / `appUrl` | 已保存的值（网页地址为规范化后的地址） |
| `clientApplied` | 恒为 `false`：保存不代表播控已应用 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `BAD_REQUEST` | 缺少修订号；运行参数缺项或超出范围；网页地址格式错误、不是https或含账号密码；纯展示点位填写网页地址 | 按提示修正 |
| 400 | `HEARTBEAT_TOO_LONG` | 心跳间隔不小于运行状态有效期的一半 | 缩短心跳间隔，或在点位展示中加长有效期 |
| 400 | — | 未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对门店与点位 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `CSRF_INVALID` / `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 缺少或无效CSRF令牌；须先修改初始密码；没有 point:edit 权限 | 刷新页面；修改密码；联系管理员授权 |
| 404 | — | 点位目录缺失 | 联系管理员核对点位数据 |
| 409 | `REVISION_CONFLICT` | 播控设置已被他人修改 | 刷新后重新填写 |

### 查看门店中控Pad
#### 功能描述

读取门店中控Pad登记：播控监听端口（全店统一）及可选的Pad名称/IP备注。一家门店一台中控Pad，控制该店所有点位；专用局域网内明文NDJSON通信，不做IP白名单与签名。未登记时返回 `configured:false`，端口按默认9850。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号，不能为 `*` |

#### 请求示例

```bash
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/central-pad" \
  -H "Cookie: <后台登录会话>"
```

#### 返回示例（HTTP 200）

```json
{
  "configured": true,
  "listenPort": 9850,
  "listenPortSource": "configured",
  "padName": "一楼中控Pad",
  "padIp": "192.168.10.20",
  "revision": 1,
  "updatedBy": "staff_001",
  "updatedAt": "2026-10-07T08:00:00.000Z",
  "defaultListenPort": 9850,
  "listenHost": "0.0.0.0",
  "portRange": { "min": 1024, "max": 65535 },
  "protocol": "ndjson_v1",
  "signing": false,
  "note": "一家门店一台中控Pad，控制该店所有点位；专用局域网内明文NDJSON通信，不做IP白名单与签名。…"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `configured` | 是否已登记；未登记时 `padName`/`padIp` 为 `null`、`revision` 为0，且不返回 `updatedBy`/`updatedAt` |
| `listenPort` / `listenPortSource` | 实际下发的监听端口及来源 `configured`/`default` |
| `padName` / `padIp` | 备注，仅供记录，不做白名单 |
| `revision` | 修订号，保存时作为 `expectedRevision` |
| `defaultListenPort` / `listenHost` / `portRange` / `protocol` / `signing` | 固定说明值 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `BAD_REQUEST` | 未指定具体门店（如 `*`） | 选择具体门店 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 须先修改初始密码；没有 device:view 权限 | 修改密码；联系管理员授权 |
| 404 | `NOT_FOUND` | 门店不存在或不在本账号门店范围 | 核对门店 |

### 登记门店中控Pad
#### 功能描述

登记播控监听端口（全店统一）与可选的Pad名称/IP备注。端口省略或为 `null` 时按默认9850保存。保存后播控在下一次同步配置时读取；端口变化时播控关闭旧监听、断开已有连接并在新端口监听。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号，不能为 `*` | `CQ-GUANGHUAN` |
| `expectedRevision` | Body | integer | 必填 | 读取到的 `revision`，未登记时为0 | `0` |
| `listenPort` | Body | integer \| null | 可选 | 1024—65535；省略或 `null` 按9850 | `9850` |
| `padName` | Body | string \| null | 可选 | ≤64字、不含控制字符；空串视为未填 | `一楼中控Pad` |
| `padIp` | Body | string \| null | 可选 | IPv4或IPv6地址，仅供记录；空串视为未填 | `192.168.10.20` |

#### 请求示例

```bash
curl -X PUT "$BASE/api/admin/stores/CQ-GUANGHUAN/central-pad" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{"expectedRevision":0,"listenPort":9850,"padName":"一楼中控Pad","padIp":"192.168.10.20"}'
```

#### 返回示例（HTTP 200）

```json
{
  "revision": 1,
  "listenPort": 9850,
  "padName": "一楼中控Pad",
  "padIp": "192.168.10.20",
  "clientApplied": false,
  "note": "保存后播控在下一次同步配置时读取；不代表现场已生效。"
}
```

| 返回字段 | 说明 |
| --- | --- |
| `revision` | 新修订号 |
| `listenPort` / `padName` / `padIp` | 已保存的值 |
| `clientApplied` | 恒为 `false`：保存不代表播控已应用 |

#### 错误情况

| HTTP | 错误码 code | 触发条件 | 调用方处理 |
| --- | --- | --- | --- |
| 400 | `BAD_REQUEST` | 未指定具体门店；端口不是1024—65535的整数；Pad名称超长或含控制字符；Pad IP不是IPv4/IPv6；缺少修订号 | 按提示修正 |
| 401 | `UNAUTHENTICATED` | 未登录后台或登录已过期 | 重新登录 |
| 403 | `CSRF_INVALID` / `MUST_CHANGE_PASSWORD` / `FORBIDDEN` | 缺少或无效CSRF令牌；须先修改初始密码；没有 device:edit 权限 | 刷新页面；修改密码；联系管理员授权 |
| 404 | `NOT_FOUND` | 门店不存在或不在本账号门店范围 | 核对门店 |
| 409 | `REVISION_CONFLICT` | 中控Pad参数已被他人修改 | 刷新后重新填写 |

### 发送播放控制指令
#### 功能描述

写入一条播放控制指令（立即播放展览、切换应用模式、暂停、继续、退出播放），由播控在下一次心跳后领取执行。新指令写入时，同点位尚未领取的旧指令标记为 `superseded`，以最后一条为准。返回 `pending` 只表示已写入，执行结果通过 [查看播控运行状态](#api-admin-display-runtime) 查看。指令含义见上文“播放控制（后台指令）说明”。

#### 请求参数（Path / Body）

| 字段 | 位置 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- | --- |
| `storeId` / `pointId` | Path | string | 必填 | 门店与点位编号 | `CQ-GUANGHUAN` / `P02` |
| `action` | Body | string | 必填 | `play_cms` / `app` / `pause` / `resume` / `exit` / `prev` / `next` / `home` / `reload`（上一个/下一个素材只在展览时有效，所有屏一起切换；回到首页/刷新网页只在互动应用时有效） | `play_cms` |

#### 请求示例

```bash
curl -X POST "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/display/commands" \
  -H "Cookie: <后台登录会话>" \
  -H "X-CSRF-Token: <csrfToken>" \
  -H "Content-Type: application/json" \
  --data '{"action":"play_cms"}'
```

#### 返回示例（HTTP 200）

```json
{
  "commandId": "cmd_3f9c0d1e2a4b5c6d7e8f90a1b2c3d4e5",
  "action": "play_cms",
  "label": "立即播放展览内容",
  "contentRevision": 12,
  "status": "pending",
  "requestedBy": "staff_001",
  "requestedAt": "2026-10-08T02:15:00.000Z",
  "expiresAt": "2026-10-08T02:15:30.000Z",
  "deviceId": null,
  "deliveredAt": null,
  "finishedAt": null,
  "message": null
}
```

| 返回字段 | 说明 |
| --- | --- |
| `commandId` | 指令编号 |
| `label` | 指令中文名 |
| `contentRevision` | `play_cms` 时为写入时后台最新保存的版本；其他指令为 `null` |
| `status` | 写入后为 `pending`，状态取值见上文 |
| `expiresAt` | 领取截止时间（写入后30秒） |
| `deviceId` / `deliveredAt` / `finishedAt` / `message` | 领取设备、送达时间、结束时间与结果说明，写入时为 `null` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | `action` 不在五个取值内；未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对后重试 |
| 401 | 未登录后台或登录已过期 | 重新登录 |
| 403 | 缺少或无效CSRF令牌；须先修改初始密码；没有 point:edit 权限 | 刷新页面；修改密码；联系管理员授权 |
| 409 | 点位没有已连接且未停用的播控电脑；`play_cms` 时未保存展示素材清单；`app` 时为普通展示点位或未登记网页地址 | 按提示完成配对、保存素材或登记网页地址（2026-10-13 起门店未营业、点位未启用也可发指令） |

### 查看播控运行状态
#### 功能描述

读取该点位播控的最新运行回报、内容回执、播放控制可用性与最近10条后台指令。运行回报 `details.paused=true` 表示展览已暂停，`details.closed=true` 表示已退出播放。`stale=true` 表示回报已超过运行状态有效期（播控可能离线）。

#### 请求参数（Path）

| 字段 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `storeId` | Path | string | 必填 | 门店编号 |
| `pointId` | Path | string | 必填 | 点位编号 |

#### 请求示例

```bash
curl "$BASE/api/admin/stores/CQ-GUANGHUAN/points/P02/display/runtime" \
  -H "Cookie: <后台登录会话>"
```

#### 返回示例（HTTP 200）

```json
{
  "items": [
    { "device_id": "CQ-GUANGHUAN-P02-PLAYER", "boot_id": "b7c1e0d2-…", "boot_ordinal": 3, "device_seq": 42, "actual_mode": "cms", "phase": "ready", "content_revision": 12, "owner": "pad", "details": { "appReady": false, "captureStopped": true, "inputEnabled": false, "outputReady": true, "message": "输出组已确认目标画面就绪", "paused": false, "closed": false }, "observed_at": "2026-10-08T02:15:30.123Z", "updated_at": "2026-10-08T02:15:30.456Z", "admissionAllowed": false, "stale": false }
  ],
  "contentAcks": [ { "device_id": "CQ-GUANGHUAN-P02-PLAYER", "revision": 12, "stage": "applied", "message": "CMS输出组已显示并回报运行状态", "updated_at": "2026-10-08T02:15:31.000Z" } ],
  "control": {
    "pointEnabled": true,
    "latestRevision": 12,
    "hasItems": true,
    "appAvailable": true,
    "commands": [ { "commandId": "cmd_3f9c…", "action": "play_cms", "label": "立即播放展览内容", "contentRevision": 12, "status": "applied", "requestedBy": "staff_001", "requestedAt": "2026-10-08T02:15:00.000Z", "expiresAt": "2026-10-08T02:15:30.000Z", "deviceId": "CQ-GUANGHUAN-P02-PLAYER", "deliveredAt": "2026-10-08T02:15:05.000Z", "finishedAt": "2026-10-08T02:15:31.000Z", "message": "已播放展览内容 r12" } ]
  }
}
```

| 返回字段 | 说明 |
| --- | --- |
| `items[]` | 每台播控设备的最新运行回报（字段为数据库原名）；`admissionAllowed` 为当前是否允许新互动，`stale` 为是否已超过运行状态有效期 |
| `contentAcks[]` | 各内容版本的最新回执，按版本倒序 |
| `control.latestRevision` / `hasItems` | 后台最新保存的展示版本及是否有素材 |
| `control.appAvailable` | 是否可切换应用模式（Agent互动点位且已登记网页地址） |
| `control.commands[]` | 最近10条指令，已过截止时间仍未领取的显示为 `expired` |

#### 错误情况

| HTTP | 触发条件 | 调用方处理 |
| --- | --- | --- |
| 400 | 未指定具体门店与点位；点位不在本账号门店范围或不存在 | 核对门店与点位 |
| 401 | 未登录后台或登录已过期 | 重新登录 |
| 403 | 须先修改初始密码；没有 point:view 权限 | 修改密码；联系管理员授权 |

### 中控Pad TCP 协议（文本指令 + ndjson_v1，2026-10-10确认）

本节不是 HTTP 接口：中控（Pad 经中控网关，如哈曼视听逻辑编程软件）在门店专用局域网内直接连接播控。播控监听本机所有网卡 `0.0.0.0`，端口由设备配置 `control.listenPort` 下发（后台“门店中控Pad”登记，全店统一，默认9850）。不校验来源IP、指令不签名，因此**专用局域网内任何设备都能向播控发送指令**，该局域网须与访客Wi-Fi、办公网和公网隔离。同一端口同时接收两种格式：以 `{` 开头的按 JSON 指令处理，其他按文本指令处理。

#### 文本指令（推荐，2026-10-10 用户确认）

中控网关每个按钮只能发一个**固定字符串**，因此播控提供文本指令：发一个英文单词就执行对应动作，全部点位用同一套单词。

| 中控Pad 按钮 | 网关发送文本 | 播控执行 | 可用于 |
| --- | --- | --- | --- |
| 品牌内容播放 | `PLAY` | 播放展览内容：后台最新保存的版本（未缓存先下载校验）；断网时只播最后同步的版本 | 所有点位 |
| 互动程序 | `APP` | 打开互动应用：每块屏打开自己登记的网页，未登记网页的屏继续播自己的展览素材；断网时打不开，报错 | 登记了网页的互动点位 |
| 上一个素材 / 下一个素材 | `PREV` / `NEXT` | 所有屏各自切到自己的上一个/下一个素材，到头循环；暂停中切换后接着播 | 正在播放展览时 |
| 回到首页 / 刷新网页 | `HOME` / `RELOAD` | 重新打开登记的网页地址 / 重新加载当前页，网页重新握手后再开放互动 | 正在显示互动应用时 |
| 暂停 / 继续 | `PAUSE` / `RESUME` | 定格当前画面 / 从暂停位置继续（多屏一起） | 正在播放展览时 |
| 关闭画面（闭馆） | `EXIT` | 关闭全部播放窗口，程序与监听继续运行 | 所有点位 |
| （查询） | `STATUS` / `PING` | 回复当前模式、版本、阶段 / 回复 `OK PING` | 所有点位 |

| 项目 | 规则 |
| --- | --- |
| 格式 | UTF-8 英文单词，不区分大小写；**不需要换行**：遇到换行/回车，或一包数据发完约0.1秒内没有新数据，即为一条指令结束；一条最长64字节 |
| 执行 | 按一次执行一次（不去重）；不核对点位编号——网关发到哪台播控（哪个IP）就是哪个点位 |
| 回复 | 每条回一行：成功 `OK 单词 说明`（如 `OK PLAY 已播放展览内容 r12`），失败 `ERR 单词 原因`（如 `ERR HOME 当前没有在显示互动应用，不能回到首页`）；网关不读回复也不影响执行 |
| 当前模式不支持 | 如播放展览时发 `HOME`、互动时发 `NEXT`/`PAUSE`：回 `ERR`，不执行、不自动切换模式 |
| 未知单词 | 回 `ERR 单词 未知指令`，**不断开连接**（如旧配置里的 `SET_MODE`、音量类按钮） |
| 声音 | 音量由中控控制，播控不提供音量指令 |
| 连接 | 长连接，不因空闲断开；播控开启TCP保活（15秒起探测），掉线由系统释放连接，网关可随时重连；后台改端口时播控主动断开已有连接 |

**网关配置（以哈曼视听逻辑编程软件为例）**：每台播控电脑一个 tcp out 节点——类型“连接”、主机地址填播控电脑的局域网IP、端口填后台“门店中控Pad”的端口（默认9850）、**不勾选**“是否在成功发送每条信息后断开连接”；“通用控制”节点第一列填 Pad 发来的按钮编号（如 `custom37_1`），第二列填上表的发送文本（如 `PLAY`），第三列不填。“开馆模式”按钮可同时向多台播控发送 `PLAY` 或 `APP`。各播控的IP与可用指令见后台“点位总览 → 门店中控Pad → 指令对照表”（可导出CSV）。

#### JSON 指令（ndjson_v1，兼容保留）

| 项目 | 规则 |
| --- | --- |
| 格式 | UTF-8 JSON，一行一条指令，以LF（`\n`）结尾，每帧最多16KiB；无效UTF-8/JSON帧回复 `INVALID_FRAME` 并断开 |
| 重发 | 同一个请求号 `requestId` 原样重发不会重复执行，返回第一次的结果（带 `idempotentHit:true`）；同一请求号内容不同则拒绝（`ID_CONFLICT`）。播控进程重启时未完成的指令记为 `interrupted`，不自动重放 |
| 旧字段 | 旧版签名协议字段 `controllerId`、`keyId`、`seq`、`issuedAt`、`signature` 收到时忽略；其他未知字段拒绝（`BAD_COMMAND`） |

指令字段（2026-10-10 补充每个字段由谁提供）：

| 字段 | 必填 | 含义 | 由谁提供 / 从哪里取 |
| --- | --- | --- | --- |
| `v` | 必填 | 协议版本，固定为 `1` | 固定值，中控Pad程序写死 |
| `requestId` | 必填 | 指令流水号：这条指令的唯一编号，1—64位字母、数字、下划线、短横线。网络不好时 Pad 用**同一个编号**重发同一条指令，播控不会重复执行，只返回第一次的结果；同一编号内容不同则拒绝（`ID_CONFLICT`）；换新编号即视为一条新指令 | **中控Pad程序自己生成**，每发一条新指令生成一个新编号（如按顺序 `pad-0001`、`pad-0002`，或“时间+序号”）；后台没有、也不需要查看。重发同一条指令时沿用原编号。只能发固定字符串的网关无法生成，请改用文本指令 |
| `pointId` | 必填 | 点位编号：这条指令发给哪个点位，如 `P02`、`D01`。须与这台播控电脑绑定的点位一致，否则拒绝（`POINT_MISMATCH`），防止发错电脑 | **AgentOS 后台分配**，即后台显示的“PID”：“点位总览”每张点位卡片左上角、点位详情标题旁“PID P02 · 门店名称” |
| `command` | 必填 | 要执行的指令：`SET_MODE`、`PAUSE`、`RESUME`、`EXIT`、`GET_STATUS`、`PING`（见下表） | 中控Pad按现场操作选择 |
| `mode` | 仅 `SET_MODE` | 切换到哪种画面：`app` 互动应用 / `cms` 展览内容 | 中控Pad按现场操作选择；`app` 只对登记了互动网页地址的点位有效 |
| `contentRevision` | 仅 `SET_MODE` + `cms` | 要播放的展览内容版本号，整数≥1，须是这台播控已下载并校验过的版本；`app` 及其他指令不得携带 | **AgentOS 后台生成**：点位详情“展示与现场模式”每保存一次素材与播放设置，版本号加1，显示在点位素材下方“配置 vN”。Pad 也可先发 `GET_STATUS`，从回执的可用版本（`availableRevisions`）中选择 |

| command | 作用 | 最终回执 |
| --- | --- | --- |
| `SET_MODE` | 切换整个输出组到互动应用或指定版本的展览内容 | `applied`（带 `actualMode`、`contentRevision`）或 `failed` |
| `PAUSE` / `RESUME` | 暂停（定格当前画面）/ 从暂停位置继续；仅展览稳定显示时可用 | `applied`（带 `paused`）或 `failed` |
| `EXIT` | 退出播放，关闭全部播放窗口，程序与监听继续运行 | `applied`（带 `closed:true`）或 `failed` |
| `GET_STATUS` / `PING` | 查询实际模式、阶段、平台连接、可用版本等（不能代替观察物理屏幕） | `ok` |

示例（实际发送为单行并以LF结尾；点位与版本不能照抄到现场）：

```json
{"v":1,"requestId":"pad-0001","pointId":"实际点位ID","command":"SET_MODE","mode":"cms","contentRevision":12}
```

回执：每条有效指令先回复 `accepted`（已写入本机账本），再回复最终结果；格式或点位错误直接回复 `rejected` 与 `errorCode`。常见 `errorCode`（文本指令的 `ERR` 原因与之对应）：

| errorCode | 含义 |
| --- | --- |
| `BAD_COMMAND` / `POINT_MISMATCH` / `ID_CONFLICT` / `INVALID_FRAME` | 指令格式错误 / 点位不符 / 同一请求号内容不同 / 帧无效（回执 `rejected`） |
| `BUSY` | 输出组正在切换或校验素材 |
| `PROFILE_HOLD` | 后台新配置未能应用（不一致、需重新启动播控或凭据失效），拒绝一切切换 |
| `PAUSE_APP_DENIED` / `NOT_PLAYING_CMS` / `NOT_IN_APP` | 应用模式不能暂停 / 当前没有在播放展览内容 / 当前没有在显示互动应用 |
| `APP_DENIED` / `APP_NOT_READY` / `ADMISSION_DENIED` | 后台为普通展示应用或没有登记网页 / 互动网页未完成握手 / AgentOS未确认互动准入 |
| `PLATFORM_OFFLINE_APP` | AgentOS离线时拒绝切到互动应用（当前没有离线互动方案，待确认） |
| `OFFLINE_NO_CACHE` / `OFFLINE_REVISION_DENIED` / `MEDIA_NOT_READY` | 断网且本机从未同步 / 断网时只能播放最后同步的版本 / 指定版本文件缺失或校验不通过 |
| `PERSISTENCE_ERROR` | 本机账本写入失败，结果需运维核对，不自动重放 |
| `INTERNAL_ERROR` | 播控内部错误，查看本机日志 |

后台指令与中控指令同等对待，同一点位以最后一条为准（播控 0.3.0 起已取消“本机接管”）。联调没有真实Pad时，可在播控目录用 `node tools/pad-sim.cjs <播控IP> PLAY`（文本指令，与网关一样不带换行）或 `node tools/pad-sim.cjs <播控IP> <点位ID> cms <内容版本号>`（JSON 指令）模拟发送，仅限联调。

## 公用｜用户资料字段

以下为当前用户profile接口允许的数据域字段，保留snake_case。可空字段可返回null；JSON字段按响应结构读取，不把字段存在理解成相应生成能力已开放。

### assets

| 返回字段 |
| --- |
| `id` |
| `asset_id` |
| `work_name` |
| `tenant_id` |
| `store_id` |
| `point_id` |
| `interaction_id` |
| `agentos_uid` |
| `asset_type` |
| `asset_subtype` |
| `storage_provider` |
| `file_size` |
| `mime_type` |
| `duration_ms` |
| `width` |
| `height` |
| `lyrics` |
| `lyrics_lrc` |
| `audit_status` |
| `audit_provider` |
| `is_final` |
| `source_task_id` |
| `synced_to_mp_at` |
| `mp_work_id` |
| `lifecycle_stage` |
| `expire_at` |
| `created_at` |
| `updated_at` |

### tags

| 返回字段 |
| --- |
| `id` |
| `tenant_id` |
| `agentos_uid` |
| `tag_key` |
| `tag_value` |
| `source` |
| `confidence` |
| `evidence_type` |
| `evidence_id` |
| `store_id` |
| `point_id` |
| `expires_at` |
| `created_by` |
| `created_at` |

### interactionAnswers

| 返回字段 |
| --- |
| `id` |
| `agentos_uid` |
| `interaction_id` |
| `store_id` |
| `point_id` |
| `config_version` |
| `state` |
| `answers` |
| `created_at` |
| `updated_at` |

### profileContributions

| 返回字段 |
| --- |
| `id` |
| `agentos_uid` |
| `interaction_id` |
| `store_id` |
| `point_id` |
| `tag_key` |
| `created_at` |

### interactionDesigns

| 返回字段 |
| --- |
| `id` |
| `interaction_id` |
| `agentos_uid` |
| `store_id` |
| `point_id` |
| `revision` |
| `design` |
| `created_at` |

## 联调｜互动点位接口调试工具（2026-10-11）

AgentOS 提供网页调试工具：`https://aiva.dev.vavedigital.com/admin/tools/point-test/`（与业务接口同域名）。工具模拟互动点位客户端，覆盖本文中互动点位调用的全部接口：配置与登录、体验、文本/图片任务、语音合成、上传录音识别（2026-10-14，麦克风录音或音频文件，自动转 16kHz WAV）与流式语音识别（麦克风或音频文件）、作品读取、AI音乐、AI车衣共创。

- **按互动走流程**：左侧可选 AIVA面基、AI音乐、AI图片生成、AI车衣共创，按本文“页面操作与调用顺序”逐步调用；用户会话、体验编号、任务号、修订号、作品编号、风格对话选中的风格等从响应自动填入后续请求，可在“流程变量”中手改。
- **请求与响应**：填写时实时显示完整请求（地址、请求头、请求体、curl），请求体模板按已读取的配置生成（如每题第一个选项），可直接改 JSON 测非法参数；“原样重发上一次”用于验证同一请求号不会重复执行；任务查询可“轮询到结束”；作品图片、音频、作品小程序码、语音合成音频直接预览。常见 401/403/409/422/503 给出排查提示。
- **需要准备**：互动点位设备凭证（后台“点位详情 → 设备接入”复制）；测试来宾卡短码，或真实的 AIVA 小程序会员码内容（只能用一次，需后台已登记 AIVA 网关及 sourceApp / scanSourceApp）。2026-10-13 起不再要求该点位播控电脑开机或正在显示互动应用，播控关机时也可调试。
- **注意**：调用真实接口，会建立体验、写入作答与作品，文本/图片/语音/音乐任务会真实调用模型、产生厂商费用并冻结/扣除测试用户 Token，只用于测试环境。凭证只保存在浏览器本标签页，预览与 curl 中只显示末4位。播控接口、已停用的打印接口不在工具中。

## 联调检查｜按客户端可见结果验收

| 检查场景 | 预期结果 |
| --- | --- |
| 无已发布配置 | 409明确提示；不套用其他点位配置 |
| 配置发生变化 | 重新读取并ACK；创建请求version与当前配置一致 |
| 身份码无效 / 会话过期 | 错误可见；不能传ONEID绕过认证或自动降级匿名 |
| 用户拒绝授权 | state=abandoned，不采集后续互动输入 |
| 问卷完整 / 重复 / 改写 | 合法提交ready；相同答案再提交不会重复处理，返回同样结果；改写409 |
| P03未选曲先提交故事 | 409；先完成选曲 |
| P04无效风格/颜色 | 400；提示重选，不替换默认值 |
| 创作修订冲突 | 409；读取当前方案供用户核对 |
| 用户退出 | 明确结束本次体验并注销身份；只logout不会自动完成互动 |
| 展示素材无法加载 | error回执；不能自报applied |
| 尚未生成即上报completed | 409；确认输入不等于体验完成 |

网络请求结果未知时先查询已有体验/方案；有requestId的操作重放必须保持同一个ID和相同内容，不能换ID重发造成重复。没有说明“同一请求号重发不会重复执行”的操作，不能假设可以安全重试。当前没有客户端收费/退款接口，不能在本地计算后自行修改Token余额。

此文档只描述实际服务端契约及明确的接入缺口；线上文档可访问不代表业务API、现场客户端或模型生产链路已验收。
