@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/ts/capabilities/session/adapters/ctrip-flight.ts

@@ -56,52 +56,115 @@ export interface SessionFlightOption {
   aircraft?: string
 }
 
-interface RawBatch {
-  status?: number
-  data?: {
-    flightItineraryList?: Array<{
-      flightSegments?: Array<{
-        airlineName?: string
-        duration?: number
-        flightList?: Array<{
-          flightNo?: string
-          departureAirportName?: string
-          arrivalAirportName?: string
-          departureDateTime?: string
-          arrivalDateTime?: string
-          aircraftName?: string
-        }>
-      }>
-      priceList?: Array<{ adultPrice?: number }>
-    }>
-  }
+/** 解析结果的三态判语(issue #279):空响应不再一律 miss——已识别合法空 = miss,
+ * 形状未识别(malformed/unknown)= error,选项命中 = hit。误把任意 [] 判 miss 会把未知
+ * 响应错误收敛为「这条线路没有航班」,这是上游接口改版/协议变动期的常见陷阱 */
+export type BatchSearchVerdict = 'hit' | 'miss' | 'error'
+
+export interface BatchSearchResult {
+  options: SessionFlightOption[]
+  verdict: BatchSearchVerdict
+}
+
+/** 安全取字符串字段(任意来源字段都可能是 null/undefined/数字/对象) */
+function asString(v: unknown): string {
+  return typeof v === 'string' ? v : ''
+}
+
+/** 安全取正数(无法解析按 0 返,绝不伪造价格) */
+function asPositiveNumber(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0
 }
 
 /** 解析 batchSearch 响应(纯函数,fixture 测试锚点);malformed 一律返空,不抛错 */
 export function parseBatchSearch(body: string): SessionFlightOption[] {
-  let raw: RawBatch
+  return parseBatchSearchResult(body).options
+}
+
+/**
+ * 结构化解析(issue #279):返回选项 + 三态判语。
+ *   - `hit`  = 已识别合法结构 + 至少一个有效行程
+ *   - `miss` = 已识别合法空(data.flightItineraryList 是空数组)
+ *   - `error`= 形状未识别(JSON 解析失败 / 非对象根 / data 缺失或非对象 /
+ *              flightItineraryList 不是数组 / 非空数组没有可用行程)——未知响应
+ *              不可静默收敛为 miss
+ * 绝不发明价格、航班号、机场、时刻;混合数组保留有效项,全畸形数组报 error。
+ */
+export function parseBatchSearchResult(body: string): BatchSearchResult {
+  let raw: unknown
   try {
-    raw = JSON.parse(body) as RawBatch
+    raw = JSON.parse(body)
   } catch {
-    return []
+    return { options: [], verdict: 'error' }
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { options: [], verdict: 'error' }
+  }
+  const data = (raw as { data?: unknown }).data
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    return { options: [], verdict: 'error' }
+  }
+  const list = (raw as { data: { flightItineraryList?: unknown } }).data.flightItineraryList
+  if (!Array.isArray(list)) {
+    return { options: [], verdict: 'error' }
   }
   const out: SessionFlightOption[] = []
-  for (const it of raw.data?.flightItineraryList ?? []) {
-    const seg = it.flightSegments?.[0]
-    const fl = seg?.flightList?.[0]
-    if (!fl?.flightNo || !fl.departureDateTime) continue
-    const prices = (it.priceList ?? []).map((p) => Number(p.adultPrice ?? 0)).filter((n) => n > 0)
+  for (const it of list) {
+    if (it === null || typeof it !== 'object' || Array.isArray(it)) continue
+    const item = it as { flightSegments?: unknown; priceList?: unknown }
+    const segs = item.flightSegments
+    if (!Array.isArray(segs) || segs.length === 0) continue
+    const seg = segs[0]
+    if (seg === null || typeof seg !== 'object' || Array.isArray(seg)) continue
+    const segObj = seg as { airlineName?: unknown; duration?: unknown; flightList?: unknown }
+    const fl = segObj.flightList
+    if (!Array.isArray(fl) || fl.length === 0) continue
+    const flight = fl[0]
+    if (flight === null || typeof flight !== 'object' || Array.isArray(flight)) continue
+    const f = flight as {
+      flightNo?: unknown
+      departureAirportName?: unknown
+      arrivalAirportName?: unknown
+      departureDateTime?: unknown
+      arrivalDateTime?: unknown
+      aircraftName?: unknown
+    }
+    if (typeof f.flightNo !== 'string' || !f.flightNo) continue
+    if (typeof f.departureDateTime !== 'string' || !f.departureDateTime) continue
+    // 缺 priceList 延续旧合同为「有航班、价格未知」;显式非数组与畸形价项
+    // 属未知响应,整项跳过。若响应里没有其他有效项,最终判 error 而非 miss。
+    if (item.priceList !== undefined && !Array.isArray(item.priceList)) continue
+    const priceList = item.priceList ?? []
+    const prices: number[] = []
+    let malformedPrice = false
+    for (const p of priceList) {
+      if (p === null || typeof p !== 'object' || Array.isArray(p)) {
+        malformedPrice = true
+        break
+      }
+      const adultPrice = (p as { adultPrice?: unknown }).adultPrice
+      if (adultPrice === undefined) continue
+      if (typeof adultPrice !== 'number' || !Number.isFinite(adultPrice)) {
+        malformedPrice = true
+        break
+      }
+      if (adultPrice > 0) prices.push(adultPrice)
+    }
+    if (malformedPrice) continue
     out.push({
-      flightNo: fl.flightNo,
-      airline: seg?.airlineName ?? '',
-      depDateTime: fl.departureDateTime ?? '',
-      arrDateTime: fl.arrivalDateTime ?? '',
-      depAirport: fl.departureAirportName ?? '',
-      arrAirport: fl.arrivalAirportName ?? '',
-      durationMin: Number(seg?.duration ?? 0) || 0,
+      flightNo: f.flightNo,
+      airline: asString(segObj.airlineName),
+      depDateTime: asString(f.departureDateTime),
+      arrDateTime: asString(f.arrivalDateTime),
+      depAirport: asString(f.departureAirportName),
+      arrAirport: asString(f.arrivalAirportName),
+      durationMin: asPositiveNumber(segObj.duration),
       price: prices.length > 0 ? Math.min(...prices) : 0,
-      aircraft: fl.aircraftName,
+      aircraft: typeof f.aircraftName === 'string' ? f.aircraftName : undefined,
     })
   }
-  return out
+  return {
+    options: out,
+    verdict: out.length > 0 ? 'hit' : list.length === 0 ? 'miss' : 'error',
+  }
 }

package/ts/capabilities/session/adapters/dida-portal.ts

@@ -0,0 +1,250 @@
+/**
+ * Dida 供应商门户站点适配器(2026-09-09 实装;hotel-be portal integration 迁移线:
+ * 员工子账号免知凭据访问供应商 portal——登录经 hotel-be portal 自动填充跳板在
+ * dida 官网由人完成,gotry 只在用户本人 Chrome 登录态里被动嗅探检索回包)。
+ *
+ *   - entry:https://portal.dida.com/hotel/find(SPA,页内交互触发检索;深链参数
+ *     形态未知——D-13 同款边界,首个真会话后校准)
+ *   - networkHints:portal-webapi.dida.com 实时价/价格监控 XHR(接口名取自
+ *     hotel-be supplier/integration/dida/portal 已捕获端点,2026-07 抓包校准);
+ *     URL hint 未命中时由 content-main 的形状嗅探兜底(响应 JSON 含报价签名即
+ *     转发),对接口改名免疫
+ *   - 解析:SearchRealTime 信封(Envelope{Data.HotelPriceList[].RoomTypeList[]
+ *     .RatePlanList[]})逐报价展平;SearchMonitor 响应形状未捕获前不猜测——
+ *     只按 URL 命中转发、解析留给首个真会话校准(D-13)
+ *
+ * 只读:适配器不含任何提交/预订语义;预订面(PriceConfirm 等)URL 属 hotel-be
+ * 适配器边界,gotry 侧不存在对应原语;登录语义红线同全局:gotry 永不读取/存储/
+ * 回传 cookie 值,只读票据 cookie 名(CN_M_DidaTravel)存在性。
+ */
+
+/** 票据 cookie 名(hotel-be portal 会话同款 HttpOnly cookie;只读名字,永不读值) */
+export const DIDA_LOGIN_COOKIE_NAMES = ['CN_M_DidaTravel']
+
+/** page 域(content_scripts 注入面与 background 白名单的对账源) */
+export const DIDA_SITE_HOST = 'portal.dida.com'
+/** cookie 域(chrome.cookies 过滤器与登录票据检查;did a 站点 cookie 挂 .dida.com 域 cookie) */
+export const DIDA_SITE_DOMAIN = 'dida.com'
+
+/** 默认检索入口(酒店 find 页;SPA 加载后由页面自身代码发起价格检索) */
+export const DIDA_ENTRY_URL = 'https://portal.dida.com/hotel/find'
+
+export interface DidaEntry {
+  ok: boolean
+  url?: string
+}
+
+export interface DidaEntryQuery {
+  /** 显式覆盖入口 URL(深链参数校准后使用;必须落在 portal.dida.com 域内) */
+  entryUrl?: string
+}
+
+/** entry 构造(v1:固定 find 页 + 显式覆盖守白名单域;URL 直开即零 DOM 交互) */
+export function buildDidaEntryUrl(q: DidaEntryQuery = {}): DidaEntry {
+  const url = (q.entryUrl ?? '').trim() || DIDA_ENTRY_URL
+  if (!/^https:\/\/portal\.dida\.com\//.test(url)) return { ok: false }
+  return { ok: true, url }
+}
+
+/** networkHints:portal-webapi.dida.com 实时价/价格监控 XHR(2026-07 抓包口径;
+ * 首个真会话后按现行接口校准——D-13 同款边界) */
+export const DIDA_NETWORK_HINTS = [
+  /portal-webapi\.dida\.com\/HotelPriceAPI\/SearchRealTime/i,
+  /portal-webapi\.dida\.com\/HotelPriceAPI\/SearchMonitor/i,
+  // 2026-09-10 UAT 实测校准:find 页加载态自发的是推荐流(非 SearchRealTime——
+  // 那是用户点「预订」后的实时价接口)。推荐酒店 + 推荐价格两个接口成对出现。
+  /portal-webapi\.dida\.com\/HotelRecommendAPI\/SearchHomepageRecommendHotels/i,
+  /portal-webapi\.dida\.com\/HotelRecommendAPI\/SearchHomepageRecommendPrices/i,
+  /portal-webapi\.dida\.com\/PopularDestinationAPI\/SearchHotels/i,
+  /portal-webapi\.dida\.com\/PopularDestinationAPI\/SearchHotelPrices/i,
+]
+
+/** 形状嗅探签名:URL hint 未命中时的兜底(实时价信封报价签名,对接口改名免疫);
+ * 大小上限由调用方先把关 */
+export function looksLikeDidaRatesBody(body: string): boolean {
+  if (!body || body.length > 2_000_000) return false
+  return /"HotelPriceList"|"RatePlanList"/.test(body)
+}
+
+// ── 现行加载态接口(2026-09-10 校准):推荐酒店 + 推荐价格 ──────────────────
+
+export interface DidaRecommendHotel {
+  hotelId: string
+  name: string
+  nameEN?: string
+}
+
+/** 解析推荐酒店列表(Data.Hotels[]:HotelID/Name/Name_CN/Name_EN;Current 页加载态无价) */
+export function parseDidaRecommendHotels(body: string, opts: { maxItems?: number } = {}): DidaRecommendHotel[] {
+  let raw: unknown
+  try { raw = JSON.parse(body) } catch { return [] }
+  const hotels = (raw as { Data?: { Hotels?: unknown } })?.Data?.Hotels
+  if (!Array.isArray(hotels)) return []
+  const out: DidaRecommendHotel[] = []
+  for (const item of hotels.slice(0, opts.maxItems ?? 60)) {
+    if (item == null || typeof item !== 'object') continue
+    const h = item as Record<string, unknown>
+    const hotelId = h.HotelID != null ? String(h.HotelID) : ''
+    const name = typeof h.Name_CN === 'string' && h.Name_CN.trim() ? h.Name_CN : (typeof h.Name === 'string' ? h.Name : '')
+    if (!hotelId || !name) continue
+    out.push({ hotelId, name, nameEN: typeof h.Name_EN === 'string' ? h.Name_EN : undefined })
+  }
+  return out
+}
+
+export interface DidaPriceEntry {
+  hotelId: string
+  price: number
+  originalPrice?: number
+  currency?: string
+  /** 单晚起始价对应日期(YYYY-MM-DD) */
+  priceDate?: string
+  checkInDate?: string
+  checkOutDate?: string
+}
+
+// (parser types continue below)
+
+/** 解析价格列表:兼容 Recommend Prices(HotelId/Date)与 PopularDestination(HotelID/CheckInDate)两种键形 */
+export function parseDidaPrices(body: string): DidaPriceEntry[] {
+  let raw: unknown
+  try { raw = JSON.parse(body) } catch { return [] }
+  const prices = (raw as { Data?: { Prices?: unknown } })?.Data?.Prices
+  if (!Array.isArray(prices)) return []
+  const out: DidaPriceEntry[] = []
+  for (const item of prices) {
+    if (item == null || typeof item !== 'object') continue
+    const p = item as Record<string, unknown>
+    const hotelId = p.HotelId != null ? String(p.HotelId) : (p.HotelID != null ? String(p.HotelID) : '')
+    const price = typeof p.Price === 'number' ? p.Price : NaN
+    if (!hotelId || !Number.isFinite(price) || price <= 0) continue
+    const dateOf = (v: unknown): string | undefined => (typeof v === 'string' && v.length >= 10 ? v.slice(0, 10) : undefined)
+    out.push({
+      hotelId,
+      price,
+      originalPrice: typeof p.OriginalPrice === 'number' ? p.OriginalPrice : undefined,
+      currency: typeof p.Currency === 'string' ? p.Currency : undefined,
+      priceDate: dateOf(p.Date),
+      checkInDate: dateOf(p.CheckInDate),
+      checkOutDate: dateOf(p.CheckOutDate),
+    })
+  }
+  return out
+}
+
+/** 单条报价(一房一价一计划;语义判定在工具层,本层只归形状——页面 JSON 是不可信输入) */
+export interface SessionDidaRateOption {
+  hotelId?: string
+  hotelName?: string
+  roomTypeId?: string
+  roomName?: string
+  ratePlanId?: string
+  /** 单价(数值不可得时为 0) */
+  price: number
+  /** 总价(含税费口径以 dida 页面为准) */
+  totalPrice?: number
+  currency?: string
+  mealType?: string
+  breakfastType?: string
+  bedType?: string
+  paymentType?: string
+  /** 库存/可订间数(0=未给) */
+  inventory?: number
+  /** 检索续期令牌(dida 报价引用号;服务端预订链凭此续操作) */
+  referenceNo?: string
+  /** 酒店详情落地页(由人完成预订;gotry 不碰) */
+  jumpUrl?: string
+  /** 推荐价对应日期(YYYY-MM-DD;推荐流单晚起始价) */
+  priceDate?: string
+}
+
+interface RateCandidate {
+  hotelId?: string
+  hotelName?: string
+  roomTypeId?: string
+  roomName?: string
+  plan: Record<string, unknown>
+}
+
+/** 从 RoomTypePrice 展平一条报价候选(RatePlanList 元素为 dida 已知形态);
+ * 酒店字段取 HotelPriceItem.Hotel 嵌套(HotelStatic),容忍旧式扁平形态 */
+function rateCandidate(hotel: Record<string, unknown>, room: Record<string, unknown>, plan: Record<string, unknown>): RateCandidate | null {
+  if (plan == null || typeof plan !== 'object') return null
+  const ratePlanId = plan.RatePlanID
+  const price = plan.Price
+  const totalPrice = plan.TotalPrice
+  if (typeof ratePlanId !== 'string' || !ratePlanId.trim()) return null
+  if (typeof price !== 'number' && typeof totalPrice !== 'number') return null
+  const hotelStatic = (hotel.Hotel != null && typeof hotel.Hotel === 'object' ? hotel.Hotel : hotel) as Record<string, unknown>
+  const hotelId = hotelStatic.HotelID
+  const roomTypeId = room.DidaRoomTypeID
+  return {
+    hotelId: hotelId != null ? String(hotelId) : undefined,
+    hotelName: typeof hotelStatic.Name === 'string' ? hotelStatic.Name : undefined,
+    roomTypeId: roomTypeId != null ? String(roomTypeId) : undefined,
+    roomName: typeof room.DidaRoomTypeName_CN === 'string' && room.DidaRoomTypeName_CN.trim()
+      ? room.DidaRoomTypeName_CN
+      : (typeof room.DidaRoomTypeName_EN === 'string' ? room.DidaRoomTypeName_EN : undefined),
+    plan,
+  }
+}
+
+/** 走形:SearchRealTime 信封 → 展平报价列表(纯函数,fixture 测试锚点);
+ * malformed 一律返空,不抛错——页面/接口 JSON 是不可信输入(RFC §3.5) */
+export function parseDidaRates(body: string, opts: { maxItems?: number } = {}): SessionDidaRateOption[] {
+  let raw: unknown
+  try {
+    raw = JSON.parse(body)
+  } catch {
+    return []
+  }
+  const maxItems = opts.maxItems ?? 40
+  const out: SessionDidaRateOption[] = []
+  // 定位 HotelPriceList:信封顶层 Data 下;无信封时容忍裸数组形态
+  let hotelList: unknown
+  if (raw != null && typeof raw === 'object' && !Array.isArray(raw)) {
+    const data = (raw as Record<string, unknown>).Data
+    if (data != null && typeof data === 'object') hotelList = (data as Record<string, unknown>).HotelPriceList
+  } else if (Array.isArray(raw)) {
+    hotelList = raw
+  }
+  if (!Array.isArray(hotelList)) return out
+  for (const item of hotelList) {
+    if (out.length >= maxItems || item == null || typeof item !== 'object') continue
+    const hotel = item as Record<string, unknown>
+    // RoomTypeList 与 RoomList 是合并关系(hotel-be converter 两表都吃),不是二选一
+    const rooms = [
+      ...(Array.isArray(hotel.RoomTypeList) ? hotel.RoomTypeList : []),
+      ...(Array.isArray(hotel.RoomList) ? hotel.RoomList : []),
+    ]
+    for (const room of rooms) {
+      if (out.length >= maxItems || room == null || typeof room !== 'object') continue
+      const plans = (room as Record<string, unknown>).RatePlanList
+      if (!Array.isArray(plans)) continue
+      for (const plan of plans) {
+        if (out.length >= maxItems) return out
+        const cand = rateCandidate(hotel, room as Record<string, unknown>, plan as Record<string, unknown>)
+        if (!cand) continue
+        const p = cand.plan
+        out.push({
+          hotelId: cand.hotelId,
+          hotelName: cand.hotelName,
+          roomTypeId: cand.roomTypeId,
+          roomName: cand.roomName,
+          ratePlanId: typeof p.RatePlanID === 'string' ? p.RatePlanID : undefined,
+          price: typeof p.Price === 'number' ? p.Price : 0,
+          totalPrice: typeof p.TotalPrice === 'number' ? p.TotalPrice : undefined,
+          currency: typeof p.Currency === 'string' ? p.Currency : undefined,
+          mealType: typeof p.MealType === 'string' ? p.MealType : undefined,
+          breakfastType: typeof p.BreakfastType === 'string' ? p.BreakfastType : undefined,
+          bedType: typeof p.BedType === 'string' ? p.BedType : undefined,
+          paymentType: typeof p.PaymentType === 'string' ? p.PaymentType : undefined,
+          inventory: typeof p.Inventory === 'number' ? p.Inventory : (typeof p.RoomCount === 'number' ? p.RoomCount : undefined),
+          referenceNo: typeof p.ReferenceNo === 'string' ? p.ReferenceNo : undefined,
+          jumpUrl: cand.hotelId ? `https://portal.dida.com/hotel/find` : undefined,
+        })
+      }
+    }
+  }
+  return out
+}

package/ts/capabilities/session/adapters/rail-12306.ts

@@ -169,15 +169,63 @@ export interface AdapterEntry {
   unresolved?: string[]
 }
 
-export function buildTrainEntryUrl(q: TrainEntryQuery): AdapterEntry {
+export interface TrainQueryTelecodes {
+  fromStationTelecode: string
+  toStationTelecode: string
+  date: string
+}
+
+export interface TrainResponseBinding extends TrainQueryTelecodes {
+  /** Exact URL observed on the response whose body was parsed. */
+  url: string
+}
+
+export type TrainResponseUrlValidation =
+  | { ok: true; binding: TrainResponseBinding }
+  | { ok: false; reason: string }
+
+export function resolveTrainQueryTelecodes(q: TrainEntryQuery): { ok: true; telecodes: TrainQueryTelecodes } | { ok: false; unresolved: string[] } {
   const unresolved: string[] = []
   const fromTc = (q.fromStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.from.trim()]
   const toTc = (q.toStationTelecode ?? '').trim().toUpperCase() || STATION_TELECODES[q.to.trim()]
   if (!fromTc) unresolved.push(q.from)
   if (!toTc) unresolved.push(q.to)
-  if (unresolved.length > 0 || !/^\d{4}-\d{2}-\d{2}$/.test(q.date)) {
-    return { ok: false, unresolved: unresolved.length > 0 ? unresolved : [q.date] }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(q.date)) unresolved.push(q.date)
+  if (unresolved.length > 0 || !fromTc || !toTc) return { ok: false, unresolved }
+  return { ok: true, telecodes: { fromStationTelecode: fromTc, toStationTelecode: toTc, date: q.date } }
+}
+
+/** Bind a parsed body to the exact 12306 query request that this invocation built. */
+export function validateTrainQueryResponseUrl(observedUrl: string, expected: TrainQueryTelecodes): TrainResponseUrlValidation {
+  let parsed: URL
+  try {
+    parsed = new URL(observedUrl)
+  } catch {
+    return { ok: false, reason: 'response URL malformed' }
+  }
+  if (parsed.protocol !== 'https:' || parsed.hostname.toLowerCase() !== TRAIN_SITE_HOST || parsed.port) {
+    return { ok: false, reason: 'response URL host/protocol is not the 12306 HTTPS host' }
+  }
+  if (!/^\/otn\/leftTicket\/query[A-Za-z0-9_-]*$/i.test(parsed.pathname)
+    || !TRAIN_NETWORK_HINTS.some((hint) => hint.test(parsed.pathname))) {
+    return { ok: false, reason: 'response URL is not an allowed leftTicket query endpoint' }
   }
+  const exactParam = (name: string): string | undefined => {
+    const values = parsed.searchParams.getAll(name)
+    return values.length === 1 ? values[0] : undefined
+  }
+  if (exactParam('leftTicketDTO.train_date') !== expected.date
+    || exactParam('leftTicketDTO.from_station') !== expected.fromStationTelecode
+    || exactParam('leftTicketDTO.to_station') !== expected.toStationTelecode) {
+    return { ok: false, reason: 'response URL query route/date does not match the invocation' }
+  }
+  return { ok: true, binding: { url: observedUrl, ...expected } }
+}
+
+export function buildTrainEntryUrl(q: TrainEntryQuery): AdapterEntry {
+  const resolved = resolveTrainQueryTelecodes(q)
+  if (!resolved.ok) return { ok: false, unresolved: resolved.unresolved }
+  const { fromStationTelecode: fromTc, toStationTelecode: toTc } = resolved.telecodes
   const fs = encodeURIComponent(`${q.from.trim()},${fromTc}`)
   const ts = encodeURIComponent(`${q.to.trim()},${toTc}`)
   return { ok: true, url: `https://kyfw.12306.cn/otn/leftTicket/init?linktypeid=dc&fs=${fs}&ts=${ts}&date=${q.date}&flag=N,N,Y` }
@@ -199,6 +247,8 @@ export interface SessionTrainOption {
   arrTime: string
   /** 历时(分钟) */
   durationMin: number
+  /** 12306 train-origin date(YYYY-MM-DD);validated and preserved, not passenger query date */
+  startTrainDate?: string
   /** Y=可预订 / N=不可 / 其他上游原话 */
   canWebBuy: string
   /** 余票分桶(第一方校准索引,见 SEAT_BUCKETS;值原样:数字 / 有 / 无 / --) */
@@ -231,24 +281,56 @@ const SEAT_BUCKETS: Array<{ index: number; field: string; label: string }> = [
 const TRAIN_CODE_RE = /^[GDCZTKYLSF]\d{1,5}[A-Z]?$/i
 const HHMM_RE = /^\d{2}:\d{2}$/
 
+export const TRAIN_QUERY_PARSE_SCHEMA = 'gotry_session_train_parse.v1' as const
+
+export type TrainQueryParseOutcome =
+  | { kind: 'recognized-nonempty'; trains: SessionTrainOption[] }
+  | { kind: 'recognized-empty'; trains: [] }
+  | { kind: 'malformed'; reason: string }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
 /** 历时 "07:52" → 分钟 */
 function lishiToMin(s: string | undefined): number {
   const m = /^(\d{1,3}):(\d{2})$/.exec((s ?? '').trim())
   if (!m) return 0
+  if (Number(m[2]) > 59) return 0
   return Number(m[1]) * 60 + Number(m[2])
 }
 
+function normalizeStartTrainDate(value: string): string | undefined {
+  if (!/^\d{8}$/.test(value)) return undefined
+  const normalized = `${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}`
+  const parsed = new Date(`${normalized}T00:00:00.000Z`)
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== normalized) return undefined
+  return normalized
+}
+
 /** 行级签名:车次码形态 + 时刻形态不符即整行跳过(索引漂移 fail-visible,不造数) */
-function rowToOption(row: string, stationMap: Record<string, string> | undefined, entryUrl: string): SessionTrainOption | null {
+function rowToOption(row: string, stationMap: Record<string, unknown> | undefined, entryUrl: string): SessionTrainOption | null {
   const f = row.split('|')
   if (f.length < 34) return null
   const trainCode = (f[3] ?? '').trim()
   const depTime = (f[8] ?? '').trim()
   const arrTime = (f[9] ?? '').trim()
-  if (!TRAIN_CODE_RE.test(trainCode) || !HHMM_RE.test(depTime) || !HHMM_RE.test(arrTime)) return null
+  const durationMin = lishiToMin(f[10])
+  const startTrainDateRaw = (f[13] ?? '').trim()
+  const startTrainDate = normalizeStartTrainDate(startTrainDateRaw)
+  const validHm = (value: string): boolean => HHMM_RE.test(value)
+    && Number(value.slice(0, 2)) <= 23 && Number(value.slice(3, 5)) <= 59
+  if (!TRAIN_CODE_RE.test(trainCode) || !validHm(depTime) || !validHm(arrTime)
+    || durationMin <= 0 || !startTrainDate || !(f[6] ?? '').trim() || !(f[7] ?? '').trim()) return null
   // 官方 cN 口径:站名 = data.map[电报码](map 缺失/缺键时退电报码原样,不猜名)
-  const fromStation = stationMap?.[f[6] ?? ''] ?? (f[6] ?? '')
-  const toStation = stationMap?.[f[7] ?? ''] ?? (f[7] ?? '')
+  const stationName = (code: string): string | null => {
+    if (!stationMap || !Object.prototype.hasOwnProperty.call(stationMap, code)) return code
+    const mapped = stationMap[code]
+    return typeof mapped === 'string' && mapped.trim() ? mapped.trim() : null
+  }
+  const fromStation = stationName((f[6] ?? '').trim())
+  const toStation = stationName((f[7] ?? '').trim())
+  if (!fromStation || !toStation) return null
   const seats: Record<string, string> = {}
   for (const b of SEAT_BUCKETS) {
     const v = (f[b.index] ?? '').trim()
@@ -260,34 +342,51 @@ function rowToOption(row: string, stationMap: Record<string, string> | undefined
     toStation,
     depTime,
     arrTime,
-    durationMin: lishiToMin(f[10]),
+    durationMin,
+    startTrainDate,
     canWebBuy: (f[11] ?? '').trim(),
     seats,
     jumpUrl: entryUrl,
   }
 }
 
-/** 解析 leftTicket/query 响应(纯函数,fixture 测试锚点;字段索引与站名映射
- * 全部对齐 12306 官方前端 cN(result,map)——见 SEAT_BUCKETS 注释);
- * malformed 一律返空,不抛错 */
-export function parseLeftTicketQuery(body: string, entryUrl: string, opts: { maxItems?: number } = {}): SessionTrainOption[] {
-  let raw: { data?: { result?: unknown; map?: Record<string, string> } }
+/** 解析 leftTicket/query 响应的 typed outcome。
+ * recognized-empty 只代表明确存在的 data.result=[];
+ * recognized-nonempty 要求批次每一行都通过签名校验,任一畸形行即整个批次
+ * malformed,不暴露部分候选。transport/runtime failure 不在此纯解析函数伪造。
+ */
+export function parseLeftTicketQueryResult(body: string, entryUrl: string, opts: { maxItems?: number } = {}): TrainQueryParseOutcome {
+  let raw: unknown
   try {
-    raw = JSON.parse(body) as typeof raw
+    raw = JSON.parse(body) as unknown
   } catch {
-    return []
+    return { kind: 'malformed', reason: 'response body is not valid JSON' }
   }
-  const rows = raw.data?.result
-  if (!Array.isArray(rows)) return []
-  const map = (raw.data?.map && typeof raw.data.map === 'object') ? raw.data.map : undefined
+  if (!isRecord(raw) || !isRecord(raw.data)) return { kind: 'malformed', reason: 'response root/data is not an object' }
+  const rows = raw.data.result
+  if (!Array.isArray(rows)) return { kind: 'malformed', reason: 'data.result is not an array' }
+  if (raw.data.map !== undefined && !isRecord(raw.data.map)) {
+    return { kind: 'malformed', reason: 'data.map is not an object' }
+  }
+  if (rows.length === 0) return { kind: 'recognized-empty', trains: [] }
+  const map = raw.data.map as Record<string, unknown> | undefined
   const out: SessionTrainOption[] = []
   for (const r of rows) {
-    if (typeof r !== 'string') continue
+    if (typeof r !== 'string') return { kind: 'malformed', reason: 'data.result contains a non-string row' }
     const opt = rowToOption(r, map, entryUrl)
-    if (opt) {
-      out.push(opt)
-      if (out.length >= (opts.maxItems ?? 30)) break
-    }
+    if (!opt) return { kind: 'malformed', reason: 'data.result contains a malformed or unrecognized row' }
+    if (out.length < (opts.maxItems ?? 30)) out.push(opt)
   }
-  return out
+  return { kind: 'recognized-nonempty', trains: out }
+}
+
+/** 兼容旧调用方:typed outcome 之外仍保留旧的数组投影,错误与 genuine empty 均为 []。 */
+export function parseLeftTicketQuery(body: string, entryUrl: string, opts: { maxItems?: number } = {}): SessionTrainOption[] {
+  const outcome = parseLeftTicketQueryResult(body, entryUrl, opts)
+  return outcome.kind === 'recognized-nonempty' ? outcome.trains : []
+}
+
+/** Positive availability is deliberately a small closed set, not canWebBuy alone. */
+export function hasRecognizedAvailableSeat(option: SessionTrainOption): boolean {
+  return Object.values(option.seats).some(value => value === '有' || /^[1-9]\d*$/.test(value))
 }