Manulife WeApp（臻奇智荟圈）

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

📚 项目文档

• 经验教训总结 - Taro 项目开发经验、最佳实践和常见陷阱
• CLAUDE.md - 项目开发指南（供 Claude Code 使用）
• 文档导航 - 项目文档索引与使用建议
• 计划书表单 Schema 使用文档 - 计划书表单配置与扩展指南

🚀 快速开始

安装依赖

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
• ✅ 文档预览能力 - DocumentPreview 支持多格式文件预览
• ✅ 统一列表交互 - 搜索、收藏、资料列表统一点击与操作逻辑

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

构建告警修复

• ✅ usePlanView 导出补齐 - 补充 usePlanView 导出并绑定 viewFile，修复构建告警

计划书表单演进

• ✅ Schema 驱动 - 储蓄类模板字段由配置驱动渲染与校验
• ✅ 提交映射下沉 - 提交字段映射从容器迁移到模板配置
• ✅ 人寿/重疾同步 - 人寿与重疾模板改为 Schema 驱动
• ✅ 校验提示优化 - 必填提示与百分比校验统一更准确

字段命名优化

• ✅ 提取方式字段 - 统一将 specified_amount_type 重命名为 withdrawal_method
• ✅ 文档同步 - 更新提取计划相关文档字段示例
• ✅ 优化建议 - 提取计划相关字段命名保持“功能优先”的语义一致性

文档对齐

• ✅ 业务模块更新 - README 页面清单与业务模块对齐现有路由
• ✅ 新人指南更新 - 入口文档从工具生成器调整为业务上手流程
• ✅ 文档导航同步 - docs/README 快速导航修正与补充

计划书模块定位

• ✅ 配置与入口整理 - 补充计划书模块入口、配置与 API 位置说明
• ✅ 优化建议 - 新增产品时优先补齐 form_sn 与 plan_config，避免模板缺失

计划书模块优化补齐

• ✅ 字段分组补齐 - 补齐基本信息/保障/提取字段分组
• ✅ 错误回调兼容 - 支持 onError 回调并保持 onViewError 兼容
• ✅ 转换逻辑修正 - 分元双向转换统一使用转换器
• ✅ 依赖检测测试 - 补充循环依赖检测单测与分组工具测试

计划书配置核查

• ✅ 配置应用核查 - 确认 plan-templates 已驱动表单渲染与提交映射，plan-fields 与字段关联/转换 composable 尚未接入生成链路
• ✅ 依赖与转换接入 - 表单可见性接入 useFieldDependencies，提交金额转换接入 useFieldValueTransform
• ✅ 提取字段拆分 - 指定提取金额与最高固定提取金额字段独立显示与提交映射

🆕 最新更新（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 接口层
├── assets/                     # 静态资源
├── components/                 # 通用组件
│   ├── cards/                  # 卡片组件
│   ├── documents/              # 文档预览组件
│   ├── forms/                  # 表单组件
│   ├── icons/                  # 图标组件
│   ├── list/                   # 列表组件
│   ├── navigation/             # 导航组件
│   └── plan/                   # 计划书相关组件
├── composables/                # 组合式函数
├── config/                     # 功能与权限配置
├── hooks/                      # hooks
├── pages/                      # 页面组件
│   ├── index/                  # 首页
│   ├── product-center/         # 产品中心
│   ├── product-detail/         # 产品详情
│   ├── category-list/          # 分类列表
│   ├── material-list/          # 资料列表
│   ├── week-hot-material/      # 周热门资料
│   ├── signing/                # 签单相关
│   ├── family-office/          # 家办业务
│   ├── plan/                   # 计划书列表
│   ├── plan-submit-result/     # 计划书提交结果
│   ├── search/                 # 搜索
│   ├── document-preview/       # 文档预览
│   ├── message/                # 消息列表
│   ├── message-detail/         # 消息详情
│   ├── feedback/               # 意见反馈
│   ├── feedback-list/          # 反馈列表
│   ├── favorites/              # 我的收藏
│   ├── mine/                   # 我的
│   ├── avatar/                 # 头像编辑
│   ├── help-center/            # 帮助中心
│   ├── login/                  # 登录
│   ├── onboarding/             # 引导页
│   ├── video-player/           # 视频播放
│   └── webview/                # WebView 承载页
├── app.js                      # 应用入口
├── app.config.js               # 页面路由配置
└── app.less                    # 全局样式

📄 页面说明

主要业务页面

• 首页 - 导航入口、产品与资料推荐
• 产品中心 - 产品聚合展示与筛选
• 产品详情 - 产品信息与附件预览入口
• 分类列表/资料列表 - 分类浏览与资料列表
• 周热门资料 - 热门资料聚合列表
• 签单相关 - 业务签单资料入口
• 家办业务 - 家办相关资料入口
• 计划书 - 计划书列表、状态展示
• 计划书提交结果 - 提交完成提示与下一步引导
• 搜索 - 全局搜索与结果分类

辅助与管理页面

• 消息列表/消息详情 - 消息通知与计划书状态查看
• 文档预览/视频播放 - 文件预览与播放
• 意见反馈/反馈列表 - 反馈提交与历史查看
• 我的/头像/帮助中心 - 个人信息与常用入口
• 登录/引导页 - 认证与首次引导
• WebView - 承载外部 H5 内容

页面特性

• ✅ 列表页顶部筛选固定，列表独立滚动
• ✅ 统一的导航头（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/login/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 接口用于微信登录。

📦 技术栈

• 框架：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/login/index
6. 所有函数必须有 JSDoc 注释 - 详见 ~/.claude/rules/code-commenting.md
7. 业务路由以 src/app.config.js 为准，计划类文档仅保留历史记录

✅ 优化建议

1. 持续维护 API 集成日志与页面模块对应关系
2. 文档预览与视频播放页面补充更多异常场景说明
3. 页面入口与权限策略保持同步，避免入口显示但权限不一致

📄 License

MIT