wangchuanli/workbuddy-portal
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

chore: 项目定名为 workbuddy-portal，容器化并补齐文档体系

浏览代码 
## 项目定名
- 目录 wb_usage_portal → workbuddy-portal
- Python 包 wb_usage → workbuddy_portal（含 session cookie 名）
- 界面品牌统一为 WorkBuddy Portal；项目标识收敛到 config 单一来源

## 容器化
- Dockerfile：多阶段构建，依赖层与源码解耦；非 root(uid 1000)；内置健康检查
- docker-compose.yml：单服务 + 绑定挂载 data/logs + 日志轮转 + TZ
- docker/entrypoint.sh：幂等初始化 → exec serve（LF 行尾，已由 .gitattributes 锁定）
- docker/healthcheck.py：纯标准库探活 /login（slim 镜像无 curl）
- .dockerignore / .env.example；数据目录可用 WB_DATA_DIR 等环境变量覆盖

## 文档
- docs/USER-GUIDE.md    用户使用手册（含 9 张真实界面截图）
- docs/DEPLOYMENT.md    部署运维（Docker / 裸机 / 反代 / 备份 / 推 Gitea 注册表）
- docs/ARCHITECTURE.md  架构与设计说明（含已知坑与红线、验证体系）
- docs/API.md           接口参考（路径 / 参数 / 返回结构 / 错误码）
- docs/FAQ.md           常见问题；docs/CHANGELOG.md 变更日志

## 修复缺陷（8）
1. /records/export 必然 500：生成器在请求上下文销毁后才迭代，改用自建连接
2. 大屏页图表全白：相对路径把 echarts.min.js 解析成 /vendor/... → 404
3. /users 500：路由已注册但模板缺失
4. 明细页日期筛选失效：视图传 f.frm、模板读 f.from
5. 配置页维护按钮全死：调用了不存在的 WBU.bindMaint()
6. 审计只能看最近 40 条：LIMIT 写死
7. 明细页多跑一条无用 SELECT：day_list() 取了没人用
8. 登录页锁定阈值未从配置注入

## 安全加固
- 新增 safe_next()：拒绝 //evil.com 等协议相对 URL 的开放重定向
- 缺 CSRF 的写请求统一 400
- 默认开启云端 HTTPS 证书校验（ssl_verify=1）；Cookie 是账号凭证
- 登录失败计数表加上限与 TTL
- /logout 拆分为 POST(执行) + GET(仅提示)，防 <img src=/logout> 静默退出
- settings 内部簿记键 slot:* 读写两侧过滤，不再从 /api/settings 泄漏

## 内部质量与工具
- 设置项写时校验 + 读时兜底，杜绝「一个手滑的数字让采集整个跑不起来」
- 全局 ValueError → 400：手写 query string 不再暴露 500 页面
- CSV 导出改 csv.writer 流式写入（原手工拼串，字段含逗号会串列）
- bundle 明细加 20000 上限并回传 recordsTotal/recordsTruncated，不静默丢数据
- tools/smoke.py 离线回归 99 项；tools/check_live.py 真实 HTTP 56 项
- tools/shots.py Playwright 逐页截图 + JS 报错收集

## 验证
- compileall 通过；smoke 99/99；对容器实例 check_live 56/56；截图 0 JS 报错
- 容器内采集实测成功（trigger=startup 补跑：新增 11 条）
这个提交包含在：
wangchuanli
2026-09-14 14:55:50 +08:00
当前提交 86631ae7ab
共修改 58 个文件，包含 9409 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
docs/ARCHITECTURE.md
+382
查看文件
@@ -0,0 +1,382 @@
# 架构与设计说明
> 面向**开发 / 维护者**。解释这个系统为什么长这样，以及改动时不能碰的红线。
**目录**
- [一、分层与数据流](#一分层与数据流)
- [二、数据模型](#二数据模型)
- [三、采集：断点、去重、锁](#三采集断点去重锁)
- [四、调度：为什么不用 APScheduler](#四调度为什么不用-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` 层，
口径不可能不一致。
---
## 二、数据模型
```sql
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()`），
用户不会在配置页看到它们，也无法通过接口写入任意键。
---
## 三、采集：断点、去重、锁
### 断点续采
```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 分钟；计数表有上限（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`）
```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` 的范围再钳一次。
---
## 九、已知坑与红线
### 流式响应里不能复用 `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（大屏全白）只有它抓到 |
```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 层跑绿。**