zhixing-system/.trellis/spec/backend/index.md

后端开发规格

后端是 Python 3.12 + FastAPI 的单体服务。当前代码只包含启动组合、环境配置、运维端点和 system HTTP 切片；业务 bounded context 尚未创建。新增后端代码应先确认它属于启动边界、共享基础设施、HTTP 入口还是某个明确的 bounded context。

规格导航

规格	用途
目录与模块边界	包结构、bounded context 和导入边界
配置与运行时	Settings、应用工厂和部署环境
HTTP 契约	路由组合、响应模型和同源 API 路径
错误处理	当前 FastAPI 错误行为及跨层错误传递
质量与测试	Ruff、Pyright、pytest 及禁止模式

开发前检查

• 先阅读 docs/adr/0001-bounded-context-first-modular-monolith.md，确认新业务是否有清晰的语言和所有权边界。
• 先阅读目标上下文的 modules/<bounded_context>/README.md（如已存在），再决定 domain、application、infrastructure、presentation 的位置。
• 变更 HTTP 字段时同时检查 zhixing-server/tests/、前端 feature API 类型以及 docs/adr/0002-use-a-same-origin-browser-api.md。
• 不要为了“未来可能需要”创建空的数据库、服务或日志层；当前仓库没有这些实现。

质量检查

在 zhixing-server/ 下运行：

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

根目录 ./dev.sh check 和 ./dev.sh test 会执行完整前后端检查。