CLAUDE.md 8.88 KB

Raw Blame History Permalink



CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在处理此仓库代码时提供指导。

设计原则：这是一个轻量级索引文档，只保留必须立即知道的信息。详细内容通过链接访问。


📚 项目文档索引


功能屏蔽说明 - 因个人主体限制而屏蔽的功能及恢复方法

经验教训总结 - Taro 项目开发经验、最佳实践和常见陷阱

接口联调日志 - API 集成状态和联调记录

变更日志 - 项目版本更新历史

项目 README - 项目概述和快速开始指南


🚀 开发命令


核心命令

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）

详细更新记录：


变更日志 - 完整版本更新历史

接口联调日志 - API 集成状态


最新亮点：


🎯 文档解析重大升级（多产品支持、智能字段提取）
🎯 计划书模块重构（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' }
])


📁 详细文档


开发指南


页面开发指南 - 如何添加新页面

API 集成指南 - API 调用详解

导航系统指南 - 导航和参数传递


参考文档


页面参考 - 所有页面详细说明

组件参考 - 组件库文档

Composables 参考 - 可复用逻辑


最佳实践


最佳实践 - 组件开发、API 集成、性能优化

调试指南 - 调试技巧和工具


🔧 关键文件


修改前必须理解


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/


📖 更多文档


页面参考 - 查看所有页面

组件参考 - 查看所有组件

Composables 参考 - 查看所有 Composables

最佳实践 - 代码质量和性能优化

调试指南 - 调试技巧

经验教训总结 - 常见陷阱和解决方案