AI Coding Full Stack Template

AI Coding 全栈项目模板，面向前端或后端工程师向全栈方向发展。基于 FastAPI 官方全栈模板整理：后端保留 FastAPI、Docker、测试、OpenAPI 等成熟工程能力；前端调整为团队更熟悉的 React Router、SWR、Ant Design 和自动生成 API client。

适用场景

• 快速启动带登录、用户管理、示例资源、邮件能力的管理台全栈项目。
• 单仓、约定清晰，配合 OpenAPI 自动生成 client，降低跨栈协作成本。
• 作为 Codex / Cursor 等 AI Coding 的稳定项目骨架，并配备 AI Coding 工作流。

技术栈

层	技术
后端	FastAPI、SQLModel / SQLAlchemy、PostgreSQL、Alembic、Pydantic Settings、JWT、Pytest、Ruff、Mypy
前端	React、TypeScript、Vite、React Router、SWR、Ant Design、Playwright
工程化	Docker Compose、Traefik、Mailcatcher、Adminer、Bun workspace、uv workspace、OpenAPI 自动生成 client

前置要求

• Docker Desktop（跑全栈或后端依赖）
• 本地前端热更新：Node.js 18+（通过 npx bun 调用，无需全局安装 Bun）
• 可选：本机 uv（直接跑后端测试或 pre-commit）

首次克隆后，确认根目录 .env 已配置（模板通常已包含本地默认值）。

快速启动

安装并启动 Docker Desktop 后，在仓库根目录执行：

docker compose up -d --build

本地地址

服务	地址
前端管理台	http://localhost:5173
后端 API	http://localhost:8000
API 文档	http://localhost:8000/docs
数据库管理 (Adminer)	http://localhost:8080
邮件收件箱 (Mailcatcher)	http://localhost:1080
Traefik 面板	http://localhost:8090

默认管理员（来自根目录 .env 的 FIRST_SUPERUSER / FIRST_SUPERUSER_PASSWORD）：

admin@example.com
changethis

Adminer 登录（打开 http://localhost:8080 后按下列填写；值来自根目录 .env 的 POSTGRES_*）：

字段	填写值	说明
System	PostgreSQL	默认即可
Server	db	Docker 网络内数据库服务名，不是 localhost
Username	postgres	POSTGRES_USER
Password	changethis	POSTGRES_PASSWORD
Database	app	POSTGRES_DB；可留空，登录后再选库

若你改过 .env 里的 POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB，请用你自己的值。Server 在通过 Adminer 容器访问时始终填 db。

常用操作

docker compose down              # 停止服务
docker compose down -v           # 停止并清空数据库
docker compose build --no-cache frontend && docker compose up -d frontend  # 前端仍是旧页面时重建

本地开发

推荐方式：后端及依赖走 Docker，前端走本机 Vite（热更新更快）。

# 1. 启动后端、数据库、邮件、Adminer
docker compose up -d db mailcatcher adminer backend

# 2. 安装依赖并启动前端
npx --yes bun@1.3.12 install
npx --yes bun@1.3.12 run --filter frontend dev --host 0.0.0.0

前端 API 地址读取 frontend/.env 或构建参数中的 VITE_API_URL，本地通常为：

VITE_API_URL=http://localhost:8000

docker compose watch 更适合后端开发。前端容器是 Nginx 静态服务，展示的是构建后的 dist；日常前端开发请优先使用 Vite。

更细的后端 / 前端本地流程见 backend/README.md、frontend/README.md。

常用命令

# 前端
npx --yes bun@1.3.12 run --filter frontend dev
bash scripts/check-frontend.sh        # lint + build
bash scripts/check-frontend.sh --e2e  # lint + build + Playwright（需栈已启动）

# 后端
cd backend && uv sync && cd ..
bash scripts/check-backend.sh         # ruff + mypy + pytest

# 全栈
bash scripts/test.sh

# 后端改接口后，更新前端生成 client
bash scripts/generate-client.sh

# 校验生成产物与 migration 是否同步（pre-commit / CI 也会跑）
bash scripts/check-generated-sync.sh

数据库迁移

docker compose exec backend alembic revision --autogenerate -m "Add xxx"
docker compose exec backend alembic upgrade head

可选：安装 pre-commit

cd backend && uv sync && uv run pre-commit install

质量检查与 CI

仓库通过统一脚本保证本地与 CI 一致（见 .gitlab-ci.yml）：

• scripts/check-generated-sync.sh — 禁止手改 frontend/src/client；models.py 表结构变更必须带 Alembic migration
• scripts/check-backend.sh — Ruff、Mypy、Pytest
• scripts/check-frontend.sh — Biome、构建、可选 E2E

目录结构

.
├── backend/                 # FastAPI 后端（见 backend/README.md）
├── frontend/                # React 管理台（见 frontend/README.md）
├── scripts/                 # 检查、测试、生成 client 等根级脚本
├── .trellis/spec/           # 项目约定唯一事实来源（AI / 人工开发均以此为准）
├── doc/                     # 架构说明、AI Coding 工作流等文档
├── compose.yml              # 基础 Docker Compose
└── compose.override.yml     # 本地开发覆盖

前端关键路径：src/pages（页面）、src/features/<domain>/hooks.ts（SWR）、src/client（生成代码，不手改）、src/app/App.tsx（路由）。

后端关键路径：app/api/routes/（接口）、app/models.py（模型与 schema）、app/alembic/（迁移）。

开发约定

完整规则以 .trellis/spec/index.md 为准；以下为高频约束：

1. 改后端接口：更新 models.py / api/routes / crud.py → 表结构变化补 migration → 补测试 → 运行 bash scripts/generate-client.sh。
2. 加前端页面：页面放 src/pages，数据封装到 src/features/<domain>/hooks.ts，路由与侧栏分别改 App.tsx、AppLayout.tsx；UI 用 Ant Design，请求用 SWR + 生成 client。
3. 不要手改 frontend/src/client；不要提交密钥或环境专属配置。

使用 Cursor 时，可先附上 doc/AI_CODING.md 中的 Minimal Prompt，或让 Agent 读取 .trellis/spec 与对应 skill（project-backend、project-frontend 等）。

内置能力

• 登录、注册、找回密码邮件（本地进入 Mailcatcher，不发真实邮箱）
• 当前用户资料、改密、删号
• 管理员用户管理
• Item 示例资源

参考文档

文档	说明
doc/README.md	项目文档索引
doc/PROJECT_ARCHITECTURE.md	架构、拓扑、数据流
doc/AI_CODING.md	AI Coding 工作流与检查命令
.trellis/spec/index.md	项目约定索引（事实来源）
frontend/FRONTEND_CONVENTIONS.md	前端详细约定
backend/README.md	后端本地开发与命令
frontend/README.md	前端本地开发与命令