# 云灵 H5：客户服务器开发指南

版本：2.1 · 2026-11-01。配套机器可读契约：[openapi.json](./openapi.json)。本文件描述**本次已经实现的适配协议**，客户可以在现有系统外增加适配层，不必重构原系统。

## 在线文档与 Agent 阅读顺序

- 平台地址：https://agents.ipboxs.com
- 交互演示：https://agents.ipboxs.com/demo/yunling
- 本指南 Markdown：https://agents.ipboxs.com/docs/yunling/customer-api.md
- 小程序开发商接入清单：[miniprogram-integration.md](./miniprogram-integration.md)
- 页面定制协议：https://agents.ipboxs.com/docs/yunling/page-config.md
- 页面预设：https://agents.ipboxs.com/docs/yunling/yunling-pages.json
- OpenAPI 3.1：https://agents.ipboxs.com/docs/yunling/openapi.json
- PDF 下载：https://agents.ipboxs.com/docs/yunling/customer-development-guide.pdf

开发 Agent 应先阅读小程序接入清单、确定接入范围，再读取本指南及 OpenAPI 中启用业务对应的路径和 schema。下述 15 条路径是**完整启用客服内业务办理时客户需要实现的接口**，不是在 woodenhorse 域名上新增同名路由。仅接入客服并跳转客户已有业务页面时，不要求实现全部 15 个接口；登录用户仍需客户后端换取客服身份。业务适配服务部署在客户自己的服务器。文档与示例均不包含真实凭证，不应把示例商品、订单、价格用于生产。

下面实施顺序及交付表针对完整业务接入。按功能分期时，双方必须同步配置页面和入口，未接通的业务不能开放为正式可办理功能。微信小程序原生页面跳转尚需平台桥接，不能仅将 HTTPS 链接替换为 `/pages/...`。

## 建议实施顺序

1. 客户项目负责人确认租户/项目 ID、测试环境、用户 ID 映射、运营文案和业务负责人；由平台方提供项目 API Key。
2. 在客户后端增加适配服务，配置独立 Bearer 凭证，并将该凭证绑定允许访问的租户与项目。查询和写入沿用客户现有数据库及服务。
3. 实现商品查询和用户登录换取 H5 令牌；先验证匿名浏览与已登录身份切换。
4. 实现预订入口、订单查询、投诉和失物接口；每个写接口同步完成事务与幂等控制。
5. 客户交付测试地址、凭证、登录入口及场景账号；平台配置测试连接，双方按本文末尾验收清单联调。
6. 客户核对价格、库存、退改、失物核验及隐私告知；验收后配置生产接口。独立演示页始终保留演示标识，不充当正式业务入口。

建议对接配置名称：`WOODENHORSE_ORIGIN`、`WOODENHORSE_TENANT_ID`、`WOODENHORSE_PROJECT_ID`、`WOODENHORSE_PROJECT_API_KEY`、`CUSTOMER_ADAPTER_BEARER`。前四项供客户登录后端调用平台；最后一项供客户接口验证平台请求。密钥通过双方约定的安全渠道交换，不写入本指南、代码仓库或前端构建产物。

## 分工与交付边界

woodenhorse 负责云灵 H5 页面、AI 对话与历史记忆、服务指南/FAQ 管理、出行需求与建议行程、表单校验、业务入口及结果展示。客户服务器是用户身份、产品价格与可售状态、订单归属、投诉处理、失物处理和领取安排的事实来源。

行程建议由 H5 根据天数、成人/儿童人数、滑雪水平、住宿需求和偏好生成。预算作为商品查询条件传给客户接口；行程不是预订确认。AI 可以调用 `show_service_panel` 展示站内入口、预填明确的出行信息，但不能提交投诉、领取物品或创建已支付订单。业务写入必须由用户点击表单按钮触发。

UI 压缩包和联调站点中的价格、销量和订单都是演示数据，正式模式不会使用这些值兜底。产品暂无图片时展示无商品照片的占位插画。客户应提供可公开展示的商品图片与正式文案。

## 客户需要交付的内容

| 完整业务接入交付 | 用途 |
|---|---|
| 测试与生产 API 基础地址、服务器间 Bearer 凭证 | 每个项目独立配置；例如 `https://api.customer.com/woodenhorse` |
| 下述 15 个业务接口 | 商品、预订入口、订单、投诉、失物、选项、现场状态、商家和人工客服 |
| 客户登录页和登录后接入逻辑 | 将已登录客户身份绑定至 woodenhorse，不接受前端自行声明身份 |
| 测试账号与场景数据 | 有订单/无订单、儿童票、下架商品、已处理投诉、找到/未找到物品、领取资格不足 |
| 正式运营文案与图片 | 核对营业时间、票种、儿童/缆车规则、退改规则、交通、宠物政策和人工客服地址 |
| 人工客服系统适配和已核实电话 | 接入、查询、发消息接口及救援联系电话；没有号码时不提供拨号 |

## 身份接入

1. 用户在客户平台完成登录。客户服务器从自己的登录会话取真实 `userId`。当前允许 1-128 位英文字母、数字、下划线或短横线，区分大小写；如原用户 ID 不符合，客户需维护稳定且唯一的映射，不直接使用姓名或手机号。
2. **客户服务器**调用 woodenhorse `POST /api/v1/tokens`，使用该 woodenhorse 项目的 API Key：

```http
Authorization: Bearer <woodenhorse-project-api-key>
Content-Type: application/json
```
```json
{"tenantId":"<租户 ID>","projectId":"<项目 ID>","userId":"<客户系统稳定用户 ID>"}
```

返回 `token` 和 `expiresAt`；现有签发有效期为 15 分钟。不要把项目 API Key 放在浏览器、小程序或 App 包内。

3. 打开 H5：`https://<woodenhorse>/agent/<projectId>?tenant=<tenantId>&user=<URL 编码 userId>&view=home#token=<URL 编码 token>`。签名令牌放在 fragment，bootstrap 成功后 H5 会将其从地址栏移除。会话使用当前 woodenhorse 的项目级 HttpOnly cookie，最长 24 小时。
4. 用户私有业务（订单、预订、投诉、失物、人工客服会话）仅允许已验证身份。匿名用户仍可浏览指南、聊天和查公开商品。仅把 `userId` 放到 URL 里不能获得个人业务权限。
5. 客户登录地址应在完成登录后重新签发令牌、回到对应 H5。账号切换时必须带新令牌进入；不要复用上一账号的登录链接。令牌签发本身不允许任意公开用户 ID 换取身份。

客户后端接入示例（JavaScript，放在已有受登录保护的控制器中）：

```js
// sessionUserId 必须取自已校验的客户登录会话。
async function createCustomerChatURL(sessionUserId, config) {
  if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionUserId)) {
    throw new Error("Invalid customer user ID mapping");
  }
  const response = await fetch(`${config.origin}/api/v1/tokens`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${config.projectAPIKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      tenantId: config.tenantId,
      projectId: config.projectId,
      userId: sessionUserId
    }),
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) throw new Error("Chat identity unavailable");
  const { token } = await response.json();
  if (typeof token !== "string" || !token) throw new Error("Invalid token");
  const url = new URL(`/agent/${config.projectId}`, config.origin);
  url.searchParams.set("tenant", config.tenantId);
  url.searchParams.set("user", sessionUserId);
  url.searchParams.set("view", "home");
  url.hash = `token=${encodeURIComponent(token)}`;
  return url.toString();
}
```

客户登录路由可在取得地址后返回 302 跳转或返回给当前已登录客户端；该响应设置 `Cache-Control: no-store`。禁止把生成的地址写入分析日志、公共缓存或其他用户的会话；签发失败时显示重试提示，不回退为其他用户或伪造成功。

## 通用调用规范

所有业务接口均为 **POST + JSON**。woodenhorse 的 Go 后端发起请求，浏览器不会直接请求客户 API，也不会得到客户接口凭证。

| 请求头 | 内容 |
|---|---|
| `Authorization` | `Bearer <客户接口凭证>`，与 woodenhorse 项目 API Key 是两套不同凭证 |
| `Content-Type` / `Accept` | `application/json` |
| `X-Tenant-ID` | woodenhorse 的租户 ID |
| `X-Project-ID` | woodenhorse 的项目 ID |
| `X-User-ID` | 已验证用户的客户系统 ID，按 `application/x-www-form-urlencoded` 规则编码；客户解码一次。公开商品查询可能不带此头 |
| `X-Request-ID` | 每次调用的追踪 UUID，可用于双方排障 |
| `Idempotency-Key` | 写操作必传；同一次提交及其重试保持相同值 |

客户必须校验 Bearer 凭证对应的租户/项目和用户权限；不能仅凭 `orderId`、登记编号、手机号获取或修改他人记录。身份来自受信任服务器请求头，不来自请求 JSON。

- 基础地址必须是公网 HTTPS，443 端口；不允许用户名密码、查询参数和 fragment。当前实现阻止内网、回环地址、DNS 指向私网及 HTTP 重定向。私有网络对接需另行部署受控网关，不应关闭这些校验。
- 总调用时限 12 秒，建议普通查询/受理接口 3 秒内返回；长处理任务应先返回登记编号，再通过查询接口更新。
- 单响应不超过 128 KB；商品、订单每次最多 100 条。当前订单下拉需要返回该用户可售后订单列表（最多 100 条），超出时客户应按可办理范围筛选；本版未实现分页。
- 时间戳用 RFC 3339（带时区），出行日期用 `YYYY-MM-DD`（雪场当地日期）；金额用整数分，当前币种 `CNY`。
- 所有面向用户的字符串是纯文本，禁止塞入 HTML。商品图片与跳转地址必须是完整 HTTPS URL。
- 返回成功状态 2xx 和 JSON；未知响应字段会被丢弃，必需字段缺失/无效会被判定为服务异常。

## 1. 查询可售商品

`POST /v1/products/search`，允许匿名。客户根据日期、人数、预算、住宿、水平与偏好筛选或排序商品，并确认年龄/身高规则在商品说明与最终确认页可见。

```json
{
  "date":"2026-12-12","days":2,"adults":2,"children":1,
  "budget":"500–1,000 元","lodging":"需要住宿",
  "level":"初次滑雪","preference":"亲子轻松"
}
```

`days` 1–7，`adults` 1–20，`children` 0–20。预算、住宿、水平、偏好为字符串，可为空；H5 提供的选择值见 OpenAPI。不能仅凭儿童人数判断儿童优惠资格，客户在预订确认页补充核验年龄/身高。

```json
{"products":[{
  "id":"sku-family-day","category":"tickets","name":"家庭滑雪票 · 2 成人 1 儿童",
  "description":"示例说明，正式返回应写明包含雪具、使用时长、适用儿童条件及退改限制",
  "priceCents":103600,"currency":"CNY","imageURL":"https://cdn.customer.com/family.webp",
  "available":true,"priceLabel":"/ 套，2 成人 1 儿童","sold":684
}]}
```

上述金额仅为契约示例。`priceLabel` 要明确按人/套/晚，是否为起价，避免总价误解。`sold`、`category` 和 `eligibility` 为可选字段，其余示例字段必需，`imageURL` 可为空。无结果返回 `{"products":[]}`。正式模式接口失败时显示错误，不回退到演示商品。

商品 `category` 可取 tickets / stay / offers / camp / lesson / pass。行程查询可能同时返回雪票和住滑套餐，每个商品应带实际分类，平台按已发布页面配置显示分类标题；省略时兼容显示“行程推荐商品”，不按数组顺序或名称猜测。非法分类会被拒绝。预订会将该分类与商品 ID 一起传给 checkout，客户仍须核验两者一致。无需新增接口路径。

新版云顶行程页在用户确认日期、人数、预算与住宿前保留占位提示，不直接查询商品。生成的是可修改的行程建议；点击“查看行程推荐商品”后才请求本接口。失败可重试，离开页面后迟到的响应不会覆盖新的行程。旧页面配置未启用确认选项时保持原表单行为。

## 2. 创建预订入口

`POST /v1/checkout`，要求验证身份和 `Idempotency-Key`。

```json
{"productId":"sku-family-day","date":"2026-12-12","adults":2,"children":1}
```
```json
{"url":"https://customer.com/checkout/session-123","expiresAt":"2026-12-10T10:15:00+08:00"}
```

此接口准备客户平台订单确认/结算入口，**不代表扣款或预订完成**。客户页面负责重新核价、库存、年龄/身高、数量、具体套餐日期、实名信息、退改条款和支付。分类商品与行程推荐都进入同一个预订承接页，由用户再次点击前往；收到响应和点击时均校验 HTTPS 及有效期，链接过期时要求重新预订。离开列表后迟到的响应不会自动导航，刷新承接页不会恢复私有预订地址。不要在链接中包含长期凭证或直接信任用户可编辑的金额。入口必须绑定当前用户及提交的商品/日期/人数。

## 3. 查询当前用户的可售后订单

`POST /v1/orders/search`，要求验证身份。请求 `{}` 或 `{"status":"all"}`，待支付页面传 `{"status":"pending"}`。客户只返回当前用户符合状态的订单，按创建时间倒序。可同时传 `createdFrom` 与 `createdBefore`（RFC 3339 带时区，最长 366 天），查询创建时间 `>= createdFrom` 且 `< createdBefore` 的订单；不能用出游日期 `date` 代替创建时间。两个字段必须同时存在，不传则查询全部时间。

在 id/title/status 之外，可返回 category、amountCents（整数分）、quantity、date、createdAt、description、sold、imageURL、detailURL、payURL 和 purchaseURL。`sold` 是商品真实累计销量（0–100000000），不能拿当前订单的 quantity 充当；未提供时不显示“已售”。`purchaseURL` 是再次购买该商品的客户确认页，多订单卡片用“立即购买 + 更多订单”并排展示；缺少购买入口时保留详情入口。打开 URL 不得自动创建订单或扣款，确认页须重新核价和核验资格。pending 为待支付；付款链接只返回给当前用户仍可支付的订单。URL 为空时不展示对应跳转，服务端不拼接猜测链接。

```json
{"orders":[{"id":"order-123","title":"云顶太子公寓住宿加滑雪套餐","status":"已完成"}]}
```

“本周”按周一零点至下一周一零点计算。平台在生成回复或首次进入配置为本周查询的订单页时，根据已发布内容的可选 `timeZone`（IANA 名称，默认 `Asia/Shanghai`）计算并保存绝对范围，重开历史回复仍查询原范围。独立订单页会在当前页面运行时保存此范围，重试及导航返回继续查询相同区间；跨周后文案改为“所选时段”。客户无需解析自然语言或自行推测时区。范围请求示例：`{"status":"all","createdFrom":"2026-10-26T00:00:00+08:00","createdBefore":"2026-11-02T00:00:00+08:00"}`。客户必须执行范围过滤；Mock 也按 createdAt 过滤。

平台 H5 的内部 `POST /api/public/service` 可传 `input.orderPeriod: "this_week"`，禁止与绝对区间混用。平台解析后删除此字段，客户 `/v1/orders/search` 不需要新增参数；平台返回的 `query: {period, createdFrom?, createdBefore?}` 由平台生成，客户无需返回且不能覆盖它。旧客户响应 `{orders: [...]}` 保持兼容。

没有订单返回空数组，不得返回其他用户的订单。`id` 必须是稳定业务主键，不能把产品名称当订单 ID。

## 4–5. 投诉/售后受理与进度

`POST /v1/complaints`，要求验证身份和幂等键。

```json
{"orderId":"order-123","description":"请核实订单包含的装备项目，与页面说明不一致。"}
```

`description` 1–500 字。客户再次核对订单归属及能否受理，然后返回 Receipt（结构见下）。

`POST /v1/complaints/lookup`：`{"reference":"CMP-123"}`，要求验证身份，返回相同 Receipt 的最新状态。处理结果、退款金额及承诺时间由客户提供，woodenhorse 不推断。退款/改期页面本次是规则说明与售后入口，没有直接退款/取消订单按钮，也不要求新增退款写接口。

## 6–8. 失物登记、查询、领取申请

`POST /v1/lost-items`，要求验证身份和幂等键。

```json
{"itemName":"蓝色滑雪手套","lostAt":"2026-12-12T14:30:00+08:00","location":"雪具大厅入口","contact":"13800000000"}
```

物品名称 1–80 字、地点 1–120 字、联系方式 3–80 字；遗失时间不能晚于当前时间。联系方式是客户业务处理数据，请按客户隐私政策接收与保管。

`POST /v1/lost-items/lookup`，要求验证身份：
```json
{"reference":"LOST-123","contact":"13800000000"}
```

`POST /v1/lost-items/claim`，要求验证身份和幂等键：
```json
{"reference":"LOST-123","characteristics":"右手手套，拇指处有白色标记","contact":"13800000000"}
```

`characteristics` 1–500 字。客户必须核对登记记录归属、物品匹配与领取资格。此操作为**申请安排领取**；只有客户已核验确认时才返回具体 `pickup` 信息。不能因为按钮叫“确认领取安排”就直接把物品标为已领取。真正交付物品仍遵循客户现场核验流程。

## Receipt：投诉与失物的统一回执

```json
{
  "id":"LOST-123",
  "status":"待人工核验",
  "message":"已收到领取申请，请等待客服核验。",
  "createdAt":"2026-12-12T15:00:00+08:00"
}
```

`id` 1–100 字，`status` 1–80 字（面向用户的状态名称），`message` 1–2,000 字，`createdAt` 为原始受理时间。建议状态：待受理、处理中、已处理、待认领、待人工核验、待领取、已领取、已关闭。状态转换由客户系统控制。

核验完成后可以增加：
```json
{"pickup":{"location":"雪具大厅服务台","time":"2026-12-13 09:00–17:00","requirements":"携带登记编号和能证明物品归属的材料"}}
```

仅有登记成功时不要返回虚构领取安排。`demo` 是平台演示标记，正式客户响应即使带此字段也不会被采信。

## 幂等、重试与错误

六个写接口：checkout、complaints、lost-items、lost-items/claim、support/sessions、support/messages。客户按 `(凭证对应项目, X-User-ID, 接口路径, Idempotency-Key)` 去重；同键同参数返回同一业务结果，同键不同参数返回 409。并发请求也必须只创建一次。建议保留幂等记录至少 30 天，并与业务记录生命周期协调。

woodenhorse 在数据库中绑定提交编号与参数摘要、串行化并发提交、缓存成功回执。网络超时或响应无效时保留编号；H5 当前标签页跨刷新也保留待重试编号及 SHA-256 参数摘要，不保存明文表单。服务器崩溃、代理中断或用户关闭页面时，客户幂等仍是避免重复写入的必要条件。相同用户/项目之外的请求不共享回执。失败不会在前端伪造成功。

| HTTP 状态 | 客户应表达的含义 | H5 行为 |
|---|---|---|
| 200/201 | 查询或受理成功 | 展示返回数据/回执 |
| 404 | 无匹配记录，或当前用户无权访问 | 提示核对编号与联系方式，不暴露记录存在性 |
| 409 | 状态冲突/幂等参数冲突 | 提示重新查询后办理 |
| 422 | 商品不适用、订单不能受理、校验未通过 | 提示核对商品/订单/表单 |
| 429 | 过于频繁 | 提示稍后重试 |
| 5xx / 超时 | 客户服务不可用或结果未确认 | 保留填写内容，允许原编号重试 |

建议错误体为 `{"error":{"code":"ITEM_NOT_FOUND","message":"...","requestId":"..."}}`，客户端当前展示平台固定友好错误文案，不将客户原始错误体、堆栈或内部信息直接显示给用户。客户 API 自身 401/403 通常表示服务凭证或授权配置错误，平台按服务异常处理；匿名用户在平台侧调用私有业务会先收到 401 并引导客户登录。

## 9. 查询商品选项

`POST /v1/catalog/options`，公开查询。请求 `{"category":"stay","hotelId":"grand"}`，hotelId 可省略。category 为 tickets / stay / offers / camp / lesson / pass。

```json
{"dates":["2026-12-12","2026-12-13"],"hotels":[{"id":"grand","label":"云顶大酒店"}],"rooms":[{"id":"double","label":"双人房"}],"equipment":[{"id":"with","label":"含雪具"}]}
```

所有数组都必须返回，无选项用空数组。dates 最多 366 项，其余数组各最多 100 项，选项 ID 在同组内唯一。房型应根据酒店返回，不可售日期不应出现在选项中。H5 选择日期、酒店、房型与雪具后，会把 category、endDate、hotelId、roomId、equipmentId 传给商品查询和 checkout。endDate 不早于 date，最多相差 30 天。客户必须重新核验组合、价格和库存，不能直接使用客户端金额。

## 10. 查询雪道与缆车状态

`POST /v1/resort/status`，公开查询，请求 `{}`。

```json
{"updatedAt":"2026-12-12T09:00:00+08:00","items":[{"id":"lift-1","name":"1号缆车","kind":"lift","status":"open","opensAt":"08:00","operatingHours":"08:00–16:30","description":"运行信息由雪场提供","detailURL":"https://customer.com/lifts/1"}]}
```

kind 为 trail / lift；status 为 open / closed / scheduled / departed（开放 / 未开放 / 待开放 / 已发车）；departed 仅适用于 lift，雪道不能返回已发车。此状态由客户系统提供，平台不会仅按当前时间猜测；opensAt 为当地 HH:mm 或空字符串。可选 operatingHours 为最多 80 字的展示时段（例如 08:00–16:30），不替代用于排序的 opensAt；旧接口省略该字段时仍显示开始时间。detailURL 可以为空。最多 200 项。更新时间必须真实，临时停运及时更新。接口请求体仍为 `{}`，不接受浏览器自行传入的身份或坐标。现场首页支持以下可选响应字段：

- `summary`：最多 200 字的设施汇总，例如“高速缆车6条 · 拖牵5条 · 魔毯3条”，由雪场提供，不从部分列表推算。
- `nearestLiftId`：必须对应 items 中的缆车 ID；只有客户后端持有当前已验证用户授权、仍有效的位置时才可返回。
- `items[].nextDeparture`：仅 lift 可提供 `{ "time":"12:00", "state":"on-time" }`。time 为 HH:mm，state 为 on-time / scheduled / delayed / cancelled，分别显示准时发车 / 计划发车 / 发车延迟 / 班次取消，不把 opensAt 当作下一班次。

items 中 ID 必须唯一。省略附近信息时，页面显示“缆车信息”，省略 nextDeparture 时显示 operatingHours 或 opensAt。点击详情展开 description，有 HTTPS detailURL 时可查看完整信息。

## 11. 查询园区商家

`POST /v1/merchants/search`，公开查询。请求 `{"category":"food"}`，分类支持 all / food / coffee / snacks / shopping / family。

```json
{"items":[{"id":"food-1","name":"餐厅名称","category":"food","description":"营业与服务说明","imageURL":"https://cdn.customer.com/food.webp","address":"雪场服务中心二层","navigationURL":"https://customer.com/map/food-1"}]}
```

最多 100 项，ID 必须唯一，空列表表示该分类暂无商家。可选顶层 `nearestId` 必须指向本响应 items 中的商家；可选 `items[].distanceMeters` 为 0–1000000 的整数米数。无位置时省略，不能以 0 或固定示例值代替未知。现场首页单独查询 category=food，不沿用商家目录上一次选择的分类。 分类数量使用当前响应 items 的实际长度；此版本没有分页或 total 字段，客户应返回该分类完整的可展示列表，不把原稿中的示意数量写死。imageURL 与 navigationURL 可以为空。缺图或加载失败时显示占位，未配置导航地址的卡片不提供跳转。有效导航地址使整张商家卡片可点击，并支持键盘。导航链接由客户配置，H5 通过既有宿主 openURL 能力打开；未安装宿主能力时在当前页跳转 HTTPS 地址。微信小程序原生页面映射尚需平台桥接，详见小程序接入清单。

Mock 使用 ZIP 中可完整辨认的 10 个商家示例和原稿照片，不能作为当前营业名录。点击卡片进入 `https://agents.ipboxs.com/examples/yunding/index.html?view=merchant&merchantId=demo-jinhua&source=woodenhorse`；参数调试面板展示入口参数及商家查询响应。该页面不执行真实地图导航。接入生产只需将商家响应的 `navigationURL` 改为客户已实现的 HTTPS 地图或详情页；参数不包含登录凭证，目标页面自行验证登录。

### 位置上下文与跨域接入

上述附近信息是可选能力，不增加新的平台业务路径。客户小程序 / App 自行向用户申请位置权限，并通过自己的鉴权后端保存本次有效位置。Widget 通过既有签名身份接入，平台转发的 X-User-ID 仅在已验证身份时存在；客户后端按 X-Tenant-ID、X-Project-ID、X-User-ID 匹配位置、校验授权与时效，再计算最近项和距离。匿名请求、拒绝授权、位置过期或无法匹配用户时必须省略 nearestLiftId / nearestId / distanceMeters，仍可返回公开列表。不要使用账号旧位置或统一默认位置冒充实时距离。

本版本 H5 不自动采集位置，也没有浏览器坐标上传接口。客户若需要 H5 内直接定位，需另行实现用户授权、位置提交与失效管理，不能把坐标放进跳转 URL 或通用 HTML 扩展消息。浏览器仍请求平台同源 /api/public/service，由平台连接器服务端访问客户服务器；客户无需向浏览器开放业务 API 的跨域凭证访问。导航继续走宿主 openURL，HTML 扩展协议及允许来源见 runtime-architecture.md。

演示数据中的“最近”、300 米、12:00 准时发车及设施总数仅用于重现 ZIP 的展示状态，不是实时位置或运营数据。客户开发时应使用上述真实计算结果替换，并保持商家分类过滤后 nearestId 仍包含在返回列表内。

## 12. 人工客服与救援信息

`POST /v1/support/info`，公开查询，请求 `{}`。

```json
{"phone":"0313-0000000","hours":"09:00–24:00","rescuePhone":"0313-0000001","rescueInstructions":"请说明雪道名称、明显地标、伤者情况与联系电话。"}
```

示例号码不可用于生产。phone/rescuePhone 仅允许数字、空格、连字符及开头的加号，也可为空；其他字段必需，可为空。页面拨号前显示确认提示，空号码不提供拨号按钮。客户必须提供已核实的客服与救援号码、实际值班时间。

## 13–15. 人工客服会话与消息

三个接口都要求已验证身份。会话和订单归属必须同时校验租户、项目及 X-User-ID。客户可适配现有客服系统，不要求自建坐席产品。

| 路径 | 请求与行为 |
|---|---|
| `POST /v1/support/sessions` | `{}`，幂等写入；创建或恢复当前用户的客服会话，返回 waiting / connected / closed 状态 |
| `POST /v1/support/sessions/lookup` | `{"sessionId":"support-1"}`；查询最新状态和最近消息，H5 可见时每 10 秒轮询 |
| `POST /v1/support/messages` | `{"sessionId":"support-1","text":"需要帮助","orderId":"order-123"}`；幂等写入，text/orderId 至少一个 |

三者返回同一结构：

```json
{"id":"support-1","status":"connected","agentName":"工号1001","messages":[{"id":"message-1","role":"user","text":"需要帮助","createdAt":"2026-12-12T09:00:00+08:00","orderId":"order-123"}]}
```

messages 最多返回最近 200 条，按时间升序；消息 ID 稳定且不重复，role 为 user / agent / system。text 最多 2000 字符，orderId 可省略。排队时返回 waiting，不伪造坐席已接入；closed 会话停止轮询，重新接入需调用 start。发送订单前客户服务器必须校验该订单确属该用户。相同幂等键不能重复投递消息或重复创建客服会话。

人工对话与 AI 对话分开。平台语音转写结果可填入人工输入框，但发送目标仍是客服会话接口。人工消息成功响应会作为幂等回执存入 woodenhorse 的 service_requests，可能包含对话正文和订单编号；双方需要明确访问权限、保留和删除策略，不可宣称该表只有摘要。H5 未发送草稿仅在当前页面内存中保留。

### 客服会话前端行为

- 进入人工客服页自动调用一次 `support.start`，失败后用户可重试。`waiting` 禁止发送；`connected` 开放文字和最近订单发送；`closed` 停止轮询并禁用发送。救援页只查询公开联系方式，不创建人工会话。
- 页面可见时每 10 秒查询最新会话，前一次查询未完成或正在发送时不再轮询。返回完整且按会话顺序排列的 `messages`；旧查询响应不能覆盖发送后的新结果。
- “发送最近的订单”先查询当前用户的订单，再提交第一笔订单 ID，因此订单接口必须按创建时间倒序返回。查询和发送共用防重复锁，但这不替代客户服务器的归属及幂等校验。
- 发送失败保留草稿；退出客服页后，未完成的订单查询不再触发消息发送。已经提交到服务器的请求可能仍会成功，不能将切页视为撤销。再次接入时，客户应恢复该用户的有效会话及历史消息。
- `agentName` 作为客服标识显示在状态卡和消息内，例如“工号1001”；没有该字段内容时不虚构工号。电话及救援说明来自 `support.info`。拨号弹窗确认后交给系统电话，开发联调不要拨打真实号码。

## 客户适配层开发约定

每个请求按以下顺序处理：校验服务凭证及租户/项目授权；读取并解码用户 ID；验证 JSON schema；检查订单或登记记录归属；在数据库事务内执行幂等检查和业务处理；返回本文定义的 JSON。查询接口也必须执行归属检查。

写接口建议建立幂等表，唯一键为项目、用户、接口路径和幂等键，保存规范化参数摘要、处理状态、业务记录 ID 及响应。使用数据库唯一约束或行锁处理并发，业务记录与成功回执尽可能在同一事务提交；涉及外部系统时使用其幂等能力及结果查询恢复，不能仅靠进程内存或先查后插判断。不要把一次临时网络故障永久缓存成业务成功。

checkout 请求不携带 `days`、预算或住宿偏好，但可携带 category、endDate、hotelId、roomId、equipmentId；商品 ID 必须能明确对应套餐，客户结算页补齐必要的住宿日期、实名信息及规格。若原系统不能通过商品 ID 确定这些信息，应先在客户确认页补选，不能自行推断并扣款。

接口返回的 `status`、`message` 和 `pickup` 会显示给用户，应由客服业务流程产生。客户自行负责失物联系方式和回执数据的访问权限、保留及删除策略。请求日志仅记录追踪 ID、路由、耗时、状态和脱敏业务编号，不记录 Bearer、完整令牌、手机号或投诉全文。

## 交付与验收记录

| 客户交付项 | 完成标准 |
|---|---|
| 接口实现 | 15 条 POST 路径均可访问，字段与 OpenAPI 一致 |
| 身份接入 | 登录后可进入本人 H5；退出、切换账号、过期凭证均有明确处理 |
| 商品与结算 | 真实价格、库存、套餐规则、过期链接及支付确认由客户系统负责 |
| 投诉流程 | 本人订单受理、无订单提示、编号查询和最终状态可闭环 |
| 失物流程 | 登记、查询、归属核验、领取申请和人工确认状态可闭环 |
| 重试与隔离 | 并发重复提交只生成一条记录；跨用户/跨项目查询不泄露数据 |
| 测试资料 | 测试账号、测试订单与登记编号、预期结果；凭证另行交换 |
| 生产切换 | 生产地址、值班联系人、变更窗口及回退方案经双方确认 |

新增验收场景：酒店切换清空旧房型、无可售日期、缆车临时关闭、商家分类为空、客服排队/接入/关闭、文字与订单分别发送、轮询与发送并发、跨用户客服会话访问。

建议每个场景记录：环境、时间、X-Request-ID、脱敏用户编号、操作、预期与实际结果。平台已完成自身页面与适配层测试；客户业务正确性、登录回跳和真实支付页仍需双方验收。

## 发布与联调验收

1. 在“智能体项目 → 编辑智能体 → 界面与模板”选择云灵模板、保存草稿。
2. 在“云灵服务内容与业务接口”核对品牌、9 个指南页、FAQ 与人工客服入口，保存草稿、预览、发布内容。布局与内容分别发布；内容当前保留草稿/已发布两份，外观版本恢复不会回滚服务内容。
3. 先选演示模式验收页面。独立 `/demo/yunling` 完全不调用客户接口，刷新清空其临时回执；项目演示模式的回执由 woodenhorse 按当前用户持久化。
4. 配置测试 API 基础地址、凭证与登录地址，切换正式模式，使用客户验证账号完成端到端联调。
5. 必测：正确/错误账号、跨用户订单与登记编号、过期身份、空商品、售罄、价格变动、过期 checkout、订单列表为空、字段超长、重复点击、响应丢失重试、超时、409、领取未核验、真实领取时间地点、跨项目访问。
6. 更换生产地址与凭证后发布。生产前必须确认真实商品与运营文案；本次仓库实现不等于已接通客户系统。

## 后续嵌入小程序或 App

当前交付 H5，可由 WebView 加载。网页 widget.js 依赖 DOM，不能直接作为微信小程序原生组件使用。小程序采用“原生悬浮图标 → 客服承载页 → web-view”接入，完整清单与示例见 [miniprogram-integration.md](./miniprogram-integration.md)。

对于具备注入 JavaScript 能力的 App 宿主，现有 H5 预留以下扩展点：

```ts
window.WoodenhorseHost = {
  openURL(url: string) { /* 宿主将 HTTPS 业务地址交给自身导航层 */ },
  close() { /* 关闭客服 WebView */ }
};
```

这个对象不是已交付的微信 SDK。当前代码没有接入 wx.miniProgram 导航，不能要求客户在原生小程序中直接赋值远端网页的 window；该扩展点也不代表所有业务卡片、支付链接已经接通原生导航。未安装时，业务地址使用 H5 当前页跳转，关闭按钮返回客服首页。平台需统一导航出口并补齐微信桥接，客户提供页面路由及业务域名配置。当前没有使用不受限的 `postMessage('*')` 信任通道，也没有直接使用客户原生支付能力。页面布局通过平台已有外观草稿/发布接口中的 pages 配置；具体协议见 [page-config.md](./page-config.md)。客户无需为 H5 另建页面 HTML 接口。

语音转文字由 woodenhorse 平台统一提供，通过服务端调用 AgentLLM 的 FunASR。云灵 v2 用户切换到语音模式后，按住说话录音，松开转写，上滑取消；首次需授权麦克风，最长 60 秒，完成录音后提交转写；结果先放入输入框，由用户检查后发送。当前为“录完转写”，不提供边说边出字。客户服务器不需要开发语音识别接口，也不需要持有 AgentLLM 密钥。

H5 录音浮层显示聆听/取消状态，暂时停用背景导航；上移后移回按住区域可继续录音。键盘可按住空格或 Enter，松开转写，Escape 取消；焦点或指针捕获丢失时取消。等待授权时提前松开也会取消，迟到的麦克风授权会立即释放。识别中可点停止，已取消请求的迟到结果不会填入草稿。这些交互由平台组件提供，客户只配置素材和入口，不需要重新实现录音状态机。

### 平台语音接口（供 H5 / 后续宿主接入）

- 请求：`POST /api/public/audio/transcriptions?projectId=<项目 UUID>&conversationId=<当前会话 ID>`。
- 身份：先完成现有 bootstrap，使用该项目的 HttpOnly 会话 Cookie；请求 Origin 必须匹配平台域名。服务端核验当前会话归属和项目启用状态，不能以请求中的 tenantId/userId 冒充用户。
- 请求头：`Content-Type: audio/pcm; rate=16000; channels=1; format=s16le`。
- 请求体：原始 PCM 二进制，16kHz、单声道、16 位小端；不带 WAV 头。时长 0.25 至 60 秒，最多 1,920,000 字节。H5 内置录音和重采样，不接受 MP3/WebM 直接上传。
- 成功：`{"text":"识别文本","durationMs":2300,"requestId":"UUID"}`。客户端必须让用户确认发送，不能自动执行业务操作。
- 错误：400 音频无效；401 会话过期；403 来源不符；404 会话不属于用户；413 音频超限；415 音频格式不符；422 未识别到内容；429 限流/额度不足；502 上游失败；503 平台未开启；504 转写超时。错误正文为 `{"error":"可显示的提示"}`。
- bootstrap 的 `voice.enabled` 表示平台是否配置语音，`voice.maxSeconds` 表示单次最长录音时间。
- H5 需要 HTTPS 和麦克风权限。目前使用浏览器录音能力，尚未交付微信 JSSDK 或小程序原生录音适配；不能以浏览器录音成功代替微信真机验收。原生上传也不能直接绕过上述 Cookie 和 Origin 校验，若增加原生采集通道，平台必须提供相应鉴权与转写适配。客户无需开发 ASR，也不得把平台密钥放入客户端。

### 平台运维配置（客户无需提供）

- `ASR_ENABLED=true`：开启平台语音；设为 false 关闭。未配置有效密钥时不启用。
- `ASR_WS_URL=wss://agentllm.linkyun.co/v1beta/dashscope/asr/ws`。
- `ASR_MODEL=fun-asr-realtime`。
- `ASR_API_KEY`：可单独设置；留空时复用平台 `AGENTLLM_API_KEY`，仅限服务端。
- `ASR_TENANT_DAILY_SECONDS=3600`：每租户每天可提交的音频秒数，按 UTC 日期重置。已提交上游的失败/取消请求也计入，避免反复失败绕过额度。
- 每用户每分钟最多 8 次，每租户每分钟最多 60 次（按 API 实例计数）；跨实例同时处理中每用户最多 1 次、每租户最多 8 次；日额度由数据库统一核算。
- 平台 `speech_usage` 仅记录租户、项目、用户、模型、时长和处理状态，不保存原始录音和识别文本。音频在完成录音后经平台发往 AgentLLM 转写；识别文本仅在用户主动发送消息后进入聊天历史。上游日志和保留策略由平台运营方另行管理。


## 结构化回复与补充业务字段（2.1）

平台的 `show_service_reply` 只选择回复类型和用户明确提供的条件；订单、价格、库存、儿童适用条件、入园凭证和电话仍从客户适配接口获取。AI 生成的 HTML、支付地址或二维码不作为业务事实。客户无需额外实现 AI 卡片接口。

现有 15 个接口增加以下可选字段，旧响应保持兼容：

| 位置 | 可选字段 | 使用规则 |
|---|---|---|
| 商品查询及预订请求 | `childrenDetails: [{age?, heightCm?}]` | 数量必须等于 `children`；年龄为 0–17 整数，身高为 30–220 厘米整数。未知条件可省略，不推断儿童票资格 |
| 商品响应 | `eligibility: {adult, child, conditions}` | 客户提供成人/儿童适用条件及规则说明，三项分别最长 300/300/500 字符；缺失时界面提示待核实 |
| 订单响应 | `description` | 最长 1000 字符的订单项目说明 |
| 订单响应 | `admission: {imageURL, expiresAt, caption}` | HTTPS 凭证图片、RFC3339 到期时间、最长 120 字符说明；必须属于当前 `X-User-ID` 的有效订单。前端到期即隐藏并提供刷新，不生成虚假二维码 |

凭证图片应使用短期、不可猜测的签名地址；不要提供公共永久二维码。平台不把图片地址交给模型。商品和预订接口须复核儿童条件；仅有用户自填的年龄身高，不代表已通过票务核验。

## 网站悬浮 widget 的语音交互

```html
<script src="https://agents.ipboxs.com/widget.js"
  data-tenant-id="TENANT_ID" data-project-uuid="PROJECT_ID"
  data-user-id="CUSTOMER_USER_ID" data-token="SHORT_LIVED_TOKEN"
  data-launcher="icon" data-launcher-caption="智能助手"
  data-launcher-motion="yunling-launcher-20261031"
  data-view="home" data-chrome="native" data-voice="true"></script>
```

点击打开客服；长按录音；上移取消；释放后显示处理中并调用平台 FunASR；处理中可取消。识别完成进入聊天，将文字填入草稿，用户检查后发送。授权拒绝、录音过短、网络错误均可重试。网页需要 HTTPS 和麦克风权限；宿主设置 Permissions-Policy 时应允许本站麦克风。

跨域客户网站使用客户登录后端换取的 15 分钟身份 token。widget 自动调用平台 `POST /api/public/widget/audio/transcriptions?tenantId=…&projectId=…&userId=…`，Authorization 为 `Bearer <token>`，提交 `audio/pcm; rate=16000; channels=1; format=s16le`。该平台接口只识别语音，不需要客户实现，且不接收第三方 Cookie 身份。过期后客户应重新换取 token 并重新挂载 widget。项目 API Key 和 FunASR Key 始终留在服务器。

同域演示站可用匿名浏览会话录音；跨域未登录访客点击进入平台 H5 后仍可使用语音。原生微信小程序不运行网页 script，需要沿用小程序接入指南的承载页及录音适配，不能把网页录音验证当作微信真机验收。

## 记忆授权（平台能力）

`GET /api/public/memory?projectId=…` 读取当前项目聊天会话的记忆设置。`PATCH/DELETE /api/public/memory` 将 `projectId` 放在 JSON 请求体中。云灵 v2 首次默认未开启偏好记忆；用户主动授权后才参与后续记忆提取。PATCH 携带当前 `revision` 和 `enabled` / `memory`，版本冲突返回 409，重新读取后处理。DELETE 携带 `revision`，清空并关闭记忆；正在处理的旧请求不能在撤销后写回。客户不需要另建记忆接口。

平台 H5 在已有聊天会话下同源调用上述接口；客户网页不直接跨域读写记忆。返回值为 `{enabled: boolean, memory: string, revision: 非负整数}`。读取失败时禁用修改；409 或写入响应丢失时保留编辑草稿，重新 GET 核对最新状态后，由用户明确确认再次提交，不能自动使用旧 revision 重试。关闭授权保留已有内容；删除清空并关闭。演示模式仅使用当前标签页内按项目隔离的模拟设置。
