wecom-ai-assistant/docs/phase2.md

Phase 2：后端基础 API + 数据库迁移

新增内容

• ORM：app/models/（User, ChatSession, Message, Ticket），SQLAlchemy 2.x
• 数据库：app/database.py 异步会话，get_db 依赖
• 迁移：Alembic，alembic/versions/001_init_tables.py、002_seed_admin.py
• 认证：app/services/auth_service.py（bcrypt + JWT），app/deps.py（get_current_user_id）
• 登录：POST /api/auth/login 查 User 表并校验密码，返回 JWT

本地启动与迁移

1. 启动 DB（或整栈）：

   docker-compose up -d db
   

2. 在 backend/ 下执行迁移（需已配置 DATABASE_URL_SYNC，如从项目根 .env 加载）：

   cd backend
   # 若 .env 在项目根，可：export $(grep -v '^#' ../.env | xargs)  或复制 .env 到 backend/
   alembic upgrade head
   

3. 启动后端：

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

验证

• 健康检查：curl http://localhost:8000/api/health → code: 0, data.status: "up"
• 登录：curl -X POST http://localhost:8000/api/auth/login -H "Content-Type: application/json" -d "{\"username\":\"admin\",\"password\":\"admin\"}"
  • 迁移并 seed 后应返回 code: 0 且 data.access_token 为 JWT
• 测试：pytest tests/test_health.py tests/test_auth.py -v

关键配置项

• DATABASE_URL：异步连接串，供 FastAPI 使用（如 postgresql+asyncpg://...）
• DATABASE_URL_SYNC：同步连接串，供 Alembic 使用（如 postgresql://...）
• JWT_SECRET：生产环境必须修改
• JWT_EXPIRE_MINUTES：token 有效期（分钟）

Docker 内迁移

若后端在 Docker 内启动，可在首次启动时自动迁移（可选）。例如在 backend/Dockerfile 或启动脚本中：

alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000

需保证容器内能访问 DATABASE_URL_SYNC 且指向 db:5432。