FinClaw V1 Sub-Packet: Refresh Diff View
状态：Pending 日期：2026-05-16 Lane：Engineering / Frontend Owner：Frontend Agent D（web/） + Engineering Agent A（agent/ + api/）协作 Parent Packet：v1-engineering-implementation-task-packet.md 对齐 Action Item：AL-5
1. 目标
把 v1-ui-ux-interaction-design.md §6A Refresh Diff View 落地为可运行的 UI + 后端 diff builder，覆盖：
- Desktop 三列布局（previous / current / change annotation）；
- Mobile 时间线卡片；
- 5 类 change sections（new facts / changed inferences / risk changes / evidence changes / watch question updates）；
- 「无实质变化」显式说明。
2. 允许读取
见 frontmatter must_read / reference_only。
3. 禁止范围
- 不在 Refresh Diff 中暴露内部 prompt / agent trace / model chain；
- 不让 Refresh 覆盖历史 snapshot（必须遵守 v1-product-object-and-schema-design.md §13 API constraint，新增不覆写）；
- 不在 Diff 中显示 buy / sell / 订单 CTA；
- 不把刷新触发条件（refresh_conditions）与执行触发器混淆。
4. Acceptance Criteria
| AC ID | 验收项 |
|---|---|
| AC-1 | RefreshDiffView 组件渲染所有 5 类 change sections |
| AC-2 | Desktop 三列布局在 ≥ 1280px viewport 工作；Mobile 时间线在 ≤ 768px viewport 工作 |
| AC-3 | 「无实质变化」case 显示明确文案 + 原因（来源未更新 / 无新事件 / 原判断维持），不生成新的相似文本 |
| AC-4 | 后端 refresh_diff_builder 输出符合 v1-product-object-and-schema-design.md §4.3 Refresh Change Record schema |
| AC-5 | API 新增 GET /v1/threads/<id>/refresh-diff/<refresh_id> 返回结构化 diff |
| AC-6 | Evaluation case snapshot-to-watch-questions.yaml 的 thread refresh 路径在 UI 端能被复现验证 |
| AC-7 | 单测：6 个 change-type fixture（new fact only / inference change only / risk change only / evidence change only / watch question only / no-change）全部通过 |
| AC-8 | 与 sub-5 协作：Diff 视图入口可从 Save Thread Sheet 之后的 Thread 主视图进入 |
5. 回写位置
- 代码 → 工程仓库
fin-claw； - v1-governance-engineering-alignment.md §5 / §9.AL-5 状态由
missing→aligned-initial； - Hand-off anchor →
handoff-anchors/v1-eng-impl-sub-4-refresh-diff-view.yaml； - 解除依赖：trial sub-2（trial 任务 2 Thread refresh 观察依赖此视图）。
6. 风险与裁决项
- 风险 R-1：Refresh 没有变化时 LLM 倾向生成「相似文本」→ 必须在 prompt 中明确「无变化时返回 sentinel」；
- 风险 R-2：Diff 渲染性能在 cognition_changes 数 ≥ 50 时退化 → V1 阶段建议分页加载（≤ 10 / page）；
- 裁决项 J-1：「实质变化」阈值（多少字段变化算「实质」）由 trial 第 1 周 spot-check 后调整；建议默认 ≥ 1 个 main_thesis / counter_thesis / invalidator 字段变化。
7. 与其他 Sub-Packet 的关系
- 并行无冲突：sub-5（共用 Thread 视图入口但不同组件）；
- 解除：trial sub-2；
- 共享文件需协调：
server/api/thread_routes.py（与其他 sub-packet 协调；本 sub-packet 只新增 endpoint）。