chajia/modules/providers/quote-provider.ts

/** QuoteProvider 接口契约（PRD 附录 A / 技术设计 §7.1） */

export type ProviderAddress = {
  street: string;
  city: string;
  state: string;
  zip: string;
  placeId: string;
  formattedAddress: string;
  selectedFromSuggestions: boolean;
  mothershipOptionId: string;
  mothershipDisplayLabel: string;
  selectedFromMothership: boolean;
};

export type QuoteRequest = {
  cargoHash: string;
  /** 候选 API 返回的单会话 ID，复用 browser storageState */
  quoteSessionId?: string;
  pickup: ProviderAddress;
  delivery: ProviderAddress;
  weightLb: number;
  dimsIn: { l: number; w: number; h: number };
  palletCount: number;
  cargoType: string;
};

export type RateOptionKind = "lowest" | "fastest" | "bestValue";

export type QuoteItem = {
  serviceLevel: "standard" | "guaranteed";
  rateOption: RateOptionKind;
  carrier: string;
  transitDays: string;
  transitDescription: string;
  rawFreight: number;
  surcharges: number;
  rawTotal: number;
};

export type QuoteResult = {
  /** 至少含核心 4 档；MotherShip 有 bestValue 等扩展档时一并返回 */
  items: QuoteItem[];
  sourceType: "rpa";
  confidenceScore: number;
};

export interface QuoteProvider {
  getQuote(req: QuoteRequest): Promise<QuoteResult>;
  healthCheck(): Promise<boolean>;
}