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

feat:更新core 和首页代码

Browse Source
This commit is contained in:
R524809
2026-03-27 17:31:52 +08:00
parent dc5e057cb3
commit 1b45ba7d11
44 changed files with 2891 additions and 1087 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/技术架构设计文档.md
+205 -438
View File
@@ -1,8 +1,10 @@
# Doodle Mini - 技术架构设计文档
> 版本：v3.0
> 最后更新：2026-03-24
> 配套文档：[现有功能清单](./现有功能清单.md) | [产品设计文档](./产品设计文档.md) | [PC-Web端技术预案](./PC-Web端技术预案.md)
> 版本：v3.2
> 最后更新：2026-03-27
> 配套文档：[现有功能清单](./现有功能清单.md) | [产品设计文档](./产品设计文档.md) | [小程序云开发方案](./小程序云开发方案.md) | [后端部署方案](./后端部署方案.md) | [PC-Web端技术预案](./PC-Web端技术预案.md)
**后端阶段说明（重要）**：**现阶段**后端能力采用**微信小程序云开发**（云数据库、云存储、云函数），与 [小程序云开发方案](./小程序云开发方案.md) 一致。**当前阶段有效期至 2026 年 9 月 15 日**（到期前需结合用量、成本与产品路线，决定续用云开发、升级套餐或迁移至 [后端部署方案](./后端部署方案.md) 所述 NestJS + 自有服务器方案）。前端仍通过 `platform/cloud-adapter` 对接 `wx.cloud`，迁移时再抽象为 HTTP 适配层。
---
@@ -12,7 +14,7 @@
| 原则 | 说明 |
| ------------ | ------------------------------------------------------------------------------------------------- |
| **成本优先** | 优先使用微信云开发，避免自建服务器的运维和费用 |
| **成本优先** | 现阶段用云开发免费额度控制成本；**2026-09-15** 前复盘是否续用或迁移自建；核心逻辑仍保持前端执行 |
| **渐进增强** | 先小程序跑通，后续再扩展 PC Web，不为未来过度设计 |
| **前端为主** | Canvas 渲染、随机生成、PNG 导出等核心逻辑保持前端执行，零服务器成本；后端仅做必要的数据存储和服务 |
| **可迁移** | 核心绘制逻辑与平台 API 解耦，为将来迁移 Web 做准备 |
@@ -38,9 +40,10 @@
│ 需要后端（轻量级） │
├─────────────────────────────────────────────────────────┤
│ 📦 内容配置远程下发（热更新题型/分类，无需发版） │
│ 📦 静态素材存储与 CDN 分发（涂色卡线稿、折纸模板等） │
│ 📦 静态素材存储与分发（涂色卡线稿、折纸模板等） │
│ 📦 用户数据同步（收藏、历史记录跨设备） │
│ 📦 下载统计 / 热度排名 │
│ 📦 用户标识 / 鉴权（云开发侧 OpenID 等） │
│ 📦 PDF 多页合并导出（远期增值功能，非核心路径） │
│ 📦 未来 PC Web 端的 API 服务 │
└─────────────────────────────────────────────────────────┘
@@ -48,24 +51,29 @@
#### 方案对比与选择
| 维度 | 微信云开发 | 自建云服务器 | 决策 |
| ----------- | -------------------------------------------------------- | -------------------- | --------- |
| 接入成本 | ⭐ 极低（已有基础） | ⭐⭐⭐ 需搭建部署 | 云开发 ✅ |
| 运维成本 | ⭐ 免运维 | ⭐⭐⭐ 需监控/维护 | 云开发 ✅ |
| 费用 | 免费额度足够早期（数据库 2GB/存储 5GB/云函数 10万次/月） | 最低约 ¥50-100/月 | 云开发 ✅ |
| 小程序集成 | ⭐ 原生集成，鉴权零成本 | ⭐⭐ 需对接登录/鉴权 | 云开发 ✅ |
| PC Web 支持 | ⭐⭐ 需通过 HTTP API 桥接 | ⭐ 天然支持 | 自建 ✅ |
| 灵活性 | ⭐⭐ 受限于云开发 SDK | ⭐ 完全自由 | 自建 ✅ |
| 数据迁移 | ⭐⭐ 可导出但不方便 | ⭐ 标准数据库 | 自建 ✅ |
| 维度 | 微信云开发 | 自有云服务器（NestJS） | 现阶段决策（至 2026-09-15） |
| ----------- | ----------------------------- | --------------------------- | --------------------------- |
| 接入成本 | ⭐ 极低（原生集成） | ⭐⭐ 需搭建部署（~3-5天） | **云开发 ✅** |
| 运维成本 | ⭐ 免运维 | ⭐⭐ 需简单维护（PM2 守护） | **云开发 ✅** |
| 费用 | 免费额度内 ¥0；超出按套餐计费 | 已有服务器可零增量 | **云开发（阶段内）✅** |
| 小程序集成 | ⭐ 鉴权零成本 | ⭐⭐ 需对接微信登录+JWT | **云开发 ✅** |
| PC Web 支持 | ⭐⭐ 需通过 HTTP API 桥接 | ⭐ RESTful API 天然支持 | 远期再评估 NestJS |
| 灵活性 | ⭐⭐ 受限于云开发 SDK | ⭐ 完全自由 | 到期后按需评估 |
| 数据迁移 | ⭐⭐ 可导出 | ⭐ 标准 MySQL | 到期后按需评估 |
**最终决策：近期使用微信云开发，远期按需引入轻量后端**
**最终决策（分阶段）**
```
Phase 1-3（当前~8周）：100% 微信云开发
└── 云数据库 + 云存储 + 云函数，零服务器成本
现阶段（至 2026-09-15）：微信小程序云开发
└── 云数据库 + 云存储 + 云函数；详情见 → 小程序云开发方案.md
远期（需要 PC Web 时）：按需引入轻量后端
└── 详见 PC-Web端技术预案.md
阶段到期后：在 2026-09-15 前复盘，可选路径包括
① 续用云开发（含升级套餐）
② 迁移至 NestJS + 自有服务器 → 后端部署方案.md
③ 混合方案（按模块拆分）
平台适配层保持抽象：当前 cloud-adapter（wx.cloud），迁移时可替换为 http-adapter，
业务服务层接口尽量不变（见 platform/ 设计）。
```
---
@@ -100,13 +108,13 @@ Phase 1-3（当前~8周）：100% 微信云开发
│ │ 🔑 此层可直接在未来 PC Web 项目中 import 复用 │ │
│ └──────────────────────────────────────────────────────┘ │
└───────────────────────────┬────────────────────────────────────┘
│
│ wx.cloud / callFunction
▼
┌────────────────────────────────────────────────────────────────┐
│ 后端服务层 │
│ 后端服务层（现阶段：微信云开发） │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 微信云开发（零服务器成本） │ │
│ │ 微信云开发 │ │
│ │ │ │
│ │ ┌────────────┐ ┌──────────┐ ┌─────────────┐ │ │
│ │ │ 云数据库 │ │ 云存储 │ │ 云函数 │ │ │
@@ -121,11 +129,13 @@ Phase 1-3（当前~8周）：100% 微信云开发
│ └──────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ CDN (腾讯云) │ │
│ │ CDN（云开发资源） │ │
│ │ 素材图片 / 字体文件 / 预览图 / 分享图 │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
│ PC Web 远期方案见 → PC-Web端技术预案.md │
│ 云开发详细设计 → 小程序云开发方案.md │
│ 阶段到期后可选迁移 → 后端部署方案.md │
│ PC Web 远期方案 → PC-Web端技术预案.md │
└────────────────────────────────────────────────────────────────┘
```
@@ -165,22 +175,16 @@ miniprogram/
```
miniprogram/
├── core/ ← 🆕 共享核心层（平台无关）
├── core/ ← 🆕 共享核心层（平台无关，可被主包/分包复用）
│ ├── models/ ← 数据模型定义
│ │ ├── worksheet.ts ← WorksheetType 统一模型
│ │ ├── category.ts ← 分类模型
│ │ ├── user.ts ← 用户数据模型
│ │ └── print-config.ts ← 打印配置模型
│ ├── generators/ ← 题目生成算法（纯逻辑）
│ │ ├── math/ ← 数学题目生成器
│ │ │ ├── addition.ts
│ │ │ ├── subtraction.ts
│ │ │ ├── number-sequence.ts
│ │ │ └── ...
│ │ ├── focus/ ← 专注力题目生成器
│ │ ├── chinese/ ← 语文题目生成器
│ │ └── english/ ← 英语题目生成器
│ ├── draw/ ← 绘制服务（Canvas 2D API，平台无关）
│ ├── generators/ ← 题目生成算法（仅保留跨分包通用部分）
│ │ ├── common/ ← 公共算法（如随机、序列、通用算术）
│ │ └── registry.ts ← 生成器注册与装配
│ ├── draw/ ← 绘制服务（仅保留跨分包通用部分）
│ │ ├── base-draw.ts ← 基础绘制（纸面、页眉、网格等）
│ │ ├── template-engine.ts ← 🆕 模板引擎入口
│ │ ├── renderer-registry.ts ← 🆕 渲染器注册表
@@ -194,10 +198,7 @@ miniprogram/
│ │ │ ├── full-page-asset.ts
│ │ │ ├── sequence-pattern.ts
│ │ │ └── special-graphic.ts
│ │ ├── legacy/ ← 存量专用绘制服务（渐进迁移后移除）
│ │ │ ├── math-draw/
│ │ │ ├── focus-draw/
│ │ │ └── chinese-draw/
│ │ └── legacy/ ← 存量中仍可复用的通用兼容层（逐步收敛）
│ ├── data/ ← 内容配置数据
│ │ ├── worksheets.ts ← 所有题型定义（本地兜底）
│ │ ├── categories.ts ← 分类定义
@@ -211,7 +212,7 @@ miniprogram/
├── platform/ ← 🆕 平台适配层
│ ├── canvas-adapter.ts ← Canvas API 适配（wx ↔ Web）
│ ├── storage-adapter.ts ← 存储适配（wxStorage ↔ localStorage）
│ ├── cloud-adapter.ts ← 云服务适配（wx.cloud ↔ HTTP）
│ ├── cloud-adapter.ts ← 云服务适配（wx.cloud；迁移 NestJS 后可换 http-adapter）
│ ├── image-adapter.ts ← 图片加载适配
│ └── share-adapter.ts ← 分享能力适配
│
@@ -228,22 +229,27 @@ miniprogram/
│ ├── app-store.ts ← 全局状态（用户/配置/主题）
│ └── page-store.ts ← 页面级状态工具
│
├── pages/ ← 重构后的主包页面
│ ├── home/ ← 发现首页（合并原 4 个 Tab 入口）
│ ├── category/ ← 分类详情页
│ ├── worksheet/ ← 统一的题型生成/预览页
├── pages/ ← 主包（受 2MB 限制，只放高频入口与通用页）
│ ├── home/ ← 发现首页
│ ├── category/ ← 分类详情页（仅列表，不承载重绘制逻辑）
│ ├── profile/ ← 我的
│ ├── guide/ ← 打印指南
│ ├── favorites/ ← 收藏列表
│ ├── history/ ← 下载历史
│ └── settings/ ← 设置
│ └── guide/ ← 打印指南
│
├── subpackages/ ← 🆕 按品类分包
│ ├── math/ ← 数学题型页面
│ ├── chinese/ ← 语文题型页面
│ ├── english/ ← 英语题型页面
│ ├── puzzle/ ← 益智游戏页面
│ └── craft/ ← 创意手工页面
├── mathPages/ ← 数学分包
│ ├── ... ← 数学题型页面
│ └── shared/ ← 仅数学分包依赖（service/templates/assets/constants/draw/generators）
├── chinesPages/ ← 语文分包（命名可按实现统一为 chinesePages）
│ ├── ... ← 识字/练字及后续语文题型页面
│ └── shared/ ← 仅语文分包依赖（含语文专用 draw/generators）
├── englishPages/ ← 英语分包
│ ├── ... ← 字母/拼读等页面
│ └── shared/ ← 仅英语分包依赖（含英语专用 draw/generators）
├── puzzlePages/ ← 益智分包
│ ├── ... ← 迷宫/找不同/连线等页面
│ └── shared/ ← 仅益智分包依赖（含益智专用 draw/generators）
├── craftPages/ ← 创意手工分包
│ ├── ... ← 涂色卡/折纸/手工模板页面
│ └── shared/ ← 仅创意手工分包依赖（含手工专用 draw/generators）
│
├── components/ ← UI 组件
│ ├── shared/ ← 通用组件
@@ -265,6 +271,14 @@ miniprogram/
└── style/ ← 全局样式
```
> 分包约束（新增）：为控制主包体积与首屏加载，**题型页面、重绘制逻辑、题型私有素材、题型私有工具、题型私有 draw 与 generators** 必须下沉到对应分包；仅该分包使用的依赖统一放到该分包的 `shared/` 目录中（延续当前 `mathPages/shared`、`focusPages/shared` 的组织方式）。
>
> 归属原则（draw / generators）：
>
> 1. **跨分包复用**（2 个及以上分包共用）→ 放 `core/draw`、`core/generators`；
> 2. **仅单一分包使用** → 放对应 `<xxx>Pages/shared/draw`、`<xxx>Pages/shared/generators`；
> 3. 如后续从“单分包”演进为“跨分包”，再从分包 `shared` 上提到 `core`，避免过早抽象导致主包膨胀。
### 3.3 分层职责
```
@@ -534,71 +548,71 @@ interface WorksheetConfig {
status: 'active' | 'draft' | 'hidden';
// ─── 模板引擎配置（渲染用）───
template: TemplateType; // 使用哪个排版模板
generator: GeneratorType; // 使用哪个数据生成器
generatorConfig: Record<string, any>; // 生成器参数（不同生成器不同）
layoutConfig: LayoutConfig; // 排版参数
userConfigurable?: UserConfigField[]; // 用户可调整的参数定义
template: TemplateType; // 使用哪个排版模板
generator: GeneratorType; // 使用哪个数据生成器
generatorConfig: Record<string, any>; // 生成器参数（不同生成器不同）
layoutConfig: LayoutConfig; // 排版参数
userConfigurable?: UserConfigField[]; // 用户可调整的参数定义
}
/**
* 排版模板枚举（前端代码实现，新增需发版）
*/
type TemplateType =
| 'grid-exercise' // 模式 A：网格计算型
| 'match-connect' // 模式 B：配对连线型
| 'grid-coloring' // 模式 C：网格涂色型
| 'card-layout' // 模式 D：卡片排列型
| 'tracing-writing' // 模式 E：描红书写型
| 'full-page-asset' // 模式 F：全幅素材型
| 'sequence-pattern' // 模式 G：序列/排序型
| 'special-graphic'; // 模式 H：时钟/特殊图形型
| 'grid-exercise' // 模式 A：网格计算型
| 'match-connect' // 模式 B：配对连线型
| 'grid-coloring' // 模式 C：网格涂色型
| 'card-layout' // 模式 D：卡片排列型
| 'tracing-writing' // 模式 E：描红书写型
| 'full-page-asset' // 模式 F：全幅素材型
| 'sequence-pattern' // 模式 G：序列/排序型
| 'special-graphic'; // 模式 H：时钟/特殊图形型
/**
* 数据生成器枚举（前端代码实现，新增需发版）
*/
type GeneratorType =
| 'arithmetic' // 加减乘除运算题
| 'number-sequence' // 数列/排序
| 'number-decompose' // 数的分与合
| 'counting' // 数数类
| 'comparison' // 比大小
| 'shape-grid' // 图形网格
| 'color-pattern' // 颜色规律
| 'character-tracing' // 汉字描红（需 SVG 笔画数据）
| 'letter-tracing' // 字母描红
| 'pinyin-tracing' // 拼音描红
| 'static-asset' // 静态素材（不生成，直接用素材）
| 'maze' // 迷宫算法
| 'dot-connect' // 点连线
| 'clock' // 时钟
| 'custom'; // 自定义（需指定 customGeneratorId）
| 'arithmetic' // 加减乘除运算题
| 'number-sequence' // 数列/排序
| 'number-decompose' // 数的分与合
| 'counting' // 数数类
| 'comparison' // 比大小
| 'shape-grid' // 图形网格
| 'color-pattern' // 颜色规律
| 'character-tracing' // 汉字描红（需 SVG 笔画数据）
| 'letter-tracing' // 字母描红
| 'pinyin-tracing' // 拼音描红
| 'static-asset' // 静态素材（不生成，直接用素材）
| 'maze' // 迷宫算法
| 'dot-connect' // 点连线
| 'clock' // 时钟
| 'custom'; // 自定义（需指定 customGeneratorId）
/**
* 排版配置
*/
interface LayoutConfig {
columns?: number; // 列数
rows?: number; // 行数
fontSize?: number; // 字号
showBorder?: boolean; // 是否显示边框
showTitle?: boolean; // 是否显示标题
padding?: number; // 内边距
itemSpacing?: number; // 元素间距
showInstruction?: boolean; // 是否显示题目说明文字
instructionText?: string; // 说明文字内容
columns?: number; // 列数
rows?: number; // 行数
fontSize?: number; // 字号
showBorder?: boolean; // 是否显示边框
showTitle?: boolean; // 是否显示标题
padding?: number; // 内边距
itemSpacing?: number; // 元素间距
showInstruction?: boolean; // 是否显示题目说明文字
instructionText?: string; // 说明文字内容
}
/**
* 用户可配置的参数定义（渲染到参数设置面板）
*/
interface UserConfigField {
key: string; // 对应 generatorConfig 中的 key
label: string; // 显示名称
key: string; // 对应 generatorConfig 中的 key
label: string; // 显示名称
type: 'select' | 'slider' | 'switch';
options?: { label: string; value: any }[]; // select 类型的选项
min?: number; // slider 最小值
max?: number; // slider 最大值
options?: { label: string; value: any }[]; // select 类型的选项
min?: number; // slider 最小值
max?: number; // slider 最大值
defaultValue: any;
}
```
@@ -737,7 +751,11 @@ abstract class BaseTemplateRenderer {
this.paper = paper;
}
async render(data: any, layout: LayoutConfig, printConfig: PrintConfig): Promise<void> {
async render(
data: any,
layout: LayoutConfig,
printConfig: PrintConfig,
): Promise<void> {
this.drawBackground();
this.drawHeader(printConfig);
if (layout.showInstruction) {
@@ -747,7 +765,10 @@ abstract class BaseTemplateRenderer {
this.drawFooter(printConfig);
}
protected abstract drawContent(data: any, layout: LayoutConfig): Promise<void>;
protected abstract drawContent(
data: any,
layout: LayoutConfig,
): Promise<void>;
}
/**
@@ -804,12 +825,15 @@ class TemplateEngine {
async render(
worksheetConfig: WorksheetConfig,
userParams: Record<string, any>, // 用户在 UI 上调整的参数
userParams: Record<string, any>, // 用户在 UI 上调整的参数
ctx: CanvasRenderingContext2D,
printConfig: PrintConfig,
): Promise<void> {
// 1. 合并用户参数到 generatorConfig
const mergedConfig = { ...worksheetConfig.generatorConfig, ...userParams };
const mergedConfig = {
...worksheetConfig.generatorConfig,
...userParams,
};
// 2. 选择生成器，生成题目数据
const generator = this.generatorRegistry.get(worksheetConfig.generator);
@@ -839,7 +863,7 @@ createPage({
const config = WorksheetService.getConfig(worksheetId);
this.setData({
title: config.title,
userFields: config.userConfigurable, // 动态渲染参数面板
userFields: config.userConfigurable, // 动态渲染参数面板
userParams: getDefaultParams(config),
});
},
@@ -927,124 +951,34 @@ createPage({
---
## 六、后端（云开发）详细设计
## 六、后端概要设计
### 6.1 云数据库集合设计
> **现阶段（至 2026-09-15）**：云数据库、云存储、云函数及调用策略的**完整设计**见 → [小程序云开发方案](./小程序云开发方案.md)。
> **阶段到期后可选迁移**：NestJS 项目结构、Prisma、REST API、部署等见 → [后端部署方案](./后端部署方案.md)。
```
云数据库 Collections:
┌─────────────────────────────────────────────────┐
│ │
│ worksheets (题型配置表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string │ │
│ │ category: string │ │
│ │ subcategory: string │ │
│ │ title: string │ │
│ │ desc: string │ │
│ │ ageRange: [number, number] │ │
│ │ difficulty: 1|2|3|4 │ │
│ │ previewImage: string │ │
│ │ tags: string[] │ │
│ │ isNew: boolean │ │
│ │ isHot: boolean │ │
│ │ sortOrder: number │ │
│ │ downloadCount: number │ │
│ │ status: 'active'|'draft'|'hidden' │ │
│ │ │ │
│ │ ── 模板引擎字段 ── │ │
│ │ template: TemplateType │ ← 渲染模板│
│ │ generator: GeneratorType │ ← 生成器 │
│ │ generatorConfig: object │ ← 生成参数│
│ │ layoutConfig: object │ ← 排版参数│
│ │ userConfigurable: array │ ← 用户可调│
│ │ legacyPage: string | null │ ← 旧页面 │
│ │ │ │
│ │ createdAt: Date │ │
│ │ updatedAt: Date │ │
│ └─────────────────────────────────────┘ │
│ │
│ categories (分类表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string │ │
│ │ name: string │ │
│ │ icon: string │ │
│ │ color: string │ │
│ │ sortOrder: number │ │
│ │ parentId: string | null │ │
│ └─────────────────────────────────────┘ │
│ │
│ users (用户表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string (openid) │ │
│ │ uuid: string │ │
│ │ nickName: string │ │
│ │ avatarUrl: string │ │
│ │ totalDownloads: number │ │
│ │ createdAt: Date │ │
│ │ lastActiveAt: Date │ │
│ └─────────────────────────────────────┘ │
│ │
│ favorites (收藏表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string │ │
│ │ _openid: string │ │
│ │ worksheetId: string │ │
│ │ createdAt: Date │ │
│ └─────────────────────────────────────┘ │
│ │
│ download_logs (下载日志表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string │ │
│ │ _openid: string │ │
│ │ worksheetId: string │ │
│ │ params: object (生成参数快照) │ │
│ │ createdAt: Date │ │
│ └─────────────────────────────────────┘ │
│ │
│ feedback (用户反馈表) │
│ ┌─────────────────────────────────────┐ │
│ │ _id: string │ │
│ │ _openid: string │ │
│ │ content: string │ │
│ │ contact: string │ │
│ │ createdAt: Date │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────┘
```
### 6.1 现阶段：微信云开发（摘要）
### 6.2 云函数设计
| 组件 | 技术 | 说明 |
| ---------- | ---------------------------- | -------------------------------------- |
| 数据 | 云数据库（文档型） | worksheets / categories / users 等集合 |
| 文件 | 云存储（COS） | 预览图、涂色线稿、字体等 |
| 逻辑 | 云函数（Node.js） | 统一入口路由、业务 action |
| 小程序接入 | `wx.cloud` + `cloud-adapter` | 与业务服务层解耦，便于日后替换为 HTTP |
```
cloudfunctions/
└── doodle/
├── index.js ← 统一入口（action 路由）
├── package.json
├── src/
│ ├── user/
│ │ ├── getOpenId.js ← ✅ 已有，保留
│ │ └── updateProfile.js ← 🆕 更新用户信息
│ ├── worksheet/
│ │ ├── getList.js ← 🆕 获取题型列表（支持分类/筛选）
│ │ ├── getDetail.js ← 🆕 获取题型详情
│ │ └── incrementDownload.js← 🆕 下载计数+1
│ ├── favorite/
│ │ ├── add.js ← 🆕 添加收藏
│ │ ├── remove.js ← 🆕 取消收藏
│ │ └── list.js ← 🆕 我的收藏列表
│ ├── history/
│ │ └── list.js ← 🆕 下载历史
│ ├── feedback/
│ │ └── submit.js ← 🆕 提交反馈
│ └── pdf/
│ └── generate.js ← 🆕 PDF 生成（远期增值功能，会员专属）
└── common/
├── responseMiddleware.js ← ✅ 已有，保留
└── auth.js ← 🆕 鉴权中间件
```
### 6.2 远期可选：自建 NestJS（摘要）
### 6.3 云函数调用策略
| 组件 | 技术 | 说明 |
| ---- | ----------------------- | --------------------------- |
| 应用 | NestJS + TypeScript | RESTful API，多端统一 |
| 数据 | MySQL 8.0 + Prisma | 关系型存储与迁移 |
| 文件 | 本地磁盘 + Nginx | 静态素材 URL 由自有域名提供 |
| 鉴权 | 微信 code2Session + JWT | 小程序与 Web 可共用逻辑 |
（接口路径、表结构、部署步骤等以 [后端部署方案](./后端部署方案.md) 为准，此处不重复。）
### 6.3 数据加载策略（两阶段一致的产品策略）
无论后端是云开发还是 HTTP API，**客户端侧优先级**保持一致：
```
┌────────────────────────────────────────────────────────────┐
@@ -1053,7 +987,7 @@ cloudfunctions/
│ 题型配置数据 (worksheets/categories) │
│ ┌────────────────────────────────────────┐ │
│ │ 优先级 1: 本地缓存（wx.Storage） │ │
│ │ 优先级 2: 云数据库查询 │ │
│ │ 优先级 2: 云端拉取（云 DB 或 HTTP API） │ │
│ │ 优先级 3: 前端内置兜底数据 │ ← 保证离线可用 │
│ └────────────────────────────────────────┘ │
│ │
@@ -1062,49 +996,19 @@ cloudfunctions/
│ • 后续启动：先用缓存渲染 → 后台静默更新 │
│ • 缓存有效期：24 小时 │
│ • 无网络：使用本地缓存或内置兜底 │
│ │
│ 用户数据 (favorites/history) │
│ ┌────────────────────────────────────────┐ │
│ │ 本地优先写入 → 后台同步云端 │ │
│ │ 冲突策略：以云端为准（云端时间戳更新） │ │
│ └────────────────────────────────────────┘ │
│ │
│ 统计数据 (download count) │
│ ┌────────────────────────────────────────┐ │
│ │ 批量上报：本地累计 → 退出时/定时上报 │ │
│ │ 非关键路径，允许丢失 │ │
│ └────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
```
### 6.4 云存储规划
### 6.4 静态素材 URL（现阶段）
素材使用 **云存储 fileID / 临时 URL**，例如：
```
云存储目录结构：
cloud://doodle-xxx.xxxx/
├── assets/
│ ├── previews/ ← 题型效果预览图
│ │ ├── math/
│ │ ├── chinese/
│ │ ├── english/
│ │ ├── puzzle/
│ │ └── craft/
│ ├── coloring/ ← 涂色卡线稿（SVG/PNG）
│ │ ├── animals/
│ │ ├── vehicles/
│ │ ├── holidays/
│ │ └── ...
│ ├── origami/ ← 折纸展开图
│ ├── stickers/ ← 贴纸素材
│ ├── maze-templates/ ← 迷宫模板数据（JSON）
│ └── craft-templates/ ← 手工模板
├── fonts/ ← 字体文件
│ ├── SimHei.ttf
│ └── handwriting.ttf
└── share/ ← 分享图
└── default-share.png
cloud://doodle-xxx.xxxx/assets/coloring/animals/dinosaur-01.svg
```
（目录规划见 [小程序云开发方案](./小程序云开发方案.md) 第六节。迁移自建后改为 `https://你的域名/static/...`。）
---
## 七、关键技术方案
@@ -1177,7 +1081,7 @@ class WxImageAdapter implements IImageAdapter {
│ 微信聊天直接发图片，接收方零门槛查看 │
│ │
│ 4. 零服务器成本 │
│ Canvas 本地渲染，不消耗云函数算力和存储 │
│ Canvas 本地渲染，不消耗云函数算力与云存储（主路径） │
│ 用户量增长不会带来额外成本 │
│ │
│ 5. 技术架构成熟 │
@@ -1189,7 +1093,7 @@ class WxImageAdapter implements IImageAdapter {
→ 用户打印时多选图片即可
PDF 导出方案（远期增值功能，会员专属）：
小程序：客户端渲染多张 PNG → 上传云存储 → 云函数用 pdfkit 合并为 PDF
小程序：客户端渲染多张 PNG → 上传云存储 → 云函数 pdfkit 合并为 PDF（迁移自建后同逻辑可落在 NestJS）
定位：会员订阅的差异化权益，非核心路径
```
@@ -1233,167 +1137,28 @@ PDF 导出方案（远期增值功能，会员专属）：
└──────────────────────────────────────────────────────┘
```
---
## 八、PC Web 端技术预案（远期）
> PC Web 端属于远期规划，详细方案见独立文档：[PC-Web端技术预案](./PC-Web端技术预案.md)
>
> **当前阶段的准备**：只需确保 `core/` 层内不 import 任何 `wx.*` API，未来迁移时提取为独立 npm 包即可。
---
## 九、前端重构路线图
### Phase 1：基础重构（第 1-2 周）
```
优先级：🔴 关键
目标：不改变现有功能，优化代码结构
1. 修复技术债务
├── 统一云函数名称（callCloud 中 robotaxi → doodle）
├── 清理 cloudfunctions/doodle/index.js 中无效的模块引用
├── 移除 debug 页中指向不存在页面的死链
└── 清理未使用的代码和资源
2. 建立 core/ 目录
├── 将 constants/ 迁移到 core/data/
├── 将纯工具函数迁移到 core/utils/
├── 将 DrawService 基类提取到 core/draw/
└── 定义统一的 WorksheetType 数据模型
3. 建立 platform/ 目录
├── 抽取 canvas-adapter（封装 wx Canvas API）
├── 抽取 storage-adapter（封装 wx.Storage）
└── 抽取 image-adapter（封装图片加载）
4. 统一 WXML 模板
└── 合并 mathPages 和 focusPages 的重复 canvas-page-template
```
### Phase 2：模板引擎 + 首页重构 + 配置化（第 3-5 周）
```
优先级：🟡 重要（模板引擎是后续扩展的基础）
1. 模板引擎核心开发
├── 实现 BaseTemplateRenderer 基类
├── 实现 TemplateEngine 入口（配置解析 + 渲染器/生成器调度）
├── 实现 RendererRegistry / GeneratorRegistry
├── 开发通用 worksheet 页面（pages/worksheet/worksheet）
│ └── 根据 JSON 配置动态渲染参数面板 + Canvas 预览
├── 优先实现 3 种高复用模板渲染器：
│ ├── grid-exercise（网格计算型，覆盖 ~15 种现有数学题）
│ ├── full-page-asset（全幅素材型，覆盖涂色卡/折纸等新内容）
│ └── tracing-writing（描红书写型，覆盖练字/字母/拼音）
└── 将 2-3 种现有题型试点迁移到模板引擎（验证可行性）
2. 数据模型升级
├── WorksheetConfig 增加 template/generator/layoutConfig 等字段
├── 定义 Category 模型
├── 重构 MATH_FUNCTION_TYPES / FOCUS_FUNCTION_TYPES 为统一 JSON 格式
└── 编写存量题型的 JSON 配置映射
3. 首页重构
├── 新建 pages/home/ 替代原四个 Tab 入口页
├── 实现分类标签栏 + 搜索 + 推荐区
├── 实现年龄筛选、难度筛选
└── 使用新的 worksheet-card 组件（带预览图）
4. TabBar 重构
└── 发现 | 分龄 | 收藏 | 我的
5. 云数据库初始化
├── 建表：worksheets（含模板引擎字段）、categories
├── 编写数据初始化脚本（存量题型 JSON 导入）
└── 实现前端数据加载（缓存优先 + 云端更新）
```
### Phase 3：模板扩展 + 新内容接入（第 6-8 周）
```
优先级：🟡 重要
1. 补全剩余模板渲染器
├── match-connect（配对连线型）
├── grid-coloring（网格涂色型）
├── card-layout（卡片排列型）
├── sequence-pattern（序列/排序型）
└── special-graphic（时钟/特殊图形型）
2. 新增题型（通过 JSON 配置 + 素材上传，大部分无需写新代码）
├── 数学：时钟练习（需 special-graphic 渲染器）
├── 语文：拼音练习（复用 tracing-writing）
├── 英语：字母描红（复用 tracing-writing + letter-tracing 生成器）
├── 英语：字母闪卡（复用 card-layout + static-asset）
├── 益智：控笔练习（复用 tracing-writing）
└── 创意：涂色卡（复用 full-page-asset，仅需上传素材）
3. 存量题型批量迁移
├── 批次 1：grid-exercise 类 (~15 种)
├── 批次 2：match-connect 类 (~6 种)
└── 批次 3：grid-coloring 类 (~8 种)
4. 完善新分包
├── english/ 分包
├── puzzle/ 分包
└── craft/ 分包
```
### Phase 4：体验与功能升级（第 9-10 周）
```
优先级：🟢 增强
1. 用户体系
├── 微信登录
├── 收藏功能（本地 + 云端同步）
└── 下载历史
2. 打印体验
├── 打印指南页面
├── 批量生成图片（多张保存到相册）
└── 客户端渲染性能优化
3. 运营能力
├── 数据埋点完善
├── 下载统计展示（热门排行）
└── 用户反馈入口
4. 远期增值功能
└── PDF 导出（会员专属，云函数合并 PNG 为 PDF）
```
---
## 十、成本预估
### 9.1 微信云开发费用
### 10.1 后端费用
```
免费额度（基础版 1）：
现阶段（微信云开发，至 2026-09-15 复盘）：
┌────────────────────────────────────────┐
│ 云数据库：2 GB 存储 / 50 万次读写/天 │
│ 云存储：5 GB / 2 GB 下载/天 │
│ 云函数：10 万次调用/月 / 1000 GBs/月 │
│ CDN：5 GB/月 │
└────────────────────────────────────────┘
预估用量（DAU 1000）：
┌────────────────────────────────────────┐
│ 云数据库：~100 MB（足够） │
│ 云存储：~2 GB（素材渐增） │
│ 云函数：~3 万次/月 │
│ CDN：~3 GB/月 │
│ 免费额度内：云数据库 / 云存储 / 云函数 │
│ 预估早期 DAU 下可落在免费额度内 │
│ 超出后按套餐计费（如 19.9 元/月起） │
│ │
│ 结论：免费额度可覆盖到 DAU 3000 左右 │
│ 超出后升级到 19.9 元/月即可 │
│ 详见 → 小程序云开发方案.md 第七节 │
└────────────────────────────────────────┘
到期后若迁移自建（参考 后端部署方案.md）：
┌────────────────────────────────────────┐
│ 已有云服务器可做到增量 ¥0（仅运维） │
│ 需在 2026-09-15 前对比两路径总成本 │
└────────────────────────────────────────┘
```
### 9.2 开发资源
### 10.2 开发资源
```
开发投入估算：
@@ -1415,44 +1180,46 @@ PDF 导出方案（远期增值功能，会员专属）：
## 十一、技术风险与应对
| 风险 | 影响 | 应对方案 |
| -------------------- | ------------------ | ----------------------------------------------------------------- |
| 云开发免费额度不够 | 功能受限 | ① 优化查询减少调用 ② 本地缓存减少读取 ③ 升级付费版（19.9元/月起） |
| Canvas 兼容性 | 低端机渲染异常 | ① 使用 Canvas 2D（已采用）② 控制单次绘制复杂度 ③ 降级方案 |
| 小程序包体积 | 超 2MB 限制 | ① 素材用 CDN / 云存储 ② 合理分包 ③ 图片压缩 |
| 素材制作瓶颈 | 涂色卡等需设计资源 | ① 使用开源 SVG 素材 ② AI 生成线稿 ③ 社区投稿 |
| 跨平台迁移成本 | Web 端重复开发 | ① core/ 层保持平台无关 ② 适配器模式隔离差异（详见 [PC-Web端技术预案](./PC-Web端技术预案.md)） |
| 风险 | 影响 | 应对方案 |
| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |
| 云开发免费额度不足 | 功能受限或需付费 | ① 优化查询与缓存 ② 控制云函数调用 ③ **2026-09-15 前**复盘是否升级套餐或迁移 [后端部署方案](./后端部署方案.md) |
| 服务器宕机（迁移自建后） | 后端不可用 | ① PM2 自动重启 ② 前端兜底数据 ③ 定期备份数据库 |
| Canvas 兼容性 | 低端机渲染异常 | ① 使用 Canvas 2D（已采用）② 控制单次绘制复杂度 ③ 降级方案 |
| 小程序包体积 | 超 2MB 限制 | ① 素材用云存储 / CDN ② 合理分包 ③ 图片压缩 |
| 素材制作瓶颈 | 涂色卡等需设计资源 | ① 使用开源 SVG 素材 ② AI 生成线稿 ③ 社区投稿 |
| 跨平台迁移成本 | Web 端重复开发 | ① core/ 层保持平台无关 ② 适配器隔离差异（详见 [PC-Web端技术预案](./PC-Web端技术预案.md)） |
| 带宽与加载（迁移自建远期） | 素材加载慢 | ① 图片压缩 ② 长缓存 ③ 可接入 CDN |
---
## 附录 A：现有代码与目标架构映射
| 现有文件 | 目标位置 | 迁移动作 |
| -------------------------------- | -------------------------------------- | --------------------- |
| `constants/mathFunctions.ts` | `core/data/worksheets.ts` | 合并，增加字段 |
| `constants/focusFunctions.ts` | `core/data/worksheets.ts` | 合并，增加字段 |
| `constants/words.ts` | `core/data/words.ts` | 移动 |
| `constants/colors.ts` | `core/data/colors.ts` | 移动 |
| `constants/shapes.ts` | `core/data/shapes.ts` | 移动 |
| `service/baseDraw.ts` | `core/draw/base-draw.ts` | 重构，去除 wx.\* 依赖 |
| `service/wordDrawService.ts` | `core/draw/chinese-draw/word-draw.ts` | 移动，去除 wx.\* |
| `service/drawServiceFactory.ts` | `core/draw/draw-factory.ts` | 扩展 |
| `mathPages/shared/service/*.ts` | `core/draw/legacy/math-draw/*.ts` | 移入 legacy，去除 wx.\*，逐步迁移到模板引擎 |
| `focusPages/shared/service/*.ts` | `core/draw/legacy/focus-draw/*.ts` | 移入 legacy，去除 wx.\*，逐步迁移到模板引擎 |
| `base/pageMixin.ts` | `services/print-service.ts` + 页面代码 | 拆分职责 |
| `base/callCloud.ts` | `platform/cloud-adapter.ts` | 重构 |
| `utils/saveImage.ts` | `platform/canvas-adapter.ts` | 合并到适配器 |
| `utils/downloadPrint.ts` | `services/print-service.ts` | 整合 |
| `utils/tracker.ts` | `services/stats-service.ts` | 整合 |
| `config/config.ts` | `core/models/print-config.ts` | 类型化 |
| 现有文件 | 目标位置 | 迁移动作 |
| -------------------------------- | -------------------------------------- | ------------------------------------------------ |
| `constants/mathFunctions.ts` | `core/data/worksheets.ts` | 合并，增加字段 |
| `constants/focusFunctions.ts` | `core/data/worksheets.ts` | 合并，增加字段 |
| `constants/words.ts` | `core/data/words.ts` | 移动 |
| `constants/colors.ts` | `core/data/colors.ts` | 移动 |
| `constants/shapes.ts` | `core/data/shapes.ts` | 移动 |
| `service/baseDraw.ts` | `core/draw/base-draw.ts` | 重构，去除 wx.\* 依赖 |
| `service/wordDrawService.ts` | `core/draw/chinese-draw/word-draw.ts` | 移动，去除 wx.\* |
| `service/drawServiceFactory.ts` | `core/draw/draw-factory.ts` | 扩展 |
| `mathPages/shared/service/*.ts` | `core/draw/legacy/math-draw/*.ts` | 移入 legacy，去除 wx.\*，逐步迁移到模板引擎 |
| `focusPages/shared/service/*.ts` | `core/draw/legacy/focus-draw/*.ts` | 移入 legacy，去除 wx.\*，逐步迁移到模板引擎 |
| `base/pageMixin.ts` | `services/print-service.ts` + 页面代码 | 拆分职责 |
| `base/callCloud.ts` | `platform/cloud-adapter.ts` | 封装 wx.cloud；迁移 NestJS 后再考虑 http-adapter |
| `utils/saveImage.ts` | `platform/canvas-adapter.ts` | 合并到适配器 |
| `utils/downloadPrint.ts` | `services/print-service.ts` | 整合 |
| `utils/tracker.ts` | `services/stats-service.ts` | 整合 |
| `config/config.ts` | `core/models/print-config.ts` | 类型化 |
## 附录 B：技术选型决策记录
| 决策点 | 选项 | 决策 | 理由 |
| -------------- | ---------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| 跨端框架 | Taro / uni-app / 原生 | **原生** | 项目已用原生开发，迁移成本高；Taro 等框架对 Canvas 2D 支持有限；core/ 层抽取足以实现代码复用 |
| 状态管理 | MobX / 自定义 / 原生 setData | **轻量自定义** | 小程序场景简单，不需要 Redux 级方案；页面级 setData + 全局 Store 够用 |
| UI 组件库 | Vant / 自研 | **Vant + 自定义组件** | 已用 Vant，保持；业务组件自研 |
| 云开发 vs 自建 | 云开发 / 云服务器 | **云开发** | 零运维、免费额度充足、原生集成鉴权 |
| 导出方案 | PNG 保存相册 / PDF | **PNG 为主，PDF 为增值** | PNG 保存到相册是手机端最短路径（用户教育成本低、零服务器开销）；PDF 作为远期会员增值功能，小程序用云端 pdfkit 合并，Web 用 jsPDF |
| Monorepo | pnpm workspace / Turborepo | **暂不采用** | 当前只有小程序，过早引入增加复杂度；core/ 作为目录组织，未来再拆包 |
| 决策点 | 选项 | 决策 | 理由 |
| --------- | ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 跨端框架 | Taro / uni-app / 原生 | **原生** | 项目已用原生开发，迁移成本高；Taro 等框架对 Canvas 2D 支持有限；core/ 层抽取足以实现代码复用 |
| 状态管理 | MobX / 自定义 / 原生 setData | **轻量自定义** | 小程序场景简单，不需要 Redux 级方案；页面级 setData + 全局 Store 够用 |
| UI 组件库 | Vant / 自研 | **Vant + 自定义组件** | 已用 Vant，保持；业务组件自研 |
| 后端方案 | 云开发 / 自有云服务器 | **现阶段云开发（至 2026-09-15）** | 详见 [小程序云开发方案](./小程序云开发方案.md)；到期后可选迁移 [后端部署方案](./后端部署方案.md)（NestJS） |
| 导出方案 | PNG 保存相册 / PDF | **PNG 为主，PDF 为增值** | PNG 保存到相册是手机端最短路径（用户教育成本低、零服务器开销）；PDF 作为远期会员增值功能，服务端 pdfkit 合并，Web 用 jsPDF |
| Monorepo | pnpm workspace / Turborepo | **暂不采用** | 当前只有小程序，过早引入增加复杂度；core/ 作为目录组织，未来再拆包 |