# WonderQ-Admin

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

## 本地手动启动

以下命令默认在项目根目录执行：`D:\www\znkj\WonderQ-Admin`。

### 1. 准备环境变量

首次启动先复制环境变量模板：

```powershell
Copy-Item .env.example .env
```

然后编辑 `.env`，至少确认以下配置：

- `DATABASE_URL`：本地 Docker PostgreSQL 默认使用 `localhost:5433`。
- `JWT_SECRET`：生产环境必须替换为高强度随机值。
- `OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`、`OSS_ENDPOINT`、`OSS_BUCKET_NAME`：填写实际 OSS 配置；真实密钥只放在 `.env` 或部署平台密钥中，不提交到 Git。

### 2. 创建并启用 Python 虚拟环境

首次启动或 `.venv` 不存在时执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
```

如果 PowerShell 阻止执行激活脚本，可临时允许当前进程执行脚本后再激活：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```

后续日常启动只需要重新激活虚拟环境：

```powershell
.\.venv\Scripts\Activate.ps1
```

### 3. 启动依赖服务

启动本地 PostgreSQL 和 Redis：

```powershell
docker-compose up -d postgres redis
```

确认容器状态：

```powershell
docker-compose ps
```

### 4. 初始化或升级数据库

首次启动、迁移变更后执行：

```powershell
python -m alembic upgrade head
```

空库首次导入初始化内容时执行：

```powershell
python -m app.seed
```

注意：`python -m app.seed` 会重置站点内容、产品、目的地、活动和媒体数据；已有业务数据时不要重复执行。只需要确保默认后台账号存在时，用：

```powershell
python -m app.seed --no-reset
```

### 5. 启动 API 服务

开发模式启动：

```powershell
python -m uvicorn app.main:app --host 0.0.0.0 --port 4000 --reload
```

如果需要手动重启 4001 端口服务，先释放端口，再重新运行：

```powershell
$port = 4001
$listenerPids = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty OwningProcess -Unique
foreach ($listenerPid in $listenerPids) {
  Get-CimInstance Win32_Process |
    Where-Object { $_.ParentProcessId -eq $listenerPid } |
    ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }
  Stop-Process -Id $listenerPid -Force -ErrorAction SilentlyContinue
}
python -m uvicorn app.main:app --host 0.0.0.0 --port 4001 --reload
```

启动后访问：

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

### 日常启动速查

从 `D:\www\znkj\WonderQ-Project` 根目录手动启动时，先确认 Docker Desktop 已运行，通常只需要：

```powershell
Set-Location .\WonderQ-Admin
.\.venv\Scripts\Activate.ps1
docker-compose up -d postgres redis
python -m alembic upgrade head
python -m uvicorn app.main:app --host 0.0.0.0 --port 4001 --reload
```

## Docker 部署

完整本地部署：

```bash
docker-compose up --build
```

服务包含：

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

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

```bash
alembic stamp head
```

空库或全新环境使用：

```bash
python -m 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/`：基础单元和接口冒烟测试。

## 常用命令

| 命令                                                  | 说明                              |
| ----------------------------------------------------- | --------------------------------- |
| `python -m uvicorn app.main:app --reload --port 4000` | 启动开发服务                      |
| `python -m alembic upgrade head`                      | 创建或升级数据库结构              |
| `alembic stamp head`                                  | 标记已有数据库已处于当前 baseline |
| `python -m app.seed`                                  | 重置并导入初始化内容              |
| `python -m app.seed --no-reset`                       | 只确保默认后台账号存在            |
| `python -m 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/media-assets/upload`
- `POST /api/admin/reset-guizhou-content`
- `POST /api/admin/publish`

## 注意事项

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