技能｜仪表盘聚合视图接入流程

适用场景

已有多处在台账页/财务页的零散统计，要聚合成常驻总览页 /overview，且系统零第三方依赖（不能引图表库）时。触发词：仪表盘、总览页、概览、KPI 聚合、首页统计。

操作步骤

1. 路由入口：在 app.py 的分发器加 elif path == '/overview': self._dashboard()（本项目已实现：app.py 中 /overview 调 _dashboard()；另有一处旧的 _overview() 走 overview_page，新接入以 _dashboard 为准）。
2. 拼装取数（关键：每块独立容错）：_dashboard() 里逐个调：
   - 财务：db.monthly_summary(month)、db.account_balances()、db.list_txns(limit=8)、db.year_summary(year)、三年循环 db.year_summary(str(y))、db.monthly_series(year)、db.budget_vs_actual(month)（预算执行率 budget_pct = 已用/总额）。
   - 台账：[(s['title'], len(db.ledger_list(s['key']))) for s in ledgers.SPECS] 做各域条数；db.ledger_list('zl_f07') 取中高危且未关闭项作风险；db.ledger_list('lw_f01') 取 valid_to 在 30 天内的证件到期。
   - 每一块都用 try/except 包住：失败则该块降级为 0 / [] / [(title,0)...]，绝不让一块异常拖垮整页（这是聚合页最容易整页 500 的根因）。
3. 单一取数出口：所有取数走 db 模块（同一连接封装），不要各视图自己开连接、自己解析。
4. 模板渲染：self._html(T.dashboard(dict(...)))，渲染函数在 templates.py:516 def dashboard(d)；卡片网格 + 内联 SVG（环形/趋势），配色用 CSS 变量（陶土橙 --accent2 等），暗色模式 [data-theme=dark] 同步。
5. 链接闭环：每张卡片可点跳明细——交易明细 /txn、预算 /budget、各域台账 /l/<key>（见 templates.py 的 overview_page 里 href="/l/%s"）。
6. 验收：接入后跑全站冒烟，确认 /overview 不在错误列表；空数据态显示"暂无记录"而非报错。

注意边界

• 首页 /overview 与页头导航若已定稿，只加区块不改结构与样式（参见导航改造技能里的定稿约束）。
• 指标口径必须与明细页一致（如预算执行率算法与 /budget 页同源），否则两处数字打架。
• 取数要轻：每次访问都算，避免大表全扫；可按数据源指纹做内存缓存、源变即失效。

反例避雷

• 一个 try 包住全部取数 → 一处挂、整页挂（本项目的 _dashboard 正是逐块 try 才稳）。
• 新造指标 → 与明细页口径不一致，使用者不信。
• 引第三方图表库 → 破坏零依赖与离线可用。
• 卡片只展示不给跳转 → 聚合页变死胡同。

关联笔记

• [[技能｜全页面回归冒烟法]]
• [[技能｜吞噬异常统一留痕治理法]]

实战战绩

2026-09-28 首跑：把分散在台账页/财务页的统计聚合为常驻 /overview（_dashboard）。约 11 个取数块各自独立 try 容错，单块异常不影响整页；近 8 笔交易、三年对比、预算执行率、各域条数、中高风险、证件临期全部聚合可跳转；接入后全站冒烟 0 错误。

版本记录