R524809
65 lines
5.8 KiB
Markdown
65 lines
5.8 KiB
Markdown
# 小程序分类页接入新后端
|
||
|
||
更新：2026-10-16。分类页已由旧 CloudBase 查询切换为 doodle-store 的公开 HTTP 接口；首页、微信登录、收藏、下载计数及其他页面仍使用原有云服务，本次不做双写或隐式数据同步。
|
||
|
||
## 全局配置
|
||
|
||
入口：`miniprogram/config/api.ts`。
|
||
|
||
| 配置 | 当前值 | 用途 |
|
||
| ---------------------- | ---------------------------- | --------------------------------------------- |
|
||
| developmentEnvironment | local | 开发版选择 local 或 online |
|
||
| localBaseUrl | http://127.0.0.1:8800/api/v1 | 开发者工具连接本机后端 |
|
||
| onlineBaseUrl | 空串 | 线上地址待确定；填写完整 HTTPS 地址及 /api/v1 |
|
||
| timeout | 10000 | 请求超时，毫秒 |
|
||
|
||
环境通过 `wx.getAccountInfoSync().miniProgram.envVersion` 获取。develop 默认走 local，可以修改 developmentEnvironment 联调线上；trial、release 和未知版本只走 online。线上地址为空时明确显示“请先配置线上接口地址”，不会回退本地或云函数。该配置不保存 AppSecret、JWT 密钥或数据库凭据。
|
||
|
||
新后端请求统一使用 `services/api-request.ts`，分别校验 HTTP 状态、业务 code 和响应结构；`services/content-api.ts` 封装分类、完整题型分页与详情。旧 `utils/http.ts` 和旧云请求保留，以免影响其他页面。
|
||
|
||
## 如何切换接口环境
|
||
|
||
修改 [miniprogram/config/api.ts](../../miniprogram/config/api.ts)：
|
||
|
||
```ts
|
||
export const apiConfig = {
|
||
developmentEnvironment: 'local' as ApiEnvironment,
|
||
localBaseUrl: 'http://127.0.0.1:8800/api/v1',
|
||
onlineBaseUrl: '',
|
||
timeout: 10000,
|
||
};
|
||
```
|
||
|
||
- **开发版连接本地**：将 `developmentEnvironment` 设置为 `'local'`，在 `localBaseUrl` 中填写本地接口地址。
|
||
- **开发版连接线上**：先填写 `onlineBaseUrl`，再将 `developmentEnvironment` 设置为 `'online'`。
|
||
- **体验版、正式版**：自动使用 `onlineBaseUrl`，不受 `developmentEnvironment` 影响。地址需要使用 HTTPS，并包含 `/api/v1`；目前线上地址尚未确定，保持空串，确定后再填写。
|
||
- **手机测试本地服务**：保持 `'local'`，将 `localBaseUrl` 中的 `127.0.0.1` 改为电脑局域网 IP；同时将后端 `doodle-store/apps/server/.env` 中的 `HOST` 设置为 `0.0.0.0` 并重启后端。手机和电脑需在同一局域网。
|
||
|
||
修改后重新编译小程序即可。当前此配置用于已迁移的分类页，其他页面仍使用原云服务。
|
||
|
||
## 本地运行
|
||
|
||
1. 在 doodle-store 执行 `pnpm dev`。实际 `apps/server/.env` 和缺省端口已改为 8800，默认 HOST 仍为 127.0.0.1。
|
||
2. 浏览器访问 `http://127.0.0.1:8800/api/v1/health` 或 `http://127.0.0.1:8800/api-docs`。
|
||
3. 微信开发者工具打开 doodle-mini，重新编译后进入分类页。本机 `project.private.config.json` 的 urlCheck 已设为 false，公共 project.config.json 保持域名校验；私有配置覆盖公共配置。
|
||
4. 真机测试时手机和电脑在同一局域网；后端 HOST 改为 0.0.0.0 并重启，将 localBaseUrl 的 IP 改为电脑局域网 IP，保留 8800 和 /api/v1。手机上的 127.0.0.1 指向手机自身。
|
||
|
||
开发者工具打开服务端口后才可使用微信官方 CLI 自动化。本机当前未开启该端口，本次没有修改 IDE 全局安全设置、上传代码或发布小程序。
|
||
|
||
## 分类页行为
|
||
|
||
- 分类导航读取 GET /categories，不再用写死目录决定上线状态；全部、热门推荐、下载最多是前端内置入口。现有后端目录包含 craft、不含 papers，页面按后端实际目录展示。
|
||
- GET /worksheets?page=1&pageSize=100，按 hasNext 继续读取，完整成功后才生成页面数据。分页变化、重复 ID 或缺页时展示重试，不返回局部榜单。
|
||
- 保留旧交互：全部及普通分类以 updatedAt 最近两条置顶，其余按下载数降序；热门推荐仍为收藏数前 12，下载最多为下载数前 12。前端“热门推荐”与服务端 sort=hot（下载热度）含义不同，因此不直接用后者替代。
|
||
- likes/downloads 已含展示 seed，保留十进制字符串；按字符串长度及字典序比较，不转换为 Number，不要求微信运行时支持 BigInt。
|
||
- previewImg 为空时显示所属分类图标；当前 51 张预览尚未迁移，不阻止题型数据展示。
|
||
- 每次 onShow 重新读取。加载失败清空旧数据，展示原因和“重新加载”；不恢复 category.data.ts、写死目录或旧云查询。
|
||
- 请求采用页面版本标记，旧请求或离开页面后的响应不会覆盖新数据。已下架的默认分类回到“全部”。
|
||
- 点击题型先查询 GET /worksheets/:id，再使用当前服务端 path 跳转；404 时刷新列表，网络失败不直接进入内置生成页。通过分享或其他页面直接进入生成页的访问检查另行迁移，不能只凭分类页迁移认定全站均受新后端发布控制。
|
||
|
||
## 验证
|
||
|
||
`npm run test:category` 运行环境切换、请求失败、121 条完整分页、分页变化、64 位计数、服务端目录、空图、页面重试、过期响应和点击下架检查。`TEST_LOCAL_API=1 npm run test:category` 额外连接真实本地 8800 服务。
|
||
|
||
本次 9 项含真实接口的测试全部通过，读取 6 个分类及 51 个题型，卡片数据及点击详情正常。小程序全量 TypeScript 检查原有 117 条报错仍存在，修改前后结果一致，本次相关文件无新增错误。后端 pnpm check 通过。微信开发者工具模拟器的实际编译/显示尚未通过 CLI 验证（服务端口关闭），不能把脚本联调等同于真机验收。
|