You've already forked template-MP
文档 优化commit命令配置并新增AGENTS.md项目文档
This commit is contained in:
yuantao
@@ -7,5 +7,5 @@
|
||||
description = "分析您的更改并创建有意义的提交消息"
|
||||
|
||||
prompt = """
|
||||
我会分析您的更改并创建一条有意义的提交消息并使用简单的git命令进行提交更改。我会分析更改，以确定修改了哪些文件、更改的性质（功能、修复、重构等）以及受影响的范围/组件。基于分析结果、以及遵循项目的IFLOW上下文中的提交规范，我会创建一条常规的中文提交消息，其中包含类型（新增|修复|文档|优化|其他）、主题（用现在时清晰描述）。
|
||||
你会分析我的更改并创建一条有意义的提交消息并使用简单的git命令进行提交更改，以确定修改了哪些文件、更改的性质（功能、修复、重构等）以及受影响的范围/组件。基于分析结果、以及遵循项目的IFLOW上下文中的提交规范，你会创建一条常规的中文提交消息，其中包含类型（新增|修复|文档|优化|其他）、主题（用现在时清晰描述），如果IFLOW上下文中不存在提交规范则按照如下规范(git commit -m "新增 XX功能模块"、git commit -m "修复 XX错误"、git commit -m "优化 XX性能"、git commit -m "架构 XX结构")进行提交。
|
||||
"""
|
||||
|
||||
447
AGENTS.md
Normal file
447
AGENTS.md
Normal file
@@ -0,0 +1,447 @@
|
||||
# 项目概述 - IFLOW 上下文
|
||||
|
||||
这是一个基于 UniApp + Vue3 + uView-Plus 的微信小程序项目模板。它提供了一个基础的项目结构和一些常用的工具函数，方便快速开发微信小程序。
|
||||
|
||||
## 技术栈
|
||||
|
||||
* **UniApp**: 跨平台开发框架，用于构建微信小程序。
|
||||
* **Vue3**: 渐进式 JavaScript 框架，用于构建用户界面。
|
||||
* **uView-Plus**: 基于 UniApp 的 UI 组件库。
|
||||
* **z-paging**: 高性能分页加载组件库
|
||||
* **Vuex**: 状态管理库，用于统一管理应用状态。
|
||||
* **Vite**: 现代化构建工具，配置了自定义插件用于manifest.json的appid替换。
|
||||
* **luch-request**: 网络请求库，提供请求封装和拦截器功能。
|
||||
* **uniapp-error-monitor**: 错误监控库，用于捕获和上报小程序运行时错误
|
||||
* **dayjs**: 轻量级日期时间处理库
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
.
|
||||
├── api/ # 接口相关
|
||||
│ ├── modules/ # 业务接口模块
|
||||
│ └── request.js # 请求封装和拦截器配置
|
||||
├── common/ # 公共资源
|
||||
│ ├── styles/ # 全局样式
|
||||
│ │ ├── common.css # CodeFun原子类样式
|
||||
│ │ └── base.scss # 全局样式变量和 Mixins
|
||||
│ └── utils/ # 工具函数
|
||||
│ └── tool.js # 常用工具函数
|
||||
├── components/ # 全局公共组件
|
||||
├── wxcomponents/ # 微信原生组件
|
||||
│ └── painter/ # 海报绘制组件
|
||||
├── uni_modules/ # uni-app 插件
|
||||
│ └── z-paging/ # 分页组件库
|
||||
├── lib/ # 第三方库
|
||||
│ └── luch-request/ # luch-request 网络请求库
|
||||
├── uview-plus/ # uView-Plus 组件库
|
||||
├── mixins/ # Vue 混入
|
||||
│ └── global.js # 全局混入
|
||||
├── pages/ # 主包页面
|
||||
│ └── index/ # 首页
|
||||
├── subPages/ # 分包页面
|
||||
│ └── welcome/ # 欢迎页
|
||||
├── static/ # 静态资源文件
|
||||
│ └── assets/ # 静态图片资源
|
||||
├── store/ # 状态管理
|
||||
│ └── index.js # Vuex store 配置
|
||||
├── scripts/ # 自动化脚本
|
||||
│ └── upload-weapp.js # 微信小程序自动化上传脚本
|
||||
├── App.vue # 应用入口
|
||||
├── main.js # 主入口文件
|
||||
├── pages.json # 页面配置
|
||||
├── manifest.json # 应用配置
|
||||
├── uni.scss # 全局样式变量
|
||||
├── vite.config.js # Vite 编译配置
|
||||
├── .nvmdrc # Node.js 版本要求
|
||||
├── .env # 环境变量配置
|
||||
├── .iflow/ # iFlow CLI 配置
|
||||
├── package.json # 项目依赖配置
|
||||
└── uni.promisify.adaptor.js # uni-app promise 适配器
|
||||
```
|
||||
|
||||
## 开发环境与运行
|
||||
|
||||
### 环境要求
|
||||
|
||||
* Node.js (版本信息在 `.nvmdrc` 文件中指定，当前为 24.0.1)
|
||||
* npm 或 yarn
|
||||
|
||||
### 当前依赖
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"dayjs": "*",
|
||||
"dotenv": "^17.2.2",
|
||||
"uniapp-error-monitor": "*",
|
||||
"vue": "^3.5.21"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 安装依赖
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### 运行项目
|
||||
|
||||
由于这是一个 UniApp 项目，通常需要使用 HBuilderX 或其他支持 UniApp 的 IDE 来运行和调试：
|
||||
|
||||
1. 使用 HBuilderX 打开项目
|
||||
2. 选择"运行到小程序模拟器"或"运行到手机或模拟器"
|
||||
3. 选择微信开发者工具
|
||||
|
||||
### 构建项目
|
||||
|
||||
同样，构建项目也需要使用 HBuilderX 或相应的 CLI 工具。
|
||||
|
||||
### 自动化上传微信小程序
|
||||
|
||||
项目提供了自动化上传微信小程序的功能，可以快速将编译后的小程序上传到微信开发者平台。
|
||||
|
||||
#### 使用前准备
|
||||
|
||||
1. **配置微信开发者工具CLI路径**
|
||||
|
||||
需要设置环境变量 `WECHAT_CLI_PATH`，指向微信开发者工具CLI的路径：
|
||||
|
||||
- **Windows**: `C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat`
|
||||
- **macOS**: `/Applications/wechatwebdevtools.app/Contents/MacOS/cli`
|
||||
|
||||
或者在 `scripts/upload-weapp.js` 中修改 `CONFIG.cliPath` 的值。
|
||||
|
||||
2. **编译项目**
|
||||
|
||||
使用 HBuilderX 编译项目，生成微信小程序代码：
|
||||
- 打开 HBuilderX
|
||||
- 点击"发行" → "小程序-微信"
|
||||
- 等待编译完成
|
||||
|
||||
#### 使用方法
|
||||
|
||||
编译完成后，运行以下命令进行上传：
|
||||
|
||||
```bash
|
||||
npm run upload:weapp
|
||||
```
|
||||
|
||||
#### 功能特性
|
||||
|
||||
自动化上传脚本会自动执行以下操作：
|
||||
|
||||
1. **版本号自增**
|
||||
- 自动递增 `manifest.json` 中的 `versionName`（如 1.0.0 → 1.0.1）
|
||||
- 自动递增 `versionCode`
|
||||
|
||||
2. **生成上传备注**
|
||||
- 获取当前 git 分支名
|
||||
- 获取最近 5 条 git 提交日志
|
||||
- 将英文相对时间转换为中文格式（如 "3 weeks ago" → "3周前"）
|
||||
- 每条日志前添加序号（1、2、3...）
|
||||
|
||||
3. **更新配置文件**
|
||||
- 更新 `manifest.json` 中的版本号
|
||||
|
||||
4. **上传到微信**
|
||||
- 调用微信开发者工具CLI上传编译后的小程序
|
||||
|
||||
#### 上传描述格式
|
||||
|
||||
上传备注的格式示例：
|
||||
|
||||
```
|
||||
[master] (1) 新增IDE配置文件 (yuantao, 3周前) | (2) 优化工具函数 (yuantao, 6周前) | (3) 修复bug (yuantao, 7周前)
|
||||
```
|
||||
|
||||
#### 注意事项
|
||||
|
||||
- 上传前必须先使用 HBuilderX 编译项目
|
||||
- 确保项目是 git 仓库（用于获取日志）
|
||||
- 确保微信开发者工具CLI路径配置正确
|
||||
- 编译后的文件位于 `unpackage/dist/build/mp-weixin` 目录
|
||||
|
||||
## 代码规范与开发约定
|
||||
|
||||
### 样式规范
|
||||
|
||||
* **全局样式变量**: `uni.scss` 提供了全局样式变量
|
||||
* **全局样式文件**: 位于 `common/styles/` 目录
|
||||
* `common.css`: CodeFun 原子类样式，用于快速布局
|
||||
* `base.scss`: SCSS 变量、Mixins 和常用样式类生成器
|
||||
* **样式规范**: 遵循项目中已有的样式风格，统一使用原子类
|
||||
|
||||
### JavaScript 规范
|
||||
|
||||
* **ES6+**: 严格遵循 ES6+ 语法规范
|
||||
* **函数式编程**: 优先使用函数式编程范式
|
||||
* **函数定义**: 使用 `function` 关键字定义方法函数
|
||||
* **响应式数据**:
|
||||
* 少于 4 个 `ref` 时直接使用 `ref`
|
||||
* 超过 4 个时使用 `reactive` 进行封装
|
||||
* **生命周期**: 通过 `@dcloudio/uni-app` 按需导入，如：
|
||||
```javascript
|
||||
import { onLoad, onShow, onHide } from '@dcloudio/uni-app'
|
||||
```
|
||||
页面的加载、挂载生命周期不要使用 `onMounted`，应该使用 `onLoad`
|
||||
* **变量命名**:
|
||||
* 小驼峰命名法: `userName`, `orderList`
|
||||
* 常量全大写: `MAX_LENGTH`, `DEFAULT_VALUE`
|
||||
* 状态类变量: `isLogin`, `isOpen`, `isLoading`
|
||||
* 事件方法: `onClick`, `onSelect`, `onSubmit`
|
||||
* **注释规范**: 变量和方法必须有注释说明和类型说明
|
||||
* **异步处理**: 所有 Promise 类方法使用 `async/await` 写法，避免 `.then` 嵌套
|
||||
* **字符串拼接**: 使用 ES6 模板语法 `` `string ${variable}` ``
|
||||
|
||||
### 静态资源
|
||||
|
||||
* **资源路径**: 使用全局混入的 `ASSETSURL` 变量
|
||||
* **使用方式**:
|
||||
```html
|
||||
// 在 template 中
|
||||
<image :src="`${ASSETSURL}image.png`"/>
|
||||
```
|
||||
|
||||
```html
|
||||
// 在 CSS 中
|
||||
background-image: url($ASSETSURL + 'image.png')
|
||||
```
|
||||
|
||||
```javascript
|
||||
// 在 JavaScript 中
|
||||
const ASSETSURL = import.meta.env.VITE_ASSETSURL
|
||||
const imageUrl = `${ASSETSURL}image.png`
|
||||
```
|
||||
|
||||
## 工具函数 (tool.js)
|
||||
|
||||
`common/utils/tool.js` 提供完整的工具函数库：
|
||||
|
||||
### 提示与加载
|
||||
* `alert(str, icon, duration)`: 文字轻提示
|
||||
* `icon`: 0-无, 1-成功, 2-加载中
|
||||
* `duration`: 提示时间（毫秒）
|
||||
* `loading(title, mask)`: 显示加载状态
|
||||
* `hideLoading()`: 隐藏加载状态
|
||||
|
||||
### 页面跳转
|
||||
* `navigateTo(url)`: 可返回跳转（导航到新页面）
|
||||
* `redirectTo(url)`: 不可返回跳转（重定向到新页面）
|
||||
* `reLaunch(url)`: 清除页面栈跳转（重新启动到新页面）
|
||||
* `switchTab(url)`: 跳转到 TabBar 页面
|
||||
* `navigateBack(delta, fallbackUrl)`: 返回上一页面或指定页面
|
||||
|
||||
### 本地存储
|
||||
* `storage(key, value)`: 设置或获取本地存储
|
||||
* 传入 `value`: 设置存储
|
||||
* 不传 `value`: 读取存储
|
||||
* `key` 为 `'#'`: 清空所有存储
|
||||
* `removeStorage(key)`: 移除本地存储项
|
||||
* `getStorageInfo()`: 获取存储信息
|
||||
|
||||
### 其他功能
|
||||
* `copy(data)`: 复制文本到剪贴板
|
||||
* `saveImageToPhotos(url)`: 保存图片到相册（自动处理权限）
|
||||
* `requestPayment(paymentData)`: 发起微信支付
|
||||
* `upload(filePath)`: 文件上传（自动添加 token）
|
||||
* `loadFont(fontName)`: 动态加载字体（支持缓存）
|
||||
|
||||
## 网络请求
|
||||
|
||||
### 请求配置
|
||||
|
||||
* **请求库**: 使用 `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`
|
||||
* **当前状态**: 基础配置，包含空的 state、mutations、actions 和 getters
|
||||
* **使用方式**: 通过 `createStore` 创建 store 实例
|
||||
|
||||
### 组件库
|
||||
|
||||
* `uni_modules` 目录中的组件无需导入直接可以进行使用。
|
||||
* **组件库**: 集成 `uView-Plus` 和 `z-paging`
|
||||
* **uView-Plus**: 通过 `easycom` 自动导入，无需手动 import
|
||||
```vue
|
||||
// 直接使用，无需import
|
||||
<u-button>按钮</u-button>
|
||||
<u-icon name="home" />
|
||||
```
|
||||
* **组件分类**:
|
||||
* **全局组件**: 放在 `components/` 目录
|
||||
* **页面组件**: 放在页面根目录的 `components/` 目录
|
||||
* **微信原生组件**: 放在页面根目录的 `wxcomponents/` 目录
|
||||
|
||||
### 分页功能
|
||||
|
||||
* **分页组件**: 使用 `z-paging` 实现高性能分页
|
||||
* **全局配置**: 在 `main.js` 中配置 `uni.$zp`
|
||||
* `empty-view-text`: 空数据提示文字（"空空如也~~"）
|
||||
* `refresher-enabled`: 是否启用下拉刷新（true）
|
||||
* **使用方式**:
|
||||
```vue
|
||||
<template>
|
||||
<z-paging
|
||||
ref="paging"
|
||||
v-model="dataList"
|
||||
@query="queryList"
|
||||
>
|
||||
<view v-for="item in dataList" :key="item.id">
|
||||
{{ item.name }}
|
||||
</view>
|
||||
</z-paging>
|
||||
</template>
|
||||
<script setup>
|
||||
import { ref } from 'vue'
|
||||
|
||||
const paging = ref(null)
|
||||
const dataList = ref([])
|
||||
|
||||
// 分页查询函数
|
||||
const queryList = async (pageNo, pageSize) => {
|
||||
try {
|
||||
const result = await api.getList({ pageNo, pageSize })
|
||||
paging.value.complete(result.data.list)
|
||||
} catch (error) {
|
||||
paging.value.complete(false)
|
||||
}
|
||||
}
|
||||
|
||||
// 刷新数据
|
||||
const refresh = () => {
|
||||
paging.value.reload()
|
||||
}
|
||||
</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
|
||||
* **执行时机**: 仅在首次编译时执行，避免热重载时重复执行导致内存占用高
|
||||
|
||||
## 代码提交规范
|
||||
|
||||
### 提交信息格式
|
||||
|
||||
* **新增功能**: `新增 功能描述`
|
||||
* **错误修复**: `修复 问题描述`
|
||||
* **性能优化**: `优化 优化内容`
|
||||
* **文档更新**: `文档 更新内容`
|
||||
|
||||
### 示例
|
||||
|
||||
```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()` 后进行了返回操作，请使用如下规范：
|
||||
```javascript
|
||||
async () => {
|
||||
await tool.alert('提示')
|
||||
await tool.navigateBack()
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 页面开发
|
||||
|
||||
* 使用 Composition API（setup 语法糖）
|
||||
* 遵循 Vue3 响应式原理
|
||||
* 合理使用 computed 和 watch
|
||||
* 页面生命周期使用 `onLoad` 而非 `onMounted`
|
||||
|
||||
### 组件开发
|
||||
|
||||
* 保持组件单一职责
|
||||
* 使用 props 进行父子通信
|
||||
* 合理使用 emits 进行事件派发
|
||||
* 全局组件放在 `components/` 目录
|
||||
|
||||
### 状态管理
|
||||
|
||||
* 合理划分 store 模块
|
||||
* 避免过度依赖全局状态
|
||||
* 及时清理不需要的状态
|
||||
|
||||
### 性能优化
|
||||
|
||||
* 使用 z-paging 进行列表优化
|
||||
* 合理使用图片懒加载
|
||||
* 避免不必要的重复渲染
|
||||
* 使用分包加载减少主包体积
|
||||
|
||||
### 错误处理
|
||||
|
||||
* 所有 API 请求都应使用 try-catch 包裹
|
||||
* 错误信息应友好提示用户
|
||||
* 重要错误会自动上报到企业微信机器人
|
||||
|
||||
### 代码质量
|
||||
|
||||
* 添加必要的注释说明
|
||||
* 遵循统一的代码风格
|
||||
* 定期进行代码审查
|
||||
Reference in New Issue
Block a user