From 1621d791922d5335fe463d37f117c9bfd5a1f2b3 Mon Sep 17 00:00:00 2001 From: yuantao Date: Sat, 31 Jan 2026 09:52:01 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=20=E4=BC=98=E5=8C=96commit?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E9=85=8D=E7=BD=AE=E5=B9=B6=E6=96=B0=E5=A2=9E?= =?UTF-8?q?AGENTS.md=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .iflow/commands/commit.toml | 2 +- AGENTS.md | 447 ++++++++++++++++++++++++++++++++++++ 2 files changed, 448 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/.iflow/commands/commit.toml b/.iflow/commands/commit.toml index 4d5373d..b69b581 100644 --- a/.iflow/commands/commit.toml +++ b/.iflow/commands/commit.toml @@ -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结构")进行提交。 """ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3661697 --- /dev/null +++ b/AGENTS.md @@ -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 中 + + ``` + + ```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 + 按钮 + + ``` +* **组件分类**: + * **全局组件**: 放在 `components/` 目录 + * **页面组件**: 放在页面根目录的 `components/` 目录 + * **微信原生组件**: 放在页面根目录的 `wxcomponents/` 目录 + +### 分页功能 + +* **分页组件**: 使用 `z-paging` 实现高性能分页 +* **全局配置**: 在 `main.js` 中配置 `uni.$zp` + * `empty-view-text`: 空数据提示文字（"空空如也~~"） + * `refresher-enabled`: 是否启用下拉刷新（true） +* **使用方式**: + ```vue + + + ``` + +## 路由配置 + +* **主包页面**: 放在 `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 包裹 +* 错误信息应友好提示用户 +* 重要错误会自动上报到企业微信机器人 + +### 代码质量 + +* 添加必要的注释说明 +* 遵循统一的代码风格 +* 定期进行代码审查 \ No newline at end of file