wangchuanli/workbuddy-portal
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
3751dffef94179a9b4c1e5f4667c8ff623795dcb
workbuddy-portal/docs/ARCHITECTURE.md
T
wangchuanli 1bf961f6b3 feat(权限): 收敛普通账号写权限至本人凭证 
将调度时刻、采集参数等实例级配置收归管理员，普通账号仅可维护本人 Cookie 与 User-Agent。
新增 config.writable_by 作为唯一写权限入口，set_setting 强制全局键落到 user_id=0，
消除「管理员改了只有自己生效」的静默缺陷。新增 tools/check_docs.py 文档自检，
smoke 断言扩至 215 项、check_live 扩至 122 项并支持普通账号越权验收，
忽略 backups/、data/*.bak* 与 legacy-v1/，版本升至 v1.3.0。
2026-09-18 08:46:00 +08:00

28 KiB
原始文件 Blame 文件历史

架构与设计说明

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

目录

一、分层与数据流

client.py          纯 urllib 调云端；读编辑器 settings.json 取凭证
    │
    ▼
collect.py         断点续采 → 文件锁 → 规范化 → 分批 upsert；导入/导出也在这
    │                    ▲                       所有函数都要求 uid
    │                    │ scheduler.py 只是「到点调 collect.sync(conn, uid, ...)」
    ▼
crypto.py          凭证静态加密（手写 ChaCha20 + HMAC）；captcha.py 出验证码图
    ▼
db.py + schema.sql SQLite（WAL），单写者；settings 表兼作运行期配置（主键 (user_id,key)）
    │
    ▼
query.py           全部聚合下推 SQL：daily / dims / top / records / summary / bundle / manifest
    │               uid 是 WHERE 的第一个条件
    ├──▶ web/views.py   Jinja 后台（含 /login /register /profile + 6 个数据页）
    └──▶ web/api.py     JSON（大屏 + 页面异步调用）

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

关键点：没有「当前用户」这种隐式全局。 uid 必须由调用方一路显式传下去 （见 七、安全模型），所以「忘了过滤」在类型层面就写不出来。

二、数据模型

-- 多用户布局：所有按账号隔离的表都以 user_id 打头
usage_records(
    user_id    INTEGER NOT NULL DEFAULT 0,
    request_id TEXT    NOT NULL,   -- 云端请求 ID，去重靠它
    ts         TEXT    NOT NULL,   -- 本地时间戳 'YYYY-MM-DD HH:MM:SS'
    day        TEXT    NOT NULL,   -- 派生字段：便于按天聚合与建索引
    hour       INTEGER NOT NULL,   -- 派生字段：0-23，供时段分布
    model      TEXT NOT NULL DEFAULT '-', client TEXT NOT NULL DEFAULT '-',
    credits    REAL NOT NULL DEFAULT 0,
    prompt     TEXT,               -- 可截断（max_prompt）
    first_seen TEXT NOT NULL, last_seen TEXT NOT NULL,
    cloud_ts   TEXT,               -- 云端原始时间，用于漂移检测
    PRIMARY KEY (user_id, request_id)      -- 复合主键：去重是「按账号」去重
)

collect_runs(
    id INTEGER PRIMARY KEY, user_id INTEGER NOT NULL DEFAULT 0,
    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(user_id INTEGER NOT NULL DEFAULT 0, key TEXT NOT NULL, value, updated_at,
         PRIMARY KEY (user_id, key))

users(id, username UNIQUE, password_hash, display_name, email,
      is_admin, status, register_ip, last_login_ip,
      created_at, last_login_at, login_count)

captchas(id TEXT PRIMARY KEY, answer TEXT, purpose TEXT,
         created_at, expires_at, used_at)

audit_log(id, user_id, at, actor, action, detail, ip)

user_id = 0 的含义：在 settings / collect_runs / audit_log 里表示 实例级（所有账号共用，例如 api_base、schedule_times、page_size、系统迁移审计）； 在 usage_records 里是「尚未归属」的兜底值，正常不会出现。

⚠️ 实例级不是「孤儿行」。清理孤儿数据的 SQL 必须显式排除 user_id = 0， 例如 DELETE FROM settings WHERE user_id <> 0 AND user_id NOT IN (SELECT id FROM users)。 写成 user_id NOT IN (SELECT id FROM users) 会一次性删光整片实例级配置 —— 表现是「所有账号的调度、采集参数、注册策略突然全部回到默认值」。

索引全部以 user_id 打头，覆盖六类热点查询： (user_id, day)、(user_id, day, hour)、(user_id, model, day)、(user_id, client, day)、 (user_id, credits DESC)、(user_id, ts)。

为什么要复合主键而不是「加一列 user_id」

usage_records 的主键从 request_id 变成 (user_id, request_id) 是语义变化： 两个人可能各自命中同一个云端 request_id（同一台机器上的多个浏览器 profile 就会）， 单列主键会让后写入的人把前一个人的记录覆盖掉。去重必须按账号做。

为什么 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()）， 用户不会在配置页看到它们，也无法通过接口写入任意键。 多用户下槽位标记是按账号的（(user_id, 'slot:09:00')），所以谁改了自己的时刻 只影响自己。

升级路径：PRAGMA user_version

db.init_db() 用 PRAGMA user_version 判断库结构版本（0/1 = 单用户，2 = 多用户）。 主键变了的表不能 ALTER，只能重建，顺序不能变：

1. 删掉所有自建索引        ← 关键，见下
2. ALTER TABLE ... RENAME TO _v1_xxx
3. ALTER TABLE 加新列（只加列的表用这个，代价小得多）
4. executescript(schema.sql)   ← 此时列齐了，表与索引一次建全
5. INSERT ... SELECT 回填(user_id) → DROP TABLE _v1_xxx
6. 把历史明文凭证加密 + 写一条 schema_migrate 审计

为什么第 1 步不能省：ALTER TABLE RENAME 会把索引一起带走且名字仍被占用， 于是随后的 CREATE INDEX IF NOT EXISTS 被静默跳过 —— 新表一个索引都没有， 功能看起来完全正常，查询却慢几百倍。这是最阴的一类迁移 bug。 第 3 步放在第 4 步之前，则是为了让引用新列的索引一次就建成功。

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

断点续采

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 分钟；计数表有上限（8192 key）与 TTL（1 小时）
验证码 策略 always（默认）/ adaptive / off；先验码再验密
注册 开关 allow_register + 同 IP 每日配额 register_max_per_ip + 强制验证码
停用即失效 current_user() 每请求回查 users.status（缓存在 flask.g），不等会话过期
会话固定防护 login_session() 先 session.clear()，顺带换掉 CSRF token 与验证码 id

授权与数据隔离

@login_required（/api/* 未登录返回 401 JSON，页面跳登录）+ @admin_required（403）两层。仅管理员：/users、/api/users*、/logs、/logs/tail、vacuum。

两者之间还有一层「同一个页面、两种形态」：/tasks 与 /config 对普通账号仍然可达， 但渲染成只读形态（不给表单，换成只读表格 + 一句说明为什么只读）， 写接口也会拒绝。页面形态与接口判断共用 config.writable_by()， 所以不存在「界面上没按钮、构造请求却能改」的空隙 —— 这是本次权限收敛刻意保证的性质。

多租户隔离靠「显式传参」而不是「隐式全局」，这是本节最重要的一条设计：

# 每个公开函数都把 uid 放在 conn 之后的第一个位置，且**不给默认值**
def daily(conn, uid, frm=None, to=None, with_maps=True): ...
def totals(conn, uid, frm=None, to=None): ...
collect.sync(conn, uid, trigger="manual", ...)
scheduler.slots(conn, uid=0)

为什么不给默认值？因为一旦写成 uid=0，忘记传参就会静默返回实例级（≈全量）数据—— 这种越权不会报错、不会进日志，只会在某天被人发现。给成必填参数后，漏传是 TypeError， 在第一次跑测试时就炸掉。

配套的几条：

项 做法
单条读取也过滤 /api/records/<id>、/api/runs/<id> 的 WHERE 都带 user_id
配置作用域 三级回落 个人 → 实例 → DEFAULTS；GLOBAL_KEYS（云端接口 + 注册策略 + 调度 + 采集参数）一律存实例级 user_id=0 且仅管理员可写；普通账号可写的只有 USER_EDITABLE_KEYS = {cookie, user_agent}
凭证不回落 NO_FALLBACK_KEYS = {cookie, user_agent} 跳过实例级回落 —— 否则新账号会「继承」管理员的 Cookie，这是最严重的串号越权
导出隔离 CSV 文件名带账号名（多用户下同目录同名会互相覆盖）
审计归属 audit_log / collect_runs 都带 user_id；/api/audit 普通账号只看自己

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

凭证加密与验证码

这两件事都要求「零第三方依赖」（requirements.txt 只有 Flask / waitress / openpyxl）， 所以都是手写标准库实现。

凭证加密（crypto.py） —— 手写 ChaCha20（RFC 8439 §2.3 的块函数）+ HMAC-SHA256 encrypt-then-MAC，所以不存在「先解密再验签」的填充预言类问题：

密文 = "v1." + b64(salt) + "." + b64(nonce) + "." + b64(ciphertext) + "." + b64(tag)
子密钥 = HMAC-SHA256(master, salt, "aead-key") / ("aead-mac")   ← 密钥分离

实现上的三个决定：

  1. decrypt() 失败抛异常，绝不返回原值。返回原值看似「容错」， 实际是把「密钥不匹配」伪装成「Cookie 是个奇怪字符串」，然后把这段垃圾发给云端。 现在会明确抛 db.SecretUnreadable，页面提示「密文解不开，请重新粘贴」。
  2. 非 v1. 前缀原样返回 —— 专门用来兼容单用户时代存下来的明文； 下次写入时自动升级为密文。升级迁移还会主动扫一遍并就地加密。
  3. get_settings() 把加密键置空，明文的唯一出口是 db.get_secret()。 这比「记得别回传 cookie」可靠：写新接口的人即使 **settings 一把梭也带不出凭证。

图形验证码（captcha.py） —— 手写 PNG 编码器（zlib 压缩 IDAT）+ 5×7 点阵字模

  • Bresenham 干扰线 + 逐字符抖动 + 噪点：
决定 原因
出 PNG 而不是 SVG SVG 是文本，答案会明文出现在页面源码里，等于把答案发给机器人
不用第三方 captcha/Pillow 保持零第三方依赖；图像只由点阵矩形构成，没必要引入整个图像栈
答案不进会话 Flask 会话是「签名 + base64，不加密」的（客户端可解码读明文），放答案等于送答案。只写一个随机 id
先删后判 verify() 先 DELETE 再比对，避免并发下同一张图被用两次
按 purpose 隔离 拿注册的题去登录校验必然失败
出图限速 60 秒 40 张 —— 出图要做点阵渲染 + zlib 压缩，不设限就是一条廉价的 CPU/带宽放大路径
登录先验码 否则攻击者能拿「密码对不对」当信号，在解验证码之前就把字典跑完

CSRF

before_request 统一校验：X-CSRF-Token 头或 _csrf 表单域。 退出登录也走 POST——GET 型退出能被 <img src="/logout"> 静默触发。 未登录的 POST 也会先被 CSRF 拦成 400（先拦比先鉴权更保守）。

开放重定向

登录跳转的 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 的范围再钳一次。

配置的作用域：三级回落与一个例外

个人(user_id=n)  ──没有──▶  实例(user_id=0)  ──没有──▶  config.DEFAULTS
        ▲
        └── NO_FALLBACK_KEYS（cookie / user_agent）到此为止，不回落到实例级

GLOBAL_KEYS（共 17 个键，分四组）在读写两侧都被强制折算到 user_id = 0， 所以它们天然只有一份，非管理员改不了：

分组 键 为什么归实例级
云端接口(2) api_base、api_path 一台部署连的就是那一个云端，逐账号配没有意义
注册策略(4) allow_register、register_max_per_ip、captcha_policy、captcha_length 敞开注册与否是运营决策，不能由任意账号开关
调度(4) schedule_enabled、schedule_times、catch_up、catch_up_grace_hours 普通账号不能设置定时任务频率（本轮需求）
采集参数(7) page_size、rewind_minutes、drift_tolerance_minutes、max_prompt、verify_days、timeout、ssl_verify 关掉 ssl_verify 就能把所有人的 Cookie 发到中间人手里

这三样东西必须对齐，缺一不可：

  1. 键存在哪一级 —— GLOBAL_KEYS 一律 user_id = 0；
  2. 谁能写 —— config.writable_by(key, is_admin)：只有 USER_EDITABLE_KEYS 对普通账号放行；
  3. 读时落哪 —— 三级回落 个人 → 实例 → DEFAULTS。

🔴 最常见的静默 bug 是「只做到第 2 条」：管理员能改，但值写进了管理员自己的 user_id=n。 别的账号读同一个键时会落回 DEFAULTS，于是「管理员改了，但只有他自己那边生效」， 界面上完全看不出来。所以 set_setting() 内部会把全局键强制重定向到 user_id = 0， 从结构上消除这种可能，而不是靠调用方记得传 0。

有个 slot:* 例外：slot:09:00 这类簿记键表示「本账号今天这个槽位跑过没有」， 它是个人级（每个账号各记一份），而它所指向的时刻 schedule_times 是实例级。 这两者千万别一起改 —— 把 slot:* 也搬到实例级，会让两个账号互相以为对方已经跑过当天采集。

有个容易误判的细节：NO_FALLBACK_KEYS 只拦住「实例级那一行」，不拦 DEFAULTS。 所以一个全新账号读 user_agent 拿到的是 DEFAULTS 里的通用 Chrome UA（非空）， 而不是空串 —— 这是刻意的（首次采集总得带个 UA）。测试断言要注意： 正确的断言是「新账号的 UA ≠ 实例级那一份」，而不是「新账号的 UA 为空」。

九、已知坑与红线

流式响应里不能复用 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 注释，否则注释里的示例路径会被误判）。

母模板里的 {% set %} 会静默覆盖子模板的同名变量

base.html 顶层原本写 {% set me = current_user() %}，用来渲染右上角的用户名。 但 current_user() 只回 {id, username, display_name, is_admin} 四个键 —— 而 profile.html 自己也用 me 接视图传来的完整用户行。

结果：母模板的 set 把子模板的 me 顶掉了，me.created_at 取不到， 个人中心渲染成「账号 admin · 注册于 · 最近登录 未登录」——不报错、不告警， 页面看起来只是"少了个时间"。

规则：母模板里给全站用的局部变量要起专门的名字（现在叫 cur）， 不要复用子模板可能用到的键。smoke.py 里有 3 条断言盯着这件事 （注册于 必须是真实日期、最近登录 不能是空占位、base.html 不得再出现 set me = ）。

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（215 项断言，离线） 模板残留、历史缺陷防回归 ①~⑭、多用户隔离 / 凭证保密 / 注册与验证码全链路、非管理员越权面全关死、全局键必须落在实例级、静态资源 404、class↔CSS 对账
3 tools/check_live.py（122 项断言，真实 HTTP） test_client 覆盖不到的：waitress、端口、cookie 往返、开放重定向、CSRF、验证码、安全响应头；--as 账号:密码 追加普通账号越权验收
4 Node DOM stub + vm.runInContext 跑大屏真实脚本 「页面聚合 == 独立算出的聚合」、切区间只发一次请求
5 tools/shots.py（Playwright 截图 + console/pageerror） 界面层。本轮最有价值的 bug（大屏全白）只有它抓到
附 tools/check_docs.py（文档层，不属于上面五层） 内部链接 / 跨文件锚点 / 图片引用 / 绝对路径泄漏 / 版本一致性 / 产品名硬编码。章节一重排，锚点就静默失效，Markdown 自己不报错，只有它抓得到。文档清单自动发现，不写死文件名 
python tools/smoke.py                                        # 1~2 层，随时跑
python tools/check_docs.py                                   # 文档层，改过 md 就跑
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 层在多用户下的两个约定：

  1. login(cli, uid) 只注入 uid 不够「假装」成谁 —— current_user() 每请求回查 users 表（为的是停用立即失效），所以 uname / adm 这些会话键改不了权限。 要测非管理员行为，必须真的在库里有一个普通账号。 smoke.py 会临时建一个（随机用户名，finally 里删掉），并在注册链路里临时再建一个。
  2. 「验证码答案没泄漏」这类断言要挑对判据：答案是 4 位随机大写串， 直接在页面里搜它只能说明「这次没撞上」。更可靠的是结构断言 —— 会话里只有 id、库里才有答案、同 id 二次校验必失败、图必须由独立接口下发 （页面里不出现 data:image）。

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

在新工单中引用 查看 Git Blame 复制永久链接