更新项目文档，明确小程序独立架构和技术选型

2025-09-17 23:01:14 +08:00
parent aa1e08baa5
commit eeedbebb9c
20 changed files with 2020 additions and 116 deletions
--- a/mini_program/README.md
+++ b/mini_program/README.md
@@ -2,7 +2,7 @@

 ## 📱 项目概述

-活牛采购智能数字化系统小程序矩阵基于uni-app框架开发，支持微信小程序、支付宝小程序、H5等多端发布。系统包含四个独立的小程序应用，分别服务于不同角色用户，实现活牛采购全流程的移动端操作。
+活牛采购智能数字化系统小程序矩阵包含四个完全独立的小程序应用，分别服务于不同角色用户，实现活牛采购全流程的移动端操作。每个小程序都是独立开发、独立部署的，不共享公共资源、API、类型定义或样式。

 **核心特性：**
 - 🎯 **多角色支持**：客户端、供应商、司机、内部员工四大角色
@@ -11,55 +11,80 @@
 - 📍 **位置服务**：GPS定位和轨迹跟踪
 - 📸 **媒体支持**：图片、视频上传和播放
 - 💼 **离线缓存**：关键数据本地缓存
+- 🔐 **安全机制**：数据加密与权限控制
+- 📊 **数据可视化**：业务数据图表展示

 ## 🛠 技术栈

-| 类别 | 技术选型 | 版本 | 说明 |
+每个小程序可以根据自身需求选择适合的技术栈：
+
+| 类别 | 可选技术 | 版本 | 说明 |
 |------|----------|------|------|
-| **跨端框架** | uni-app | ^3.0.0 | 跨平台开发框架 |
-| **前端框架** | Vue 3 | ^3.3.0 | 响应式前端框架 |
-| **开发语言** | TypeScript | ^5.0.0 | 类型安全开发 |
-| **状态管理** | Pinia | ^2.1.0 | 状态管理库 |
-| **UI组件库** | uni-ui | ^1.4.0 | uni-app官方组件库 |
-| **HTTP客户端** | uni.request | 内置 | 网络请求封装 |
-| **地图服务** | 腾讯地图 | latest | 位置和导航服务 |
-| **构建工具** | Vite | ^4.4.0 | 快速构建工具 |
-| **代码规范** | ESLint + Prettier | latest | 代码质量保证 |
+| **跨端框架** | uni-app / 原生小程序 | 最新版 | 根据需求选择 |
+| **前端框架** | Vue 3 / 原生 | 最新版 | 根据需求选择 |
+| **开发语言** | TypeScript / JavaScript | 最新版 | 根据需求选择 |
+| **状态管理** | Pinia / Vuex / 原生 | 最新版 | 根据需求选择 |
+| **UI组件库** | 各平台组件库 | 最新版 | 根据需求选择 |
+| **HTTP客户端** | 平台API | 内置 | 网络请求 |
+| **地图服务** | 腾讯/高德/百度地图 | 最新版 | 位置和导航服务 |
+| **构建工具** | 平台工具 | 最新版 | 构建发布 |

 ## 📂 项目结构

 ```
 mini_program/
-├── client-mp/                  # 客户端小程序
+├── client-mp/                  # 客户端小程序（采购人）
 │   ├── src/
 │   │   ├── pages/             # 页面文件
-│   │   │   ├── index/         # 首页
-│   │   │   ├── order/         # 订单相关
-│   │   │   ├── profile/       # 个人中心
-│   │   │   └── auth/          # 认证相关
 │   │   ├── components/        # 组件
+│   │   ├── stores/            # 状态管理
+│   │   ├── utils/             # 工具函数
+│   │   ├── api/               # API接口
+│   │   ├── static/            # 静态资源
+│   │   ├── App.vue            # 应用入口
+│   │   └── main.ts            # 主文件
+│   ├── manifest.json          # 应用配置
+│   ├── pages.json            # 页面配置
+│   └── package.json          # 依赖配置
+├── supplier-mp/               # 供应商小程序（完全独立）
+│   ├── src/
+│   │   ├── pages/            # 页面文件
+│   │   ├── components/       # 组件
 │   │   ├── stores/           # 状态管理
 │   │   ├── utils/            # 工具函数
 │   │   ├── api/              # API接口
 │   │   ├── static/           # 静态资源
 │   │   ├── App.vue           # 应用入口
 │   │   └── main.ts           # 主文件
-│   ├── manifest.json         # 应用配置
-│   ├── pages.json           # 页面配置
-│   └── package.json         # 依赖配置
-├── supplier-mp/               # 供应商小程序
 │   └── ...
-├── driver-mp/                # 司机小程序
+├── driver-mp/                # 司机小程序（完全独立）
+│   ├── src/
+│   │   ├── pages/            # 页面文件
+│   │   ├── components/       # 组件
+│   │   ├── stores/           # 状态管理
+│   │   ├── utils/            # 工具函数
+│   │   ├── api/              # API接口
+│   │   ├── static/           # 静态资源
+│   │   ├── App.vue           # 应用入口
+│   │   └── main.ts           # 主文件
 │   └── ...
-├── staff-mp/                 # 内部员工小程序
+├── staff-mp/                 # 内部员工小程序（完全独立）
+│   ├── src/
+│   │   ├── pages/            # 页面文件
+│   │   ├── components/       # 组件
+│   │   ├── stores/           # 状态管理
+│   │   ├── utils/            # 工具函数
+│   │   ├── api/              # API接口
+│   │   ├── static/           # 静态资源
+│   │   ├── App.vue           # 应用入口
+│   │   └── main.ts           # 主文件
 │   └── ...
-├── common/                   # 公共资源
-│   ├── components/          # 公共组件
-│   ├── utils/              # 公共工具
-│   ├── api/                # 公共API
-│   ├── types/              # 类型定义
-│   └── styles/             # 公共样式
 ├── docs/                     # 开发文档
+│   ├── 需求文档-第1部分.md    # 概述和用户角色
+│   ├── 需求文档-第2部分.md    # 功能需求
+│   ├── 需求文档-第3部分.md    # 界面设计和交互流程
+│   ├── 需求文档-第4部分.md    # 技术实现和测试计划
+│   └── ...
 └── README.md                # 项目文档
 ```

@@ -67,38 +92,40 @@ mini_program/

 ### 环境要求
 - Node.js >= 16.0.0
- HBuilderX >= 3.8.0 或 VS Code + uni-app插件
- 微信开发者工具
- 支付宝小程序开发工具（可选）
+- 各小程序开发工具（微信开发者工具、支付宝小程序开发工具等）

 ### 安装依赖
 ```bash
+# 每个小程序独立安装依赖
 cd mini_program/client-mp
 npm install

-# 安装其他小程序依赖
-cd ../supplier-mp && npm install
-cd ../driver-mp && npm install
-cd ../staff-mp && npm install
+cd ../supplier-mp
+npm install
+
+cd ../driver-mp
+npm install
+
+cd ../staff-mp
+npm install
 ```

 ### 开发模式
 ```bash
-# 客户端小程序
+# 每个小程序独立开发
 cd client-mp
-npm run dev:mp-weixin    # 微信小程序
-npm run dev:mp-alipay    # 支付宝小程序
-npm run dev:h5           # H5
+npm run dev    # 或使用对应平台的开发命令

 # 其他小程序类似
 ```

 ### 构建发布
 ```bash
-# 生产环境构建
-npm run build:mp-weixin
-npm run build:mp-alipay
-npm run build:h5
+# 每个小程序独立构建
+cd client-mp
+npm run build  # 或使用对应平台的构建命令
+
+# 其他小程序类似
 ```

 ## 📱 小程序功能模块
@@ -106,38 +133,130 @@ npm run build:h5
 ### 1. 客户端小程序 (Client MP)
 **目标用户**：采购人、采购企业
 **核心功能**：
- 📋 **订单管理**：创建采购订单、查看订单状态
- 🚛 **运输跟踪**：实时查看运输进度和位置
- ✅ **验收确认**：到货验收、质量确认
- 💰 **支付结算**：查看结算单、在线支付
- 📊 **数据统计**：采购数据分析和报表
+- 📋 **订单管理**
+  - 创建采购订单
+  - 选择供应商
+  - 设置牛只品种、数量、重量要求
+  - 设置单价和预付款比例
+  - 查看订单状态和流转记录
+- 🚛 **运输跟踪**
+  - 实时查看运输车辆位置
+  - 显示运输轨迹和预计到达时间
+  - 查看历史轨迹回放
+  - 查看牛只运输状态实时数据
+  - 接收异常状态预警通知
+- ✅ **验收管理**
+  - 验收牛只数量和重量
+  - 记录验收结果（合格/不合格）
+  - 上传验收照片和视频
+  - 记录异常情况（死亡、受伤等）
+  - 提交异常处理申请
+- 💰 **支付结算**
+  - 查看系统自动生成的结算单
+  - 核对结算金额明细
+  - 支持微信支付、支付宝支付
+  - 支持银行转账凭证上传
+  - 查看支付记录和凭证
+- 📊 **数据统计**
+  - 展示采购总量、总金额等关键指标
+  - 展示采购趋势图表
+  - 按品种、供应商等维度统计
+  - 牛只质量合格率统计
+  - 供应商质量评分对比

 ### 2. 供应商小程序 (Supplier MP)
 **目标用户**：牲畜供应商
 **核心功能**：
- 📦 **订单接收**：接收和确认采购订单
- 🐄 **牲畜管理**：牲畜信息录入和管理
- 📋 **检疫证明**：上传检疫合格证明
- 🚚 **装车管理**：装车过程记录和监控
- 📸 **现场拍照**：装车现场照片和视频
+- 📦 **订单管理**
+  - 接收新订单通知
+  - 查看订单详情
+  - 确认接单或拒绝
+  - 设置预计发货时间
+  - 按状态分类查看订单
+- 🐄 **牛只管理**
+  - 录入牛只基本信息（品种、数量、重量等）
+  - 上传牛只照片
+  - 批量导入牛只信息
+  - 上传《动物检疫合格证明》
+  - 上传疫苗接种记录
+- 🚚 **装车管理**
+  - 确认空水空槽时间
+  - 上传装车前准备证明
+  - 联系司机确认装车时间
+  - 记录装车过程
+  - 上传装车视频和照片
+- 💼 **结算管理**
+  - 查看结算单详情
+  - 核对结算金额
+  - 确认结算单
+  - 查看收款记录
+  - 开具发票管理
+- 📋 **资质管理**
+  - 营业执照信息维护
+  - 资质证书上传和管理
+  - 联系人信息维护

 ### 3. 司机小程序 (Driver MP)
 **目标用户**：运输司机
 **核心功能**：
- 🚛 **车辆登记**：车辆信息和证件管理
- 📍 **位置上报**：实时GPS位置上报
- 📱 **状态更新**：运输状态实时更新
- 🎥 **视频上报**：运输过程视频记录
- 📄 **单据管理**：运输单据电子化管理
+- 🚛 **任务管理**
+  - 接收运输任务通知
+  - 查看任务详情
+  - 确认接受任务
+  - 按状态分类展示任务
+  - 历史任务查询
+- 🚗 **车辆信息**
+  - 车辆基本信息维护
+  - 驾驶证和行驶证上传
+  - 车辆照片上传
+  - 上传空车过磅视频
+  - 上传车辆消毒证明
+- 📍 **位置上报**
+  - 自动定时上报GPS位置（每10分钟）
+  - 手动上报当前位置
+  - 设置位置共享权限
+  - 查看导航路线
+  - 查看上报历史
+- 📱 **状态上报**
+  - 定时上报牛只状态
+  - 上传运输过程视频
+  - 记录休息和加油等事件
+  - 上报交通事故、车辆故障等异常
+  - 上报牛只异常状况
+- 📄 **交付确认**
+  - 确认到达目的地
+  - 上传到达照片
+  - 记录到达时间
+  - 电子交接单生成
+  - 采购方签字确认

 ### 4. 内部员工小程序 (Staff MP)
 **目标用户**：企业内部员工
 **核心功能**：
- 👥 **用户管理**：用户信息查看和管理
- 📊 **数据监控**：业务数据实时监控
- ⚠️ **异常处理**：异常情况处理和跟进
- 📋 **审核管理**：订单和流程审核
- 📈 **统计报表**：业务统计和分析
+- 👥 **订单监控**
+  - 审核新创建的订单
+  - 查看订单详情
+  - 修改订单信息
+  - 确认或驳回订单
+  - 全流程订单状态监控
+- 🚚 **运输监控**
+  - 查看所有运输中车辆位置
+  - 监控运输异常情况
+  - 远程指导处理问题
+  - 查看实时上传的视频
+  - 调阅历史视频记录
+- 📊 **数据管理**
+  - 牛只品种管理
+  - 价格区间设置
+  - 区域信息管理
+  - 管理采购人账号
+  - 管理供应商账号
+- 📈 **统计分析**
+  - 订单量和交易额统计
+  - 供应商绩效分析
+  - 运输效率分析
+  - 异常事件统计
+  - 改进措施跟踪

 ## 🔧 开发规范

@@ -146,26 +265,37 @@ npm run build:h5
 - **组件名**：PascalCase（如 `OrderCard.vue`）
 - **变量名**：camelCase（如 `orderInfo`）
 - **常量名**：UPPER_SNAKE_CASE（如 `API_BASE_URL`）
+- **接口名**：以I开头，PascalCase（如 `IOrderData`）
+- **类型名**：PascalCase（如 `OrderStatus`）

 ### 目录规范
+每个小程序独立维护自己的目录结构：
 - `pages/`：页面文件，按功能模块分组
 - `components/`：组件文件，按类型分组
 - `stores/`：状态管理，按业务模块分组
 - `api/`：接口定义，按业务模块分组
 - `utils/`：工具函数，按功能分组
+- `static/`：静态资源，按类型分组
+- `types/`：类型定义，按业务模块分组

 ### 代码规范
+每个小程序可以根据自身需求制定代码规范，但建议：
 - 使用TypeScript进行类型约束
- 使用Composition API编写组件
+- 使用Composition API编写组件（如使用Vue）
 - 遵循ESLint和Prettier规范
 - 组件props必须定义类型
 - 使用defineEmits定义事件
+- 使用状态管理库管理全局状态
+- 使用async/await处理异步操作
+- 使用try/catch处理异常

-## 🌐 API接口
+## 🌐 API接口示例

-### 接口配置
+每个小程序独立实现自己的API接口层：
+
+### 接口配置示例
 ```typescript
-// 环境配置
+// 环境配置示例（每个小程序独立配置）
 const config = {
  development: {
    baseURL: 'http://localhost:3001/api',
@@ -178,9 +308,9 @@ const config = {
 }
 ```

-### 请求封装
+### 请求封装示例
 ```typescript
-// 统一请求封装
+// 请求封装示例（每个小程序独立实现）
 interface RequestOptions {
  url: string
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
@@ -200,11 +330,13 @@ const request = (options: RequestOptions) => {
 }
 ```

-## 📍 位置服务
+## 📍 位置服务示例

-### GPS定位
+每个小程序独立实现位置服务功能：
+
+### GPS定位示例
 ```typescript
-// 获取当前位置
+// 获取当前位置示例
 const getCurrentLocation = () => {
  return new Promise((resolve, reject) => {
    uni.getLocation({
@@ -215,51 +347,40 @@ const getCurrentLocation = () => {
  })
 }

-// 实时位置上报
+// 实时位置上报示例
 const startLocationTracking = () => {
-  setInterval(async () => {
-    try {
-      const location = await getCurrentLocation()
-      await reportLocation(location)
-    } catch (error) {
-      console.error('位置上报失败:', error)
-    }
-  }, 10000) // 每10秒上报一次
-}
-```
-
-## 📸 媒体处理
-
-### 图片上传
-```typescript
-// 选择并上传图片
-const uploadImage = () => {
-  uni.chooseImage({
-    count: 9,
+  // 后台定位权限检查
+  uni.getSetting({
    success: (res) => {
-      res.tempFilePaths.forEach(filePath => {
-        uni.uploadFile({
-          url: `${config.baseURL}/upload`,
-          filePath,
-          name: 'file',
-          header: {
-            'Authorization': `Bearer ${getToken()}`
+      if (!res.authSetting['scope.userLocation']) {
+        uni.authorize({
+          scope: 'scope.userLocation',
+          success: () => {
+            startBackgroundLocationTracking();
          },
-          success: (uploadRes) => {
-            console.log('上传成功:', uploadRes)
+          fail: () => {
+            uni.showModal({
+              title: '提示',
+              content: '需要位置权限才能进行运输跟踪',
+              showCancel: false
+            });
          }
-        })
-      })
+        });
+      } else {
+        startBackgroundLocationTracking();
+      }
    }
-  })
+  });
 }
 ```

-## 💾 数据缓存
+## 💾 数据缓存示例

-### 本地存储
+每个小程序独立实现数据缓存功能：
+
+### 本地存储示例
 ```typescript
-// 缓存管理
+// 缓存管理示例
 class CacheManager {
  static set(key: string, value: any, expire?: number) {
    const data = {
@@ -288,11 +409,13 @@ class CacheManager {
 }
 ```

-## 🔐 权限管理
+## 🔐 权限管理示例

-### 登录状态管理
+每个小程序独立实现权限管理功能：
+
+### 登录状态管理示例
 ```typescript
-// 登录状态检查
+// 登录状态检查示例
 const checkAuth = () => {
  const token = CacheManager.get('token')
  if (!token) {
@@ -304,7 +427,7 @@ const checkAuth = () => {
  return true
 }

-// 页面访问权限
+// 页面访问权限示例
 const checkPagePermission = (userRole: string, requiredRole: string[]) => {
  return requiredRole.includes(userRole)
 }
@@ -312,6 +435,8 @@ const checkPagePermission = (userRole: string, requiredRole: string[]) => {

 ## 🧪 测试策略

+每个小程序独立进行测试：
+
 ### 单元测试
 - 工具函数测试
 - 组件功能测试
@@ -326,6 +451,8 @@ const checkPagePermission = (userRole: string, requiredRole: string[]) => {

 ## 📦 发布部署

+每个小程序独立发布部署：
+
 ### 微信小程序发布
 1. 使用微信开发者工具打开项目
 2. 点击「上传」按钮上传代码
@@ -338,13 +465,44 @@ const checkPagePermission = (userRole: string, requiredRole: string[]) => {
 3. 登录支付宝开放平台提交审核
 4. 审核通过后发布上线

+## 📚 相关文档
+
+### 需求文档
+- [需求文档-第1部分](./需求文档-第1部分.md) - 概述和用户角色
+- [需求文档-第2部分](./需求文档-第2部分.md) - 功能需求
+- [需求文档-第3部分](./需求文档-第3部分.md) - 界面设计和交互流程
+- [需求文档-第4部分](./需求文档-第4部分.md) - 技术实现和测试计划
+
+### 开发指南
+- [uni-app官方文档](https://uniapp.dcloud.io/)
+- [Vue 3官方文档](https://v3.cn.vuejs.org/)
+- [TypeScript官方文档](https://www.typescriptlang.org/)
+- [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
+- [支付宝小程序开发文档](https://opendocs.alipay.com/mini/developer)
+
 ## 🤝 贡献指南

-1. **Fork** 仓库
-2. **创建**特性分支 (`git checkout -b feature/AmazingFeature`)
-3. **提交**更改 (`git commit -m 'Add some AmazingFeature'`)
-4. **推送**到分支 (`git push origin feature/AmazingFeature`)
-5. **开启** Pull Request
+每个小程序独立管理代码仓库和贡献流程。
+
+## 📅 开发计划
+
+### 第一阶段（2025年10月）
+- 完成四个小程序的基础框架搭建
+- 实现各小程序的用户认证功能
+- 开发各小程序的核心功能模块
+
+### 第二阶段（2025年11月）
+- 完成四个小程序的全部功能开发
+- 实现各小程序的实时数据同步
+- 完成各小程序的媒体上传功能
+- 开发各小程序的数据统计模块
+
+### 第三阶段（2025年12月）
+- 各小程序独立测试
+- 系统联调和集成测试
+- 性能优化和兼容性测试
+- 用户体验优化
+- 准备上线发布

 ---