README.md
12.2 KB
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 支持多格式文件预览
- ✅ 统一列表交互 - 搜索、收藏、资料列表统一点击与操作逻辑
📝 更新日志
完整更新记录请查看 CHANGELOG.md
近期亮点
- 文档解析系统 - 从 PDF/DOCX 自动生成计划书配置（支持多产品文档分割）
- 计划书 Schema 驱动 - 储蓄类/人寿/重疾模板字段配置化
- Git 工作流标准化 - 使用 standard-version + Conventional Commits
- 认证系统完善 - 401 自动刷新、登录权限检查、TabBar 红点
- API 集成进度 - 29 个接口，已完成 26 个（89.7%）
⚡ 常见问题
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
🔐 认证流程
项目内置完整的微信登录认证系统：
- 静默认证：应用启动时自动执行
- 401 自动刷新：接口返回 401 时自动刷新会话
- 登录页回跳：登录完成后自动跳转回原页面
核心文件：
-
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说明
🔧 开发工具
文档解析工具
自动从保险产品文档（PDF/DOCX）中提取配置，生成计划书模板：
# 解析所有待处理文档
pnpm parse:docs
# 解析指定文件
pnpm parse:docs -- --file=产品说明书.pdf
# 查看待处理文档列表
pnpm parse:docs -- --list
# 应用审核通过的配置
pnpm parse:docs -- --apply=计划书模版4
# 预览变更（不实际修改）
pnpm parse:docs -- --apply=计划书模版4 --dry-run
# 查看配置状态
pnpm parse:docs -- --status
核心能力：
- 📄 支持 PDF、DOCX、TXT、MD 格式
- 🔄 自动识别并分割多产品文档
- 🤖 智能字段提取（8 个核心字段）
- ✅ 人工审核流程
- 💾 自动备份和回滚
详细文档: 文档解析系统架构
可选功能组件
以下功能可以根据项目需求选择使用或移除：
-
二维码组件：
src/components/qrCode.vue -
海报生成器：
src/components/PosterBuilder/ -
微信支付：
src/utils/wechatPay.js -
时间选择器：
src/components/time-picker-data/
✅ 优化建议
文档解析系统
| 优先级 | 优化项 | 说明 |
|---|---|---|
| 🔴 P0 | 启用 AI 服务 | 配置 AI_SERVICE_TYPE 提升复杂文档解析准确率 |
| 🟡 P1 | 完善 .doc 支持 | 使用 antiword 或 LibreOffice 转换 |
| 🟡 P1 | 增加自动化测试 | 补充 parse-docs.test.js 测试用例 |
| 🟢 P2 | 添加 OCR 能力 | 支持扫描件解析（Tesseract.js） |
项目整体
- 持续维护 API 集成日志与页面模块对应关系
- 文档预览与视频播放页面补充更多异常场景说明
- 页面入口与权限策略保持同步，避免入口显示但权限不一致
📚 相关文档
- 文档解析系统架构 - 计划书配置自动化工具详解
- 经验教训总结 - Taro 项目开发经验、最佳实践和常见陷阱
- CLAUDE.md - 项目开发指南（供 Claude Code 使用）
- 文档解析待处理说明 - 文档解析样本与脚本使用方式
- 文档解析改造任务 - 解析链路改造进度与验收
- Taro 官方文档
- NutUI 文档
- Vue 3 文档
- Pinia 文档
⚠️ 注意事项
- 小程序启动会自动执行静默认证，确保后端接口正常
- 请求超时默认 5 秒，可在
src/utils/request.js中修改 - NutUI 组件已配置自动导入，无需手动引入
- TailwindCSS 已禁用 preflight，避免与小程序样式冲突
- 认证失败会自动跳转到
/pages/login/index -
所有函数必须有 JSDoc 注释 - 详见
~/.claude/rules/code-commenting.md - 业务路由以
src/app.config.js为准，计划类文档仅保留历史记录 - 文档解析成功后原始文档会自动归档到
docs/to-parse/archived/YYYY-MM-DD/ - 待审核文件按原始文档名分目录存放于
docs/parse-audit/pending/<原始文档名>/
✅ 优化建议
- 持续维护 API 集成日志与页面模块对应关系
- 文档预览与视频播放页面补充更多异常场景说明
- 页面入口与权限策略保持同步，避免入口显示但权限不一致
📄 License
MIT