# 开发约束

本文件适用于本仓库内的所有代码、测试、配置和文档变更。后续开发必须遵守以下约束；如与更深层目录中的 `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. 最终说明包含改动文件、验证命令与结果，以及未验证项（如有）。