R524809
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# Worksheet 发布方案
|
||
|
||
> 版本：v1.0 | 最后更新：2026-04-29
|
||
> 配套文档：[页面内容管理方案](./页面内容管理方案.md) | [小程序云开发方案](./小程序云开发方案.md)
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
在小程序**开发版**的 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 已存在时更新，不存在时创建。
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
发布前需确保：
|
||
|
||
1. 云开发环境已初始化
|
||
2. `categories` 集合中存在对应大类（`math`、`puzzle`、`english` 等）
|
||
3. 当前页面实现了 `getPublishMeta()`
|
||
4. 页面 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` 集合 |
|