workbuddy-portal/docs/ARCHITECTURE.md

架构与设计说明

面向开发 / 维护者。解释这个系统为什么长这样，以及改动时不能碰的红线。

目录

• 一、分层与数据流
• 二、数据模型
• 三、采集：断点、去重、锁
• 四、调度：为什么不用 APScheduler
• 五、聚合层：边界在哪
• 六、呈现层：两套界面共用一套令牌
• 七、安全模型
• 八、配置系统：写时校验 + 读时兜底
• 九、已知坑与红线
• 十、验证体系

---

一、分层与数据流

client.py          纯 urllib 调云端；读编辑器 settings.json 取凭证
    │
    ▼
collect.py         断点续采 → 文件锁 → 规范化 → 分批 upsert；导入/导出也在这
    │                    ▲
    │                    │ scheduler.py 只是「到点调 collect.sync()」
    ▼
db.py + schema.sql SQLite（WAL），单写者；settings 表兼作运行期配置
    │
    ▼
query.py           全部聚合下推 SQL：daily / dims / top / records / summary / bundle / manifest
    │
    ├──▶ web/views.py   Jinja 后台（7 个页面）
    └──▶ web/api.py     JSON（大屏 + 页面异步调用）

关键点：没有中间 JSON 层。 旧版本是「脚本 → CSV → 预生成 JSON → 大屏」， 任何一次查询变化都要重新跑生成器。现在聚合全部下推 SQL，页面与接口共享同一个 query 层， 口径不可能不一致。

---

二、数据模型

usage_records(
    request_id TEXT PRIMARY KEY,   -- 云端请求 ID，去重靠它
    ts         TEXT NOT NULL,      -- 本地时间戳 'YYYY-MM-DD HH:MM:SS'
    day        TEXT NOT NULL,      -- 派生字段：便于按天聚合与建索引
    hour       INTEGER NOT NULL,   -- 派生字段：0-23，供时段分布
    model      TEXT, client TEXT,
    credits    REAL NOT NULL,
    prompt     TEXT,               -- 可截断（max_prompt）
    first_seen TEXT, last_seen TEXT,
    cloud_ts   TEXT                -- 云端原始时间，用于漂移检测
)

collect_runs(
    id INTEGER PRIMARY KEY, trigger TEXT, status TEXT,
    started_at, finished_at, duration_ms,
    win_from, win_to,              -- 本次扫描窗口
    fetched, added, dup, total, conflicts,
    exit_code, message, detail     -- detail 存逐行日志原文
)

settings(key PRIMARY KEY, value, updated_at)   -- cookie / 调度 / 采集参数 / 与 slot:HH:MM 簿记
users(id, username UNIQUE, password_hash, display_name, is_admin, created_at, last_login_at, login_count)
audit_log(id, at, actor, action, detail, ip)

索引：day、(day,hour)、(model,day)、(client,day)、credits DESC、ts。 覆盖了「按天」「按天+时段」「模型/客户端 × 天」「单笔 TOP」「时间排序」五类热点查询。

为什么 day/hour 是冗余列

substr(ts,1,10) 这类函数表达式无法走索引。把它们物化成列 + 索引，聚合查询从全表扫描 变成索引扫描。写入时多算一次，读的时候省下 N 次。

为什么 settings 表兼作簿记

调度槽位去重需要一个「今天 09:00 已经跑过了」的持久标记，正好复用 settings(key='slot:2026-09-14T09:00', value='done')。这类键用前缀 slot: 标记为 内部键：/api/settings 读写两侧都过滤掉（config.is_internal_key()）， 用户不会在配置页看到它们，也无法通过接口写入任意键。

---

三、采集：断点、去重、锁

断点续采

since = 本地 MAX(ts) - rewind_minutes      # 回退几分钟，容忍云端写入延迟
rows  = client.fetch_range(since, now)     # 分页拉取

回退的意义：云端记录可能比本地时间晚落库，卡在边界上的记录会被漏掉。 默认回退 2 分钟，重复拉到已有记录由去重兜住——宁可重复拉，不可漏。

去重：ON CONFLICT + 取更早的时间

INSERT INTO usage_records(...) VALUES(...)
ON CONFLICT(request_id) DO UPDATE SET
    ts = CASE WHEN excluded.ts < usage_records.ts THEN excluded.ts ELSE usage_records.ts END,
    ...

同一条请求可能被多次拉到（断点回退 + 区间补采重叠）。冲突时以更早的本地 ts 为准， 因为后拉到的可能已经越过了跨日边界。

单写者：文件锁

collect._Lock()  →  data/collect.lock   (O_CREAT|O_EXCL)

三处调用者共享这把锁：调度线程、页面手动触发（POST /api/collect）、CLI（manage.py collect）。 拿到锁失败 → 抛 collect.Busy → API 返回 409，页面提示「采集正在进行中」。

锁文件含时间戳，超过 30 分钟视为僵尸锁可抢占（进程被 kill 时锁不会自己释放）。

为什么不用数据库锁：SQLite 的写锁是「事务级」的，而一次采集可能持续几分钟 且分多个事务提交。用文件锁把「整个采集流程」串起来，比用事务锁正确得多。

分批提交

upsert() 每 200 行一个显式事务（BEGIN / COMMIT），并带重入保护：

own_tx = not conn.in_transaction     # 已在事务里就别再 BEGIN（会报错）

这样中途失败只回滚当前一批，已入库的不受影响。

---

四、调度：为什么不用 APScheduler

需求只有「每天几个固定时刻」。一个 20 秒轮询的线程就够：

while True:
    now = datetime.now()
    for slot in due_slots(now):       # 今天该跑但没跑过的时刻
        if not already_done(slot):    # 靠 settings 里的 slot: 键去重
            mark_done(slot)
            collect.sync(trigger="schedule")
    sleep(20)

自研换来三件事外部调度器给不了：

1. 启动补跑：程序没开时错过的时刻，启动后检查「今天已过的时刻」， 在宽限期（catch_up_grace_hours，默认 12 小时）内补采。
2. 与 CLI 共享同一把锁：手动 manage.py collect 不会和调度撞车。
3. 零额外依赖：少一个包，少一类版本冲突。

注意事项：

• WERKZEUG_RUN_MAIN 守卫：--debug 下 reloader 会 fork 子进程，只允许子进程起调度。
• WB_DISABLE_SCHEDULER=1 关掉调度（多副本时给除第一份外的实例用）。
• 轮询间隔 20 秒是折中：时刻精度 ±20 秒足够，且几乎不占 CPU。

---

五、聚合层：边界在哪

query.py 是唯一的聚合出口。几个刻意的设计：

函数	边界	为什么
manifest()	全量	存档总览，供页面显示「数据范围」「活跃天数」
bundle() 的 daily	全量（约 200 B/天）	大屏的日历与日期轴需要完整日期序列
bundle() 的 top	全局	大屏的「单笔 TOP」不该随窗口变（否则排名会跳）
bundle() 的 dims/records/totals	随窗口	这才是筛选真正影响的部分
bundle() 的 records	有上限核心集	见下
summary()	窗口 + 上一段	环比；前一段不在存档内时不给假数字，明确标记

bundle 为什么要设上限

大屏是「数据进浏览器 → 控件联动 → 即时重绘」的模型，必须把数据一次性下发。 但全量明细可能有几十万条，直接塞进 JSON 会把浏览器打死。

所以：

BUNDLE_RECORDS_CAP = 20000

超过上限时只发最新的 N 条，同时返回 recordsTotal / recordsCap / recordsTruncated， 页面据此提示「明细表只显示最近 N 条，完整数据请到数据明细页」。不静默丢数据是关键。

日期归一化

norm_day() 容忍 2026/09/08、2026-09-08 12:00:00、T 分隔； norm_window() 还会自动交换写反的起止。任何手写 query string 都不该让接口 500。

---

六、呈现层：两套界面共用一套令牌

• Jinja 后台：web/templates/*.html + web/static/css/app.css
• ECharts 大屏：web/static/dashboard/index.html（单文件，内联样式）

两者共用同一套设计令牌（色板 / 圆角 / 间距 / 字号）。大屏是独立静态页， 因为它需要完全自由的布局与 canvas 尺寸，套进导航框架反而受限。

大屏页的所有权边界

大屏页有 13 个渲染函数，只允许改数据层，不允许改渲染逻辑。原因： 渲染函数经过 Node DOM stub 工装验证（断言「页面聚合 == 独立算出的聚合」）， 改动它们会让验证失效。

返回值形状契约

大屏页沿用旧版 dashboard/data/*.json 的短键：

daily:   d(day) c(credits) k(calls) f(first) b(build) m(models) h(hours[24])
records: id c(credits) m(model) cl(client) t(ts) px(prompt)

而 /api/records（供 Jinja 表格与导出）用可读全名： request_id / credits / model / client / ts / prompt。

这不是不一致，是两套消费方的契约不同：改短键要大屏重写，改全名要模板重写。 不要试图「统一」它们。

---

七、安全模型

认证

项	做法
密码存储	pbkdf2:sha256:200000（Werkzeug 实现）
会话	Flask 签名 cookie workbuddy_portal_sid，HttpOnly + SameSite=Lax，12 小时
密钥持久化	data/instance.json 的 secret_key，重启不踢人
失败限速	同 IP 连续 5 次失败锁定 10 分钟；计数表有上限（4096 个 IP）与 TTL（1 小时）

授权

@login_required（/api/* 未登录返回 401 JSON，页面跳登录）+ @admin_required（403）两层。/users 与 /api/users* 全部要管理员。

内置护栏（服务端强制，前端只是提前提示）：不能取消自己的管理员身份、不能删自己、至少留一个账号。

CSRF

before_request 统一校验：X-CSRF-Token 头或 _csrf 表单域。 退出登录也走 POST——GET 型退出能被 <img src="/logout"> 静默触发。

开放重定向

登录跳转的 next 只接受站内相对路径。security.safe_next() 拒绝：

• //evil.com（协议相对 URL，浏览器会当成 http://evil.com）
• /\evil.com、含 \ 的
• http://... / https://... 绝对地址
• 含 CR/LF 的（防 header 注入）

凭证

• Cookie 只回掩码（cookie_hint），页面与接口都不回明文；保存时留空 = 不覆盖。
• 默认 ssl_verify=1：Cookie 就是账号凭证，不该在无校验的 TLS 上裸奔。
• 内部簿记键（slot:*）读写两侧都过滤。

参数

所有查询参数在入口归一化 / 钳制。非法值返回 400（带人话说明）或回落默认， 绝不 500——全局 ValueError 处理器兜住 strptime / int() 这类异常。

---

八、配置系统：写时校验 + 读时兜底

历史 bug：配置页是自由文本框，把 page_size 敲成 abc 后， 采集在 int() 处抛 ValueError 整个跑不起来。现在的双保险：

写时校验（config.normalize_setting）

NUM_SETTINGS = {"page_size": (20, 1000, "条/页"), ...}   # 范围 + 单位
BOOL_SETTINGS = {"schedule_enabled", "catch_up"}

非法值 → 400 {"error":"invalid","errors":[...]}，一次列出全部错误，并写审计 settings_rejected。

读时兜底

page_size = db.get_int(conn, "page_size", 200)   # 任何异常都回落默认值

采集路径上不允许出现裸 int(s.get(...))。数值还会按 NUM_SETTINGS 的范围再钳一次。

---

九、已知坑与红线

流式响应里不能复用 db.get_db()

Flask 在 full_dispatch_request() 返回 app_iter 之后就 pop 请求上下文 （teardown_appcontext → close_db 关掉 g.db），WSGI 服务器才开始迭代生成器。 于是生成器一读库就报 Cannot operate on a closed database。

规则：凡 Response(gen()) / stream_with_context 场景，生成器内部要 db.connect() 自建连接并 finally 关闭。（/records/export 就是这么修的。）

send_from_directory 吐的单层路由，页内资源必须写绝对路径

/dashboard 没有尾斜杠，页内 src="vendor/echarts.min.js" 会被解析成 /vendor/echarts.min.js → 404 → 整页图表全白。静态挂载点是 /static， 所以写 /static/dashboard/vendor/echarts.min.js。

这个 bug 曾经躲过「状态码断言」和「真实 HTTP」两层测试，只有浏览器截图才抓到。 现在 tools/smoke.py 有专门一节：抓页面里所有 src/href 资源引用逐个断言 200 （断言前先剥掉 HTML 注释，否则注释里的示例路径会被误判）。

Jinja 里避开 dict 的方法名

模板中 a.items / a.keys / a.get / a.values / a.update / a.pop / a.copy 会命中方法而不是数据（属性查找优先于下标）。视图里把这类值拆成独立变量传。

同类坑：视图里不要把 fetchall() 的 Row 列表用列表推导扁平化成字符串列表 ——模板写 a[0] 会变成「取字符串第一个字符」，而且不报错。

同一文件不能连续并行编辑

同一轮响应里对同一文件发多个编辑会互相覆盖（都返回成功，只有最后一个落盘）。 改同一文件必须串行，改完回读确认。

新增组件用带前缀的独有类名

class="bar" 撞上页面已有的筛选条 .bar（带 backdrop-filter: blur(6px)）， 会让整块文字被静默虚化。新组件一律用带前缀的类名（如 .calcell .cbar）。 smoke.py 里有「页面 class ∩ app.css 选择器」差集断言兜这类问题。

前端日期运算不要用 toISOString().slice(0,10)

GMT+8 下 new Date("2026-08-15T00:00:00") 的 UTC 时刻是前一天 16:00， 取出来就少一天，「加一天」变成「减一天」，循环跑飞。 用 getFullYear/getMonth/getDate 拼本地串。

ECharts 热力图 data 是「一个坐标一个点」

同坐标重复 push 会互相覆盖而非累加。要展示格子合计，必须先在 JS 里按 (x,y) 聚合再 push。

其它

• 传给模板的「带下标的行」直接传 fetchall() 的 Row 列表，不要先扁平化。
• 本机 chromium 截图要用同版本二进制初始化过的 profile 目录； Playwright 驱动与本机浏览器版本会错位，需显式传 executable_path。
• urllib / curl 会走本机代理，把 127.0.0.1 也拦成 502—— 探测本地服务要 build_opener(ProxyHandler({}), ...) 或 --noproxy '*'。

---

十、验证体系

五层，按代价从低到高。前两层已固化成脚本，改完必须跑。

层	手段	抓什么
1	独立聚合对账（直读 CSV 不走 query.py）	口径错、少算。热力图要逐格比，历史上出过「同格覆盖少算 84%」
2	tools/smoke.py（99 项断言，离线）	模板残留、历史缺陷防回归 ①~⑭、静态资源 404、class↔CSS 对账
3	tools/check_live.py（56 项断言，真实 HTTP）	test_client 覆盖不到的：waitress、端口、cookie 往返、开放重定向、CSRF
4	Node DOM stub + vm.runInContext 跑大屏真实脚本	「页面聚合 == 独立算出的聚合」、切区间只发一次请求
5	tools/shots.py（Playwright 截图 + console/pageerror）	界面层。本轮最有价值的 bug（大屏全白）只有它抓到

python tools/smoke.py                                        # 1~2 层，随时跑
python manage.py serve --port 8849 --no-scheduler            # 另开终端
python tools/check_live.py --base http://127.0.0.1:8849      # 3 层
python tools/shots.py    --base http://127.0.0.1:8849 --full # 5 层

改动前先读 九、已知坑与红线，改完先把第 2 层跑绿。