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

package/src/domain/parking.ts

@@ -0,0 +1,207 @@
+/**
+ * 停车域模型（015：POC parking 域精华沉淀，TIER1）。
+ * 金额一律 cents（number）；展示层字符串化（D11）。
+ */
+
+/** 停车车辆（绑定车） */
+export interface ParkingVehicle {
+  readonly vehicleRef: string;
+  readonly plateNo: string;
+  readonly boundAt?: string;
+  /**
+   * 是否在场内（可选能力）：provider 无入场查询能力时缺省，UI 据此不显示任何入场状态——
+   * 缺省与 false 不同义，false 是「查过，不在场」。
+   */
+  readonly parked?: boolean;
+}
+
+/**
+ * 入场探测结果元素（可选能力口 ParkingQueryPort.probeParkedVehicles 出参）。
+ * 仅含在场车辆；缺席 = 未入场或未知。
+ */
+export interface ParkingPresence {
+  readonly plateNo: string;
+  /** 已停时长（分钟，≥1）；provider 给不出时缺省，UI 退回通用计费文案 */
+  readonly parkedMinutes?: number;
+}
+
+/** 费用明细项 */
+export interface ParkingFeeItem {
+  readonly name: string;
+  /** 应收（cents） */
+  readonly amountCents: number;
+  /** 优惠减免（cents，正数） */
+  readonly discountCents?: number;
+  readonly note?: string;
+}
+
+/** 报价快照（revision 乐观锁：权益重选 → 新 revision，旧卡提交被拒） */
+export interface QuoteSnapshot {
+  readonly quoteRef: string;
+  readonly plateNo: string;
+  readonly mallId: string;
+  readonly entryAt?: string;
+  readonly exitAt?: string;
+  readonly feeItems: readonly ParkingFeeItem[];
+  /** 应收合计（cents） */
+  readonly totalCents: number;
+  /** 已减免合计（cents） */
+  readonly discountCents: number;
+  /** 应付（total - discount，cents） */
+  readonly payableCents: number;
+  /** 已生效权益（benefitRef → 标题） */
+  readonly appliedBenefits: ReadonlyArray<{
+    readonly benefitRef: string;
+    readonly title: string;
+    readonly discountCents: number;
+  }>;
+  /** 乐观锁版本（reprice 递增） */
+  readonly revision: number;
+  readonly paymentState: 'UNPAID' | 'PAYING' | 'PAID';
+  readonly expiresAt?: string;
+  /**
+   * 支付交接包（provider 有跳转支付页能力时给出）：客户端卡据 kind 调壳 tbox 能力收款——
+   * `kind:'pay'` → `openParkingPay`(传 orderInfo,壳负责跳确认页/收银台);
+   * `kind:'unpaid'` → `openParkingUnpaidOrder`(传 orderNo,壳打开已有待支付订单详情页)。
+   * provider 无此语义时缺省（调用方退回内部建单/收银台流程）。
+   */
+  readonly payHandoff?: {
+    readonly kind: 'pay' | 'unpaid';
+    readonly parkingStoreId?: string;
+    /** kind='pay' 时给——传给壳 `openParkingPay` 的订单信息 */
+    readonly orderInfo?: ParkingPayOrderInfo;
+    /** kind='unpaid' 时给——已有订单号(= 厂商 tradeOrderNo,与壳协议 orderNo 同号)传给壳 `openParkingUnpaidOrder` */
+    readonly orderNo?: string;
+  };
+}
+
+/**
+ * 厂商协议 `openParkingPay` 的 orderInfo（从 advancePaymentOrder 聚合）。
+ * 壳用这些字段自己拼确认页,不再回查费。
+ */
+export interface ParkingPayOrderInfo {
+  /** 停车秒数 */
+  readonly staySecond?: number;
+  /** 停车费,单位分 */
+  readonly parkingFee?: number;
+  /** 车牌绑定状态 */
+  readonly bindingStatus?: number;
+  /** 车牌 */
+  readonly plateNumber?: string;
+  /** 1=在场缴费,2=逃费/欠费 */
+  readonly orderType: number;
+  /** 车场侧订单号 */
+  readonly spParkingOrderId?: string;
+  /** 车场 ID(协议已定 string) */
+  readonly parkingId: string;
+  /** 入场时间 */
+  readonly entranceTime?: string;
+  /** 逗号分隔的能力枚举,如 "LEVEL_DISCOUNT,POINT_DISCOUNT,COUPON" */
+  readonly supportDiscount?: string;
+}
+
+/** 可选权益（用户可勾选参与 reprice） */
+export interface ParkingBenefit {
+  readonly benefitRef: string;
+  readonly title: string;
+  readonly description?: string;
+  /** 是否已默认勾选生效 */
+  readonly autoSelected: boolean;
+  readonly estimatedDiscountCents?: number;
+  /** Provider 归一化后的权益类型；不得由客户端从标题猜测。 */
+  readonly kind?: 'points' | 'discount' | 'coupon' | 'other';
+  /**
+   * 与本权益互斥的权益类型（Provider 归一化下发；客户端不得从标题或类型推断）。
+   * 三类优惠（券 / 积分抵扣 / 等级权益）默认可叠加，互斥是厂商侧的按券配置——
+   * 部分停车券标记「不可与积分叠加」即 ['points']。互斥判定必须双向：勾选任一方
+   * 都要撤下另一方（见客户端 resolveBenefitSelection）。
+   */
+  readonly exclusiveWithKinds?: readonly ('points' | 'discount' | 'coupon')[];
+  /** 仅在 Provider 返回权威兑换计划时提供。 */
+  readonly requiredPoints?: number;
+  /** 与 requiredPoints 对应的权威预估应付金额。 */
+  readonly previewPayableCents?: number;
+  /** 不可与哪些 benefitRef 同时生效；为空数组表示与所有同类别权益（如所有 coupon）互斥。 */
+  readonly exclusiveWith?: readonly string[];
+  /** 是否可与优惠券叠加（仅积分类权益有意义）；undefined 表示未知/默认允许。 */
+  readonly stacksWithCoupon?: boolean;
+}
+
+/** 寻车定位 */
+export interface ParkingLocation {
+  readonly floorName?: string;
+  readonly zoneName?: string;
+  readonly spaceNo?: string;
+  readonly walkingRoute?: string;
+  readonly mapUrl?: string;
+}
+
+/** 缴费记录条目 */
+export interface ParkingPaymentRecord {
+  readonly recordRef: string;
+  readonly plateNo: string;
+  /** 实付（cents） */
+  readonly amountCents: number;
+  readonly paidAt: string;
+  readonly status: 'PAID' | 'REFUNDED' | 'CLOSED' | 'UNKNOWN';
+  /** 厂商原始交易状态文案（如「交易关闭」「交易完成」，供卡片直接展示） */
+  readonly statusText?: string;
+  readonly parkName?: string;
+  readonly plazaName?: string;
+  readonly entryAt?: string;
+  readonly exitAt?: string;
+  readonly payOrderNoMasked?: string;
+  /** 厂商订单是否已完成（开票资格的前置条件） */
+  readonly orderCompleted?: boolean;
+  /** 当前是否允许申请开票（同时受停车场配置与订单状态约束） */
+  readonly invoiceEligible?: boolean;
+  /** 是否已开票/已提交开票申请 */
+  readonly invoiceIssued?: boolean;
+}
+
+export interface ParkingRecordPage {
+  readonly items: readonly ParkingPaymentRecord[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly hasMore: boolean;
+}
+
+/** 停车场综合信息（四合一 kind） */
+export interface ParkingInfo {
+  readonly kind: 'chargeRules' | 'benefitPolicy' | 'pendingOrder' | 'vehicleLocation';
+  readonly title: string;
+  /** 通用键值展示（余位数/首小时费率/会员权益政策等） */
+  readonly entries: ReadonlyArray<{
+    readonly label: string;
+    readonly value: string;
+  }>;
+  /** pendingOrder 时的待支付单引用 */
+  readonly pendingQuote?: QuoteSnapshot;
+}
+
+/**
+ * 支付操作（StateStore 持久化单据）：
+ * PAYING →（reconcile 权威）→ PAID / CANCELLED；UNKNOWN = 厂商态不明（悬挂，下次交互收口，V2）。
+ */
+export interface PaymentOperation {
+  /** 对外不透明引用；卡片/客户端只能持有该值 */
+  readonly paymentRef: string;
+  /** 厂商支付引用，仅服务端持久化并用于回查 */
+  readonly providerPaymentRef: string;
+  readonly quoteRef: string;
+  readonly plateNo: string;
+  /** 支付操作归属主体；与 mallId 共同用于服务端授权 */
+  readonly subjectId: string;
+  readonly mallId: string;
+  readonly payableCents: number;
+  /** 厂商支付单号（masked 展示） */
+  readonly payOrderNoMasked?: string;
+  /** 厂商支付组件流水 ID（GetPaySign 产出；结果上报 UploadPayParamsResult 回传） */
+  readonly payOrderFlowId?: string;
+  readonly status: 'PAYING' | 'PAID' | 'CANCELLED' | 'UNKNOWN';
+  readonly createdAt: string;
+  readonly paidAt?: string;
+  /** 入场时间（建单时自报价带入）：回执要算停车时长，而报价此时已不可达 */
+  readonly entryAt?: string;
+}

package/src/domain/points.ts

@@ -0,0 +1,15 @@
+/** 会员积分（商圈领域 DTO） */
+export interface Points {
+  userId: string;
+  /** 当前积分余额 */
+  balance: number;
+  /** 厂商返回的真实会员标签；不得由积分余额推导。 */
+  membershipLabel?: string;
+}
+
+/** 积分余额变动结果 */
+export interface PointsChangeResult {
+  success: boolean;
+  balance: number;
+  reason?: string;
+}

package/src/domain/shopping-guide.ts

@@ -0,0 +1,242 @@
+/**
+ * 商品导购域模型（shopping-guide domain model，TIER1）。
+ * 商品、门店（shop）、位置、类目、知识库、人工导购等核心业务实体。
+ * Port 接口见 services/shopping-guide.ts；卡片数据结构见 shopping-guide/cards.ts。
+ */
+import type { FreeCouponClaimMode } from './coupon';
+
+// ===== 共享值对象 =====
+
+/** 货币金额值对象 */
+export interface MoneyRecord {
+  readonly currency: 'CNY';
+  readonly amountMinor: number;
+  readonly display: string;
+}
+
+/** 门店位置值对象（零坐标依赖，POC R5；poiId 有值时可升级为坐标导航） */
+export interface ShopLocationRecord {
+  readonly buildingName?: string;
+  readonly floorName?: string;
+  readonly unitName?: string;
+  readonly displayText: string;
+  readonly poiId?: string;
+}
+/** @deprecated 使用 ShopLocationRecord */
+export type MerchantLocationRecord = ShopLocationRecord;
+
+// ===== 商品目录域 =====
+
+/** 商品实体 */
+export interface ProductRecord {
+  readonly productId: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly imageUrls: readonly string[];
+  readonly brand?: string;
+  readonly categoryPath: readonly string[];
+  readonly price: ProductPrice;
+  readonly availability: ProductAvailability;
+  readonly merchant: ProductShopRef;
+  readonly labels: readonly string[];
+  readonly attributes: ReadonlyArray<ProductAttribute>;
+  readonly promotionFacts: readonly string[];
+  readonly observedAt: string;
+}
+
+export interface ProductPrice {
+  readonly sale?: MoneyRecord;
+  readonly original?: MoneyRecord;
+  readonly promotion?: MoneyRecord;
+}
+
+export interface ProductAvailability {
+  readonly status: 'in_stock' | 'out_of_stock' | 'limited' | 'unknown';
+  readonly label: string;
+  readonly marketable: boolean;
+  readonly observedAt: string;
+}
+
+/** 商品上的门店引用（轻量，不含完整门店信息） */
+export interface ProductShopRef {
+  readonly merchantId: string;
+  readonly name: string;
+  readonly location?: ShopLocationRecord;
+}
+/** @deprecated 使用 ProductShopRef */
+export type ProductMerchantRef = ProductShopRef;
+
+export interface ProductAttribute {
+  readonly name: string;
+  readonly value: string;
+}
+
+export interface ProductFacetsRecord {
+  readonly brands: ReadonlyArray<FacetOption>;
+  readonly categories: ReadonlyArray<FacetOption>;
+  readonly priceRanges: ReadonlyArray<PriceRangeFacet>;
+  readonly floors: ReadonlyArray<FloorFacetOption>;
+}
+
+export interface FacetOption {
+  readonly code: string;
+  readonly name: string;
+  readonly count: number;
+}
+
+export interface PriceRangeFacet {
+  readonly minMinor: number;
+  readonly maxMinor: number;
+  readonly displayLabel: string;
+  readonly count: number;
+}
+
+export interface FloorFacetOption {
+  readonly code: string;
+  readonly displayName: string;
+  readonly count: number;
+}
+
+// ===== 门店目录域 =====
+
+/** 门店关联优惠（来自 couponList） */
+export interface ShopCoupon {
+  readonly name: string;
+  readonly imageUrl?: string;
+  /** 去 HTML 标签后的纯文本描述（可选） */
+  readonly description?: string;
+  /** 券面值（元，parValue/100） */
+  readonly faceValue?: number;
+  /** 售价（元，price/100；0 = 免费领取） */
+  readonly salePrice?: number;
+  /** 适用业态列表（useBusinessType） */
+  readonly applicableCategories?: string[];
+  /** 领取后有效小时数（expiredAfterHours） */
+  readonly validHours?: number;
+  /** 可用时间文案（useWeekTime 解析：星期段 + st-et 截前 5 位，provider 直出） */
+  readonly usageTimeText?: string;
+  /** 券的小程序详情入口；付费券固定跳转，免费券由 freeCouponClaimMode 决定。 */
+  readonly purchaseUrl?: string;
+  /** 仅免费券消费；缺省保持既有直领语义。 */
+  readonly freeCouponClaimMode?: FreeCouponClaimMode;
+  /**
+   * 营销域券引用（厂商 offerRef 形如 `offer:${couponNo}`）——厂商 couponList 返回券编号时提供；
+   * DIRECT 模式下经 promotion.acquire 同链路领取。
+   */
+  readonly offerRef?: string;
+}
+
+/** 门店实体（聚合根） */
+export interface ShopRecord {
+  readonly merchantId: string;
+  readonly name: string;
+  readonly logoUrl?: string;
+  readonly coverUrls: readonly string[];
+  readonly brand?: string;
+  readonly businessCategories: readonly string[];
+  readonly location: ShopLocationRecord;
+  readonly status: ShopStatus;
+  readonly description?: string;
+  readonly contactInfo?: ReadonlyArray<ContactChannel>;
+  readonly services: readonly string[];
+  readonly promotionFacts: readonly string[];
+  /** 门店关联优惠券列表（来自 provider couponList；有值时展示） */
+  readonly coupons?: ReadonlyArray<ShopCoupon>;
+  readonly observedAt: string;
+}
+/** @deprecated 使用 ShopRecord */
+export type MerchantRecord = ShopRecord;
+
+export interface ShopStatus {
+  readonly code: 'enabled' | 'disabled' | 'unknown';
+  readonly label: string;
+  readonly observedAt: string;
+}
+/** @deprecated 使用 ShopStatus */
+export type MerchantStatus = ShopStatus;
+
+export interface ContactChannel {
+  readonly channel: string;
+  readonly value: string;
+}
+
+// ===== 业态分类域 =====
+
+export interface CategoryRecord {
+  readonly code: string;
+  readonly name: string;
+  readonly description?: string;
+  /** 类目图标 URL（C 端 GetListMallCategory 返回；空字符串时由前端展示默认图标） */
+  readonly iconUrl?: string;
+  readonly merchantCount: number;
+  readonly subCategories?: ReadonlyArray<SubCategoryRecord>;
+}
+
+export interface SubCategoryRecord {
+  readonly code: string;
+  readonly name: string;
+  readonly merchantCount: number;
+}
+
+// ===== 楼栋目录域 =====
+
+export interface MallDirectoryRecord {
+  readonly mallId: string;
+  readonly mallName: string;
+  readonly buildings: ReadonlyArray<BuildingRecord>;
+  readonly observedAt: string;
+}
+
+export interface BuildingRecord {
+  readonly buildingCode: string;
+  readonly buildingName: string;
+  readonly floors: ReadonlyArray<FloorRecord>;
+}
+
+export interface FloorRecord {
+  readonly floorCode: string;
+  readonly floorName: string;
+  readonly businessCategories: readonly string[];
+  readonly merchantCount: number;
+}
+
+// ===== 知识库 & 客服域 =====
+
+export interface FaqEntry {
+  readonly question: string;
+  readonly answer: string;
+  readonly category?: string;
+  readonly relevanceScore: number;
+}
+
+export interface KnowledgeEntry {
+  readonly content: string;
+  readonly title?: string;
+  readonly score: number;
+}
+
+// ===== 人工导购域 =====
+
+export interface HumanGuideRecord {
+  readonly guideId: string;
+  readonly name: string;
+  readonly title?: string;
+  readonly avatarUrl?: string;
+  readonly contactInfo?: ReadonlyArray<ContactChannel>;
+  readonly available: boolean;
+}
+
+// ===== 附近商场域 =====
+
+export interface NearbyMallRecord {
+  readonly mallId: string;
+  readonly name: string;
+  readonly address: string;
+  readonly distanceKm?: number;
+  readonly status: NearbyMallStatus;
+}
+
+export interface NearbyMallStatus {
+  readonly code: 'open' | 'closed' | 'unknown';
+  readonly label: string;
+}

package/src/events/index.ts

@@ -0,0 +1,10 @@
+/**
+ * MallEventMap：商圈跨模块事件（类型化事件总线 keyof 约束，001 §5.4）。
+ * 用 type（非 interface）以获得隐式索引签名，满足 SDK EventMap（Record<string, unknown>）约束。
+ */
+export type MallEventMap = {
+  /** 会员等级变更 */
+  'member.level.changed': { userId: string; newLevel: 'silver' | 'gold' | 'platinum' };
+  /** 停车券核销 */
+  'parking.coupon.used': { userId: string; couponId: string; amount: number };
+};

package/src/guard.ts

@@ -0,0 +1,48 @@
+/**
+ * 商圈守卫（011：location/user 领域守卫，TIER1 运行时）：
+ * 卡片/工具入参中的位置与用户字段防御解析。
+ * 平台存储数据不可全信——一切外部形状先过 zod。
+ */
+import { z } from 'zod';
+
+/** 商圈位置（经纬度字符串化，D11：数值一律字符串化） */
+export interface MallLocation {
+  latitude: string;
+  longitude: string;
+  /** 可选商圈 id（位置所属 mall） */
+  mallId?: string;
+  /** 可选名称（POI） */
+  name?: string;
+}
+
+export const mallLocationSchema = z.object({
+  latitude: z.string().min(1),
+  longitude: z.string().min(1),
+  mallId: z.string().optional(),
+  name: z.string().optional(),
+});
+
+/** 解析失败返回 undefined（调用方降级「位置未知」文案） */
+export function parseMallLocation(raw: unknown): MallLocation | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const result = mallLocationSchema.safeParse(raw);
+  return result.success ? result.data : undefined;
+}
+
+/** 商圈用户标识（D11 字符串化 user 字段守卫） */
+export interface MallUserRef {
+  userId: string;
+  /** 可选 mall 会员主体 id */
+  subjectId?: string;
+}
+
+export const mallUserRefSchema = z.object({
+  userId: z.string().min(1),
+  subjectId: z.string().optional(),
+});
+
+export function parseMallUserRef(raw: unknown): MallUserRef | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const result = mallUserRefSchema.safeParse(raw);
+  return result.success ? result.data : undefined;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * @tbox.cn/app-contracts-mall：商圈领域契约（TIER1，types + runtime）。
+ * 消费方（module-* / 模板装配点）只依赖本契约，
+ * 不依赖任何模块实现包——结构类型子集接口 + 事件总线破环双向依赖。
+ * runtime 值（scope 解析/装配器/守卫）经 ./runtime 导出（dist/runtime.js）。
+ */
+export * from './domain/points';
+export * from './domain/coupon';
+export * from './domain/discount';
+export * from './domain/parking';
+export * from './domain/offer';
+export * from './domain/entitlement';
+export * from './domain/activity';
+export * from './domain/operation';
+export * from './services/member';
+export * from './services/parking';
+export * from './services/promotion';
+export * from './services/mall-info';
+export * from './events';
+export * from './scope';
+export * from './query-context';
+export * from './deployment';
+export * from './assembly';
+export * from './guard';
+export * from './shopping-guide/cards';
+export * from './shared/cards';
+export * from './domain/shopping-guide';
+export * from './services/shopping-guide';
+export * from './services/customer-service';
+export * from './member/cards';
+export * from './promotion/cards';
+export * from './parking/cards';
+export * from './alipay-activity/cards';