From 6edbebde62a87b10fbe8a7676c45b1016896e76a Mon Sep 17 00:00:00 2001 From: sugar1569 Date: Tue, 27 Jan 2026 10:19:02 +0800 Subject: [PATCH] =?UTF-8?q?=E3=80=90=E5=89=8D=E7=AB=AF=E6=96=87=E4=BB=B6?= =?UTF-8?q?=E3=80=91docs:=20=E6=B7=BB=E5=8A=A0=E6=A8=A1=E6=9D=BF=E7=9B=AE?= =?UTF-8?q?=E5=BD=95=E5=92=8Cuni-app=E9=A1=B9=E7=9B=AE=E7=9A=84README?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加了template目录的README.md文件，详细说明前端项目的目录结构、技术栈和开发规范。同时添加了uni-app项目的README.md文件，包含项目简介、目录结构、技术栈、开发环境和部署说明等内容。这些文档将为开发者提供项目概览和开发指导。 --- template/README.md | 190 +++++++++++++++++++++++ template/uni-app/README.md | 303 +++++++++++++++++++++++++++++++++++++ 2 files changed, 493 insertions(+) create mode 100644 template/README.md create mode 100644 template/uni-app/README.md diff --git a/template/README.md b/template/README.md new file mode 100644 index 000000000..8567fb5fa --- /dev/null +++ b/template/README.md @@ -0,0 +1,190 @@ +# Template 目录说明文档 + +## 目录结构 + +`template` 目录包含 CRMEB 系统的前端项目代码，主要分为两个子项目： + +``` +template/ +├── admin/ # 管理端前端项目（Vue.js + Element UI） +└── uni-app/ # 移动端前端项目（UniApp） +``` + +## 项目说明 + +### 1. 管理端前端项目 (admin/) + +管理端前端项目基于 Vue.js + Element UI 开发，用于后台管理系统的操作界面。 + +#### 主要目录结构 + +``` +admin/ +├── public/ # 静态资源目录 +├── src/ # 源代码目录 +│ ├── api/ # API 接口定义 +│ ├── assets/ # 静态资源文件 +│ ├── components/ # 通用组件 +│ ├── config/ # 配置文件 +│ ├── directive/ # 自定义指令 +│ ├── filters/ # 过滤器 +│ ├── layout/ # 布局组件 +│ ├── libs/ # 工具库 +│ ├── pages/ # 页面组件 +│ ├── router/ # 路由配置 +│ ├── store/ # 状态管理 +│ ├── styles/ # 样式文件 +│ ├── utils/ # 工具函数 +│ ├── App.vue # 根组件 +│ └── main.js # 入口文件 +├── .env.dev # 开发环境配置 +├── .env.production # 生产环境配置 +├── package.json # 项目依赖 +├── vue.config.js # Vue 配置 +└── README.md # 项目说明 +``` + +#### 技术栈 +- Vue.js 2.x +- Element UI +- Vue Router +- Vuex +- Axios +- ECharts + +#### 开发命令 +- 安装依赖：`npm install` +- 开发环境运行：`npm run dev` +- 生产环境构建：`npm run build` +- 代码检查：`npm run lint` + +### 2. 移动端前端项目 (uni-app/) + +移动端前端项目基于 UniApp 开发，支持多端发布（微信小程序、H5、App 等）。 + +#### 主要目录结构 + +``` +uni-app/ +├── api/ # API 接口定义 +├── components/ # 通用组件 +├── config/ # 配置文件 +├── libs/ # 工具库 +├── mixins/ # 混合器 +├── pages/ # 页面组件 +├── static/ # 静态资源 +├── App.vue # 根组件 +├── main.js # 入口文件 +├── manifest.json # 应用配置 +├── pages.json # 页面配置 +└── package.json # 项目依赖 +``` + +#### 技术栈 +- UniApp +- Vue.js 2.x +- uView UI (UniApp 组件库) +- Vuex +- Axios + +#### 开发命令 +- 安装依赖：`npm install` +- 开发环境运行：使用 HBuilderX 运行到对应平台 +- 生产环境构建：使用 HBuilderX 发行到对应平台 + +## 前端与后端交互 + +前端项目通过 API 接口与后端进行交互，主要配置如下： + +### 管理端 API 配置 +- 开发环境：`admin/.env.dev` 文件中的 `VUE_APP_API_URL` +- 生产环境：`admin/.env.production` 文件中的 `VUE_APP_API_URL` + +### 移动端 API 配置 +- 配置文件：`uni-app/config/api.js` +- API 基础路径：`baseURL` 变量 + +## 部署说明 + +### 管理端部署 +1. 执行构建命令：`npm run build` +2. 将 `admin/dist` 目录下的文件部署到 Web 服务器 +3. 配置 Nginx 或 Apache 服务器，指向构建后的静态文件 + +### 移动端部署 +1. 使用 HBuilderX 打开 `uni-app` 目录 +2. 根据需要发行到对应平台： + - 微信小程序：发行 -> 小程序-微信 + - H5：发行 -> H5 + - App：发行 -> 原生 App-云打包 + +## 开发规范 + +### 代码风格 +- 遵循 Vue 官方风格指南 +- 使用 ESLint 进行代码检查 +- 组件名使用 PascalCase +- 方法和变量名使用 camelCase + +### 命名规范 +- 文件和目录名使用 kebab-case +- 组件名使用 PascalCase +- 常量使用全大写，单词间用下划线分隔 + +### 目录使用 +- `api/`：按模块组织 API 接口 +- `components/`：存放可复用组件 +- `pages/`：存放页面组件 +- `utils/`：存放工具函数 +- `styles/`：存放全局样式 + +## 注意事项 + +1. **API 接口**：前端项目需要与后端 API 接口保持一致，如有接口变更，需要同步修改前端代码。 + +2. **环境配置**：不同环境下的 API 地址需要在对应配置文件中修改。 + +3. **依赖管理**：使用 npm 管理项目依赖，确保依赖版本的一致性。 + +4. **构建优化**：生产环境构建时会自动进行代码压缩和优化。 + +5. **跨域处理**：开发环境下使用 Vue CLI 的代理配置处理跨域问题，生产环境需要在服务器端配置 CORS。 + +6. **性能优化**： + - 合理使用组件懒加载 + - 优化图片资源 + - 减少不必要的 API 请求 + - 使用缓存减少重复数据获取 + +## 常见问题 + +### 1. 开发环境 API 调用失败 +- 检查 `.env.dev` 文件中的 API 地址是否正确 +- 检查后端服务是否正常运行 +- 检查网络连接是否正常 + +### 2. 构建后页面空白 +- 检查路由配置是否正确 +- 检查是否有未捕获的错误 +- 检查静态资源路径是否正确 + +### 3. 移动端适配问题 +- 使用 Flex 布局进行响应式设计 +- 针对不同设备尺寸进行适配 +- 测试不同设备的显示效果 + +## 联系与支持 + +- 官方文档：https://doc.crmeb.com +- 技术社区：https://www.crmeb.com/ask +- 官方 QQ 群：请参考官方网站 + +## 版本信息 + +- CRMEB 版本：5.6.4 +- 管理端前端：Vue 2.x + Element UI +- 移动端前端：UniApp + +--- + +**说明**：本目录为前端项目代码，后端代码位于项目根目录的 `crmeb/` 目录中。 \ No newline at end of file diff --git a/template/uni-app/README.md b/template/uni-app/README.md new file mode 100644 index 000000000..859ad8623 --- /dev/null +++ b/template/uni-app/README.md @@ -0,0 +1,303 @@ +# CRMEB UniApp 项目说明文档 + +## 项目简介 + +CRMEB UniApp 项目是基于 UniApp 框架开发的移动端应用，支持多端发布，包括微信小程序、H5、App（Android/iOS）等平台。该项目是 CRMEB 开源商城系统的移动端前端部分，提供了完整的商城购物、用户管理、活动参与等功能。 + +## 目录结构 + +``` +uni-app/ +├── api/ # API 接口定义 +│ ├── activity.js # 活动相关接口 +│ ├── admin.js # 管理员相关接口 +│ ├── api.js # 通用 API 配置 +│ ├── kefu.js # 客服相关接口 +│ ├── lottery.js # 抽奖相关接口 +│ ├── order.js # 订单相关接口 +│ ├── points_mall.js # 积分商城接口 +│ ├── public.js # 公共接口 +│ ├── store.js # 店铺相关接口 +│ └── user.js # 用户相关接口 +├── components/ # 通用组件 +│ ├── Loading/ # 加载组件 +│ ├── cartList/ # 购物车列表组件 +│ ├── goodList/ # 商品列表组件 +│ ├── guide/ # 引导组件 +│ ├── home/ # 首页组件 +│ ├── homeList/ # 首页列表组件 +│ ├── kefuIcon/ # 客服图标组件 +│ ├── payment/ # 支付组件 +│ ├── skeleton/ # 骨架屏组件 +│ ├── swipers/ # 轮播组件 +│ ├── zb-code/ # 二维码组件 +│ ├── Authorize.vue # 授权组件 +│ ├── BaseMoney.vue # 金额基础组件 +│ ├── BaseTag.vue # 标签基础组件 +│ ├── emptyPage.vue # 空页面组件 +│ ├── menuIcon.vue # 菜单图标组件 +│ ├── numberScroll.vue # 数字滚动组件 +│ ├── pageLoading.vue # 页面加载组件 +│ └── tabNav.vue # 标签导航组件 +├── config/ # 配置文件 +│ ├── app.js # 应用配置 +│ ├── cache.js # 缓存配置 +│ └── socket.js # Socket 配置 +├── libs/ # 工具库 +│ ├── chat.js # 聊天工具 +│ ├── login.js # 登录工具 +│ ├── new_chat.js # 新聊天工具 +│ ├── order.js # 订单工具 +│ ├── permission.js # 权限工具 +│ ├── routine.js # 小程序工具 +│ ├── uniApi.js # UniApp API 封装 +│ └── wechat.js # 微信工具 +├── mixins/ # 混合器 +│ ├── SendVerifyCode.js # 发送验证码 +│ ├── color.js # 颜色处理 +│ ├── debounce.js # 防抖处理 +│ ├── sharePoster.js # 分享海报 +│ └── skuSelect.js # SKU 选择 +├── pages/ # 页面组件 +│ ├── activity/ # 活动页面 +│ ├── admin/ # 管理员页面 +│ ├── annex/ # 附件页面 +│ ├── goods/ # 商品页面 +│ ├── goods_details/ # 商品详情页面 +│ ├── guide/ # 引导页面 +│ ├── index/ # 首页 +│ ├── points_mall/ # 积分商城页面 +│ ├── user/ # 用户中心页面 +│ └── users/ # 用户相关页面 +├── static/ # 静态资源 +├── App.vue # 根组件 +├── androidPrivacy.json # Android 隐私配置 +├── main.js # 入口文件 +├── manifest.json # 应用配置 +├── pages.json # 页面配置 +└── package.json # 项目依赖 +``` + +## 技术栈 + +- **框架**: UniApp +- **前端框架**: Vue.js 2.x +- **UI 组件库**: uView UI +- **状态管理**: Vuex +- **网络请求**: Axios +- **小程序开发**: 微信小程序 +- **App 开发**: 原生 App (Android/iOS) +- **H5 开发**: 移动端网页 + +## 开发环境 + +### 开发工具 +- **HBuilderX**: 推荐使用 HBuilderX 3.0+ 版本进行开发 +- **Node.js**: v12.0+（用于安装依赖） +- **微信开发者工具**: 用于微信小程序开发和调试 + +### 依赖管理 +- 安装依赖：`npm install` + +## 开发命令 + +### HBuilderX 操作 +1. **运行到微信小程序**: + - 点击 HBuilderX 工具栏的 "运行" -> "运行到小程序模拟器" -> "微信开发者工具" + +2. **运行到 H5**: + - 点击 HBuilderX 工具栏的 "运行" -> "运行到浏览器" -> 选择浏览器 + +3. **运行到 App**: + - 点击 HBuilderX 工具栏的 "运行" -> "运行到手机或模拟器" -> 选择设备 + +### 命令行操作 +- **安装依赖**: `npm install` +- **构建 H5**: 使用 HBuilderX 发行功能 +- **构建小程序**: 使用 HBuilderX 发行功能 +- **构建 App**: 使用 HBuilderX 发行功能 + +## 配置说明 + +### 应用配置 +- **manifest.json**: 应用基本配置，包括应用名称、版本、权限等 +- **pages.json**: 页面配置，包括页面路径、导航栏设置、底部标签栏等 +- **config/app.js**: 应用业务配置，包括 API 地址、应用常量等 + +### API 配置 +- **api/api.js**: API 基础配置，包括 baseURL、请求拦截器、响应拦截器等 +- **api/**: 按模块组织的 API 接口定义 + +### 环境配置 +- 开发环境 API 地址: 在 `config/app.js` 中修改 `baseURL` +- 生产环境 API 地址: 在发布前修改 `config/app.js` 中的 `baseURL` + +## 功能模块 + +### 核心功能 +- **首页**: 轮播图、商品分类、推荐商品、活动入口等 +- **商品**: 商品列表、商品详情、SKU 选择、加入购物车等 +- **购物车**: 购物车管理、商品结算、优惠券选择等 +- **订单**: 订单创建、订单列表、订单详情、订单支付等 +- **用户中心**: 个人信息、地址管理、收藏管理、优惠券管理等 +- **活动**: 秒杀、拼团、砍价、积分商城等 +- **客服**: 在线客服、消息中心等 + +### 特色功能 +- **多端适配**: 一套代码适配多个平台 +- **响应式设计**: 适配不同屏幕尺寸的设备 +- **性能优化**: 图片懒加载、组件按需加载等 +- **用户体验**: 流畅的动画效果、友好的交互界面 +- **安全保障**: 数据加密传输、权限控制等 + +## 部署说明 + +### 微信小程序部署 +1. 在 HBuilderX 中点击 "发行" -> "小程序-微信" +2. 填写小程序名称、AppID、版本号等信息 +3. 点击 "发行" 按钮，等待构建完成 +4. 在微信开发者工具中导入构建后的代码 +5. 提交代码审核，审核通过后发布 + +### H5 部署 +1. 在 HBuilderX 中点击 "发行" -> "H5" +2. 填写网站标题、域名等信息 +3. 点击 "发行" 按钮，等待构建完成 +4. 将构建后的文件部署到 Web 服务器 +5. 配置服务器域名，确保能正常访问 + +### App 部署 +1. 在 HBuilderX 中点击 "发行" -> "原生 App-云打包" +2. 填写应用名称、版本号、包名等信息 +3. 选择 Android/iOS 平台 +4. 点击 "打包" 按钮，等待打包完成 +5. 下载打包后的安装包，进行测试和发布 + +## 开发规范 + +### 代码风格 +- 遵循 Vue 官方风格指南 +- 组件名使用 PascalCase +- 方法和变量名使用 camelCase +- 文件名使用 kebab-case + +### 命名规范 +- 组件名: PascalCase（如：GoodsList.vue） +- 方法名: camelCase（如：getGoodsList()） +- 变量名: camelCase（如：goodsList） +- 常量名: 全大写，单词间用下划线分隔（如：API_BASE_URL） +- 文件名: kebab-case（如：goods-detail.vue） + +### 目录使用 +- **api/**: 按模块组织 API 接口 +- **components/**: 存放可复用组件 +- **pages/**: 存放页面组件 +- **libs/**: 存放工具库 +- **mixins/**: 存放混合器 +- **static/**: 存放静态资源 + +### 开发建议 +1. **组件化开发**: 将常用功能封装为组件，提高代码复用率 +2. **模块化开发**: 按功能模块组织代码，提高代码可维护性 +3. **代码注释**: 为关键代码添加注释，提高代码可读性 +4. **错误处理**: 合理处理异步操作的错误，提高应用稳定性 +5. **性能优化**: 避免不必要的渲染和计算，提高应用性能 + +## 注意事项 + +### 平台差异 +- **微信小程序**: 部分 API 只在微信小程序中可用，需要做平台判断 +- **H5**: 部分原生能力在 H5 中不可用，需要做降级处理 +- **App**: 权限申请、原生功能调用等需要适配不同平台 + +### API 调用 +- 所有 API 调用需要通过 `api` 目录下的模块进行 +- API 地址需要根据环境进行配置 +- API 调用需要处理 loading 状态和错误状态 + +### 性能优化 +- **图片优化**: 使用适当尺寸的图片，避免过大的图片 +- **代码分包**: 合理使用代码分包，减少主包体积 +- **按需加载**: 组件和页面按需加载，减少初始加载时间 +- **缓存策略**: 合理使用缓存，减少重复请求 + +### 安全问题 +- **数据加密**: 敏感数据需要加密传输 +- **权限控制**: 合理控制用户权限，避免越权操作 +- **输入验证**: 对用户输入进行验证，避免恶意输入 + +## 常见问题 + +### 1. 微信小程序登录失败 +- 检查微信开发者工具是否登录 +- 检查 `libs/login.js` 中的登录逻辑 +- 检查 `api/user.js` 中的登录接口 + +### 2. API 接口调用失败 +- 检查 `config/app.js` 中的 API 地址是否正确 +- 检查网络连接是否正常 +- 检查后端服务是否正常运行 + +### 3. 页面白屏或加载失败 +- 检查页面路径是否正确 +- 检查页面组件是否有语法错误 +- 检查 API 调用是否有错误 + +### 4. 样式适配问题 +- 使用 Flex 布局进行响应式设计 +- 使用 `rpx` 单位进行尺寸适配 +- 针对不同平台做样式兼容处理 + +### 5. 打包失败 +- 检查是否有语法错误 +- 检查是否有未定义的变量或方法 +- 检查文件大小是否超过平台限制 + +## 联系与支持 + +- **官方文档**: https://doc.crmeb.com +- **技术社区**: https://www.crmeb.com/ask +- **GitHub**: https://github.com/crmeb/CRMEB +- **Gitee**: https://gitee.com/ZhongBangKeJi/CRMEB + +## 版本信息 + +- **CRMEB 版本**: 5.6.4 +- **UniApp 版本**: 3.0+ +- **uView UI 版本**: 2.0+ +- **Vue 版本**: 2.6+ + +## 更新日志 + +### v5.6.4 +- 优化首页加载速度 +- 修复商品详情页 SKU 选择问题 +- 完善订单支付流程 +- 优化用户体验 + +### v5.6.3 +- 添加积分商城功能 +- 优化活动参与流程 +- 修复已知 bug + +### v5.6.2 +- 完善客服系统 +- 优化购物车体验 +- 修复页面跳转问题 + +## 贡献指南 + +欢迎对 CRMEB UniApp 项目进行贡献，包括但不限于： + +1. **Bug 修复**: 提交 Issue 或 Pull Request +2. **功能增强**: 提交 Feature Request 或 Pull Request +3. **文档完善**: 改进项目文档 +4. **代码优化**: 优化代码结构和性能 + +## 许可证 + +本项目采用 Apache-2.0 许可证开源，详见 LICENSE 文件。 + +--- + +**说明**：本项目是 CRMEB 开源商城系统的移动端前端部分，需要与后端 API 配合使用。后端代码位于项目根目录的 `crmeb/` 目录中。 \ No newline at end of file