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

本文档仅面向 `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` 判定稳定。