template-MP/AGENTS.md

# 项目概述 - 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 包裹
*   错误信息应友好提示用户
*   重要错误会自动上报到企业微信机器人

### 代码质量

*   添加必要的注释说明
*   遵循统一的代码风格
*   定期进行代码审查