WonderQ-Admin/README.md

WonderQ-Admin

独立的 WonderQ 后端 API 服务，基于 Python、FastAPI、SQLAlchemy 2、Alembic、PostgreSQL、JWT 和 Pydantic。

本地启动

1. 复制环境变量：

cp .env.example .env

2. 创建虚拟环境并安装依赖：

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

3. 启动 PostgreSQL 和 Redis：

docker compose up -d postgres redis

4. 初始化数据库结构并导入初始内容：

alembic upgrade head
python -m app.seed

5. 启动 API：

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

访问：

• 健康检查：http://localhost:4000/health
• 默认后台账号：admin@example.com / ChangeMe123!

Docker 部署

完整本地部署：

docker compose up --build

服务包含：

• api：FastAPI 服务，默认监听 4000
• postgres：PostgreSQL 16，宿主机端口 5433
• redis：Redis 7，宿主机端口 6380

已有生产数据库迁移到 Python 版时，先备份数据库，再执行：

alembic stamp head

空库或全新环境使用：

alembic upgrade head
python -m app.seed

目录说明

• app/：FastAPI 应用、路由、鉴权、数据库模型、schema、seed 逻辑。
• app/routers/public.py：H5 Public API。
• app/routers/admin.py：后台 Admin API。
• app/models.py：SQLAlchemy ORM，兼容原 Prisma 表结构。
• alembic/：数据库迁移 baseline。
• data/generated-products.json：从 H5 拆出的产品初始数据。
• docker-compose.yml：API、PostgreSQL 和 Redis 编排。
• tests/：基础单元和接口冒烟测试。

常用命令

命令	说明
uvicorn app.main:app --reload --port 4000	启动开发服务
alembic upgrade head	创建或升级数据库结构
alembic stamp head	标记已有数据库已处于当前 baseline
python -m app.seed	重置并导入初始化内容
python -m app.seed --no-reset	只确保默认后台账号存在
pytest	运行测试
docker compose up --build	构建并启动完整服务

API 兼容范围

Python 版保留原有核心路径：

• GET /health
• GET /api/public/site-config
• GET /api/public/products
• GET /api/public/products/{id}
• GET /api/public/destinations
• POST /api/public/leads
• POST /api/admin/auth/login
• GET /api/admin/me
• GET /api/admin/dashboard
• GET /api/admin/products
• POST /api/admin/products
• PATCH /api/admin/products/{id}
• GET /api/admin/destinations
• GET /api/admin/site-config
• PATCH /api/admin/site-config/{module}/{id}
• GET /api/admin/leads
• PATCH /api/admin/leads/{id}/status
• GET /api/admin/media-assets
• POST /api/admin/reset-guizhou-content
• POST /api/admin/publish

注意事项

• 生产环境必须替换 JWT_SECRET，禁止使用示例值。
• 真实环境变量只放在 .env 或部署平台密钥中，不提交到 Git。
• python -m app.seed 会重置站点内容、产品、目的地、活动和媒体数据；不要直接对生产库执行。
• 保留现有 PostgreSQL 数据时使用 alembic stamp head，不要在已有生产表上直接运行初始建表迁移。