zhixing-system/.trellis/spec/backend/directory-structure.md

后端目录与模块边界

当前布局

zhixing-server/
├── src/zhixing_server/
│   ├── bootstrap/                 # 应用工厂和进程配置
│   │   ├── app.py
│   │   └── config.py
│   ├── interfaces/http/           # 跨上下文 HTTP 路由目录
│   │   ├── router.py              # /api/v1 路由目录
│   │   └── system.py              # /healthz、/api/v1/system/status
│   ├── modules/                   # 业务 bounded context（目前为空）
│   │   └── README.md
│   ├── shared/                    # 没有特定业务所有权的小型基础能力
│   ├── main.py                    # ASGI 入口，只导出 app
│   └── __init__.py
└── tests/                         # 按行为/入口组织的 pytest 测试

zhixing-server/src/zhixing_server/bootstrap/app.py:create_app 负责组合 FastAPI 应用，main.py 只执行 app = create_app()。不要把应用组合、环境读取或业务逻辑塞进 main.py。

新增业务上下文

只有在领域语言和所有权边界明确后，才在 modules/ 下创建上下文。推荐形状来自 zhixing-server/src/zhixing_server/modules/README.md：

modules/<bounded_context>/
├── domain/           # 实体、值对象、领域服务、端口
├── application/      # 用例和编排
├── infrastructure/   # 存储及外部系统适配器
└── presentation/     # HTTP 或消息驱动的交付适配器

domain 层不能导入 FastAPI、持久化客户端或 infrastructure 适配器。上下文内的 presentation 负责把输入转换成用例需要的类型；顶层 interfaces/http 只承载跨上下文的运维入口和路由目录。

命名与导入

• Python 包、模块和函数使用 snake_case；测试文件使用 test_*.py，例如 tests/test_system_http.py。
• 对外公开的类、响应模型和函数应有类型标注与文档字符串，参照 bootstrap/config.py 和 interfaces/http/system.py。
• shared/ 只能放跨上下文且无业务归属的原语；不要把某个上下文的领域规则放进去。
• 避免新建全局 services/、repositories/ 或 utils/ 目录来绕过上下文边界。

参考实现

• 应用组合：zhixing-server/src/zhixing_server/bootstrap/app.py
• 路由目录：zhixing-server/src/zhixing_server/interfaces/http/router.py
• 运维/系统端点：zhixing-server/src/zhixing_server/interfaces/http/system.py
• 当前 HTTP 契约测试：zhixing-server/tests/test_system_http.py