# 找视频记录展示设计

## 1. 目标与范围

为 `find_agent` 增加只读的运行记录工作台，主要展示以下三张表：

1. `video_discovery_run`：一次找视频任务的输入、意图、状态和汇总计数。
2. `video_discovery_search`：任务内每个关键词、每一页的搜索轨迹。
3. `video_discovery_candidate`：搜索结果、画像证据、评分、决策分池及 AIGC 分发状态。

本期只提供查询和审计，不修改运行状态、候选分池或 AIGC 计划。

## 2. 信息架构

三张表采用“运行 → 搜索轨迹 / 候选视频”的主从结构，不做三张彼此割裂的宽表。

```text
找视频记录
├── 运行列表（video_discovery_run）
│   ├── 业务日、状态、需求词 / Run ID 筛选
│   └── 运行状态、搜索数、候选数
└── 运行详情
    ├── 输入、意图、停止原因和分池汇总
    ├── 搜索轨迹（video_discovery_search）
    └── 候选视频（video_discovery_candidate）
```

登录用户在左侧选择一次运行，右侧按需加载对应的搜索或候选记录。该结构同时保留任务上下文和逐条证据，适合日常巡检与问题排查。

## 3. 页面设计

### 3.1 运行列表

- 筛选：业务日、运行状态、需求词、种子标题、Run ID。
- 数据范围：固定只展示 `biz_dt >= 20260730` 的运行及其搜索、候选记录。
- 排序：创建时间倒序，同时间按主键倒序。
- 摘要：需求词、状态、业务日、搜索页数、候选数。
- 分页：后端分页，每页 20 条。

### 3.2 运行概览

- 基本身份：`run_id`、`biz_dt`、`demand_grade_id`、种子视频。
- Agent 解释：`intent_summary`。
- 运行结果：搜索页、全部候选、主推荐、淘汰、待评估。
- 默认展开上下文：`relevant_points_json` 和 `stop_reason`，用户仍可手动收起。
- `relevant_points_json` 不直接输出 JSON，而是展示需求摘要，并按参考视频分组展示灵感点、
  目的点、关键点及其说明；同时兼容包含 `reference_videos` 的对象格式和历史点位数组格式。

计数由关联表实时聚合，避免只依赖运行表中的缓存计数而掩盖数据不一致。

### 3.3 搜索轨迹

默认展示：

- 搜索记录 ID 和成功/失败状态；
- 关键词、形成原因；
- 来源类型、来源值、父搜索；
- 供应方、页码、游标；
- 结果数、新增候选数、是否有下一页；
- 创建时间。

展开后优先以卡片展示该搜索记录直接关联的候选视频，包括标题、作者、分池、播放量、
点赞、评论、收藏、转发和价值评分；同时展示搜索键、完整检索参数、供应方分页状态和
错误信息。标题、作者和互动数据被截断时，鼠标悬浮展示完整内容。

### 3.4 候选视频

默认展示：

- 候选 ID、决策分池；
- 标题、作者、视频 ID；
- 播放、点赞、评论、收藏、分享；
- `R / E / S / V` 评分；
- AIGC 计划标签和爬取计划；
- 创建时间。

展开后只展示决策原因、标签和原视频入口，不展示年龄证据、归一化结果、来源搜索或
AIGC 计划明细。

候选支持按分池以及视频 ID、标题、作者筛选。
候选列表中的标题、作者和互动数据同样提供完整悬浮提示。

页面正文、表格、筛选控件和状态标签使用不小于 11px 的字号，主要操作与正文使用
12px～14px，避免审计信息过小影响阅读。

## 4. 接口设计

| 接口 | 用途 |
|---|---|
| `GET /api/video-discovery/runs` | 分页查询运行记录与实时聚合计数 |
| `GET /api/video-discovery/runs/{run_id}` | 查询单次运行概览 |
| `GET /api/video-discovery/runs/{run_id}/searches` | 分页查询搜索轨迹 |
| `GET /api/video-discovery/runs/{run_id}/candidates` | 分页查询候选视频 |

所有接口均为登录用户可访问的只读接口。列表最大单页 100 条，页面默认 20 条；不存在的 `run_id` 返回 404。

## 5. 异常与兼容

- 空表、空筛选结果、加载失败分别展示明确状态。
- 历史候选的 `search_id` 允许为空，页面标记为“历史记录未关联”。
- JSON 字段解析成功后以结构化数据返回；历史脏数据无法解析时保留原始文本，保证审计信息不丢失。
- 未知的状态、来源类型和决策分池直接展示原值，避免新增枚举后页面空白。
- 宽表只在记录区域内横向滚动，不造成整个页面横向溢出。
