# 核心组件文档

## 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加密
- 敏感信息保护
- 传输安全

### 权限控制
- 登录状态检查
- 角色权限验证
- 接口访问控制

### 数据验证
- 输入参数验证
- 响应数据校验
- 异常数据处理