R524809
155 lines
6.3 KiB
Markdown
155 lines
6.3 KiB
Markdown
# Doodle Mini v3.5 Web 与服务端生成策略
|
||
|
||
> 状态：架构决策草案
|
||
>
|
||
> 更新日期：2026-09-24
|
||
|
||
## 1. 决策结论
|
||
|
||
### 1.1 Web 的定位
|
||
|
||
Web 是长期的搜索获客、内容沉淀、电脑打印和教师/机构扩展渠道；小程序仍是当前的微信内打开、分享、每日推荐和家庭留存主产品。
|
||
|
||
因此，v3.5 采用：
|
||
|
||
> **70% 投入小程序核心体验，30% 投入 Web 与服务端生成试点。**
|
||
|
||
不等待小程序“达到很大用户量”才准备 Web，因为搜索内容、服务端渲染和内容生产机制都需要时间积累；但也不在内容库、内容生产和核心留存未验证时建设完整 Web 平台。
|
||
|
||
### 1.2 生成位置
|
||
|
||
未来 Web 的高价值题型采用**服务端生成与渲染优先**。浏览器负责选择参数、展示预览、发起下载和账户交互；不得承载完整题目生成规则、排版参数与私有素材。
|
||
|
||
小程序既有题型暂可保留客户端 Canvas 生成，以避免高风险的一次性重写。创意涂色纸及后续主题包、批量 PDF 等新能力必须按服务端模式实现。
|
||
|
||
## 2. 为什么不把核心生成放在 Web 客户端
|
||
|
||
Web 客户端代码、网络请求和静态资源可被用户查看、保存和分析。即使经过压缩或混淆，也只能提高复制成本，无法提供真正的保护。
|
||
|
||
服务端模式保护的是：
|
||
|
||
- 题目随机规则、难度控制、答案逻辑。
|
||
- 模板坐标、排版参数和批量内容生产能力。
|
||
- 原始 SVG/高清线稿、字体、商用素材以及素材关联关系。
|
||
- 未发布题型、主题包和会员规则。
|
||
|
||
服务端无法阻止他人观察最终 PNG/PDF 并模仿视觉效果；产品壁垒仍来自稳定的内容供给、素材版权、生成质量、运营数据和用户体验。
|
||
|
||
## 3. 目标架构
|
||
|
||
```text
|
||
小程序 / Web
|
||
└─ 仅提交受控参数：worksheetId、年龄、难度、主题、孩子姓名
|
||
↓
|
||
统一业务 API
|
||
↓
|
||
Render API（鉴权、配额、限流、参数校验）
|
||
↓
|
||
私有题型配置 + 私有素材 + 生成器 + 渲染器
|
||
↓
|
||
生成 PNG / PDF，写入对象存储
|
||
↓
|
||
返回短期签名预览/下载 URL 或异步任务状态
|
||
```
|
||
|
||
示例请求：
|
||
|
||
```json
|
||
{
|
||
"worksheetId": "coloring-animal-01",
|
||
"variant": "easy",
|
||
"childProfileId": "child_123",
|
||
"output": "png"
|
||
}
|
||
```
|
||
|
||
服务端根据 `worksheetId` 查询内部配置，生成随机种子和题目内容；客户端不能传素材 URL、任意渲染器名称、自由模板参数或数据库字段。
|
||
|
||
## 4. 数据与接口边界
|
||
|
||
### 4.1 平台无关的 worksheet 模型
|
||
|
||
当前内容数据中存在小程序专用 `path`，例如 `/mathPages/mathDraw/mathDraw?id=number-find`。v3.5 起应建立平台无关的核心字段：
|
||
|
||
```ts
|
||
type Worksheet = {
|
||
id: string;
|
||
category: string;
|
||
title: string;
|
||
ageMin: number;
|
||
ageMax: number;
|
||
difficulty: 1 | 2 | 3 | 4;
|
||
tags: string[];
|
||
rendererKey: string; // 仅服务端可解释
|
||
generatorKey: string; // 仅服务端可解释
|
||
assetRefs: string[]; // 私有资源引用
|
||
status: 'draft' | 'active' | 'hidden';
|
||
};
|
||
```
|
||
|
||
小程序路由与 Web URL 是展示层映射，不能作为内容本体。旧字段可在迁移期保留为 `miniProgramPath`，但新服务端生成不依赖它。
|
||
|
||
### 4.2 业务服务接口
|
||
|
||
页面不得再散落调用 `wx.cloud.callFunction`。逐步收口为业务接口：
|
||
|
||
```ts
|
||
worksheetService.list(filters)
|
||
worksheetService.getDetail(id)
|
||
renderService.createJob(request)
|
||
renderService.getJob(jobId)
|
||
favoriteService.toggle(worksheetId)
|
||
historyService.list()
|
||
```
|
||
|
||
小程序适配器可以暂时使用云函数，Web 使用 HTTP；上层页面不感知具体实现。
|
||
|
||
## 5. 后端演进路径
|
||
|
||
### 阶段 A：现在至创意涂色 MVP
|
||
|
||
- 保留 CloudBase 数据库、存储和既有云函数。
|
||
- 新建可通过 HTTP 调用的 Render API；可先使用 CloudBase 云托管容器，无需立即维护独立云服务器。
|
||
- 私有素材存放在不可公开枚举的对象存储路径；最终文件通过短期 URL 交付。
|
||
- 只迁移创意涂色纸，验证延迟、成本和保护边界。
|
||
|
||
### 阶段 B：Web 小规模试点
|
||
|
||
- Web 调用统一 HTTP API；小程序继续调用业务服务层。
|
||
- 新题型优先服务端生成；旧题型按商业价值与迁移成本逐步处理。
|
||
- 增加异步渲染任务、缓存、批量导出和基础监控。
|
||
|
||
### 阶段 C：扩张决策
|
||
|
||
当 Web 需要 SEO、会员支付、复杂搜索、教师版、批量 PDF、AI/异步任务，或 CloudBase 成本与能力成为瓶颈时，再迁核心 API 到 NestJS + MySQL/对象存储。
|
||
|
||
迁移的是业务 API 和数据，不是让前端重新实现一套生成逻辑。
|
||
|
||
## 6. 安全、成本与体验基线
|
||
|
||
| 维度 | v3.5 最低要求 |
|
||
| --- | --- |
|
||
| 素材保护 | 原始素材不公开；仅输出最终位图/PDF；下载链接短时有效 |
|
||
| 接口控制 | 登录/游客策略、参数白名单、按用户/IP 限流、每日生成配额 |
|
||
| 缓存 | 以题型、变体、随机种子、个性化字段计算缓存键；个性化内容谨慎缓存 |
|
||
| 任务模式 | 单张同步生成；多页学习包/PDF 使用异步任务与状态查询 |
|
||
| 可观测性 | 记录生成耗时、失败原因、缓存命中、文件大小、单位成本 |
|
||
| 体验目标 | 单张预览 P95 小于 3 秒；异步任务需有明确进度和失败重试提示 |
|
||
|
||
## 7. Web MVP 范围与升级门槛
|
||
|
||
Web MVP 仅包含：首页、10–20 个高意图主题/详情页、2–3 类生成器、预览与打印/PDF 下载。首选试点为创意涂色纸。
|
||
|
||
满足以下条件后，才扩张为完整 Kiddoleap 风格的资源平台：
|
||
|
||
- 可稳定按周上新内容，并有明确的素材/审核/发布流程。
|
||
- Web 已获得自然搜索访问、有效下载与回访，不只是小程序导流。
|
||
- 生成服务的时延、成功率和成本达到产品目标。
|
||
- 主题包或批量导出表现出明确的付费/订阅意愿。
|
||
|
||
## 8. 与既有文档的关系
|
||
|
||
本策略更新了既有架构文档中“前端为主、核心生成保持客户端执行”的长期方向：该原则仍适用于存量小程序题型的成本与离线体验，但**不适用于未来 Web 的高价值题型**。
|
||
|
||
在 v3.5 评审通过后，应同步更新《技术架构设计文档》《PC-Web端技术预案》《小程序云开发方案和数据库设计》中的阶段说明，避免文档之间出现相反结论。
|