zhixing-system/.trellis/spec/backend/quality-guidelines.md

# 后端质量与测试

## 工具链

`zhixing-server/pyproject.toml` 固定 Python 3.12，使用 `uv` 管理环境和锁文件。质量门禁由以下配置定义：

- Ruff 格式化：100 列、双引号。
- Ruff lint：`B`, `E`, `F`, `I`, `SIM`, `UP`。
- Pyright：`strict`，检查 `src` 和 `tests`。
- Pytest：严格配置和严格 markers，测试目录为 `tests/`。

不要只在编辑器里运行局部检查；提交前至少执行：

```bash
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
```

## 代码规则

- 函数、方法和公开类使用完整类型标注；公共入口写清楚参数、返回值和边界原因，参照 `bootstrap/config.py`、`bootstrap/app.py`。
- HTTP 响应显式使用 Pydantic 模型和 `response_model`，不要返回随意拼接的 dict。
- 配置通过 `Settings` 注入，不直接读取进程环境；应用组合集中在 `create_app`。
- 领域代码不得依赖 FastAPI、持久化客户端或 infrastructure，符合 `modules/README.md` 的边界。
- 变更端点时同时更新行为测试和与之对应的前端契约。

## 测试形状

`tests/test_system_http.py` 使用 `TestClient(create_app())` 从真实应用组合出发，断言状态码和完整 JSON。新增路由优先采用相同的黑盒 HTTP 测试；只有纯领域逻辑才单独测试函数或对象。

## 禁止模式

- 不要提交未使用的 import、宽泛 `except Exception`、无类型的公共参数或绕过 Pyright 的 `Any`。
- 不要把秘密、完整环境变量、请求凭据写进响应或日志；系统状态端点只返回安全元数据。
- 不要引入没有真实使用场景的空数据库/日志抽象，或在尚未理解 bounded context 前创建业务模块。
- 不要为了让测试通过复制 `create_app` 的路由逻辑；测试应调用实际应用工厂。