153 lines
5.0 KiB
Markdown
153 lines
5.0 KiB
Markdown
# 智绘微刻小程序开发说明
|
||
|
||
## 项目简介
|
||
|
||
智绘微刻（Smart-Engraving）微信小程序，为用户提供词云生成 + 个性化激光雕刻定制服务。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Taro 3.x + React 18 + TypeScript
|
||
- **样式**: SCSS
|
||
- **目标平台**: 微信小程序（可扩展 H5）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
smart-engraving-miniapp/
|
||
├── config/ # Taro 配置文件
|
||
├── docs/ # 项目文档
|
||
│ └── mask-config-guide.md # 遮罩尺寸配置指南
|
||
├── src/
|
||
│ ├── app.tsx # 应用入口
|
||
│ ├── app.scss # 全局样式
|
||
│ ├── app.config.ts # 应用配置（页面路由、tabBar等）
|
||
│ ├── types/
|
||
│ │ └── index.ts # TypeScript 类型定义
|
||
│ ├── utils/
|
||
│ │ └── productConfig.ts # 产品品类配置
|
||
│ ├── pages/
|
||
│ │ ├── index/ # 首页
|
||
│ │ ├── wordcloud/ # 词云生成
|
||
│ │ ├── diy/ # DIY 工作台
|
||
│ │ ├── orders/ # 订单列表
|
||
│ │ └── profile/ # 个人中心
|
||
│ └── components/ # 公共组件（可按需拆分）
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── project.config.json # 微信开发者工具配置
|
||
```
|
||
|
||
## 页面说明
|
||
|
||
| 页面 | 路径 | 功能 |
|
||
|---|---|---|
|
||
| 首页 | `/pages/index/index` | 品类入口、案例展示、快捷导航 |
|
||
| 词云生成 | `/pages/wordcloud/index` | 三步式词云生成（上传底图→输入名单→生成预览） |
|
||
| DIY工作台 | `/pages/diy/index` | 选品类→上传图片→拖拽缩放→预览下单 |
|
||
| 订单 | `/pages/orders/index` | 订单列表与管理 |
|
||
| 个人中心 | `/pages/profile/index` | 用户信息、设计稿、客服入口 |
|
||
|
||
## 核心交互流程
|
||
|
||
### 流程一：词云生成 → 定制
|
||
1. 首页点击「AI词云生成」
|
||
2. 上传底图（或选模板）
|
||
3. 输入名字名单（手动输入/批量导入）
|
||
4. 生成词云，预览效果
|
||
5. 点击「前往个性化定制」跳转 DIY 工作台
|
||
|
||
### 流程二：直接定制
|
||
1. 首页选择品类（笔记本/杯垫/笔盒/书灯）
|
||
2. 进入 DIY 工作台上传图片
|
||
3. 拖拽调整位置，缩放至合适大小
|
||
4. 预览确认后下单
|
||
|
||
## 关键配置
|
||
|
||
### 遮罩尺寸
|
||
详见 `docs/mask-config-guide.md`。当实际产品尺寸确定后，仅需修改 `src/utils/productConfig.ts` 中的 `PRODUCTS` 数组。
|
||
|
||
### 后端接口（待接入）
|
||
当前代码中以下功能需要接入后端 API：
|
||
1. 词云生成：调用 `/api/wordcloud/generate` 提交底图+名单，生成词云图
|
||
2. 图片保存：调用 `/api/upload` 上传用户设计图
|
||
3. 订单创建：调用 `/api/order/create` 提交订单
|
||
|
||
## 启动开发
|
||
|
||
### 安装依赖
|
||
```bash
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
```
|
||
|
||
### 开发模式（微信小程序）
|
||
```bash
|
||
npm run dev:weapp
|
||
```
|
||
|
||
### 构建（微信小程序）
|
||
```bash
|
||
npm run build:weapp
|
||
```
|
||
|
||
### H5 预览
|
||
```bash
|
||
npm run dev:h5
|
||
```
|
||
|
||
## 图片资源与包体积说明
|
||
|
||
当前项目的产品实物照片（`src/img/`）已内置在小程序中。由于微信小程序**预览/上传代码包体积上限为 2MB**，大量高分辨率照片会导致超限。
|
||
|
||
### 已采取的措施（两步压缩脚本）
|
||
|
||
- `compress-images.js`（基于 [sharp](https://sharp.pixelplumbing.com/)）已配置到项目中，支持批量：
|
||
1. **resize**：最大边长限制到 800px
|
||
2. **format**：PNG → JPG
|
||
3. **quality**：JPG 质量 60%
|
||
- 执行一次即可：`node compress-images.js`
|
||
- 当前编译后 `dist/` 总大小约 **1.02 MB**，满足微信限制。
|
||
|
||
### ⚠️ 注意：压缩 ≠ 长期方案
|
||
|
||
压缩后的图片在手机上画质会有可见损失（尤其缩放到全屏轮播时）。**建议上线前迁移到 CDN**：
|
||
|
||
1. 注册 **腾讯云 COS**（微信小程序配套，国内访问最快）或 **阿里云 OSS**。
|
||
2. 将 `src/img/` 中的实物照片上传到对象存储。
|
||
3. 拿到每个图片的 **HTTPS 外链 URL**。
|
||
4. 修改 `src/utils/productConfig.ts` 中各产品的 `images` 字段，从本地路径 `/img/xxx.jpg` 替换为网络 URL：
|
||
```ts
|
||
// 改之前
|
||
images: ['/img/penbox/The1.jpg']
|
||
// 改之后
|
||
images: ['https://your-bucket.cos.ap-guangzhou.myqcloud.com/penbox/The1.jpg']
|
||
```
|
||
5. 修改 `config/index.js`，缩小 `copy.patterns` 范围（只 copy icon/占位图等小文件），或直接移除 `src/img` 的 copy 规则，减少构建体积。
|
||
|
||
**迁移优点**：
|
||
- 图片清晰度恢复到原图级别；
|
||
- 小程序包体积长期保持 < 500KB；
|
||
- 后续更换产品图只需在图床后台操作，无需重新发版。
|
||
|
||
---
|
||
|
||
## 下一步开发计划
|
||
|
||
### 高优先级
|
||
- [ ] 接入后端词云生成 API，替换模拟数据
|
||
- [ ] 实现图片上传接口
|
||
- [ ] 实现订单创建与支付流程
|
||
- [ ] 添加微信小程序登录授权
|
||
|
||
### 中优先级
|
||
- [ ] 添加更多词云底图模板
|
||
- [ ] 支持从微信聊天记录导入 Excel 名单
|
||
- [ ] 实现设计稿保存到草稿箱功能
|
||
|
||
### 低优先级
|
||
- [ ] 3D 效果预览（模拟材质纹理）
|
||
- [ ] 批量下单优惠逻辑
|
||
- [ ] 企业定制专属通道
|