CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概览

智绘微刻（Smart-Engraving）微信小程序：词云生成 + 个性化激光雕刻定制。基于 Taro 3.6.31 + React 18 + TypeScript，SCSS 变量驱动主题，构建产物运行在微信小程序（webpack5 编译到 dist/）。

常用命令

npm install                 # 安装依赖
npm run dev:weapp           # 微信小程序开发模式（watch，配合微信开发者工具）
npm run build:weapp         # 生产构建；也是提交前 / 验收的标准验证命令
npm run dev:h5              # H5 预览调试（H5 下事件用 onClick，见下文）
node --test tools/homeTopMask.test.mjs   # 运行 node:test 单测（目前唯一测试，无需 jest）

没有配置 lint/test 脚本。提交前验证 = npm run build:weapp 通过（见 docs/parallel-development-guide.md §6）。

数据访问层（核心架构，务必先读）

页面不得直接读写 Storage 或直接发请求。所有数据操作取道两个聚合入口，二者都只 re-export、不堆业务：

../../utils/store（DA 层，本地 Storage，按域拆文件）：页面从 src/utils/store/index.ts 导入 getDesignList()、addAddress()、designToOrder() 等。
../../utils/api（HTTP 层，按域拆文件）：页面从 src/utils/api/index.ts 导入 login()、fetchProducts() 等。

openid 作用域隔离（store/keys.ts）：storage key 形如 ${scope}_${openid}，通过 key(scope)（当前用户）与 keyFor(scope, openid)（指定用户）生成，实现多用户数据隔离。

类型统一放 src/types/index.ts 或 src/types/<domain>.ts，不要散落在页面里。

协作约定（R0–R4 并行路线）

仓库按四人并行开发组织，主干为 master，禁止直接推主干，合入走 PR。每人一条端到端路线（前端 + 后端、同名分支）：

路线	分支	页面归属	数据域
R1 商品目录	`feat/r1-catalog`	`index`、`shop`、`shop/detail`、`product`	`api/product`
R2 地址+设计清单	`feat/r2-address-design`	`address`、`designList`	`store/design`、`store/address`、`api/address`、`api/design`
R3 订单+支付占位	`feat/r3-order-pay`	`checkout`、`orders`、`orderDetail`	`store/order`、`api/order`
R4 上传+词云+线稿	`feat/r4-upload-wordcloud`	`wordcloud`、`diy/stickerEdit`	`api/upload`

store/index.ts 与 api/index.ts 由 R0（本分支 feat/r0-dev-foundation）维护，只加不删、不堆业务。完整规则见 docs/team-collaboration-guide.md 与 docs/parallel-development-guide.md（含合并顺序：R1 → R2/R4 → R3）。

主题系统

ThemeMode：light / dark / auto（store/theme.ts）。ThemeContext（src/context/ThemeContext.tsx）产出最终生效的 resolvedTheme: 'light' | 'dark'。

页面根节点 className={theme-${resolvedTheme}}；所有颜色/字号来自 app.scss 里的 CSS 变量（浅色 :root + .theme-dark），禁止在页面里硬编码颜色/字号/组件形态，token 语义见 DESIGN.md，落地规则见 设计变更文档.md。
每个页面都挂 <ThemedPageMeta />（PageMeta + NavigationBar），按 resolvedTheme 强制覆盖顶部/状态栏颜色；useStatusBar(resolvedTheme) 在页面显示时再同步一次。app.config.ts 里的 darkmode: true 只作为系统主题探测通道（onThemeChange/getAppBaseInfo），窗口颜色不依赖它。
自定义 tabBar 无法继承 React Context，通过 Taro.eventCenter 订阅 themeChange 事件 (THEME_CHANGE_EVENT) 同步主题。
图标一律用 src/icon/ 下的 PNG/SVG，禁止用 emoji 当图标。

事件与生命周期（重要兼容坑）

一律用 onTap，不要用 onClick。微信基础库 3.17.0 + Taro React 下动态更新 handler 会触发 TaroElement.removeEventListener(undefined)，报 Cannot read properties of undefined (reading '_num')。仅在 H5 构建里可用 onClick。
页面显示刷新用 useDidShow（@tarojs/taro），不要手动覆盖 page.onShow（热更新会重复叠加导致异常）。

请求与登录

src/utils/request.ts：BASE_URL = https://wxbackend.tokenleaping.com；后端统一响应 { code, message, data }，code === 0 成功；token 存 smart_access_token，走 Authorization: Bearer。HTTP 401 会自动触发一次会话续登（app.tsx 注册的 refreshSession），失败则清 token 并调 onUnauthorized。
session.ts 的 refreshSession：wx.login 换新 code → /api/auth/login 续签 → /api/users/me 校验 openid 与本地账号一致才放行（防串号）。mock_* 开头的 openid 是历史残留，isMockOpenid 会识别并拒绝。
登录态校验有缓存（src/utils/authState.ts），LoginGuard 监听 authStateChanged/tabBarChange/themeChange 事件自动刷新。

静态资源与 OSS

产品大图已迁到阿里云 OSS（bucket wordcloudwechat，杭州），包体积需保持在微信 2MB 限制内（当前 dist/ 约 1MB）。
基址在根目录 .env 的 OSS_BASE_URL（git 忽略），由 config/index.js 注入为 __OSS_BASE_URL__ 常量。
所有资源路径经 assetUrl()（src/utils/asset.ts）处理：/img/* 大图拼 OSS 远程地址，/icon/* 小图标与 src/icon、theme.json 通过 config/index.js 的 copy patterns 打包进 dist/。
商品/品类配置集中在 src/utils/productConfig.ts（PRODUCTS 数组 + icon 映射 + tone 主题色），遮罩尺寸说明见 docs/mask-config-guide.md。

页面结构说明

路由与 tabBar 见 src/app.config.ts（全局 navigationStyle: custom，5 个 tab 的自定义 tabBar）。几个非平凡的页面：

pages/shop/index：单页双容器——2 列商品网格 + 固定 overlay 沉浸式详情（滚动视差、产品 tone 主题色联动），点击卡片在当前页内过渡，不跳转；底部 CTA 跳 /pages/product/index?id=xxx 衔接购买链路。
pages/diy/index：DIY 工作台（贴纸拖拽/缩放/碰撞检测），后续 diy/stickerEdit 为贴纸编辑画板。
共享组件在 src/components/（ThemedPageMeta、ScrollTopMask、TopBarGradient、BottomActionBar、LoginGuard、LoginModal 等）。

已知遗留问题

README「已知遗留问题」表记载（改动相关页面时注意）：

checkout 页在设计中新增地址后无法及时同步（design 数据写入与读取生命周期不一致）。
diy/stickerEdit 页面无法运行：Canvas 2D createImage 在部分基础库版本返回 undefined，且线稿 AI 接口未接入。

7.0 KiB Raw Blame History Unescape Escape