商品浏览页构建前最后一次更新

README.md

@@ -6,32 +6,50 @@
 
 ## 技术栈
 
-- **框架**: Taro 3.x + React 18 + TypeScript
-- **样式**: SCSS
-- **目标平台**: 微信小程序（可扩展 H5）
+- **框架**: Taro 3.6.31 + React 18 + TypeScript
+- **样式**: SCSS（CSS 变量驱动主题系统）
+- **目标平台**: 微信小程序
+- **包管理器**: npm
 
 ## 项目结构
 
 ```
 smart-engraving-miniapp/
 ├── config/              # Taro 配置文件
-├── docs/                # 项目文档
-│   └── mask-config-guide.md   # 遮罩尺寸配置指南
+│   └── index.js         # 构建配置（含 copy patterns：icon、img 资源复制）
 ├── src/
-│   ├── app.tsx          # 应用入口
-│   ├── app.scss         # 全局样式
-│   ├── app.config.ts    # 应用配置（页面路由、tabBar等）
+│   ├── app.tsx          # 应用入口（全局 ThemeProvider 挂载）
+│   ├── app.scss         # 全局样式（CSS 变量 + 主题工具类）
+│   ├── app.config.ts    # 应用配置（页面路由、tabBar、window）
+│   ├── custom-tab-bar/  # 自定义底部导航（4 tab：首页/设计清单/订单/我的）
 │   ├── types/
-│   │   └── index.ts     # TypeScript 类型定义
+│   │   └── index.ts     # TypeScript 类型定义（ProductCategory、DesignItem、OrderItem 等）
 │   ├── utils/
-│   │   └── productConfig.ts   # 产品品类配置
-│   ├── pages/
-│   │   ├── index/       # 首页
-│   │   ├── wordcloud/   # 词云生成
-│   │   ├── diy/         # DIY 工作台
-│   │   ├── orders/      # 订单列表
-│   │   └── profile/     # 个人中心
-│   └── components/      # 公共组件（可按需拆分）
+│   │   ├── productConfig.ts   # 产品品类配置（5 个品类 + iconImg 映射）
+│   │   └── store.ts           # Data Access 层（Storage 读写，openid 隔离）
+│   ├── context/
+│   │   └── ThemeContext.tsx   # 全局主题 Context（light/dark）
+│   ├── components/
+│   │   ├── ThemeToggle/       # 主题切换按钮（onTap 触发）
+│   │   ├── LoginGuard/        # 登录守卫（未登录时居中提示）
+│   │   └── LoginModal/        # 登录弹窗（历史组件）
+│   └── pages/
+│       ├── index/        # 首页（品类入口、成品轮播、搜索）
+│       ├── product/      # 商品详情页（轮播图 + 加入设计清单弹窗）
+│       ├── diy/          # DIY 工作台（贴纸拖拽、缩放、碰撞检测）
+│       ├── checkout/     # 设计效果确认页（收货地址 + 下单）
+│       ├── designList/   # 我的设计清单（需登录）
+│       ├── orders/       # 订单列表（需登录）
+│       ├── orderDetail/  # 订单详情（收货地址 + 物流时间轴）
+│       ├── profile/      # 个人中心（5 状态入口、6 宫格菜单、企业定制）
+│       ├── service/      # 联系客服页
+│       ├── wordcloud/    # 词云生成
+│       ├── address/      # 收货地址管理
+│       ├── settings/     # 设置（个人信息、账号管理、退出登录）
+│       ├── agreement/    # 使用协议
+│       └── userDatabase/ # 账号管理（密码保护：zhihui2024）
+├── src/icon/            # 19 个 icon PNG（28~56px，打包到 dist/icon）
+├── src/img/             # 8 张产品实物压缩图（打包到 dist/img）
 ├── package.json
 ├── tsconfig.json
 └── project.config.json  # 微信开发者工具配置
@@ -41,37 +59,102 @@ smart-engraving-miniapp/
 
 | 页面 | 路径 | 功能 |
 |---|---|---|
-| 首页 | `/pages/index/index` | 品类入口、案例展示、快捷导航 |
-| 词云生成 | `/pages/wordcloud/index` | 三步式词云生成（上传底图→输入名单→生成预览） |
-| DIY工作台 | `/pages/diy/index` | 选品类→上传图片→拖拽缩放→预览下单 |
-| 订单 | `/pages/orders/index` | 订单列表与管理 |
-| 个人中心 | `/pages/profile/index` | 用户信息、设计稿、客服入口 |
+| 首页 | `/pages/index/index` | 品类入口、成品轮播、搜索框、热门品类网格 |
+| 商品详情 | `/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） |
 
 ## 核心交互流程
 
-### 流程一：词云生成 → 定制
-1. 首页点击「AI词云生成」
-2. 上传底图（或选模板）
-3. 输入名字名单（手动输入/批量导入）
-4. 生成词云，预览效果
-5. 点击「前往个性化定制」跳转 DIY 工作台
+### 完整业务流程
 
-### 流程二：直接定制
-1. 首页选择品类（笔记本/杯垫/笔盒/书灯）
-2. 进入 DIY 工作台上传图片
-3. 拖拽调整位置，缩放至合适大小
-4. 预览确认后下单
+```
+首页浏览品类 → 商品详情页（轮播图+价格+介绍）
+  → 加入设计清单（弹窗选数量）→ 设计清单页（支持自动筛选）
+  → 立即下单 → DIY 工作台（直接进入）
+    → 添加贴纸（相册/相机）→ 拖动调整位置 → 碰撞检测
+    → 预览效果 → 确认完成 → 设计效果确认页（含收货地址）
+      → 弹窗确认下单 → 订单生成 → 订单列表/订单详情（可改地址）
+        → 物流时间轴追踪 → 确认收货 → 完成
+```
 
-## 关键配置
+### 个人主页快捷入口流
+
+```
+个人主页
+  → 待设计 / 待付款 / 待发货 / 待收货 / 已完成 → 自动跳转对应页面并筛选
+  → 收货地址 → 增删改复 + 省市区选择（微信原生 Picker）+ 默认地址
+  → 设置 → 修改昵称头像 / 退出登录 / 定制协议 / 账号管理
+    → 账号管理（密码保护：zhihui2024）→ 查看/切换/新建/删除本地用户
+  → 企业批量定制 → 客服咨询
+```
+
+## 关键配置与实现细节
+
+### 主题系统（Light / Dark）
+
+- 全局 CSS 变量定义在 `app.scss`：`var(--bg-card)`、`var(--text-primary)`、`var(--text-secondary)`、`var(--line-star)` 等
+- 切换方式：根节点 `className={theme-${theme}}`（`theme-light` / `theme-dark`）
+- 状态管理：`src/context/ThemeContext.tsx`（React Context），支持全局同步
+- 切换按钮：`src/components/ThemeToggle/index.tsx`（使用 `onTap`，非 `onClick`）
+
+### 事件绑定规范（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/`
+- 产品 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. 登录授权：当前 `openid` 为 mock 值，接入真实后端后替换 `wx.login` 的 `code`
 
 ## 启动开发
 
@@ -133,15 +216,41 @@ npm run dev:h5
 
 ---
 
+## 最近更新记录（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 openid）
+- [ ] 订单物流接口接入（目前为静态 mock）
 
 ### 中优先级
+- [ ] 将实物照片迁移到 CDN（腾讯云 COS / 阿里云 OSS）
 - [ ] 添加更多词云底图模板
 - [ ] 支持从微信聊天记录导入 Excel 名单
 - [ ] 实现设计稿保存到草稿箱功能
@@ -149,4 +258,4 @@ npm run dev:h5
 ### 低优先级
 - [ ] 3D 效果预览（模拟材质纹理）
 - [ ] 批量下单优惠逻辑
-- [ ] 企业定制专属通道
+- [ ] 完善企业定制专属通道