340 lines
18 KiB
Markdown
340 lines
18 KiB
Markdown
# 智绘微刻小程序开发说明
|
||
|
||
## 项目简介
|
||
|
||
智绘微刻（Smart-Engraving）微信小程序，为用户提供词云生成 + 个性化激光雕刻定制服务。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: Taro 3.6.31 + React 18 + TypeScript
|
||
- **样式**: SCSS（CSS 变量驱动主题系统）
|
||
- **目标平台**: 微信小程序
|
||
- **包管理器**: npm
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
smart-engraving-miniapp/
|
||
├── config/ # Taro 配置文件
|
||
│ └── index.js # 构建配置（含 copy patterns：icon、theme.json 复制）
|
||
├── src/
|
||
│ ├── app.tsx # 应用入口（全局 ThemeProvider 挂载）
|
||
│ ├── app.scss # 全局样式（CSS 变量 + 主题工具类）
|
||
│ ├── app.config.ts # 应用配置（页面路由、tabBar、window、darkmode/themeLocation）
|
||
│ ├── custom-tab-bar/ # 自定义底部导航（5 tab：首页/商品/设计清单/订单/我的）
|
||
│ ├── hooks/
|
||
│ │ ├── useSafeArea.ts # 状态栏/胶囊安全区避让
|
||
│ │ ├── useStatusBar.ts # 页面状态栏文字/导航条颜色同步
|
||
│ │ └── useTheme.ts # 主题读写 Hook
|
||
│ ├── types/
|
||
│ │ └── index.ts # TypeScript 类型定义（ProductCategory、DesignItem、OrderItem 等）
|
||
│ ├── utils/
|
||
│ │ ├── productConfig.ts # 产品品类配置（5 个品类 + iconImg 映射）
|
||
│ │ ├── store.ts # Data Access 层（Storage 读写，openid 隔离）
|
||
│ │ ├── api.ts / request.ts # 后端 HTTP 封装（wx.request + token）
|
||
│ │ ├── authState.ts # 登录态校验缓存（isAuthVerified / invalidateAuthCache）
|
||
│ │ └── themeBackground.ts # 页面窗口背景同步（backgroundColorTop/Bottom）
|
||
│ ├── context/
|
||
│ │ └── ThemeContext.tsx # 全局主题 Context（light/dark/auto）
|
||
│ ├── components/
|
||
│ │ ├── ThemedPageMeta/ # page-meta + navigation-bar 原生顶栏控制
|
||
│ │ ├── ThemeToggle/ # 主题切换按钮（历史组件，现收敛到设置页）
|
||
│ │ ├── LoginGuard/ # 登录守卫（登录态事件驱动刷新）
|
||
│ │ └── LoginModal/ # 登录弹窗（历史组件）
|
||
│ ├── theme.json # darkmode 主题映射（用于跟随系统探测）
|
||
│ └── pages/
|
||
│ ├── index/ # 首页（品类入口、成品轮播、搜索）
|
||
│ ├── shop/ # 商品浏览页（2列网格 + 沉浸式详情 overlay）
|
||
│ ├── product/ # 商品详情页（轮播图 + 加入设计清单弹窗）
|
||
│ ├── diy/ # DIY 工作台（贴纸拖拽、缩放、碰撞检测）
|
||
│ ├── checkout/ # 设计效果确认页（收货地址 + 下单）
|
||
│ ├── designList/ # 我的设计清单（需登录）
|
||
│ ├── orders/ # 订单列表（需登录）
|
||
│ ├── orderDetail/ # 订单详情（收货地址 + 物流时间轴）
|
||
│ ├── profile/ # 个人中心（5 状态入口、6 宫格菜单、企业定制）
|
||
│ ├── service/ # 联系客服页
|
||
│ ├── wordcloud/ # 词云生成
|
||
│ ├── address/ # 收货地址管理
|
||
│ ├── settings/ # 设置（个人信息、账号管理、退出登录）
|
||
│ ├── agreement/ # 使用协议
|
||
│ └── userDatabase/ # 账号管理（密码保护：zhihui2024）
|
||
├── src/icon/ # 20 个小图标 PNG/SVG（打包到 dist/icon）
|
||
├── OSS 产品图 # 产品实拍大图放在阿里云 OSS（bucket: wordcloudwechat/img）
|
||
├── package.json
|
||
├── tsconfig.json
|
||
└── project.config.json # 微信开发者工具配置
|
||
```
|
||
|
||
## 页面说明
|
||
|
||
| 页面 | 路径 | 功能 |
|
||
|---|---|---|
|
||
| 首页 | `/pages/index/index` | 品类入口、成品轮播、搜索框、热门品类网格 |
|
||
| 商品浏览 | `/pages/shop/index` | 2列商品网格 → 点击卡片进入沉浸式详情 overlay（滚动视差 + 主题色联动）→ 底部 CTA 跳转购买页 |
|
||
| 商品详情 | `/pages/product/index` | 轮播图、单价/工期/尺寸、加入设计清单弹窗 |
|
||
| DIY 工作台 | `/pages/diy/index` | 选品类→上传图片/相机→拖拽缩放→碰撞检测→预览下单 |
|
||
| 设计效果确认 | `/pages/checkout/index` | 展示设计效果、选择/修改收货地址、确认下单 |
|
||
| 设计清单 | `/pages/designList/index` | 清单列表（全部/待设计/未设计/设计中/已下单） |
|
||
| 订单列表 | `/pages/orders/index` | 订单列表（全部/待付款/待发货/待收货/已完成） |
|
||
| 订单详情 | `/pages/orderDetail/index` | 订单详情页（收货地址 + 物流时间轴） |
|
||
| 个人中心 | `/pages/profile/index` | 用户信息、5 状态快捷入口、6 宫格菜单、企业定制 |
|
||
| 词云生成 | `/pages/wordcloud/index` | 三步式词云生成 |
|
||
| 收货地址 | `/pages/address/index` | 增删改查 + 省市区选择 + 默认地址 |
|
||
| 设置 | `/pages/settings/index` | 修改信息、账号管理、定制协议、退出登录 |
|
||
| 联系客服 | `/pages/service/index` | 客服电话、微信、邮箱、企业批量定制 |
|
||
| 账号管理 | `/pages/userDatabase/index` | 查看/切换/新建/删除本地用户（密码：zhihui2024） |
|
||
|
||
## 核心交互流程
|
||
|
||
### 完整业务流程
|
||
|
||
```
|
||
首页浏览品类 → 商品详情页（轮播图+价格+介绍）
|
||
→ 加入设计清单（弹窗选数量）→ 设计清单页（支持自动筛选）
|
||
→ 立即下单 → DIY 工作台（直接进入）
|
||
→ 添加贴纸（相册/相机）→ 拖动调整位置 → 碰撞检测
|
||
→ 预览效果 → 确认完成 → 设计效果确认页（含收货地址）
|
||
→ 弹窗确认下单 → 订单生成 → 订单列表/订单详情（可改地址）
|
||
→ 物流时间轴追踪 → 确认收货 → 完成
|
||
```
|
||
|
||
### 个人主页快捷入口流
|
||
|
||
```
|
||
个人主页
|
||
→ 待设计 / 待付款 / 待发货 / 待收货 / 已完成 → 自动跳转对应页面并筛选
|
||
→ 收货地址 → 增删改复 + 省市区选择（微信原生 Picker）+ 默认地址
|
||
→ 设置 → 修改昵称头像 / 退出登录 / 定制协议 / 账号管理
|
||
→ 账号管理（密码保护：zhihui2024）→ 查看/切换/新建/删除本地用户
|
||
→ 企业批量定制 → 客服咨询
|
||
```
|
||
|
||
## 关键配置与实现细节
|
||
|
||
### 主题系统（浅色 / 深色 / 跟随系统）
|
||
|
||
- 主题模式：`light` / `dark` / `auto`，设置入口在 `src/pages/settings/index.tsx`；`ThemeContext` 产出最终生效的 `resolvedTheme`
|
||
- 页面根节点使用 `className={theme-${resolvedTheme}}`（`theme-light` / `theme-dark`），CSS 变量定义在 `app.scss`
|
||
- `app.config.ts` 保留 `darkmode: true + themeLocation`，仅作为 `onThemeChange` / `getAppBaseInfo().theme` 的系统主题探测通道
|
||
- 顶部/状态栏颜色由每个页面的 `ThemedPageMeta`（`page-meta + navigation-bar`）按 `resolvedTheme` 强覆盖，固定浅色/深色时不跟随系统；`useStatusBar` 负责页面显示时再次同步
|
||
- “跟随系统”模式下，系统切换深浅色会通过 `wx.onThemeChange` 实时更新 `resolvedTheme`，CSS `prefers-color-scheme` 探测器作为兜底
|
||
|
||
### 事件绑定规范（Taro 小程序兼容）
|
||
|
||
> ⚠️ **重要**：微信小程序 + Taro React + 微信基础库 3.17.0 存在 `onClick` 兼容风险。
|
||
>
|
||
> 现象：动态更新事件 handler 时可能触发 `TaroElement.removeEventListener(undefined)`，导致 `Cannot read properties of undefined (reading '_num')`。
|
||
>
|
||
> **本项目已全部使用 `onTap` 替代 `onClick`**。后续新增组件也须遵守此规范。
|
||
|
||
| 平台 | 推荐事件 | 说明 |
|
||
|------|---------|------|
|
||
| 微信小程序 | `onTap` | 编译为 `bindtap`，原生稳定 |
|
||
| H5 | `onClick` | 仅在 H5 构建中使用 |
|
||
|
||
### Taro React 生命周期建议
|
||
|
||
- **页面显示刷新**：使用 `import { useDidShow } from '@tarojs/taro'`，而非手动覆盖 `page.onShow`
|
||
- 手动 `page.onShow = function(){}` 在热更新时会重复叠加，导致异常
|
||
|
||
### 前端 DA 层设计
|
||
|
||
所有数据操作通过 `src/utils/store.ts` 抽象：
|
||
|
||
```
|
||
pages/
|
||
└─ 调用 store.getDesignList() / addDesign() / designToOrder() 等业务接口
|
||
└─ store.ts 内封装 Taro.getStorageSync / setStorageSync
|
||
└─ key = ${scope}_${openid} 实现多用户数据隔离
|
||
```
|
||
|
||
**后端替换方案**：上线时只需重写 `store.ts` 中的函数为 `wx.request` HTTP 调用，页面层零改动。
|
||
|
||
### Icon 系统（emoji 已完全移除）
|
||
|
||
- 19 个 icon 存放在 `src/icon/`，构建时通过 `config/index.js` copy 到 `dist/icon/`。新增「商品」tab 图标后共 20 个 icon
|
||
- 产品 icon 映射：`src/utils/productConfig.ts` 中每个产品有 `iconImg` 字段
|
||
- 旧数据兼容：列表渲染时检测 `productIcon` 是否以 `/icon/` 开头，否则通过 `PRODUCT_ICON_MAP` 查映射表
|
||
|
||
### 遮罩尺寸
|
||
|
||
详见 `docs/mask-config-guide.md`。当实际产品尺寸确定后，仅需修改 `src/utils/productConfig.ts` 中的 `PRODUCTS` 数组。
|
||
|
||
### 后端接口（登录已接入，业务接口待接入）
|
||
|
||
当前代码中以下业务接口仍待接入后端 API：
|
||
1. 词云生成：调用 `/api/wordcloud/generate` 提交底图+名单，生成词云图
|
||
2. 图片保存：调用 `/api/upload` 上传用户设计图
|
||
3. 订单创建：调用 `/api/order/create` 提交订单
|
||
4. 登录授权：已接入 `/api/auth/login`（`wx.login` code 换取 `accessToken` + 真实 `openid`），不再使用 mock openid
|
||
|
||
## 启动开发
|
||
|
||
### 安装依赖
|
||
```bash
|
||
npm install
|
||
# 或
|
||
yarn install
|
||
```
|
||
|
||
### 开发模式（微信小程序）
|
||
```bash
|
||
npm run dev:weapp
|
||
```
|
||
|
||
### 构建（微信小程序）
|
||
```bash
|
||
npm run build:weapp
|
||
```
|
||
|
||
### H5 预览
|
||
```bash
|
||
npm run dev:h5
|
||
```
|
||
|
||
## 图片资源与包体积说明
|
||
|
||
产品实拍大图已迁移到阿里云 OSS（`wordcloudwechat/img`），`src/img/` 本地目录已删除；由于微信小程序**上传代码包体积上限为 2MB**，大图继续放远端可以长期保持包体稳定。
|
||
|
||
### 已采取的措施（两步压缩脚本）
|
||
|
||
- `compress-images.js`（基于 [sharp](https://sharp.pixelplumbing.com/)）已配置到项目中，支持批量：
|
||
1. **resize**：最大边长限制到 800px
|
||
2. **format**：PNG → JPG
|
||
3. **quality**：JPG 质量 60%
|
||
- 产品大图目前已迁到 OSS，`src/img` 本地目录已删除，不再需要执行本地压缩脚本
|
||
- 当前编译后 `dist/` 总大小约 **1.03 MB**（新增 1 个 icon 约 7KB），满足微信限制。
|
||
|
||
### 当前状态：已迁移 OSS
|
||
|
||
压缩后的图片在手机上画质会有可见损失（尤其缩放到全屏轮播时）。**建议上线前迁移到 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；
|
||
- 后续更换产品图只需在图床后台操作，无需重新发版。
|
||
|
||
### 阿里云 OSS 实际操作（当前桶：wordcloudwechat）
|
||
|
||
1. 当前 Bucket `wordcloudwechat` 已创建：地域 `华东1（杭州）`，读写权限**公共读**，可直接使用。
|
||
2. 只需把 `src/img/` 下的产品大图传到 Bucket 的 `img/` 目录；`src/icon/` 等几 KB 以内的小图标继续打包在本地，不用传 OSS。
|
||
|
||
3. 资源基地址统一配在项目根目录 `.env`（已提供 `.env.example`）：
|
||
```dotenv
|
||
OSS_BASE_URL=https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com
|
||
```
|
||
后续迁移换桶/换域名时，只需要改 `.env` 里的 `OSS_BASE_URL`。
|
||
4. 商品图、首页成品图会走 OSS；代码只在 `path` 以 `/img/` 开头时才拼接远程地址，`/icon/*` 小图标仍从包内加载。
|
||
5. 照片稳定走远程后，`config/index.js` 中 `src/img` 的 copy 规则不再需要（当前已移除）。
|
||
6. 微信小程序后台需要在「开发管理 - 服务器域名」配置 `downloadFile` 合法域名：`https://wordcloudwechat.oss-cn-hangzhou.aliyuncs.com`；如果改用了 CNAME，则填对应 HTTPS 域名。
|
||
|
||
如果用 `ossutil64` 命令行一次传完，在项目根目录执行：
|
||
|
||
```bash
|
||
ossutil64 config
|
||
ossutil64 cp -r -f src/img oss://wordcloudwechat/img
|
||
```
|
||
|
||
---
|
||
|
||
## 最近更新记录（2026-08-06）
|
||
|
||
### Batch 13 — 顶栏主题解耦 + 跟随系统恢复 + 登录态缓存
|
||
|
||
| 序号 | 修改内容 |
|
||
|------|----------|
|
||
| 1 | **顶栏颜色与系统解耦**：所有页面新增 `ThemedPageMeta`（`page-meta + navigation-bar`），顶部/状态栏颜色按 `resolvedTheme` 强制覆盖 |
|
||
| 2 | **跟随系统恢复**：保留 `darkmode: true` 仅用于 `onThemeChange`/`getAppBaseInfo` 探测；设置固定浅色/深色时不跟随系统 |
|
||
| 3 | **登录守卫重构**：新增 `authState.ts` 登录态缓存，`LoginGuard` 监听 `authStateChanged/tabBarChange/themeChange` 自动刷新 |
|
||
| 4 | **自定义 tabBar 状态同步**：切换 tab 后选中态立即更新，并随主题/登录事件同步刷新 |
|
||
|
||
## 最近更新记录（2026-08-04）
|
||
|
||
### Batch 12 — 主题跟随 + 贴纸编辑 + 安全区适配
|
||
|
||
| 序号 | 修改内容 |
|
||
|------|----------|
|
||
| 1 | **主题跟随系统**：`app.config.ts` 补 `darkmode: true`；`ThemeContext` 增加 `useDidShow` + `wx.onAppShow` 双兜底，每次回到前台重新检测系统主题 |
|
||
| 2 | **贴纸编辑画板空白**：Canvas 2D 初始化改为 `Taro.nextTick()` + 300ms 自动重试；增加 `Math.round(cw * dpr)` 防小数尺寸；`img.src` 增加空值保护 |
|
||
| 3 | **画板截断统一**：DIY 工作台、预览弹窗、确认页三处 `.canvas-area` / `.preview-canvas` 统一补充 `max-width: 100%` + `box-sizing: border-box` |
|
||
| 4 | **顶部安全区适配**：`env(safe-area-inset-top, 20px)` 兜底 + 48px 按钮高度；各页面独立 `.page-header` 强制 `!important` 对齐全局 |
|
||
|
||
### 已知遗留问题（待修复）
|
||
|
||
| 序号 | 问题 | 状态 |
|
||
|------|------|------|
|
||
| 1 | **地址在设计中添加后无法及时同步** | ❌ 未修复 — checkout 页从 store 读取地址时，design 数据写入和读取生命周期不一致 |
|
||
| 2 | **贴纸编辑页无法运行** | ❌ 未修复 — Canvas 2D `createImage` 在某些基础库版本返回 `undefined`；线稿 AI 接口未接入 |
|
||
| 3 | **个人主页登录后页面失灵** | ✅ 已修复 — LoginGuard 改为登录态缓存 + 事件驱动重新校验，登录完成后自动放行 |
|
||
| 4 | **跟随系统的主题切换按钮无法及时切换** | ✅ 已修复 — 改用 `onThemeChange`/`getAppBaseInfo` 实时同步，`PageMeta` 按 `resolvedTheme` 覆盖顶栏 |
|
||
|
||
---
|
||
|
||
## 最近更新记录（2026-08-02）
|
||
|
||
### Batch 11 — 商品浏览页（Shop Page）沉浸式体验构建
|
||
|
||
| 序号 | 修改内容 |
|
||
|------|----------|
|
||
| 1 | **新增「商品」tab**：底部导航 4 tab → 5 tab（首页/商品/设计清单/订单/我的），`app.config.ts` + `custom-tab-bar` 同步扩展，新增 `/icon/商品.png` |
|
||
| 2 | **构建 `pages/shop/index.tsx`**：单页双容器结构——列表 2 列网格 + 固定 overlay 沉浸式详情；点击卡片当前页内过渡，不走页面跳转 |
|
||
| 3 | **滚动驱动视差动画**：Hero 图上下边缘裁剪 → 整图上滑退出 → `transition-band` 吸顶显现 → 内容区延迟上浮淡入；`ScrollView` + `scrollEventThrottle={16}` |
|
||
| 4 | **产品主题色联动**：每个产品新增 `tone: [r,g,b]`（5 产品 5 色调），详情页背景、渐变遮罩、CTA 栏、吸顶条实时跟随变换 |
|
||
| 5 | **商品文案升级**：5 个产品全部补充 `subtitle`/`story`/`scene`/`tags`/`specs`/`originalPrice`，电商级长文案展示 |
|
||
| 6 | **CTA 衔接现有链路**：底部悬浮毛玻璃栏「立即定制」跳转到原有 `/pages/product/index?id=xxx`，购买流程零改动 |
|
||
|
||
## 最近更新记录（2026-08-01）
|
||
|
||
### Batch 10 — 夜间模式适配 + 地址弹窗统一 + 空状态主题化
|
||
|
||
| 序号 | 修改内容 |
|
||
|------|----------|
|
||
| 1 | **订单详情页夜间模式文字修复**：补充 `.status-text`、`.logistics-title/num`、`.meta-title/label/value`、`.timeline-status/time/desc` 等 CSS 变量配色，夜间模式自动变亮 |
|
||
| 2 | **地址选择弹窗统一**：提取 `.modal-overlay` + `.addr-picker-sheet` 为 `app.scss` 全局统一样式；移除 checkout/orderDetail 中的重复覆写 |
|
||
| 3 | **收货地址空状态主题适配**：📍 emoji → `<Image src='/icon/地址.png'>`；空状态文字使用 CSS 变量；同步修复 `orders/index.scss` 中硬编码颜色 |
|
||
|
||
### Batch 9（2026-07-29）— emoji → icon 彻底收尾
|
||
- `productConfig.ts` 增加 `iconImg` 字段
|
||
- `store.ts` 写入层修复（存 `iconImg` 而非 emoji）
|
||
- 运行时旧数据兼容映射 `PRODUCT_ICON_MAP`
|
||
- 商品详情页弹窗去 emoji
|
||
|
||
### Batch 8（2026-07-29）— Taro 事件兼容修复
|
||
- 全量 `onClick` → `onTap`（15 个文件，82 处）
|
||
- Profile `STATUS_MAP.map` 消除 Fragment（改为 `View.status-group`）
|
||
- `useEffect + page.onShow` 重写为 `useDidShow`
|
||
- 删除废弃 `permission.scope.writePhotosAlbum`
|
||
|
||
---
|
||
|
||
## 下一步开发计划
|
||
|
||
### 高优先级
|
||
- [ ] 接入后端词云生成 API，替换模拟数据
|
||
- [ ] 实现图片上传接口
|
||
- [ ] 实现订单创建与支付流程
|
||
- [ ] 订单物流接口接入（目前为静态 mock）
|
||
|
||
### 中优先级
|
||
- [x] 产品图已上传阿里云 OSS，资源基址通过 `.env` 的 `OSS_BASE_URL` 配置
|
||
- [ ] 添加更多词云底图模板
|
||
- [ ] 支持从微信聊天记录导入 Excel 名单
|
||
- [ ] 实现设计稿保存到草稿箱功能
|
||
|
||
### 低优先级
|
||
- [ ] 3D 效果预览（模拟材质纹理）
|
||
- [ ] 批量下单优惠逻辑
|
||
- [ ] 完善企业定制专属通道
|