# 微信小程序真机测试说明

本文用于指导测试人员在 Windows 开发机上启动后端、构建前端，并通过微信开发者工具预览到真实手机。测试重点是确认：小程序页面能够通过 HTTPS 访问后端接口，商品、地址、设计清单和订单等页面可以正常联调。

## 一、测试环境

| 项目 | 配置 |
| --- | --- |
| 前端源码 | `G:\wordcloud_wechat\wechat_wc` |
| 前端导入目录 | `G:\wordcloud_wechat\wechat_wc` |
| 后端源码 | `G:\wordcloud_wechat\wxmp_backend` |
| 小程序 AppID | `wxad998564cf43a7d9` |
| 真机后端地址 | `https://wxbackend.tokenleaping.com` |
| 本机 Docker 后端地址 | `http://127.0.0.1:3090` |
| 商品图片地址 | `https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com` |

说明：`127.0.0.1` 只代表当前 Windows 电脑。真实手机不能通过这个地址访问电脑上的 Docker 容器；真机应使用可公开访问的 HTTPS 域名。

## 二、启动本机 Docker 后端

本步骤用于确认后端和数据库本身正常，也可供微信开发者工具模拟器联调。

1. 启动 Docker Desktop，确认左下角显示 Engine running。
2. 打开 PowerShell，执行：

   ```powershell
   cd G:\wordcloud_wechat\wxmp_backend
   docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
   ```

3. 查看容器状态：

   ```powershell
   docker compose -f docker-compose.yml -f docker-compose.dev.yml ps
   ```

   预期 `wxmp-app`、`wxmp-postgres`、`wxmp-redis` 均为运行状态，其中数据库和 Redis 应显示 `healthy`。

4. 在浏览器检查本机接口：

   - `http://127.0.0.1:3090/health`
   - `http://127.0.0.1:3090/docs`
   - `http://127.0.0.1:3090/api/categories`
   - `http://127.0.0.1:3090/api/products?page=1&pageSize=20`
   - `http://127.0.0.1:3090/api/products/penbox`

   `/health` 和商品接口返回 HTTP 200，且响应中有 `code: 0`，即可继续测试。

### 本机登录配置

本机 Docker 若只用于开发者工具模拟器联调，可在后端 `.env` 使用本地 mock 登录：

```env
WX_APPID=local-dev-appid
WX_SECRET=local-dev-secret
WX_MOCK_LOGIN=1
```

这是项目《本机容器化联调教程》规定的开发配置，不代表真实微信登录。真实手机登录时，必须改为线上服务器中的真实 `WX_APPID` 与 `WX_SECRET`，并将 `WX_MOCK_LOGIN` 留空；AppSecret 不能提交到 Git。

## 三、构建微信小程序前端

1. 打开新的 PowerShell 窗口，执行：

   ```powershell
   cd G:\wordcloud_wechat\wechat_wc
   npm run build:weapp
   ```

2. 构建成功后，产物位于：

   ```text
   G:\wordcloud_wechat\wechat_wc\dist
   ```

3. 当前真机构建应使用线上地址：

   ```text
   https://wxbackend.tokenleaping.com
   ```

   修改环境变量或配置后，必须重新执行构建；微信开发者工具不会自动读取源码目录中的环境变量。

## 四、配置微信公众平台合法域名

登录小程序管理后台，在“开发 → 开发管理 → 开发设置 → 服务器域名”中配置：

| 类型 | 域名 |
| --- | --- |
| request 合法域名 | `https://wxbackend.tokenleaping.com` |
| downloadFile 合法域名 | `https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com` |
| uploadFile 合法域名 | 使用 COS 直传时配置同一 OSS 域名 |

配置要求：

- 只填写 HTTPS 域名，不填写接口路径、端口、`/health` 或 `/api`。
- HTTPS 证书必须有效，域名证书需覆盖 `wxbackend.tokenleaping.com`。
- 修改服务器域名后，重新编译并重新预览小程序。

开发者工具中的“不校验合法域名”只适合模拟器临时调试，不能替代公众平台的正式域名配置。

## 五、导入开发者工具并预览

1. 打开微信开发者工具。
2. 选择“导入项目”。
3. 项目目录填写前端源码根目录：

   ```text
   G:\wordcloud_wechat\wechat_wc
   ```

   不要选择工作区总目录 `G:\wordcloud_wechat`。根目录中的 `project.config.json` 已声明
   `miniprogramRoot: "dist/"`，开发者工具会自动把 `dist` 作为小程序运行产物。

4. AppID 选择：

   ```text
   wxad998564cf43a7d9
   ```

5. 点击“编译”，确认模拟器能打开首页。
6. 点击工具栏“预览”，等待二维码生成。
7. 使用已登录该小程序的微信扫描二维码，在手机上打开预览版本。

## 六、真机功能测试清单

建议按以下顺序测试，并在每一步记录结果：

| 序号 | 操作 | 预期结果 |
| --- | --- | --- |
| 1 | 启动小程序 | 首页正常显示，无白屏或启动异常 |
| 2 | 打开“商品”页 | 显示后端返回的在售商品列表 |
| 3 | 下拉刷新商品页 | 请求成功，列表无重复或空白 |
| 4 | 点击商品 | 商品详情、价格、规格、图片正常显示 |
| 5 | 返回首页 | 首页商品数据正常显示 |
| 6 | 打开“设计清单” | 已登录时可读取服务端清单；未登录时提示登录 |
| 7 | 新增、编辑、删除地址 | 地址操作成功，默认地址状态正确 |
| 8 | 进入 DIY 并保存设计 | 设计清单状态和内容正常更新 |
| 9 | 提交订单 | 能创建订单并显示服务端计算的金额 |
| 10 | 进入支付 | 若未配置微信支付，显示“支付未配置”等明确提示，不应假装支付成功 |

商品目录重点验收：页面显示的商品必须来自 `GET /api/products` 和 `GET /api/products/:id`，不能只显示前端写死数据。可在测试数据库中修改一个商品价格，再重新进入商品页，确认页面价格同步变化。

## 七、如何确认手机确实访问了后端

在微信开发者工具的“调试器 → Network”中查看请求，商品页至少应看到：

```text
GET https://wxbackend.tokenleaping.com/api/products?page=1&pageSize=20
GET https://wxbackend.tokenleaping.com/api/products/{商品ID}
```

响应状态应为 `200`，响应体应包含：

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

如果请求地址仍然是 `127.0.0.1:3090`，说明前端没有使用真机构建配置，需要重新检查环境变量并执行 `npm run build:weapp`。

## 八、本机 Docker 与真机的关系

本机 Docker 只负责在 Windows 上运行 Linux 容器中的后端、PostgreSQL 和 Redis。它不会自动获得公网 HTTPS 地址。

有两种测试方式：

### 方式 A：直接测试线上 HTTPS 服务（推荐）

- 前端构建地址使用 `https://wxbackend.tokenleaping.com`。
- 微信开发者工具生成预览二维码。
- 手机通过互联网访问线上后端。
- 本机 Docker 只用于本地接口检查，不影响手机请求。

### 方式 B：让手机测试本机 Docker 代码

需要额外配置内网穿透或 FRP：

1. Windows 上的 `frpc` 将本机 `3090` 转发到服务器上的 FRP 服务端。
2. 服务器反向代理将 HTTPS 域名转发到 FRP 通道。
3. 前端仍构建为 `https://wxbackend.tokenleaping.com`。
4. 确认微信公众平台合法域名已配置，并重新预览。

仅启动 Docker Desktop，不能让真实手机直接访问 `127.0.0.1`。

### 当前项目的 FRP 映射

本项目提供的 `frpc.toml` 使用以下转发关系：

```toml
serverAddr = "43.155.206.17"
serverPort = 7000

[[proxies]]
name = "wxbackend"
type = "tcp"
localIP = "host.docker.internal"
localPort = 3090
remotePort = 3090
```

对应含义是：FRP 客户端容器把 Windows 主机的 `3090` 转发到服务器 `3090`；服务器上的 HTTPS 反向代理再将 `wxbackend.tokenleaping.com` 转到该端口。`frpc.toml` 中的认证 token 仅保存在本机文件，不要提交到 Git。

## 九、常见问题

| 现象 | 处理方法 |
| --- | --- |
| `request:fail url not in domain list` | 在公众平台添加 request 合法域名，重新编译并预览 |
| `ERR_CERT` 或 TLS 错误 | 检查 HTTPS 证书、域名解析和服务器时间 |
| 手机请求连接被拒绝 | 不要使用 `127.0.0.1`；确认线上域名或 FRP 转发正常 |
| 模拟器正常、手机白屏 | 检查真机构建地址和服务器域名配置，查看 Network 错误 |
| 商品图片不显示 | 将 OSS 域名加入 downloadFile 合法域名，并检查图片 URL |
| 登录失败 | 检查线上后端的微信 AppID、AppSecret；本机空配置只能测试公开接口 |
| 词云或支付无法完成 | 检查对应外部服务和密钥；未配置时属于预期限制 |

## 十、测试记录模板

```text
测试日期：
测试人员：
前端提交：
后端提交：
手机型号 / 微信版本：
后端地址：https://wxbackend.tokenleaping.com

商品列表：通过 / 不通过
商品详情：通过 / 不通过
地址管理：通过 / 不通过
设计清单：通过 / 不通过
订单创建：通过 / 不通过
支付：已配置并通过 / 未配置 / 失败
备注：
```