llm-intelligence/docs/plans/2026-05-13-daily-report-v1-implementation-plan.md

# Daily Report V1 Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 将当前“数据库导出式日报”改造成移动端优先、变化驱动、可快速决策的 V1 日报页面，并同步补齐 Dashboard 摘要入口。

**Architecture:** 保留现有数据库和采集链路不动，把改造集中在 `scripts/generate_daily_report.go` 的报告语义层与 HTML 模板层。先把“结论、行动建议、头条、免费来源标签、场景推荐”抽成可测试的构建函数，再重写 HTML 模板和前端摘要视图，最后用真实日报生成、Go 测试、前端构建联合验收。

**Tech Stack:** Go 1.22、html/template、PostgreSQL、React、TypeScript、CSS

---

### Task 1: 为日报 V1 语义层补测试

**Files:**
- Modify: `scripts/generate_daily_report_test.go`
- Test: `scripts/generate_daily_report_test.go`

**Step 1: 写失败测试**

补 3 组测试：
- 免费来源标签分组测试：验证 `official_free`、`aggregator_free`、`unknown_free`
- V1 首页摘要测试：验证会输出一句话结论、行动建议、头条、附录快捷入口
- 平静日状态测试：验证当事件不足时，首页出现“观察重点 + 稳定推荐”文案

**Step 2: 运行失败测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerate|TestBuild'`

Expected:
- 新增测试失败
- 失败原因是缺少语义层函数或 HTML 中不存在新版文案

**Step 3: 最小实现语义函数**

在 `scripts/generate_daily_report.go` 中新增：
- 免费来源分类辅助类型
- 首页摘要结构
- 头条 / 建议 / 推荐构建函数

**Step 4: 重新运行测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerate|TestBuild'`

Expected:
- 新增测试通过

**Step 5: Commit**

```bash
git add scripts/generate_daily_report.go scripts/generate_daily_report_test.go
git commit -m "feat(report): add v1 report summary builders"
```

### Task 2: 重构日报数据结构以支撑 V1 页面

**Files:**
- Modify: `scripts/generate_daily_report.go`
- Test: `scripts/generate_daily_report_test.go`

**Step 1: 写失败测试**

为以下内容补断言：
- 免费模型按来源可信度分组显示
- 推荐卡存在证据短句
- 头条卡存在变化基线或“首次出现”标签

**Step 2: 运行失败测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateHTMLV3|TestBuild'`

Expected:
- HTML 内容不包含新版结构字段

**Step 3: 最小实现**

在 `ReportV3` 上新增 V1 所需衍生字段，例如：
- `HeroSummary`
- `ActionItems`
- `HeadlineItems`
- `SceneSections`
- `FreeBreakdown`
- `AppendixLinks`
- `PageMode`

并在 `generateReportDataV3` 末尾统一填充。

**Step 4: 重新运行测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateHTMLV3|TestBuild'`

Expected:
- 数据结构相关测试通过

**Step 5: Commit**

```bash
git add scripts/generate_daily_report.go scripts/generate_daily_report_test.go
git commit -m "feat(report): enrich daily report v1 view model"
```

### Task 3: 重写 HTML 模板为移动端优先 V1 首页

**Files:**
- Modify: `scripts/generate_daily_report.go`
- Test: `scripts/generate_daily_report_test.go`

**Step 1: 写失败测试**

断言 HTML 包含以下结构关键词：
- `今日一句话结论`
- `三条行动建议`
- `今日头条`
- `场景推荐`
- `完整数据附录`
- 免费来源标签：`官方免费`、`聚合免费`、`待确认`

**Step 2: 运行失败测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateHTMLV3Includes'`

Expected:
- 失败，说明旧模板仍是统计卡 + 表格

**Step 3: 最小实现**

重写 `generateHTMLV3`：
- 使用移动端优先布局
- 加入结论卡、行动建议卡、头条卡、场景推荐、附录入口
- 保留必要的完整表格，但下沉到附录区
- 按设计文档落地颜色、字号、标签、平静日/热点日状态

**Step 4: 重新运行测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateHTMLV3Includes'`

Expected:
- 模板结构测试通过

**Step 5: Commit**

```bash
git add scripts/generate_daily_report.go scripts/generate_daily_report_test.go
git commit -m "feat(report): redesign html daily report for v1"
```

### Task 4: 调整 Markdown 让结构与新版日报一致

**Files:**
- Modify: `scripts/generate_daily_report.go`
- Test: `scripts/generate_daily_report_test.go`

**Step 1: 写失败测试**

补充 Markdown 断言：
- 顶部出现“今日结论”“今日行动建议”“今日变化”
- 免费区出现来源分类摘要

**Step 2: 运行失败测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateMarkdownV3'`

Expected:
- 旧 Markdown 不包含新版结构

**Step 3: 最小实现**

改写 `generateMarkdownV3` 的章节顺序，至少与 HTML 保持：
- 结论
- 行动建议
- 变化摘要
- 场景推荐
- 附录

**Step 4: 重新运行测试**

Run: `go test -tags llm_script ./scripts -run 'TestGenerateMarkdownV3'`

Expected:
- Markdown 测试通过

**Step 5: Commit**

```bash
git add scripts/generate_daily_report.go scripts/generate_daily_report_test.go
git commit -m "feat(report): align markdown report with v1 structure"
```

### Task 5: 补 Dashboard 摘要卡以对齐新版日报

**Files:**
- Modify: `frontend/src/pages/Dashboard.tsx`
- Modify: `frontend/src/App.css`

**Step 1: 写失败测试或构建前检查**

由于当前前端未配置页面测试，先以类型检查和构建作为验收门槛，并在实现前明确 UI 目标：
- Dashboard 出现一句话摘要
- 显示报告日期、状态、HTML / Markdown 入口
- 展示“固定路径回退”提示
- 视觉上更接近新版日报入口卡

**Step 2: 最小实现**

在 `Dashboard.tsx` 中：
- 扩展 `LatestReport` 展示字段
- 生成更强的信息层级摘要
- 调整布局让入口更接近移动端日报卡片语义

在 `App.css` 中：
- 为日报入口补新版卡片层级
- 优化移动端字号和按钮布局

**Step 3: 运行构建**

Run: `cd frontend && npm run build`

Expected:
- 构建通过

**Step 4: Commit**

```bash
git add frontend/src/pages/Dashboard.tsx frontend/src/App.css
git commit -m "feat(frontend): align dashboard report card with v1 report"
```

### Task 6: 真实生成和联调验证

**Files:**
- Modify: `reports/daily/*`（生成产物）
- Verify: `scripts/generate_daily_report.go`
- Verify: `scripts/verify_phase3.sh`

**Step 1: 运行脚本测试**

Run: `go test -tags llm_script ./scripts`

Expected:
- 脚本相关测试通过

**Step 2: 运行后端测试**

Run: `go test ./...`

Expected:
- 全部通过

**Step 3: 运行前端构建**

Run: `cd frontend && npm run build`

Expected:
- 构建通过

**Step 4: 真实生成日报**

Run: `go run -tags llm_script ./scripts/generate_daily_report.go`

Expected:
- 生成新版 md/html
- 主产物与归档产物都更新

**Step 5: 门禁验证**

Run: `bash scripts/verify_phase3.sh`

Expected:
- `PHASE_RESULT: PASS`

**Step 6: Commit**

```bash
git add scripts/generate_daily_report.go scripts/generate_daily_report_test.go frontend/src/pages/Dashboard.tsx frontend/src/App.css reports/daily
git commit -m "feat(report): ship daily report v1 experience"
```

### Task 7: 推送到仓库

**Files:**
- Verify: working tree

**Step 1: 检查状态**

Run: `git status --short`

Expected:
- 只剩可接受的既有脏文件或已知产物

**Step 2: 推送**

Run: `git push`

Expected:
- 推送成功