workbuddy-portal/docs/ARCHITECTURE.md

# 架构与设计说明

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

**目录**

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

---

## 一、分层与数据流

```
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` 必须由调用方一路显式传下去
（见 [七、安全模型](#七安全模型)），所以「忘了过滤」在类型层面就写不出来。

---

## 二、数据模型

```sql
-- 多用户布局：所有按账号隔离的表都以 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`、系统迁移审计）；在 `usage_records` 里
是「尚未归属」的兜底值，正常不会出现。

索引全部以 `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 步之前，则是为了让引用新列的索引一次就建成功。

---

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

### 断点续采

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

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

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

```sql
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`），并带重入保护：

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

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

---

## 四、调度：为什么不用 APScheduler

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

```python
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 会把浏览器打死。

所以：

```python
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/tail`、`vacuum` 要管理员。

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

```python
# 每个公开函数都把 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` 只有管理员能改 |
| **凭证不回落** | `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`）

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

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

**读时兜底**

```python
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`（`api_base` / `api_path` / `allow_register` / `register_max_per_ip` /
`captcha_policy` / `captcha_length`）在读写两侧都被强制折算到 `user_id = 0`，
所以它们天然只有一份，非管理员改不了。

有个**容易误判**的细节：`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`（**165 项断言**，离线） | 模板残留、历史缺陷防回归 ①~⑭、**多用户隔离 / 凭证保密 / 注册与验证码全链路**、静态资源 404、class↔CSS 对账 |
| 3 | `tools/check_live.py`（**83 项断言**，真实 HTTP） | `test_client` 覆盖不到的：waitress、端口、cookie 往返、开放重定向、CSRF、验证码、安全响应头 |
| 4 | Node DOM stub + `vm.runInContext` 跑大屏真实脚本 | 「页面聚合 == 独立算出的聚合」、切区间只发一次请求 |
| 5 | `tools/shots.py`（Playwright 截图 + console/pageerror） | **界面层**。本轮最有价值的 bug（大屏全白）只有它抓到 |

```bash
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 层在**多用户**下的两个约定：

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

**改动前先读 [九、已知坑与红线](#九已知坑与红线)，改完先把第 2 层跑绿。**