wangchuanli
1bf961f6b3
将调度时刻、采集参数等实例级配置收归管理员，普通账号仅可维护本人 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。
573 行
28 KiB
Markdown
573 行
28 KiB
Markdown
# 架构与设计说明
|
||
|
||
> 面向**开发 / 维护者**。解释这个系统为什么长这样，以及改动时不能碰的红线。
|
||
|
||
**目录**
|
||
|
||
- [一、分层与数据流](#一分层与数据流)
|
||
- [二、数据模型](#二数据模型)
|
||
- [三、采集：断点、去重、锁](#三采集断点去重锁)
|
||
- [四、调度：为什么不用 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`、`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 步之前，则是为了让引用新列的索引一次就建成功。
|
||
|
||
---
|
||
|
||
## 三、采集：断点、去重、锁
|
||
|
||
### 断点续采
|
||
|
||
```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`、`/logs/tail`、`vacuum`。
|
||
|
||
两者之间还有一层「同一个页面、两种形态」：`/tasks` 与 `/config` 对普通账号**仍然可达**，
|
||
但渲染成**只读形态**（不给表单，换成只读表格 + 一句说明为什么只读），
|
||
写接口也会拒绝。页面形态与接口判断**共用 `config.writable_by()`**，
|
||
所以不存在「界面上没按钮、构造请求却能改」的空隙 —— 这是本次权限收敛刻意保证的性质。
|
||
|
||
**多租户隔离靠「显式传参」而不是「隐式全局」**，这是本节最重要的一条设计：
|
||
|
||
```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`（云端接口 + 注册策略 + 调度 + 采集参数）一律存**实例级 `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`）
|
||
|
||
```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`（共 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 自己不报错，只有它抓得到。文档清单自动发现，不写死文件名 |
|
||
|
||
```bash
|
||
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 层跑绿。**
|