root/Neo-ZQYY

Fork 0

Files

Neo 6e20987d2f 微信小程序页面迁移校验之前 P5任务处理之前

2026-03-09 01:19:21 +08:00

7.1 KiB

Raw Blame History

小程序认证系统联调指南

本文档说明如何在本地环境中完成小程序认证系统的前后端联调测试，覆盖从微信登录到管理端审核的完整流程。

1. 环境准备

1.1 后端服务

在项目根目录 .env.local 中添加以下配置：

WX_DEV_MODE=true          # 开启开发模式，跳过真实微信 code2Session 调用
JWT_SECRET_KEY=dev-secret  # 开发环境 JWT 密钥（生产环境请使用强随机值）

确保数据库 test_zqyy_app 已执行认证相关迁移脚本：

# 建表脚本
psql -d test_zqyy_app -f db/zqyy_app/migrations/2026-02-26__p3_create_auth_tables.sql

# 种子数据（角色、权限、角色-权限映射）
psql -d test_zqyy_app -f db/zqyy_app/migrations/2026-02-26__p3_seed_roles_permissions.sql

启动后端服务：

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

服务默认监听 http://localhost:8000。

1.2 微信开发者工具

导入项目：打开微信开发者工具 → 导入项目 → 选择 apps/miniprogram/ 目录
AppID：使用测试号，或在项目设置中选择「不使用云服务」
项目设置：
- 勾选「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」（开发环境必须）
- 勾选「不校验 HTTPS 证书」
编译模式（可选）：点击编译模式下拉 → 添加编译模式 → 指定启动页面（如 pages/login/login）方便调试特定页面

2. 联调测试流程

Step 1：Mock 登录

开发模式下使用 POST /api/xcx/dev-login 端点，绕过微信 code2Session 调用。

# 默认创建 pending 状态用户
curl -X POST http://localhost:8000/api/xcx/dev-login \
  -H "Content-Type: application/json" \
  -d '{"openid": "test_user_001"}'

# 指定用户状态（可选值：pending / approved / rejected / disabled）
curl -X POST http://localhost:8000/api/xcx/dev-login \
  -H "Content-Type: application/json" \
  -d '{"openid": "test_user_001", "status": "pending"}'

返回示例：

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "user_status": "pending",
  "user_id": 1
}

小程序端会自动将 token 存储到 Storage 和 globalData 中。

Step 2：提交申请

在申请页面（pages/apply/apply）填写以下信息：

字段	示例值	说明
球房ID（site_code）	`AB123`	格式：2 字母 + 3 数字
申请身份	`助教` 或 `员工`	下拉选择
手机号	`13800138000`	11 位数字
编号（选填）	`EMP001`	员工编号，用于辅助匹配
昵称	`张三`	显示名称

提交后自动跳转到审核等待页（pages/reviewing/reviewing）。

也可通过 API 直接提交：

curl -X POST http://localhost:8000/api/xcx/apply \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "site_code": "AB123",
    "applied_role_text": "助教",
    "phone": "13800138000",
    "nickname": "张三"
  }'

Step 3：管理端审核

使用管理端 API 审核申请：

# 1. 查看申请列表
curl http://localhost:8000/api/admin/applications \
  -H "Authorization: Bearer <admin_token>"

# 2. 查看申请详情（含候选匹配）
curl http://localhost:8000/api/admin/applications/1 \
  -H "Authorization: Bearer <admin_token>"

# 3a. 批准申请（需提供 role_id，可选 binding 信息）
curl -X POST http://localhost:8000/api/admin/applications/1/approve \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 1,
    "binding": {"assistant_id": 100, "binding_type": "assistant"},
    "review_note": "信息核实通过"
  }'

# 3b. 拒绝申请（需提供拒绝原因）
curl -X POST http://localhost:8000/api/admin/applications/1/reject \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"review_note": "信息不匹配，请重新申请"}'

提示：管理端 API 需要 site_admin 或 tenant_admin 角色的 token。可通过 dev-login 创建一个 approved 状态的管理员用户，再手动在数据库中为其分配管理角色。

Step 4：重新登录验证

审核通过后，在小程序中重新登录（或使用 dev-login）：

用户状态应变为 approved
小程序应自动跳转到主页（mvp 页面）
可通过 GET /api/xcx/me 验证用户状态和关联信息

curl http://localhost:8000/api/xcx/me \
  -H "Authorization: Bearer <access_token>"

3. API 端点汇总

小程序端

端点	方法	说明	认证要求
`/api/xcx/login`	POST	微信登录	无
`/api/xcx/dev-login`	POST	开发模式 mock 登录	无（仅 `WX_DEV_MODE=true`）
`/api/xcx/apply`	POST	提交申请	JWT（含 pending）
`/api/xcx/me`	GET	查询用户状态	JWT（含 pending）
`/api/xcx/me/sites`	GET	查询关联店铺	JWT（approved）
`/api/xcx/switch-site`	POST	切换店铺	JWT（approved）
`/api/xcx/refresh`	POST	刷新令牌	refresh_token

管理端

端点	方法	说明	认证要求
`/api/admin/applications`	GET	查询申请列表	JWT + site_admin/tenant_admin
`/api/admin/applications/{id}`	GET	申请详情 + 候选匹配	JWT + site_admin/tenant_admin
`/api/admin/applications/{id}/approve`	POST	批准申请	JWT + site_admin/tenant_admin
`/api/admin/applications/{id}/reject`	POST	拒绝申请	JWT + site_admin/tenant_admin

4. 常见问题排查

401 Unauthorized

原因：token 过期或无效
排查：检查小程序 Storage 中的 access_token 是否存在；尝试使用 dev-login 重新获取 token
注意：access_token 默认有效期较短，过期后小程序会自动尝试用 refresh_token 刷新

403 Forbidden

原因：用户状态为 disabled，或权限不足
排查：通过 GET /api/xcx/me 检查用户 status 字段；确认用户在目标店铺下有对应角色

409 Conflict

原因：已有待审核申请（重复提交），或审核目标申请状态非 pending
排查：通过 GET /api/xcx/me 查看现有申请列表及状态

422 Validation Error

原因：表单数据格式错误
常见情况：
- site_code 不符合 2字母+3数字 格式（如 AB123）
- phone 不是 11 位纯数字
- 必填字段为空

网络请求失败

检查后端是否启动：访问 http://localhost:8000/docs 确认 Swagger 文档可访问
检查域名配置：小程序 utils/request.ts 中的 BASE_URL 应指向 http://localhost:8000
「不校验合法域名」未勾选：开发环境必须在微信开发者工具项目设置中勾选此选项，否则 localhost 请求会被拦截

Mock 登录不可用

原因：WX_DEV_MODE 未设置为 true
排查：检查 .env.local 中是否有 WX_DEV_MODE=true；重启后端服务使配置生效

7.1 KiB Raw Blame History Unescape Escape