chore(begin-route): 补充核心状态变量及常量的代码注释

hejianhao

2026-03-24 bd6b2c879657e6ed3ec6256e588d90cbb12d93f4

chore(begin-route): 补充核心状态变量及常量的代码注释

- 为所有 useState 声明的变量添加详细的用途说明注释
- 补充 useRef 变量的业务逻辑含义，如状态同步、防抖等
- 完善 STATUS_RULES 配置对象中各键值的含义说明
- 优化部分工具变量及常量的注释，提升代码可读性

 src/robotaxi/pages/begin-route/index.tsx

@@ -64,60 +64,61 @@
  const [endSite, setEndSite] = useState<any>({}); // 下车点
  const [tripStatus, setTripStatus] = useState<number>(Number(Taro.getStorageSync('tripStatus')) || 1); // 行程状态 1:发布行程 2:发布中 3:呼叫车中 4:车辆即将到达 5:车辆到达上车点 6:车辆行驶中 7:到达目的地 8:行程已结束 9:支付成功 10:取消订单时页面只展示一个上车点
  const [elapsedSeconds, setElapsedSeconds] = useState(0); // 等待计时秒数
  const requoteTriggeredRef = useRef(false);
  const requoteTriggeredRef = useRef(false); // 重新报价触发标记，防止重复触发
  const [showCancelPopup, setShowCancelPopup] = useState(false); // 取消弹窗是否显示
  const [showAnnouncementsPopup, setShowAnnouncementsPopup] = useState(false); // 安全注意事项动画弹窗是否显示
  const [showOverRoutePopup, setShowOverRoutePopup] = useState(false); // 结束行程弹窗是否显示
  const [showPassengerNotice, setShowPassengerNotice] = useState(false); // 乘车需知弹窗是否显示
  const [cancelType, setCancelType] = useState(1); // 取消类型
  const [showEvaluatePopup, setShowEvaluatePopup] = useState(false); // 评价弹窗是否显示
  const [showTipPopup, setShowTipPopup] = useState(false);
  const [tipType, setTipType] = useState('');
  const [showTipPopup, setShowTipPopup] = useState(false); // 提示弹窗是否显示
  const [tipType, setTipType] = useState(''); // 提示类型
  const [routePoints, setRoutePoints] = useState<any[]>([]); // 路线点集合
  // 步行路径点
  const [walkingPoints, setWalkingPoints] = useState<any[]>([]);
  const [walkingTime, setWalkingTime] = useState<number>(0);
  const carMarkerInitialized = useRef(false);
  const [walkingTime, setWalkingTime] = useState<number>(0); // 步行到上车点的预估时间（秒）
  const carMarkerInitialized = useRef(false); // 车辆标记是否已初始化
  const [fareEstimate, setFareEstimate] = useState<any>({}); // 预估费用信息
  const [routeAndFareError, setRouteAndFareError] = useState(false);
  const [callSubmitting, setCallSubmitting] = useState(false);
  const [vehicleLocation, setVehicleLocation] = useState<{ latitude: number, longitude: number } | null>(null);
  const [vehicleDirection, setVehicleDirection] = useState<number | null>(null);
  const [routeAndFareError, setRouteAndFareError] = useState(false); // 路线费用查询是否出错
  const [callSubmitting, setCallSubmitting] = useState(false); // 呼叫车辆提交中状态
  const [vehicleLocation, setVehicleLocation] = useState<{ latitude: number, longitude: number } | null>(null); // 车辆当前位置坐标
  const [vehicleDirection, setVehicleDirection] = useState<number | null>(null); // 车辆航向角（0-360度）
  const [routeDistance, setRouteDistance] = useState<{ value: number; unit: 'km' | 'm' } | null>(null); // 路线距离
  const [routeDuration, setRouteDuration] = useState<number | null>(null); // 路线时间
  const [vehicleInfo, setVehicleInfo] = useState<any>({}); // 车辆信息
  const [orderId, setOrderId] = useState<string>(''); // 订单ID
  const [finishCountdownEnabled, setFinishCountdownEnabled] = useState(false);
  const customCalloutIconUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/f9e285fc-4c09-404d-90f8-4bac178565d0.png';
  const waitingCalloutBgUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/f55ce277-68de-4615-9c7c-807f588afaac.png';
  const waitingRadarUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/63ff36fc-e84c-4078-a53b-467870645105.webp';
  const [customCalloutIconSrc, setCustomCalloutIconSrc] = useState(customCalloutIconUrl);
  const [waitingCalloutBgSrc, setWaitingCalloutBgSrc] = useState(waitingCalloutBgUrl);
  const [waitingRadarSrc, setWaitingRadarSrc] = useState(waitingRadarUrl);
  const [waitingRadarStyle, setWaitingRadarStyle] = useState<any>({});
  const [waitingRadarVisible, setWaitingRadarVisible] = useState(true);
  const [resetDetailVersion, setResetDetailVersion] = useState(0);
  const [priceUpdateVersion, setPriceUpdateVersion] = useState(0);
  const [evaluateSubmitVersion, setEvaluateSubmitVersion] = useState(0);
  const [evaluateCloseVersion, setEvaluateCloseVersion] = useState(0);
  const [originOpacity, setOriginOpacity] = useState(1);
  const [originBoxHidden, setOriginBoxHidden] = useState(false);
  const [mapBottomPadding, setMapBottomPadding] = useState(280);
  const [carCalloutStyle, setCarCalloutStyle] = useState<any>({});
  const [carCalloutVisible, setCarCalloutVisible] = useState(false);
  const [arriveCalloutStyle, setArriveCalloutStyle] = useState<any>({});
  const [arriveCalloutVisible, setArriveCalloutVisible] = useState(false);
  const [distanceConfig, setDistanceConfig] = useState<any>({});
  const [mapScale, setMapScale] = useState(14);
  const [showLocationFlag, setShowLocationFlag] = useState(true);
  const [trunkStatus, setTrunkStatus] = useState(false);
  const [finishCountdownEnabled, setFinishCountdownEnabled] = useState(false); // 完成倒计时是否启用
  const customCalloutIconUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/f9e285fc-4c09-404d-90f8-4bac178565d0.png'; // 自定义气泡图标URL
  const waitingCalloutBgUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/f55ce277-68de-4615-9c7c-807f588afaac.png'; // 等待气泡背景图URL
  const waitingRadarUrl = 'https://huishou-1323682843.cos.ap-nanjing.myqcloud.com/images/63ff36fc-e84c-4078-a53b-467870645105.webp'; // 等待雷达动画图URL
  const [customCalloutIconSrc, setCustomCalloutIconSrc] = useState(customCalloutIconUrl); // 自定义气泡图标源（本地缓存路径）
  const [waitingCalloutBgSrc, setWaitingCalloutBgSrc] = useState(waitingCalloutBgUrl); // 等待气泡背景图源
  const [waitingRadarSrc, setWaitingRadarSrc] = useState(waitingRadarUrl); // 等待雷达动画图源
  const [waitingRadarStyle, setWaitingRadarStyle] = useState<any>({}); // 等待雷达动画样式
  const [waitingRadarVisible, setWaitingRadarVisible] = useState(true); // 等待雷达动画是否可见
  const [resetDetailVersion, setResetDetailVersion] = useState(0); // 重置详情版本号，用于触发组件更新
  const [priceUpdateVersion, setPriceUpdateVersion] = useState(0); // 价格更新版本号
  const [evaluateSubmitVersion, setEvaluateSubmitVersion] = useState(0); // 评价提交版本号
  const [evaluateCloseVersion, setEvaluateCloseVersion] = useState(0); // 评价关闭版本号
  const [originOpacity, setOriginOpacity] = useState(1); // 起点标记透明度
  const [originBoxHidden, setOriginBoxHidden] = useState(false); // 起点信息框是否隐藏
  const [mapBottomPadding, setMapBottomPadding] = useState(280); // 地图底部内边距（像素）
  const [carCalloutStyle, setCarCalloutStyle] = useState<any>({}); // 车辆气泡标注样式
  const [carCalloutVisible, setCarCalloutVisible] = useState(false); // 车辆气泡标注是否可见
  const [arriveCalloutStyle, setArriveCalloutStyle] = useState<any>({}); // 到达气泡标注样式
  const [arriveCalloutVisible, setArriveCalloutVisible] = useState(false); // 到达气泡标注是否可见
  const [distanceConfig, setDistanceConfig] = useState<any>({}); // 距离显示配置
  const [mapScale, setMapScale] = useState(14); // 地图缩放级别
  const [showLocationFlag, setShowLocationFlag] = useState(true); // 是否显示定位按钮
  const [trunkStatus, setTrunkStatus] = useState(false); // 后备箱开启状态

  const markersRef = useRef<any[]>([]);
  const markersRef = useRef<any[]>([]); // 标记点列表引用，用于实时访问最新值
  const tripStatusRef = useRef(tripStatus); // 行程状态引用
  const lastTripStatusRef = useRef(tripStatus);
  const tripStatusForMapSyncRef = useRef(tripStatus);
  const lastTripStatusRef = useRef(tripStatus); // 上一次行程状态，用于检测状态变化
  const tripStatusForMapSyncRef = useRef(tripStatus); // 用于地图同步的行程状态引用
  const routeRequestKeyRef = useRef<string>(''); // 路线请求键
  const orderRouteInitializedRef = useRef(false);
  const orderRouteInitializedRef = useRef(false); // 订单路线是否已初始化
  // 行程状态显示规则配置：showPickup-显示上车点，showDropoff-显示下车点，showCar-显示车辆，showRoute-显示路线，showWalking-显示步行路线，viewport-视口类型，translateCar-车辆是否平移
  const STATUS_RULES: Record<number, any> = {
    1: { showPickup: true, showDropoff: true, showCar: false, showRoute: true, showWalking: true, viewport: 'route_walking', translateCar: false },
    2: { showPickup: true, showDropoff: false, showCar: false, showRoute: false, showWalking: false, viewport: 'pickup', translateCar: false },
@@ -130,40 +131,40 @@
    9: { showPickup: true, showDropoff: true, showCar: false, showRoute: true, showWalking: false, viewport: 'order_detail', translateCar: false },
    10: { showPickup: true, showDropoff: false, showCar: false, showRoute: false, showWalking: false, viewport: 'pickup', translateCar: false },
  };
  const statusRule = useMemo(() => STATUS_RULES[tripStatus] || STATUS_RULES[1], [tripStatus]);
  const shouldShowRoute = statusRule.showRoute;
  const statusRule = useMemo(() => STATUS_RULES[tripStatus] || STATUS_RULES[1], [tripStatus]); // 当前行程状态对应的显示规则
  const shouldShowRoute = statusRule.showRoute; // 当前状态是否显示路线
  const authSuccessBound = useRef(false); // 认证成功是否绑定
  const messageBound = useRef(false); // 消息是否绑定
  const orderStatusBound = useRef(false); // 订单状态是否绑定
  const orderRouteBound = useRef(false); // 订单路线是否绑定
  const vehicleLocationBound = useRef(false); // 车辆位置是否绑定
  const openTrunkBound = useRef(false);
  const orderUpdatePriceBound = useRef(false);
  const openTrunkBound = useRef(false); // 打开后备箱事件是否绑定
  const orderUpdatePriceBound = useRef(false); // 订单价格更新事件是否绑定
  const authSuccessHandlerRef = useRef<(data: any) => void>(); // 认证成功处理函数
  const messageHandlerRef = useRef<(data: any) => void>(); // 消息处理函数
  const orderStatusHandlerRef = useRef<(data: any) => void>(); // 订单状态处理函数
  const orderRouteHandlerRef = useRef<(data: any) => void>(); // 订单路线处理函数
  const vehicleLocationHandlerRef = useRef<(data: any) => void>(); // 车辆位置处理函数
  const openTrunkHandlerRef = useRef<(data: any) => void>();
  const orderUpdatePriceHandlerRef = useRef<(data: any) => void>();
  const socketOpenHandlerRef = useRef<(() => void) | null>(null);
  const openTrunkHandlerRef = useRef<(data: any) => void>(); // 打开后备箱事件处理函数
  const orderUpdatePriceHandlerRef = useRef<(data: any) => void>(); // 订单价格更新事件处理函数
  const socketOpenHandlerRef = useRef<(() => void) | null>(null); // WebSocket连接打开处理函数
  // 记录已为某订单拉取过车辆信息，避免重复
  const lastFetchedVehicleOrderIdRef = useRef<string | null>(null);
  const mapRectRef = useRef<any>(null);
  const viewportKeyRef = useRef<string>('');
  const tripStatus6ViewportLockedRef = useRef(false);
  const tripStatus6MarkerRefreshedRef = useRef(false);
  const polylineKeyRef = useRef<string>('');
  const orderDetailRouteRequestIdRef = useRef(0);
  const lastRoutePointRef = useRef<{ latitude: number; longitude: number } | null>(null);
  const lastRouteUpdateAtRef = useRef<number>(0);
  const lastVehiclePointRef = useRef<{ latitude: number; longitude: number } | null>(null);
  const lastVehicleUpdateAtRef = useRef<number>(0);
  const lastPolylineUpdateAtRef = useRef<number>(0);
  const lastRouteAndFareRequestAtRef = useRef<number>(0);
  const markersSignatureRef = useRef<string>('');
  const currentFullRouteRef = useRef<any[]>([]);
  const lastErasedIndexRef = useRef<number>(0);
  const mapRectRef = useRef<any>(null); // 地图边界矩形区域引用
  const viewportKeyRef = useRef<string>(''); // 视口唯一键，用于标识视口状态
  const tripStatus6ViewportLockedRef = useRef(false); // 行程状态6视口是否锁定
  const tripStatus6MarkerRefreshedRef = useRef(false); // 行程状态6标记是否已刷新
  const polylineKeyRef = useRef<string>(''); // 路线唯一键
  const orderDetailRouteRequestIdRef = useRef(0); // 订单详情路线请求ID
  const lastRoutePointRef = useRef<{ latitude: number; longitude: number } | null>(null); // 最后一次路线点位置
  const lastRouteUpdateAtRef = useRef<number>(0); // 最后路线更新时间戳
  const lastVehiclePointRef = useRef<{ latitude: number; longitude: number } | null>(null); // 最后一次车辆位置
  const lastVehicleUpdateAtRef = useRef<number>(0); // 最后车辆位置更新时间戳
  const lastPolylineUpdateAtRef = useRef<number>(0); // 最后路线绘制更新时间戳
  const lastRouteAndFareRequestAtRef = useRef<number>(0); // 最后路线费用请求时间戳
  const markersSignatureRef = useRef<string>(''); // 标记点签名，用于检测变化
  const currentFullRouteRef = useRef<any[]>([]); // 当前完整路线点集合
  const lastErasedIndexRef = useRef<number>(0); // 最后擦除的路线点索引
  const isAndroid = useMemo(() => {
    try {
      const info = Taro.getSystemInfoSync();
@@ -173,10 +174,10 @@
      return false;
    }
  }, []);
  const shouldShowWaitingRadar = isAndroid && [2, 3].includes(tripStatus);
  const vehicleMarkerId = !isAndroid && tripStatus === 6 ? 30 : 3;
  const isCheckedEnter = useRef(false);
  const router = Taro.useRouter();
  const shouldShowWaitingRadar = isAndroid && [2, 3].includes(tripStatus); // 是否显示等待雷达动画（Android且状态2/3）
  const vehicleMarkerId = !isAndroid && tripStatus === 6 ? 30 : 3; // 车辆标记ID，iOS状态6使用不同ID
  const isCheckedEnter = useRef(false); // 是否已检查页面进入状态
  const router = Taro.useRouter(); // 路由对象

  useEffect(() => {
    const wasHold = [4, 6].includes(lastTripStatusRef.current);