# 后端目录与模块边界

## 当前布局

```text
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`：

```text
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`