Worksheet 发布方案

版本：v1.0 | 最后更新：2026-04-29 配套文档：页面内容管理方案 | 小程序云开发方案

概述

在小程序开发版的 worksheet 绘制页面中，开发者完成调试后可直接将当前 worksheet 发布为云端内容。发布能力只在 develop 环境可见，正式版不展示入口。

核心链路：

预览组件导出 A4 图 → 裁剪压缩为入口图 → 上传云存储 → 云函数 upsert worksheets → draft 入库

已接入页面

页面	元数据配置	category	path 示例
数学 worksheet	`mathPages/mathDraw/mathDraw.config.ts`	`math`	`/mathPages/mathDraw/mathDraw?id=number-find`
专注力 / 益智	`focusPages/focusDraw/focusDraw.config.ts`	`puzzle`	`/focusPages/focusDraw/focusDraw?id=dot-connect`
英语字母描红	`englishPages/letterTracing/letterTracing.config.ts`	`english`	`/englishPages/letterTracing/letterTracing?id=letter-tracing-single`

新增 worksheet 页面只需复用 pageMixin 并实现 getPublishMeta() 即可接入。

发布流程

流程在 miniprogram/base/pageMixin.ts 中完成：

┌─────────────────────────────────────────────────────────────┐
│  开发版页面                                                   │
│  │                                                           │
│  ├─ syncDebugPublishEnv 判断 envVersion === develop          │
│  ├─ 点击 debug-publish-tools 悬浮发布按钮                      │
│  ├─ getPublishMeta() 读取当前 worksheet 元数据                 │
│  ├─ 弹窗微调 title / subtitle / tags / status / 图片参数       │
│  ├─ preview-card.exportToTempFile() 导出预览图                 │
│  ├─ debug-publish-tools.processImage() 裁剪压缩入口图          │
│  ├─ wx.cloud.uploadFile → assets/previews/<category>/<id>.jpg │
│  └─ wx.cloud.callFunction('worksheetsPublish') upsert         │
└─────────────────────────────────────────────────────────────┘

图片处理规则

处理由 components3.0/debug-publish-tools 完成，参数定义在 utils/debugPublish.ts。

默认参数

参数	默认值	说明
`cropMode`	`header-footer`	裁掉页眉页脚，保留主体内容
`width`	`600`	输出入口图宽度（px）
`quality`	`90`	初始 JPEG 质量
`maxSizeKB`	`200`	超出后自动降低质量压缩
云存储路径	`assets/previews/<category>/<id>.jpg`	由 `buildWorksheetPreviewCloudPath` 生成

裁剪模式

模式	用途
`header-footer`	默认 — 只保留 worksheet 主体内容
`header-only`	保留底部品牌区
`none`	完整 A4 预览图压缩上传

入库字段

DebugPublishMeta 与 worksheetsPublish 云函数字段已对齐：

字段	来源	说明
`_id` / `id`	页面元数据	worksheet 业务唯一 ID
`title`	页面元数据（弹窗可改）	展示标题
`subtitle`	页面元数据（弹窗可改）	展示副标题
`category`	页面元数据	必须存在于 `categories` 集合
`subcategory`	页面元数据	如 `math-draw`、`focus-draw`、`letter-tracing`
`path`	页面元数据	小程序跳转路径
`previewImg`	云存储上传结果	入口图 fileID
`ageMin` / `ageMax`	页面元数据	适龄范围
`grade`	`inferGradeFromAge` 推断	年级映射
`difficulty`	页面元数据	1=入门 2=基础 3=进阶 4=挑战
`tags`	页面元数据（弹窗可改）	搜索和运营标签
`isNew` / `isHot`	页面元数据	首页和推荐位复用
`sortOrder`	页面元数据	列表排序权重
`downloads` / `likes`	发布 payload 或默认值	运营统计展示
`status`	弹窗选择（默认 `draft`）	`draft` / `active` / `hidden`
`createdAt` / `updatedAt`	云函数	创建和更新时间

worksheetsPublish 是 upsert 语义：同 ID 已存在时更新，不存在时创建。

前置条件

发布前需确保：

云开发环境已初始化
categories 集合中存在对应大类（math、puzzle、english 等）
当前页面实现了 getPublishMeta()
页面 WXML 已挂载 debug-publish-tools 组件

如果 categories 中没有对应分类，worksheetsPublish 会返回"分类不合法"。

关键文件索引

文件	职责
`miniprogram/base/pageMixin.ts`	发布流程主逻辑
`miniprogram/components3.0/debug-publish-tools/`	发布 UI 组件、图片处理
`miniprogram/utils/debugPublish.ts`	图片参数、云路径生成
`cloudfunctions/worksheetsPublish/`	upsert `worksheets` 集合

5.1 KiB Raw Blame History Unescape Escape