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

后端开发规格

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

规格导航

规格	用途
目录与模块边界	包结构、bounded context 和导入边界
配置与运行时	Settings、应用工厂和部署环境
市场数据同步	Tushare qfq、PostgreSQL、CSV 快照和一次性 Job 契约
Tushare 当前上市股票范围	所有股票型功能统一只使用构建时 stock_basic(list_status=L) 母集
历史选股	selection bounded context、目标交易日、qfq 读取和信号结果契约
HTTP 契约	路由组合、响应模型和同源 API 路径
错误处理	当前 FastAPI 错误行为及跨层错误传递
质量与测试	Ruff、Pyright、pytest 及禁止模式

开发前检查

• 先阅读 docs/adr/0001-bounded-context-first-modular-monolith.md，确认新业务是否有清晰的语言和所有权边界。
• 涉及 Tushare 个股数据时先阅读 tushare-listed-stock-universe.md，所有新功能都必须从当前 L 股票母集继续缩小范围，禁止重新引入 D/P/G/UN。
• 先阅读目标上下文的 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 会执行完整前后端检查。