@tbox.cn/app-module-promotion 0.2.0 → 0.9.4

package/tests/promotion.test.ts

@@ -0,0 +1,976 @@
+/**
+ * 015 S6：promotion 测试。
+ * - acquire 闭环（重复点击交由 Provider / member.status 会员门禁八态 / 三态卡 / 业务错误透传）
+ * - InMemory 四 Port 演示语义
+ * - M1' 承接：listEntitlements itemAction value（话术锚定券名）+ 工具描述分工断言
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+// mock ports 服务解析（tool 内部 import；缺省回真实 InMemory 单例——actions 层 monkey-patch 用例不破）
+vi.mock('../src/server/ports', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../src/server/ports')>();
+  const fallback = vi.fn(async () => actual.inMemoryPromotion);
+  return {
+    ...actual,
+    resolvePromotionOffersPort: fallback,
+    resolvePromotionEntitlementsPort: fallback,
+    resolvePromotionActivitiesPort: fallback,
+    resolvePromotionAcquisitionPort: fallback,
+  };
+});
+
+import {
+  promotionActivityListCardDataSchema,
+  promotionEntitlementListCardDataSchema,
+} from '@tbox.cn/app-contracts-mall';
+import { InMemoryPromotionService } from '../src/server/service';
+import { classifyRejection, createPromotionActions } from '../src/server/actions';
+import { inMemoryPromotion } from '../src/server/ports';
+import {
+  resolvePromotionOffersPort,
+  resolvePromotionEntitlementsPort,
+  resolvePromotionActivitiesPort,
+  resolvePromotionAcquisitionPort,
+} from '../src/server/ports';
+
+/** 四槽 resolver 持久注入（跨多次解析保持；vi.clearAllMocks 复位） */
+const mockAllSlotsPersist = (service: unknown) => {
+  vi.mocked(resolvePromotionOffersPort).mockResolvedValue(service as never);
+  vi.mocked(resolvePromotionEntitlementsPort).mockResolvedValue(service as never);
+  vi.mocked(resolvePromotionActivitiesPort).mockResolvedValue(service as never);
+  vi.mocked(resolvePromotionAcquisitionPort).mockResolvedValue(service as never);
+};
+
+/** 四槽 resolver 统一注入（017 槽位原子化：工具/动作按语义选槽，测试恒全注入） */
+const mockAllSlots = (service: unknown) => {
+  vi.mocked(resolvePromotionOffersPort).mockResolvedValueOnce(service as never);
+  vi.mocked(resolvePromotionEntitlementsPort).mockResolvedValueOnce(service as never);
+  vi.mocked(resolvePromotionActivitiesPort).mockResolvedValueOnce(service as never);
+  vi.mocked(resolvePromotionAcquisitionPort).mockResolvedValueOnce(service as never);
+};
+import { createPromotionTools, offerDetail, offerSummary } from '../src/server/tools';
+import { createPromotionIntentHandler, PROMOTION_INTENTS } from '../src/server/handler';
+import { createServerContext, createToolExecContext, matchIntent } from '@tbox.cn/app-sdk/server';
+import type { IntentRoute } from '@tbox.cn/app-sdk/server';
+
+const q = { scope: { miniAppId: 'app', mallId: 'mall-1' }, subjectId: 'u_1' } as never;
+
+/** 上下文统一化：显式缝——reqCtx 由调用方透传（handle 第四参 / 工具 execute 第二参） */
+const testRequestContext = (userId = 'u_1') => ({
+  identity: { userId, source: 'dev' as const },
+  attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } },
+});
+
+function createPromotionTestContext(_userId = 'u_1') {
+  return createServerContext();
+}
+
+/** 外层意图路由测试表（镜像 collectIntentRoutes 装配语义：keywords/match 同源 + 导航前缀路由） */
+const PROMOTION_TEST_ROUTES: IntentRoute[] = [
+  ...Object.entries(PROMOTION_INTENTS).map(
+    ([kind, intent]) => ({
+      id: `promotion:${intent.patterns[0]}`,
+      keywords: [...intent.patterns],
+      handlerId: 'promotion',
+      action: kind,
+      match: 'exact' as const,
+    }),
+  ),
+  { id: 'promotion:navigation-prefix', keywords: ['查看「'], handlerId: 'promotion', action: 'intent', match: 'prefix' as const },
+];
+
+/** 意图可连性（顶层确定性档：exact 整句全等 + 导航模板句头 prefix 命中） */
+function expectPromotionIntentRoutable(query: string) {
+  expect(matchIntent(PROMOTION_TEST_ROUTES, query)?.handlerId).toBe('promotion');
+}
+
+describe('InMemoryPromotionService', () => {
+  it('projects provider C-end coupon display facts into both card shapes', () => {
+    const offer = {
+      offerRef: 'o1', title: '券', offerType: 'COUPON' as const, tags: [],
+      validity: { end: '' }, facets: [], availability: { status: 'AVAILABLE' as const, reasonCodes: [], evaluatedAt: '', authoritative: true },
+      priceText: '免费', originalPriceText: '¥50', discountLabel: '5折', claimActionLabel: '领取',
+      purchaseUrl: 'alipays://platformapi/startapp?appId=demo&page=coupon', freeCouponClaimMode: 'REDIRECT' as const,
+      stockText: '剩余：42', usageSceneText: '小程序扫码买单', guaranteeText: '随时退·过期自动退',
+    };
+    expect(offerSummary(offer)).toMatchObject({ priceText: '免费', originalPriceText: '¥50', discountLabel: '5折', claimActionLabel: '领取', purchaseUrl: 'alipays://platformapi/startapp?appId=demo&page=coupon', freeCouponClaimMode: 'REDIRECT', stockText: '剩余：42', usageSceneText: '小程序扫码买单', guaranteeText: '随时退·过期自动退' });
+    expect(offerDetail(offer, true, 'coupon')).toMatchObject({ priceText: '免费', originalPriceText: '¥50', discountLabel: '5折', claimActionLabel: '领取', stockText: '剩余：42', usageSceneText: '小程序扫码买单', guaranteeText: '随时退·过期自动退' });
+  });
+
+  it('does not render a missing coupon threshold as 满0减', () => {
+    const summary = offerSummary({
+      offerRef: 'o-no-threshold', title: '无门槛券', offerType: 'COUPON', tags: [], validity: { end: '' },
+      facets: [{ kind: 'COUPON', discountType: 'AMOUNT', value: 5500 }],
+      availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: '', authoritative: true },
+    });
+    expect(summary.benefitText).toBe('¥55');
+    expect(summary).not.toHaveProperty('thresholdText');
+  });
+
+  it('保留优惠金额的小数精度，避免 LLM 摘要丢失金额', () => {
+    const summary = offerSummary({
+      offerRef: 'o-five-cents', title: '小额券', offerType: 'COUPON', tags: [], validity: { end: '' },
+      facets: [{ kind: 'COUPON', discountType: 'AMOUNT', value: 5, thresholdCents: 5 }],
+      availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: '', authoritative: true },
+    });
+    expect(summary).toMatchObject({ benefitText: '满 0.05 减 0.05 元', thresholdText: '满 0.05 元可用' });
+  });
+
+  it('prefers provider validity text over the fixed date range', () => {
+    const summary = offerSummary({
+      offerRef: 'o-relative-validity', title: '领取后有效', offerType: 'COUPON', tags: [],
+      validity: { start: '2026-09-03', end: '2027-01-07' }, validityText: '含领取之日起7天内有效',
+      facets: [], availability: { status: 'AVAILABLE', reasonCodes: [], evaluatedAt: '', authoritative: true },
+    });
+    expect(summary.validityText).toBe('含领取之日起7天内有效');
+  });
+
+  it('搜索/详情/推荐', async () => {
+    const service = new InMemoryPromotionService();
+    const page = await service.searchOffers(q, { keyword: '餐饮' });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((o) => o.title.includes('餐饮') || o.tags.some((t) => t.includes('餐饮')))).toBe(true);
+
+    const detail = await service.getOfferDetail(q, { offerRef: 'demo:coupon:1001' });
+    expect(detail?.title).toContain('满 100 减 20');
+    expect(detail?.facets[0]).toMatchObject({ kind: 'COUPON', discountType: 'AMOUNT', value: 2000 });
+
+    const keywordFallback = await service.getOfferDetail(q, { keyword: '团购' });
+    expect(keywordFallback?.offerType).toBe('GROUPON');
+
+    const recommended = await service.recommendOffers(q, {});
+    expect(recommended.length).toBeLessThanOrEqual(3);
+  });
+
+  it('最优测算：AMOUNT 与 PERCENTAGE 门槛过滤', async () => {
+    const service = new InMemoryPromotionService();
+    const under = await service.calculateBestDeal(q, { currentAmountCents: 5000 });
+    expect(under.estimatedSavingCents).toBeGreaterThan(0); // 餐饮 85 折满 50 可用
+    const over = await service.calculateBestDeal(q, { currentAmountCents: 20000 });
+    expect(over.estimatedSavingCents).toBe(3000); // 85 折省 30 元 > 满 100 减 20
+  });
+
+  it('厂商未提供测算能力时只返回文字，不出优惠测算卡', async () => {
+    const service = {
+      supportsBestDeal: false,
+      searchOffers: vi.fn(async () => ({ items: [], hasMore: false })),
+    };
+    mockAllSlots(service);
+    const tools = createPromotionTools({ getCtx: () => createServerContext() });
+    const result = await tools.calculateBestDeal.execute!(
+      { currentAmountCents: '32800' },
+      createToolExecContext(testRequestContext()) as never,
+    ) as { supported?: boolean; cards?: unknown[]; message?: string };
+    expect(result).toMatchObject({ supported: false, message: '当前商场暂不支持优惠测算，请在结算页确认最终优惠' });
+    expect(result.cards).toBeUndefined();
+    expect(service.searchOffers).not.toHaveBeenCalled();
+    vi.mocked(resolvePromotionOffersPort).mockReset(); vi.mocked(resolvePromotionEntitlementsPort).mockReset(); vi.mocked(resolvePromotionActivitiesPort).mockReset(); vi.mocked(resolvePromotionAcquisitionPort).mockReset();
+  });
+
+  it('厂商要求统一券列表时，推荐结果不进入旧 recommendation 展示分支', async () => {
+    const service = new InMemoryPromotionService();
+    Object.defineProperty(service, 'usesUnifiedCouponList', { value: true });
+    mockAllSlots(service);
+    const tools = createPromotionTools({ getCtx: () => createServerContext() });
+    const result = await tools.recommendOffers.execute!(
+      {},
+      createToolExecContext(testRequestContext()) as never,
+    ) as { presentation?: string; mode?: string; cards?: { cardType: string; data: { presentation?: string; mode?: string } }[] };
+    expect(result).toMatchObject({
+      presentation: 'coupon',
+      mode: 'claimable',
+      cards: [{ cardType: 'promotion-offer-list', data: { presentation: 'coupon', mode: 'claimable' } }],
+    });
+    vi.mocked(resolvePromotionOffersPort).mockReset(); vi.mocked(resolvePromotionEntitlementsPort).mockReset(); vi.mocked(resolvePromotionActivitiesPort).mockReset(); vi.mocked(resolvePromotionAcquisitionPort).mockReset();
+  });
+
+  it('acquire 幂等 + entitlement 落账', async () => {
+    const service = new InMemoryPromotionService();
+    const key = 'idem-1';
+    const first = await service.acquire(q, { offerRef: 'demo:coupon:1001', externalMemberRef: 'member-ref:abc', idempotencyKey: key });
+    expect(first.status).toBe('SUCCEEDED');
+    const second = await service.acquire(q, { offerRef: 'demo:coupon:1001', externalMemberRef: 'member-ref:abc', idempotencyKey: key });
+    expect(second.operationRef).toBe(first.operationRef); // 幂等返回首果
+
+    const ents = await service.listEntitlements(q, {});
+    expect(ents.items).toHaveLength(1);
+    expect(ents.items[0]!.codeMasked).toContain('**');
+
+    const bad = await service.acquire(q, { offerRef: 'missing', externalMemberRef: 'm', idempotencyKey: 'k2' });
+    expect(bad.status).toBe('REJECTED');
+    expect(bad.code).toBe('30017');
+  });
+
+  it('活动列表与详情（场次/指南）', async () => {
+    const service = new InMemoryPromotionService();
+    const list = await service.listActivities(q, {});
+    expect(list.items).toHaveLength(1);
+    const detail = await service.getActivityDetail(q, list.items[0]!.activityRef);
+    expect(detail?.sessions).toHaveLength(2);
+    expect(detail?.guide?.conditions).toContain('限会员本人参与');
+  });
+});
+
+describe('legacy marketing 能力面', () => {
+  it('完整注册 17 个营销域工具（碰出惊喜 2 工具已迁出至 module-alipay-activity）', () => {
+    const tools = createPromotionTools({ getCtx: () => createServerContext() });
+    expect(Object.keys(tools)).toEqual([
+      'listActivityCategories',
+      'listActivities',
+      'getActivityDetail',
+      'listActivitySessions',
+      'getActivityGuide',
+      'searchOffers',
+      'getOfferDetail',
+      'listEntitlements',
+      'listPromotions',
+      'getPromotionDetail',
+      'getParticipationGuide',
+      'listCoupons',
+      'getPackageDetail',
+      'recommendOffers',
+      'calculateBestDeal',
+    ]);
+  });
+
+  it('领取 Action 绑定券列表与通用详情卡两处', () => {
+    const actions = createPromotionActions({} as never);
+    // 券走列表浮层（一卡多券，令牌必须可复用）；活动/礼包等非券优惠仍从详情卡领
+    expect(actions.acquireFromList.cardType).toBe('promotion-offer-list');
+    expect(actions.acquireFromList.singleUse).toBe(false);
+    expect(actions.acquire.cardType).toBe('promotion-offer-detail');
+    expect((actions as Record<string, unknown>).acquireConfirm).toBeUndefined();
+  });
+});
+
+describe('classifyRejection（已知码语义兜底）', () => {
+  it('保留源码中的已知错误分类，未知码仍使用通用兜底', () => {
+    expect(classifyRejection('636').kind).toBe('OUT_OF_STOCK');
+    expect(classifyRejection('637').kind).toBe('OUT_OF_STOCK');
+    expect(classifyRejection('638').kind).toBe('ALREADY_ACQUIRED');
+    expect(classifyRejection('5113').kind).toBe('ALREADY_ACQUIRED');
+    expect(classifyRejection('30017').kind).toBe('NOT_ELIGIBLE');
+    expect(classifyRejection('100408').kind).toBe('UNKNOWN');
+  });
+});
+
+describe('promotion 确定性意图路由', () => {
+  it('活动意图在专属策略下分流到联单活动 handler，其他 provider 保持原活动卡', async () => {
+    const ctx = createServerContext();
+    const alipayActivityHandler = {
+      id: 'alipay-activity',
+      intents: [],
+      handle: vi.fn(async (_action: string, _payload: unknown, _ctx: unknown, reqCtx: { credentials?: { provider?: string } }) =>
+        reqCtx.credentials?.provider === 'target'
+          ? { cards: [{ cardType: 'promotion-bumpin-activity', data: {} }], text: '联单活动' }
+          : { cards: [], continueWith: { content: '活动中心' } },
+      ),
+    };
+    ctx.handlers.register(alipayActivityHandler as never);
+    const handler = createPromotionIntentHandler(ctx);
+
+    const linked = await handler.handle('intent', { content: '活动中心' }, ctx, {
+      ...testRequestContext(),
+      credentials: { token: 'target-token', provider: 'target' },
+    });
+    expect(linked.cards[0]?.cardType).toBe('promotion-bumpin-activity');
+    expect(alipayActivityHandler.handle).toHaveBeenCalledWith('activity-router', expect.anything(), ctx, expect.objectContaining({
+      credentials: expect.objectContaining({ provider: 'target' }),
+    }));
+
+    const otherProvider = await handler.handle('intent', { content: '活动中心' }, ctx, {
+      ...testRequestContext(),
+      credentials: { token: 'other-token', provider: 'other' },
+    });
+    expect(otherProvider.cards[0]?.cardType).toBe('promotion-activity-list');
+  });
+
+  it('活动工具在专属策略下先分流，不依赖 promotion service 解析', async () => {
+    const ctx = createServerContext();
+    const alipayActivityHandler = {
+      id: 'alipay-activity',
+      intents: [],
+      handle: vi.fn(async () => ({
+        cards: [{ cardType: 'promotion-bumpin-activity', data: {} }],
+        text: '联单活动',
+      })),
+    };
+    ctx.handlers.register(alipayActivityHandler as never);
+    const resolveCallsBefore = vi.mocked(resolvePromotionActivitiesPort).mock.calls.length;
+    const tools = createPromotionTools({ getCtx: () => ctx });
+    const result = await tools.listActivities.execute!({}, createToolExecContext({
+      ...testRequestContext(),
+      credentials: { token: 'target-token', provider: 'target' },
+    }) as never);
+
+    expect(result).toMatchObject({ cards: [{ cardType: 'promotion-bumpin-activity' }] });
+    expect(vi.mocked(resolvePromotionActivitiesPort).mock.calls.length).toBe(resolveCallsBefore);
+    expect(alipayActivityHandler.handle).toHaveBeenCalledWith('activity-router', { content: '活动中心' }, ctx, expect.anything());
+  });
+
+  it('“最近有什么营销活动”只返回活动卡，不经过会员积分候选卡', async () => {
+    const ctx = createServerContext();
+    const reqCtx = { identity: { userId: 'u_activity', source: 'dev' as const }, attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } } };
+    const handler = createPromotionIntentHandler(ctx);
+
+    expect(handler.intents?.flatMap((intent) => intent.patterns)).toEqual(
+      expect.arrayContaining([
+        ...PROMOTION_INTENTS['list-entitlements'].patterns,
+        ...PROMOTION_INTENTS['list-activities'].patterns,
+      ]),
+    );
+
+    const result = await handler.handle('intent', { content: '最近有什么营销活动？' }, ctx, reqCtx);
+
+    expect(result.cards).toHaveLength(1);
+    expect(result.cards[0]?.cardType).toBe('promotion-activity-list');
+    expect(result.cards.some((card) => card.cardType === 'member-point-usage-list')).toBe(false);
+    expect(promotionActivityListCardDataSchema.safeParse(result.cards[0]?.data).success).toBe(true);
+    expect(result.cards[0]?.data).toMatchObject({
+      items: [
+        expect.objectContaining({
+          activityRef: expect.any(String),
+          title: '周末亲子市集',
+          availabilityStatus: expect.any(String),
+          itemActions: [
+            expect.objectContaining({
+              kind: 'send',
+              label: '查看活动详情',
+              value: expect.stringContaining('周末亲子市集'),
+            }),
+          ],
+        }),
+      ],
+    });
+    const activity = (result.cards[0]?.data as {
+      items: { activityRef: string; itemActions: { value?: string }[] }[];
+    }).items[0];
+    expect(activity.itemActions[0]?.value).toBe('查看「周末亲子市集」的活动详情');
+    expect(activity.itemActions[0]?.value).not.toContain(activity.activityRef);
+  });
+
+  it('意图路由收窄：跨域泛词问句不再误入营销意图（便宜/折扣/团购/市集/展览）', () => {
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '这个手机好便宜哪里买')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '哪家店折扣力度大')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '公司团建去哪里玩')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '附近有什么展览馆')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '周末市集人好多好热闹')).toBeUndefined();
+  });
+
+  it('意图路由保持：exact 固定句与导航模板前缀仍可路由', () => {
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '活动中心')?.handlerId).toBe('promotion');
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '有什么优惠')?.handlerId).toBe('promotion');
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '现在有什么优惠？')?.handlerId).toBe('promotion');
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '查看「周末亲子市集」的活动详情')?.handlerId).toBe('promotion');
+  });
+
+  it('复合句回归锚：自然语言不再被 BM25 单标签截断（走 LLM 多工具编排）', () => {
+    // 「推荐门店+领券」曾 BM25 命中 search-offers 直出券卡、吞掉导购半句（2026-08-31 实证）
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '给我推荐一下哪些导购的门店，并且有哪些优惠券可以领')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '最近有什么营销活动')).toBeUndefined();
+    expect(matchIntent(PROMOTION_TEST_ROUTES, '查询我的优惠券')).toBeUndefined();
+  });
+
+  it.each(['查询我的优惠券', '查看我现在持有的优惠券'])(
+    '“%s”直达已领取券列表，不被可领券关键词截获',
+    async (content) => {
+      const service = new InMemoryPromotionService();
+      await service.acquire(q, {
+        offerRef: 'demo:coupon:1001',
+        externalMemberRef: 'member-ref:u_1',
+        idempotencyKey: `owned-intent-${content}`,
+      });
+      const listEntitlements = vi.spyOn(service, 'listEntitlements');
+      const searchOffers = vi.spyOn(service, 'searchOffers');
+      mockAllSlotsPersist(service);
+      const ctx = createPromotionTestContext();
+      const handler = createPromotionIntentHandler(ctx);
+
+      const result = await handler.handle('intent', { content }, ctx, testRequestContext());
+
+      expect(listEntitlements).toHaveBeenCalledWith(expect.anything(), { limit: 50 });
+      expect(searchOffers).not.toHaveBeenCalled();
+      expect(result.text).toBe('你的券包里有 1 张优惠券');
+      expect(result.cards).toHaveLength(1);
+      expect(result.cards[0]?.cardType).toBe('promotion-entitlement-list');
+      expect(promotionEntitlementListCardDataSchema.safeParse(result.cards[0]?.data).success).toBe(true);
+      expect(result.cards[0]?.data).toMatchObject({
+        items: [expect.objectContaining({ title: '满 100 减 20 元券', status: 'EFFECTIVE' })],
+      });
+    },
+  );
+
+  it('“有什么优惠可以领取”直达可领取券列表，不查询已领取券包', async () => {
+    const service = new InMemoryPromotionService();
+    const listEntitlements = vi.spyOn(service, 'listEntitlements');
+    const available = await service.getOfferDetail(q, { offerRef: 'demo:coupon:1001' });
+    vi.spyOn(service, 'searchOffers').mockResolvedValue({
+      items: [
+        ...Array.from({ length: 6 }, (_, index) => ({ ...available!, offerRef: `available-${index}` })),
+        { ...available!, offerRef: 'sold-out', availability: { ...available!.availability, status: 'UNAVAILABLE' } },
+      ],
+      hasMore: false,
+    });
+    const searchOffers = vi.mocked(service.searchOffers);
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const handler = createPromotionIntentHandler(ctx);
+
+    const result = await handler.handle('intent', { content: '有什么优惠可以领取？帮我找找可领的优惠券' }, ctx, testRequestContext());
+
+    expect(searchOffers).toHaveBeenCalledWith(expect.anything(), { offerTypes: ['COUPON'], limit: 50 });
+    expect(listEntitlements).not.toHaveBeenCalled();
+    expect(result.cards[0]?.cardType).toBe('promotion-offer-list');
+    expect(result.text).toContain('可领取优惠券');
+    expect(result.text).toContain('6 张');
+    expect(result.cards[0]?.data).toMatchObject({ items: expect.any(Array) });
+    expect((result.cards[0]?.data as { items: unknown[] }).items).toHaveLength(6);
+  });
+
+  it('纯券搜索统一投影为券列表，避免回落到活动与优惠卡', async () => {
+    const service = new InMemoryPromotionService();
+    vi.spyOn(service, 'searchOffers').mockResolvedValue({
+      items: [
+        {
+          ...(await service.getOfferDetail(q, { offerRef: 'demo:coupon:1001' }))!,
+          offerType: 'COUPON',
+        },
+      ],
+      hasMore: false,
+    });
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const handler = createPromotionIntentHandler(ctx);
+
+    const result = await handler.handle('intent', { content: '有没有餐饮团购套餐？' }, ctx, testRequestContext());
+
+    expect(result.cards[0]).toMatchObject({
+      cardType: 'promotion-offer-list',
+      data: { presentation: 'coupon' },
+    });
+  });
+});
+
+describe('promotion 卡片导航闭环', () => {
+  it('活动列表动作进入活动详情，不回到活动列表', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const handler = createPromotionIntentHandler(ctx);
+    const list = await handler.handle('intent', { content: '最近有什么营销活动？' }, ctx, testRequestContext());
+    const item = (list.cards[0]?.data as {
+      items: { title: string; activityRef: string; itemActions: { value: string }[] }[];
+    }).items[0]!;
+
+    expect(item.itemActions[0]!.value).not.toContain(item.activityRef);
+    expectPromotionIntentRoutable(item.itemActions[0]!.value);
+    const detail = await handler.handle('intent', { content: item.itemActions[0]!.value }, ctx, testRequestContext());
+
+    expect(detail.cards).toHaveLength(1);
+    expect(detail.cards[0]).toMatchObject({
+      cardType: 'promotion-activity-detail',
+      data: { title: item.title, presentation: 'detail' },
+    });
+  });
+
+  it('厂商活动详情失败时仍进入详情卡，并引导到支付宝查看完整安排', async () => {
+    const service = new InMemoryPromotionService();
+    const listActivities = service.listActivities.bind(service);
+    service.listActivities = vi.fn(async (q, input) => {
+      const page = await listActivities(q, input);
+      // F5：报名深链为 provider 出参快照（数据驱动），模块不再拼装
+      return {
+        ...page,
+        items: page.items.map((item) => ({
+          ...item,
+          activityRef: 'demo-act:3001',
+          registrationUrl: 'alipays://platformapi/startapp?appId=demo&page=v%2Fmarketing%2Factivity%2Fdetail%3Fid%3Ddemo-activity',
+        })),
+      };
+    });
+    service.getActivityDetail = vi.fn(async () => {
+      throw new Error('用户token错误或已过期');
+    });
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const handler = createPromotionIntentHandler(ctx);
+    const list = await handler.handle('intent', { content: '最近有什么营销活动？' }, ctx, testRequestContext());
+    const item = (list.cards[0]?.data as {
+      items: { title: string; itemActions: { value: string }[] }[];
+    }).items[0]!;
+
+    const result = await handler.handle('intent', { content: item.itemActions[0]!.value }, ctx, testRequestContext());
+
+    expect(result.text).toBe('这是「周末亲子市集」的活动概览，可前往支付宝查看完整安排并报名');
+    expect(result.cards[0]).toMatchObject({
+      cardType: 'promotion-activity-detail',
+      data: {
+        title: item.title,
+        presentation: 'detail',
+        notice: '完整活动安排请前往支付宝活动页查看',
+        sessions: [],
+      },
+    });
+    expect((result.cards[0]!.data as { registrationUrl?: string }).registrationUrl).toBe(
+      'alipays://platformapi/startapp?appId=demo&page=v%2Fmarketing%2Factivity%2Fdetail%3Fid%3Ddemo-activity',
+    );
+  });
+
+  it('券列表动作进入优惠券详情卡并消费详情接口结果', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const handler = createPromotionIntentHandler(ctx);
+    const list = await handler.handle('intent', { content: '现在有什么优惠？' }, ctx, testRequestContext());
+    const item = (list.cards[0]?.data as {
+      items: { title: string; offerRef: string; itemActions: { value: string }[] }[];
+    }).items[0]!;
+
+    expect(item.itemActions[0]!.value).not.toContain(item.offerRef);
+    expectPromotionIntentRoutable(item.itemActions[0]!.value);
+    const detail = await handler.handle('intent', { content: item.itemActions[0]!.value }, ctx, testRequestContext());
+
+    expect(detail.cards[0]).toMatchObject({
+      cardType: 'promotion-offer-detail',
+      data: { presentation: 'offer' },
+    });
+    expect((detail.cards[0]!.data as { title: string }).title).toBe(item.title);
+  });
+
+  it('已领券的详情提问进入我的券单条卡（详情由行内浮层承载）', async () => {
+    const service = new InMemoryPromotionService();
+    await service.acquire(q, {
+      offerRef: 'demo:coupon:1001',
+      externalMemberRef: 'member-ref:u_1',
+      idempotencyKey: 'navigation-entitlement',
+    });
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const tools = createPromotionTools({ getCtx: () => ctx });
+    const handler = createPromotionIntentHandler(ctx);
+    const list = (await tools.listEntitlements.execute!({} as never, createToolExecContext(testRequestContext()) as never)) as {
+      cards: { data: { items: { title: string; entitlementRef: string }[] } }[];
+    };
+    const item = list.cards[0]!.data.items[0]!;
+
+    // 行上已无发消息动作，但用户直接问某张券仍要能落到卡上
+    const query = `查看「${item.title}」这张优惠券的使用详情`;
+    expectPromotionIntentRoutable(query);
+    const detail = await handler.handle('intent', { content: query }, ctx, testRequestContext());
+
+    expect(detail.cards[0]).toMatchObject({ cardType: 'promotion-entitlement-list' });
+    expect((detail.cards[0] as unknown as { data: { items: unknown[] } }).data.items).toHaveLength(1);
+  });
+
+  it('活动分类动作进入对应分类的活动列表', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const ctx = createPromotionTestContext();
+    const tools = createPromotionTools({ getCtx: () => ctx });
+    const handler = createPromotionIntentHandler(ctx);
+    const categories = (await tools.listActivityCategories.execute!({} as never, createToolExecContext(testRequestContext()) as never)) as {
+      cards: { data: { items: { name: string; categoryId: string; itemActions: { value: string }[] }[] } }[];
+    };
+    const category = categories.cards[0]!.data.items[0]!;
+
+    expect(category.itemActions[0]!.value).not.toContain(category.categoryId);
+    expectPromotionIntentRoutable(category.itemActions[0]!.value);
+    const list = await handler.handle('intent', { content: category.itemActions[0]!.value }, ctx, testRequestContext());
+
+    expect(list.cards[0]).toMatchObject({
+      cardType: 'promotion-activity-list',
+      data: { items: [expect.objectContaining({ categoryName: category.name })] },
+    });
+  });
+});
+
+describe('createPromotionActions.acquire（actions 层闭环）', () => {
+  // subject-binding 兼容键仍注册在场（版本偏斜期双通道并存）；门禁只消费 member.status
+  const binding = { resolveExternalMemberRef: (userId: string) => `member-ref:${userId}` };
+  const activeAccount = {
+    authState: 'authenticated' as const,
+    state: 'active' as const,
+    primaryMallCardNo: 'C-1001',
+    memberRef: 'member:C-1001',
+    observedAt: '2026-08-30T00:00:00.000Z',
+  };
+  const statusFactory = (outcome: string, account?: unknown) =>
+    async () => ({ outcome, ...(account !== undefined ? { account } : {}) });
+  // 按键分发：member.status → 门禁工厂；其余（subject-binding 兼容）→ binding
+  // providers.resolve 抛 → ports 降级 InMemory 单例（双模缺省路径）
+  const ctxWithStatus = (
+    outcome = 'active',
+    account: unknown = activeAccount,
+    logger: { warn: ReturnType<typeof vi.fn> } = { warn: vi.fn() },
+  ) =>
+    ({
+      services: { resolve: (key: string) => (key === 'member.status' ? statusFactory(outcome, account) : binding) },
+      logger,
+      auth: { getContext: () => undefined },
+      providers: { resolve: async () => { throw new Error('no provider'); } },
+    }) as never;
+  const reqCtx = (userId: string) =>
+    ({ identity: { userId, source: 'dev' }, attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } } }) as never;
+
+  it('会员门禁：not_enrolled 拦截且不触 promotion 服务（门禁先于幂等占位；深链解耦后恒带卡）', async () => {
+    vi.mocked(resolvePromotionAcquisitionPort).mockClear();
+    const actions = createPromotionActions(
+      ctxWithStatus('not_enrolled', { authState: 'authenticated', state: 'not_enrolled', observedAt: '2026-08-30T00:00:00.000Z' }),
+    );
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_enroll'));
+    expect(result.card?.cardType).toBe('member-enrollment-cta');
+    expect(result.card?.data).toMatchObject({ authState: 'authenticated', state: 'not_enrolled' });
+    expect(result.card?.data).not.toHaveProperty('enrollUrl');
+    expect(result.text).toBe('领取需要会员身份，办理入会后即可领券');
+    expect(resolvePromotionAcquisitionPort).not.toHaveBeenCalled();
+  });
+
+  it('会员门禁：凭证轴未认证（合法登录但无会员凭证）→ 统一会员引导文案', async () => {
+    const actions = createPromotionActions(
+      ctxWithStatus('unauthenticated', { authState: 'unauthenticated', state: 'unknown', observedAt: '2026-08-30T00:00:00.000Z' }),
+    );
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_unauth'));
+    expect(result.text).toBe('领取需要会员身份，请先登录或办理入会后再领券');
+  });
+
+  it('会员门禁：unknown 软文案（不误伤可能是会员的用户，不引导入会）', async () => {
+    const actions = createPromotionActions(ctxWithStatus('unknown', undefined));
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_unknown'));
+    expect(result.text).toContain('暂时无法确认会员状态');
+    expect(result.text).not.toContain('办理入会');
+  });
+
+  it('会员门禁：member.status 缺席（member 未装/旧版混装）→ 兼容档文案', async () => {
+    const ctx = {
+      services: { resolve: (key: string) => (key === 'member.status' ? undefined : binding) },
+      logger: { warn: vi.fn() },
+      auth: { getContext: () => undefined },
+      providers: { resolve: async () => { throw new Error('no provider'); } },
+    } as never;
+    const actions = createPromotionActions(ctx);
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_compat'));
+    expect(result.text).toBe('领取需要会员身份，请先登录或办理入会后再领券');
+  });
+
+  it('会员门禁：active 放行并透传真实卡号（primaryMallCardNo 真值，非平台派生引用）', async () => {
+    vi.mocked(resolvePromotionOffersPort).mockReset(); vi.mocked(resolvePromotionEntitlementsPort).mockReset(); vi.mocked(resolvePromotionActivitiesPort).mockReset(); vi.mocked(resolvePromotionAcquisitionPort).mockReset();
+    const seen: string[] = [];
+    const origAcquire = inMemoryPromotion.acquire.bind(inMemoryPromotion);
+    (inMemoryPromotion as { acquire: unknown }).acquire = async (
+      qi: Parameters<typeof origAcquire>[0],
+      ai: Parameters<typeof origAcquire>[1],
+    ) => {
+      seen.push(ai.externalMemberRef);
+      return origAcquire(qi, ai);
+    };
+    try {
+      const actions = createPromotionActions(ctxWithStatus());
+      const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_active'));
+      expect(result.card?.cardType).toBe('promotion-entitlement-list');
+      expect(seen).toEqual(['C-1001']);
+    } finally {
+      (inMemoryPromotion as { acquire: unknown }).acquire = origAcquire;
+    }
+  });
+
+  it('会员门禁：仅 opaque 引用的账户（演示链形态）→ 透传放行', async () => {
+    vi.mocked(resolvePromotionOffersPort).mockReset(); vi.mocked(resolvePromotionEntitlementsPort).mockReset(); vi.mocked(resolvePromotionActivitiesPort).mockReset(); vi.mocked(resolvePromotionAcquisitionPort).mockReset();
+    const seen: string[] = [];
+    const origAcquire = inMemoryPromotion.acquire.bind(inMemoryPromotion);
+    (inMemoryPromotion as { acquire: unknown }).acquire = async (
+      qi: Parameters<typeof origAcquire>[0],
+      ai: Parameters<typeof origAcquire>[1],
+    ) => {
+      seen.push(ai.externalMemberRef);
+      return origAcquire(qi, ai);
+    };
+    try {
+      const actions = createPromotionActions(
+        ctxWithStatus('active', { authState: 'authenticated', state: 'active', memberRef: 'demo:member:demo-user', observedAt: '2026-08-30T00:00:00.000Z' }),
+      );
+      const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_opaque'));
+      expect(result.card?.cardType).toBe('promotion-entitlement-list');
+      expect(seen).toEqual(['demo:member:demo-user']);
+    } finally {
+      (inMemoryPromotion as { acquire: unknown }).acquire = origAcquire;
+    }
+  });
+
+  it('会员门禁：active 但账户快照缺席（解析器原子性破坏）→ 软失败 + warn 留痕', async () => {
+    vi.mocked(resolvePromotionAcquisitionPort).mockClear();
+    const warn = vi.fn();
+    // 内联构造：ctxWithStatus 第二参有默认值（显式 undefined 仍取 activeAccount），
+    // 无法表达「account 键缺席」形态
+    const ctx = {
+      services: {
+        resolve: (key: string) =>
+          key === 'member.status' ? async () => ({ outcome: 'active' }) : binding,
+      },
+      logger: { warn },
+      auth: { getContext: () => undefined },
+      providers: { resolve: async () => { throw new Error('no provider'); } },
+    } as never;
+    const actions = createPromotionActions(ctx);
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_noaccount'));
+    expect(result.card).toBeUndefined();
+    expect(result.text).toContain('暂时无法确认会员状态');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(resolvePromotionAcquisitionPort).not.toHaveBeenCalled();
+  });
+
+  it('会员门禁：active 但双引用缺失 → 软失败 + warn 留痕（不触 promotion 服务）', async () => {
+    vi.mocked(resolvePromotionAcquisitionPort).mockClear();
+    const warn = vi.fn();
+    const actions = createPromotionActions(
+      ctxWithStatus('active', { authState: 'authenticated', state: 'active', observedAt: '2026-08-30T00:00:00.000Z' }, { warn }),
+    );
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_gate_noref'));
+    expect(result.card).toBeUndefined();
+    expect(result.text).toContain('暂时无法确认会员状态');
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(resolvePromotionAcquisitionPort).not.toHaveBeenCalled();
+  });
+
+  it('评审修复（#4）：厂商异常释放幂等占位 → 重试可成功（不固化 24h 拒绝）', async () => {
+    vi.mocked(resolvePromotionOffersPort).mockReset(); vi.mocked(resolvePromotionEntitlementsPort).mockReset(); vi.mocked(resolvePromotionActivitiesPort).mockReset(); vi.mocked(resolvePromotionAcquisitionPort).mockReset();
+    const actions = createPromotionActions(ctxWithStatus());
+    const origAcquire = inMemoryPromotion.acquire.bind(inMemoryPromotion);
+    let failNext = true;
+    (inMemoryPromotion as { acquire: unknown }).acquire = async (
+      qi: Parameters<typeof origAcquire>[0],
+      ai: Parameters<typeof origAcquire>[1],
+    ) => {
+      if (failNext) {
+        failNext = false;
+        throw new Error('gateway timeout');
+      }
+      return origAcquire(qi, ai);
+    };
+    const payload = { offerRef: 'demo:coupon:1001' };
+    try {
+      // 第一次：厂商异常 → 可重试文案（无卡，经 tbox:notice 下发；占位已释放，不 commit）
+      const first = await actions.acquire.execute!(payload, reqCtx('u_flaky'));
+      expect(first.card).toBeUndefined();
+      expect(first.text).toContain('请稍后重试');
+      // 第二次：恢复 → 占位不阻塞，领取成功后直接出「我的券」
+      const second = await actions.acquire.execute!(payload, reqCtx('u_flaky'));
+      expect(second.card?.cardType).toBe('promotion-entitlement-list');
+    } finally {
+      (inMemoryPromotion as { acquire: unknown }).acquire = origAcquire;
+    }
+  });
+
+  it('重复点击不在模块层拦截，是否允许由 Provider 返回控制', async () => {
+    const acquire = vi.fn()
+      .mockResolvedValueOnce({ operationRef: 'op-1', offerRef: 'demo:coupon:1001', status: 'REJECTED', code: '100408', message: '领取失败，请稍后重试', observedAt: '2026-09-04T00:00:00.000Z' })
+      .mockResolvedValueOnce({ operationRef: 'op-2', offerRef: 'demo:coupon:1001', status: 'SUCCEEDED', observedAt: '2026-09-04T00:00:01.000Z' });
+    mockAllSlotsPersist({ acquire, listEntitlements: vi.fn(async () => ({ items: [] })) });
+    const warn = vi.fn();
+    const actions = createPromotionActions(ctxWithStatus('active', activeAccount, { warn }));
+    const payload = { offerRef: 'demo:coupon:1001' };
+    const first = await actions.acquire.execute!(payload, reqCtx('u_repeat'));
+    const second = await actions.acquire.execute!(payload, reqCtx('u_repeat'));
+    expect(first.text).toBe('领取失败：领取失败，请稍后重试（code 100408）');
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('code=100408'));
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('message="领取失败，请稍后重试"'));
+    expect(second.text).toContain('领取成功');
+    expect(acquire).toHaveBeenCalledTimes(2);
+    expect(acquire.mock.calls[0]![1].idempotencyKey).not.toBe(acquire.mock.calls[1]![1].idempotencyKey);
+  });
+
+  it('未枚举的业务 message 和 code 也原样返回并记录', async () => {
+    const acquire = vi.fn(async () => ({
+      operationRef: 'op-unlisted', offerRef: 'demo:coupon:1001', status: 'REJECTED',
+      code: 'BIZ_UNLISTED', message: '上游自定义拒绝原因', observedAt: '2026-09-04T00:00:00.000Z',
+    }));
+    mockAllSlotsPersist({ acquire });
+    const warn = vi.fn();
+    const actions = createPromotionActions(ctxWithStatus('active', activeAccount, { warn }));
+
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtx('u_unlisted'));
+
+    expect(result.text).toBe('领取失败：上游自定义拒绝原因（code BIZ_UNLISTED）');
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('code=BIZ_UNLISTED'));
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('message="上游自定义拒绝原因"'));
+  });
+});
+
+describe("M1' 承接：券详情收口到列表浮层", () => {
+  it('listEntitlements 出我的券卡且不再带 itemActions（详情由行内浮层承载）', async () => {
+    const service = new InMemoryPromotionService();
+    await service.acquire(q, { offerRef: 'demo:coupon:1001', externalMemberRef: 'm', idempotencyKey: 'm1-ent' });
+    mockAllSlotsPersist(service);
+    const ctxFake = {
+      auth: {
+        getContext: () => ({
+          identity: { userId: 'u_1', source: 'dev' },
+          attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } },
+        }),
+      },
+    } as never;
+    const tools = createPromotionTools({ getCtx: () => ctxFake });
+    const result = (await tools.listEntitlements.execute!({} as never, createToolExecContext(testRequestContext()) as never)) as {
+      cards: { cardType: string; data: { items: { title: string; itemActions?: unknown[] }[] } }[];
+    };
+    expect(result.cards[0].cardType).toBe('promotion-entitlement-list');
+    expect(promotionEntitlementListCardDataSchema.safeParse(result.cards[0].data).success).toBe(true);
+    // 券码与使用说明改由行内浮层展示，行上不再挂发消息动作——
+    // 那句话原本指向 getCouponDetail，工具撤掉后留着就是死路由
+    expect(result.cards[0].data.items[0].itemActions).toBeUndefined();
+  });
+
+  it('券专属详情工具已撤，通用优惠详情仍在', () => {
+    const ctxFake = { auth: { getContext: () => null } } as never;
+    const tools = createPromotionTools({ getCtx: () => ctxFake }) as Record<string, { description?: string }>;
+    expect(tools.getCouponDetail).toBeUndefined();
+    expect(tools.getOfferDetail.description).toContain('通用优惠详情卡');
+  });
+});
+
+describe('会员门禁（TIER1 门禁闭环，SPEC-3）', () => {
+  const statusOf = (outcome: string, extra: Record<string, unknown> = {}) => async () => ({ outcome, ...extra });
+  const ctxWithGate = (factory: unknown) =>
+    ({ services: { resolve: (key: string) => (key === 'member.status' ? factory : undefined) } }) as never;
+  const reqCtxOf = (userId = 'u_gate') =>
+    ({ identity: { userId, source: 'dev' as const }, attributes: { mall: { miniAppId: 'app', mallId: 'mall-1' } } }) as never;
+  const execCtx = (userId = 'u_gate') => createToolExecContext(reqCtxOf(userId)) as never;
+
+  it('listEntitlements：not_enrolled + enrollUrl → 出 member-enrollment-cta 且 found:false', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({
+      getCtx: () => ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll', loginUrl: 'alipays://login' })),
+    });
+    const result = (await tools.listEntitlements.execute!({} as never, execCtx())) as {
+      found: boolean;
+      cards?: { cardType: string; data: Record<string, unknown> }[];
+      noResultsReason?: string;
+    };
+    expect(result.found).toBe(false);
+    expect(result.cards?.[0]?.cardType).toBe('member-enrollment-cta');
+    expect(result.cards?.[0]?.data).toMatchObject({
+      userId: 'u_gate',
+      authState: 'authenticated',
+      state: 'not_enrolled',
+      enrollUrl: 'alipays://enroll',
+    });
+    expect(result.noResultsReason).toBe('完成入会后即可使用该服务');
+  });
+
+  it('listCoupons(OWNED)：not_enrolled → 出 member-enrollment-cta（entitlementFacts 单点覆盖两工具）', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({
+      getCtx: () => ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll' })),
+    });
+    const result = (await tools.listCoupons.execute!({ mode: 'OWNED' } as never, execCtx())) as {
+      cards?: { cardType: string }[];
+    };
+    expect(result.cards?.[0]?.cardType).toBe('member-enrollment-cta');
+  });
+
+  it('listCoupons(CLAIMABLE)：note 契约——含数量关键事实（W7 抽样断言）', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({ getCtx: () => ctxWithGate(undefined) });
+    const result = (await tools.listCoupons.execute!({} as never, execCtx())) as {
+      items?: unknown[];
+      cards?: { cardType: string; note: string }[];
+    };
+    if ((result.items?.length ?? 0) > 0) {
+      expect(result.cards?.[0]?.cardType).toBe('promotion-offer-list');
+      expect(result.cards![0]!.note).toContain('可领优惠券');
+      expect(result.cards![0]!.note).toContain(`${result.items!.length} 张`);
+    }
+  });
+
+  it('listEntitlements：member 未装（工厂缺席）→ fail-open 照常（InMemory 空券包文案）', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({ getCtx: () => ctxWithGate(undefined) });
+    const result = (await tools.listEntitlements.execute!({} as never, execCtx())) as {
+      cards?: { cardType: string }[];
+      noResultsReason?: string;
+    };
+    // 无门禁：InMemory 空券包 → 无卡 + 引导找可领优惠
+    expect(result.cards).toBeUndefined();
+    expect(result.noResultsReason).toContain('还没有优惠券');
+  });
+
+  it('listEntitlements：unknown → 软放行（不误伤瞬时故障的会员）', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({ getCtx: () => ctxWithGate(statusOf('unknown')) });
+    const result = (await tools.listEntitlements.execute!({} as never, execCtx())) as {
+      cards?: { cardType: string }[];
+    };
+    expect(result.cards).toBeUndefined();
+  });
+
+  it('getOfferDetail：entitlementRef + not_enrolled → 拦截；keyword + not_enrolled → 不拦', async () => {
+    const service = new InMemoryPromotionService();
+    const getOfferDetail = vi.spyOn(service, 'getOfferDetail');
+    mockAllSlotsPersist(service);
+    const tools = createPromotionTools({
+      getCtx: () => ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll' })),
+    });
+    // entitlementRef 反查 = 我的券详情（属人）：拦
+    const blocked = (await tools.getOfferDetail.execute!({ entitlementRef: 'ent-1' } as never, execCtx())) as {
+      found: boolean;
+      cards?: { cardType: string }[];
+    };
+    expect(blocked.found).toBe(false);
+    expect(blocked.cards?.[0]?.cardType).toBe('member-enrollment-cta');
+    expect(getOfferDetail).not.toHaveBeenCalled();
+    // keyword 公共反查：不拦
+    const pass = (await tools.getOfferDetail.execute!({ keyword: '团购' } as never, execCtx())) as {
+      found: boolean;
+      cards?: { cardType: string }[];
+    };
+    expect(pass.found).toBe(true);
+    expect(getOfferDetail).toHaveBeenCalled();
+  });
+
+  it('意图 list-entitlements：not_enrolled → 零 LLM 直出 {cards:[cta], text:notice}', async () => {
+    const service = new InMemoryPromotionService();
+    const listEntitlements = vi.spyOn(service, 'listEntitlements');
+    mockAllSlotsPersist(service);
+    const ctx = ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll' }));
+    const handler = createPromotionIntentHandler(ctx);
+    const result = await handler.handle('intent', { content: '我的优惠券' }, ctx, reqCtxOf('u_h_gate'));
+    expect(listEntitlements).not.toHaveBeenCalled();
+    expect(result.cards?.[0]?.cardType).toBe('member-enrollment-cta');
+    expect(result.text).toBe('完成入会后即可使用该服务');
+  });
+
+  it('意图 entitlement-detail：not_enrolled → 直出 {cards:[cta], text:notice}', async () => {
+    const service = new InMemoryPromotionService();
+    mockAllSlotsPersist(service);
+    const ctx = ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll' }));
+    const handler = createPromotionIntentHandler(ctx);
+    const result = await handler.handle('intent', { content: '查看「满 100 减 20 元券」这张优惠券的使用详情' }, ctx, reqCtxOf('u_h_gate2'));
+    expect(result.cards?.[0]?.cardType).toBe('member-enrollment-cta');
+  });
+
+  it('意图 list-entitlements：active → 全量回归（券包正常直出）', async () => {
+    const service = new InMemoryPromotionService();
+    await service.acquire(q, { offerRef: 'demo:coupon:1001', externalMemberRef: 'm', idempotencyKey: 'gate-active-1' });
+    mockAllSlotsPersist(service);
+    const ctx = ctxWithGate(statusOf('active', { account: { authState: 'authenticated', state: 'active' } }));
+    const handler = createPromotionIntentHandler(ctx);
+    const result = await handler.handle('intent', { content: '我的优惠券' }, ctx, reqCtxOf('u_1'));
+    expect(result.cards?.[0]?.cardType).toBe('promotion-entitlement-list');
+    expect(result.text).toContain('你的券包里有 1 张优惠券');
+  });
+
+  it('acquire blocked：not_enrolled + enrollUrl → 附卡且文案仍为自有八态文案（fail-closed 语义）', async () => {
+    vi.mocked(resolvePromotionAcquisitionPort).mockClear();
+    const actions = createPromotionActions(
+      ctxWithGate(statusOf('not_enrolled', { enrollUrl: 'alipays://enroll' })),
+    );
+    const result = await actions.acquire.execute!({ offerRef: 'demo:coupon:1001' }, reqCtxOf('u_gate_card'));
+    expect(result.card?.cardType).toBe('member-enrollment-cta');
+    expect(result.text).toBe('领取需要会员身份，办理入会后即可领券'); // 文案表零改动
+    expect(resolvePromotionAcquisitionPort).not.toHaveBeenCalled();
+  });
+});