55 lines
4.2 KiB
Markdown
55 lines
4.2 KiB
Markdown
## 项目（快速）指导 — 供 AI 编码代理使用
|
||
|
||
下面的要点帮助你快速理解并在本代码库中高效工作。保持简短、具体并以可执行示例为主。
|
||
|
||
- 项目类型：FastAPI 后端 (Python 3.11) + Vue3/Vite 前端（目录 `web/`）。后端使用 Tortoise ORM（配置在 `app/settings/config.py`），前端用 pnpm/vite。
|
||
|
||
- 快速启动（后端）：在项目根目录
|
||
- 建议 Python venv，然后安装依赖：`pip install -r requirements.txt`（或使用项目 README 中的 uv/uvenv 过程）。
|
||
- 启动：`python run.py`。这会通过 `uvicorn` 运行 `app:app`（见 `run.py`），开启 `reload=True`，OpenAPI 在 `/docs`。
|
||
|
||
- 快速启动（前端）：进入 `web/`，使用 pnpm（或 npm）安装并运行：`pnpm i`，`pnpm dev`。
|
||
|
||
- 后端关键入口
|
||
- `run.py`：应用启动脚本，设置 uvicorn 日志格式并运行 `app:app`。
|
||
- `app/__init__.py`：创建 FastAPI app（调用 `core/init_app.py` 中的注册函数）：init 数据、注册中间件、异常处理与路由（路由前缀为 `/api`）。
|
||
- `app/core/init_app.py`（注意：此文件包含启动时的路由/中间件/异常注册逻辑，请优先阅读它来理解请求生命周期）。
|
||
|
||
- 重要配置点
|
||
- `app/settings/config.py`：使用 Pydantic Settings，包含 `TORTOISE_ORM`（默认 SQLite，db 文件在项目根 `db.sqlite3`）、JWT、SECRET_KEY、CORS 等。修改环境变量即可覆盖设置。
|
||
- `app/utils/api_config.py`：提供 `api_config` 全局实例，用来存放第三方 API（示例：`chinaz`、`xiaohongshu`）。常用方法：`api_config.get_api_key(provider)`、`get_endpoint_config(provider, endpoint)`、`add_endpoint(...)`、`save_config()`。
|
||
|
||
- 路由与模块约定
|
||
- API 版本化：`app/api/v1/` 下放置 v1 接口。路由统一由 `core/init_app.py` 通过 `register_routers(..., prefix='/api')` 注册。
|
||
- 控制器（HTTP handlers）位于 `app/controllers/`，数据模型在 `app/models/`，Pydantic schemas 在 `app/schemas/`。
|
||
|
||
- 数据库与迁移
|
||
- 使用 Tortoise ORM，`TORTOISE_ORM` 在 `app/settings/config.py`。项目把 `aerich.models` 列入 models（见配置），repository 中存在 `migrations/` 文件夹。若需变更模型，按项目现有工具链（如 aerich）执行迁移；在不确定时，先检查 `pyproject.toml`/`requirements.txt` 是否包含 aerich 并复核 README。
|
||
|
||
- 日志与持久化
|
||
- 日志目录：`app/logs`（可在 `settings.LOGS_ROOT` 找到）。运行时可根据 `run.py` 中的 LOGGING_CONFIG 调整格式。
|
||
|
||
- 第三方 API 集成（示例）
|
||
- `api_config` 示例用法（Python）:
|
||
```py
|
||
from app.utils.api_config import api_config
|
||
cfg = api_config.get_endpoint_config('xiaohongshu', 'xiaohongshu_note_detail')
|
||
base = api_config.get_base_url('xiaohongshu')
|
||
key = api_config.get_api_key('xiaohongshu')
|
||
```
|
||
- 环境变量覆盖：CHINAZ_API_KEY、XIAOHONGSHU_TOKEN、EXAMPLE_API_KEY 等会被 `api_config` 或 settings 读取。
|
||
|
||
- 编辑/贡献约定（可自动推断的现有模式）
|
||
- 新增 API：在 `app/api/v1/...` 添加路由模块，控制器放 `app/controllers/`，schema 放 `app/schemas/`，并在 `core/init_app.py` 中确保路由被注册。
|
||
- 新增模型：更新 `app/models/` 并生成迁移（项目使用 Tortoise + aerich 风格）。先检查 `migrations/models` 是否有对应变更。
|
||
|
||
- 调试提示
|
||
- 本地运行时使用 `python run.py`（reload=True），然后访问 `http://localhost:9999/docs` 查看 OpenAPI，确认路由/依赖注入是否按预期工作。
|
||
- 常见故障点：环境变量未设置（导致 API keys 丢失）、Tortoise 连接配置错误（检查 `TORTOISE_ORM.connections`）、以及中间件注册顺序会影响异常处理。
|
||
|
||
- 其它注意事项（小而具体）
|
||
- 前端以 `/api` 为后端前缀，修改后端接口时请同步前端 `web/src/api` 的调用。
|
||
- `app/utils/api_config.py` 会在模块导入时创建 `api_config` 单例；修改该文件时注意导入时机（不要在模块顶层做阻塞网络调用）。
|
||
|
||
如果需要我把 README 中的启动说明转成更精确的 shell 命令（或添加 aerich 的迁移示例命令），我可以继续补充。请告诉我你希望强调的额外部分或需要澄清的地方。
|