docs: update dashboard plan - defer visual design decisions

docs/superpowers/plans/2026-04-16-dashboard-frontend-rebuild.md

@@ -2,13 +2,13 @@
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
-**Goal:** 在保留像素风视觉风格的基础上，重做 dashboard 前端：砍掉废数据、加图表、拆分文件、新增伏笔追踪和系统状态页。
+**Goal:** 重做 dashboard 前端：砍掉废数据、加数据可视化、拆分文件、新增伏笔追踪和系统状态页。
 
-**Architecture:** React 19 + Vite，新增 Recharts 图表库和 react-router-dom 路由。保留现有 CSS 变量和像素风设计系统。后端补 3 个聚合 API。
+**Architecture:** React 19 + Vite，新增图表库和路由。后端补聚合 API。
 
-**Tech Stack:** React 19, Vite, Recharts, react-router-dom v7, react-force-graph-2d (替换 3d)
+**Tech Stack:** React 19, Vite, react-router-dom v7, 图表库待定, 关系图库待定
 
-**Design:** `dashboard/frontend/design.md`
+**Design:** 视觉风格和具体图表形式待确认，见 `dashboard/frontend/design.md`（待更新）
 
 ---
 
@@ -19,20 +19,21 @@
 ```
 src/
 ├── main.jsx                    # 入口，挂载 Router
-├── App.jsx                     # Layout shell（侧边栏 + Router Outlet）
+├── App.jsx                     # Layout shell（侧边栏 + Router Outlet + SSE）
 ├── api.js                      # API 请求（保留，补新端点）
-├── index.css                   # 全局样式（保留，补图表样式）
+├── index.css                   # 全局样式
 ├── components/
-│   ├── PixelChart.jsx          # Recharts 像素风封装（统一 tooltip/grid/axis 样式）
+│   ├── ChartWrapper.jsx        # 图表组件封装（统一风格）
 │   ├── Badge.jsx               # Badge 组件
+│   ├── Pager.jsx               # 翻页控制组件（大数据量分窗口浏览）
 │   └── DataTable.jsx           # 带分页的表格组件（从 MiniTable 提取）
 └── pages/
-    ├── OverviewPage.jsx        # 总览（精简版，含趋势图）
-    ├── CharactersPage.jsx      # 角色图鉴（原 EntitiesPage + GraphPage 合并）
-    ├── PacingPage.jsx          # 节奏雷达（新：Strand + 钩子 + 字数图表）
-    ├── ForeshadowingPage.jsx   # 伏笔追踪（新：甘特图 + 状态统计）
-    ├── FilesPage.jsx           # 文档浏览（原有，移出来）
-    └── SystemPage.jsx          # 系统状态（新：Runtime + commit + RAG 环境）
+    ├── OverviewPage.jsx        # 总览
+    ├── CharactersPage.jsx      # 角色图鉴（实体 + 关系图合并）
+    ├── PacingPage.jsx          # 节奏雷达
+    ├── ForeshadowingPage.jsx   # 伏笔追踪
+    ├── FilesPage.jsx           # 文档浏览（迁移）
+    └── SystemPage.jsx          # 系统状态
 ```
 
 ### 后端（dashboard/app.py 补充 API）
@@ -41,409 +42,198 @@ src/
 /api/stats/chapter-trend       # 聚合：每章字数 + 审查得分 + 钩子强度
 /api/commits                   # 最近 N 个 commit 的 meta + projection_status
 /api/contracts/summary         # MASTER_SETTING 摘要 + 当前卷/章合同存在性
+/api/env-status                # RAG/Rerank 环境配置状态（PR #50）
+/api/env-status/probe          # RAG/Rerank 主动探测（PR #50）
 ```
 
 ---
 
-## Task 1: 后端补 3 个聚合 API
+## Task 1: 后端补聚合 API
 
 **Files:**
 - Modify: `webnovel-writer/dashboard/app.py`
 
 - [ ] **Step 1: 加 `/api/stats/chapter-trend`**
 
-从 index.db 聚合查询，一次返回每章的字数、审查得分、钩子类型和强度：
-
-```python
-@app.get("/api/stats/chapter-trend")
-def chapter_trend(limit: int = 50):
-    with closing(_get_db()) as conn:
-        chapters = _fetchall_safe(conn,
-            "SELECT chapter, word_count, title FROM chapters ORDER BY chapter DESC LIMIT ?", (limit,))
-        reading = _fetchall_safe(conn,
-            "SELECT chapter, hook_type, hook_strength FROM chapter_reading_power ORDER BY chapter DESC LIMIT ?", (limit,))
-        reviews = _fetchall_safe(conn,
-            "SELECT end_chapter as chapter, overall_score FROM review_metrics ORDER BY end_chapter DESC LIMIT ?", (limit,))
-
-    reading_map = {r["chapter"]: r for r in reading}
-    review_map = {r["chapter"]: r for r in reviews}
-
-    result = []
-    for ch in chapters:
-        c = ch["chapter"]
-        result.append({
-            "chapter": c,
-            "title": ch.get("title", ""),
-            "word_count": ch.get("word_count", 0),
-            "hook_type": reading_map.get(c, {}).get("hook_type"),
-            "hook_strength": reading_map.get(c, {}).get("hook_strength"),
-            "review_score": review_map.get(c, {}).get("overall_score"),
-        })
-    result.sort(key=lambda x: x["chapter"])
-    return result
-```
+从 index.db 聚合查询，一次返回每章的字数、审查得分、钩子类型和强度。支持 `limit` 和 `offset` 参数，默认返回最近 50 章。
 
 - [ ] **Step 2: 加 `/api/commits`**
 
-读取 `.story-system/commits/` 目录下的 commit JSON 文件：
-
-```python
-@app.get("/api/commits")
-def list_commits(limit: int = 20):
-    commits_dir = _story_system_dir() / "commits"
-    if not commits_dir.is_dir():
-        return []
-    files = sorted(commits_dir.glob("*.commit.json"), reverse=True)[:limit]
-    result = []
-    for f in files:
-        try:
-            data = json.loads(f.read_text(encoding="utf-8"))
-            result.append({
-                "file": f.name,
-                "chapter": data.get("meta", {}).get("chapter"),
-                "status": data.get("meta", {}).get("status"),
-                "projection_status": data.get("projection_status", {}),
-            })
-        except Exception:
-            pass
-    return result
-```
+读取 `.story-system/commits/` 目录下的 commit JSON 文件，返回 chapter、status、projection_status。支持 `limit` 参数。
 
 - [ ] **Step 3: 加 `/api/contracts/summary`**
 
-读取合同树文件存在性和关键字段：
-
-```python
-@app.get("/api/contracts/summary")
-def contracts_summary():
-    ss = _story_system_dir()
-    master = {}
-    master_path = ss / "MASTER_SETTING.json"
-    if master_path.is_file():
-        try:
-            data = json.loads(master_path.read_text(encoding="utf-8"))
-            route = data.get("route", {})
-            master = {
-                "exists": True,
-                "primary_genre": route.get("primary_genre", ""),
-                "core_tone": data.get("master_constraints", {}).get("core_tone", ""),
-            }
-        except Exception:
-            master = {"exists": True, "parse_error": True}
-    else:
-        master = {"exists": False}
-
-    volumes = sorted((ss / "volumes").glob("*.json")) if (ss / "volumes").is_dir() else []
-    chapters = sorted((ss / "chapters").glob("*.json")) if (ss / "chapters").is_dir() else []
-    reviews = sorted((ss / "reviews").glob("*.json")) if (ss / "reviews").is_dir() else []
-
-    return {
-        "master_setting": master,
-        "volume_count": len(volumes),
-        "chapter_count": len(chapters),
-        "review_count": len(reviews),
-        "anti_patterns_exists": (ss / "anti_patterns.json").is_file(),
-    }
-```
+读取合同树文件存在性和关键字段（MASTER_SETTING 的 primary_genre/core_tone、volume/chapter/review 合同数量）。
 
 - [ ] **Step 4: 合并 PR #50 的 env-status API**
 
-从 PR #50 的 diff 中提取 `/api/env-status` 和 `/api/env-status/probe` 的代码，加入 app.py。
-
-- [ ] **Step 5: 运行后端测试确认不破坏现有 API**
-
-```bash
-cd webnovel-writer && python -m pytest scripts/data_modules/tests/test_dashboard_app.py -v --tb=short
-```
-
-- [ ] **Step 6: Commit**
+从 PR #50 提取 `/api/env-status` 和 `/api/env-status/probe` 代码。
 
-```bash
-git add webnovel-writer/dashboard/app.py
-git commit -m "feat(dashboard): add chapter-trend, commits, contracts-summary, env-status APIs"
-```
+- [ ] **Step 5: 测试 + Commit**
 
 ---
 
-## Task 2: 前端基础设施（路由 + 图表封装 + 文件拆分）
+## Task 2: 前端基础设施（路由 + 文件拆分 + 公共组件）
 
 **Files:**
 - Modify: `dashboard/frontend/package.json`
 - Modify: `dashboard/frontend/src/main.jsx`
 - Modify: `dashboard/frontend/src/App.jsx`
 - Modify: `dashboard/frontend/src/api.js`
-- Modify: `dashboard/frontend/src/index.css`
-- Create: `dashboard/frontend/src/components/PixelChart.jsx`
-- Create: `dashboard/frontend/src/components/Badge.jsx`
-- Create: `dashboard/frontend/src/components/DataTable.jsx`
-
-- [ ] **Step 1: 安装依赖**
-
-```bash
-cd webnovel-writer/dashboard/frontend
-npm install recharts react-router-dom react-force-graph-2d
-npm uninstall react-force-graph-3d
-```
-
-- [ ] **Step 2: 创建 PixelChart.jsx**
-
-封装 Recharts 的像素风样式，统一 tooltip/grid/axis：
-
-```jsx
-// 像素风 Recharts 封装
-// - CartesianGrid: stroke="#e8dcc4" strokeDasharray="3 3"
-// - Tooltip: border="2px solid #2a220f", background="#fffaf0", 无圆角
-// - XAxis/YAxis: tick fill="#8f7f5c" fontSize=12
-// - 主线 stroke="#26a8ff", 次线 stroke="#f5a524"
-```
-
-- [ ] **Step 3: 提取 Badge 和 DataTable 公共组件**
+- Create: `dashboard/frontend/src/components/*.jsx`
 
-从现有 App.jsx 中提取 `MiniTable` → `DataTable.jsx`，提取 badge 渲染逻辑 → `Badge.jsx`。
+- [ ] **Step 1: 安装依赖（路由 + 图表库 + 关系图库）**
 
-- [ ] **Step 4: 改造 main.jsx 加路由**
-
-```jsx
-import { BrowserRouter, Routes, Route } from 'react-router-dom'
-// 每个 page 组件 lazy import
-```
+具体图表库待设计确认后决定。
 
-- [ ] **Step 5: 瘦身 App.jsx 为纯 Layout Shell**
+- [ ] **Step 2: 提取公共组件**
 
-App.jsx 只保留：侧边栏 + SSE 连接 + Router Outlet。所有页面逻辑移到 pages/ 下。
+从现有 App.jsx 提取 Badge、DataTable（原 MiniTable）、Pager（翻页控制）。
 
-- [ ] **Step 6: 补图表相关 CSS**
-
-在 index.css 中补充 Recharts 容器样式：
-
-```css
-.chart-container {
-  border: 3px solid var(--border-main);
-  box-shadow: var(--shadow-main);
-  background: var(--bg-card);
-  padding: 16px;
-  margin-bottom: 16px;
-}
-.recharts-tooltip-wrapper .pixel-tooltip {
-  border: 2px solid var(--border-main) !important;
-  background: var(--bg-card) !important;
-}
-```
+Pager 组件要点：
+- 支持窗口大小（每页 N 条）+ 翻页 + "跳到最新"
+- 适配 500+ 章数据量
 
-- [ ] **Step 7: 更新 api.js**
+- [ ] **Step 3: 改造 main.jsx 加路由**
 
-补新端点的 fetch 函数：
+每个 page 组件 lazy import + React Router。
 
-```js
-export const fetchChapterTrend = (limit = 50) => fetchJSON('/api/stats/chapter-trend', { limit })
-export const fetchCommits = (limit = 20) => fetchJSON('/api/commits', { limit })
-export const fetchContractsSummary = () => fetchJSON('/api/contracts/summary')
-export const fetchEnvStatus = () => fetchJSON('/api/env-status')
-export const fetchEnvProbe = () => fetchJSON('/api/env-status/probe')
-```
+- [ ] **Step 4: 瘦身 App.jsx 为纯 Layout Shell**
 
-- [ ] **Step 8: 构建验证**
+只保留：侧边栏导航 + SSE 连接 + Router Outlet。所有页面逻辑移到 pages/。
 
-```bash
-cd webnovel-writer/dashboard/frontend && npm run build
-```
+- [ ] **Step 5: 更新 api.js**
 
-- [ ] **Step 9: Commit**
+补新端点的 fetch 函数（chapter-trend, commits, contracts-summary, env-status, env-probe）。
 
-```bash
-git add webnovel-writer/dashboard/frontend/
-git commit -m "refactor(dashboard): add routing, chart components, split file structure"
-```
+- [ ] **Step 6: 构建验证 + Commit**
 
 ---
 
-## Task 3: 总览页重做
+## Task 3: 总览页
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/OverviewPage.jsx`
 
-- [ ] **Step 1: 实现总览页**
-
-保留现有内容，做以下改动：
-
-**保留：**
-- 5 个统计卡（总字数、当前章节、Story Runtime、主角状态、紧急伏笔）
-- Strand Weave 分布条
-- 待回收伏笔 Top 5 表格
-
-**新增：**
-- 章节趋势折线图（用 PixelChart + Recharts LineChart）
-  - X 轴：章节号
-  - 左 Y 轴：审查得分（蓝线）
-  - 右 Y 轴：字数（琥珀线）
-  - 数据来源：`/api/stats/chapter-trend`
+**功能：**
+- 统计卡：总字数/进度、当前章节/卷、Story Runtime 状态、审查均分、紧急伏笔数
+- 审查得分可视化：支持翻页浏览（默认最近 N 章）——具体图表形式待定
+- 字数分布可视化：按卷分组——具体图表形式待定
+- Strand Weave 整体分布
+- 紧急伏笔 Top 5 表格
+- 最近 3 章概要卡片
 
 **删除：**
-- MergedDataView（全量数据视图）——整个组件删掉
-- FULL_DATA_GROUPS / FULL_DATA_DOMAINS 常量——删掉
-
-**修改：**
-- "最近章节"改为从 chapter-trend 取，显示最近 3 章的摘要卡片
+- MergedDataView（全量数据视图）
+- FULL_DATA_GROUPS / FULL_DATA_DOMAINS 常量
 
-- [ ] **Step 2: 构建验证**
+**大数据量适配：**
+- 可视化组件默认显示最近窗口，支持翻页
+- 字数按卷分组，不一次性铺开所有章节
 
-- [ ] **Step 3: Commit**
+- [ ] **Step 1: 实现 + 构建验证 + Commit**
 
 ---
 
-## Task 4: 角色图鉴页（合并实体 + 图谱）
+## Task 4: 角色图鉴页
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/CharactersPage.jsx`
 
-- [ ] **Step 1: 实现角色图鉴页**
+**功能：**
+- Tab 1 列表视图：实体列表 + 筛选 + 详情面板 + 状态变化历史（保留现有逻辑）
+- Tab 2 关系图谱：替换 3D 为 2D 关系图
 
-合并原 EntitiesPage + GraphPage 为一页，两个 tab 切换：
-
-**Tab 1：列表视图**（原 EntitiesPage，保留不动）
-- 左列表 + 右详情 + 状态变化历史
-
-**Tab 2：关系图谱**
-- 换成 react-force-graph-2d（从 3d 降级）
-- 保留颜色编码和节点标签
-
-- [ ] **Step 2: Commit**
+- [ ] **Step 1: 实现 + Commit**
 
 ---
 
-## Task 5: 节奏雷达页（新）
+## Task 5: 节奏雷达页
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/PacingPage.jsx`
 
-- [ ] **Step 1: 实现节奏雷达页**
-
-三个区块：
+**功能：**
+- 钩子强度走势：支持翻页，每页 N 章——具体可视化形式待定
+- Strand 分布：逐章 Strand 分布——具体可视化形式待定
+- 字数分布：按卷分组——具体可视化形式待定
 
-**区块 1：Strand 分布（堆叠条形图）**
-- 最近 20 章的 Strand 分布
-- 用 Recharts BarChart，堆叠模式
-- Quest=蓝，Fire=粉红，Constellation=紫
+**大数据量适配：**
+- 所有组件支持翻页 + "跳到最新"
 
-**区块 2：钩子强度折线图**
-- X 轴：章节号
-- Y 轴：strong=3, medium=2, weak=1
-- 连续 weak 标红区域
-- 数据来源：chapter-trend API 的 hook_strength 字段
-
-**区块 3：最近 10 章节奏卡片**
-- 每章一个小卡片行：钩子类型 + 强度 badge + Strand + 是否过渡章
-
-- [ ] **Step 2: Commit**
+- [ ] **Step 1: 实现 + Commit**
 
 ---
 
-## Task 6: 伏笔追踪页（新）
+## Task 6: 伏笔追踪页
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/ForeshadowingPage.jsx`
 
-- [ ] **Step 1: 实现伏笔追踪页**
-
-**顶部：4 个统计卡**
-- 总伏笔数、活跃数、已回收数、超期/紧急数
+**功能：**
+- 统计卡：总伏笔、活跃、已回收、紧急/超期
+- 状态筛选按钮：全部 / 紧急 / 活跃 / 已回收
+- 伏笔时间线：横向甘特图，埋设章→目标章，颜色按状态，蓝线标当前章
+- 完整伏笔表格：内容、状态、埋设章、目标章、紧急度
 
-**中部：伏笔时间线（横向甘特图）**
-- 用 Recharts BarChart 横向模式模拟甘特图
-- X 轴：章节号范围
-- 每条伏笔一行：从埋设章到目标章画一条横条
-- 颜色：绿=已回收，黄=活跃，红=快超期/已超期
+**大数据量适配：**
+- 甘特图默认只显示活跃+紧急，已回收折叠
+- 横轴范围自动适配（不铺满 1-500）
 
-**底部：完整伏笔表格**
-- 列：内容、状态、埋设章、目标章、紧急度
-- 数据来源：`/api/project/info` 的 `plot_threads.foreshadowing`
-
-- [ ] **Step 2: Commit**
+- [ ] **Step 1: 实现 + Commit**
 
 ---
 
-## Task 7: 系统状态页（新）
+## Task 7: 系统状态页
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/SystemPage.jsx`
 
-- [ ] **Step 1: 实现系统状态页**
-
-**区块 1：Story Runtime 健康**
-- 调 `/api/story-runtime/health`
-- 显示 mainline/fallback 状态、fallback_sources、latest commit status
-
-**区块 2：合同树概览**
-- 调 `/api/contracts/summary`
-- 显示 MASTER_SETTING 的题材/调性、volume/chapter/review 合同数量
-
-**区块 3：最近 Commit 历史**
-- 调 `/api/commits`
-- 表格：章节号、状态（accepted/rejected badge）、projection_status 五项
+**功能：**
+- Story Runtime 健康状态（mainline/fallback、latest commit）
+- 合同树概览（MASTER_SETTING 题材/调性、volume/chapter/review 数量）
+- 最近 Commit 历史表格（章节、accepted/rejected、5 路 projection_status）
+- RAG 环境状态（embed/rerank key、vector_db 大小、rag_mode）+ 诊断按钮
 
-**区块 4：RAG 环境（PR #50）**
-- 调 `/api/env-status`
-- 显示 embed/rerank key 配置状态、vector_db 大小、rag_mode
-- "诊断" 按钮调 `/api/env-status/probe`，显示延迟和连通性
-
-- [ ] **Step 2: Commit**
+- [ ] **Step 1: 实现 + Commit**
 
 ---
 
-## Task 8: 文档浏览页迁移 + 清理
+## Task 8: 文档浏览迁移 + 最终清理
 
 **Files:**
 - Create: `dashboard/frontend/src/pages/FilesPage.jsx`
-- Modify: `dashboard/frontend/src/App.jsx` (最终清理)
-
-- [ ] **Step 1: 迁移 FilesPage**
-
-从 App.jsx 移到 `pages/FilesPage.jsx`，逻辑不变。
-
-- [ ] **Step 2: 最终清理 App.jsx**
-
-确认 App.jsx 只剩 Layout Shell（侧边栏 + Router Outlet + SSE），无页面逻辑。
-
-删除所有已迁移的组件和常量（DashboardPage、EntitiesPage、GraphPage 等）。
-
-- [ ] **Step 3: 前端构建 + 验证**
-
-```bash
-cd webnovel-writer/dashboard/frontend && npm run build
-```
-
-启动 dashboard 确认所有 6 个页面正常：
-```bash
-cd webnovel-writer && python -m dashboard.server --project-root "{test_project}" --no-browser
-```
-
-- [ ] **Step 4: Commit**
+- Modify: `dashboard/frontend/src/App.jsx`
 
-```bash
-git add webnovel-writer/dashboard/
-git commit -m "feat(dashboard): complete frontend rebuild with charts, pacing, foreshadowing, system pages"
-```
+- [ ] **Step 1: 迁移 FilesPage（逻辑不变）**
+- [ ] **Step 2: 最终清理 App.jsx（删除所有已迁移的组件和常量）**
+- [ ] **Step 3: 前端构建 + 启动验证所有 6 页 + Commit**
 
 ---
 
-## 导航变更汇总
+## 导航变更
 
 | 旧导航 | 新导航 | 变化 |
 |--------|--------|------|
-| 📊 数据总览 | 📊 总览 | 删全量视图，加趋势折线图 |
+| 📊 数据总览 | 📊 总览 | 删全量视图，加可视化 |
 | 👤 设定词典 | 👤 角色图鉴 | 合并关系图谱，2D 替 3D |
 | 🕸️ 关系图谱 | _(合并到角色)_ | 删除独立页面 |
-| 📝 章节一览 | 📈 节奏雷达 | 新页面，Strand/钩子/字数图表 |
+| 📝 章节一览 | 📈 节奏雷达 | 新页面 |
 | 📁 文档浏览 | 📁 文档浏览 | 不变 |
-| 🔥 追读力 | 🔖 伏笔追踪 | 新页面，替代纯表格追读力 |
+| 🔥 追读力 | 🔖 伏笔追踪 | 新页面 |
 | _(无)_ | ⚙️ 系统状态 | 新页面 |
 
 ## 删除的数据
 
-- RAG 查询日志
-- 工具调用统计
-- Override 合约明细
-- 债务事件明细
-- 无效事实列表
-- 写作清单评分原始数据
-- 全量数据视图（MergedDataView）
+- RAG 查询日志、工具调用统计、Override 合约明细、债务事件明细
+- 无效事实列表、写作清单评分原始数据、全量数据视图（MergedDataView）
+
+## 待确认项（设计讨论后更新）
+
+- [ ] 视觉风格确认（保留像素风 / 调整）
+- [ ] 审查得分可视化形式
+- [ ] 字数分布可视化形式
+- [ ] 钩子强度可视化形式
+- [ ] Strand 分布可视化形式
+- [ ] 图表库选型（Recharts / 其他 / 纯 CSS）
+- [ ] 关系图库选型（react-force-graph-2d / @antv/G6 / 其他）