开发文档
面向贡献者和团队工程师。文档按 Diátaxis 四象限组织：起步（跑通） / 概念（理解） / How-to（任务） / 故障排查（问题）。
5 分钟跑通
bash
git clone https://github.com/yyq19990828/ai-annotation-platform
cd ai-annotation-platform
cp .env.example .env
docker compose up -d
# API: http://localhost:8000 Web: http://localhost:5173详见 本地开发。
我该改哪里？
| 任务 | 入口 |
|---|---|
| 加一个后端 API | How-to: 新增 API 端点 |
| 加一个前端页面 | How-to: 新增前端页面 |
| 改数据库结构 | How-to: Alembic 迁移 |
| 写 / 调试后台任务 | How-to: 调试 Celery |
| 理解项目模块 | 概念：项目模块 |
| 理解任务模块 | 概念：任务模块 |
| 理解批次模块 | 概念：批次模块 |
| 理解派题与锁 | Scheduler 与派题 · Task Lock |
| 理解状态流 | 状态机总览 |
| 理解横切机制 | 计数与派生字段 · 审计与通知 |
| 理解整体架构 | 概念：架构地图 |
| 排查运行时问题 | 故障排查总览 |
| 查协议规范 | ML Backend 协议 · WebSocket 协议 · 视频帧服务 |
项目仓库结构
apps/ 下两个子项目：
| 子项目 | 语言 | 框架 | 入口 |
|---|---|---|---|
apps/api | Python 3.11+ | FastAPI + SQLAlchemy + Alembic + Celery | app/main.py |
apps/web | TypeScript | React + Vite + Zustand + TanStack Query | src/main.tsx |
docs-site/ 是你正在看的这个 VitePress 文档站。