workbuddy-portal/CONTRIBUTING.md

贡献指南（Contributing）

感谢你有兴趣改进 WorkBuddy Portal。这是一个单进程 Flask + SQLite 的轻量项目， 刻意保持了很小的依赖面与很平的目录结构——请先花两分钟读完本文，你的改动会更顺利被接受。

---

一、开发环境

项	要求
Python	3.13（Docker 镜像用的就是 3.13-slim；3.11+ 一般也可）
操作系统	Linux / macOS / Windows 均可，但注意下面「Windows 特有坑」一节
依赖	pip install -r requirements.txt
可选	Playwright + Chromium（只有跑界面截图才需要）

起步：

git clone <你的仓库地址> workbuddy-portal
cd workbuddy-portal
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

python manage.py init                              # 建表 + 建管理员（默认 admin/admin123）
python manage.py serve --port 8848                 # 或 docker compose up -d --build

二、用示例数据开发，别用真实数据

tools/demo_data.py 会生成一份完全合成的数据集（假模型名、假 Prompt、偏斜的积分分布）， 放在 data/demo/ 下（该目录已在 .gitignore 内）：

python tools/demo_data.py                          # 默认 data/demo，管理员 admin/admin123
WB_DATA_DIR=$PWD/data/demo python manage.py serve --port 8849 --no-scheduler

这样你既能有一个「看起来像真的」的界面来调试，也不会把任何真实用量带进仓库或截图。

三、改动前请先跑一遍验证

项目有一层层递进的验证，代价从低到高，改完至少跑到第 2 层：

#	命令	覆盖什么	需要什么
1	python -m compileall -q workbuddy_portal manage.py tools	语法	—
2	python tools/smoke.py	99 项离线断言：全页面只读渲染、模板残留检测、历史缺陷防回归、静态资源、CSS 类名对账	无（用 Flask test_client，不启服务）
3	python tools/check_live.py --base http://127.0.0.1:8848	56 项真实 HTTP 断言，含登录/CSRF/开放重定向	一个运行中的服务
4	python tools/shots.py --base http://127.0.0.1:8849	登录后逐页截图并收集 console/pageerror	Playwright + Chromium
5	docker compose up -d --build && docker compose ps	容器化路径	Docker

tools/shots.py 是最有价值的一层：项目曾经出过「大屏整页全白」的 bug， 只有它抓到了（smoke 与 check_live 都放过了）。改前端务必跑。

这三支脚本都会打印 RESULT: ok=N fail=0，fail 不为 0 时退出码是 1，可直接接进 CI。

四、必须遵守的几条不变量

这些是踩过坑之后定下来的，破坏它们会在生产上以很隐蔽的方式出问题：

1. SQLite 只允许一个写者。 任何采集动作都要走 collect._Lock()（data/collect.lock）。 不要起多个带调度的进程；多实例部署时其余实例设 WB_DISABLE_SCHEDULER=1。
2. 列表类接口默认不返回 prompt 全文。 它占原始体积约 80%。只有 /api/top 与 /api/records 带，且都做截断。新增接口请沿用这个约定。
3. 两种字段命名契约不要互相「统一」：/api/bundle 用短键（d/c/k/m/cl/t/px，大屏页依赖）， /api/records 用可读全名。改错会让大屏静默渲染成空白。
4. 流式响应里不要复用 db.get_db()。 Flask 在响应迭代开始前就会关掉请求上下文里的连接， 生成器一读库就 Cannot operate on a closed database。要在生成器内部自建连接并 finally 关闭。
5. Docker 部署用命名卷，不要退回绑定挂载。 Windows + Docker Desktop 走 9p， 宿主进程碰过 WAL 库之后容器会永久打不开数据库（详见 docs/ARCHITECTURE.md）。
6. .gitignore 不支持行尾注释——规则后跟 # 注释 会让整行失效。注释必须单独占一行， 改完用 git check-ignore -v <file> 逐条确认命中。

五、代码风格

• 遵循 PEP 8；行宽 100。
• 注释与文档字符串用中文，说明「为什么这么做」而不是「这行在做什么」。
• 提交前用 python -m compileall 与 python tools/smoke.py 自查。
• 不要引入新的第三方依赖，除非有充分理由并在 PR 里说明——这个项目的卖点之一就是依赖少。 如果确实新增了，请同步登记到 THIRD-PARTY-NOTICES.md。

六、提交与 PR

提交信息用 Conventional Commits，一句话说清「改了什么」即可，正文可写动机：

fix(docker): 数据改用 Docker 命名卷，修容器打不开数据库的问题
feat(api): 新增 /api/export 支持按筛选条件导出 CSV
docs: 补充反向代理部署示例

PR 请包含：

• 动机：解决什么问题，或复现步骤
• 改动：涉及哪些文件、有没有破坏性变更
• 验证：贴出 smoke / check_live 的 RESULT 行；改前端再贴截图脚本的输出
• 若改动影响数据口径（聚合、去重、时区），请额外写一份独立聚合与之比对， 不要只靠肉眼看页面

七、Windows 特有坑（若你在 Windows 上开发）

• 宿主 Windows 进程访问过 data/usage.sqlite 后，容器内会打不开同一个库。 用命名卷部署时，宿主侧跑 CLI 请一律走 docker compose exec portal python manage.py …。
• Git 的 /tmp 会被解析成 C:\tmp，git commit -F /tmp/msg.txt 会失败——用仓库内路径。
• 本机若开着 HTTP 代理，curl http://127.0.0.1:… 会被代理拦成 502，探测本地服务要加 --noproxy '*'。
• 行尾：仓库用 .gitattributes 锁死 eol=lf，docker/*.sh 若带 CRLF 会在容器里报 exec format error。

---

有任何不确定的地方，先在 Issue 里问，比写完再返工更省事。