2026-03-13 09:45:53 +08:00
|
|
|
|
---
|
|
|
|
|
|
alwaysApply: true
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
# Backend Fastapi
|
|
|
|
|
|
|
2026-03-19 01:12:17 +08:00
|
|
|
|
## 架构规则
|
|
|
|
|
|
1. **`common/` / `utils/` / `shared/` / `helpers/` 禁止创建**：只有 truly cross-cutting 能力进 `core/`，业务 DTO/校验/错误码归 feature
|
|
|
|
|
|
2. **router 禁止操作 DB**：所有数据访问通过 repo，所有业务逻辑通过 service
|
2026-03-13 09:45:53 +08:00
|
|
|
|
3. **service 禁止 import adapter**：只依赖 port protocol，通过 DI 注入。代码中出现 `from adapters.xxx import ...` 即为违规
|
|
|
|
|
|
4. **feature 间禁止 import router**：跨 feature 调用通过 service 注入
|
|
|
|
|
|
5. **所有 schema 变更走 Alembic**：禁止直接 DDL
|
|
|
|
|
|
6. **新增 provider 必须实现 port protocol**：不得在 feature 中直接调用 SDK
|
2026-03-19 01:12:17 +08:00
|
|
|
|
7. **事务边界：repo 不提交，service 管事务**：`repo.py` 只做 `add/delete/query`，`commit/rollback` 由 service 或 UoW 统一执行。`get_async_db()` 不自动 commit
|
2026-03-13 09:45:53 +08:00
|
|
|
|
8. **port 边界不可打穿**：service 需要厂商增强能力时，必须扩充 port 或定义第二个窄 port，禁止直接引用 adapter 扩展方法
|
|
|
|
|
|
9. **quota 是独立 feature**：conversation、memoir、payment 如需配额检查，通过注入 `QuotaService`，不得直接 import quota 内部函数
|
|
|
|
|
|
10. **成功响应不强制包装**：`core/errors.py` 只统一错误响应格式 `{error_code, message, request_id}`，成功响应直接返回 Pydantic model / FileResponse / 原始结构
|
2026-03-19 01:12:17 +08:00
|
|
|
|
|
|
|
|
|
|
## 依赖管理（uv）
|
|
|
|
|
|
11. **依赖统一用 uv 管理**：禁止直接 `pip install`、禁止手动编辑 `pyproject.toml` 的 `[project.dependencies]` 或 `[dependency-groups]`
|
|
|
|
|
|
12. **新增依赖用 `uv add <pkg>`**，dev 依赖用 `uv add --dev <pkg>`，移除用 `uv remove <pkg>`
|
|
|
|
|
|
13. **`uv.lock` 必须纳入版本控制**：保证 CI 和本地环境精确一致
|
|
|
|
|
|
14. **安装环境统一用 `uv sync`**：开发环境 `uv sync --dev`，生产环境 `uv sync --no-dev`
|
|
|
|
|
|
15. **运行命令统一用 `uv run`**：如 `uv run pytest`、`uv run alembic upgrade head`、`uv run uvicorn ...`
|
2026-03-26 12:13:36 +08:00
|
|
|
|
16. 每次添加新代码时，一定要阅读已有部分代码，确保符合项目架构，pattern，loguru模式
|
|
|
|
|
|
17. **日志**：业务代码使用 `app.core.logging.get_logger(__name__)`（loguru `bind`）；禁止在 `app` 包内用 `import logging` 取业务 logger；仅第三方 SDK / 适配器层可对标准库 `logging` 做桥接（如 `InterceptHandler`）
|
