niumalll/mini_program/README.md

# Mini Program - 活牛采购智能数字化系统小程序矩阵

## 📱 项目概述

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

**核心特性：**
- 🎯 **多角色支持**：客户端、供应商、司机、内部员工四大角色
- 🔄 **跨平台兼容**：支持微信、支付宝、H5等多平台
- 📡 **实时同步**：WebSocket实时数据更新
- 📍 **位置服务**：GPS定位和轨迹跟踪
- 📸 **媒体支持**：图片、视频上传和播放
- 💼 **离线缓存**：关键数据本地缓存
- 🔐 **安全机制**：数据加密与权限控制
- 📊 **数据可视化**：业务数据图表展示

## 🛠 技术栈

每个小程序可以根据自身需求选择适合的技术栈：

| 类别 | 可选技术 | 版本 | 说明 |
|------|----------|------|------|
| **跨端框架** | uni-app / 原生小程序 | 最新版 | 根据需求选择 |
| **前端框架** | Vue 3 / 原生 | 最新版 | 根据需求选择 |
| **开发语言** | TypeScript / JavaScript | 最新版 | 根据需求选择 |
| **状态管理** | Pinia / Vuex / 原生 | 最新版 | 根据需求选择 |
| **UI组件库** | 各平台组件库 | 最新版 | 根据需求选择 |
| **HTTP客户端** | 平台API | 内置 | 网络请求 |
| **地图服务** | 腾讯/高德/百度地图 | 最新版 | 位置和导航服务 |
| **构建工具** | 平台工具 | 最新版 | 构建发布 |

## 📂 项目结构

```
mini_program/
├── client-mp/                  # 客户端小程序（采购人）
│   ├── src/
│   │   ├── pages/             # 页面文件
│   │   ├── 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           # 主文件
│   └── ...
├── driver-mp/                # 司机小程序（完全独立）
│   ├── src/
│   │   ├── pages/            # 页面文件
│   │   ├── components/       # 组件
│   │   ├── stores/           # 状态管理
│   │   ├── utils/            # 工具函数
│   │   ├── api/              # API接口
│   │   ├── static/           # 静态资源
│   │   ├── App.vue           # 应用入口
│   │   └── main.ts           # 主文件
│   └── ...
├── staff-mp/                 # 内部员工小程序（完全独立）
│   ├── src/
│   │   ├── pages/            # 页面文件
│   │   ├── components/       # 组件
│   │   ├── stores/           # 状态管理
│   │   ├── utils/            # 工具函数
│   │   ├── api/              # API接口
│   │   ├── static/           # 静态资源
│   │   ├── App.vue           # 应用入口
│   │   └── main.ts           # 主文件
│   └── ...
├── docs/                     # 开发文档
│   ├── 需求文档-第1部分.md    # 概述和用户角色
│   ├── 需求文档-第2部分.md    # 功能需求
│   ├── 需求文档-第3部分.md    # 界面设计和交互流程
│   ├── 需求文档-第4部分.md    # 技术实现和测试计划
│   └── ...
└── README.md                # 项目文档
```

## 🚀 快速开始

### 环境要求
- Node.js >= 16.0.0
- 各小程序开发工具（微信开发者工具、支付宝小程序开发工具等）

### 安装依赖
```bash
# 每个小程序独立安装依赖
cd mini_program/client-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    # 或使用对应平台的开发命令

# 其他小程序类似
```

### 构建发布
```bash
# 每个小程序独立构建
cd client-mp
npm run build  # 或使用对应平台的构建命令

# 其他小程序类似
```

## 📱 小程序功能模块

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

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

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

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

## 🔧 开发规范

### 命名规范
- **页面文件**：kebab-case（如 `order-list.vue`）
- **组件名**：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编写组件（如使用Vue）
- 遵循ESLint和Prettier规范
- 组件props必须定义类型
- 使用defineEmits定义事件
- 使用状态管理库管理全局状态
- 使用async/await处理异步操作
- 使用try/catch处理异常

## 🌐 API接口示例

每个小程序独立实现自己的API接口层：

### 接口配置示例
```typescript
// 环境配置示例（每个小程序独立配置）
const config = {
  development: {
    baseURL: 'http://localhost:3001/api',
    wsURL: 'ws://localhost:3001'
  },
  production: {
    baseURL: 'https://api.niumall.com/api',
    wsURL: 'wss://api.niumall.com'
  }
}
```

### 请求封装示例
```typescript
// 请求封装示例（每个小程序独立实现）
interface RequestOptions {
  url: string
  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
  data?: any
  header?: Record<string, string>
}

const request = (options: RequestOptions) => {
  return uni.request({
    ...options,
    header: {
      'Authorization': `Bearer ${getToken()}`,
      'Content-Type': 'application/json',
      ...options.header
    }
  })
}
```

## 📍 位置服务示例

每个小程序独立实现位置服务功能：

### GPS定位示例
```typescript
// 获取当前位置示例
const getCurrentLocation = () => {
  return new Promise((resolve, reject) => {
    uni.getLocation({
      type: 'gcj02',
      success: resolve,
      fail: reject
    })
  })
}

// 实时位置上报示例
const startLocationTracking = () => {
  // 后台定位权限检查
  uni.getSetting({
    success: (res) => {
      if (!res.authSetting['scope.userLocation']) {
        uni.authorize({
          scope: 'scope.userLocation',
          success: () => {
            startBackgroundLocationTracking();
          },
          fail: () => {
            uni.showModal({
              title: '提示',
              content: '需要位置权限才能进行运输跟踪',
              showCancel: false
            });
          }
        });
      } else {
        startBackgroundLocationTracking();
      }
    }
  });
}
```

## 💾 数据缓存示例

每个小程序独立实现数据缓存功能：

### 本地存储示例
```typescript
// 缓存管理示例
class CacheManager {
  static set(key: string, value: any, expire?: number) {
    const data = {
      value,
      expire: expire ? Date.now() + expire : null
    }
    uni.setStorageSync(key, JSON.stringify(data))
  }

  static get(key: string) {
    try {
      const data = JSON.parse(uni.getStorageSync(key))
      if (data.expire && Date.now() > data.expire) {
        this.remove(key)
        return null
      }
      return data.value
    } catch {
      return null
    }
  }

  static remove(key: string) {
    uni.removeStorageSync(key)
  }
}
```

## 🔐 权限管理示例

每个小程序独立实现权限管理功能：

### 登录状态管理示例
```typescript
// 登录状态检查示例
const checkAuth = () => {
  const token = CacheManager.get('token')
  if (!token) {
    uni.redirectTo({
      url: '/pages/auth/login'
    })
    return false
  }
  return true
}

// 页面访问权限示例
const checkPagePermission = (userRole: string, requiredRole: string[]) => {
  return requiredRole.includes(userRole)
}
```

## 🧪 测试策略

每个小程序独立进行测试：

### 单元测试
- 工具函数测试
- 组件功能测试
- API接口测试
- 状态管理测试

### 真机测试
- 多设备兼容性测试
- 网络环境测试
- 性能压力测试
- 用户体验测试

## 📦 发布部署

每个小程序独立发布部署：

### 微信小程序发布
1. 使用微信开发者工具打开项目
2. 点击「上传」按钮上传代码
3. 登录微信公众平台提交审核
4. 审核通过后发布上线

### 支付宝小程序发布
1. 使用支付宝小程序开发工具打开项目
2. 点击「上传」按钮上传代码
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)

## 🤝 贡献指南

每个小程序独立管理代码仓库和贡献流程。

## 📅 开发计划

### 第一阶段（2025年10月）
- 完成四个小程序的基础框架搭建
- 实现各小程序的用户认证功能
- 开发各小程序的核心功能模块

### 第二阶段（2025年11月）
- 完成四个小程序的全部功能开发
- 实现各小程序的实时数据同步
- 完成各小程序的媒体上传功能
- 开发各小程序的数据统计模块

### 第三阶段（2025年12月）
- 各小程序独立测试
- 系统联调和集成测试
- 性能优化和兼容性测试
- 用户体验优化
- 准备上线发布

---

**🎯 让移动办公更便捷，让业务管理更高效！**