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

package/dist/domain/entitlement.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 营销权益（已领取资产）域模型（015，TIER1）。
+ */
+import type { OfferType } from './offer';
+export type EntitlementStatus = 'EFFECTIVE' | 'USED' | 'EXPIRED' | 'INVALID' | 'UNKNOWN';
+export interface PromotionEntitlement {
+    readonly entitlementRef: string;
+    readonly offerRef?: string;
+    readonly title: string;
+    /** 厂商券面图；相对路径由 Provider Adapter 归一为 HTTPS URL。 */
+    readonly imageUrl?: string;
+    readonly entitlementType: OfferType;
+    readonly status: EntitlementStatus;
+    /** 已授权 C 端详情使用的完整券码（不得写入日志） */
+    readonly code?: string;
+    readonly codeMasked?: string;
+    /** 小程序券码区域是否允许生成二维码；状态置灰不影响该能力。 */
+    readonly qrCodeEnabled?: boolean;
+    readonly stores?: ReadonlyArray<{
+        storeId: string;
+        storeName: string;
+        businessName?: string;
+        imageUrl?: string;
+        address?: string;
+        floor?: string;
+        latitude?: number;
+        longitude?: number;
+    }>;
+    /** 生效/过期窗口（ISO8601） */
+    readonly validFrom?: string;
+    readonly validUntil?: string;
+    /** 原生券面有效期文案（例如“含领取之日起7天内有效”）。 */
+    readonly validityText?: string;
+    /** 抵扣价值（cents；PERCENTAGE 类为折扣分子） */
+    readonly valueCents?: number;
+    readonly discountPercent?: number;
+    readonly thresholdText?: string;
+    readonly benefitText?: string;
+    readonly usageNotice?: string;
+    readonly guaranteeText?: string;
+    readonly usageSceneText?: string;
+    /** 使用时间（如 00:00:00 至 23:59:59）。 */
+    readonly usageTimeText?: string;
+    /** 可领取时间窗口。 */
+    readonly claimTimeText?: string;
+    /** 原生券面“使用规则”富文本。 */
+    readonly usageRuleText?: string;
+}
+export interface PromotionEntitlementPage {
+    readonly items: readonly PromotionEntitlement[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+}

package/dist/domain/offer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 营销 Offer 域模型（015：POC marketing domain/offer 精华沉淀，TIER1）。
+ * 五类 facet 判别联合 + 可用性事实 + 参与方式；金额 cents（域内 number）。
+ */
+import type { FreeCouponClaimMode } from './coupon';
+/** 券面值类型 */
+export interface CouponFacet {
+    readonly kind: 'COUPON';
+    readonly discountType: 'AMOUNT' | 'PERCENTAGE';
+    /** AMOUNT → cents；PERCENTAGE → 折扣率分子（85 = 8.5 折） */
+    readonly value: number;
+    /** 使用门槛（cents） */
+    readonly thresholdCents?: number;
+}
+export interface BundleFacet {
+    readonly kind: 'BUNDLE';
+    readonly items: ReadonlyArray<{
+        readonly name: string;
+        readonly quantity: number;
+    }>;
+}
+export interface PromotionFacet {
+    readonly kind: 'PROMOTION';
+    readonly ruleType: 'FULL_REDUCTION' | 'DISCOUNT' | 'LADDER';
+    readonly ruleDescription: string;
+}
+export interface ActivityFacet {
+    readonly kind: 'ACTIVITY';
+    readonly registrationRequired: boolean;
+    readonly capacity?: number;
+}
+export interface GrouponFacet {
+    readonly kind: 'GROUPON';
+    readonly requiredParticipants: number;
+    readonly groupExpiresInSeconds?: number;
+}
+export type OfferFacet = CouponFacet | BundleFacet | PromotionFacet | ActivityFacet | GrouponFacet;
+export type OfferType = 'COUPON' | 'BUNDLE' | 'PROMOTION' | 'ACTIVITY' | 'GROUPON';
+/** 可用性（厂商事实，非客户端推断） */
+export interface OfferAvailability {
+    readonly status: 'AVAILABLE' | 'UNAVAILABLE' | 'REQUIRES_ACTION' | 'UNKNOWN';
+    readonly reasonCodes: readonly string[];
+    readonly evaluatedAt: string;
+    /** true = 厂商实时评估；false = 目录静态推断（领取前须厂商校验） */
+    readonly authoritative: boolean;
+    readonly requiredActions?: readonly string[];
+}
+export type ParticipationMode = 'AUTOMATIC_DISCOUNT' | 'CLAIM_THEN_PURCHASE' | 'REGISTER_THEN_ATTEND' | 'GROUP_PURCHASE' | 'UNKNOWN';
+export interface OfferParticipation {
+    readonly mode: ParticipationMode;
+    readonly steps: ReadonlyArray<{
+        readonly title: string;
+        readonly description: string;
+    }>;
+    readonly requirements?: readonly string[];
+    readonly notice?: string;
+}
+/** 营销 Offer（厂商实例聚合根引用） */
+export interface PromotionOffer {
+    readonly offerRef: string;
+    readonly providerInstanceId?: string;
+    readonly offerType: OfferType;
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly description?: string;
+    readonly imageUrl?: string;
+    /** Provider 直出的 C 端展示文案，避免客户端从金额/规则反推语义。 */
+    readonly priceText?: string;
+    readonly originalPriceText?: string;
+    readonly discountLabel?: string;
+    readonly claimActionLabel?: string;
+    /** 券的小程序详情入口；付费券抢购、免费券 REDIRECT 均由客户端在弹窗内唤起。 */
+    readonly purchaseUrl?: string;
+    /** 仅免费券消费；付费券始终使用 purchaseUrl 跳转。 */
+    readonly freeCouponClaimMode?: FreeCouponClaimMode;
+    readonly stockText?: string;
+    readonly usageNoticeText?: string;
+    readonly usageSceneText?: string;
+    readonly usageTimeText?: string;
+    readonly claimTimeText?: string;
+    /** Provider 直出的有效期文案（如「含领取之日起 7 天内有效」）。 */
+    readonly validityText?: string;
+    readonly usageRuleText?: string;
+    readonly guaranteeText?: string;
+    readonly tags: readonly string[];
+    /** ISO8601 有效期 [start, end] */
+    readonly validity: {
+        readonly start?: string;
+        readonly end: string;
+    };
+    readonly facets: readonly OfferFacet[];
+    readonly participation?: OfferParticipation;
+    readonly availability: OfferAvailability;
+    /** 领取/参与入口的厂商外部绑定（activityId 等，不透明） */
+    readonly externalBinding?: Readonly<Record<string, string>>;
+}
+/** Offer 分页（cursor 透传） */
+export interface PromotionOfferPage {
+    readonly items: readonly PromotionOffer[];
+    readonly nextCursor?: string;
+    readonly hasMore: boolean;
+}
+/** 最优优惠测算（calculateBestDeal） */
+export interface PromotionBestDeal {
+    readonly offerRef: string;
+    readonly title: string;
+    /** 预估优惠（cents） */
+    readonly estimatedSavingCents: number;
+    readonly reason: string;
+    readonly candidatesConsidered: number;
+}

package/dist/domain/operation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 营销写操作域模型（015，TIER1）：POC MarketingOperation 状态机沉淀。
+ * CREATED → EXECUTING → SUCCEEDED | PARTIAL | REJECTED | PENDING_AUTHORITY。
+ */
+export type PromotionOperationStatus = 'CREATED' | 'EXECUTING' | 'SUCCEEDED' | 'PARTIAL' | 'REJECTED' | 'PENDING_AUTHORITY';
+/** 操作终态（模块出卡只关心四态；CREATED/EXECUTING 为过程态不出卡） */
+export type PromotionOperationOutcome = Extract<PromotionOperationStatus, 'SUCCEEDED' | 'PARTIAL' | 'REJECTED' | 'PENDING_AUTHORITY'>;
+export interface PromotionOperation {
+    readonly operationRef: string;
+    readonly status: PromotionOperationStatus;
+    readonly offerRef: string;
+    /** 厂商操作引用（对账/查询用，不透明） */
+    readonly externalOperationRef?: string;
+    /** 成功领取后的券码（脱敏） */
+    readonly codeMasked?: string;
+    /** 厂商错误码（30013 未授权 / 636·637 库存 / 638 重复 / 30017 不合格 等） */
+    readonly code?: string;
+    readonly message?: string;
+    readonly observedAt: string;
+}
+/** acquire 的厂商拒绝语义分类（错误码映射产物，出卡文案用） */
+export type PromotionRejectionKind = 'AUTH_FAILED' | 'OUT_OF_STOCK' | 'ALREADY_ACQUIRED' | 'NOT_ELIGIBLE' | 'UNKNOWN';

package/dist/domain/parking.d.ts

@@ -1,13 +1,196 @@
-/** 停车费单（商圈领域 DTO，同时是 parking-fee 卡片数据契约） */
-export interface ParkingFee {
-    orderId: string;
-    userId: string;
-    plate: string;
-    /** 应付金额（元） */
-    fee: number;
-    /** 实付金额（抵扣后，元） */
-    paidAmount?: number;
-    /** 使用积分 */
-    pointsUsed?: number;
-    status: 'PENDING' | 'PAID' | 'CANCELLED';
+/**
+ * 停车域模型（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/dist/domain/points.d.ts

@@ -1,9 +1,10 @@
-/** 会员积分与等级（商圈领域 DTO） */
+/** 会员积分（商圈领域 DTO） */
 export interface Points {
     userId: string;
     /** 当前积分余额 */
     balance: number;
-    level: 'silver' | 'gold' | 'platinum';
+    /** 厂商返回的真实会员标签；不得由积分余额推导。 */
+    membershipLabel?: string;
 }
 /** 积分余额变动结果 */
 export interface PointsChangeResult {

package/dist/domain/shopping-guide.d.ts

@@ -0,0 +1,201 @@
+/**
+ * 商品导购域模型（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/dist/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @tbox.cn/app-contracts-mall：商圈领域契约（TIER1，types + runtime）。
- * 消费方（module-* / scenario / 模板装配点）只依赖本契约，
+ * 消费方（module-* / 模板装配点）只依赖本契约，
  * 不依赖任何模块实现包——结构类型子集接口 + 事件总线破环双向依赖。
  * runtime 值（scope 解析/装配器/守卫）经 ./runtime 导出（dist/runtime.js）。
  */
@@ -8,14 +8,27 @@ 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 './mall-scope-url';
 export * from './guard';
 export * from './shopping-guide/cards';
-export * from './shopping-guide/ports';
+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';

package/dist/mall-scope-url.d.ts

@@ -0,0 +1,13 @@
+/**
+ * mall scope URL 读源（客户端单一真源；自 mall 模板 platform/ 迁入，单一模板统一化 W1-①；
+ * search-only——hash 内参数不读，壳侧 URL 改写层若移参进 hash 则失效，接入契约显式声明）。
+ *
+ * mallId = 契约键（优先）；plazaId = 商场通用别名兜底（壳侧词汇兼容，非 vendor 特判——
+ * 正式小程序壳 webview 传 ?…&plazaId=1105288，本 helper 将其归一为 mallId 读源）。
+ *
+ * 仅客户端消费（浏览器环境）；服务端不调用（本包其余 runtime 同构，本文件为浏览器面例外，
+ * 函数体内联 window 访问——Node 侧调用会抛，属契约外用法）。
+ */
+export declare function readMallIdFromUrl(): string | null;
+/** 小程序 appId 读源（可选；服务端按 root config 回填，客户端缺省不阻塞） */
+export declare function readMiniAppIdFromUrl(): string | null;