## 项目（快速）指导 — 供 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 的迁移示例命令），我可以继续补充。请告诉我你希望强调的额外部分或需要澄清的地方。