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

package/README.md

@@ -1,6 +1,6 @@
 # @tbox.cn/app-contracts-mall
 
-商圈领域契约（TIER1，types-only）：Port 接口 + MallEventMap + 领域 DTO。
+商圈领域契约与运行时（TIER1）：Port 接口 + MallEventMap + 领域 DTO + runtime 装配器 + 签名策略。
 
 ## 安装
 
@@ -8,6 +8,20 @@
 pnpm add @tbox.cn/app-contracts-mall
 ```
 
+发布包同时提供两种消费形态：直接安装使用 `dist` 编译产物；模板中的 `@app/contracts-mall` shim 默认转发发布包，`tbox-app module add` 自动依赖本包时将其替换为本地源码包。显式使用 `--mode sdk` 时仍保持发布态消费。
+
+## 入口
+
+- `@tbox.cn/app-contracts-mall` — 领域类型与 Port（模块消费面）
+- `@tbox.cn/app-contracts-mall/runtime` — runtime：`createMallRuntimeAssembly` 装配器、
+  `createInMemoryStateStore`、`createScopeSessionRegistry`、Provider 四件、
+  `createActionGrantService` / `createModuleActionDispatcher` / `createEffectRuntime`、
+  knowledge/payment client（tsup 出 `dist/runtime.js`）
+- `@tbox.cn/app-contracts-mall/server` — server-only 请求凭证读取助手
+  （`request-credentials.ts`：credentialsToken / credentialsMemberId / credentialsOpenId；
+  登录换码器已归 provider 包，见 `@tbox.cn/app-provider-<vendor>/server` 系列）
+
 ## 说明
 
-商圈业务契约类型真源包；消费方经 `@tbox.cn/app-contracts-mall` 公开入口引用。
+商圈业务语义唯一真源（MallScope zod 解析 + 领域卡 schema/Port）；模块只消费本包，
+不 import SDK 内部路径。分层判据见仓库 [Provider 与集成参考](../../docs/reference/providers.md)。

package/dist/alipay-activity/cards.d.ts

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

package/dist/assembly.d.ts

@@ -4,26 +4,51 @@
  * 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 } from '@tbox.cn/app-contracts';
 import type { MallDeploymentControlPlane } from './deployment';
-import { type MallScope, type MallRequestContext } from './scope';
+import { type MallScope } from './scope';
+/**
+ * mall 域登录换码槽（integrations services 键；TIER1 拥有 mall 域槽位词汇——
+ * provider 包与模板装配点经本常量收敛，禁止各处拼写 'auth.alipay-login' 字面量）。
+ */
+export declare const AUTH_LOGIN_SERVICE = "auth.alipay-login";
+/**
+ * 形状守卫核（WS/HTTP 两形态共享单一来源）：
+ * - mall 键缺席 → true（非 mall 部署/无 context 放行——校验面不因缺 mall 拒绝；
+ *   '' scopeKey = 全局会话）；
+ * - mall 键在场 → mallId 非空串（会话边界键唯一硬要求；miniAppId 可选——
+ *   客户端发送侧本就条件附加，v4 起服务端不再要求）。
+ */
+export declare function isValidMallShape(attributes: Record<string, unknown>): boolean;
 /** 装配器产物：模板注入 createScopeSessionRegistry 的 extractor/validator + 领域提取函数 */
 export interface MallRuntimeAssembly {
     /**
      * scope 键提取（SDK ScopeSessionRegistry 注入点）：
-     * 无 mall scope → 抛 'Mall scope is required'（非 mall 部署不应装载本装配器）。
+     * mall scope 在场 → mallId；防御兜底 ''（主通路：无 mall context 不触发 bootstrap，
+     * 本函数不会被无 scope 会话调用）。
      */
     extractScopeKey(ctx: RequestContext): string;
-    /** scope 白名单校验（SDK ScopeSessionRegistry 注入点）：parseMallScope 成功且 mallId ∈ malls */
+    /** 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;
-    /** 提取必在 MallScope（调用方已确认存在） */
-    requireMallScope(ctx: MallRequestContext): MallScope;
-    /** 控制平面（只读快照） */
+    /** 控制平面（只读快照；纯元数据参考表——展示/目录/默认解析消费，非闸门） */
     controlPlane: Readonly<MallDeploymentControlPlane>;
 }
 export declare function createMallRuntimeAssembly(controlPlane: MallDeploymentControlPlane): MallRuntimeAssembly;
+/**
+ * HTTP validateContext 形态（上下文统一化全局面注入点）：与 WS validateScope
+ * 共享同一形状守卫核（isValidMallShape）——单一来源，勿再分叉。
+ * HTTP 面消费 mallId-only 形状（login/dev-login 的 body.context 有独立归一化，
+ * 不套 MallScope 全形状）；miniAppId 不要求（消费点自补：linked-panel 自查表；
+ * WS 面由 enhanceContext 补——两形态不对称有内在一致性，勿补对称）。
+ */
+export declare function createMallContextValidator(): (attributes: Record<string, unknown>) => boolean;

package/dist/chunk-KIZD6FZ2.js

@@ -0,0 +1,43 @@
+// src/scope.ts
+import { z } from "zod";
+import { defineContextSlot } from "@tbox.cn/app-contracts";
+var MALL_SCOPE_KEY = "mall";
+var mallScopeSchema = z.object({
+  miniAppId: z.string().min(1).optional(),
+  mallId: z.string().min(1),
+  subjectId: z.string().optional()
+});
+var mallSlot = defineContextSlot({
+  key: MALL_SCOPE_KEY,
+  parse: (raw) => {
+    if (!raw || typeof raw !== "object") return void 0;
+    const result = mallScopeSchema.safeParse(raw);
+    return result.success ? result.data : void 0;
+  }
+});
+function parseMallScope(attributes) {
+  return mallSlot.read(attributes);
+}
+function extractMallScope(ctx) {
+  return parseMallScope(ctx.attributes);
+}
+function mallScopeOf(reqCtx) {
+  const mallId = parseMallScope(reqCtx.attributes ?? {})?.mallId;
+  return mallId ? { mallId } : {};
+}
+function readLoginMallId(context) {
+  const mall = context?.[MALL_SCOPE_KEY];
+  if (!mall || typeof mall !== "object") return void 0;
+  const mallId = mall.mallId;
+  return typeof mallId === "string" && mallId.length > 0 ? mallId : void 0;
+}
+
+export {
+  MALL_SCOPE_KEY,
+  mallScopeSchema,
+  mallSlot,
+  parseMallScope,
+  extractMallScope,
+  mallScopeOf,
+  readLoginMallId
+};

package/dist/deployment.d.ts

@@ -1,43 +1,42 @@
 /**
- * 商圈部署控制平面（011 L2：三段配置的类型真源）：
- * deployment（小程序/agent/组件清单）+ malls（白名单）+ providerInstances（外部服务实例）。
- * 无内联密钥（loader 断言在模板层，见 011 L2）。
+ * 商圈部署控制平面（纯 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 裁剪。
  */
-import type { ProviderInstance } from '@tbox.cn/app-contracts';
-/** 组件启用项：componentId + 可选 feature 子集（feature 门控 = 运行时护栏，非装配期裁剪，011 D10） */
-export interface MallDeploymentComponent {
-    componentId: string;
-    /** 启用 feature（⊆ 模块 declaration.features，doctor feature-declaration 校验） */
-    enabledFeatures?: string[];
-    /** 可选组件：未安装该模块时 doctor 降级 warning（缺省 false = 必须安装） */
-    optional?: boolean;
-}
 /** 商圈白名单项 */
 export interface MallDeploymentMall {
     mallId: string;
     name: string;
+    /** 客服电话（可选；shopping-guide customer-service-faq 卡 link 拨打条目消费，缺省不渲染） */
+    contactPhone?: string;
+    /** 小程序 appId（可选拓扑值；mall 级共享——HELLO context.mall.miniAppId 的配置承载，供默认商圈拼装） */
+    miniAppId?: string;
+    /**
+     * 地理坐标（可选；有值时参与 /api/nearby-mall 就近推荐；缺省不参与排序）。
+     * 坐标系：WGS-84（高德/支付宝 getLocation 默认输出）。
+     */
+    location?: {
+        lat: number;
+        lon: number;
+        /** 展示地址（可选；推荐 Banner 展示用） */
+        address?: string;
+    };
 }
-/** Provider 模版声明（011 评审 7.1：credentialType 真源参数化，模板装配不再硬编码商家类型） */
-export interface MallDeploymentProviderTemplate {
-    /** 'id@version'（与 ProviderInstance.providerTemplateId 匹配） */
-    providerTemplateId: string;
-    /** 认证类型（ProviderAuthStrategy.credentialType 注册点匹配键） */
-    credentialType: string;
-}
-/** 部署控制平面（部署配置 JSON 的形状） */
+/** 部署控制平面（mallControlPlaneOf 投影产物；provider 绑定迁 integrations 后纯两键） */
 export interface MallDeploymentControlPlane {
-    deployment: {
-        /** 小程序 appId */
-        miniAppId: string;
-        /** agent 实例 id */
-        agentId: string;
-        /** 组件清单（与已装模块对账，doctor deployment-consistency） */
-        components: MallDeploymentComponent[];
-    };
-    /** 商圈白名单（validateScope 依据） */
+    /** 商圈参考表（纯元数据：目录/展示/默认解析；v4 起非会话闸门） */
     malls: MallDeploymentMall[];
-    /** Provider 模版声明（可选；缺省由模板装配从实例派生） */
-    providerTemplates?: MallDeploymentProviderTemplate[];
-    /** Provider 实例（三段之三；机密走 credentialRef，禁内联密钥） */
-    providerInstances: ProviderInstance[];
+    /**
+     * 默认商圈（可选）：无 URL 参数访问时服务端补入 HELLO context 的 mallId。
+     * 来源 = normalizeInstances（显式 ?? 单实例唯一解）；参考表缺席时仍可在场
+     * （env 注入动态默认形态——defaultInstanceId 独立键）；URL 显式参数优先级更高。
+     */
+    defaultMallId?: string;
 }

package/dist/domain/activity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 营销活动域模型（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/dist/domain/coupon.d.ts

@@ -6,3 +6,5 @@ export interface Coupon {
     amount: number;
     status: 'AVAILABLE' | 'USED' | 'EXPIRED';
 }
+/** 免费券领取通道；缺省由消费方保持既有直领语义。 */
+export type FreeCouponClaimMode = 'DIRECT' | 'REDIRECT';

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;
+}