整合 backend/CLAUDE.md 与 frontend/CLAUDE.md 至 AGENTS.md

2026-08-21 21:12:37 +08:00
1 parent 887c1f449e
commit 6a65f3b582
@@ -1,93 +0,0 @@
-# 后端开发
-
-## 技术栈
-
-Python 3.12 + FastAPI + SQLAlchemy + Alembic + loguru + httpx + chromadb
-uv (用于虚拟环境和依赖管理)
-
-## 开发命令
-
-启动命令之前确保目前在backend目录下，并且已经激活了虚拟环境。默认本地开发使用 SQLite（aiosqlite）文件数据库，Redis、ChromaDB、Neo4j 暂不启用
-
-```bash
-uv venv -p 3.12                                       # 创建虚拟环境
-source .venv/bin/activate                             # 激活虚拟环境
-uv add <pkg>                                          # 添加依赖
-uv remove <pkg>                                       # 移除依赖
-uv run python -m app.main                            # 按 .env 中 BACKEND_HOST/BACKEND_PORT 启动服务
-uv run uvicorn app.main:app --reload --port 8000      # 手动指定端口启动服务（命令行 --port 会覆盖 .env）
-
-# 数据库迁移
-uv run alembic revision --autogenerate --rev-id=001 -m "描述"       # 生成迁移
-uv run alembic upgrade head                           # 执行迁移
-uv run alembic downgrade -1                           # 回滚一个版本
-uv run alembic current                                # 查看当前版本
-
-# 测试
-uv run pytest                                         # 运行测试
-```
-
-## 代码规范
-
-在__init__文件中可以将模块内的类、函数等导出，方便其他模块导入使用
-遵循 PEP 8 代码风格指南和更加pythonic的开发方式
-遵循单一职责原则，每个文件、类、函数等都要只干一件事
-使用 loguru 进行日志记录，避免使用 logging 模块
-使用 Alembic 进行数据库迁移，禁止手动修改数据库表结构，文件命名以迁移版本号开头，例如 001_initial.py；迁移必须优先兼容 SQLite，涉及 PostgreSQL 专用 DDL 时必须提供 SQLite 分支或显式跳过
-使用alembic init alembic命令初始化迁移环境，使用命令生成相关的迁移文件,不能直接生成迁移文件
-使用 httpx 进行异步 HTTP 请求，禁止在路由函数内直接使用同步数据库会话或 httpx 客户端
-所有的测试代码都写在tests目录下，测试文件命名以test_开头，测试函数命名以test_开头
-所有敏感信息（如密钥、Token、数据库密码）必须通过环境变量或配置文件管理，禁止硬编码到代码中
-
-## 目录结构与分层边界
-
-后端采用务实分层，完整设计见 [后端分层架构设计](../docs/architecture/backend-layering-design.md)，本节为开发速查。
-
-### 顶层目录职责
-
-| 目录 | 职责 |
-| --- | --- |
-| `api/v1` | `endpoints/`（路由）+ `deps.py`（依赖注入），只做 参数校验 → 调用 → 转响应 |
-| `schemas` | Pydantic 请求/响应（API 边界） |
-| `application` | 用例编排（跨多模块复杂流程） |
-| `services` | 薄业务服务（CRUD 编排） |
-| `modules` | 九枢领域逻辑（★ 纯函数/数据结构，禁止 IO） |
-| `models` | SQLAlchemy ORM |
-| `repositories` | 数据访问（返回 ORM，不暴露 Query/Session） |
-| `ai_provider` | 统一模型接入层（chat/multimodal/embedding/rerank） |
-| `integrations` | 外部系统适配（沙箱/向量/图/对象存储） |
-| `core` | 配置集中（`core/config/`）+ 日志/错误/安全/ID/时间 |
-| `db` | 数据库会话与初始化 |
-
-### 分层硬规矩
-
- `modules/` 禁止 import `repositories` / `db` / `integrations` / `ai_provider` / `httpx` / `sqlalchemy`——一旦需要 IO，立即上移到 `services` 或 `application`。
- 路由函数禁止直接 `Depends(get_session)` 或写业务逻辑——改为注入 usecase / service。
- `repositories/` 返回 ORM，禁止把 Query / Session 暴露到上层。
- 模型能力（对话/多模态/嵌入/重排）一律进 `ai_provider/`；存储/检索/外部接入进 `integrations/`。
- 配置一律进 `core/config/`，业务目录不持有 `settings.py` / `config.py`。
- `.env` 只放项目根目录，`Settings` 以绝对路径 `_env_file` 初始化，不使用 `python-dotenv`。
-
-## 代码审查
-
-开发完成后必须使用以下命令进行代码检查：
-
-```bash
-uv run ruff check         # Lint 检查
-uv run ruff check --fix   # 自动修复部分代码风格问题
-uv run pre-commit run --all-files  # 可选：完整运行 CI 级检查（包括类型检查）
-```
-
-确保没有任何 lint 错误后再提交。
-
-## 绝对禁止事项
-
-直接修改 pyproject.toml 文件添加或者移除依赖（必须使用 uv add/remove 命令）
-在路由函数内直接使用同步数据库会话（必须通过 Depends 注入）
-在路由函数内直接 async with httpx.AsyncClient()
-使用 logging 模块（统一用 loguru）
-硬编码密钥、Token、数据库密码到代码
-手动创建/修改数据库表结构（必须使用 Alembic 迁移）
-在 `modules/` 中 import `repositories` / `db` / `integrations` / `ai_provider` / `httpx` / `sqlalchemy`（领域层禁止 IO，需要 IO 时上移到 services/application）
-在业务目录（`ai_provider` / `integrations` 等）中持有 `settings.py` / `config.py`（配置统一进 `core/config/`）
-使用 `python-dotenv`（`.env` 由 `core/config` 以绝对路径 `_env_file` 加载）