车驾管服务系统详细设计说明书

/**
 * 订单实体类
 */
public class Order {
    /**
     * 订单ID
     */
    private Long orderId;
    
    /**
     * 订单号（唯一）
     */
    private String orderNo;
    
    /**
     * 客户ID
     */
    private Long customerId;
    
    /**
     * 车辆ID
     */
    private Long vehicleId;
    
    /**
     * 服务类型ID
     */
    private Long serviceId;
    
    /**
     * 订单类型（DRIVER-代驾订单, SELF-自驾订单）
     */
    private String orderType;
    
    /**
     * 订单来源（CUSTOMER-客户直接下单, CHANNEL-渠道API下单, ADMIN-管理员手动创建）
     */
    private String orderSource;
    
    /**
     * 渠道ID（渠道来源订单必填）
     */
    private Long channelId;
    
    /**
     * 订单状态（PENDING_PAYMENT-待支付, PAID-已支付, PENDING_ASSIGN-待分配, 
     * PROCESSING-办理中, PENDING_CONFIRM-待确认, COMPLETED-已完成, 
     * CANCELLED-已取消, REFUNDED-已退款）
     */
    private String status;
    
    /**
     * 订单金额
     */
    private BigDecimal amount;
    
    /**
     * 实际支付金额
     */
    private BigDecimal paidAmount;
    
    /**
     * 服务地址
     */
    private String serviceAddress;
    
    /**
     * 服务时间
     */
    private LocalDateTime serviceTime;
    
    /**
     * 代驾人员ID
     */
    private Long driverId;
    
    /**
     * 接待员ID
     */
    private Long receptionistId;
    
    /**
     * 检测站ID
     */
    private Long stationId;
    
    /**
     * 订单备注
     */
    private String remark;
    
    /**
     * 创建时间
     */
    private LocalDateTime createTime;
    
    /**
     * 更新时间
     */
    private LocalDateTime updateTime;
    
    // getter/setter方法
}

/**
 * 订单服务接口
 */
public interface OrderService {
    /**
     * 创建订单（客户下单）
     * @param orderCreateDTO 订单创建DTO
     * @return 订单信息
     */
    OrderVO createOrder(OrderCreateDTO orderCreateDTO);
    
    /**
     * 创建订单（渠道API下单）
     * @param channelOrderCreateDTO 渠道订单创建DTO
     * @return 订单信息
     */
    OrderVO createOrderFromChannel(ChannelOrderCreateDTO channelOrderCreateDTO);
    
    /**
     * 手动创建订单
     * @param adminOrderCreateDTO 管理员订单创建DTO
     * @return 订单信息
     */
    OrderVO createOrderByAdmin(AdminOrderCreateDTO adminOrderCreateDTO);
    
    /**
     * 查询订单列表
     * @param queryDTO 查询条件
     * @return 订单列表
     */
    PageResult<OrderVO> queryOrderList(OrderQueryDTO queryDTO);
    
    /**
     * 查询订单详情
     * @param orderId 订单ID
     * @return 订单详情
     */
    OrderDetailVO getOrderDetail(Long orderId);
    
    /**
     * 更新订单状态
     * @param orderId 订单ID
     * @param newStatus 新状态
     * @param operatorId 操作人ID
     * @param reason 变更原因
     */
    void updateOrderStatus(Long orderId, String newStatus, Long operatorId, String reason);
    
    /**
     * 取消订单
     * @param orderId 订单ID
     * @param reason 取消原因
     */
    void cancelOrder(Long orderId, String reason);
    
    /**
     * 分配订单
     * @param orderId 订单ID
     * @param assignDTO 分配信息
     */
    void assignOrder(Long orderId, OrderAssignDTO assignDTO);
}

/**
 * 订单状态机
 * 管理订单状态的流转规则
 */
public class OrderStateMachine {
    
    /**
     * 订单状态流转规则
     */
    private static final Map<String, Set<String>> STATUS_TRANSITION_MAP = new HashMap<>();
    
    static {
        // 待支付可以流转到：已支付、已取消
        STATUS_TRANSITION_MAP.put("PENDING_PAYMENT", 
            Set.of("PAID", "CANCELLED"));
        
        // 已支付可以流转到：待分配、已退款、已取消
        STATUS_TRANSITION_MAP.put("PAID", 
            Set.of("PENDING_ASSIGN", "REFUNDED", "CANCELLED"));
        
        // 待分配可以流转到：办理中、已取消
        STATUS_TRANSITION_MAP.put("PENDING_ASSIGN", 
            Set.of("PROCESSING", "CANCELLED"));
        
        // 办理中可以流转到：待确认、已取消
        STATUS_TRANSITION_MAP.put("PROCESSING", 
            Set.of("PENDING_CONFIRM", "CANCELLED"));
        
        // 待确认可以流转到：已完成、已取消
        STATUS_TRANSITION_MAP.put("PENDING_CONFIRM", 
            Set.of("COMPLETED", "CANCELLED"));
        
        // 已完成、已取消、已退款为终态，不能再流转
    }
    
    /**
     * 验证状态流转是否合法
     * @param currentStatus 当前状态
     * @param newStatus 新状态
     * @return 是否合法
     */
    public boolean canTransition(String currentStatus, String newStatus) {
        Set<String> allowedStatuses = STATUS_TRANSITION_MAP.get(currentStatus);
        if (allowedStatuses == null) {
            return false;
        }
        return allowedStatuses.contains(newStatus);
    }
    
    /**
     * 获取可流转的状态列表
     * @param currentStatus 当前状态
     * @return 可流转的状态列表
     */
    public Set<String> getAllowedStatuses(String currentStatus) {
        return STATUS_TRANSITION_MAP.getOrDefault(currentStatus, Collections.emptySet());
    }
}

/**
 * 更新订单状态
 */
public void updateOrderStatus(Long orderId, String newStatus, Long operatorId, String reason) {
    // 1. 查询订单当前状态
    Order order = orderMapper.selectById(orderId);
    if (order == null) {
        throw new BusinessException("订单不存在");
    }
    
    String currentStatus = order.getStatus();
    
    // 2. 验证状态流转是否合法
    if (!orderStateMachine.canTransition(currentStatus, newStatus)) {
        throw new BusinessException(
            String.format("订单状态不能从 %s 流转到 %s", currentStatus, newStatus));
    }
    
    // 3. 使用分布式锁，防止并发修改
    String lockKey = "order:status:lock:" + orderId;
    RLock lock = redissonClient.getLock(lockKey);
    try {
        if (lock.tryLock(5, 10, TimeUnit.SECONDS)) {
            // 4. 再次查询订单状态（双重检查）
            order = orderMapper.selectById(orderId);
            if (!currentStatus.equals(order.getStatus())) {
                throw new BusinessException("订单状态已被修改，请刷新后重试");
            }
            
            // 5. 更新订单状态
            order.setStatus(newStatus);
            order.setUpdateTime(LocalDateTime.now());
            orderMapper.updateById(order);
            
            // 6. 记录状态变更日志
            OrderStatusLog statusLog = new OrderStatusLog();
            statusLog.setOrderId(orderId);
            statusLog.setOldStatus(currentStatus);
            statusLog.setNewStatus(newStatus);
            statusLog.setOperatorId(operatorId);
            statusLog.setReason(reason);
            statusLog.setCreateTime(LocalDateTime.now());
            orderStatusLogMapper.insert(statusLog);
            
            // 7. 发送状态变更通知
            sendStatusChangeNotification(order, currentStatus, newStatus);
            
            // 8. 如果状态为"已支付"，触发订单分配流程
            if ("PAID".equals(newStatus)) {
                triggerOrderAssign(order);
            }
            
            // 9. 如果状态为"已完成"，触发后续流程
            if ("COMPLETED".equals(newStatus)) {
                triggerOrderComplete(order);
            }
        } else {
            throw new BusinessException("订单正在处理中，请稍后重试");
        }
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
        throw new BusinessException("订单状态更新失败");
    } finally {
        if (lock.isHeldByCurrentThread()) {
            lock.unlock();
        }
    }
}

/**
 * 订单分配规则引擎
 */
public class OrderAssignRuleEngine {
    
    /**
     * 代驾人员分配规则
     */
    public List<Driver> filterDrivers(Order order, List<Driver> allDrivers) {
        return allDrivers.stream()
            .filter(driver -> checkDriverStatus(driver))           // 状态检查
            .filter(driver -> checkDriverArea(driver, order))     // 区域检查
            .filter(driver -> checkDriverWorkload(driver))         // 负载检查
            .filter(driver -> checkDriverQualification(driver))    // 资质检查
            .filter(driver -> checkDriverRating(driver))           // 评价检查
            .collect(Collectors.toList());
    }
    
    /**
     * 代驾人员排序（优先级排序）
     */
    public List<Driver> sortDrivers(List<Driver> drivers, Order order) {
        return drivers.stream()
            .sorted(Comparator
                .comparing((Driver d) -> calculateDistance(d, order)).thenComparing(  // 距离最近
                Comparator.comparing(Driver::getCurrentOrderCount)).thenComparing(      // 负载最轻
                Comparator.comparing(Driver::getAverageRating).reversed()).thenComparing( // 评价最高
                Comparator.comparing(Driver::getAverageResponseTime)))                 // 响应最快
            .collect(Collectors.toList());
    }
    
    /**
     * 计算距离（使用高德地图API或数据库存储的距离信息）
     */
    private double calculateDistance(Driver driver, Order order) {
        // 实现距离计算逻辑
        // 可以使用高德地图API计算实际距离
        // 或使用数据库存储的距离信息
        return 0.0;
    }
}

/**
 * 渠道实体类
 */
public class Channel {
    /**
     * 渠道ID
     */
    private Long channelId;
    
    /**
     * 渠道编码（唯一）
     */
    private String channelCode;
    
    /**
     * 渠道名称
     */
    private String channelName;
    
    /**
     * 联系方式
     */
    private String contactPhone;
    
    /**
     * 地址
     */
    private String address;
    
    /**
     * 负责人
     */
    private String contactPerson;
    
    /**
     * 业务类型
     */
    private String businessType;
    
    /**
     * 渠道状态（ENABLED-启用, DISABLED-停用, PENDING-审核中, BANNED-已禁用）
     */
    private String status;
    
    /**
     * API Key
     */
    private String apiKey;
    
    /**
     * API Secret（加密存储）
     */
    private String apiSecret;
    
    /**
     * 创建时间
     */
    private LocalDateTime createTime;
    
    /**
     * 更新时间
     */
    private LocalDateTime updateTime;
    
    // getter/setter方法
}

/**
 * API签名验证服务
 */
@Service
public class ApiSignatureService {
    
    /**
     * 验证API签名
     * @param request 请求对象
     * @param apiKey API Key
     * @param apiSecret API Secret
     * @return 是否验证通过
     */
    public boolean verifySignature(HttpServletRequest request, String apiKey, String apiSecret) {
        // 1. 获取请求参数
        String timestamp = request.getHeader("X-Timestamp");
        String nonce = request.getHeader("X-Nonce");
        String signature = request.getHeader("X-Signature");
        
        // 2. 验证时间戳（防止重放攻击，时间差不超过5分钟）
        if (!isValidTimestamp(timestamp)) {
            return false;
        }
        
        // 3. 验证nonce（防止重复请求，使用Redis存储已使用的nonce）
        if (!isValidNonce(nonce)) {
            return false;
        }
        
        // 4. 构建签名字符串
        String signString = buildSignString(request, timestamp, nonce);
        
        // 5. 计算签名
        String calculatedSignature = calculateSignature(signString, apiSecret);
        
        // 6. 比较签名
        return signature != null && signature.equals(calculatedSignature);
    }
    
    /**
     * 构建签名字符串
     */
    private String buildSignString(HttpServletRequest request, String timestamp, String nonce) {
        // 获取请求方法、URI、参数等
        String method = request.getMethod();
        String uri = request.getRequestURI();
        String queryString = request.getQueryString();
        String body = getRequestBody(request);
        
        // 按字典序排序参数
        Map<String, String> params = new TreeMap<>();
        params.put("timestamp", timestamp);
        params.put("nonce", nonce);
        if (queryString != null) {
            // 解析query参数
            String[] pairs = queryString.split("&");
            for (String pair : pairs) {
                String[] kv = pair.split("=");
                if (kv.length == 2) {
                    params.put(kv[0], kv[1]);
                }
            }
        }
        if (body != null && !body.isEmpty()) {
            // 解析body参数（JSON格式）
            // ...
        }
        
        // 构建签名字符串
        StringBuilder sb = new StringBuilder();
        sb.append(method).append("\n");
        sb.append(uri).append("\n");
        for (Map.Entry<String, String> entry : params.entrySet()) {
            sb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
        }
        if (sb.length() > 0) {
            sb.deleteCharAt(sb.length() - 1);
        }
        
        return sb.toString();
    }
    
    /**
     * 计算签名（HMAC-SHA256）
     */
    private String calculateSignature(String signString, String apiSecret) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hash = mac.doFinal(signString.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hash);
        } catch (Exception e) {
            throw new RuntimeException("签名计算失败", e);
        }
    }
    
    /**
     * 验证时间戳
     */
    private boolean isValidTimestamp(String timestamp) {
        try {
            long ts = Long.parseLong(timestamp);
            long currentTime = System.currentTimeMillis() / 1000;
            long diff = Math.abs(currentTime - ts);
            return diff <= 300; // 5分钟内有效
        } catch (Exception e) {
            return false;
        }
    }
    
    /**
     * 验证nonce
     */
    private boolean isValidNonce(String nonce) {
        // 使用Redis存储已使用的nonce，有效期5分钟
        String key = "api:nonce:" + nonce;
        Boolean exists = redisTemplate.hasKey(key);
        if (exists != null && exists) {
            return false; // nonce已使用
        }
        redisTemplate.opsForValue().set(key, "1", 5, TimeUnit.MINUTES);
        return true;
    }
}

/**
 * API限流服务（令牌桶算法）
 */
@Service
public class ApiRateLimitService {
    
    @Autowired
    private RedisTemplate<String, Object> redisTemplate;
    
    /**
     * 检查是否限流
     * @param channelId 渠道ID
     * @param limit 限流阈值（每分钟请求数）
     * @return 是否允许请求
     */
    public boolean checkRateLimit(Long channelId, int limit) {
        String key = "api:ratelimit:" + channelId;
        
        // 获取当前令牌数
        String tokensStr = (String) redisTemplate.opsForValue().get(key);
        int tokens = tokensStr != null ? Integer.parseInt(tokensStr) : limit;
        
        if (tokens > 0) {
            // 有令牌，允许请求，令牌数减1
            redisTemplate.opsForValue().set(key, String.valueOf(tokens - 1), 60, TimeUnit.SECONDS);
            return true;
        } else {
            // 无令牌，拒绝请求
            return false;
        }
    }
    
    /**
     * 添加令牌（定时任务，每秒添加limit/60个令牌）
     */
    @Scheduled(fixedRate = 1000)
    public void addTokens() {
        // 获取所有渠道的限流配置
        List<Channel> channels = channelService.getAllChannels();
        for (Channel channel : channels) {
            if ("ENABLED".equals(channel.getStatus())) {
                String key = "api:ratelimit:" + channel.getChannelId();
                int limit = channel.getRateLimit(); // 每分钟限流数
                int addTokens = limit / 60; // 每秒添加的令牌数
                
                String tokensStr = (String) redisTemplate.opsForValue().get(key);
                int tokens = tokensStr != null ? Integer.parseInt(tokensStr) : limit;
                int newTokens = Math.min(tokens + addTokens, limit); // 不超过上限
                
                redisTemplate.opsForValue().set(key, String.valueOf(newTokens), 60, TimeUnit.SECONDS);
            }
        }
    }
}

/**
 * 支付服务接口
 */
public interface PaymentService {
    /**
     * 创建支付订单
     * @param orderId 订单ID
     * @param paymentType 支付方式（WECHAT-微信, ALIPAY-支付宝）
     * @return 支付信息（支付URL或支付参数）
     */
    PaymentVO createPayment(Long orderId, String paymentType);
    
    /**
     * 处理支付回调
     * @param paymentType 支付方式
     * @param callbackData 回调数据
     * @return 处理结果
     */
    PaymentCallbackResult handlePaymentCallback(String paymentType, Map<String, String> callbackData);
    
    /**
     * 查询支付状态
     * @param paymentNo 支付流水号
     * @return 支付状态
     */
    PaymentStatusVO queryPaymentStatus(String paymentNo);
    
    /**
     * 申请退款
     * @param orderId 订单ID
     * @param refundAmount 退款金额
     * @param reason 退款原因
     * @return 退款信息
     */
    RefundVO applyRefund(Long orderId, BigDecimal refundAmount, String reason);
    
    /**
     * 处理退款回调
     * @param paymentType 支付方式
     * @param callbackData 回调数据
     * @return 处理结果
     */
    RefundCallbackResult handleRefundCallback(String paymentType, Map<String, String> callbackData);
}

/**
 * 代驾人员分配算法
 */
public Driver assignDriver(Order order) {
    // 1. 筛选符合条件的代驾人员
    List<Driver> candidates = driverService.findAvailableDrivers(order);
    
    if (candidates.isEmpty()) {
        throw new BusinessException("没有可用的代驾人员");
    }
    
    // 2. 计算每个代驾人员的综合得分
    List<DriverScore> scores = new ArrayList<>();
    for (Driver driver : candidates) {
        double score = calculateDriverScore(driver, order);
        scores.add(new DriverScore(driver, score));
    }
    
    // 3. 按得分排序（得分越高优先级越高）
    scores.sort((a, b) -> Double.compare(b.getScore(), a.getScore()));
    
    // 4. 选择得分最高的代驾人员
    Driver selectedDriver = scores.get(0).getDriver();
    
    // 5. 分配订单
    assignOrderToDriver(order, selectedDriver);
    
    return selectedDriver;
}

/**
 * 计算代驾人员综合得分
 */
private double calculateDriverScore(Driver driver, Order order) {
    double score = 0.0;
    
    // 距离得分（距离越近得分越高，权重40%）
    double distance = calculateDistance(driver.getLocation(), order.getServiceAddress());
    double distanceScore = 100.0 / (1.0 + distance / 10.0); // 距离每增加10km，得分减半
    score += distanceScore * 0.4;
    
    // 负载得分（负载越轻得分越高，权重30%）
    int currentOrders = driver.getCurrentOrderCount();
    int maxOrders = driver.getMaxConcurrentOrders();
    double loadScore = 100.0 * (1.0 - (double)currentOrders / maxOrders);
    score += loadScore * 0.3;
    
    // 评价得分（评价越高得分越高，权重20%）
    double rating = driver.getAverageRating();
    double ratingScore = rating * 20.0; // 5星评价 = 100分
    score += ratingScore * 0.2;
    
    // 响应速度得分（响应越快得分越高，权重10%）
    long avgResponseTime = driver.getAverageResponseTime(); // 秒
    double responseScore = 100.0 / (1.0 + avgResponseTime / 60.0); // 响应时间每增加60秒，得分减半
    score += responseScore * 0.1;
    
    return score;
}

/**
 * 接待员分配算法
 */
public Receptionist assignReceptionist(Order order) {
    // 1. 筛选符合条件的接待员
    List<Receptionist> candidates = receptionistService.findAvailableReceptionists(order);
    
    if (candidates.isEmpty()) {
        throw new BusinessException("没有可用的接待员");
    }
    
    // 2. 计算每个接待员的综合得分
    List<ReceptionistScore> scores = new ArrayList<>();
    for (Receptionist receptionist : candidates) {
        double score = calculateReceptionistScore(receptionist, order);
        scores.add(new ReceptionistScore(receptionist, score));
    }
    
    // 3. 按得分排序
    scores.sort((a, b) -> Double.compare(b.getScore(), a.getScore()));
    
    // 4. 选择得分最高的接待员
    Receptionist selectedReceptionist = scores.get(0).getReceptionist();
    
    // 5. 分配订单
    assignOrderToReceptionist(order, selectedReceptionist);
    
    return selectedReceptionist;
}

/**
 * 计算接待员综合得分
 */
private double calculateReceptionistScore(Receptionist receptionist, Order order) {
    double score = 0.0;
    
    // 负载得分（权重50%）
    int currentOrders = receptionist.getCurrentOrderCount();
    int maxOrders = receptionist.getMaxConcurrentOrders();
    double loadScore = 100.0 * (1.0 - (double)currentOrders / maxOrders);
    score += loadScore * 0.5;
    
    // 距离得分（权重30%）
    double distance = calculateDistance(receptionist.getLocation(), order.getServiceAddress());
    double distanceScore = 100.0 / (1.0 + distance / 10.0);
    score += distanceScore * 0.3;
    
    // 完成率得分（权重20%）
    double completionRate = receptionist.getCompletionRate();
    double completionScore = completionRate * 100.0;
    score += completionScore * 0.2;
    
    return score;
}

/**
 * 全局异常处理器
 */
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    /**
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public Result handleBusinessException(BusinessException e) {
        log.warn("业务异常：{}", e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }
    
    /**
     * 处理参数异常
     */
    @ExceptionHandler(ParameterException.class)
    public Result handleParameterException(ParameterException e) {
        log.warn("参数异常：{}", e.getMessage());
        return Result.error(400, e.getMessage());
    }
    
    /**
     * 处理系统异常
     */
    @ExceptionHandler(SystemException.class)
    public Result handleSystemException(SystemException e) {
        log.error("系统异常：", e);
        return Result.error(500, "系统异常，请稍后重试");
    }
    
    /**
     * 处理其他异常
     */
    @ExceptionHandler(Exception.class)
    public Result handleException(Exception e) {
        log.error("未知异常：", e);
        return Result.error(500, "系统异常，请稍后重试");
    }
}

/**
 * 重试机制实现
 */
@Retryable(value = {SystemException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000, multiplier = 2))
public void callThirdPartyService() {
    // 调用第三方服务
}

/**
 * 数据加密服务
 */
@Service
public class EncryptionService {
    
    private static final String ALGORITHM = "AES";
    private static final String TRANSFORMATION = "AES/CBC/PKCS5Padding";
    
    /**
     * 加密
     */
    public String encrypt(String data) {
        // 实现AES加密
    }
    
    /**
     * 解密
     */
    public String decrypt(String encryptedData) {
        // 实现AES解密
    }
}