README.md



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


🆕 最新更新（2026-02-13）


权限与测试


✅ 资料查看权限 - 资料查看入口增加登录校验，支持动作级权限扩展
✅ 回跳路径统一 - 统一保存登录回跳路径，确保权限拦截后可恢复
✅ 搜索页测试 - 搜索页测试对齐当前实现并补充接口 Mock


🆕 最新更新（2026-02-12）


计划书功能优化


✅ 状态标记 - 添加计划书卡片状态标记（"生成中" / "已完成"）


黄色背景表示"生成中"状态
绿色背景表示"已完成"状态
使用条件类名动态切换样式


✅ 查看状态更新 - 仅在预览成功后标记为已查看，返回列表不刷新位置
✅ 提交跳转体验 - 提交后先关闭并重置弹框，再无固定延迟跳转结果页
✅ 返回重置体验 - 关闭弹框时清理已选产品，确保返回后表单为空
✅ 字段优化 - 优化提取金额字段并新增每年提取字段


认证与权限优化


✅ 登录权限检查 - 为所有制作计划书按钮添加登录权限检查
✅ 红点状态管理 - 修复退出登录时红点状态未重置的问题
✅ TabBar 红点 - 配置 TabBar 红点功能使用新的 unread_msg_count 字段
✅ 登录页返回 - 修复登录页返回按钮，清空 router store 并跳转到首页
✅ 401 修复 - 修复 401 重定向死循环和返回报错问题


消息功能优化


✅ 消息列表 - 优化消息列表卡片布局，提升信息可读性
✅ 消息详情 - 优化消息详情页布局，避免内容重复显示
✅ 未读提示 - 增加未读消息红点提示
✅ API 错误处理 - 添加消息列表 API 错误提示


视觉优化


✅ 首页网格导航 - 优化导航图标视觉体验
✅ 产品卡片 - 优化 ProductCard 组件视觉样式
✅ 页面风格 - 重构"我的"页面为专业高端风格
✅ 统一视觉 - 优化视觉柔和度和整体统一性
✅ 头图优化 - 优化首页头图 CDN 加载


API 集成


✅ 接口联调完成 - 计划书模块接口联调完成（submitPlanAPI、listAPI）
✅ 总进度 - 29 个接口，已完成 26 个（89.7%）
✅ 关闭 Mock - 禁用消息列表 Mock 数据，使用真实接口


代码质量


✅ 移除本地配置 - 从版本控制中移除本地配置文件 settings.local.json
✅ Composable 抽取 - 提取计划书提交回调逻辑为 composable
✅ 清理调试日志 - 清理项目中的调试日志
✅ 文档更新 - 完善开发文档和经验教训总结


⚡ 常见问题


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


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


🔐 认证流程

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


静默认证：应用启动时自动执行

401 自动刷新：接口返回 401 时自动刷新会话

授权页回跳：认证完成后自动跳转回原页面


核心文件：


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 说明


🔧 可选功能

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


二维码组件：src/components/qrCode.vue


海报生成器：src/components/PosterBuilder/


微信支付：src/utils/wechatPay.js


时间选择器：src/components/time-picker-data/


📚 相关文档


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

CLAUDE.md - 项目开发指南（供 Claude Code 使用）
Taro 官方文档
NutUI 文档
Vue 3 文档
Pinia 文档


⚠️ 注意事项


小程序启动会自动执行静默认证，确保后端接口正常
请求超时默认 5 秒，可在 src/utils/request.js 中修改
NutUI 组件已配置自动导入，无需手动引入
TailwindCSS 已禁用 preflight，避免与小程序样式冲突
认证失败会自动跳转到 /pages/auth/index


所有函数必须有 JSDoc 注释 - 详见 ~/.claude/rules/code-commenting.md


📄 License

MIT