project-workflow

项目工作流与启动规范

🏗️ 基础底座

本项目遵循以下通用开发标准：

• Python 环境: 遵循 python-uv-web 规范。
• 前端环境: 遵循 nextjs-pnpm 规范。

🚀 项目特定启动流程

在遵循通用规范的基础上，本项目有以下特有逻辑：

1. 本地开发模式 (推荐，响应最快)

后端 (FastAPI)

• 目录: /backend
• 前提: 已安装 uv
• 启动: uv run fastapi dev app/main.py
• 端口: 8000
• 文档: http://localhost:8000/docs

前端 (Next.js)

• 目录: /frontend
• 前提: 已安装 pnpm
• 启动: pnpm dev
• 端口: 3000
• 注意: 本地模式下，前端通过 next.config.ts 中的 rewrites 代理到 127.0.0.1:8000。

2. 容器开发模式 (环境一致性)

• 命令: docker compose -f docker-compose.dev.yml up
• 特点:
  • 支持热更新 (Hot Reload)。
  • 自动处理数据库、Redis 等基础设施。
  • 前端通过 Docker 网络连接后端 (http://backend:8000)。

---

🛠️ 初始化流程 (新环境)

如果是第一次克隆项目，请按此顺序执行：

1. 环境准备:

   • 复制 .env.example -> .env (根据需要修改)。
   • 确保安装了 uv, pnpm, docker。

2. 后端初始化:

   cd backend
   uv sync               # 安装依赖
   make db-migrate       # 初始化数据库表结构
   uv run app/initial_data.py  # 注入初始管理员数据
   

3. 前端初始化:

   cd frontend
   pnpm install          # 安装依赖
   pnpm api:generate     # 生成 API SDK（强烈建议）
   

4. 内容同步:

   ./scripts/sync-posts.sh  # 将 content/ 下的示例内容同步到数据库
   

---

🔄 日常开发循环

1. 修改代码:
   • 后端逻辑修改。
   • 前端 UI 修改。
2. 同步 API (如果后端 Schema 变了):
   • 执行 ./scripts/generate-api.sh。
3. 验证:
   • 运行测试: cd backend && make test。
   • 检查 lint: make lint (backend) / pnpm lint (frontend)。

---

⚠️ 常见问题启动检查项

• 数据库连接失败: 检查 .env 中的 DATABASE_URL 是否正确（本地通常是 localhost，Docker 内通常是 db）。
• 前端 SSR 报错: 检查 BACKEND_INTERNAL_URL 环境变量是否配置正确。
• 端口占用: 确保 3000 和 8000 端口未被其他服务占用。