wecom-ai-assistant/docs/phase1.md

Phase 1：初始化仓库与脚手架 + 本地跑通

目录结构

backend/          # FastAPI，routers/services/models，config 来自 env
admin/            # Next.js + TypeScript + Ant Design
deploy/           # nginx.conf
docs/             # wecom.md, phase*.md
docker-compose.yml
.env.example

本地启动

1. 复制环境变量：
   • Bash: cp .env.example .env
   • PowerShell: Copy-Item .env.example .env
2. 一键启动（需本机已装 Docker + docker-compose）：

   docker-compose up -d
   

3. 等待 db 健康后，backend 与 admin 会启动；nginx 监听 80。

验证

• 健康检查：curl http://localhost:8000/api/health 或经 nginx curl http://localhost/api/health
  • 期望：{"code":0,"message":"ok","data":{"status":"up"},"trace_id":"..."}
• 管理后台：浏览器打开 http://localhost:3000 或 http://localhost（经 nginx）
  • 登录页，用户名/密码填 admin/admin，点击登录应提示「登录成功」（当前为占位校验）
• 后端测试：在 backend/ 下执行 pytest tests/test_health.py -v

关键配置项（.env）

• DATABASE_URL / DATABASE_URL_SYNC：Phase 2 迁移会用。
• NEXT_PUBLIC_API_BASE：前端请求 API 的地址；本地直连后端可设为 http://localhost:8000，经 nginx 可留空或 http://localhost。

仅本地跑后端（不 Docker）

cd backend
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt
# 先启动 PostgreSQL 并建库 wecom_ai、用户 wecom
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

前端单独起：

• Bash: cd admin && npm install && npm run dev，且设置 NEXT_PUBLIC_API_BASE=http://localhost:8000（可在 admin/.env.local 写一行）。
• PowerShell: 先 cd admin，再 npm install，再 $env:NEXT_PUBLIC_API_BASE="http://localhost:8000"; npm run dev（或把 NEXT_PUBLIC_API_BASE=http://localhost:8000 写入 admin/.env.local 后直接 npm run dev）。