doodle-mini/docs/v3.5/本地后端接口联调.md

小程序分类页接入新后端

更新：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：

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 验证（服务端口关闭），不能把脚本联调等同于真机验收。