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

package/tests/cards.test.ts

@@ -0,0 +1,586 @@
+/**
+ * 015 S1：契约 zod 域单测。
+ * - itemActions 判别联合拒未知 kind（F1）
+ * - 新卡 schema sample round-trip（promotion 6 + parking 5 + member 入会 2）
+ * - host-effect 协议单源经 contracts 包导出可达
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  actionDraftSchema,
+  pageInfoSchema,
+  shoppingGuideCardDataSchemas,
+  promotionCardDataSchemas,
+  parkingCardDataSchemas,
+  memberEnrollmentFormCardDataSchema,
+  memberEnrollmentStatusCardDataSchema,
+  memberEnrollmentCtaCardDataSchema,
+  memberCardSummaryCardDataSchema,
+} from '../src/index';
+import { TBOX_EFFECT_EVENT_NAME } from '@tbox.cn/app-contracts';
+
+describe('actionDraftSchema 判别联合（F1）', () => {
+  it('接受 send/link 两变体', () => {
+    expect(
+      actionDraftSchema.safeParse({
+        kind: 'send',
+        label: '查看详情',
+        value: '老凤祥',
+      }).success,
+    ).toBe(true);
+    expect(
+      actionDraftSchema.safeParse({ kind: 'send', label: '联系导购' }).success,
+    ).toBe(true);
+    expect(
+      actionDraftSchema.safeParse({
+        kind: 'link',
+        label: '拨打客服',
+        url: 'tel:0571-88888888',
+      }).success,
+    ).toBe(true);
+  });
+
+  it('拒绝 write 变体与未知 kind（无 token 机制支撑，不进联合）', () => {
+    expect(
+      actionDraftSchema.safeParse({
+        kind: 'write',
+        actionId: 'x',
+        label: '领券',
+      }).success,
+    ).toBe(false);
+    expect(
+      actionDraftSchema.safeParse({ kind: 'navigate', label: '切换商场' })
+        .success,
+    ).toBe(false);
+    // 旧形状（actionId 顶层）不再合法
+    expect(
+      actionDraftSchema.safeParse({ actionId: 'a', label: 'x', input: {} })
+        .success,
+    ).toBe(false);
+  });
+
+  it('link 缺 url 拒绝；send 缺 label 拒绝', () => {
+    expect(
+      actionDraftSchema.safeParse({ kind: 'link', label: '导航' }).success,
+    ).toBe(false);
+    expect(actionDraftSchema.safeParse({ kind: 'send' }).success).toBe(false);
+  });
+});
+
+describe('member-card-summary 动态展示契约', () => {
+  const base = {
+    userId: 'u1',
+    cardRef: 'card-1',
+    cardDisplay: '金卡会员',
+    status: 'active' as const,
+    availablePoints: 987,
+  };
+
+  it('接受通用卡面、消费进度和权益摘要，旧数据仍兼容', () => {
+    expect(memberCardSummaryCardDataSchema.safeParse(base).success).toBe(true);
+    expect(memberCardSummaryCardDataSchema.safeParse({
+      ...base,
+      cardImageUrl: 'https://cdn.example.test/card.png',
+      pointsRuleImageUrl: 'https://cdn.example.test/points-rule.jpg',
+      presentation: { variant: 'gold' },
+      progress: {
+        daySpentCents: 12_345,
+        yearSpentCents: 500_000,
+        percent: 25,
+        message: '今日已消费123.45元，年累计已消费5000.00元',
+      },
+      benefits: [{
+        benefitRef: 'b1',
+        name: '免费停车',
+        iconUrl: 'https://cdn.example.test/icon.png',
+        description: '可免2小时',
+      }],
+    }).success).toBe(true);
+  });
+
+  it('拒绝越界进度、负消费额与非 URL 图标', () => {
+    expect(memberCardSummaryCardDataSchema.safeParse({
+      ...base,
+      progress: { daySpentCents: -1, yearSpentCents: 0, percent: 101, message: '' },
+      benefits: [{ benefitRef: 'b1', name: '权益', iconUrl: 'not-a-url' }],
+    }).success).toBe(false);
+  });
+
+  it('拒绝非 URL 的积分规则图片', () => {
+    expect(memberCardSummaryCardDataSchema.safeParse({
+      ...base,
+      pointsRuleImageUrl: 'not-a-url',
+    }).success).toBe(false);
+  });
+});
+
+describe('0.3.2 D4 契约纯增（optional 双向兼容）', () => {
+  it('actionDraftSchema 经 shared/cards 单源可达（index + runtime 导出面）', async () => {
+    const runtime = await import('../src/runtime');
+    expect(runtime.actionDraftSchema).toBe(actionDraftSchema);
+  });
+
+  it('pageInfo.pageSize 上限 200（0.7.5 放宽：品牌导览常驻入口 port 直调回显过卡 schema）', () => {
+    const base = { page: 1, total: 12, hasMore: false };
+    expect(
+      pageInfoSchema.safeParse({ ...base, pageSize: 200 }).success,
+    ).toBe(true);
+    expect(
+      pageInfoSchema.safeParse({ ...base, pageSize: 201 }).success,
+    ).toBe(false);
+  });
+
+  it('五处条目 itemActions 均可缺省（旧数据零迁移通过）', () => {
+    // sg category-list categories[] / mall-directory floors[]
+    expect(
+      shoppingGuideCardDataSchemas['category-list'].safeParse({
+        categories: [{ code: 'c1', name: '餐饮', merchantCount: 12 }],
+        observedAt: '2026-08-01T00:00:00.000Z',
+      }).success,
+    ).toBe(true);
+    expect(
+      shoppingGuideCardDataSchemas['mall-directory'].safeParse({
+        mallId: 'm1',
+        mallName: '银泰',
+        observedAt: '2026-08-01T00:00:00.000Z',
+        buildings: [
+          {
+            buildingCode: 'b1',
+            buildingName: '主楼',
+            floors: [
+              {
+                floorCode: 'f1',
+                floorName: 'L1',
+                businessCategories: ['餐饮'],
+                merchantCount: 8,
+              },
+            ],
+          },
+        ],
+      }).success,
+    ).toBe(true);
+    // promotion offer-list / entitlement-list
+    expect(
+      promotionCardDataSchemas['promotion-offer-list'].safeParse({
+        mode: 'search',
+        items: [
+          {
+            offerRef: 'o1',
+            title: '满减券',
+            offerType: 'COUPON',
+            claimable: true,
+            tags: [],
+          },
+        ],
+      }).success,
+    ).toBe(true);
+    expect(
+      promotionCardDataSchemas['promotion-entitlement-list'].safeParse({
+        items: [
+          {
+            entitlementRef: 'e1',
+            title: '停车券',
+            entitlementType: 'COUPON',
+            status: 'EFFECTIVE',
+          },
+        ],
+      }).success,
+    ).toBe(true);
+  });
+
+  it('itemActions 含 send/link 合法；未知 kind 拒', () => {
+    const ok = shoppingGuideCardDataSchemas['category-list'].safeParse({
+      categories: [
+        {
+          code: 'c1',
+          name: '餐饮',
+          merchantCount: 2,
+          itemActions: [
+            { kind: 'send', label: '看看有哪些餐厅' },
+            { kind: 'link', label: '电话', url: 'tel:10086' },
+          ],
+        },
+      ],
+      observedAt: '2026-08-01T00:00:00.000Z',
+    });
+    expect(ok.success).toBe(true);
+    const bad = shoppingGuideCardDataSchemas['category-list'].safeParse({
+      categories: [
+        {
+          code: 'c1',
+          name: '餐饮',
+          merchantCount: 2,
+          itemActions: [{ kind: 'write', label: 'x' }],
+        },
+      ],
+      observedAt: '2026-08-01T00:00:00.000Z',
+    });
+    expect(bad.success).toBe(false);
+  });
+
+  it('refreshRequiredAt 格式校验；referenceUrl 仅 https', () => {
+    const base = {
+      products: [
+        {
+          productId: 'p1',
+          name: '商品',
+          price: {},
+          availability: {
+            status: 'in_stock',
+            label: '有货',
+            marketable: true,
+            observedAt: '2026-08-01T00:00:00.000Z',
+          },
+          merchant: { merchantId: 'm1', name: '商户' },
+          attributes: [],
+          caveats: [],
+        },
+      ],
+      observedAt: '2026-08-01T00:00:00.000Z',
+    };
+    expect(
+      shoppingGuideCardDataSchemas['product-comparison'].safeParse({
+        ...base,
+        refreshRequiredAt: '2026-08-18T12:00:00Z',
+      }).success,
+    ).toBe(true);
+    expect(
+      shoppingGuideCardDataSchemas['product-comparison'].safeParse({
+        ...base,
+        refreshRequiredAt: '2026/08/18',
+      }).success,
+    ).toBe(false);
+    const faqOk = shoppingGuideCardDataSchemas[
+      'customer-service-faq'
+    ].safeParse({
+      query: '发票',
+      faqs: [
+        {
+          question: 'q',
+          answer: 'a',
+          relevanceScore: 0.9,
+          referenceUrl: 'https://example.com/faq',
+        },
+      ],
+    });
+    expect(faqOk.success).toBe(true);
+    const faqBad = shoppingGuideCardDataSchemas[
+      'customer-service-faq'
+    ].safeParse({
+      query: '发票',
+      faqs: [
+        {
+          question: 'q',
+          answer: 'a',
+          relevanceScore: 0.9,
+          referenceUrl: 'http://example.com/faq',
+        },
+      ],
+    });
+    expect(faqBad.success).toBe(false);
+  });
+});
+
+describe('promotion 9 卡 schema round-trip', () => {
+  const offerListSample = {
+    mode: 'search',
+    items: [
+      {
+        offerRef: 'off_1',
+        title: '满 100 减 20 券',
+        offerType: 'COUPON',
+        benefitText: '满 100 减 20',
+        claimable: true,
+        tags: ['餐饮'],
+      },
+    ],
+  };
+  const offerDetailSample = {
+    offerRef: 'off_1',
+    title: '满 100 减 20 券',
+    offerType: 'COUPON',
+    rules: ['单笔满 100 可用', '限领 1 张'],
+    claimable: false,
+    unavailableReason: '需登录会员',
+    caveats: ['资格、库存和最终优惠以厂商实时校验为准'],
+  };
+  const entitlementListSample = {
+    items: [
+      {
+        entitlementRef: 'ent_1',
+        title: '停车 2 小时券',
+        entitlementType: 'COUPON',
+        status: 'EFFECTIVE',
+        codeMasked: 'AB**CD',
+      },
+    ],
+  };
+  const activityListSample = {
+    items: [
+      {
+        activityRef: 'act_1',
+        title: '周末亲子市集',
+        registrationRequired: true,
+        remainingQuota: 12,
+      },
+    ],
+  };
+  const activityDetailSample = {
+    activityRef: 'act_1',
+    title: '周末亲子市集',
+    registrationRequired: true,
+    registrationUrl:
+      'alipays://platformapi/startapp?appId=demo&page=v%2Fmarketing%2Factivity%2Fdetail%3Fid%3Ddemo-activity',
+    sessions: [
+      {
+        sessionRef: 's_1',
+        title: '第一场',
+        startText: '周六 10:00',
+        status: 'OPEN',
+      },
+    ],
+    guideSteps: ['打开支付宝扫现场码', '选择场次', '凭报名码入场'],
+    conditions: ['限会员本人参与'],
+  };
+
+  it('全部 sample 解析通过', () => {
+    const samples: Record<string, unknown> = {
+      'promotion-offer-list': offerListSample,
+      'promotion-offer-detail': offerDetailSample,
+      'promotion-entitlement-list': entitlementListSample,
+      'promotion-activity-list': activityListSample,
+      'promotion-activity-detail': activityDetailSample,
+      'promotion-activity-category-list': {
+        items: [{ categoryId: 'family', name: '亲子' }],
+      },
+      'promotion-best-deal': {
+        authoritative: true,
+        originalAmountCents: 10000,
+        savingsCents: 2000,
+        expectedPayCents: 8000,
+        appliedOfferRefs: ['off_1'],
+      },
+    };
+    for (const [cardType, data] of Object.entries(samples)) {
+      const schema =
+        promotionCardDataSchemas[
+          cardType as keyof typeof promotionCardDataSchemas
+        ];
+      const result = schema.safeParse(data);
+      expect(result.success, `${cardType} should parse`).toBe(true);
+    }
+  });
+
+  it('9 个传输卡型显式覆盖 19 个 legacy presentation 语义', () => {
+    for (const presentation of [
+      'offer',
+      'promotion',
+      'coupon',
+      'recommendation',
+    ] as const) {
+      expect(
+        promotionCardDataSchemas['promotion-offer-list'].safeParse({
+          ...offerListSample,
+          presentation,
+        }).success,
+      ).toBe(true);
+    }
+    for (const presentation of [
+      'offer',
+      'promotion',
+      'promotion-guide',
+      'coupon',
+      'package',
+    ] as const) {
+      expect(
+        promotionCardDataSchemas['promotion-offer-detail'].safeParse({
+          ...offerDetailSample,
+          presentation,
+        }).success,
+      ).toBe(true);
+    }
+    for (const presentation of ['detail', 'schedule', 'guide'] as const) {
+      expect(
+        promotionCardDataSchemas['promotion-activity-detail'].safeParse({
+          ...activityDetailSample,
+          presentation,
+        }).success,
+      ).toBe(true);
+    }
+    expect(
+      promotionCardDataSchemas['promotion-offer-list'].safeParse({
+        ...offerListSample,
+        presentation: 'generic',
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe('parking 5 卡 schema round-trip', () => {
+  const paymentSample = {
+    quoteRef: 'q_1',
+    plateNo: '浙A12345',
+    feeItems: [{ name: '停车费（3 小时）', amountText: '15.00 元' }],
+    totalText: '15.00 元',
+    payableText: '10.00 元',
+    discountText: '5.00 元',
+    appliedBenefits: [
+      { benefitRef: 'b_1', title: '会员停车 95 折', discountText: '0.75 元' },
+    ],
+    selectableBenefits: [
+      { benefitRef: 'b_2', title: '积分抵 5 元', autoSelected: false },
+    ],
+    revision: 2,
+    caveats: ['费用以出场实际计费为准'],
+  };
+  const resultSample = {
+    paymentRef: 'p_1',
+    plateNo: '浙A12345',
+    status: 'PAID',
+    amountText: '10.00 元',
+    message: '支付成功',
+  };
+  const recordsSample = {
+    items: [
+      {
+        recordRef: 'r_1',
+        plateNo: '浙A12345',
+        amountText: '10.00 元',
+        paidAtText: '08-14 10:00',
+        status: 'PAID',
+      },
+    ],
+    total: 1,
+    hasMore: false,
+    caveats: ['仅展示近 6 个月记录'],
+  };
+  const vehiclesSample = {
+    bound: [
+      { vehicleRef: 'v_1', plateNo: '浙A12345', parked: true },
+      { vehicleRef: 'v_2', plateNo: '浙B67890' },
+    ],
+  };
+  const infoSample = {
+    kind: 'chargeRules',
+    title: '收费规则',
+    entries: [{ label: '首小时', value: '5.00 元' }],
+  };
+
+  it('全部 sample 解析通过', () => {
+    const samples: Record<string, unknown> = {
+      'parking-payment': paymentSample,
+      'parking-payment-result': resultSample,
+      'parking-payment-records': recordsSample,
+      'parking-vehicle-management': vehiclesSample,
+      'parking-info': infoSample,
+    };
+    for (const [cardType, data] of Object.entries(samples)) {
+      const schema =
+        parkingCardDataSchemas[cardType as keyof typeof parkingCardDataSchemas];
+      expect(schema.safeParse(data).success, `${cardType} should parse`).toBe(
+        true,
+      );
+    }
+  });
+
+  it('payment 缺 revision 拒绝（乐观锁必填）', () => {
+    const { revision: _rev, ...withoutRevision } = paymentSample;
+    expect(
+      parkingCardDataSchemas['parking-payment'].safeParse(withoutRevision)
+        .success,
+    ).toBe(false);
+  });
+
+  it('缴费记录接受详情、开票状态与动作反馈字段', () => {
+    const result = parkingCardDataSchemas['parking-payment-records'].safeParse({
+      ...recordsSample,
+      message: '开票申请已提交',
+      items: [
+        {
+          ...recordsSample.items[0],
+          orderCompleted: true,
+          invoiceEligible: false,
+          invoiceIssued: true,
+        },
+      ],
+    });
+    expect(result.success).toBe(true);
+    expect(result.success && result.data.message).toBe('开票申请已提交');
+    expect(result.success && result.data.items[0]?.invoiceIssued).toBe(true);
+  });
+});
+
+describe('member 入会 2 卡 schema（015 扩展）', () => {
+  const formSample = {
+    userId: 'u_1',
+    state: 'not_enrolled',
+    formVersion: 'v2026.08',
+    fields: [
+      {
+        fieldId: 'mobile',
+        label: '手机号',
+        type: 'tel',
+        required: true,
+        readOnly: true,
+        prefill: '138****0000',
+      },
+      { fieldId: 'displayName', label: '姓名', type: 'text', required: false },
+    ],
+    consents: [
+      {
+        consentId: 'privacy',
+        version: '1',
+        title: '隐私政策',
+        required: true,
+        url: 'https://example.com/privacy',
+      },
+    ],
+    authorization: { status: 'authorized', mobileMasked: '138****0000' },
+  };
+  const statusSample = {
+    userId: 'u_1',
+    attemptRef: 'att_1',
+    state: 'pending_confirmation',
+    message: '厂商确认中，请稍后刷新',
+  };
+
+  it('form/status sample 解析通过', () => {
+    expect(
+      memberEnrollmentFormCardDataSchema.safeParse(formSample).success,
+    ).toBe(true);
+    expect(
+      memberEnrollmentStatusCardDataSchema.safeParse(statusSample).success,
+    ).toBe(true);
+  });
+
+  it('form 缺 formVersion/authorization 拒绝', () => {
+    const { formVersion: _f, ...a } = formSample;
+    expect(memberEnrollmentFormCardDataSchema.safeParse(a).success).toBe(false);
+    const { authorization: _au, ...b } = formSample;
+    expect(memberEnrollmentFormCardDataSchema.safeParse(b).success).toBe(false);
+  });
+});
+
+describe('member 入会 CTA 状态边界', () => {
+  const sample = {
+    userId: 'u_1',
+    authState: 'authenticated',
+    state: 'not_enrolled',
+    enrollUrl: 'alipays://platformapi/startapp?appId=demo&page=enroll',
+  } as const;
+
+  it('只接受已登录的未入会/已关闭状态与受支持地址', () => {
+    expect(memberEnrollmentCtaCardDataSchema.safeParse(sample).success).toBe(true);
+    expect(memberEnrollmentCtaCardDataSchema.safeParse({ ...sample, state: 'unknown' }).success).toBe(false);
+    expect(memberEnrollmentCtaCardDataSchema.safeParse({ ...sample, authState: 'unauthenticated' }).success).toBe(false);
+    expect(memberEnrollmentCtaCardDataSchema.safeParse({ ...sample, enrollUrl: 'javascript:alert(1)' }).success).toBe(false);
+  });
+});
+
+describe('host-effect 协议单源（P1，经 contracts-mall 传递可达）', () => {
+  it('TBOX_EFFECT_EVENT_NAME 从 contracts re-export 可达', async () => {
+    const contracts = await import('@tbox.cn/app-contracts');
+    expect(contracts.TBOX_EFFECT_EVENT_NAME).toBe('tbox:effect');
+    expect(TBOX_EFFECT_EVENT_NAME).toBe('tbox:effect');
+    expect(contracts.TBOX_EFFECT_EVENT_NAME).toBe(TBOX_EFFECT_EVENT_NAME);
+  });
+});

package/tests/context-unification.test.ts

@@ -0,0 +1,73 @@
+/**
+ * 上下文统一化 Stage 2 锁：mallSlot（TIER0 ContextSlot 协议接线）、mallIdentityView（身份视图组装）。
+ */
+import { describe, expect, it } from 'vitest';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { mallSlot, parseMallScope, extractMallScope, MALL_SCOPE_KEY } from '../src/scope';
+import { mallIdentityView } from '../src/server/mall-context';
+
+const IDENTITY = { userId: 'u_1', source: 'external' as const };
+
+const SCOPE = { miniAppId: 'mp_1', mallId: 'm_1', subjectId: 's_1' };
+
+const FULL_CTX: RequestContext = {
+  identity: IDENTITY,
+  conversationId: 'c_1',
+  credentials: {
+    token: 'tok_1',
+    provider: 'mall-gateway',
+    attributes: { openid: 'o_abc', memberId: 'mb_9' },
+  },
+  attributes: { [MALL_SCOPE_KEY]: SCOPE },
+};
+
+describe('mallSlot（TIER0 槽位协议接线）', () => {
+  it('read：合法 attributes.mall → 解析结果；引用键 = MALL_SCOPE_KEY', () => {
+    expect(mallSlot.key).toBe('mall');
+    expect(mallSlot.read({ [MALL_SCOPE_KEY]: SCOPE })).toEqual(SCOPE);
+  });
+
+  it('read fail-soft：缺省/非法形状/解析失败 → undefined（不 throw）', () => {
+    expect(mallSlot.read(undefined)).toBeUndefined();
+    expect(mallSlot.read({})).toBeUndefined();
+    expect(mallSlot.read({ [MALL_SCOPE_KEY]: 'plain-string' })).toBeUndefined();
+    // v4：mallId-only 合法（miniAppId 可选——N1 缺陷修复）；解析失败面收敛到 mallId 缺失/非法
+    expect(mallSlot.read({ [MALL_SCOPE_KEY]: { mallId: 'm_1' } })).toEqual({ mallId: 'm_1' });
+    expect(mallSlot.read({ [MALL_SCOPE_KEY]: { miniAppId: 'a' } })).toBeUndefined(); // 缺 mallId（会话边界键）
+    expect(mallSlot.read({ [MALL_SCOPE_KEY]: { mallId: '' } })).toBeUndefined(); // 空 mallId 非法
+  });
+
+  it('parseMallScope 薄包装与 slot 等价；extractMallScope 从 RequestContext 提取', () => {
+    expect(parseMallScope(FULL_CTX.attributes)).toEqual(mallSlot.read(FULL_CTX.attributes));
+    expect(extractMallScope(FULL_CTX)).toEqual(SCOPE);
+  });
+});
+
+describe('mallIdentityView（身份视图组装）', () => {
+  it('全字段：identity 原样 + scope + token + memberId + openId', () => {
+    const view = mallIdentityView(FULL_CTX);
+    expect(view.identity).toBe(IDENTITY);
+    expect(view.scope).toEqual(SCOPE);
+    expect(view.sessionToken).toBe('tok_1');
+    expect(view.memberId).toBe('mb_9');
+    expect(view.openId).toBe('o_abc');
+  });
+
+  it('最小形态：无 credentials/attributes → scope undefined、token 空串、可选字段缺省', () => {
+    const view = mallIdentityView({ identity: { userId: 'anon_1', source: 'anonymous' } });
+    expect(view.scope).toBeUndefined();
+    expect(view.sessionToken).toBe('');
+    expect(view.memberId).toBeUndefined();
+    expect(view.openId).toBeUndefined();
+  });
+
+  it('非法 mall scope（fail-soft）不阻断视图组装', () => {
+    const view = mallIdentityView({
+      identity: IDENTITY,
+      // v4：mallId-only 已合法（miniAppId 可选）——非法形状用「缺会话边界键 mallId」代表
+      attributes: { [MALL_SCOPE_KEY]: { miniAppId: 'app-only' } },
+    });
+    expect(view.scope).toBeUndefined();
+    expect(view.identity).toBe(IDENTITY);
+  });
+});