15 KiB
15 KiB
核心组件文档
1. 认证组件 (Auth)
功能描述
用户认证和权限管理组件，负责登录状态检查、用户信息存储和token管理。
入参
// 无直接入参，通过方法调用
出参
// 用户信息对象
{
isLogin: boolean, // 是否已登录
token: string, // 访问令牌
refreshToken: string, // 刷新令牌
expiresIn: number, // 过期时间
tokenType: string, // 令牌类型
userId: string, // 用户ID
username: string, // 用户名
avatar: string, // 头像
loginTime: number, // 登录时间
isDriver: boolean, // 是否为司机
driverInfo: object // 司机信息
}
调用方式
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()
数据模型
// 用户信息模型
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注入、错误处理和用户凭证过期检测。
入参
// 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)
出参
// 标准响应格式
{
statusCode: number, // HTTP状态码
data: object, // 响应数据
header: object, // 响应头
errMsg: string // 错误信息
}
调用方式
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' })
数据模型
// 请求配置模型
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)
功能描述
地理位置获取和权限管理组件，提供位置获取、权限检查和用户引导功能。
入参
// 无直接入参，通过方法调用
出参
// 位置信息对象
{
latitude: number, // 纬度
longitude: number, // 经度
accuracy: number, // 精度
altitude: number, // 海拔
speed: number, // 速度
timestamp: number // 时间戳
}
调用方式
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()
数据模型
// 位置信息模型
interface LocationInfo {
latitude: number
longitude: number
accuracy: number
altitude: number
speed: number
timestamp: number
}
// 权限状态
type PermissionStatus = true | false | undefined
4. 字典组件 (Dict)
功能描述
数据字典管理组件，提供统一的字典数据获取和管理功能。
入参
// 获取单个字典数据
getDictData(type: string)
// 批量获取字典数据
getMultipleDictData(types: string[])
// 根据值获取文本
getDictText(dictData: DictItem[], value: string)
// 根据文本获取值
getDictValue(dictData: DictItem[], text: string)
出参
// 字典数据项
{
text: string, // 显示文本
value: string // 值
}
调用方式
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, '平板')
数据模型
// 字典项模型
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加密功能用于密码加密。
入参
aesEncrypt(word: string, keyWord?: string)
出参
// 加密后的字符串
string
调用方式
import { aesEncrypt } from '../utils/crypto.js'
// 加密密码
const encryptedPassword = aesEncrypt('123456', 'pigxpigxpigxpigx')
数据模型
// 加密参数模型
interface EncryptOptions {
word: string // 要加密的内容
keyWord?: string // 加密密钥，默认: 'pigxpigxpigxpigx'
}
6. API组件 (API)
功能描述
API接口管理组件，统一管理所有后端接口调用。
入参
// 认证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)
出参
// 标准API响应
{
statusCode: number,
data: object
}
调用方式
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')
数据模型
// 登录数据模型
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)
功能描述
车辆信息录入表单组件，支持照片上传、位置获取和订单提交。
入参
// 组件Props
{
visible: boolean, // 是否显示
carData: CarData, // 车辆数据
companyId: string // 供应商ID
}
出参
// 事件
{
submit: (formData) => void, // 表单提交事件
refresh: () => void // 刷新事件
}
调用方式
<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>
数据模型
// 车辆数据模型
interface CarData {
carNum: string // 车牌号
carType: string // 车辆类型
id: string // 车辆ID
carWeight: string // 车辆重量
carVolume: string // 车辆容积
}
// 表单数据模型
interface FormData {
carNum: string // 车牌号
carBackType: string // 尾挂类型
photos: string[] // 照片URL数组
}
8. 使用示例
完整登录流程
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
}
}
完整订单创建流程
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. 错误处理
统一错误处理
// 用户凭证过期处理
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'
})
}
})
}
网络错误处理
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. 调试功能
开发环境配置
// 调试环境下的默认账号密码
if (process.env.NODE_ENV === 'development') {
loginForm.username = 'driver'
loginForm.password = '123456'
console.log('调试环境：已设置默认账号密码')
}
日志输出
// 请求日志
console.log(`API请求成功: ${method} ${url}`, response)
// 调试信息
console.log('开始获取待完成车次数据，司机ID:', driverId)
console.log('今日统计API响应:', response)
console.log('获取位置成功:', location)
11. 性能优化
请求优化
- 统一请求超时设置
- 自动token注入
- 请求去重处理
缓存策略
- 用户信息本地存储
- 字典数据缓存
- 位置信息缓存
错误恢复
- 自动重试机制
- 降级处理
- 用户引导
12. 安全考虑
数据加密
- 密码AES加密
- 敏感信息保护
- 传输安全
权限控制
- 登录状态检查
- 角色权限验证
- 接口访问控制
数据验证
- 输入参数验证
- 响应数据校验
- 异常数据处理