kairee
e2cdf997af
Implement P0 of the reaction dashboard: config loading with hot reload, SQLite migrations with backups, single-writer queue, read-only Bilibili fav client, folder import/diff sync, invalid-resource handling, blacklist seed, scheduler, and JSON redacted logging. Includes offline unit and transport-level contract tests; all existing and new tests pass.
81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 开发约束
|
|
|
|
本文件适用于本仓库内的所有代码、测试、配置和文档变更。后续开发必须遵守以下约束；如与更深层目录中的 `AGENTS.md` 冲突，以更深层文件为准。
|
|
|
|
## 1. 测试是实现的一部分
|
|
|
|
- 新增或修改任何方法、函数、类方法或业务逻辑时，必须同步新增或更新自动化测试。
|
|
- **不依赖外部接口、文件系统、时钟、随机数或进程环境的纯函数**必须有可靠的单元测试，覆盖：
|
|
- 正常输入与预期输出；
|
|
- 边界值；
|
|
- 空值、异常值或非法输入（如函数设计需要处理）；
|
|
- 已修复缺陷对应的回归用例。
|
|
- 不得以“仅人工运行验证”“代码简单”或“调用方已有测试”为由省略纯函数测试。
|
|
- 测试必须确定、可重复、离线运行；不得访问真实 B 站、Telegram 或其他外部服务。
|
|
|
|
## 2. 外部 API 调用必须使用契约一致的 Mock 验证
|
|
|
|
- 所有依赖外部 HTTP/API 接口的方法或函数必须有自动化测试。
|
|
- 测试中的 Mock 响应必须与实际接口的返回格式一致，包括：
|
|
- 顶层字段和嵌套结构；
|
|
- 字段类型（例如整数、字符串、数组、`null`）；
|
|
- 成功响应的 `code` / `data` 等包装层；
|
|
- 项目需要处理的失败响应、缺字段、空数组和异常响应。
|
|
- Mock 数据应优先来自已记录的真实接口样本，并完成脱敏；不得为方便测试而编造与接口契约不一致的简化结构。
|
|
- 每个 API 客户端至少覆盖：
|
|
- 成功响应的解析与字段映射；
|
|
- API 业务错误码；
|
|
- HTTP/网络错误；
|
|
- 本项目依赖的边界情形（例如 B 站 `infos` 静默缺失资源、`view` 返回 `-404`、鉴权失效）。
|
|
- Mock 应替换网络传输边界（HTTP client / transport），而不是替换正在测试的业务解析与错误处理逻辑。
|
|
|
|
## 3. 测试执行要求
|
|
|
|
- 所有测试命令必须通过 `uv run` 在项目锁定的 Python 3.14 环境中运行。
|
|
- 提交前至少运行受改动影响的测试；涉及共享模块、配置、数据库迁移、API 客户端或调度逻辑时，必须运行完整测试集。
|
|
- 测试失败时不得提交“已验证”的实现；应先修复代码或更新正确的测试预期。
|
|
- 测试命令、结果和未执行测试的原因必须在最终开发说明中如实记录。
|
|
|
|
当前已有测试示例：
|
|
|
|
```powershell
|
|
uv run python tests/test_auth.py
|
|
uv run python tests/test_moves.py
|
|
```
|
|
|
|
新增测试应按功能放入 `tests/`，命名清晰，并保持可由 `uv run python <测试文件>` 直接执行；如后续引入测试框架，必须同时更新 `pyproject.toml`、`uv.lock` 与相关文档。
|
|
|
|
## 4. 阶段性本地 Git 提交
|
|
|
|
- 完成一个可独立验证的关键步骤后，必须先运行对应测试，再创建一次**本地 Git 提交**；不得推送远程仓库，除非用户明确要求。
|
|
- 关键步骤包括但不限于：
|
|
- 一个完整的 API 客户端或认证能力；
|
|
- 一个数据库迁移或数据模型阶段；
|
|
- 一个调度任务；
|
|
- 一个端到端业务动作（如候选收藏、忽略、拉黑）；
|
|
- 一个完整页面/API 范围；
|
|
- 重要缺陷修复或安全修复。
|
|
- 提交前检查工作区，确保不包含凭据、Cookie、数据库、日志、缓存、构建产物或其他运行期文件。
|
|
- 提交信息使用简洁的 Conventional Commits 风格，例如：
|
|
|
|
```text
|
|
feat(sync): add favorite-folder import
|
|
fix(auth): preserve device fingerprint cookies
|
|
test(api): cover missing favorite resource responses
|
|
docs: document local uv workflow
|
|
```
|
|
|
|
- 若当前目录尚未初始化为 Git 仓库，或 Git 用户身份未配置，应向用户说明这一阻塞项；**不得未经明确授权自行执行 `git init`、配置 Git 身份或创建提交。**
|
|
- 不得执行会丢失用户工作区内容的 Git 命令，例如 `git reset --hard`、`git checkout -- .` 或强制清理未跟踪文件，除非用户明确要求。
|
|
|
|
## 5. 完成定义
|
|
|
|
一个开发任务只有在以下条件满足后才可视为完成：
|
|
|
|
1. 实现与文档/需求口径一致；
|
|
2. 新增或变更的纯函数已有可靠离线单元测试；
|
|
3. API 相关逻辑已有契约一致的 Mock 测试；
|
|
4. 受影响测试已通过；
|
|
5. 关键步骤已经创建本地 Git 提交，或已明确记录无法提交的原因；
|
|
6. 最终说明包含改动文件、验证命令与结果，以及未验证项（如有）。
|