智绘微刻小程序开发说明

项目简介

智绘微刻（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/             # Data Access 层（按域拆分，openid 隔离）
│   │   ├── api/               # 后端 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/ 抽象（按域拆分，详见 docs/parallel-development-guide.md）：

pages/
  └─ 调用 store.getDesignList() / addDesign() / designToOrder() 等业务接口
        └─ store/<domain>.ts 内封装 Taro.getStorageSync / setStorageSync
              └─ key = ${scope}_${openid} 实现多用户数据隔离

后端替换方案：按域在 store/<domain>.ts 与 api/<domain>.ts 中替换为 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

启动开发

安装依赖

npm install
# 或
yarn install

开发模式（微信小程序）

npm run dev:weapp

构建（微信小程序）

npm run build:weapp

H5 预览

npm run dev:h5

图片资源与包体积说明

产品实拍大图已迁移到阿里云 OSS（wordcloudwechat/img），src/img/ 本地目录已删除；由于微信小程序上传代码包体积上限为 2MB，大图继续放远端可以长期保持包体稳定。

已采取的措施（两步压缩脚本）

• compress-images.js（基于 sharp）已配置到项目中，支持批量：
  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：

   // 改之前
   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）：

   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 命令行一次传完，在项目根目录执行：

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）

中优先级

• 产品图已上传阿里云 OSS，资源基址通过 .env 的 OSS_BASE_URL 配置
• 添加更多词云底图模板
• 支持从微信聊天记录导入 Excel 名单
• 实现设计稿保存到草稿箱功能

低优先级

• 3D 效果预览（模拟材质纹理）
• 批量下单优惠逻辑
• 完善企业定制专属通道