12 - 财务票据 OCR：端点全景、统一文档模型与接入架构¶

/** 财务票据种类（与 multiple_invoice 的 type 及专用端点对应）。 */
export type DocumentKind =
  | 'vat_invoice'
  | 'machine_invoice'
  | 'quota_invoice'
  | 'train_ticket'
  | 'taxi_receipt'
  | 'online_taxi_itinerary'
  | 'air_ticket'
  | 'bus_ticket'
  | 'toll_invoice'
  | 'ferry_ticket'
  | 'vehicle_sale_invoice'
  | 'used_vehicle_invoice'
  | 'shopping_receipt'
  | 'bank_receipt'
  | 'other';

/** 所有文档共有的最小外壳：仅存原始返回与质量标记，兜住红线 5。 */
interface DocumentBase {
  readonly sourceType: string | null; // multiple_invoice 的 type 原值
  readonly raw: Readonly<Record<string, unknown>>; // 完整返回（红线 5）
  readonly confidenceFlags: ReadonlyArray<string>; // amount_unparsed / amount_mismatch …
}

// ── 增值税 / 机打 / 定额：金额 + 商品行 ─────────────────────────────
export interface GoodsLine {
  readonly row: number;
  readonly name: string;
  readonly unit: string | null;
  readonly quantity: string | null;
  readonly unitPriceFen: Fen | null;
  readonly amountFen: Fen | null;
  readonly taxRate: string | null;
}

/**
 * 发票票种（取自百度验真接口的 invoice_type 枚举，权威且稳定）：发票不是一种结构，
 * 专票有进项字段、通行费有出入口、机动车有车辆/合格证、铁路/航空有乘客与车次航班。
 */
export type InvoiceKind =
  | 'special_vat' // 增值税专用发票
  | 'elec_special_vat' // 增值税电子专票
  | 'normal_vat' // 增值税普通发票
  | 'elec_normal_vat' // 增值税普通发票（电子）
  | 'roll_normal_vat' // 增值税普通发票（卷式）
  | 'elec_invoice_special' // 全电发票（专用发票）
  | 'elec_invoice_normal' // 全电发票（普通发票）
  | 'toll_elec_normal' // 通行费增值税电子普通发票
  | 'freight_special' // 货运运输业增值税专用发票
  | 'motor_vehicle_sale' // 机动车销售统一发票（含电子）
  | 'used_vehicle_sale' // 二手车销售统一发票（含电子）
  | 'blockchain' // 区块链发票
  | 'printed_elec' // 通用机打电子发票
  | 'railway_elec' // 电子发票（铁路电子客票）
  | 'air_elec_itinerary'; // 电子发票（航空电子客票行程单）

/** 发票公共票面字段；票种差异全部下移到各 subtype，避免大而全的“发票结构”。 */
interface InvoiceBase extends DocumentBase {
  readonly kind: 'vat_invoice'; // 文档大类
  readonly invoiceKind: InvoiceKind; // 票种判别键（第二层）
  readonly invoiceNum: string; // 发票号码（组织级防重键）
  readonly invoiceCode: string | null; // 发票代码（全电票为空）
  readonly invoiceTypeOrg: string | null; // 票面名称，如“浙江增值税专用发票”
  readonly invoiceDate: string | null;
  readonly amountFen: Fen; // 价税合计
  readonly totalAmountFen: Fen | null; // 不含税
  readonly totalTaxFen: Fen | null;
  readonly sellerName: string | null;
  readonly sellerRegisterNum: string | null;
  readonly purchaserName: string | null;
  readonly purchaserRegisterNum: string | null;
  readonly items: ReadonlyArray<GoodsLine>;
  readonly remarks: string | null;
}

/** 普票 / 电子普票 / 全电普票：买方常为个人，无专票进项字段。 */
export interface NormalVatInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'normal_vat' | 'elec_normal_vat' | 'elec_invoice_normal';
  readonly checkCode: string | null;
  readonly invoiceNumDigit: string | null; // 全电票号码（密码区）
}

/** 专票 / 电子专票 / 全电专票 / 货运专票：含双方地址银行等进项字段。 */
export interface SpecialVatInvoiceDocument extends InvoiceBase {
  readonly invoiceKind:
    'special_vat' | 'elec_special_vat' | 'elec_invoice_special' | 'freight_special';
  readonly sellerAddress: string | null;
  readonly sellerBank: string | null;
  readonly purchaserAddress: string | null;
  readonly purchaserBank: string | null;
  readonly invoiceNumDigit: string | null;
  /** 货运专票专属：运输工具/车牌/起讫/货物。 */
  readonly transport: {
    readonly type: string | null;
    readonly plateNum: string | null;
    readonly departure: string | null;
    readonly arrival: string | null;
    readonly cargo: string | null;
  } | null;
}

/** 卷票：无代码校验场景，含卷号。 */
export interface RollVatInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'roll_normal_vat';
}

/** 通行费电子普票：含入口/出口/车牌/路段。 */
export interface TollElecInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'toll_elec_normal';
  readonly plateNum: string | null;
  readonly entry: string | null;
  readonly exit: string | null;
  readonly route: string | null;
}

/** 机动车销售统一发票：车辆 / 合格证 / 限乘信息。 */
export interface MotorVehicleSaleInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'motor_vehicle_sale';
  readonly vehicleType: string | null;
  readonly model: string | null; // 厂牌型号
  readonly vin: string | null; // 车架号/VIN
  readonly engineNum: string | null;
  readonly certificateNum: string | null; // 合格证号
  readonly origin: string | null; // 产地
  readonly tonnage: string | null; // 吨位
  readonly passengers: string | null; // 限乘人数
  readonly purchaserIdNum: string | null; // 购方身份证/组织机构代码
  readonly taxAuthority: string | null;
}

/** 二手车销售统一发票：转出/转入与经营单位。 */
export interface UsedVehicleSaleInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'used_vehicle_sale';
  readonly vehicleType: string | null;
  readonly plateNum: string | null;
  readonly market: string | null; // 二手车市场
  readonly transferOut: string | null; // 转出方
  readonly transferIn: string | null; // 转入方
}

/** 区块链发票：含链上标识。 */
export interface BlockchainInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'blockchain';
  readonly blockChainId: string | null;
}

/** 通用机打电子发票（vat_invoice 票种，非 `invoice` 端点）。 */
export interface PrintedElecInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'printed_elec';
  readonly machineNum: string | null;
  readonly province: string | null;
  readonly city: string | null;
}

/** 电子发票（铁路电子客票）：乘客 + 车次 + 起讫。 */
export interface RailwayElecInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'railway_elec';
  readonly passengerName: string | null;
  readonly idNum: string | null;
  readonly trainNum: string | null;
  readonly startingStation: string | null;
  readonly destinationStation: string | null;
  readonly travelDate: string | null;
  readonly seatCategory: string | null;
  readonly seatNum: string | null;
  readonly elecTicketNum: string | null;
}

/** 电子发票（航空电子客票行程单）：多航段。 */
export interface AirElecItineraryInvoiceDocument extends InvoiceBase {
  readonly invoiceKind: 'air_elec_itinerary';
  readonly passengerName: string | null;
  readonly idNum: string | null;
  readonly carrier: string | null;
  readonly ticketNumber: string | null;
  readonly flights: ReadonlyArray<AirFlight>;
}

export type InvoiceDocument =
  | NormalVatInvoiceDocument
  | SpecialVatInvoiceDocument
  | RollVatInvoiceDocument
  | TollElecInvoiceDocument
  | MotorVehicleSaleInvoiceDocument
  | UsedVehicleSaleInvoiceDocument
  | BlockchainInvoiceDocument
  | PrintedElecInvoiceDocument
  | RailwayElecInvoiceDocument
  | AirElecItineraryInvoiceDocument;

export interface MachineInvoiceDocument extends DocumentBase {
  readonly kind: 'machine_invoice';
  readonly invoiceType: string | null;
  readonly invoiceCode: string | null;
  readonly invoiceNum: string | null;
  readonly invoiceDate: string | null;
  readonly amountFen: Fen | null; // 合计金额小写
  readonly totalTaxFen: Fen | null;
  readonly sellerName: string | null;
  readonly purchaserName: string | null;
  readonly province: string | null;
  readonly city: string | null;
  readonly items: ReadonlyArray<GoodsLine>;
}

export interface QuotaInvoiceDocument extends DocumentBase {
  readonly kind: 'quota_invoice';
  readonly invoiceCode: string | null;
  readonly invoiceNumber: string | null;
  readonly amountInWords: string | null;
  readonly amountFen: Fen | null;
  readonly location: string | null;
  readonly province: string | null;
  readonly city: string | null;
}

// ── 交通：行程 / 车次 / 航班 ────────────────────────────────────────
export interface OnlineTaxiTrip {
  readonly itemId: string | null;
  readonly provider: string | null; // item_provider
  readonly pickupDate: string | null;
  readonly pickupTime: string | null;
  readonly carType: string | null;
  readonly distance: string | null;
  readonly city: string | null;
  readonly startPlace: string | null;
  readonly destinationPlace: string | null;
  readonly fareFen: Fen | null;
}

export interface OnlineTaxiItineraryDocument extends DocumentBase {
  readonly kind: 'online_taxi_itinerary';
  readonly serviceProvider: string | null;
  readonly startTime: string | null;
  readonly endTime: string | null;
  readonly phone: string | null;
  readonly applicationDate: string | null;
  readonly totalFareFen: Fen | null;
  readonly trips: ReadonlyArray<OnlineTaxiTrip>;
}

export interface TaxiReceiptDocument extends DocumentBase {
  readonly kind: 'taxi_receipt';
  readonly invoiceCode: string | null;
  readonly invoiceNum: string | null;
  readonly taxiNum: string | null; // 车牌
  readonly date: string | null;
  readonly time: string | null;
  readonly pickupTime: string | null;
  readonly dropoffTime: string | null;
  readonly fareFen: Fen | null;
  readonly fuelSurchargeFen: Fen | null;
  readonly callServiceSurchargeFen: Fen | null;
  readonly totalFareFen: Fen | null;
  readonly location: string | null;
  readonly province: string | null;
  readonly city: string | null;
  readonly pricePerKm: string | null;
  readonly distance: string | null;
}

export interface TrainTicketDocument extends DocumentBase {
  readonly kind: 'train_ticket';
  readonly ticketNum: string | null;
  readonly trainNum: string | null;
  readonly startingStation: string | null;
  readonly destinationStation: string | null;
  readonly date: string | null;
  readonly time: string | null;
  readonly seatCategory: string | null;
  readonly seatNum: string | null;
  readonly passengerName: string | null;
  readonly idNum: string | null;
  readonly salesStation: string | null;
  readonly invoiceItems: ReadonlyArray<string>; // 票价/退票费/改签费
  readonly ticketRates: ReadonlyArray<string>;
  readonly invoiceNum: string | null; // 电子客票
  readonly invoiceDate: string | null;
  readonly fareFen: Fen | null;
  readonly taxFen: Fen | null;
  readonly taxRate: string | null;
  readonly elecTicketNum: string | null;
  readonly purchaserName: string | null;
}

export interface AirFlight {
  readonly flight: string | null;
  readonly startingStation: string | null;
  readonly destinationStation: string | null;
  readonly date: string | null;
  readonly time: string | null;
  readonly class: string | null;
  readonly fareBasis: string | null;
  readonly fareFen: Fen | null;
}

export interface AirTicketDocument extends DocumentBase {
  readonly kind: 'air_ticket';
  readonly passengerName: string | null;
  readonly idNum: string | null;
  readonly ticketNumber: string | null; // 电子客票号
  readonly serialNumber: string | null; // 印刷序号
  readonly carrier: string | null;
  readonly issuedDate: string | null;
  readonly totalFen: Fen | null; // 合计金额 ticket_rates
  readonly devFundFen: Fen | null;
  readonly fuelSurchargeFen: Fen | null;
  readonly otherTaxFen: Fen | null;
  readonly insuranceFen: Fen | null;
  readonly flights: ReadonlyArray<AirFlight>; // multi_detect 多航班
}

export interface BusTicketDocument extends DocumentBase {
  readonly kind: 'bus_ticket';
  readonly invoiceCode: string | null;
  readonly invoiceNum: string | null;
  readonly exitStation: string | null;
  readonly arrivalStation: string | null;
  readonly date: string | null;
  readonly time: string | null;
  readonly amountFen: Fen | null;
  readonly passengerName: string | null;
  readonly idCard: string | null;
  readonly invoiceTime: string | null;
}

export interface TollInvoiceDocument extends DocumentBase {
  readonly kind: 'toll_invoice';
  readonly invoiceCode: string | null;
  readonly invoiceNum: string | null;
  readonly entrance: string | null;
  readonly exit: string | null;
  readonly date: string | null;
  readonly time: string | null;
  readonly amountFen: Fen | null;
  readonly province: string | null;
  readonly city: string | null;
}

export interface FerryTicketDocument extends DocumentBase {
  readonly kind: 'ferry_ticket';
  readonly invoiceType: string | null;
  readonly invoiceCode: string | null;
  readonly invoiceNum: string | null;
  readonly exitStation: string | null;
  readonly arrivalStation: string | null;
  readonly amountFen: Fen | null;
  readonly date: string | null;
}

// ── 消费 / 银行 ────────────────────────────────────────────────────
export interface ReceiptLine {
  readonly product: string | null;
  readonly quantity: string | null;
  readonly unitPriceFen: Fen | null;
  readonly subtotalFen: Fen | null;
}

export interface ShoppingReceiptDocument extends DocumentBase {
  readonly kind: 'shopping_receipt';
  readonly shopName: string | null;
  readonly receiptNum: string | null;
  readonly machineNum: string | null;
  readonly employeeNum: string | null;
  readonly consumptionDate: string | null;
  readonly consumptionTime: string | null;
  readonly totalFen: Fen | null;
  readonly paidFen: Fen | null;
  readonly changeFen: Fen | null;
  readonly discount: string | null;
  readonly currency: string | null;
  readonly printDate: string | null;
  readonly lines: ReadonlyArray<ReceiptLine>;
}

export interface BankReceiptDocument extends DocumentBase {
  readonly kind: 'bank_receipt';
  readonly title: string | null;
  readonly payerName: string | null;
  readonly payerBank: string | null;
  readonly payerAccount: string | null;
  readonly payeeName: string | null;
  readonly payeeBank: string | null;
  readonly payeeAccount: string | null;
  readonly amountInWords: string | null;
  readonly amountFen: Fen | null; // 小写金额
  readonly serialNo: string | null; // 流水号
  readonly receiptNo: string | null; // 回单编号
  readonly tradeDate: string | null;
  readonly summary: string | null;
  readonly purpose: string | null;
}

/** 未知 / 仅分类（限额度、POS、其他）：只留 type 与位置，不猜内容。 */
export interface OtherDocument extends DocumentBase {
  readonly kind: 'other';
  readonly maybeKind: string | null; // limit_invoice / pos_invoice / shopping_receipt(仅分类) …
  readonly box: { left: number; top: number; width: number; height: number } | null;
}

/** 判别联合：按 kind 收窄到各自结构。 */
export type RecognizedDocument =
  | InvoiceDocument // 发票：再按 invoiceKind 收窄（专票/普票/卷票/全电/通行费/货运/机动车/铁路/航空…）
  | MachineInvoiceDocument
  | QuotaInvoiceDocument
  | OnlineTaxiItineraryDocument
  | TaxiReceiptDocument
  | TrainTicketDocument
  | AirTicketDocument
  | BusTicketDocument
  | TollInvoiceDocument
  | FerryTicketDocument
  | ShoppingReceiptDocument
  | BankReceiptDocument
  | OtherDocument;

// ── 统一投影：存储/匹配/列表等通用逻辑只看它（由各类型派生，不替代类型）──
export interface DocumentSummary {
  readonly kind: DocumentKind;
  readonly invoiceKind: InvoiceKind | null; // 仅发票有值
  readonly docNo: string | null;
  readonly issuedDate: string | null;
  readonly amountFen: Fen | null;
  readonly taxFen: Fen | null;
  readonly province: string | null;
  readonly city: string | null;
  readonly issuerName: string | null;
  readonly holderName: string | null;
  /** 匹配锚点：主金额 + 各明细金额（分），去重。 */
  readonly anchorAmountsFen: ReadonlyArray<Fen>;
}

enum ReceiptKind {                 // 非发票文档种类（发票走 Invoice）
  machine_invoice quota_invoice
  online_taxi_itinerary train_ticket taxi_receipt air_ticket
  bus_ticket toll_invoice ferry_ticket
  vehicle_sale_invoice used_vehicle_invoice
  shopping_receipt bank_receipt other
}

enum InvoiceKind {                 // 发票票种（§2.4）
  special_vat elec_special_vat normal_vat elec_normal_vat roll_normal_vat
  elec_invoice_special elec_invoice_normal toll_elec_normal freight_special
  motor_vehicle_sale used_vehicle_sale blockchain printed_elec
  railway_elec air_elec_itinerary
}

model Attachment {
  // ...既有字段...
  /// 端点的完整原始返回（红线 5：重放/重匹配不再付费）
  ocrRawJson   Json?
  /// 归一化 RecognizedDocument[]（混贴多张时多项，判别键 kind）
  documents    Json?
  /// 主文档种类（冗余 documents[0].kind，便于筛选/规则；发票时为 'vat_invoice'）
  receiptKind  ReceiptKind?
  @@index([workspaceId, receiptKind])
}

model Invoice {
  // ...既有字段：invoiceNum/invoiceCode/amountFen/... 保留，防重键与列表口径不变...
  /// 规范化票种（§2.4），筛选/规则/导出用
  invoiceKind  InvoiceKind?
  /// 票种专属字段（车辆信息/通行费起讫/铁路乘客…），按 invoiceKind 解释
  detail       Json?
}

export interface DocumentProvider {
  /** 一次分类 + 结构化 13 类财务票据（含混贴）；无则空数组。 */
  recognizeFinancialDocuments(input: ProviderInput): Promise<RecognizedDocument[]>;
  /** 单类型专用端点（精度更高 / 兜底 multiple_invoice 的“其他”）。 */
  recognizeDocument(kind: DocumentKind, input: ProviderInput): Promise<RecognizedDocument | null>;
  /** 通用全文，最终兜底（沿用）。 */
  recognizeText(input: ProviderInput): Promise<string>;
  /** 增值税主票（沿用）。 */
  parse(input: ProviderInput): Promise<StandardInvoice>;
}

// packages/providers/src/baidu/financial/registry.ts
interface EndpointSpec {
  readonly url: string;
  readonly docKind: DocumentKind;
  readonly map: (words: Record<string, unknown>) => RecognizedDocument;
}
export const BAIDU_FINANCIAL_ENDPOINTS: Record<DocumentKind, EndpointSpec>;

parse job
  ▼
vat_invoice（保留首选：主票字段最全 + 组织级防重键依赖）
  ├─ 命中 → invoice 主票（现状不变）
  └─ 282103 → 附件子管道
        ▼
      multiple_invoice（分类 + 结构化；混贴 → RecognizedDocument[]）
        ├─ type 可结构化（火车/机票/网约车/出租车/汽车/过路/机打/定额/增值税…）
        │     → 归一化 → 落 Attachment.documents / ocrRawJson / receiptKind
        │     → 金额锚点（主金额 + 各行金额）参与匹配（口径见 §7）
        └─ type ∈ {others, shopping_receipt, pos_invoice, limit_invoice}
              → 调专用端点（shopping_receipt / bank_receipt_new）或退 general_basic
        ▼
      （兜底）general_basic → 全文 → 现有 core/matcher（保证“无锚点不猜”仍可用）