@tbox.cn/app-contracts-mall 0.2.0 → 0.9.0

package/src/service-slots.json

@@ -0,0 +1,23 @@
+{
+  "$comment": "mall 域 service slot 词汇唯一真源。共址 TS 常量并集必须与本文件 slots 逐元素相等（tests/service-slots.test.ts 锁）；manifest demand/supply ⊆ slots（scripts/guard-service-slots.mjs 锁）。旧词汇不在此——迁移归 cookbook 配方。",
+  "slots": [
+    "member.account",
+    "member.profile",
+    "member.card",
+    "member.benefits",
+    "member.enrollment",
+    "parking.query",
+    "parking.payment",
+    "parking.vehicle",
+    "promotion.offers",
+    "promotion.entitlements",
+    "promotion.activities",
+    "promotion.acquisition",
+    "shopping-guide.catalog",
+    "shopping-guide.shops",
+    "shopping-guide.categories",
+    "shopping-guide.directory",
+    "auth.alipay-login",
+    "mall.info"
+  ]
+}

package/src/services/customer-service.ts

@@ -0,0 +1,12 @@
+/**
+ * 客服承接域 Port 契约（2026-08-31 客服模块拆分：自 shopping-guide AssistanceQueryPort
+ * 切出 FAQ/知识库两方法；人工导购 listHumanGuides 留导购域 AssistanceQueryPort）。
+ * 客服承接 = 本地知识库域（与 provider 远程检索面正交，恒本地装配）。
+ */
+import type { ShoppingQueryContext } from './shopping-guide';
+import type { FaqEntry, KnowledgeEntry } from '../domain/shopping-guide';
+
+export interface CustomerServiceQueryPort {
+  searchFaq(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly FaqEntry[]>;
+  searchKnowledge(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly KnowledgeEntry[]>;
+}

package/src/services/mall-info.ts

@@ -0,0 +1,31 @@
+/**
+ * 商场基础信息 Port（mall.info 槽服务契约；动态商场信息源）。
+ * 厂商 wire 词汇（如厂商侧 plaza 端点词）不进本层——投影后只余平台词汇。
+ * 结构类型子集接口——消费方（模板装配点/模块）仅依赖契约包。
+ */
+
+// ===== mall.info service slot 词汇（与 service-slots.json 同锁；id 不变，017 常量化） =====
+
+export const MALL_INFO_SERVICE = 'mall.info';
+
+/** 商场基础信息（动态商场场景下由 mall.info 槽按 mallId 拉取） */
+export interface MallInfo {
+  /** 商场 id（= scope.mallId；投影键） */
+  mallId: string;
+  /** 商场名（品牌区 mallName 动态真源；与 malls 参考表 name 同语义） */
+  name: string;
+  address?: string;
+  latitude?: number;
+  longitude?: number;
+  /** 城市 id（nearby-mall 动态化预留，本期不消费） */
+  cityId?: string;
+}
+
+/** mall.info 槽供给端口（provider 包 adapter 实现；模板装配点经 integrations 解析） */
+export interface MallInfoPort {
+  /**
+   * 查询商场信息；未知/失败 → undefined（fail-soft，调用方负责缓存与降级）。
+   * mallId 形状守卫由实现方负责（防 path 注入类字符进上游 URL）。
+   */
+  getMallInfo(mallId: string): Promise<MallInfo | undefined>;
+}

package/src/services/member.ts

@@ -0,0 +1,366 @@
+import type { Points } from '../domain/points';
+import type { DiscountRule } from '../domain/discount';
+import type { Identity, RequestContext } from '@tbox.cn/app-contracts';
+
+/**
+ * 会员域 Port（011 K2：6 Port 替换旧 MemberQueryPort/MemberSettlementPort，breaking 0.2.0）。
+ * 结构类型子集接口——模块完整实现 extends 本接口，消费方仅依赖契约包。
+ */
+
+// ===== 会员域 service slot 词汇（与 service-slots.json 同锁） =====
+
+export const MEMBER_ACCOUNT_SERVICE = 'member.account';
+export const MEMBER_PROFILE_SERVICE = 'member.profile';
+export const MEMBER_CARD_SERVICE = 'member.card';
+export const MEMBER_BENEFITS_SERVICE = 'member.benefits';
+export const MEMBER_ENROLLMENT_SERVICE = 'member.enrollment';
+
+/** 应用登录状态与会员状态相互独立；登录成功不代表已经入会。 */
+export type MemberAuthState = 'authenticated' | 'unauthenticated';
+
+/** unknown 表示当前身份无法向会员 Provider 确认状态；其余状态仅描述会员资格。 */
+export type MemberState = 'unknown' | 'active' | 'not_enrolled' | 'closed';
+
+// ===== 1. MemberAccountPort：账户/入会状态 =====
+
+export interface MemberAccountSnapshot {
+  readonly authState: MemberAuthState;
+  readonly state: MemberState;
+  readonly memberRef?: string;
+  readonly primaryMallCardNo?: string;
+  readonly registeredAt?: string;
+  readonly observedAt: string;
+}
+
+export interface MemberAccountPort {
+  getAccount(userId: string): Promise<MemberAccountSnapshot>;
+}
+
+// ===== 2. MemberProfilePort：资料 =====
+
+export interface MemberProfileSnapshot {
+  readonly displayName?: string;
+  readonly avatarUrl?: string;
+  readonly contactDisplay?: string;
+  readonly birthday?: string;
+  readonly gender?: 'unknown' | 'unspecified' | 'male' | 'female';
+  readonly labels: ReadonlyArray<{ readonly labelRef: string; readonly name: string }>;
+  readonly observedAt: string;
+}
+
+export interface MemberProfilePort {
+  getProfile(userId: string): Promise<MemberProfileSnapshot>;
+}
+
+// ===== 3. MemberCardPort：会员卡/卡名 =====
+
+/** 通用卡面视觉变体；具体等级到变体的映射由 provider 负责。 */
+export type MemberCardVisualVariant = 'blue' | 'silver' | 'gold' | 'black';
+
+export interface MemberCardPresentationSnapshot {
+  readonly variant: MemberCardVisualVariant;
+  /** 背景资源是否已包含卡名、积分标签等静态文字。 */
+  readonly labelsEmbedded?: boolean;
+}
+
+/** 卡面消费进度；金额统一为分，提示文案由 provider 按厂商规则生成。 */
+export interface MemberCardProgressSnapshot {
+  readonly daySpentCents: number;
+  readonly yearSpentCents: number;
+  readonly percent: number;
+  readonly message: string;
+}
+
+/** 卡片首屏权益摘要；规则正文与跳链不在摘要契约中直接暴露。 */
+export interface MemberBenefitPreview {
+  readonly benefitRef: string;
+  readonly name: string;
+  readonly iconUrl?: string;
+  /** 厂商权益摘要标签，例如源码按 parkingFree 拼出的“可免 X 小时”。 */
+  readonly description?: string;
+  /** 厂商原生权益动作；客户端通过支付宝 startapp 深链交给宿主跳转。 */
+  readonly action?: {
+    readonly kind: 'miniapp' | 'dialog' | 'toast';
+    readonly url?: string;
+    readonly title?: string;
+    readonly text?: string;
+  };
+}
+
+export interface MemberCardSnapshot {
+  readonly cardRef: string;
+  readonly cardDisplay: string;
+  readonly status: 'active' | 'inactive' | 'frozen' | 'expired' | 'unknown';
+  readonly levelName?: string;
+  readonly cardImageUrl?: string;
+  /** 积分规则长图；客户端以只读图片弹层展示，不作为通用跳链执行。 */
+  readonly pointsRuleImageUrl?: string;
+  readonly pointsRuleContent?: string;
+  /** C 端原生“我的积分”明细页深链。 */
+  readonly pointsUrl?: string;
+  readonly presentation?: MemberCardPresentationSnapshot;
+  readonly progress?: MemberCardProgressSnapshot;
+  readonly benefits?: ReadonlyArray<MemberBenefitPreview>;
+  readonly observedAt: string;
+}
+
+export interface MemberCardPort {
+  getCard(userId: string): Promise<MemberCardSnapshot | null>;
+}
+
+// ===== 4. MemberBenefitsPort：积分/权益（吸收旧 MemberQueryPort + 结算写） =====
+
+export interface MemberBenefitsSnapshot {
+  readonly availablePoints: number;
+  readonly usedPoints?: number;
+  readonly expiringPoints?: number;
+  readonly levelName?: string;
+  readonly observedAt: string;
+}
+
+export interface MemberBenefitsPort {
+  /** 积分查询（替代旧 MemberQueryPort.queryPoints） */
+  queryPoints(userId: string): Promise<Points>;
+  /** 权益快照 */
+  getBenefits(userId: string): Promise<MemberBenefitsSnapshot>;
+  /** 积分流水（points 卡数据源） */
+  listPointUsage(userId: string, page: number, pageSize: number): Promise<{
+    items: ReadonlyArray<PointUsageRecord>;
+    total: number;
+  }>;
+  /** 折扣查询（替代旧 MemberQueryPort.queryDiscount） */
+  queryDiscount(userId: string): Promise<DiscountRule | undefined>;
+  /** 结算写（替代旧 MemberSettlementPort；幂等键由调用方生成） */
+  deductPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean>;
+  refundPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean>;
+  awardPoints(userId: string, amount: number): Promise<boolean>;
+}
+
+export interface PointUsageRecord {
+  readonly usageRecordRef: string;
+  readonly title: string;
+  /** 字符串化金额（D11 展示层统一字符串） */
+  readonly amount: string;
+  readonly usedAt?: string;
+  readonly description?: string;
+}
+
+/**
+ * 会员服务解析工厂（上下文统一化 Stage 2）：跨模块 'member.service' 注册面。
+ * member 模块 register 期注册 `(reqCtx) => resolveMemberBenefitsPort(reqCtx, ctx)`
+ * （017 槽位原子化：本面 = benefits 单槽契约，benefits 方法族）；
+ * 跨模块消费方经 ctx.resolveService<MemberBenefitsFactory>('member.service')
+ * 结构解析后 `await factory(reqCtx)`——替代旧 'member' 全局门面（ctx.auth 并发缺陷）。
+ * 身份/会员资格判定请走 'member.status' 注册面（outcome + account），勿经本面取 account 域数据。
+ */
+export type MemberBenefitsFactory = (reqCtx: RequestContext) => Promise<MemberBenefitsPort>;
+
+// ===== 5. MemberCouponPort：优惠券（0.4.0 净删——券域由 promotion C 端承接，双真源不留） =====
+
+// ===== 6. MemberEnrollmentPort：入会（写通道，enrollment grant 闭环） =====
+
+/** 入会身份来源（F2：授权 profile 可信度高于手填） */
+export type MemberEnrollmentIdentity = 'alipay_authorized' | 'enrollment_submission';
+
+export interface MemberEnrollmentInput {
+  readonly userId: string;
+  readonly identity: MemberEnrollmentIdentity;
+  /** 表单字段（mobile 等；授权模式下 mobile 强制以授权 profile 为准） */
+  readonly fieldValues: Readonly<Record<string, string>>;
+  /** 已同意的 consent id 集合（模块侧校验必勾后传入） */
+  readonly acceptedConsentIds: readonly string[];
+  /** 幂等键（模块生成：sha256(userId\0mallId\0formVersion)） */
+  readonly idempotencyKey: string;
+  readonly formVersion?: string;
+}
+
+export type MemberEnrollmentResult =
+  | { readonly status: 'active'; readonly memberRef: string }
+  /** 厂商异步确认（pending 卡 + 显式刷新收口，R4） */
+  | { readonly status: 'pending_confirmation'; readonly attemptRef: string }
+  | { readonly status: 'rejected'; readonly reason?: string };
+
+export type MemberEnrollmentStatus =
+  | 'pending_confirmation'
+  | 'confirmation_timeout'
+  | 'active'
+  | 'failed';
+
+export interface MemberEnrollmentPort {
+  /** 入会（幂等：同 idempotencyKey 重入返回首果） */
+  enroll(input: MemberEnrollmentInput): Promise<MemberEnrollmentResult>;
+  /** 入会状态查询（attemptRef 归属校验由模块完成） */
+  getEnrollmentStatus(userId: string, attemptRef: string): Promise<{ status: MemberEnrollmentStatus; memberRef?: string; reason?: string }>;
+  /**
+   * 入会表单定义（厂商端点拉取，如厂商 enrollmentConfig 端点）；无表单端点厂商可缺省——
+   * 调用方 typeof 守卫降级（calculateBestDeal? 同款先例）。017 R13 自 module-member
+   * fat 接口收编。
+   */
+  getEnrollmentFormDefinition?(userId: string): Promise<MemberEnrollmentFormDefinition>;
+}
+
+// ===== 7. SubjectBindingPort：主体绑定解析（跨模块，015 D9） =====
+
+/**
+ * 解析平台 userId → 厂商会员外部引用（externalMemberRef）。
+ * member 模块注册实现（ctx.services.register('member.subject-binding', ...)）。
+ * @deprecated 同步派生引用不承载会员身份语义（对任意 userId 恒返回派生值）；
+ * 会员状态判定与真实外部会员引用请改用 'member.status' 服务（MemberStatusFactory）
+ * 与 externalMemberRefOf。保留仅为版本偏斜期兼容。
+ */
+export interface SubjectBindingPort {
+  resolveExternalMemberRef(userId: string): string | undefined;
+}
+
+// ===== 8. 入会表单定义（F5 自 module-member 下沉：provider 出参 + 模块工具投影共用） =====
+
+export interface MemberEnrollmentFormFieldDefinition {
+  readonly fieldId: string;
+  readonly label: string;
+  readonly type: 'text' | 'tel' | 'select' | 'date';
+  readonly required: boolean;
+  readonly placeholder?: string;
+  readonly options?: readonly string[];
+}
+
+export interface MemberEnrollmentConsentDefinition {
+  readonly consentId: string;
+  readonly version: string;
+  readonly title: string;
+  readonly required: boolean;
+}
+
+export interface MemberEnrollmentFormDefinition {
+  readonly formVersion: string;
+  readonly fields: readonly MemberEnrollmentFormFieldDefinition[];
+  readonly consents: readonly MemberEnrollmentConsentDefinition[];
+  readonly authorizationStatus: 'required' | 'unavailable';
+}
+
+// ===== 9. 会员状态折叠（outcome 单源） =====
+
+/** 折叠结果：'unauthenticated'（平台匿名短路或凭证轴未认证）或原始会员资格态。 */
+export type MemberOutcome = 'unauthenticated' | MemberState;
+
+/**
+ * 双轴折叠纯函数（无 IO，唯一真源）：identity 轴（平台登录态）优先短路；
+ * account 轴（凭证态）独立折叠——凭证轴语义由各 provider 自定义，
+ * tokenless 的合法登录可为 unauthenticated。
+ */
+export function classifyMemberOutcome(
+  identity: Pick<Identity, 'source'> | null | undefined,
+  account: MemberAccountSnapshot | null | undefined,
+): MemberOutcome {
+  if (identity?.source === 'anonymous') return 'unauthenticated';
+  if (!account) return 'unknown';
+  if (account.authState === 'unauthenticated') return 'unauthenticated';
+  return account.state;
+}
+
+/**
+ * 厂商侧会员标识：真实卡号优先，opaque 引用兜底。
+ * 兜底引用仅对不校验真实卡号的 provider 安全——需要真实卡号的厂商接口
+ * 必须由 provider 提供 primaryMallCardNo。
+ */
+export function externalMemberRefOf(account: MemberAccountSnapshot): string | undefined {
+  return account.primaryMallCardNo ?? account.memberRef;
+}
+
+/** 跨模块会员状态解析结果（窄读面；实现方注册产物可为超集）。 */
+export interface MemberStatusResolution {
+  readonly outcome: MemberOutcome | 'unavailable';
+  readonly account?: MemberAccountSnapshot;
+  /** 入会引导深链（authenticated 未入会态；未配置缺省） */
+  readonly enrollUrl?: string;
+  /** 登录引导深链（unauthenticated 态；未配置缺省） */
+  readonly loginUrl?: string;
+}
+
+/** 跨模块 'member.status' 解析工厂（与 MemberBenefitsFactory 并列的注册面契约）。 */
+export type MemberStatusFactory = (reqCtx: RequestContext) => Promise<MemberStatusResolution>;
+
+// ===== 10. 跨模块会员门禁（卡型复用 + 编排单源） =====
+
+/** 门禁卡描述子（形状 = SDK ToolCardSpec { cardType, data, note }，出卡管线兼容）。 */
+export interface MemberGateCard {
+  readonly cardType: 'member-enrollment-cta' | 'member-login-cta';
+  readonly data: Record<string, unknown>;
+  readonly note: string;
+}
+
+/** 门禁 notice 单源（工具 noResultsReason / handler text 两用；closed ≠ not_enrolled——对齐 member 先例语义拆分）。 */
+const MEMBER_GATE_NOTICES: Readonly<Record<'unauthenticated' | 'not_enrolled' | 'closed', string>> = {
+  unauthenticated: '请先登录后再使用该服务',
+  not_enrolled: '完成入会后即可使用该服务',
+  closed: '重新入会后可恢复使用该服务',
+};
+
+/**
+ * 纯卡映射：outcome → 门禁卡描述子；硬门禁态恒出卡，深链为**可选透传素材**（未配置
+ * 时卡无 URL 字段，客户端禁用按钮/壳能力接管）；软放行态 / userId 空 → undefined，
+ * 调用方退纯文字引导（notice）。
+ * 卡 schema 真源：memberEnrollmentCtaCardDataSchema / memberLoginCtaCardDataSchema（本包 member/cards.ts）。
+ */
+export function memberGateCardOf(
+  userId: string,
+  status: Pick<MemberStatusResolution, 'outcome' | 'enrollUrl' | 'loginUrl'>,
+): MemberGateCard | undefined {
+  const { outcome } = status;
+  if (outcome === 'unauthenticated') {
+    const loginUrl = status.loginUrl?.trim() || undefined;
+    return {
+      cardType: 'member-login-cta',
+      data: { title: '登录后继续', ...(loginUrl ? { loginUrl } : {}) },
+      // note 契约（W7，2026-09-01）：主体+动作（模型据此答话转述——「点击卡片登录」）
+      note: '未登录 · 点击卡片登录',
+    };
+  }
+  if (outcome !== 'not_enrolled' && outcome !== 'closed') return undefined;
+  if (!userId) return undefined;
+  const enrollUrl = status.enrollUrl?.trim() || undefined;
+  return {
+    cardType: 'member-enrollment-cta',
+    data: {
+      userId,
+      authState: 'authenticated' as const,
+      state: outcome,
+      title: '入会后继续',
+      ...(enrollUrl ? { enrollUrl } : {}),
+    },
+    note: outcome === 'not_enrolled' ? '未入会 · 点击卡片完成入会' : '已退会 · 点击卡片重新入会',
+  };
+}
+
+/** resolveMemberGate 返回的拦截块（undefined = 放行）。 */
+export interface MemberGateBlock {
+  readonly card?: MemberGateCard;
+  readonly notice: string;
+}
+
+/**
+ * 门禁编排单源：工厂缺席 / 调用抛错 → fail-open（undefined 放行）；
+ * active / unknown / unavailable → 软放行（读路径软语义——不误伤瞬时故障的会员）；
+ * 硬门禁（unauthenticated/not_enrolled/closed）→ { card?（未配深链缺省）, notice }。
+ * 实现方（member.status 工厂）应自收口异常；本函数对抛错实现兜底为软放行（横切面鲁棒性）。
+ */
+export async function resolveMemberGate(
+  factory: MemberStatusFactory | undefined,
+  reqCtx: RequestContext,
+): Promise<MemberGateBlock | undefined> {
+  if (!factory) return undefined;
+  let status: MemberStatusResolution;
+  try {
+    status = await factory(reqCtx);
+  } catch {
+    return undefined; // fail-open（防御：契约实现方未自收口）
+  }
+  const { outcome } = status;
+  if (outcome !== 'unauthenticated' && outcome !== 'not_enrolled' && outcome !== 'closed') {
+    return undefined;
+  }
+  const card = memberGateCardOf(reqCtx.identity?.userId ?? '', status);
+  return {
+    notice: MEMBER_GATE_NOTICES[outcome],
+    ...(card ? { card } : {}),
+  };
+}

package/src/services/parking.ts

@@ -0,0 +1,166 @@
+/**
+ * 停车域 Port（015：三 Port 重写，breaking 0.3.0——替换旧 ParkingQueryPort/ParkingSettlementPort）。
+ * 结算写全部收口进 ParkingPaymentPort（厂商真实支付链）；
+ * 旧 InMemory「calcFee/useCoupon/settlePayment」模拟结算面删除（S8）。
+ */
+import type { MallScope } from '../scope';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import type {
+  ParkingVehicle,
+  ParkingPresence,
+  ParkingBenefit,
+  ParkingLocation,
+  ParkingPaymentRecord,
+  ParkingRecordPage,
+  ParkingInfo,
+  QuoteSnapshot,
+} from '../domain/parking';
+
+// ===== 停车域 service slot 词汇（与 service-slots.json 同锁） =====
+
+export const PARKING_QUERY_SERVICE = 'parking.query';
+export const PARKING_PAYMENT_SERVICE = 'parking.payment';
+export const PARKING_VEHICLE_SERVICE = 'parking.vehicle';
+
+export interface ParkingQueryContext {
+  readonly scope: MallScope;
+  readonly subjectId?: string;
+  readonly requestContext: RequestContext;
+}
+
+// ===== 1. ParkingQueryPort：查询（七合一） =====
+
+export interface ParkingQueryPort {
+  /**
+   * 可选能力口：当前凭证是否不足以查询车辆（如已授权但非会员，缺 C 端会员令牌）。
+   * 返回 true 时调用方收口为「需先入会」，不再发出必然失败的厂商请求。
+   * 缺席 = provider 无此语义（调用方 typeof 守卫，照常查询）——厂商差异留在 provider 包。
+   */
+  requiresMembership?(q: ParkingQueryContext): boolean;
+  /**
+   * 可选能力口：批量入场探测（在场车 + 已停时长），仅含在场车辆。
+   * 缺席 = provider 无入场查询能力（调用方 typeof 守卫，按未入场渲染）——厂商差异留在 provider 包。
+   */
+  probeParkedVehicles?(
+    q: ParkingQueryContext,
+    plateNos: readonly string[],
+  ): Promise<readonly ParkingPresence[]>;
+  /** 计费报价（恒实时打厂商，W4；已支付态命中自动收口 PaymentOperation）。
+   *  指定车牌/vehicleRef/barcode 时返回 ≤1 条；无车辆线索（"我的车"语义）扫描绑定车队时返回所有在场有费车辆（≥1 条）。空数组 = 无在场车。 */
+  queryFee(
+    q: ParkingQueryContext,
+    input: { plateNo?: string; vehicleRef?: string; barcode?: string },
+  ): Promise<readonly QuoteSnapshot[]>;
+  /** 绑定车辆列表（parked 可选：provider 有入场查询能力时给出） */
+  listVehicles(q: ParkingQueryContext): Promise<{
+    bound: readonly ParkingVehicle[];
+  }>;
+  /** 缴费记录（脱敏；detail 含 entry/exit/payOrderNoMasked）。
+   *  orderStatus 可选：厂商交易状态过滤串（逗号分隔，语义由 provider 定义）。
+   *  缺省 = 不过滤（全量）；仅在用户语义明确指定交易状态时由工具层下发。 */
+  listPaymentRecords(
+    q: ParkingQueryContext,
+    page: number,
+    pageSize: number,
+    orderStatus?: string,
+  ): Promise<ParkingRecordPage>;
+  /** 缴费记录详情；实现必须按当前用户记录列表解析不透明 recordRef */
+  getPaymentRecordDetail(
+    q: ParkingQueryContext,
+    recordRef: string,
+  ): Promise<ParkingPaymentRecord>;
+  /** 当前停车场开票能力 */
+  getInvoiceSettings(
+    q: ParkingQueryContext,
+  ): Promise<{ parkingInvoiceEnabled: boolean }>;
+  /** 可开票订单查询 */
+  listInvoiceableOrders(
+    q: ParkingQueryContext,
+    page: number,
+    pageSize: number,
+  ): Promise<ParkingRecordPage>;
+  /**
+   * 停车场综合信息。`pendingOrder` 是 provider 侧仍保留的查询能力，但**卡片层已无此形态**——
+   * 待支付单场景改由 queryParkingFee 出可缴费的报价卡，parking-info 的 kind 不含它。
+   */
+  queryParkingInfo(
+    q: ParkingQueryContext,
+    kind: 'chargeRules' | 'benefitPolicy' | 'pendingOrder' | 'vehicleLocation',
+  ): Promise<ParkingInfo>;
+  /** 可选权益（reprice 候选） */
+  queryApplicableBenefits(
+    q: ParkingQueryContext,
+    plateNo: string,
+  ): Promise<readonly ParkingBenefit[]>;
+  /** 寻车定位 */
+  locateVehicle(
+    q: ParkingQueryContext,
+    plateNo: string,
+  ): Promise<ParkingLocation | null>;
+}
+
+// ===== 2. ParkingPaymentPort：支付写通道（三步链 R2） =====
+
+export interface ParkingPaymentPort {
+  /**
+   * step1：建单（quoteRef → 厂商支付单）。零元/免支付单可能无 payOrderId（直接 reconcile 收口）。
+   * detail：下单所需业务字段（真实链路可能必填 plateNo/payableCents；
+   * POC/mock 实现可忽略）。
+   */
+  createOrder(
+    q: ParkingQueryContext,
+    quoteRef: string,
+    detail?: {
+      plateNo?: string;
+      payableCents?: number;
+      barcode?: string;
+      /** 用户最终勾选的权益引用（跨请求无状态场景必填） */
+      benefitRefs?: readonly string[];
+    },
+  ): Promise<{ payOrderId?: string; paymentRef: string }>;
+  /** 查厂商单（channel：50 = 支付宝，不支持即拒；payableFeeCents 厂商侧权威金额） */
+  getOrderInfo(
+    q: ParkingQueryContext,
+    paymentRef: string,
+  ): Promise<{
+    orderInfo?: string;
+    channel: string;
+    payableFeeCents: number | undefined;
+  }>;
+  /** step2 前置：拉起签名串（orderInfo=my.tradePay tradeNO；payOrderFlowId 供结果上报回传） */
+  getPaymentSign(
+    q: ParkingQueryContext,
+    paymentRef: string,
+  ): Promise<{ orderInfo: string; payOrderFlowId?: string }>;
+  /** step3：客户端结果上报（status 仅上报，不作收口依据；flowId 来自 getPaymentSign） */
+  uploadResult(
+    q: ParkingQueryContext,
+    paymentRef: string,
+    status: 'success' | 'cancel' | 'failure' | 'unavailable',
+    payOrderFlowId?: string,
+  ): Promise<void>;
+  /** 权威收口唯一源（F5）：厂商侧回查支付态 */
+  reconcile(
+    q: ParkingQueryContext,
+    paymentRef: string,
+  ): Promise<'PAID' | 'PAYING' | 'CANCELLED' | 'UNKNOWN'>;
+  /** 权益重选（reprice）：新报价（revision 递增）。detail 透传试算业务字段（部分服务必填） */
+  reprice(
+    q: ParkingQueryContext,
+    quoteRef: string,
+    benefitRefs: readonly string[],
+    detail?: { plateNo?: string; payableCents?: number },
+  ): Promise<QuoteSnapshot>;
+  /** 申请停车发票；实现必须再次校验 recordRef 属于当前用户 */
+  applyInvoice(q: ParkingQueryContext, recordRef: string): Promise<void>;
+}
+
+// ===== 3. ParkingVehiclePort：车辆管理写通道 =====
+
+export interface ParkingVehiclePort {
+  bindVehicle(q: ParkingQueryContext, plateNo: string): Promise<ParkingVehicle>;
+  unbindVehicle(
+    q: ParkingQueryContext,
+    input: { plateNo?: string; vehicleRef?: string },
+  ): Promise<void>;
+}