guzhi/.github/copilot-instructions.md

项目（快速）指导 — 供 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）:

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