Merge pull request 'docs: 更新readme文档结构和内容' (#2) from dev/1.0 into main

Reviewed-on: #2
2026-01-24 09:41:36 +00:00
parent b31197a8b4 09e410df00
commit 2a0935b581
1 changed files with 133 additions and 99 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,112 +1,146 @@
 # 小程序及快应用前端源码
 ## 1. 📋 项目说明
-## 项目说明
+该项目基于 **uni-app** 开发构建，请使用 [HBuilderX](https://www.dcloud.io/hbuilderx.html) 进行代码开发及构建发布。
-该项目基于 uniapp 开发构建，请使用(HBuilderX)[https://www.dcloud.io/hbuilderx.html] 进行代码开发及构建发布。
+## 2. 🛠️ 开发说明
-## 开发说明
+- 源码基于 **Vue2** 版本
 - SCSS 采用 **dart-sass** 进行编译输出
- 源码基于Vue2版本，scss采用dart-sass进行编译输出。
+## 3. 🔧 开发调试说明
 ### 3.1 注意事项
-## 开发调试说明
+- 应用访问等关键参数的配置来源于 `./common/js/config.js`
-### 注意点
+### 3.2 本地调试
-应用访问等关键参数的配置来源于 `./common/js/config.js`
+`.local.config.js.example` 是本地调试配置示例。
-
+
-
+拷贝 `.local.config.js.example` 为 `.local.config.js` 文件，默认开发调试模式会自动加载该文件
-
+
-
+---
-
+
-## 发布说明
+## 4. 📦 发布说明
-
+
-### 小程序发布
+### 4.1 小程序发布
-
+
-
+#### 4.1.1 基本操作步骤（通用版/定制化版）
-
+
-#### 基本操作步骤：（通用版/定制化版）
+##### 4.1.1.1 【前置准备】
-
+1. 在项目根目录打开终端安装依赖：
-#### 【前置准备】
+   ```bash
-1. 在项目根目录打开终端安装依赖“npm install”（已有依赖可跳过此步骤）。
+   npm install
-#### 【发布构建】
+   ```
-2. 使用HBuilderX打开项目；
+   *已有依赖可跳过此步骤*
-3. 选择菜单栏「发行」 → 「小程序-微信」→ 「发行」，等待构建完成。（⚠️注：底部控制台弹出"请在微信小程序开发者工具中点击上传"后再执行下一步）；
+
-4. 打开资源管理器→项目根目录，右键选择「在终端中打开」，执行"npm run mp-weixin"命令并回车；
+##### 4.1.1.2 【发布构建】
-
+1. 使用 HBuilderX 打开项目
-5. 找到项目根目录 /unpackage/dist/build 下生成的 mp-weixin 压缩包
+2. 选择菜单栏「发行」 → 「小程序-微信」→ 「发行」，等待构建完成
-
+   ⚠️ **注意**：底部控制台弹出"请在微信小程序开发者工具中点击上传"后再执行下一步
-💡例如：mp-weixin-2026-01-23-1769152056146.zip;同时该目录下会生成未压缩的 mp-weixin 目录。
+3. 打开资源管理器→项目根目录，右键选择「在终端中打开」，执行命令：
-
+   ```bash
-#### 【验证与重命名】
+   npm run mp-weixin
-6. 打开该目录下同时生成未压缩的 mp-weixin 目录，找到site.js文件，将文件内的uniacid值改为当前客户编号（如：2812）并保存；
+   ```
-7. 打开微信开发者工具，导入「mp-weixin」目录，点击「编译」，在开发者工具控制台验证有无报错，以及能否返回对应客户的业务数据；
+4. 找到项目根目录 `/unpackage/dist/build` 下生成的 mp-weixin 压缩包
-
+   💡 **示例**：`mp-weixin-2026-01-23-1769152056146.zip`
-8. 确保无误后将生成的mp-weixin的压缩包重命名，格式为：定制化-客户编号-域名-mp-weixin-当前日期-生成编号.zip。
+   *同时该目录下会生成未压缩的 `mp-weixin` 目录*
-***（📌通用版无需重命名）***
+
-
+##### 4.1.1.3 【验证与重命名】
-💡例如：custom-2812-xcx.aigc-quickapp.com-mp-weixin-2026-01-22-1769152056146.zip
+1. 打开未压缩的 `mp-weixin` 目录，找到 `site.js` 文件，将文件内的 `uniacid` 值改为当前客户编号（如：2812）并保存
-
+2. 打开微信开发者工具，导入「mp-weixin」目录，点击「编译」，在开发者工具控制台验证有无报错，以及能否返回对应客户的业务数据
-🚫压缩包命名禁止包含 / \ : * ? " < > | 等特殊字符。
+3. 确保无误后将生成的 mp-weixin 压缩包重命名
- 
+   - **定制化版**格式：`定制化-客户编号-域名-mp-weixin-当前日期-生成编号.zip`
-
+   - **通用版**无需重命名
-#### 【交付与最终发布】🔍🔍
+   
-9. 将重命名后的文件发送给技术人员； ***（📌通用版直接将生成的 mp-weixin 压缩包直接发送给技术人员）***
+   💡 **示例**：`custom-2812-xcx.aigc-quickapp.com-mp-weixin-2026-01-22-1769152056146.zip`
-
+   
-10. 技术人员操作：解压压缩包 → 确认site.js中的uniacid为客户编号 → 用微信开发者工具导入解压后的代码目录 → 编译验证无误后 → 上传发布。
+   🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符
-
+
-
+##### 4.1.1.4 【交付与最终发布】🔍
-
+1. 将重命名后的文件发送给技术人员
-
+   *📌通用版直接将生成的 mp-weixin 压缩包发送给技术人员*
-
+2. **技术人员操作流程**：
-
+    - 解压压缩包
-### 快应用发布
+    - 确认 `site.js` 中的 `uniacid` 为客户编号
-
+    - 用微信开发者工具导入解压后的代码目录
-
+    - 编译验证无误后，上传发布
-#### 基本操作（通用版/定制化版）
+
-
+---
-
+
-
+### 4.2 快应用发布
-#### 【发布构建】
+
-1. 使用HBuilderX打开项目；
+#### 4.2.1 基本操作（通用版/定制化版）
-
+
-2. 打开项目根目录的manifest.json文件，切换至可视化配置界面：依次点击「Web 配置」→「运行的基础配置」，修改路径中的客户编号；***（📌通用版保留原有/hwappx/common/）***
+##### 4.2.1.1 【发布构建】
-
+1. 使用 HBuilderX 打开项目
-💡例如：/hwappx/2811/，其中2811为定制化版客户编号；
+2. 打开项目根目录的 `manifest.json` 文件，切换至可视化配置界面：
-
+   1. 依次点击「Web 配置」→「运行的基础配置」
-3. 选择菜单栏「发行」 → 「自定义发行」 →「H5-xcx.aigc-quickapp.com」，先修改以下配置：
+   2. 修改路径中的客户编号
-网站标题：快应用
+   3. 📌 **通用版**保留原有 `/hwappx/common/`
-网站域名：当前客户域名（示例：xcx.aigc-quickapp.com）
+   
-确认后点击「发行」等待构建完成。
+   💡 **示例**：`/hwappx/2811/`，其中 2811 为定制化版客户编号
-
+
-⚠️注：底部控制台弹出“项目 lucky_shop 导出Web成功，路径为：D:\项目文件\项目根目录\unpackage\dist\build\web”后再执行下一步
+3. 选择菜单栏「发行」 → 「自定义发行」 →「H5-xcx.aigc-quickapp.com」，修改以下配置：
-
+   1. **网站标题**：快应用
-💡例如：项目 lucky_shop 导出Web成功，路径为：D:\0.项目源码\lucky_shop\unpackage\dist\build\web
+   2. **网站域名**：当前客户域名（示例：xcx.aigc-quickapp.com）
-
+   3. 确认后点击「发行」等待构建完成
-4. 按控制台提示的路径找到web目录，将该目录下所有文件手动打包成一个.zip压缩包（仅打包文件，不包含外层web目录）；
+
-
+   ⚠️ **注意**：底部控制台弹出“项目 lucky_shop 导出Web成功，路径为：D:\项目文件\项目根目录\unpackage\dist\build\web”后再执行下一步
-#### 【重命名】
+   💡 **示例**：`项目 lucky_shop 导出Web成功，路径为：D:\0.项目源码\lucky_shop\unpackage\dist\build\web`
-5. 按版本类型规范重命名压缩包：
+
-
+4. 按控制台提示的路径找到 `web` 目录，将该目录下所有文件手动打包成一个 `.zip` 压缩包
-📌通用版：hwappx-common-域名-时间.zip  
+   *仅打包文件，不包含外层 web 目录*
-例如： hwappx-common-xcx.aigc-quickapp.com-2026-01-24.zip
+
-
+##### 4.2.1.2 【重命名】
-📌定制化：客户名称-定制化---hwappx-客户编号-域名-时间.zip  
+1. 按版本类型规范重命名压缩包：
- 例如：POCT检测分析平台-定制化---hwappx-2811-xcx.aigc-quickapp.com-2026-01-24.zip
+   - **通用版**：`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`
-6. 将重命名后的压缩包发送给运维人员；
+
-
+   🚫 **禁止**：压缩包命名禁止包含 `/ \ : * ? " < > |` 等特殊字符
-7. 运维人员操作：
+
-
+##### 4.2.1.3 【交付与最终发布】🔍
-① 解压压缩包；
+1. 将重命名后的压缩包发送给运维人员
-
+2. **运维人员操作流程**：
-② 打开快应用开发者工具，导入解压后的代码目录；
+   1. 解压压缩包
-
+   2. 打开快应用开发者工具，导入解压后的代码目录
-③ 验证代码无报错后，执行上传发布操作。
+   3. 验证代码无报错后，执行上传发布操作
 ---
 ## 5. 📝 构建脚本说明
 ### 5.1 可用的 npm 脚本命令
 | 命令 | 说明 |
 |------|------|
 | `npm run mp-weixin` | 默认构建（production模式，包含ZIP文件） |
 | `npm run mp-weixin:patch` | 只打补丁（production模式，不创建ZIP文件） |
 | `npm run mp-weixin:dev` | 开发模式构建（development模式，包含ZIP文件） |
 | `npm run mp-weixin:dev:patch` | 只打补丁（development模式，不创建ZIP文件） |
 ### 5.2 构建脚本功能
 - 复制 `project.config.json` 和 `project.private.config.json` 文件到构建目录
 - 复制 `site.js` 文件到构建目录
 - 在 `vendor.js` 文件开头追加 `import site from "../site.js";` 语句
 - 支持创建构建结果的 ZIP 压缩包
 - 自动打开 ZIP 文件所在目录
 ---
 ## 6. 🔄 版本历史
 ### 6.1 v1.3
 - 修复微信小程序构建脚本，支持复制 `project.config.json` 和 `project.private.config.json` 文件
 - 增强构建脚本功能，添加命令行参数支持
 - 在 `package.json` 中添加相关 npm 脚本命令
 - 优化脚本执行逻辑，提高可靠性和灵活性