# 前端数据来源与接入范围

页面遵循已确认的线稿与视觉规范。业务数据通过真实 API 读取，服务端使用 MySQL、Redis 和现有业务组件保存与处理。请求失败时显示错误并保留可重试的输入。

| 功能 | 数据来源与行为 |
| --- | --- |
| 消费者、商家登录与退出 | `/openapi/v1/auth`，身份和店铺权限来自服务端 |
| 平台登录与退出 | `/openapi/v1/platform/auth`，独立平台账户和会话 |
| 商品分类、列表及详情 | `/openapi/v1/stores/{store_id}/catalog` 和 `/products/{product_id}`，公开展示启用店铺商品 |
| 订单与商品资料 | 真实订单投影及商品目录，保留来源版本和同步时间 |
| 换货方案、客户确认、修订、取消与主管审批 | 真实售后接口，提交当前版本和幂等标识 |
| 工单及售后历史 | `/openapi/v1/tickets`，按店铺、本人或当前会话客户查询持久工单 |
| 换货服务评价 | 工单详情中的 `/openapi/v1/tickets/{ticket_id}/feedback`，本人评价已完成工单，授权员工读取结果；后端按课程讲义完成后提供此接口 |
| 客服回访记录 | `/openapi/v1/tickets/{ticket_id}` 的 `followup` 字段，客户通过已有 AI 咨询登记，客户与授权员工在原工单只读查看；后端与 Agent 按课程讲义补充此能力 |
| 会话、消息、客服接管与释放 | H5 使用真实 SSE 接口，按持久事件序号续传，失败后保留输入并提供重新连接 |
| 助手等待补充资料 | 查询原运行的 waiting，通过 `/agent/runs/{id}/inputs` 提交当前 interrupt_id、run_version 及本人补充内容 |
| 人工协助 | 会话 `/human-assistance`，持久保存请求并通知授权员工 |
| 规则读取与草稿 | 当前规则和草稿从服务端读取，草稿版本及发布版本分别检查 |
| 知识草稿、发布与撤回 | 真实知识接口，发布使用本地向量服务与 Milvus |
| Agent 配置发布 | `/admin/v1/stores/{store_id}/agent-releases`，保存配置及发布版本；所有会话每次新建助手任务时使用当前发布版本，进行中和等待中的任务保留原配置 |
| 店铺、员工与渠道配置 | 商家管理接口，按专用权限和并发版本处理 |
| 员工通知 | `/admin/v1/notifications`，按真实业务事件产生，接收人、权限和已读状态由后端管理 |
| 渠道身份关联 | 本人发起短期验证请求，受信任渠道完成身份验证，本人确认后保存关联 |
| 沟通习惯 | 本人授权、读取、修改和清空接口，使用服务端 revision |
| 模型费用 | 真实费用账户和双人审批接口，金额由元换算为微元 |
| 平台商家、资源配额、投递、运行概览与审计 | `/openapi/v1/platform`，平台只读取运行和管理元数据 |
| 交易支付、营销、地址、收藏、团队统计等范围外栏目 | 按已确认设计展示业务范围说明 |

三个入口的登录令牌、到期时间和展示用账户名称分别保存在当前标签页的 `sessionStorage`。刷新时，消费者与商家调用 `GET /openapi/v1/auth/me`，平台调用 `GET /openapi/v1/platform/auth/me`，携带对应 Bearer token 重新读取身份和权限。验证完成后显示原有授权页面；本地记录不提供权限依据，密码和业务数据不写入存储。

恢复身份期间展示加载提示，业务页面等待验证结果。网络失败、请求超时或服务端暂时不可用时保留凭据，点击“重新验证登录”重新查询，不自动连续重试。登录接口返回的 `expires_in` 用于记录原到期时间，身份查询不会延长会话有效期。到期、401 或主动退出清除对应入口凭据，其他入口的会话保持独立。客户、商家与平台的业务上下文和草稿只保存在内存；退出或更换身份时清理对应入口的数据。旧会话的迟到响应不会清除新登录会话。

写操作保持幂等标识；网络结果未知时保留相同请求标识，版本冲突后重新读取状态。公共请求超时 20 秒，不自动重试；HTTP 429 按服务端 Retry-After 提示等待秒数。

商品图片作为项目静态资源保存，来源和初始化信息见 `scripts/prepare_storefront_data.py` 及商品数据说明。开发账户和初始化数据属于独立开发商家，凭据只保存在被忽略的 `.work` 目录。

## 换货服务评价

消费者在现有售后进度页评价本人 `COMPLETED` 工单。客服、主管和商家管理员在原有工单详情读取评价。评分不高于 2 分或问题未解决时，授权员工通过已有通知详情进入该工单。前端已经接入以下接口；当前主项目的评价后端代码由课程开发补充，接口尚未提供时显示读取失败和人工重试入口。

`GET /openapi/v1/tickets/{ticket_id}/feedback` 使用当前入口的 Bearer 会话。未评价时返回 `200` 和 `{"feedback":null}`；已经评价时返回 `{"feedback":{"feedback_id":"UUID","ticket_id":"UUID","score":2,"resolved":false,"comment":"换货后问题仍然存在","created_at":"2026-09-29T08:00:00Z"}}`。工单详情同时提供相同 `feedback` 字段。员工读取需具备当前店铺的 `tickets:read` 权限，客户只读取本人记录。此接口查询单个工单，无分页。

`POST /openapi/v1/tickets/{ticket_id}/feedback` 仅接受工单本人客户，要求 Bearer 会话、当前店铺的 `tickets:read` 权限与 `Idempotency-Key`。请求示例：

```json
{
  "expected_version": 5,
  "score": 2,
  "resolved": false,
  "comment": "换货后问题仍然存在"
}
```

- `expected_version` 使用最新工单的 `version`。
- `score` 为 1 至 5 的整数，`resolved` 为布尔值。
- `comment` 可为空，去除首尾空白后最多 500 个字符。
- 首次成功和同键同参重试均返回 `201` 和同一 `feedback` 对象。一个工单只保存一次评价，客户确认窗口提交后展示已保存结果；工单状态与版本保持不变。
- 网络中断、请求超时或服务端异常时保留原请求正文与 `Idempotency-Key`，暂时禁用输入。客户选择“重试原评价”并确认后，继续发送相同内容。公共请求超时 20 秒，无自动重试。
- `409 VERSION_CONFLICT`、`INVALID_STATE`、`FEEDBACK_EXISTS`、`IDEMPOTENCY_CONFLICT` 后重新读取工单和评价。读取成功且仍可评价时，客户重新检查并确认，使用新的提交标识。
- `401` 按公共登录逻辑处理，同一身份重新登录后读取最新工单再确认；`403 FORBIDDEN` 和 `404 RESOURCE_NOT_FOUND` 停止提交并保留读取入口；`422 INVALID_INPUT` 允许修改输入；`429` 按公共请求提示等待时间。明确的请求拒绝清除本次提交标识，失败不会显示提交成功。
- 草稿只保存在当前浏览器内存中，按工单区分；退出或更换客户身份时清理。员工页面仅能读取，无法代客户评价。

## 客服回访记录

`TicketFeedback` 在工单存在 `followup` 时显示“客服回访”区域，包含“已登记”、回访原因、期望联系时段、登记时间。客户与员工均只读，长文字使用现有 `ExpandableText`。`followup` 为 `null` 时不显示回访区域。

读取复用 `GET /openapi/v1/tickets/{ticket_id}` 和现有 `ticket(id)` 方法，使用当前入口的 Bearer 会话。客户仅能读取本人工单，员工需要当前店铺的 `tickets:read` 权限。HTTP 200 的工单对象增加以下字段：

```json
{
  "followup": {
    "followup_id": "cb24ab6d-c44f-4c04-939c-614265f0c8f9",
    "ticket_id": "c1882132-c2c7-4ca4-b7b6-9779e5a110d7",
    "reason": "换货后仍然无法正常使用",
    "contact_window": "工作日晚上",
    "status": "REQUESTED",
    "created_at": "2026-09-29T09:00:00Z"
  }
}
```

每次点击“读取最新评价”，组件依次读取工单详情和评价，更新父页面工单中的版本、评价与回访信息。两个请求成功前保持评价提交禁用。刷新不改变尚未确认结果的评价正文与 `Idempotency-Key`；服务端已经保存评价时清除待重试内容。回访读取没有额外分页，沿用公共请求 20 秒超时和人工重试；401 进入登录，403 或 404 停止提交并显示错误。

客户通过现有 AI 咨询发送“工单 xxx 换货后仍有问题，请客服在工作日晚上联系我”。消息仍调用现有会话消息接口。Agent 缺少工单、问题或联系时段时，通过现有 `clarification` 等待及聊天输入补充资料。服务端 `create_followup_request` 工具保存回访请求后，员工通知沿用 `page="ticket"` 和 `target_id=ticket_id` 进入原工单。前端从工单响应展示记录，不新增回访 HTTP 方法或输入表单。

## H5 消息连接与补充输入

原会话的每次新建 `AgentRun` 都读取店铺当前已发布配置；发布后客户在原聊天中发起新请求即可使用新能力。补充资料、客户确认和主管审批继续恢复原运行，使用该运行已保存的发布快照。

进入咨询页面时，通过 `GET /openapi/v1/conversations/{id}/messages?after={sequence}&limit=100` 按页恢复消息，并查询会话及当前活动运行。之后使用 `GET /openapi/v1/conversations/{id}/events`，携带内存中的 `Authorization: Bearer` 和 `Last-Event-ID`。SSE 使用 `eventsource-parser` 处理分段和心跳，JSON 事件中的 `sequence`、`type`、`control_version` 分别对应事件序号、类型和会话控制版本。

- 服务端约50秒结束一条连接，页面自动携带最后成功处理的序号继续连接。15秒心跳保持连接，客户端65秒总期限结束失效连接。
- 相同序号只处理一次；接管后到达的旧控制版本助手及运行事件不更新页面。退出登录、切换页面或卸载页面时，立即取消当前请求。
- 网络失败显示已确认的连接中断提示，保留输入并禁用发送；用户选择重新连接后恢复读取，已受理消息不自动重发。
- HTTP 429 按 `Retry-After` 禁用重连按钮。HTTP 401 或 `access.revoked` 中的 `UNAUTHENTICATED` 结束当前登录，403及404停止显示会话内容。
- HTTP 410 `EVENT_CURSOR_EXPIRED` 或连接中的 `stream.expired` 事件触发一次历史和当前状态查询，再从已经读取的序号继续订阅；连续失败显示错误并停止自动恢复。

原运行返回 `WAITING_USER` 且 `waiting.expected_input_type` 为 `clarification` 时，原有“补充问题”和“发送”控件用于回答助手问题。页面提交 `POST /openapi/v1/agent/runs/{run_id}/inputs`，身份要求为该运行本人，必须携带 `Idempotency-Key`，请求示例如下：

```json
{
  "interrupt_id": "a632ef6c-e80a-4cbd-91b4-cb1ba7421b12",
  "expected_run_version": 2,
  "answer": "需要处理刚才选择的订单，键盘空格键无法使用。"
}
```

成功响应为202，包含 `input_event_id` 和原运行的 `run`，随后通过 `message.user`、`run.resumed` 继续读取状态；`run.waiting` 再次进入等待输入。补充内容不执行客户确认或主管审批。网络结果未知时保留相同幂等标识和输入；版本冲突、等待记录失效或权限变化由接口拒绝，页面保留输入和重新读取入口，禁止自动重放。

`after-sales-v3` 创建方案后返回 `WAITING_USER` 和 `expected_input_type=proposal_confirmation`。H5显示确认提示及已有“查看当前方案与进度”入口，读取该 `proposal_id` 的最新工单并进入方案页。客户检查字段、勾选确认后，通过已有方案确认接口提交 `proposal_version` 和 `expected_ticket_version`。普通聊天发送按钮在业务等待期间禁用，输入草稿继续保留。

确认接口保存审批任务后，工作进程处理持久业务事件，使原运行进入 `WAITING_APPROVAL` 和 `expected_input_type=approval_decision`。H5通过 `run.waiting` 中的 `status` 及等待类型显示主管审核提示。主管提交决定后，`run.resumed` 带回相同 `run_id`、`status=QUEUED`、方案和工单版本及状态；页面读取最新工单，更新当前售后卡片。刷新或重新进入时查询当前活动运行，恢复同一等待状态。停止本次回复和人工协助入口保持可用，方案确认及主管审批继续由各自已有业务页面和服务端权限检查处理。