# 小程序认证系统联调指南

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

---

## 1. 环境准备

### 1.1 后端服务

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

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

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

```bash
# 建表脚本
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
```

3. 启动后端服务：

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

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

### 1.2 微信开发者工具

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

---

## 2. 联调测试流程

### Step 1：Mock 登录

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

```bash
# 默认创建 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"}'
```

返回示例：

```json
{
  "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 直接提交：

```bash
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 审核申请：

```bash
# 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` 验证用户状态和关联信息

```bash
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`；重启后端服务使配置生效