docs:完成新版本产品和技术架构设计

2026-03-25 08:50:45 +08:00
parent a34311d35e
commit 3aaf340781
4 changed files with 1772 additions and 526 deletions
@@ -0,0 +1,147 @@
+# 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 周全职）** |