chore: snapshot frontend before home search redesign

2026-09-14 10:08:18 +08:00
parent 127858723e
commit 82b0cc485e
3 changed files with 239 additions and 2 deletions
@@ -0,0 +1,236 @@
+# 微信小程序真机测试说明
+
+本文用于指导测试人员在 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
+
+商品列表：通过 / 不通过
+商品详情：通过 / 不通过
+地址管理：通过 / 不通过
+设计清单：通过 / 不通过
+订单创建：通过 / 不通过
+支付：已配置并通过 / 未配置 / 失败
+备注：
+```