# Doodle / 涂鸦丫 - PC Web 端技术预案

> 状态：**远期规划**（当前聚焦小程序，暂不启动 Web 开发）
> 最后更新：2026-03-24
> 配套文档：[技术架构设计文档](./技术架构设计文档.md) | [产品设计文档](./产品设计文档.md)

---

## 一、启动时机判断

### 1.1 当前不急于开发 PC Web 的原因

- 小程序用户群与目标用户（家长）高度重合，微信即触达
- PC Web 需要额外解决支付、登录、SEO 等问题
- 先把小程序做好，积累内容和用户

### 1.2 何时启动 PC Web

满足以下条件中的 **2 项以上** 时考虑启动：

- 小程序 DAU 稳定 > 1000
- 用户反馈中"想在电脑上用"的需求频繁出现
- 内容积累到 100+ 种题型
- 模板引擎已稳定运行，core/ 层与 wx.\* 完全解耦

---

## 二、技术选型

```
PC Web 技术栈：
┌────────────────────────────────────┐
│  框架：Next.js (App Router)        │
│  UI：Tailwind CSS + Radix UI       │
│  Canvas：HTML5 Canvas 2D           │
│  PDF：jsPDF + html2canvas          │
│  状态：Zustand                     │
│  部署：Vercel                      │
│                                    │
│  核心复用：                        │
│  @doodle/core (共享核心层)         │
│  └── 模板引擎、生成器、数据模型    │
│      → 直接 import 使用            │
│                                    │
│  需新建：                          │
│  • Web UI 组件                     │
│  • 平台适配层 (Web 实现)           │
│  • 用户登录（微信扫码/手机号）     │
│  • SEO 优化（SSR/SSG 题型页）     │
└────────────────────────────────────┘
```

---

## 三、后端 API 层方案

PC Web 需要一个 API 层来访问小程序云开发的数据。三种方案对比：

| 方案                      | 说明                                       | 成本                  | 推荐度     |
| ------------------------- | ------------------------------------------ | --------------------- | ---------- |
| **A: 云开发 HTTP API**    | 微信云开发提供的 HTTP 触发器，Web 直接调用 | 零额外成本            | ⭐⭐⭐⭐⭐ |
| **B: Cloudflare Workers** | 轻量 Serverless 代理层，转发请求到云开发   | 极低（免费额度充裕）  | ⭐⭐⭐⭐   |
| **C: Vercel Serverless**  | Next.js API Routes 做代理                  | 低（Vercel 免费额度） | ⭐⭐⭐     |
| **D: 独立 Node.js 服务**  | 自建 Express/Fastify 服务，独立数据库      | 较高（¥50-100/月+）   | ⭐⭐       |

**推荐路径**：先用方案 A（零成本），若遇到限制再升级到方案 B。

---

## 四、代码共享策略

### 4.1 Monorepo 结构（未来演进）

```
doodle/
├── packages/
│   └── core/                  ← 共享核心（npm 包）
│       ├── src/
│       │   ├── draw/          ← 模板引擎 + 渲染器
│       │   ├── generators/    ← 题目生成器
│       │   ├── models/        ← 数据模型
│       │   └── utils/         ← 工具函数
│       ├── package.json
│       └── tsconfig.json
├── apps/
│   ├── mini/                  ← 微信小程序
│   │   ├── miniprogram/
│   │   ├── cloudfunctions/
│   │   └── project.config.json
│   └── web/                   ← PC Web
│       ├── src/
│       │   ├── app/           ← Next.js App Router
│       │   ├── components/    ← Web UI 组件
│       │   ├── platform/      ← Web 平台适配层
│       │   └── services/      ← Web 业务服务
│       ├── package.json
│       └── next.config.js
├── pnpm-workspace.yaml
└── package.json
```

### 4.2 当前阶段的准备

当前不需要搭建 Monorepo，只需在小程序项目中做好分层即可：

1. 将 `core/` 作为独立目录组织代码
2. 确保 `core/` 内**不 import 任何 wx.\* API**
3. 模板引擎、生成器、数据模型全部放在 `core/` 中
4. 未来迁移时，将 `core/` 提取为独立 npm 包即可

### 4.3 平台适配层映射

| 适配器         | 小程序实现                                        | Web 实现                              |
| -------------- | ------------------------------------------------- | ------------------------------------- |
| CanvasAdapter  | `wx.createSelectorQuery` + Canvas 2D              | `document.getElementById` + Canvas 2D |
| ImageAdapter   | `canvas.createImage()`                            | `new Image()`                         |
| StorageAdapter | `wx.setStorageSync` / `wx.getStorageSync`         | `localStorage`                        |
| CloudAdapter   | `wx.cloud.callFunction`                           | HTTP fetch 到云开发 API               |
| ShareAdapter   | `onShareAppMessage` / `onShareTimeline`           | Web Share API / 复制链接              |
| ExportAdapter  | `canvasToTempFilePath` → `saveImageToPhotosAlbum` | `canvas.toBlob()` → 下载 / jsPDF      |

---

## 五、Web 端特有功能

| 功能             | 说明                                           |
| ---------------- | ---------------------------------------------- |
| **直接下载 PDF** | jsPDF 前端生成，无需保存到相册                 |
| **批量下载**     | 一次生成多张 → 打包 ZIP 下载                   |
| **打印预览**     | 浏览器原生 `window.print()` + CSS @media print |
| **SEO**          | SSR/SSG 生成题型介绍页，搜索引擎可抓取         |
| **用户登录**     | 微信扫码登录 / 手机号 + 验证码                 |
| **分享**         | 生成题型页面 URL，可直接分享链接               |

---

## 六、开发估算

| 阶段       | 内容                                  | 预估人时                   |
| ---------- | ------------------------------------- | -------------------------- |
| 环境搭建   | Monorepo + Next.js 项目 + core 包提取 | ~16h                       |
| 平台适配层 | 5 个适配器的 Web 实现                 | ~16h                       |
| UI 开发    | 首页 + 分类页 + 生成页 + 我的         | ~40h                       |
| 用户登录   | 微信扫码 + 手机号登录                 | ~16h                       |
| SEO 优化   | SSG 题型页 + sitemap + meta           | ~8h                        |
| 测试与上线 | 联调 + 部署 Vercel                    | ~8h                        |
| **总计**   |                                       | **~104h（约 3-4 周全职）** |

---

## 八、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 导入）
   └── 实现前端数据加载（缓存优先 + 云端更新，见 小程序云开发方案.md）
```

### 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；迁移后可为 NestJS）
```

---
