Manulife WeApp（臻奇智荟圈）

基于 Taro 4 + Vue 3 + NutUI 构建的财富管理微信小程序

📚 项目文档

• 经验教训总结 - Taro 项目开发经验、最佳实践和常见陷阱
• CLAUDE.md - 项目开发指南（供 Claude Code 使用）

🚀 快速开始

安装依赖

pnpm install

开发模式

# 微信小程序
pnpm dev:weapp

# H5
pnpm dev:h5

# 支付宝小程序
pnpm dev:alipay

生产构建

pnpm build:weapp

代码检查

pnpm lint

🌟 核心特性

• ✅ 完整的认证系统 - 静默认证 + 401 自动刷新
• ✅ 双设计宽度系统 - NutUI: 375px, 其他: 750px
• ✅ 响应式优化 - shallowRef + markRaw 处理组件对象
• ✅ 样式方案 - TailwindCSS(80%) + Less(20%) 混合使用
• ✅ 组件复用 - "第 3 次出现原则"抽取 Composables
• ✅ 可复用组件 - TabBar、NavHeader、IconFont

⚡ 常见问题

NutUI 组件使用陷阱

问题	解决方案	详细文档
textarea 样式无法覆盖	使用原生 <textarea>	经验教训
IconFont 动态切换不响应	添加 :key="name"	经验教训

静态资源加载问题

问题	解决方案	详细文档
SVG 图标加载失败（500 错误）	使用 import 导入	经验教训

代码质量

• ✅ 所有函数必须有 JSDoc 注释
• ✅ 遵循"第 3 次出现原则"抽取代码
• ✅ 使用 shallowRef + markRaw 优化性能

详见经验教训总结

📁 项目结构

src/
├── api/                    # API 接口层
│   ├── index.js           # 业务接口定义
│   └── fn.js              # HTTP 请求封装
├── assets/                 # 静态资源
│   ├── images/            # 图片资源
│   └── styles/            # 全局样式
├── components/             # 通用组件
│   ├── IconFont.vue       # 图标字体组件
│   ├── NavHeader.vue      # 自定义导航头
│   ├── TabBar.vue         # 底部导航栏
│   ├── SectionCard.vue    # 分组卡片组件
│   ├── FilterTabs.vue     # 筛选标签组件
│   ├── PosterBuilder/     # 海报生成器（可选）
│   └── PlanSchemes/       # 计划书方案组件
├── composables/            # Composition API hooks
│   ├── useSectionList.js  # 分组列表管理
│   ├── useFileOperation.js # 文件操作（下载、预览）
│   └── useListItemClick.js # 列表点击处理
├── hooks/                  # 自定义 hooks
│   └── useGo.js           # 增强导航 hook
├── pages/                  # 页面组件
│   ├── index/             # 首页
│   ├── auth/              # 认证页（必须保留）
│   ├── login/             # 登录页
│   ├── product-detail/    # 产品详情
│   ├── material-list/     # 资料列表
│   ├── knowledge-base/    # 知识库
│   ├── plan/              # 计划书
│   ├── favorites/         # 我的收藏
│   ├── mine/              # 我的
│   └── ...
├── stores/                 # Pinia 状态管理
│   ├── router.js          # 路由状态（认证回跳）
│   ├── main.js            # 主 store
│   └── host.js            # 配置 store
├── utils/                  # 工具函数
│   ├── authRedirect.js    # 认证流程核心（必须）
│   ├── request.js         # HTTP 客户端核心（必须）
│   ├── config.js          # 环境配置（⚠️ 需修改）
│   ├── tools.js           # 通用工具
│   └── documentIcons.js   # 文档图标工具
├── app.js                  # 应用入口
├── app.config.js           # 页面路由配置
└── app.less                # 全局样式

📄 页面说明

主要页面

• 首页 - 产品展示、热门资料、导航入口
• 产品详情 - 完整产品信息展示
• 资料列表 - 培训材料和文档管理
• 知识库 - 培训材料和案例知识库
• 计划书 - 计划书列表和管理
• 我的收藏 - 收藏内容管理
• 我的 - 个人资料、功能菜单

页面特性

• ✅ 顶部筛选固定，列表独立滚动
• ✅ 统一的导航头（NavHeader）和底部导航（TabBar）
• ✅ 统一的文件操作逻辑（下载、预览）
• ✅ 统一的列表点击处理

⚙️ 配置说明

1. 修改服务器配置

编辑 src/utils/config.js：

const BASE_URL = process.env.NODE_ENV === 'production'
    ? 'https://your-production-domain.com'  // 生产环境域名
    : 'https://your-dev-domain.com'         // 开发环境域名

export const REQUEST_DEFAULT_PARAMS = {
    f: 'YOUR_MODULE',           // 业务模块标识
    client_name: 'YOUR_APP',    // 应用名称
}

2. 定义 API 接口

编辑 src/api/index.js：

export const yourAPI = (params) => {
    return buildApiUrl('your_action', params)
}

3. 配置页面路由

编辑 src/app.config.js：

export default {
  pages: [
    'pages/index/index',
    'pages/auth/index',
    'pages/your-page/index',  // 添加您的页面
  ],
}

4. 双设计宽度体系

• NutUI 组件：基准宽度 375px
• 其他所有页面：基准宽度 750px

详见双设计宽度系统使用指南

🔐 认证流程

项目内置完整的微信登录认证系统：

1. 静默认证：应用启动时自动执行
2. 401 自动刷新：接口返回 401 时自动刷新会话
3. 授权页回跳：认证完成后自动跳转回原页面

核心文件：

• src/utils/authRedirect.js - 认证流程管理
• src/utils/request.js - HTTP 请求拦截器

重要：后端需提供 /srv/?a=openid_wxapp 接口用于微信登录。

📦 技术栈

• 框架：Taro 4.x
• UI 库：Vue 3 + NutUI 4.x
• 状态管理：Pinia
• HTTP：axios-miniprogram
• 样式：Less + TailwindCSS
• 构建工具：Webpack 5

🎯 路径别名

@/utils      -> src/utils
@/components -> src/components
@/images     -> src/assets/images
@/assets     -> src/assets
@/composables-> src/composables
@/api        -> src/api
@/stores     -> src/stores
@/hooks      -> src/hooks

📝 开发规范

组件编写

• ✅ 使用 Vue 3 Composition API
• ✅ Props 定义清晰，有类型和默认值
• ✅ 所有函数必须有 JSDoc 注释

API 调用

• ✅ 接口统一在 src/api/index.js 定义
• ✅ 使用 xxxAPI(params) 命名格式
• ✅ 始终检查 res.code === 1 判断成功

状态管理

• ✅ 使用 Pinia 进行状态管理
• ✅ 复杂逻辑使用 composables 封装

样式编写

• ✅ TailwindCSS: 布局、间距、颜色（80%）
• ✅ Less: 组件样式、动画、伪元素（20%）

代码注释要求

遵循全局代码注释规范（~/.claude/rules/code-commenting.md）：

• ✅ 所有函数必须有 JSDoc 注释
• ✅ 包含 @description 说明功能
• ✅ 所有参数都有 @param 说明
• ✅ 返回值有 @returns 说明

🔧 可选功能

以下功能可以根据项目需求选择使用或移除：

1. 二维码组件：src/components/qrCode.vue
2. 海报生成器：src/components/PosterBuilder/
3. 微信支付：src/utils/wechatPay.js
4. 时间选择器：src/components/time-picker-data/

📚 相关文档

• 经验教训总结 - Taro 项目开发经验、最佳实践和常见陷阱
• CLAUDE.md - 项目开发指南（供 Claude Code 使用）
• Taro 官方文档
• NutUI 文档
• Vue 3 文档
• Pinia 文档

⚠️ 注意事项

1. 小程序启动会自动执行静默认证，确保后端接口正常
2. 请求超时默认 5 秒，可在 src/utils/request.js 中修改
3. NutUI 组件已配置自动导入，无需手动引入
4. TailwindCSS 已禁用 preflight，避免与小程序样式冲突
5. 认证失败会自动跳转到 /pages/auth/index
6. 所有函数必须有 JSDoc 注释 - 详见 ~/.claude/rules/code-commenting.md

📄 License

MIT