CLAUDE.md
8.76 KB
CLAUDE.md
本文件为 Claude Code (claude.ai/code) 在处理此仓库代码时提供指导。
设计原则：这是一个轻量级索引文档，只保留必须立即知道的信息。详细内容通过链接访问。
📚 项目文档索引
🚀 开发命令
核心命令
pnpm dev:weapp # 启动微信小程序开发服务器
pnpm dev:h5 # 启动 H5 开发服务器
pnpm build:weapp # 构建生产版本（微信小程序）
pnpm lint # 运行 ESLint
Git 工作流
从 develop 创建功能分支
# 1. 切换到 develop（确保最新）
git checkout develop
git pull
# 2. 创建功能分支
git checkout -b feature/功能名称
# 3. 开发完成后，合并回 develop
git checkout develop
git merge feature/功能名称
# 4. 删除功能分支（可选）
git branch -d feature/功能名称
分支命名规范：
-
feature/xxx- 新功能 -
fix/xxx- Bug 修复 -
refactor/xxx- 重构
版本自动更新（已实现）
规则：遵循 Semantic Versioning
-
feat- MINOR 版本更新（1.0.0 → 1.1.0） -
fix- PATCH 版本更新（1.0.0 → 1.0.1） -
perf- MINOR 版本更新 -
docs/style/refactor/test/chore- 不更新
实现方式：
- ✅ 使用
standard-version自动更新版本 - ✅ 配置 conventional commits 规范
- ✅ 支持
feat(version):格式跳过版本更新
其他平台构建
pnpm dev:alipay # 支付宝小程序开发
pnpm dev:swan # 百度小程序开发
pnpm dev:tt # 字节跳动小程序开发
📋 快速参考
🆕 最新更新（2026-02-15）
详细更新记录：
最新亮点：
- 🎯 文档解析重大升级（多产品支持、智能字段提取）
- 🎯 计划书模块重构（Schema 化、模板字段映射）
- 🎯 消息功能全面优化（布局、交互、红点）
- 🎯 选项控制功能合并
- 🎯 Git 工作流优化（standard-version）
⚡ 常见问题快速解决
| 问题 | 解决方案 | 参考文档 |
|---|---|---|
| NutUI textarea 样式无法覆盖 | 使用原生 <textarea>
|
经验教训 |
| IconFont 动态切换不响应 | 添加 :key="name"
|
经验教训 |
| SVG 图标加载失败（500 错误） | 使用 import 导入 |
经验教训 |
| 代码重复 3 次 | 抽取为 Composable | 经验教训 |
| 组件对象响应式警告 | 使用 shallowRef + markRaw
|
经验教训 |
| 嵌套弹窗层级冲突 | 使用 provide/inject 模式 | 最近提交记录（3357bedb） |
| 401 重定向死循环 | 检查重定向拦截器逻辑 | 最近提交记录（6d2a4ec2） |
🎯 核心架构模式
- 认证流程 - 静默认证 + 401 自动刷新
- 双设计宽度 - NutUI: 375px, 其他: 750px
- 样式策略 - TailwindCSS(80%) + Less(20%)
- 组件抽取 - "第 3 次出现原则"
📦 技术栈
- 框架: Taro 4.1.9 + Vue 3.3.0 + Composition API
- UI 库: NutUI 4.3.13（京东推出的 Taro UI 库）
- 状态管理: Pinia 3.0.3 + taro-plugin-pinia
- HTTP 客户端: axios-miniprogram
- 样式: Less + TailwindCSS 3.x（双设计宽度系统）
- 构建工具: Webpack 5
📖 项目概述
Manulife WeApp（臻奇智荟圈）是一个基于 Taro 4 + Vue 3 + NutUI 构建的财富管理微信小程序。
业务模块
- 产品展示 - 热门产品展示及详情页
- 资料库 - 培训材料和文档管理
- 家办 - 家族办公室服务
- 签单 - 签约流程
- 用户中心 - 个人资料、收藏、反馈、帮助中心
🏗️ 核心架构
1. 身份认证流程（必需）
核心文件：
-
src/utils/openid.js- 微信授权和会话管理 -
src/utils/request.js- 带 401 自动刷新拦截器的 HTTP 客户端 -
src/pages/login/index.vue- 登录页
认证流程：
-
静默认证（
miniProgramAuth()）：- 调用
wx.login()获取 code - 调用后端
/srv/?a=openid接口换取 sessionid - 自动将 sessionid 写入 localStorage
- 调用
-
401 自动刷新：
- API 返回 401 时触发
- 拦截器保存当前页面路径
- 调用
miniProgramAuth()重新获取会话 - 使用新会话重试原始请求
2. API 层架构
API 定义（src/api/index.js）：
export const yourAPI = (params) => {
return buildApiUrl('your_action', params)
}
请求包装器（src/api/fn.js）：
- 所有 API 调用都应通过此包装器
- 处理常见错误场景
- 始终检查
res.code === 1判断成功
3. 增强导航系统
useGo Hook（src/hooks/useGo.js）：
import { useGo } from '@/hooks/useGo'
const go = useGo()
go('/pages/detail/index') // 自动补全路径
go('/pages/product-detail/index', { id: 123 }) // 带查询参数
go.back() // 返回上一页
4. 样式处理策略
TailwindCSS vs Less 使用指南：
| 场景 | 使用 | 比例 |
|---|---|---|
| 布局、间距、排版、颜色 | TailwindCSS | 80% |
| 组件特定样式、深度选择器 | Less | 20% |
5. 响应式优化
处理组件对象响应式：
// ❌ BAD - 深度响应式导致性能问题
const menuItems = ref([
{ icon: IconFont, name: 'heart' }
])
// ✅ GOOD - 使用 shallowRef + markRaw
import { shallowRef, markRaw } from 'vue'
const menuItems = shallowRef([
{ icon: markRaw(IconFont), name: 'heart' }
])
📁 详细文档
开发指南
参考文档
- 页面参考 - 所有页面详细说明
- 组件参考 - 组件库文档
- Composables 参考 - 可复用逻辑
最佳实践
🔧 关键文件
修改前必须理解
-
src/utils/openid.js- 微信授权和会话管理逻辑 -
src/utils/request.js- 带拦截器的 HTTP 客户端 -
src/app.js- 应用启动序列和网络处理 -
src/utils/config.js- 服务器配置（需要修改）
核心业务逻辑
-
src/api/index.js- API 定义 -
src/api/fn.js- 请求包装器 -
src/stores/main.js- 主要状态管理 -
src/stores/user.js- 用户状态管理 -
src/stores/router.js- 路由状态管理
可复用组件
-
src/components/TabBar.vue- 底部导航栏 -
src/components/NavHeader.vue- 自定义导航头 -
src/components/MaterialCard.vue- 资料卡片（可复用） -
src/components/ProductCard.vue- 产品卡片（可复用）
Composables
-
src/composables/useSectionList.js- 分组列表管理 -
src/composables/useFileOperation.js- 文件操作 -
src/composables/useListItemClick.js- 列表点击处理
⚠️ 重要配置
环境配置（src/utils/config.js）：
-
BASE_URL- 设置开发/生产域名 -
REQUEST_DEFAULT_PARAMS.f- 设置业务模块标识符 -
REQUEST_DEFAULT_PARAMS.client_name- 设置应用名称
🚀 快速开始
1. 安装依赖
pnpm install
2. 配置环境
编辑 src/utils/config.js，设置 BASE_URL 和业务参数。
3. 启动开发服务器
pnpm dev:weapp
4. 打开微信开发者工具
导入项目目录：dist/