init

2026-02-07 16:11:40 +08:00
parent 7998e702a1
commit 71314c5b12
63 changed files with 33553 additions and 0 deletions
--- a/docs/核心组件文档.md
+++ b/docs/核心组件文档.md
@@ -0,0 +1,748 @@
+# 核心组件文档
+
+## 1. 认证组件 (Auth)
+
+### 功能描述
+用户认证和权限管理组件，负责登录状态检查、用户信息存储和token管理。
+
+### 入参
+```javascript
+// 无直接入参，通过方法调用
+```
+
+### 出参
+```javascript
+// 用户信息对象
+{
+  isLogin: boolean,           // 是否已登录
+  token: string,             // 访问令牌
+  refreshToken: string,      // 刷新令牌
+  expiresIn: number,         // 过期时间
+  tokenType: string,         // 令牌类型
+  userId: string,            // 用户ID
+  username: string,          // 用户名
+  avatar: string,            // 头像
+  loginTime: number,         // 登录时间
+  isDriver: boolean,         // 是否为司机
+  driverInfo: object         // 司机信息
+}
+```
+
+### 调用方式
+```javascript
+import { 
+  saveUserInfo, 
+  getUserInfo, 
+  getToken, 
+  isLoggedIn, 
+  isDriver, 
+  getDriverInfo, 
+  clearUserInfo, 
+  logout, 
+  checkLoginAndRedirect 
+} from '../utils/auth.js'
+
+// 保存用户信息
+saveUserInfo(userInfo)
+
+// 获取用户信息
+const userInfo = getUserInfo()
+
+// 检查登录状态
+if (isLoggedIn()) {
+  // 已登录逻辑
+}
+
+// 检查是否为司机
+if (isDriver()) {
+  const driverInfo = getDriverInfo()
+}
+
+// 退出登录
+logout()
+
+// 检查登录并重定向
+checkLoginAndRedirect()
+```
+
+### 数据模型
+```javascript
+// 用户信息模型
+interface UserInfo {
+  isLogin: boolean
+  token: string
+  refreshToken: string
+  expiresIn: number
+  tokenType: string
+  userId: string
+  username: string
+  avatar: string
+  loginTime: number
+  isDriver?: boolean
+  driverInfo?: DriverInfo
+}
+
+// 司机信息模型
+interface DriverInfo {
+  id: string
+  driverId: string
+  name: string
+  phone: string
+  status: string
+  data: {
+    id: string
+    name: string
+    phone: string
+  }
+}
+```
+
+---
+
+## 2. 请求组件 (Request)
+
+### 功能描述
+统一的HTTP请求组件，处理API调用、token注入、错误处理和用户凭证过期检测。
+
+### 入参
+```javascript
+// GET请求
+get(url: string, params?: object, headers?: object)
+
+// POST请求
+post(url: string, data?: object, headers?: object)
+
+// PUT请求
+put(url: string, data?: object, headers?: object)
+
+// DELETE请求
+del(url: string, data?: object, headers?: object)
+
+// 文件上传
+uploadFile(url: string, filePath: string, name?: string, formData?: object, headers?: object)
+```
+
+### 出参
+```javascript
+// 标准响应格式
+{
+  statusCode: number,        // HTTP状态码
+  data: object,             // 响应数据
+  header: object,           // 响应头
+  errMsg: string           // 错误信息
+}
+```
+
+### 调用方式
+```javascript
+import { get, post, put, del, uploadFile } from '../utils/request.js'
+
+// GET请求
+const response = await get('/api/users', { page: 1, size: 10 })
+
+// POST请求
+const result = await post('/api/login', { username: 'user', password: 'pass' })
+
+// 文件上传
+const uploadResult = await uploadFile('/api/upload', filePath, 'file', { type: 'image' })
+```
+
+### 数据模型
+```javascript
+// 请求配置模型
+interface RequestOptions {
+  url: string
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE'
+  data?: object
+  headers?: object
+  timeout?: number
+}
+
+// 响应模型
+interface ApiResponse {
+  statusCode: number
+  data: {
+    code?: number
+    msg?: string
+    [key: string]: any
+  }
+  header: object
+  errMsg?: string
+}
+
+// 错误模型
+interface ApiError {
+  errMsg: string
+  statusCode?: number
+}
+```
+
+---
+
+## 3. 位置组件 (Location)
+
+### 功能描述
+地理位置获取和权限管理组件，提供位置获取、权限检查和用户引导功能。
+
+### 入参
+```javascript
+// 无直接入参，通过方法调用
+```
+
+### 出参
+```javascript
+// 位置信息对象
+{
+  latitude: number,          // 纬度
+  longitude: number,         // 经度
+  accuracy: number,         // 精度
+  altitude: number,          // 海拔
+  speed: number,             // 速度
+  timestamp: number          // 时间戳
+}
+```
+
+### 调用方式
+```javascript
+import { 
+  getCurrentLocation, 
+  checkLocationPermission, 
+  requestLocationPermission, 
+  getLocationWithPermission 
+} from '../utils/location.js'
+
+// 获取当前位置
+const location = await getCurrentLocation()
+
+// 检查定位权限
+const hasPermission = await checkLocationPermission()
+
+// 申请定位权限
+const granted = await requestLocationPermission()
+
+// 获取位置并处理权限
+const location = await getLocationWithPermission()
+```
+
+### 数据模型
+```javascript
+// 位置信息模型
+interface LocationInfo {
+  latitude: number
+  longitude: number
+  accuracy: number
+  altitude: number
+  speed: number
+  timestamp: number
+}
+
+// 权限状态
+type PermissionStatus = true | false | undefined
+```
+
+---
+
+## 4. 字典组件 (Dict)
+
+### 功能描述
+数据字典管理组件，提供统一的字典数据获取和管理功能。
+
+### 入参
+```javascript
+// 获取单个字典数据
+getDictData(type: string)
+
+// 批量获取字典数据
+getMultipleDictData(types: string[])
+
+// 根据值获取文本
+getDictText(dictData: DictItem[], value: string)
+
+// 根据文本获取值
+getDictValue(dictData: DictItem[], text: string)
+```
+
+### 出参
+```javascript
+// 字典数据项
+{
+  text: string,             // 显示文本
+  value: string              // 值
+}
+```
+
+### 调用方式
+```javascript
+import { getDictData, DICT_TYPES, getDictText, getDictValue } from '../utils/dictUtils.js'
+
+// 获取尾挂类型字典
+const carBackTypes = await getDictData(DICT_TYPES.CAR_BACK_TYPE)
+
+// 批量获取字典
+const dicts = await getMultipleDictData([
+  DICT_TYPES.CAR_TYPE,
+  DICT_TYPES.COMPANY_TYPE
+])
+
+// 根据值获取文本
+const text = getDictText(carBackTypes, 'flatbed')
+
+// 根据文本获取值
+const value = getDictValue(carBackTypes, '平板')
+```
+
+### 数据模型
+```javascript
+// 字典项模型
+interface DictItem {
+  text: string
+  value: string
+}
+
+// 字典类型常量
+const DICT_TYPES = {
+  CAR_TYPE: 'car_type',
+  COMPANY_TYPE: 'company_type',
+  CAR_STATUS: 'car_status',
+  DRIVER_STATUS: 'driver_status',
+  GUFEI_ORDER_STATUS: 'gufei_order_status',
+  CAR_BACK_TYPE: 'car_back_type',
+  CAR_PACKAGE_TYPE: 'car_package_type',
+  GPS_STATUS: 'gps_status'
+}
+```
+
+---
+
+## 5. 加密组件 (Crypto)
+
+### 功能描述
+数据加密组件，提供AES加密功能用于密码加密。
+
+### 入参
+```javascript
+aesEncrypt(word: string, keyWord?: string)
+```
+
+### 出参
+```javascript
+// 加密后的字符串
+string
+```
+
+### 调用方式
+```javascript
+import { aesEncrypt } from '../utils/crypto.js'
+
+// 加密密码
+const encryptedPassword = aesEncrypt('123456', 'pigxpigxpigxpigx')
+```
+
+### 数据模型
+```javascript
+// 加密参数模型
+interface EncryptOptions {
+  word: string              // 要加密的内容
+  keyWord?: string          // 加密密钥，默认: 'pigxpigxpigxpigx'
+}
+```
+
+---
+
+## 6. API组件 (API)
+
+### 功能描述
+API接口管理组件，统一管理所有后端接口调用。
+
+### 入参
+```javascript
+// 认证API
+authAPI.login(data: LoginData)
+
+// 订单API
+orderAPI.getWaitOrders(driverId: string)
+orderAPI.createOrder(data: OrderData)
+orderAPI.getTodayTotal()
+
+// 车辆API
+carAPI.getCarPage(params: CarPageParams)
+
+// 司机API
+driverAPI.getDriverInfo(userId: string)
+
+// 文件API
+fileAPI.upload(filePath: string, formData?: object)
+
+// 字典API
+dictAPI.getDictData(type: string)
+```
+
+### 出参
+```javascript
+// 标准API响应
+{
+  statusCode: number,
+  data: object
+}
+```
+
+### 调用方式
+```javascript
+import { authAPI, orderAPI, carAPI, driverAPI, fileAPI, dictAPI } from '../api/index.js'
+
+// 登录
+const loginResult = await authAPI.login({ username: 'user', password: 'pass' })
+
+// 获取待完成车次
+const orders = await orderAPI.getWaitOrders('driver123')
+
+// 创建订单
+const result = await orderAPI.createOrder(orderData)
+
+// 获取今日统计
+const stats = await orderAPI.getTodayTotal()
+
+// 获取车辆数据
+const cars = await carAPI.getCarPage({ current: 1, size: 10 })
+
+// 获取司机信息
+const driver = await driverAPI.getDriverInfo('user123')
+
+// 上传文件
+const uploadResult = await fileAPI.upload(filePath)
+
+// 获取字典数据
+const dictData = await dictAPI.getDictData('car_type')
+```
+
+### 数据模型
+```javascript
+// 登录数据模型
+interface LoginData {
+  username: string
+  password: string
+}
+
+// 订单数据模型
+interface OrderData {
+  driverId: string
+  carId: string
+  totalWeight: number
+  companyId: string
+  carBackType: string
+  gufeiType: string
+  gufeiPackage: string
+  localImg: string
+  longitude: string
+  latitude: string
+}
+
+// 车辆分页参数模型
+interface CarPageParams {
+  current: number
+  size: number
+  driverId: string
+  companyId: string
+}
+
+// 今日统计模型
+interface TodayStats {
+  count: number              // 收货客户数
+  planWeight: number         // 预计重量
+  realWeight: number         // 实际重量
+}
+```
+
+---
+
+## 7. 车辆表单组件 (CarForm)
+
+### 功能描述
+车辆信息录入表单组件，支持照片上传、位置获取和订单提交。
+
+### 入参
+```javascript
+// 组件Props
+{
+  visible: boolean,          // 是否显示
+  carData: CarData,          // 车辆数据
+  companyId: string          // 供应商ID
+}
+```
+
+### 出参
+```javascript
+// 事件
+{
+  submit: (formData) => void,    // 表单提交事件
+  refresh: () => void            // 刷新事件
+}
+```
+
+### 调用方式
+```vue
+<template>
+  <CarForm 
+    v-model:visible="showCarForm" 
+    :car-data="selectedCarData" 
+    :company-id="scannedCompanyId"
+    @submit="handleCarFormSubmit" 
+    @refresh="handleCarFormRefresh" 
+  />
+</template>
+
+<script>
+import CarForm from '../components/CarForm.vue'
+
+export default {
+  components: {
+    CarForm
+  },
+  data() {
+    return {
+      showCarForm: false,
+      selectedCarData: {
+        carNum: '',
+        carType: '',
+        id: '',
+        carWeight: '',
+        carVolume: ''
+      },
+      scannedCompanyId: ''
+    }
+  },
+  methods: {
+    handleCarFormSubmit(formData) {
+      console.log('表单提交:', formData)
+    },
+    handleCarFormRefresh() {
+      console.log('刷新数据')
+    }
+  }
+}
+</script>
+```
+
+### 数据模型
+```javascript
+// 车辆数据模型
+interface CarData {
+  carNum: string             // 车牌号
+  carType: string            // 车辆类型
+  id: string                 // 车辆ID
+  carWeight: string          // 车辆重量
+  carVolume: string          // 车辆容积
+}
+
+// 表单数据模型
+interface FormData {
+  carNum: string             // 车牌号
+  carBackType: string        // 尾挂类型
+  photos: string[]           // 照片URL数组
+}
+```
+
+---
+
+## 8. 使用示例
+
+### 完整登录流程
+```javascript
+import { authAPI, driverAPI } from '../api/index.js'
+import { saveUserInfo } from '../utils/auth.js'
+import { aesEncrypt } from '../utils/crypto.js'
+
+// 登录处理
+const handleLogin = async (username, password) => {
+  try {
+    // 加密密码
+    const encryptedPassword = aesEncrypt(password)
+    
+    // 调用登录API
+    const response = await authAPI.login({
+      username,
+      password: encryptedPassword
+    })
+    
+    if (response.statusCode === 200) {
+      // 保存用户信息
+      const userInfo = {
+        isLogin: true,
+        token: response.data.access_token,
+        userId: response.data.userId,
+        username: username
+      }
+      
+      saveUserInfo(userInfo)
+      
+      // 检查是否为司机
+      const driverResponse = await driverAPI.getDriverInfo(userInfo.userId)
+      if (driverResponse.statusCode === 200) {
+        userInfo.isDriver = true
+        userInfo.driverInfo = driverResponse.data
+        saveUserInfo(userInfo)
+      }
+      
+      return true
+    }
+  } catch (error) {
+    console.error('登录失败:', error)
+    return false
+  }
+}
+```
+
+### 完整订单创建流程
+```javascript
+import { orderAPI, fileAPI } from '../api/index.js'
+import { getLocationWithPermission } from '../utils/location.js'
+import { getUserInfo } from '../utils/auth.js'
+
+// 创建订单
+const createOrder = async (formData, carData, companyId) => {
+  try {
+    // 获取位置
+    const location = await getLocationWithPermission()
+    
+    // 获取司机信息
+    const userInfo = getUserInfo()
+    const driverInfo = userInfo.driverInfo.data
+    
+    // 构建订单数据
+    const orderData = {
+      driverId: driverInfo.id,
+      carId: carData.id,
+      totalWeight: 1,
+      companyId: companyId,
+      carBackType: formData.carBackType,
+      gufeiType: '',
+      gufeiPackage: '',
+      localImg: formData.photos.join(','),
+      longitude: location.longitude.toString(),
+      latitude: location.latitude.toString()
+    }
+    
+    // 提交订单
+    const response = await orderAPI.createOrder(orderData)
+    
+    if (response.statusCode === 200) {
+      console.log('订单创建成功')
+      return true
+    }
+  } catch (error) {
+    console.error('订单创建失败:', error)
+    return false
+  }
+}
+```
+
+---
+
+## 9. 错误处理
+
+### 统一错误处理
+```javascript
+// 用户凭证过期处理
+if (response.data && response.data.code === 1 && response.data.msg === "用户凭证已过期") {
+  wx.showModal({
+    title: '登录过期',
+    content: '您的登录已过期，请重新登录',
+    showCancel: false,
+    confirmText: '重新登录',
+    success: () => {
+      // 清除本地存储
+      wx.removeStorageSync('userInfo')
+      wx.removeStorageSync('isLogin')
+      wx.removeStorageSync('token')
+      
+      // 跳转登录页
+      wx.navigateTo({
+        url: '/pages/login/index'
+      })
+    }
+  })
+}
+```
+
+### 网络错误处理
+```javascript
+try {
+  const response = await api.getData()
+  // 处理成功响应
+} catch (error) {
+  if (error.errMsg.includes('timeout')) {
+    wx.showToast({
+      title: '请求超时',
+      icon: 'none'
+    })
+  } else {
+    wx.showToast({
+      title: '网络错误',
+      icon: 'none'
+    })
+  }
+}
+```
+
+---
+
+## 10. 调试功能
+
+### 开发环境配置
+```javascript
+// 调试环境下的默认账号密码
+if (process.env.NODE_ENV === 'development') {
+  loginForm.username = 'driver'
+  loginForm.password = '123456'
+  console.log('调试环境：已设置默认账号密码')
+}
+```
+
+### 日志输出
+```javascript
+// 请求日志
+console.log(`API请求成功: ${method} ${url}`, response)
+
+// 调试信息
+console.log('开始获取待完成车次数据，司机ID:', driverId)
+console.log('今日统计API响应:', response)
+console.log('获取位置成功:', location)
+```
+
+---
+
+## 11. 性能优化
+
+### 请求优化
+- 统一请求超时设置
+- 自动token注入
+- 请求去重处理
+
+### 缓存策略
+- 用户信息本地存储
+- 字典数据缓存
+- 位置信息缓存
+
+### 错误恢复
+- 自动重试机制
+- 降级处理
+- 用户引导
+
+---
+
+## 12. 安全考虑
+
+### 数据加密
+- 密码AES加密
+- 敏感信息保护
+- 传输安全
+
+### 权限控制
+- 登录状态检查
+- 角色权限验证
+- 接口访问控制
+
+### 数据验证
+- 输入参数验证
+- 响应数据校验
+- 异常数据处理