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

package/src/services/promotion.ts

@@ -1,6 +1,126 @@
-import type { Coupon } from '../domain/coupon';
+/**
+ * 营销域 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';
 
-/** PromotionQueryPort：营销资格查询（scenario 出券用） */
-export interface PromotionQueryPort {
-  queryEligibleCoupons(userId: string): Promise<Coupon[]>;
+// ===== 营销域 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>;