yuantao/template-MP
Template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

文档 完善IFLOW.md项目文档，补充错误监控、网络请求配置等章节，优化代码规范说明

Browse Source
This commit is contained in:
yuantao
2026-01-22 16:35:16 +08:00
parent 7b9ce380b2
commit b19663aed4
1 changed files with 218 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
IFLOW.md
View File

@@ -7,28 +7,30 @@
* **UniApp**: 跨平台开发框架，用于构建微信小程序。
* **Vue3**: 渐进式 JavaScript 框架，用于构建用户界面。
* **uView-Plus**: 基于 UniApp 的 UI 组件库。
* **z-paging**: 一个用于处理分页加载的组件库。
* **z-paging**: 高性能分页加载组件库
* **Vuex**: 状态管理库，用于统一管理应用状态。
* **Vite**: 现代化构建工具，配置了自定义插件用于manifest.json的appid替换。
* **luch-request**: 网络请求库，提供请求封装和拦截器功能。
* **uniapp-error-monitor**: 错误监控库，用于捕获和上报小程序运行时错误
* **dayjs**: 轻量级日期时间处理库
## 目录结构
```
.
├── api/ # 接口相关
│ ├── modules/ # 业务接口（目录存在待完善）
│ └── request.js # 请求封装
│ ├── modules/ # 业务接口模块
│ └── request.js # 请求封装和拦截器配置
├── common/ # 公共资源
│ ├── styles/ # 全局样式
│ │ ├── common.css # codefun原子类样式（预留）
│ │ └── base.scss # 全局样式变量（预留）
│ │ ├── common.css # CodeFun原子类样式
│ │ └── base.scss # 全局样式变量和 Mixins
│ └── utils/ # 工具函数
│ └── tool.js # 常用工具函数
├── components/ # 公共组件（目录存在待完善）
├── components/ # 全局公共组件
├── wxcomponents/ # 微信原生组件
│ └── painter/ # 海报绘制组件
├── uni_modules/ # uni-app 组件
├── uni_modules/ # uni-app 插件
│ └── z-paging/ # 分页组件库
├── lib/ # 第三方库
│ └── luch-request/ # luch-request 网络请求库
@@ -42,6 +44,7 @@
├── static/ # 静态资源文件
│ └── assets/ # 静态图片资源
├── store/ # 状态管理
│ └── index.js # Vuex store 配置
├── scripts/ # 自动化脚本
│ └── upload-weapp.js # 微信小程序自动化上传脚本
├── App.vue # 应用入口
@@ -51,7 +54,7 @@
├── uni.scss # 全局样式变量
├── vite.config.js # Vite 编译配置
├── .nvmdrc # Node.js 版本要求
├── .env # 环境变量
├── .env # 环境变量配置
├── .iflow/ # iFlow CLI 配置
├── package.json # 项目依赖配置
└── uni.promisify.adaptor.js # uni-app promise 适配器
@@ -162,52 +165,52 @@ npm run upload:weapp
## 代码规范与开发约定
## 样式规范
### 样式规范
* `uni.scss` 提供了全局样式变量
* **全局样式**: 位于 `common/styles/` 目录
* `common.css`: CodeFun原子类样式，用于快速布局
* `base.scss`: SCSS变量、Mixins和常用样式类生成器
* **全局样式变量**: `uni.scss` 提供了全局样式变量
* **全局样式文件**: 位于 `common/styles/` 目录
* `common.css`: CodeFun 原子类样式，用于快速布局
* `base.scss`: SCSS 变量、Mixins 和常用样式类生成器
* **样式规范**: 遵循项目中已有的样式风格，统一使用原子类
## JavaScript规范
### JavaScript 规范
* **ES6+**: 严格遵循ES6+语法规范
* **ES6+**: 严格遵循 ES6+ 语法规范
* **函数式编程**: 优先使用函数式编程范式
* **函数定义**: 使用 `function` 关键字定义方法函数
* **响应式数据**:
* 少于4个 `ref` 时直接使用 `ref`
* 超过4个时使用 `reactive` 进行封装
* 少于 4 个 `ref` 时直接使用 `ref`
* 超过 4 个时使用 `reactive` 进行封装
* **生命周期**: 通过 `@dcloudio/uni-app` 按需导入，如：
```javascript
import { onLoad, onShow, onHide } from '@dcloudio/uni-app'
```
页面的加载、挂载生命周期不要使用 `onMounted` 应该使用 `onLoad`
页面的加载、挂载生命周期不要使用 `onMounted`，应该使用 `onLoad`
* **变量命名**:
* 小驼峰命名法: `userName`, `orderList`
* 常量全大写: `MAX_LENGTH`, `DEFAULT_VALUE`
* 状态类变量: `isLogin`, `isOpen`, `isLoading`
* 事件方法: `onClick`, `onSelect`, `onSubmit`
* **注释规范**: 变量和方法必须有注释说明和类型说明
* **异步处理**: 所有Promise类方法使用 `async/await` 写法，避免 `.then` 嵌套
* **字符串拼接**: 使用ES6模板语法 `` `string ${variable}` ``
* **异步处理**: 所有 Promise 类方法使用 `async/await` 写法，避免 `.then` 嵌套
* **字符串拼接**: 使用 ES6 模板语法 `` `string ${variable}` ``
## 静态资源
### 静态资源
* **资源路径**: 使用全局混入的 `ASSETSURL` 变量
* **使用方式**:
```html
// 在template中
<image src="`${ASSETSURL}image.png`"/>
// 在 template 中
<image :src="`${ASSETSURL}image.png`"/>
```
```html
// 在CSS中
// 在 CSS 中
background-image: url($ASSETSURL + 'image.png')
```
```javascript
// 在JavaScript中
// 在 JavaScript 中
const ASSETSURL = import.meta.env.VITE_ASSETSURL
const imageUrl = `${ASSETSURL}image.png`
```
@@ -217,49 +220,67 @@ npm run upload:weapp
`common/utils/tool.js` 提供完整的工具函数库：
### 提示与加载
* `alert()`: 文字轻提示
* `loading()`: 显示加载状态
* `alert(str, icon, duration)`: 文字轻提示
* `icon`: 0-无, 1-成功, 2-加载中
* `duration`: 提示时间（毫秒）
* `loading(title, mask)`: 显示加载状态
* `hideLoading()`: 隐藏加载状态
### 页面跳转
* `navigateTo()`: 跳转到指定页面
* `redirectTo()`: 关闭当前页面并跳转
* `reLaunch()`: 关闭所有页面并跳转
* `switchTab()`: 跳转到TabBar页面
* `navigateBack()`: 返回上一页面
* `navigateTo(url)`: 可返回跳转（导航到新页面）
* `redirectTo(url)`: 不可返回跳转（重定向到新页面）
* `reLaunch(url)`: 清除页面栈跳转（重新启动到新页面）
* `switchTab(url)`: 跳转到 TabBar 页面
* `navigateBack(delta, fallbackUrl)`: 返回上一页面或指定页面
### 本地存储
* `storage()`: 设置或获取本地存储
* `removeStorage()`: 移除本地存储项
* `storage(key, value)`: 设置或获取本地存储
* 传入 `value`: 设置存储
* 不传 `value`: 读取存储
* `key` 为 `'#'`: 清空所有存储
* `removeStorage(key)`: 移除本地存储项
* `getStorageInfo()`: 获取存储信息
### 其他功能
* `copy()`: 复制文本到剪贴板
* `saveImageToPhotos()`: 保存图片到相册
* `requestPayment()`: 发起微信支付
* `upload()`: 文件上传
* `loadFont()`: 动态加载字体
* `copy(data)`: 复制文本到剪贴板
* `saveImageToPhotos(url)`: 保存图片到相册（自动处理权限）
* `requestPayment(paymentData)`: 发起微信支付
* `upload(filePath)`: 文件上传（自动添加 token）
* `loadFont(fontName)`: 动态加载字体（支持缓存）
### 网络请求
## 网络请求
* 网络请求使用 `lib/luch-request` 库进行封装。
* 全局配置在 `api/request.js` 中定义，包括基础URL、请求头、SSL验证等。
* 包含请求和响应拦截器，用于处理通用逻辑（如错误提示、鉴权等）。
* 基础URL通过环境变量 `VITE_BASE_URL` 配置。
* 各业务板块的接口都应存放在 `api/modules` 下，并将单个接口进行导出以便页面按需导入。
### 请求配置
* **请求库**: 使用 `lib/luch-request` 库进行封装
* **全局配置**: 在 `api/request.js` 中定义
* 基础 URL: 通过环境变量 `VITE_BASE_URL` 配置
* SSL 验证: 关闭（`sslVerify: false`）
* 请求拦截器: 处理通用逻辑（如添加 token）
* 响应拦截器: 处理错误提示、错误监控上报等
### 错误监控
* **错误监控库**: 集成 `uniapp-error-monitor`
* **监控配置**: 在 `main.js` 中初始化
* 启用全局错误捕获: `enableGlobalError: true`
* 启用 Promise 错误捕获: `enablePromiseError: true`
* 禁用 console.error 捕获: `enableConsoleError: false`
* 企业微信机器人通知: 通过 `VITE_WEBHOOK` 配置
* **错误上报**: 在 `api/request.js` 的响应拦截器中自动上报 API 错误
### 状态管理 (Vuex)
* 项目集成了Vuex进行全局状态管理。
* 状态管理文件位于 `store/index.js`。
* 使用 `createStore` 创建store实例。
* 目前处于基础状态，包含空的state、mutations、actions和getters。
* **状态管理库**: 使用 Vuex 进行全局状态管理
* **配置文件**: `store/index.js`
* **当前状态**: 基础配置，包含空的 state、mutations、actions 和 getters
* **使用方式**: 通过 `createStore` 创建 store 实例
## 组件规范
### 组件库
* `uni_modules` 目录中的组件无需导入直接可以进行使用。
* **组件库**: 集成 `uView-Plus` 和 `z-paging`
* **自动导入**: `uView-Plus` 通过 `easycom` 自动导入
* **uView-Plus**: 通过 `easycom` 自动导入，无需手动 import
```vue
// 直接使用，无需import
<u-button>按钮</u-button>
@@ -270,9 +291,12 @@ npm run upload:weapp
* **页面组件**: 放在页面根目录的 `components/` 目录
* **微信原生组件**: 放在页面根目录的 `wxcomponents/` 目录
## 分页功能
### 分页功能
* **分页组件**: 使用 `z-paging` 实现高性能分页
* **全局配置**: 在 `main.js` 中配置 `uni.$zp`
* `empty-view-text`: 空数据提示文字（"空空如也~~"）
* `refresher-enabled`: 是否启用下拉刷新（true）
* **使用方式**:
```vue
<template>
@@ -286,7 +310,6 @@ npm run upload:weapp
</view>
</z-paging>
</template>
<script setup>
import { ref } from 'vue'
@@ -310,83 +333,115 @@ npm run upload:weapp
</script>
```
### 路由配置
## 路由配置
* **主包页面**: 放在 `pages/` 目录
* **分包页面**: 放在 `subPages/` 目录
* **TabBar配置**: 在 `pages.json` 中配置底部导航
## 环境配置
### 环境变量
项目使用环境变量管理不同环境的配置，通过 `.env` 文件配置：
* `VITE_BASE_URL`: 接口地址
* `VITE_ASSETSURL`: 资源地址
* `VITE_APPID`: 小程序 APPID
* `VITE_APPNAME`: 小程序名称
* `VITE_UNI_APPID`: UNI-APPID
* `VITE_LIBVERSION`: 微信小程序基础库版本
* `VITE_WEBHOOK`: 企业微信机器人地址（用于错误监控）
### Vite 配置
* `vite.config.js` 包含了自定义插件用于在编译时替换 `manifest.json` 中的 appid
* 仅在首次编译时执行，避免热重载时重复执行导致内存占用高
* 支持环境变量配置：
* `VITE_APPID` - 微信小程序APPID
* `VITE_UNI_APPID` - uni-app APPID
* `VITE_LIBVERSION` - 微信小程序基础库版本
### 环境配置
* 项目使用环境变量管理不同环境的配置，通过 `.env` 文件配置：
* `VITE_BASE_URL` - 接口地址
* `VITE_ASSETSURL` - 资源地址
* `VITE_APPID` - 小程序APPID
* `VITE_UNI_APPID` - UNI-APPID
* `VITE_LIBVERSION` - 微信小程序基础库版本
### 全局配置
* `main.js` 中配置了 `uni.$zp` 全局配置：
* `'empty-view-text'` - 空数据提示文字
* `'refresher-enabled'` - 是否启用下拉刷新
* **配置文件**: `vite.config.js`
* **自定义插件**: 在编译时替换 `manifest.json` 中的 appid
* **执行时机**: 仅在首次编译时执行，避免热重载时重复执行导致内存占用高
## 代码提交规范
### 提交信息格式
* **新增功能**: `新增 功能描述`
* **错误修复**: `修复 问题描述`
* **性能优化**: `优化 优化内容`
* **文档更新**: `文档 更新内容`
### 示例
```bash
git commit -m "新增 推广海报生成功能"
git commit -m "修复 购物车数量计算错误"
git commit -m "优化 接口请求性能"
```
### 其他
## 微信开放能力使用规范
* 项目中的分享功能应该使用微信原生的分享功能，通过 `button` 或 `u-button` 组件的 `open-type="share"` 属性实现。
* 项目中的头像编辑和获取功能应该使用微信原生获取头像昵称的开放能力，通过 `button` 或 `u-button` 组件的 `open-type="chooseAvatar"` 属性和其触发的 `@chooseavatar` 事件实现。
* 项目中的昵称编辑和获取功能应该使用微信原生获取头像昵称的开放能力，通过 `input` 或 `u-input` 组件的 `open-type="nickname"` 属性实现。
* 项目集成了promise适配器 `uni.promisify.adaptor.js`，用于统一处理异步操作。
* 如果在使用工具函数中的 `alert()` 后进行了返回操作，请使用如下规范：
### 分享功能
* 使用微信原生的分享功能
* 通过 `button` 或 `u-button` 组件的 `open-type="share"` 属性实现
### 头像获取
* 使用微信原生获取头像昵称的开放能力
* 通过 `button` 或 `u-button` 组件的 `open-type="chooseAvatar"` 属性实现
* 通过 `@chooseavatar` 事件获取头像
### 昵称获取
* 使用微信原生获取头像昵称的开放能力
* 通过 `input` 或 `u-input` 组件的 `open-type="nickname"` 属性实现
## 其他规范
* **Promise 适配器**: 项目集成了 `uni.promisify.adaptor.js`，用于统一处理异步操作
* **异步返回规范**: 如果在使用工具函数中的 `alert()` 后进行了返回操作，请使用如下规范：
```javascript
async ()=>{
async () => {
await tool.alert('提示')
await tool.navigateBack()
}
```
* 项目集成了 `uniapp-error-monitor` 错误监控库，用于捕获和上报小程序运行时的错误信息。
## 最佳实践
### 页面开发
* 使用Composition API (setup语法糖)
* 遵循Vue3响应式原理
* 合理使用computed和watch
* 使用 Composition API（setup 语法糖）
* 遵循 Vue3 响应式原理
* 合理使用 computed 和 watch
* 页面生命周期使用 `onLoad` 而非 `onMounted`
### 组件开发
* 保持组件单一职责
* 使用props进行父子通信
* 合理使用emits进行事件派发
* 使用 props 进行父子通信
* 合理使用 emits 进行事件派发
* 全局组件放在 `components/` 目录
### 状态管理
* 合理划分store模块
* 合理划分 store 模块
* 避免过度依赖全局状态
* 及时清理不需要的状态
### 性能优化
* 使用z-paging进行列表优化
* 使用 z-paging 进行列表优化
* 合理使用图片懒加载
* 避免不必要的重复渲染
* 使用分包加载减少主包体积
### 错误处理
* 所有 API 请求都应使用 try-catch 包裹
* 错误信息应友好提示用户
* 重要错误会自动上报到企业微信机器人
### 代码质量
* 添加必要的注释说明
* 遵循统一的代码风格
* 定期进行代码审查