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

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "@tbox.cn/app-contracts-mall",
-  "version": "0.2.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "商圈领域契约（TIER1，types + runtime）：Port 接口 + MallEventMap + 领域 DTO + scope/装配器运行时。",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/runtime.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
     }
   },
   "files": [
     "dist",
+    "src",
+    "tests",
+    "tsconfig.json",
+    "tsconfig.build.json",
     "README.md",
     "LICENSE"
   ],
@@ -21,16 +29,20 @@
     "access": "public"
   },
   "dependencies": {
-    "@tbox.cn/app-contracts": "^0.1.0",
-    "zod": "^3.24.0"
+    "@tbox.cn/app-contracts": "0.10.0",
+    "zod": "3.25.76"
   },
   "devDependencies": {
-    "tsup": "^8.0.0",
-    "typescript": "^5.7.0"
+    "@tbox.cn/app-sdk": "0.19.0",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.10",
+    "happy-dom": "20.11.2"
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsup src/runtime.ts --format esm --external @ag-ui/core --out-dir dist",
-    "typecheck": "tsc --noEmit"
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && tsup src/runtime.ts src/server/index.ts --format esm --external @ag-ui/core --out-dir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/alipay-activity/cards.ts

@@ -0,0 +1,66 @@
+/**
+ * 支付宝「碰出惊喜」互动营销活动卡片数据契约。
+ * alipay-activity 专属——与 promotion 通用卡型解耦，独立维护。
+ */
+import { z } from 'zod';
+
+/** 单张优惠券奖品 */
+const bumpInVoucherSchema = z.object({
+  prizeId: z.string(),
+  voucherName: z.string(),
+  voucherType: z.string(),
+  reductionAmount: z.string(),
+  thresholdAmountText: z.string(),
+  unit: z.string(),
+  merchantName: z.string(),
+  merchantLogo: z.string().optional(),
+  itemLogo: z.string().optional(),
+});
+export type BumpInVoucher = z.infer<typeof bumpInVoucherSchema>;
+
+/**
+ * 碰出惊喜活动生命周期状态（支付宝 IoT NSP 权威枚举）：
+ * NOT_START 未开始 / INIT 初始化 / PROCESSING 进行中 / FINISH 已完成 / RECEIVED 已领奖。
+ * RECEIVED 是用户级终态（奖励已领取），其余为活动级状态。
+ */
+export const bumpInActStatusSchema = z.enum([
+  'NOT_START',
+  'INIT',
+  'PROCESSING',
+  'FINISH',
+  'RECEIVED',
+]);
+export type BumpInActStatus = z.infer<typeof bumpInActStatusSchema>;
+
+/** promotion-bumpin-activity：进度 + 奖励池，detail/banner 双模式 */
+export const promotionBumpInActivityCardDataSchema = z.object({
+  activityRef: z.string(),
+  title: z.string(),
+  mainTitle: z.string().optional(),
+  coverUrl: z.string().optional(),
+  /** 联单活动全幅背景图 URL（与 coverUrl 互斥；backgroundUrl 存在时头部采用全幅覆盖布局） */
+  backgroundUrl: z.string().optional(),
+  /** 左上角活动类型胶囊标签，如"碰一下联单" */
+  tagLabel: z.string().optional(),
+  cardLogoUrl: z.string().optional(),
+  actStatus: bumpInActStatusSchema,
+  totalProgress: z.string().optional(),
+  currentProgress: z.string().optional(),
+  progressUnit: z.string().optional(),
+  startAtText: z.string().optional(),
+  endAtText: z.string().optional(),
+  description: z.string().optional(),
+  vouchers: z.array(bumpInVoucherSchema),
+  mode: z.enum(['detail', 'banner']).default('detail'),
+  /** bar（线性进度条，默认）| steps（圆形步骤节点，适合联单任务） */
+  progressStyle: z.enum(['bar', 'steps']).default('bar'),
+  /** 参与步骤（联单活动 guide.steps；banner 模式用于渲染步骤进度节点） */
+  steps: z.array(z.object({ title: z.string(), description: z.string().optional() })).optional(),
+});
+export type PromotionBumpInActivityCardData = z.infer<typeof promotionBumpInActivityCardDataSchema>;
+
+export const alipayActivityCardDataSchemas = {
+  'promotion-bumpin-activity': promotionBumpInActivityCardDataSchema,
+} as const;
+
+export type AlipayActivityCardType = keyof typeof alipayActivityCardDataSchemas;

package/src/assembly.ts

@@ -0,0 +1,159 @@
+/**
+ * 商圈装配器（011 B2：TIER1 领域运行时）：
+ * 纯函数——extractScopeKey/validateScope/extractMallScope，
+ * SDK 原语（ScopeSessionRegistry/ProviderRegistry）组合在模板装配点完成（011 L1）。
+ *
+ * 不 import app-sdk（依赖方向：contracts-mall → contracts；SDK 不依赖 TIER1）。
+ *
+ * integrations v4 恒动态：参考表（instances 注册表）纯元数据，永不充当解析闸门——
+ * 白名单/动态判定（dynamicMalls/mallIdAllowed）退役。任意合法拓扑形态（注册表缺席/非空）
+ * 均支持动态 mallId 会话；实例集限制是 provider 业务限制的表达位（槽 instances 激活表
+ * 显式键集 → 数据面 INSTANCE_NOT_FOUND），非框架限制。WS/HTTP 两形态共享单一形状守卫核。
+ */
+import type { RequestContext, ScopeAssemblyContract } from '@tbox.cn/app-contracts';
+import type { MallDeploymentControlPlane } from './deployment';
+import {
+  extractMallScope,
+  parseMallScope,
+  MALL_SCOPE_KEY,
+  type MallScope,
+} from './scope';
+
+/**
+ * mall 域登录换码槽（integrations services 键；TIER1 拥有 mall 域槽位词汇——
+ * provider 包与模板装配点经本常量收敛，禁止各处拼写 'auth.alipay-login' 字面量）。
+ */
+export const AUTH_LOGIN_SERVICE = 'auth.alipay-login';
+
+/**
+ * mall 域装配形状（TIER0 ScopeAssemblyContract 的 TIER1 具体化；W3-3 自 module-mall-core 下沉）：
+ * module-mall-core register 期注册于 ctx.domainAssemblies（SCOPE_ASSEMBLY_KIND），
+ * 消费方（模板装配点/module-mall-home/SDK）按本类型泛型断言查表——域模块间零包依赖
+ * （workspace-dag 铁律：跨模块走注册表 + 契约类型）。
+ * 成员 = 模板装配点（validateContext/scopeSessions/start 装点/WS 双钩）最小必要性合集。
+ */
+export interface MallScopeAssembly extends ScopeAssemblyContract {
+  /** 控制平面（只读快照；纯元数据参考表——展示/目录/默认解析消费，非闸门） */
+  readonly controlPlane: Readonly<MallDeploymentControlPlane>;
+  /** root config.miniAppId（登录槽 code2Session 入参真源；enhance 回填 + default 兜底共用） */
+  readonly rootMiniAppId: string | undefined;
+  /** scope 键提取（SDK ScopeSessionRegistry 注入点） */
+  extractScopeKey(ctx: RequestContext): string;
+  /** scope 形状校验（SDK ScopeSessionRegistry 注入点 + HTTP validateContext 同核） */
+  validateScope(attributes: Record<string, unknown>): boolean;
+  /** 提取 MallScope（模块 handler 前置；无 scope → undefined 由调用方降级） */
+  extractMallScope(ctx: RequestContext): MallScope | undefined;
+  /** 领域扁平 scope（原始形态；ActionGrant/memory 隔离等消费） */
+  buildScope(attributes: Record<string, unknown>): Record<string, string>;
+  /** 扁平 scope + mallName 回填（scopeSessions 注入点；三级回退见 withMallName） */
+  buildScopeWithMallName(attributes: Record<string, unknown>): Record<string, string>;
+  /** instanceId 提取（integrations 槽解析轴；SDK 零领域注入点） */
+  instanceIdOf(scope: Record<string, string>): string;
+  /** 域默认值（SDK ctx.scopeDefaults 视图唯一直接消费面） */
+  readonly scopeDefaults: Readonly<Record<string, unknown>> | undefined;
+  /** 016：默认商圈 HELLO context（无 URL 参数访问时的服务端兜底；缺省 defaultMallId → undefined） */
+  defaultMallContext(): Record<string, unknown> | undefined;
+  /** D1：ENHANCE_CTX 双职责（miniAppId 回填 + mall.info 预热；fail-soft——抛错/超时原 context 继续） */
+  enhanceHelloContext(context: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+/**
+ * 形状守卫核（WS/HTTP 两形态共享单一来源）：
+ * - mall 键缺席 → true（非 mall 部署/无 context 放行——校验面不因缺 mall 拒绝；
+ *   '' scopeKey = 全局会话）；
+ * - mall 键在场 → mallId 非空串（会话边界键唯一硬要求；miniAppId 可选——
+ *   客户端发送侧本就条件附加，v4 起服务端不再要求）。
+ */
+export function isValidMallShape(attributes: Record<string, unknown>): boolean {
+  const mall = attributes[MALL_SCOPE_KEY];
+  if (!mall || typeof mall !== 'object') return true;
+  const mallId = (mall as Record<string, unknown>).mallId;
+  return typeof mallId === 'string' && mallId.length > 0;
+}
+
+/** 装配器产物：模板注入 createScopeSessionRegistry 的 extractor/validator + 领域提取函数 */
+export interface MallRuntimeAssembly {
+  /**
+   * scope 键提取（SDK ScopeSessionRegistry 注入点）：
+   * mall scope 在场 → mallId；防御兜底 ''（主通路：无 mall context 不触发 bootstrap，
+   * 本函数不会被无 scope 会话调用）。
+   */
+  extractScopeKey(ctx: RequestContext): string;
+  /** scope 形状校验（SDK ScopeSessionRegistry 注入点）：单一形状守卫核（白名单判定已退役） */
+  validateScope(attributes: Record<string, unknown>): boolean;
+  /** 011 D1：领域扁平 scope（回显 + ActionGrant 签发/校验单一来源） */
+  buildScope(attributes: Record<string, unknown>): Record<string, string>;
+  /** 提取 MallScope（模块 handler 前置；无 scope → undefined 由调用方降级） */
+  extractMallScope(ctx: RequestContext): MallScope | undefined;
+  /** 控制平面（只读快照；纯元数据参考表——展示/目录/默认解析消费，非闸门） */
+  controlPlane: Readonly<MallDeploymentControlPlane>;
+}
+
+export function createMallRuntimeAssembly(
+  controlPlane: MallDeploymentControlPlane,
+): MallRuntimeAssembly {
+  return {
+    extractScopeKey(ctx: RequestContext): string {
+      // 防御兜底 ''（全局会话）：主通路中无 mall context 的连接不触发 bootstrap（ws-server 语义），
+      // 有 mall context 则 mallId 必非空（isValidMallShape 已守卫）
+      const scope = extractMallScope(ctx);
+      return scope?.mallId ?? '';
+    },
+    validateScope(attributes: Record<string, unknown>): boolean {
+      // 形状不过（mall 键在场但 mallId 缺失/空）→ console.error 提示配置排查方向
+      const ok = isValidMallShape(attributes);
+      if (!ok) {
+        console.error(
+          '[MALL] HELLO context 形状非法（需 mall.mallId 非空——URL 参数 ?mallId=；miniAppId 可选）',
+        );
+      }
+      return ok;
+    },
+    buildScope(attributes: Record<string, unknown>): Record<string, string> {
+      const scope = parseMallScope(attributes);
+      if (!scope) return {};
+      // miniAppId 可选：按在场透传（ActionGrant 签发/校验双端同构——同函数双调用，形状天然一致）
+      return {
+        mallId: scope.mallId,
+        ...(scope.miniAppId !== undefined ? { miniAppId: scope.miniAppId } : {}),
+      };
+    },
+    extractMallScope,
+    controlPlane,
+  };
+}
+
+/**
+ * HTTP validateContext 形态（上下文统一化全局面注入点）：与 WS validateScope
+ * 共享同一形状守卫核（isValidMallShape）——单一来源，勿再分叉。
+ * HTTP 面消费 mallId-only 形状（login/dev-login 的 body.context 有独立归一化，
+ * 不套 MallScope 全形状）；miniAppId 不要求（消费点自补：linked-panel 自查表；
+ * WS 面由 enhanceContext 补——两形态不对称有内在一致性，勿补对称）。
+ */
+export function createMallContextValidator(): (attributes: Record<string, unknown>) => boolean {
+  return isValidMallShape;
+}
+
+/**
+ * 014 T1：buildScope 包装——从控制平面参考表回填 mallName（自 mall 模板 deployment.ts
+ * 迁入，单一模板统一化 W1-①）。
+ * scopeFlat（mallId[+miniAppId]）→ HELLO_ACK.mallScope 回显，mallName 为壳品牌区
+ * （ChatHeader）服务端真源。
+ *
+ * 三级回退（动态商场）：参考表命中 → mall.name；未命中 → fallbackName?.(mallId)
+ * （mall.info 槽缓存）→ 双 miss 原样返回（降级）。
+ */
+export function withMallName(
+  assembly: MallRuntimeAssembly,
+  controlPlane: MallDeploymentControlPlane,
+  fallbackName?: (mallId: string) => string | undefined,
+): (attributes: Record<string, unknown>) => Record<string, string> {
+  return (attributes) => {
+    const scope = assembly.buildScope(attributes);
+    const mallId = parseMallScope(attributes)?.mallId;
+    const mall = mallId ? controlPlane.malls.find((m) => m.mallId === mallId) : undefined;
+    if (mall) return { ...scope, mallName: mall.name };
+    const fallback = mallId ? fallbackName?.(mallId) : undefined;
+    return fallback ? { ...scope, mallName: fallback } : scope;
+  };
+}

package/src/deployment.ts

@@ -0,0 +1,44 @@
+/**
+ * 商圈部署控制平面（纯 mall 域两键：零重复收敛）：
+ * malls（参考表——纯元数据，v4 起永不充当解析闸门）+ defaultMallId（默认商圈）。
+ * 构造来源 = mallControlPlaneOf 投影（server/mall-control-plane.ts）：root instances
+ * 注册表（integrations v4）→ 本形状；无参考表 → 空平面（模板装配零拓扑分支）。
+ * provider 绑定唯一真源 = config/integrations.json（integrations v4：绑定组整组继承 + catalog 派生，
+ * 真源 providers.md）——控制面不再承载
+ * providerTemplates/providerInstances（换码走 resolveLoginExchange、旁路 bumpin 走
+ * config/bumpin.json 配置面）。无内联密钥（loader 断言在模板层）。
+ * 014：deployment（miniAppId/agentId/components）整体移除——零消费方（代码即事实），
+ * 能力开关 = 模块 add/remove，非部署级 feature 裁剪。
+ */
+
+/** 商圈白名单项 */
+export interface MallDeploymentMall {
+  mallId: string;
+  name: string;
+  /** 客服电话（可选；shopping-guide customer-service-faq 卡 link 拨打条目消费，缺省不渲染） */
+  contactPhone?: string;
+  /** 小程序 appId（可选拓扑值；mall 级共享——HELLO context.mall.miniAppId 的配置承载，供默认商圈拼装） */
+  miniAppId?: string;
+  /**
+   * 地理坐标（可选；有值时参与 /api/m/mall-home/nearby-mall 就近推荐；缺省不参与排序）。
+   * 坐标系：WGS-84（高德/支付宝 getLocation 默认输出）。
+   */
+  location?: {
+    lat: number;
+    lon: number;
+    /** 展示地址（可选；推荐 Banner 展示用） */
+    address?: string;
+  };
+}
+
+/** 部署控制平面（mallControlPlaneOf 投影产物；provider 绑定迁 integrations 后纯两键） */
+export interface MallDeploymentControlPlane {
+  /** 商圈参考表（纯元数据：目录/展示/默认解析；v4 起非会话闸门） */
+  malls: MallDeploymentMall[];
+  /**
+   * 默认商圈（可选）：无 URL 参数访问时服务端补入 HELLO context 的 mallId。
+   * 来源 = normalizeInstances（显式 ?? 单实例唯一解）；参考表缺席时仍可在场
+   * （env 注入动态默认形态——defaultInstanceId 独立键）；URL 显式参数优先级更高。
+   */
+  defaultMallId?: string;
+}

package/src/domain/activity.ts

@@ -0,0 +1,66 @@
+/**
+ * 营销活动域模型（015，TIER1）：活动聚合 + 场次 + 参与指南。
+ */
+
+export interface PromotionActivity {
+  /** 报名/详情深链（provider 出参快照，数据驱动；缺省 = 无报名通道） */
+  registrationUrl?: string;
+  readonly activityRef: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly coverUrl?: string;
+  readonly categoryId?: string;
+  /** 是否需要报名 */
+  readonly registrationRequired: boolean;
+  /** 剩余名额（厂商事实，可缺省） */
+  readonly remainingQuota?: number;
+  readonly startAt?: string;
+  readonly endAt?: string;
+  /** 活动关联 Offer（可领取优惠券等） */
+  readonly offerRefs: readonly string[];
+  /**
+   * 联单/累计型活动（N 笔累计解锁奖励；卡片走 steps 进度形态）。
+   * 厂商中立语义标志：由 provider 按厂商侧活动类型枚举映射（如支付宝 actType=N_COUNT_TYPE），
+   * 消费方不得用标题关键字自行判定。
+   */
+  readonly linkedOrder?: boolean;
+  /**
+   * 活动生命周期状态（厂商侧枚举经 provider 映射为中立语义，如支付宝碰出惊喜
+   * NOT_START/INIT/PROCESSING/FINISH/RECEIVED）。缺省 = 无法判定，消费方按进行中兜底展示。
+   */
+  readonly activityStatus?: string;
+  /** 首页资源位没有独立详情时为 true；用于调整卡片文案而不改变历史活动语义。 */
+  readonly jumpOnly?: boolean;
+  /** 资源位跳转按钮文案，缺省由卡片按活动/资源位语义生成。 */
+  readonly jumpLabel?: string;
+}
+
+export interface PromotionActivityPage {
+  readonly items: readonly PromotionActivity[];
+  readonly nextCursor?: string;
+  readonly hasMore: boolean;
+}
+
+/** 活动场次 */
+export interface ActivitySession {
+  readonly sessionRef: string;
+  readonly title: string;
+  readonly startAt: string;
+  readonly endAt?: string;
+  readonly location?: string;
+  readonly remainingQuota?: number;
+  readonly status: 'OPEN' | 'FULL' | 'CLOSED' | 'UNKNOWN';
+}
+
+/** 参与指南（步骤 + 条款） */
+export interface ActivityGuide {
+  readonly steps: ReadonlyArray<{ readonly title: string; readonly description?: string }>;
+  readonly conditions: readonly string[];
+  readonly notice?: string;
+}
+
+export interface PromotionActivityDetail extends PromotionActivity {
+  readonly description?: string;
+  readonly sessions: readonly ActivitySession[];
+  readonly guide?: ActivityGuide;
+}

package/src/domain/coupon.ts

@@ -0,0 +1,11 @@
+/** 优惠券（商圈领域 DTO） */
+export interface Coupon {
+  couponId: string;
+  title: string;
+  /** 可抵扣金额（元） */
+  amount: number;
+  status: 'AVAILABLE' | 'USED' | 'EXPIRED';
+}
+
+/** 免费券领取通道；缺省由消费方保持既有直领语义。 */
+export type FreeCouponClaimMode = 'DIRECT' | 'REDIRECT';

package/src/domain/discount.ts

@@ -0,0 +1,6 @@
+/** 折扣规则（商圈领域 DTO） */
+export interface DiscountRule {
+  level: 'silver' | 'gold' | 'platinum';
+  /** 折扣率 0-1（0.9 = 9 折） */
+  discount: number;
+}

package/src/domain/entitlement.ts

@@ -0,0 +1,56 @@
+/**
+ * 营销权益（已领取资产）域模型（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/src/domain/offer.ts

@@ -0,0 +1,120 @@
+/**
+ * 营销 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/src/domain/operation.ts

@@ -0,0 +1,40 @@
+/**
+ * 营销写操作域模型（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';