# 小程序及快应用前端源码

## 1. 📋 项目说明

该项目基于 **uni-app** 开发构建，请使用 [HBuilderX](https://www.dcloud.io/hbuilderx.html) 进行代码开发及构建发布。

## 2. 🛠️ 开发说明

- 源码基于 **Vue2** 版本
- SCSS 采用 **dart-sass** 进行编译输出

## 3. 🔧 开发调试说明

### 3.1 注意事项

- 应用访问等关键参数的配置来源于 `./common/js/config.js`

### 3.2 本地调试

`.local.config.js.example` 是本地调试配置示例。

拷贝 `.local.config.js.example` 为 `.local.config.js` 文件，默认开发调试模式会自动加载该文件

---

## 4. 📦 发布说明

### 4.1 小程序发布

#### 4.1.1 基本操作步骤（通用版/定制化版）

##### 4.1.1.1 【前置准备】
1. 在项目根目录打开终端安装依赖：
   ```bash
   npm install
   ```
   *已有依赖可跳过此步骤*

##### 4.1.1.2 【发布构建】
1. 使用 HBuilderX 打开项目（不用改manifest.json的web，只有H5要改 ）
2. 选择菜单栏「发行」 → 「小程序-微信」→ 「发行」，等待构建完成
   ⚠️ **注意**：底部控制台弹出"请在微信小程序开发者工具中点击上传"后再执行下一步
3. 构建完成后，**自动执行**补丁脚本（拷贝 site.js / config 文件 + 生成 ZIP 包），无需手动操作
4. 找到项目根目录 `/unpackage/dist/build` 下生成的 mp-weixin 压缩包
   💡 **示例**：`mp-weixin-2026-05-11-3bff91e.zip`
   *压缩包文件名末尾为 Git 提交 ID*
   *同时该目录下会生成未压缩的 `mp-weixin` 目录*

##### 4.1.1.3 【验证与重命名】
1. 打开未压缩的 `mp-weixin` 目录，找到 `site.js` 文件，将文件内的 `uniacid` 值改为当前客户编号（如：2812）并保存
2. 打开微信开发者工具，导入「mp-weixin」目录，点击「编译」，在开发者工具控制台验证有无报错，以及能否返回对应客户的业务数据
3. 确保无误后将生成的 mp-weixin 压缩包重命名
   - **定制化版**格式：`定制化-客户编号-域名-mp-weixin-当前日期-Git提交ID.zip`
   - **通用版**无需重命名
   
   💡 **示例**：`custom-2812-xcx.aigc-quickapp.com-mp-weixin-2026-05-11-3bff91e.zip`
   
   🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符

##### 4.1.1.4 【交付与最终发布】🔍
1. 将重命名后的文件发送给技术人员
   *📌通用版直接将生成的 mp-weixin 压缩包发送给技术人员*
2. **技术人员操作流程**：
   - 解压压缩包
   - 确认 `site.js` 中的 `uniacid` 为客户编号
   - 用微信开发者工具导入解压后的代码目录
   - 编译验证无误后，上传发布
##### 4.1.1.5 【本地设置】
      ![](readme_files/1.jpg) 
##### 
---

### 4.2 快应用发布

#### 4.2.1 基本操作（通用版/定制化版）

##### 4.2.1.1 【发布构建】
1. 使用 HBuilderX 打开项目
2. 打开项目根目录的 `manifest.json` 文件，切换至可视化配置界面：
   1. 依次点击「Web 配置」→「运行的基础配置」
   2. 根据情况查看是否修改路径中/hwappx/？？？？/的客户编号
    📌 **通用版**保留原有 `/hwappx/common/`
   📌 **测试版**保留原有 `/hwappx/test/`
   💡 **个性化定制示例**：`/hwappx/2811/`，其中 2811 为定制化版客户编号

3. 选择菜单栏「发行」 → 「自定义发行」 →（「H5-xcx.aigc-quickapp.com」查看.local.config.js中站点的网址前缀，站点的网址前缀是什么就选自定义发行中相同的格式）
 例如：网址是5g.aigc-quickapp.com，自定义发行就选H5-5g.aigc-quickapp.com
      网址是dev.aigc-quickapp.com，自定义发行就选H5-xcx.aigc-quickapp.com
4. 修改以下配置：
   1. **网站标题**：快应用
   2. **网站域名**：当前客户域名（示例：xcx.aigc-quickapp.com或者5g.aigc-quickapp.com）
   3. 确认后点击「发行」等待构建完成

   ⚠️ **注意**：底部控制台弹出“项目 lucky_shop 导出Web成功，路径为：D:\项目文件\项目根目录\unpackage\dist\build\web”后再执行下一步
   💡 **示例**：`项目 lucky_shop 导出Web成功，路径为：D:\0.项目源码\lucky_shop\unpackage\dist\build\web`
5. 按控制台提示的路径找到 `web` 目录，将该目录下所有文件手动打包成一个 `.zip` 压缩包
   *仅打包文件，不包含外层 web 目录*

##### 4.2.1.2 【重命名】
1. 按版本类型规范重命名压缩包：
   - **通用版**：`hwappx-common-域名-时间.zip`
     💡 **示例**：`hwappx-common-xcx.aigc-quickapp.com-2026-01-24.zip`
   
   - **定制化版**：`客户名称-定制化---hwappx-客户编号-域名-时间.zip`
     💡 **示例**：`POCT检测分析平台-定制化---hwappx-2811-xcx.aigc-quickapp.com-2026-01-24.zip`

   🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符

##### 4.2.1.3 【交付与最终发布】🔍

1. 将重命名后的压缩包发送给运维人员
2. **运维人员操作流程**：
   1. 解压压缩包
   2. 打开快应用开发者工具，导入解压后的代码目录
   3. 验证代码无报错后，执行上传发布操作
##### 4.2.1.3  【测试流程】
H5：打开自己的浏览器输入网址(https://5g.aigc-quickapp.com/hwappx/common/?uniacid=75)改站点
    如果是test就把hwappx/common/改为hwappx/test/----------改站点
	
---

## 5. 📝 构建与版本信息

### 5.1 自动注入机制

生产构建时，`vue.config.js` 中的 `VersionInjectPlugin` 会自动执行以下操作：

| 操作 | 适用平台 | 说明 |
|------|---------|------|
| `__app_version` 全局变量注入 | 所有平台 | 构建产物的 `vendor.js`（小程序）或 `index.html`（H5）中自动内联版本数据 |
| 构建版本信息查看 | 所有平台 | 首页右下角连击 5 次弹出模态框显示 `commitId` 和 `buildTime` |

版本数据包含：
- **commitId**：当前构建的 Git 短提交 ID
- **buildTime**：构建时间

> **开发模式**：HMR 热更新时自动跳过重复注入，不影响开发体验。

### 5.2 可用的 npm 脚本命令

| 命令 | 说明 |
|------|------|
| `npm run mp-weixin` | 拷贝 site.js + config 文件 + 创建 ZIP 压缩包（用于手动触发） |

> 生产构建时，ZIP 打包由构建插件自动触发，通常无需手动执行此命令。

### 5.3 构建后处理功能（mp-weixin.patch.js）

- 复制 `project.config.json` 和 `project.private.config.json` 到构建目录
- 复制 `site.js` 到构建目录
- 创建 ZIP 压缩包（文件名包含 Git 提交 ID）
- 自动打开 ZIP 文件所在目录

---

## 6. 🔄 版本历史

### 6.1 v1.5.1

- `VersionInjectPlugin`：webpack emit 钩子自动注入 `__app_version` 到所有平台产物
- 首页右下角连击 5 次显示构建版本信息（commitId + buildTime）
- `mp-weixin.patch.js` 精简为仅文件拷贝和 ZIP 打包
- 修复 `openWxWorkServiceChat` 方法中 fail 回调语法错误
- ZIP 文件名末尾使用 Git 提交 ID 替换时间戳
- 构建脚本幂等性修复，支持多次运行不产生重复注入

### 6.2 v1.3
- 修复微信小程序构建脚本，支持复制 `project.config.json` 和 `project.private.config.json` 文件
- 增强构建脚本功能，添加命令行参数支持
- 在 `package.json` 中添加相关 npm 脚本命令
- 优化脚本执行逻辑，提高可靠性和灵活性