Neo-ZQYY/docs/ops/init-test-user.md

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

脚本路径：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

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

---

使用方式

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

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

默认创建：

• openid: dev_test_openid
• 昵称: 测试管理员
• 角色: site_admin（店铺管理员，拥有全部看板权限）
• 门店: 朗朗桌球（LL001）

创建助教用户

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

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

创建员工用户

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

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

创建租户管理员

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

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

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. 启动后端

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

2. 获取 JWT Token

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

返回示例：

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user_status": "approved",
  "current_site_id": 2790685415443269
}

3. 测试业务接口

# 查看用户信息
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 外部表无数据，任务列表会为空——这是正常的，说明认证链路已通，业务数据待补充。