本地开发

面向贡献者的本地开发环境搭建。

前置要求

• Python 3.13+（通过 uv 管理）
• Node.js 20+ 与 pnpm
• MySQL 8.0（或用 Docker 启动）
• Docker & Docker Compose（可选，一键起依赖）

后端

cd backend

# 安装依赖
uv sync

# 应用数据库迁移
uv run alembic upgrade head

# 创建超管(按需；也可以首次打开前端时在 /setup 向导中创建)
uv run python scripts/create_superuser.py

# 启动开发服务器(热重载)
uv run fastapi dev app/main.py

后端默认监听 http://localhost:8000，API 文档在 /docs。首次登录后会自动进入引导页创建第一个学科。

前端

cd frontend

# 安装依赖
pnpm install

# 启动开发服务器(将 /api 代理到后端)
pnpm dev

前端开发服务器会把 /api 代理到后端，无需额外跨域配置。

文档站（本仓库）

cd docs
pnpm install
pnpm docs:dev

常用命令

场景	命令
新增后端依赖	uv add <package>
生成迁移	uv run alembic revision --autogenerate -m "msg"
应用迁移	uv run alembic upgrade head
运行脚本	uv run python scripts/<script>.py
构建前端（桌面打包用）	pnpm generate

更多约定见 后端约定 与 前端约定。