# 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` 集合 |