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

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

| 功能 | 数据来源与行为 |
| --- | --- |
| 消费者、商家登录与退出 | `/openapi/v1/auth`，身份和店铺权限来自服务端 |
| 平台登录与退出 | `/openapi/v1/platform/auth`，独立平台账户和会话 |
| 商品分类、列表及详情 | `/openapi/v1/stores/{store_id}/catalog` 和 `/products/{product_id}`，公开展示启用店铺商品 |
| 订单与商品资料 | 真实订单投影及商品目录，保留来源版本和同步时间 |
| 换货方案、客户确认、修订、取消与主管审批 | 真实售后接口，提交当前版本和幂等标识 |
| 工单及售后历史 | `/openapi/v1/tickets`，按店铺、本人或当前会话客户查询持久工单 |
| 会话、消息、客服接管与释放 | 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`，平台只读取运行和管理元数据 |
| 交易支付、营销、地址、收藏、团队统计等范围外栏目 | 按已确认设计展示业务范围说明 |

真实登录令牌保存在浏览器内存，刷新后重新登录。客户、商家与平台分别管理会话、业务上下文和草稿；退出或更换身份时清理对应入口的数据。旧会话的迟到响应不会清除新登录会话。写操作保持幂等标识；网络结果未知时保留相同请求标识，版本冲突后重新读取状态。公共请求超时20秒，不自动重试；HTTP 429 按服务端 Retry-After 提示等待秒数。

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

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

进入咨询页面时，通过 `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`、方案和工单版本及状态；页面读取最新工单，更新当前售后卡片。刷新或重新进入时查询当前活动运行，恢复同一等待状态。停止本次回复和人工协助入口保持可用，方案确认及主管审批继续由各自已有业务页面和服务端权限检查处理。