README.md
7.63 KB
manulife-weapp
基于 Taro 4 + Vue 3 + NutUI 的微信小程序模板项目
🚀 快速开始
安装依赖
pnpm install
开发模式
# 微信小程序
pnpm dev:weapp
# H5
pnpm dev:h5
# 支付宝小程序
pnpm dev:alipay
生产构建
pnpm build:weapp
📁 项目结构
src/
├── api/ # API 接口层
│ ├── index.js # 业务接口定义（需根据业务修改）
│ ├── fn.js # HTTP 请求封装
│ └── wx/ # 微信相关接口（可选）
├── assets/ # 静态资源
│ ├── images/ # 图片资源
│ ├── styles/ # 全局样式
│ └── css/ # CSS 文件
├── components/ # 通用组件
│ ├── PosterBuilder/ # 海报生成器（可选）
│ ├── time-picker-data/ # 时间选择器
│ ├── PlanPopup/ # 录入计划书弹窗容器
│ ├── PlanSchemes/ # 录入计划书方案组件
│ ├── indexNav.vue # 底部导航
│ └── qrCode.vue # 二维码组件（可选）
├── composables/ # Composition API hooks
│ ├── useOfflineBookingCache.js # 离线缓存 hook
│ └── useOfflineBookingCachePolling.js # 轮询刷新 hook
├── hooks/ # 自定义 hooks
│ └── useGo.js # 导航辅助 hook
├── pages/ # 页面组件
│ ├── index/ # 首页（示例页面）
│ └── auth/ # 认证页（必须保留）
├── stores/ # Pinia 状态管理
│ ├── router.js # 路由状态（用于认证回跳）
│ ├── main.js # 主 store
│ ├── host.js # 配置 store
│ └── counter.js # 示例 store
├── utils/ # 工具函数
│ ├── authRedirect.js # 认证流程核心（必须）
│ ├── request.js # HTTP 客户端核心（必须）
│ ├── network.js # 网络状态监测
│ ├── config.js # 环境配置（⚠️ 需修改）
│ ├── tools.js # 通用工具
│ ├── uiText.js # 文案管理
│ ├── wechatPay.js # 微信支付（可选）
│ ├── mixin.js # Vue mixin
│ ├── polyfill.js # 浏览器兼容
│ └── weapp.js # 小程序工具
├── app.js # 应用入口
├── app.config.js # 页面路由配置
└── app.less # 全局样式
📄 页面说明
- 计划书页面支持顶部搜索与标签固定，列表区域独立滚动，便于快速筛选和浏览
- 资料列表、知识库、收藏、计划书页面统一使用 FilterTabs 组件进行横向筛选
✅ 优化建议
- 新增筛选类页面优先复用 FilterTabs，避免重复样式与交互逻辑
⚙️ 配置说明
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，添加您的业务接口：
import { buildApiUrl } from '@/utils/tools'
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
此配置已在 config/index.js 中设置，请确保遵循此规范。
🔐 认证流程
项目内置完整的微信登录认证系统：
- 静默认证：应用启动时自动执行静默认证
- 401 自动刷新：当接口返回 401 时，自动刷新会话并重试请求
- 授权页回跳：认证完成后自动跳转回原页面
核心文件：
-
src/utils/authRedirect.js- 认证流程管理 -
src/utils/request.js- HTTP 请求拦截器
重要：后端需提供 /srv/?a=openid_wxapp 接口用于微信登录。
🌐 弱网/离线支持
项目内置弱网和离线支持：
- 请求超时处理：自动检测网络超时并降级处理
- 离线缓存：支持离线数据缓存和读取
- 弱网提示：统一的弱网提示文案
相关文件：
src/composables/useOfflineBookingCache.jssrc/composables/useOfflineBookingCachePolling.jssrc/utils/uiText.js
📦 技术栈
- 框架：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
- 组件统一放在
src/components/目录 - Props 定义清晰，注释详细
- 图标组件直接使用
@nutui/icons-vue-taro的IconFont - 代码注释：所有函数和方法必须使用 JSDoc 注释，详细说明功能、参数、返回值
API 调用
- 接口统一在
src/api/index.js定义 - 使用
xxxAPI(params)命名格式 - 请求方法统一使用
src/api/fn.js中的封装 - 代码注释：每个 API 接口都需要 JSDoc 注释说明用途和参数
状态管理
- 使用 Pinia 进行状态管理
- Store 文件统一放在
src/stores/目录 - 复杂逻辑使用 composables 封装
- 代码注释：Store 的 state、actions 都需要详细注释
样式编写
- 通用样式使用 TailwindCSS 工具类
- 组件样式使用 Less
- NutUI 组件使用 375px 设计稿，其他使用 750px
代码注释要求
遵循全局代码注释规范（~/.claude/rules/code-commenting.md）：
- ✅ 所有函数必须有 JSDoc 注释
- ✅ 包含
@description说明功能 - ✅ 所有参数都有
@param说明 - ✅ 返回值有
@returns说明 - ✅ 复杂逻辑需要详细注释
- ✅ 正则表达式需要说明含义
🔧 可选功能
以下功能可以根据项目需求选择使用或移除：
-
二维码组件：
src/components/qrCode.vue -
海报生成器：
src/components/PosterBuilder/ -
微信支付：
src/utils/wechatPay.js、src/api/wx/ -
时间选择器：
src/components/time-picker-data/ -
离线缓存：
src/composables/useOfflineBookingCache.js
📚 相关文档
⚠️ 注意事项
- 小程序启动会自动执行静默认证，确保后端接口正常
- 请求超时默认 5 秒，可在
src/utils/request.js中修改 - NutUI 组件已配置自动导入，无需手动引入
- TailwindCSS 已禁用 preflight，避免与小程序样式冲突
- 认证失败会自动跳转到
/pages/auth/index
📄 License
MIT