client_framework/docs/history_page_requirements_and_implementation.md

生成历史记录需求与实现方案（框架对齐）

本文档仅面向 My History（生成历史记录）模块的产品需求、数据展示规则、接口对接与交互实现说明，供客户端与 client_proxy_framework 对齐开发。

---

1. 页面目标与范围

My History 用于展示用户已创建任务的结果与状态，支持查看、下载、删除、继续追踪进度。

---

2. My History 需求定义

2.1 展示数据字段（卡片）

每个历史卡片展示以下信息：

• 封面图（见 2.2 封面取值规则）
• 创建日期：由 MyTaskItem.createTime 格式化为 MMM d, yyyy
• 24 小时剩余时间：createTime + 24h - now
  • 剩余时间大于 0：展示 xh xxm left
  • 小于等于 0：展示 Expired
• 操作区：
  • 支持按客户端配置决定是否在卡片上展示 Download 入口（非必选）
  • 不展示下载入口时，操作区可仅展示状态文案（由任务状态映射）
  • 若客户端采用“详情页下载”方案，则卡片点击进入详情页后再提供下载能力
• 删除按钮：可触发删除确认弹窗

顶部需展示“有效期提醒”提示（文案可换皮配置，不要求固定英文）：

• 语义必须包含两点：
  1. 任务内容仅保留 24 小时（或 1 天）；
  2. 过期前需要下载保存。
• 各换皮应用可按品牌语气自定义标题与正文，但不得改变上述核心含义。
• 示例语义（非固定文案）：
  • 标题：24-hour expiry / Available for 24 hours
  • 正文：Each item is kept for 24 hours after creation. Download before it expires.

2.2 封面取值规则（重点）

封面来源按以下优先级：

1. 优先使用 resultUrl（网络封面）

• resultUrl 是 http/https 且为图片地址：直接展示网络图。

2. 若 resultUrl 判定为视频地址（如 .mp4/.m3u8/.webm/.mov）：

• 优先使用本地封面 localCoverPath（由 ImageTaskHistory.localCoverPathsForMyTaskItems(tasks) 提供）。
• 若本地封面不存在，展示视频占位图（摄像机 icon）。

3. 若 resultUrl 不可用：

• 回退使用 localCoverPath。

4. 仍无可用封面：

• 展示默认背景色占位块。

2.3 接口对接

历史列表接口：

• ImageApi.getMyTasks
• 对应后端：GET /v1/image/my-tasks
• 当前请求参数：
  • app: currentBackendAppType()
  • page: '1'
  • pageSize: '30'

删除任务接口：

• ImageApi.deleteTask
• 入参：taskId（int）
• 成功后前端需从列表移除对应卡片并清理本地封面映射缓存。

任务进度接口（点击生成中任务后轮询）：

• ImageApi.getProgress
• 对应后端：GET /v1/image/progress

2.4 点击行为与跳转

卡片点击按任务状态分流：

1. 有远端结果地址 跳转任务结果详情页（携带 taskId、resultUrl）。
2. 任务生成中 跳转任务进度页，建议每 5 秒轮询一次进度接口，成功后自动进入结果详情页。
3. 状态显示完成但媒体地址未就绪 提示：Media is not ready yet. Pull to refresh.
4. 其余不可进入状态 根据状态映射给出阻塞提示文案。

辅助交互（支持按客户端策略配置）：

• Download 点击（若卡片启用该入口）：下载 resultUrl 到系统相册（图片/视频分流保存）。
• 详情页下载（若卡片不提供下载入口）：进入结果详情页后再执行下载。
• Delete 点击：先弹窗二次确认，再调用删除接口，成功后移除条目并提示 Deleted。

---

3. My History 分页加载方案（建议落地）

建议客户端按统一分页模式实现 My History，支持首屏加载、下拉刷新与滚动加载更多。

3.1 增加分页状态

建议维护以下分页状态（命名由各客户端自行定义）：

• pageSize（建议 30）
• lastLoadedPage
• hasMore
• loadingMore
• listGeneration（用于刷新隔离）

3.2 请求策略

1. 首屏/下拉刷新：请求第 1 页，覆盖列表。
2. 滚动到底触发：请求 nextPage = lastLoadedPage + 1，并追加数据。
3. hasMore 判定：优先使用后端分页字段（若有），否则按返回条数兜底。
4. 封面映射增量更新：对新增任务批次补齐本地封面映射并合并到当前缓存。

3.3 去重与一致性

• 追加分页时按 taskId 去重，避免刷新/重试导致重复卡片。
• 删除任务后同步从列表数据与封面缓存中移除。
• 当用户从进度页返回后，可触发轻量刷新（仅首屏页）保障状态最新。

---

4. 异常与边界处理

• 登录未完成：展示 loading；登录失败展示错误态。
• 接口失败：展示错误文案 + Retry。
• 空数据：My History 显示 No tasks yet.
• 非法 taskId：删除时拦截并提示 Invalid task id。
• 下载失败：展示 Save failed 或系统权限错误。

---

5. 验收清单（建议）

1. My History 封面优先级符合 2.2（图片、视频、本地回退、占位）。
2. 卡片点击分流准确（结果页/进度页/提示）。
3. 删除成功后 UI 与本地封面缓存同步移除。
4. My History 分页补齐后，快滑场景无重复、无错序，且 hasMore 判定稳定。