docs: 添加重构相关文档。添加cursor rules

This commit is contained in:
Kevin
2026-03-13 09:45:53 +08:00
parent e0f546dff0
commit 16ae355510
4 changed files with 1163 additions and 0 deletions

View File

@@ -0,0 +1,24 @@
---
alwaysApply: true
---
# Backend Fastapi
## 架构规则
1. **`common/` / `utils/` / `shared/` / `helpers/` 禁止创建**:只有 truly cross-cutting 能力进 `core/`,业务 DTO/校验/错误码归 feature
2. **router 禁止操作 DB**:所有数据访问通过 repo所有业务逻辑通过 service
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
7. **事务边界repo 不提交service 管事务**`repo.py` 只做 `add/delete/query``commit/rollback` 由 service 或 UoW 统一执行。`get_async_db()` 不自动 commit
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 / 原始结构
## 依赖管理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 ...`

View File

@@ -0,0 +1,5 @@
---
alwaysApply: true
---
Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.