joey5628/doodle-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 分类接口替换为api 接口

Browse Source
This commit is contained in:
R524809
2026-10-16 17:33:24 +08:00
parent eddd7d75e2
commit 8de06ce66b
12 changed files with 1086 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/v3.5/云存储资源目录清单.md
+67
View File
@@ -0,0 +1,67 @@
# 微信云存储资源目录清单
更新：2026-10-16。依据 doodle-mini 的 miniprogram 与 cloudfunctions 源码、路径构造函数及仓库内缓存分析，不是云端存储桶的实时文件列表。本次未下载、上传、迁移或删除云文件。
## 目录树
以下为代码涉及的云存储相对路径，仅列到最后一级目录，共 9 个末级目录：
```text
/
├── assets/
│ ├── fonts/
│ └── previews/
│ ├── chinese/
│ ├── english/
│ ├── math/
│ ├── papers/
│ ├── pinyin/
│ └── puzzle/
├── content/
└── user-avatars/
```
对象存储中的“目录”是文件 key 的前缀。此处表示代码引用或能够写入的路径，不保证每个目录已经存在文件，也不能据此排除云端的历史/未引用目录。
## 用途与代码依据
| 最后一级目录 | 用途与确认范围 | 代码依据 |
| ------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| assets/previews/chinese/ | 语文、控笔、识字等题型预览；首页静态项目也直接引用此路径 | [首页数据](../../miniprogram/pages/home/home.data.ts)、[语文发布配置](../../miniprogram/chinesePages/wordColoring/wordColoring.config.ts) |
| assets/previews/english/ | 英文字母题型预览；首页静态项目直接引用此路径 | [首页数据](../../miniprogram/pages/home/home.data.ts)、[英语发布配置](../../miniprogram/englishPages/letterTracing/letterTracing.config.ts) |
| assets/previews/math/ | 数学题型预览；由发布路径构造，旧页面配置缓存也有文件引用 | [数学发布配置](../../miniprogram/mathPages/mathDraw/mathDraw.config.ts)、[路径构造](../../miniprogram/utils/debugPublish.ts) |
| assets/previews/papers/ | 作业纸预览的动态上传路径；有发布配置，不能仅凭代码断言云端已有文件 | [作业纸发布配置](../../miniprogram/papersPages/paperSheet/paperSheet.config.ts)、[路径构造](../../miniprogram/utils/debugPublish.ts) |
| assets/previews/pinyin/ | 拼音题型预览；首页静态项目直接引用此路径 | [首页数据](../../miniprogram/pages/home/home.data.ts)、[拼音发布配置](../../miniprogram/pinyinPages/pinyinDictation/pinyinDictation.config.ts) |
| assets/previews/puzzle/ | 益智题型预览；由发布路径构造，旧页面配置缓存也有文件引用 | [益智发布配置](../../miniprogram/focusPages/focusDraw/focusDraw.config.ts)、[路径构造](../../miniprogram/utils/debugPublish.ts) |
| assets/fonts/ | ToneOZ 拼音字体；通过 cloud fileID 兑换临时链接，再加载字体 | [字体配置](../../miniprogram/core/font/fontProfiles.ts)、[字体加载](../../miniprogram/core/font/fontLoader.ts) |
| content/ | 首页展示配置 JSON；内容构建和定时刷新云函数上传到 content/page-config.json | [内容构建](../../cloudfunctions/pageContentBuild/index.js)、[定时刷新](../../cloudfunctions/homeAutoRefresh/index.js) |
| user-avatars/ | 用户头像；按用户 ID 和时间生成文件名上传，文件数量须另查用户数据或云端清单 | [头像上传](../../miniprogram/pages/profile/profile.ts) |
预览图统一写入规则为 `assets/previews/${category}/${id}.jpg`，由页面发布元数据传入 category，再通过 `base/pageMixin.ts` 调用 wx.cloud.uploadFile。扫描发布配置得到 chinese、english、math、papers、pinyin、puzzle 六个分类。类型或分类导航里存在 craft，不等于存在 craft 云预览目录，本清单不据此添加。
cloudfunctions 中另有两处实际上传调用，均写 content/page-config.json。头像上传是一个调用点，题型预览上传是一个公共调用点；未发现其他业务云文件上传路径。旧云数据库 previewImg/avatarUrl 字段可以保存代码未硬编码的 fileID，因此运行时数据仍可能增加清单以外的引用。
## 已走 CDN 的远程资源
以下引用使用 `https://cdn.joeyone.cn`，不是当前源码中的微信 cloud fileID，不混入上述云存储目录。仅凭域名不能确认底层存储服务商或 bucket，也不假定需要重复迁移。
| CDN 路径 | 内容 | 代码依据 |
| ----------------- | -------------------------------------- | ------------------------------------------------------------------------ |
| doodle/fonts/ | 六个字体文件，包含手写、描红和数字字体 | [字体配置](../../miniprogram/core/font/fontProfiles.ts) |
| doodle/hanzi/ | 汉字笔画及读音 JSON | [汉字数据加载](../../miniprogram/chinesePages/shared/getWordsSvgJson.ts) |
| doodle/share-img/ | 小程序分享图片 | [分享配置](../../miniprogram/config/config.ts) |
小程序包内的 assets/imgs、assets/tabBar、iconfont 等本地文件不属于云存储迁移范围；不能因为本地路径也以 assets 开头，就当作微信云文件。
## 后续快速同步建议
先做一次批量迁移，稳定后再考虑持续同步；当前仅为方案，未执行：
1. 生成文件级清单：题型预览从旧 worksheets.previewImg/新后端 assets.source_ref 获取，头像从用户当前引用获取，补上已确认的字体和配置路径。代码目录用于限定范围，不能替代实际文件枚举。旧缓存只作线索，不作为当前有效引用的唯一依据。
2. 按清单从原云环境授权下载到本地备份；记录相对路径、MIME、大小和 SHA-256，可失败重试。不将临时签名 URL 保存为长期资源地址。
3. 上传七牛并保留可追踪路径映射。例如公共资源可采用统一前缀加原相对路径，或按资产 ID/内容摘要生成不可变 key；目标空间、前缀和同名文件处理在执行前明确。头像按现有后端设计使用私有空间，不能与公共预览一并公开。
4. 回读校验后再更新引用：51 张已导入预览保留现有 assetId/preview_asset_id，回填七牛对象信息并标记 ready；字体更新配置 URL，头像按用户绑定并经服务端签名访问。
5. 首页配置 JSON 含嵌套预览地址，需在迁移图片后重建或替换这些引用，并处理小程序缓存。仅复制 JSON 文件不会自动转换其中的 cloud fileID。
6. 同时切换后续上传、发布和定时任务的目标，否则旧代码继续往微信云存储写入，七牛副本会再次落后。切换核对完成前保留源文件。
已有实施调研见 [云存储图片迁移七牛调研](../../../doodle-store/docs/v3.5/云存储图片迁移七牛调研.md)。本地未发现可直接使用的 tcb、cloudbase、qshell 命令；已有小程序 AppSecret 不等于源环境存储管理权限或七牛凭据。后续实施需确认可读源文件的授权方式，以及目标七牛 bucket、区域、HTTPS 域名和服务端凭据，不把凭据写入文档或前端。
docs/v3.5/本地后端接口联调.md
+64
View File
@@ -0,0 +1,64 @@
# 小程序分类页接入新后端
更新：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 验证（服务端口关闭），不能把脚本联调等同于真机验收。