# 测试用户初始化脚本使用指南

> 脚本路径：`scripts/ops/init_test_user.py`
> 目标库：`test_zqyy_app`（通过 `APP_DB_DSN` 连接）
> 适用场景：在没有租户管理后台的情况下，快速创建可用的测试用户

---

## 背景

小程序认证系统（P3）的完整流程是：

```
微信登录 → 提交申请 → 管理员审核 → 分配角色 → 访问业务页面
```

但管理后台的审核 UI 尚未开发，导致用户卡在 `pending` 状态，无法测试后续的业务页面（P4 任务管理等）。

本脚本直接在数据库中完成"审核通过"所需的全部数据准备，跳过管理后台，打通完整链路。

---

## 前提条件

1. 根 `.env` 中已配置 `APP_DB_DSN`，指向 `test_zqyy_app`
2. `test_zqyy_app` 中已执行过 P3 迁移脚本（auth Schema 的 8 张表 + 种子数据）
3. Python 环境已安装 `psycopg2` 和 `python-dotenv`（`uv sync` 即可）

---

## 脚本做了什么

| 步骤 | 操作 | 写入的表 |
|------|------|----------|
| 1 | 确保门店映射存在（朗朗桌球 LL001） | `auth.site_code_mapping` |
| 2 | 创建/更新测试用户为 `approved` 状态 | `auth.users` |
| 3 | 分配门店角色 | `auth.user_site_roles` |
| 4 | 创建助教/员工绑定 | `auth.user_assistant_binding` |

所有操作幂等——重复执行不会产生重复数据。

---

## 使用方式

### 基本用法（创建店铺管理员）

```bash
cd C:\NeoZQYY
python scripts/ops/init_test_user.py
```

默认创建：
- openid: `dev_test_openid`
- 昵称: `测试管理员`
- 角色: `site_admin`（店铺管理员，拥有全部看板权限）
- 门店: 朗朗桌球（LL001）

### 创建助教用户

```bash
python scripts/ops/init_test_user.py --role coach --openid test_coach --nickname 测试助教
```

绑定到 ETL 助教：李楚欣（assistant_id=2793361915547781）

### 创建员工用户

```bash
python scripts/ops/init_test_user.py --role staff --openid test_staff --nickname 测试员工
```

绑定到 ETL 员工：厉超（staff_id=3020235774380805）

### 创建租户管理员

```bash
python scripts/ops/init_test_user.py --role tenant_admin --openid test_tenant --nickname 测试租户管理员
```

### 重置用户（清除旧数据重新初始化）

```bash
python scripts/ops/init_test_user.py --reset
```

`--reset` 会清除该用户的所有角色、绑定、申请记录，然后重新创建。

---

## 参数说明

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--openid` | `dev_test_openid` | 测试用户的微信 openid |
| `--nickname` | `测试管理员` | 用户昵称 |
| `--role` | `site_admin` | 角色：`coach` / `staff` / `site_admin` / `tenant_admin` |
| `--reset` | 否 | 重置模式：清除旧数据后重新初始化 |

---

## 初始化后的测试流程

### 1. 启动后端

```bash
cd apps/backend
uvicorn app.main:app --reload
```

### 2. 获取 JWT Token

```bash
curl -X POST http://localhost:8000/api/xcx/dev-login \
  -H "Content-Type: application/json" \
  -d '{"openid": "dev_test_openid", "status": "approved"}'
```

返回示例：
```json
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user_status": "approved",
  "current_site_id": 2790685415443269
}
```

### 3. 测试业务接口

```bash
# 查看用户信息
curl http://localhost:8000/api/xcx/me \
  -H "Authorization: Bearer <access_token>"

# 查看用户门店列表
curl http://localhost:8000/api/xcx/me/sites \
  -H "Authorization: Bearer <access_token>"

# 查看任务列表（P4）
curl http://localhost:8000/api/xcx/tasks \
  -H "Authorization: Bearer <access_token>"
```

### 4. 小程序端测试

如果要在微信开发者工具中测试：
1. 确保 `WX_DEV_MODE=true`
2. 小程序 `app.ts` 中的登录逻辑会调用 `dev-login`
3. 使用脚本创建的 openid 登录即可

---

## 角色权限对照

| 角色 | 权限 | 绑定类型 |
|------|------|----------|
| `coach` | 查看任务、查看助教看板 | 助教（李楚欣） |
| `staff` | 查看任务、查看数据看板 | 员工（厉超） |
| `site_admin` | 全部看板权限 | 管理员（绑定员工厉超） |
| `tenant_admin` | 全部看板权限 | 管理员（绑定员工厉超） |

---

## 数据来源

脚本中的门店/助教/员工 ID 来自 ETL 测试库 `test_etl_feiqiu` 的真实数据：

| 数据 | 来源表 | 值 |
|------|--------|-----|
| 门店 | `dwd.dim_site` | 朗朗桌球 (site_id=2790685415443269) |
| 助教 | `dwd.dim_assistant` | 李楚欣 (assistant_id=2793361915547781) |
| 员工 | `dwd.dim_staff` | 厉超 (staff_id=3020235774380805) |

---

## 常见问题

### Q: 执行报错 "APP_DB_DSN 未定义"
A: 检查根 `.env` 文件中是否有 `APP_DB_DSN=postgresql://...test_zqyy_app` 配置。

### Q: 执行报错 "疑似正式库"
A: 脚本会检查 DSN 中是否包含 `test_`，防止误操作正式库。确认你的 DSN 指向测试库。

### Q: dev-login 返回 404
A: 确认 `.env` 中 `WX_DEV_MODE=true`，该端点仅在开发模式下注册。

### Q: 任务列表为空
A: 任务数据由任务生成器产生，需要 ETL 库中有会员+消费指数数据。如果 FDW 外部表无数据，任务列表会为空——这是正常的，说明认证链路已通，业务数据待补充。