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

package/src/services/parking.ts

@@ -0,0 +1,182 @@
+/**
+ * 停车域 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>;
+}
+
+// ===== 4. 跨模块停车快览（首页联单面板消费面；W3-3 单一模板统一化） =====
+
+/** 跨模块 'parking.snapshot' 词汇（与 service-slots.json 同锁）。 */
+export const PARKING_SNAPSHOT_SERVICE = 'parking.snapshot';
+
+/**
+ * 停车快览 Port（linked-panel 消费面：绑定车辆列表 + 在场探测）。
+ * Pick 派生 = ParkingQueryPort 方法面（签名即契约，不手抄字段）；可选能力口
+ * （probeParkedVehicles）缺席性随 Pick 保留。parking 模块 register 期注册工厂；
+ * 消费方 resolveService 后 await factory(reqCtx) 取 Port。
+ */
+export type ParkingSnapshotPort = Pick<ParkingQueryPort, 'listVehicles' | 'probeParkedVehicles'>;
+
+/** 跨模块 'parking.snapshot' 解析工厂（register 期注册，运行期调用）。 */
+export type ParkingSnapshotFactory = (reqCtx: RequestContext) => Promise<ParkingSnapshotPort>;

package/src/services/promotion.ts

@@ -0,0 +1,126 @@
+/**
+ * 营销域 Port（015：四 Port 重写，breaking 0.3.0——替换旧单方法 PromotionQueryPort）。
+ * 结构类型子集接口——模块完整实现 extends 本接口，消费方仅依赖契约包。
+ * C 端主体经 ctx.requestContext.credentials（X2）；externalMemberRef 由消费方经 member 域
+ * 状态服务解析（'member.status' 判定 + externalMemberRefOf 取值，SubjectBindingPort 已 deprecated）。
+ */
+import type { MallScope } from '../scope';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import type { OfferType, PromotionOffer, PromotionOfferPage, PromotionBestDeal } from '../domain/offer';
+import type { PromotionEntitlement, PromotionEntitlementPage } from '../domain/entitlement';
+import type {
+  ActivitySession,
+  PromotionActivityDetail,
+  PromotionActivityPage,
+} from '../domain/activity';
+import type { PromotionOperation } from '../domain/operation';
+
+// ===== 营销域 service slot 词汇（与 service-slots.json 同锁） =====
+
+export const PROMOTION_OFFERS_SERVICE = 'promotion.offers';
+export const PROMOTION_ENTITLEMENTS_SERVICE = 'promotion.entitlements';
+export const PROMOTION_ACTIVITIES_SERVICE = 'promotion.activities';
+export const PROMOTION_ACQUISITION_SERVICE = 'promotion.acquisition';
+
+/** 查询上下文（scope + 主体 + 请求；credentials 为 C 端用户 Token 唯一来源） */
+export interface PromotionQueryContext {
+  readonly scope: MallScope;
+  readonly subjectId?: string;
+  readonly requestContext: RequestContext;
+}
+
+/**
+ * 活动卡路由策略：provider 按请求 scope 声明是否由专属活动组件承接。
+ * 契约只描述能力，不携带厂商名称或卡片实现细节。
+ */
+export const PROMOTION_ACTIVITY_ROUTING_POLICY = 'promotion.activity-routing';
+export type PromotionActivityRoutingPolicy = (reqCtx: RequestContext) => boolean;
+
+export interface PromotionSearchInput {
+  readonly keyword?: string;
+  readonly scene?: string;
+  readonly offerTypes?: readonly OfferType[];
+  readonly cursor?: string;
+  readonly limit?: number;
+}
+
+// ===== 1. PromotionOfferQueryPort：Offer 查询/推荐/测算 =====
+
+export interface PromotionOfferQueryPort {
+  searchOffers(q: PromotionQueryContext, input: PromotionSearchInput): Promise<PromotionOfferPage>;
+  /** offerRef 精查；entitlementRef 反查关联 offer；keyword 模糊兜底（LLM 泛指词路由） */
+  getOfferDetail(
+    q: PromotionQueryContext,
+    input: { offerRef?: string; entitlementRef?: string; keyword?: string },
+  ): Promise<PromotionOffer | null>;
+  recommendOffers(q: PromotionQueryContext, input: PromotionSearchInput): Promise<readonly PromotionOffer[]>;
+  /** 可选的适用门店明细；无厂商端点时由调用方保留 notice 降级。 */
+  listOfferStores?(q: PromotionQueryContext, offerRef: string): Promise<readonly PromotionStoreSummary[]>;
+  /** 最优优惠测算（厂商无此能力可缺省；工具侧不应伪造测算卡） */
+  calculateBestDeal?(
+    q: PromotionQueryContext,
+    input: { currentAmountCents: number; candidateOfferRefs?: readonly string[] },
+  ): Promise<PromotionBestDeal>;
+}
+
+export interface PromotionStoreSummary {
+  readonly storeId: string;
+  readonly storeName: string;
+  readonly businessName?: string;
+  readonly address?: string;
+  readonly floor?: string;
+}
+
+// ===== 2. PromotionEntitlementPort：已领取资产 =====
+
+export interface PromotionEntitlementPort {
+  listEntitlements(q: PromotionQueryContext, input: PromotionSearchInput): Promise<PromotionEntitlementPage>;
+  getEntitlementDetail(q: PromotionQueryContext, entitlementRef: string): Promise<PromotionEntitlement | null>;
+}
+
+// ===== 3. PromotionActivityPort：活动（含场次/指南） =====
+
+/** 活动分类（SPEZ-016：活动分类列表；厂商无分类端点时实现方可缺省） */
+export interface PromotionActivityCategoryRecord {
+  readonly categoryId: string;
+  readonly name: string;
+  readonly parentId?: string;
+}
+
+export interface PromotionActivityPort {
+  listActivities(
+    q: PromotionQueryContext,
+    input: {
+      categoryId?: string;
+      keyword?: string;
+      dataScope?: 'CURRENT' | 'HISTORY';
+      registrationRequired?: boolean;
+      startsAfter?: string;
+      endsBefore?: string;
+      cursor?: string;
+      limit?: number;
+    },
+  ): Promise<PromotionActivityPage>;
+  getActivityDetail(q: PromotionQueryContext, activityRef: string): Promise<PromotionActivityDetail | null>;
+  /** 独立场次查询，保留旧营销组件的只读接口语义。 */
+  listActivitySessions?(q: PromotionQueryContext, activityRef: string): Promise<readonly ActivitySession[]>;
+  /** 活动分类（optional——实现未接分类端点时调用方 ?. 降级） */
+  listActivityCategories?(): Promise<readonly PromotionActivityCategoryRecord[]>;
+}
+
+// ===== 4. PromotionAcquisitionPort：领取写通道 =====
+
+export interface PromotionAcquisitionPort {
+  /**
+   * 领取/报名（写操作）。
+   * 幂等：同 idempotencyKey 重复调用返回首果（厂商侧或调用方兜底）。
+   * externalMemberRef 由调用方经 member 域状态服务解析（member 域跨模块供给：
+   * 'member.status' 判定 + externalMemberRefOf 取真实卡号或 opaque 引用）。
+   */
+  acquire(
+    q: PromotionQueryContext,
+    input: { offerRef: string; externalMemberRef: string; idempotencyKey: string },
+  ): Promise<PromotionOperation>;
+  /** 操作查询（悬挂 PENDING_AUTHORITY 收口用，可缺省） */
+  getOperation?(q: PromotionQueryContext, operationRef: string): Promise<PromotionOperation | null>;
+}

package/src/services/shopping-guide.ts

@@ -0,0 +1,138 @@
+/**
+ * 导购域 Port 接口（011 S7：shopping-guide 6 Port，TIER1 结构类型子集）。
+ * 模块完整实现 extends 本接口；消费方（其他模块）仅依赖契约包。
+ * 领域模型见 domain/shopping-guide.ts。
+ */
+import type { MallScope } from '../scope';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import type {
+  ProductRecord,
+  ProductFacetsRecord,
+  ShopRecord,
+  CategoryRecord,
+  MallDirectoryRecord,
+  ShopLocationRecord,
+  HumanGuideRecord,
+  NearbyMallRecord,
+} from '../domain/shopping-guide';
+
+// ===== 导购域 service slot 词汇（与 service-slots.json 同锁） =====
+
+export const SHOPPING_CATALOG_SERVICE = 'shopping-guide.catalog';
+export const SHOPPING_SHOPS_SERVICE = 'shopping-guide.shops';
+export const SHOPPING_CATEGORIES_SERVICE = 'shopping-guide.categories';
+export const SHOPPING_DIRECTORY_SERVICE = 'shopping-guide.directory';
+
+// ===== 查询上下文（mall scope + 主体） =====
+
+export interface ShoppingQueryContext {
+  readonly scope: MallScope;
+  readonly subjectId?: string;
+  readonly requestContext: RequestContext;
+}
+
+// ===== 分页 =====
+
+export interface ShoppingPage<T> {
+  readonly items: readonly T[];
+  readonly page: number;
+  readonly pageSize: number;
+  readonly total: number;
+  readonly hasMore: boolean;
+}
+
+// ===== 1. CatalogQueryPort：商品目录 =====
+
+export interface ProductSearchCriteria {
+  readonly ctx: ShoppingQueryContext;
+  /** 单值关键词（简单调用方兼容）；与 keywords 并存时以 keywords 为准 */
+  readonly keyword?: string;
+  /** 多角度搜索词组（模型拆词产物）：provider 应逐词查询并去重合并（OR 语义），禁止拼串 */
+  readonly keywords?: readonly string[];
+  readonly categoryCode?: string;
+  readonly brandCode?: string;
+  readonly minPriceMinor?: number;
+  readonly maxPriceMinor?: number;
+  readonly floorCode?: string;
+  readonly buildingCode?: string;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly marketableOnly?: boolean;
+}
+
+export interface CatalogQueryPort {
+  searchProducts(criteria: ProductSearchCriteria): Promise<ShoppingPage<ProductRecord>>;
+  getProduct(productId: string, ctx: ShoppingQueryContext): Promise<ProductRecord | null>;
+  getFacets(criteria: ProductSearchCriteria): Promise<ProductFacetsRecord>;
+}
+
+// ===== 2. ShopDirectoryQueryPort：门店目录 =====
+
+export interface ShopSearchCriteria {
+  readonly ctx: ShoppingQueryContext;
+  /** 单值关键词（简单调用方兼容）；与 keywords 并存时以 keywords 为准 */
+  readonly keyword?: string;
+  /** 多角度搜索词组（模型拆词产物）：provider 应逐词查询并去重合并（OR 语义），禁止拼串 */
+  readonly keywords?: readonly string[];
+  readonly brandCode?: string;
+  readonly businessCategory?: string;
+  readonly floorCode?: string;
+  readonly buildingCode?: string;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+export interface ShopDirectoryQueryPort {
+  searchShops(criteria: ShopSearchCriteria): Promise<ShoppingPage<ShopRecord>>;
+  getShop(shopId: string, ctx: ShoppingQueryContext): Promise<ShopRecord | null>;
+  /**
+   * 商场概览快照（可选能力口）：品牌导览聚合——楼层 + 业态（权威计数）+ 对 C 透出的预览门店。
+   * ⚠️ stores 为首页预览子集非全量（概览卡语义），全量浏览走 searchShops。
+   * provider 未实现（缺省）→ 概览问句降级 searchShops 零参。
+   */
+  fetchStoreOverview?(ctx: ShoppingQueryContext): Promise<MallOverviewSnapshot | null>;
+}
+
+/** 商场概览快照（indexBrandGuideAgg 形态归一）：mall-overview preTool 出概览 shop-list 卡的数据源 */
+export interface MallOverviewSnapshot {
+  readonly mallId: string;
+  /** 楼层名列表（如 B1/1F/2F…，agg.floors） */
+  readonly floors: readonly string[];
+  /** 业态字典（场景 tag + 权威门店计数，agg.tags→CategoryRecord：name=业态、merchantCount=storeNum） */
+  readonly categories: readonly CategoryRecord[];
+  /** 预览门店（agg.stores——首页透出口径子集，非全量） */
+  readonly stores: readonly ShopRecord[];
+  readonly observedAt: string;
+}
+
+/** @deprecated 使用 ShopSearchCriteria */
+export type MerchantSearchCriteria = ShopSearchCriteria;
+/** @deprecated 使用 ShopDirectoryQueryPort */
+export type MerchantDirectoryQueryPort = ShopDirectoryQueryPort;
+
+// ===== 3. CommercialCategoryQueryPort：业态分类 =====
+
+export interface CommercialCategoryQueryPort {
+  listCategories(ctx: ShoppingQueryContext): Promise<readonly CategoryRecord[]>;
+}
+
+// ===== 4. MallDirectoryQueryPort：楼栋-楼层目录 =====
+
+export interface MallDirectoryQueryPort {
+  getDirectory(ctx: ShoppingQueryContext): Promise<MallDirectoryRecord | null>;
+}
+
+// ===== 5. AssistanceQueryPort：人工导购协助 =====
+// （客服 FAQ/知识库两方法已拆分至 customer-service.ts CustomerServiceQueryPort——2026-08-31 客服模块拆分）
+
+export interface AssistanceQueryPort {
+  listHumanGuides(merchantId: string, ctx: ShoppingQueryContext): Promise<readonly HumanGuideRecord[]>;
+}
+
+// ===== 6. NavigationPort：位置/附近商场/浏览历史 =====
+
+export interface NavigationPort {
+  getLocation(shopId: string, ctx: ShoppingQueryContext): Promise<ShopLocationRecord | null>;
+  listNearbyMalls(ctx: ShoppingQueryContext, query?: string): Promise<readonly NearbyMallRecord[]>;
+  listBrowsingHistory(ctx: ShoppingQueryContext, page: number, pageSize: number): Promise<ShoppingPage<ProductRecord>>;
+}

package/src/shared/cards.ts

@@ -0,0 +1,25 @@
+/**
+ * 商圈通用卡片片段（0.3.2 D4：actionDraftSchema 单源——从 shopping-guide/cards.ts 抽出，
+ * 四域条目动作共用；index.ts 与 runtime.ts 均 re-export 本文件，M2 导出面）。
+ */
+
+import { z } from 'zod';
+
+/**
+ * 卡内条目动作草稿（015 F1：判别联合——仅客户端本地语义，write 变体无 token 机制支撑不进）。
+ * - send：发消息（value 缺省用 label）；link：打开 URL（tel:/https:）。
+ * 渲染端经 card-action-handler 既有通道分发（零新机制）；zod 判别联合天然拒未知 kind。
+ */
+export const actionDraftSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('send'),
+    label: z.string().min(1),
+    /** 发给服务端 AI 的完整指令（可含隐藏上下文如 merchantId）；缺省用 label */
+    value: z.string().optional(),
+    /** 用户气泡展示文本（有值时 sendMessage 走 visible=false 隐藏，只展示此文本为气泡副本）；
+     * 缺省则 visible=true，直接展示 value/label */
+    visibleValue: z.string().optional(),
+  }),
+  z.object({ kind: z.literal('link'), label: z.string().min(1), url: z.string().min(1) }),
+]);
+export type ActionDraft = z.infer<typeof actionDraftSchema>;