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

package/src/member/cards.ts

@@ -0,0 +1,209 @@
+/**
+ * 会员域卡片数据契约（011 K2：member 卡 zod schema，TIER1；券面 0.4.0 净删——promotion 承接）。
+ */
+import { z } from 'zod';
+
+export const memberAuthStateSchema = z.enum(['authenticated', 'unauthenticated']);
+export const memberStateSchema = z.enum(['unknown', 'active', 'not_enrolled', 'closed']);
+
+/** PRD 6.6 首批会员偏好问题；卡片展示、意图路由与记忆写入共用同一真源。 */
+export const MEMBER_PREFERENCE_VALUES = [
+  '我常来买衣服',
+  '我常带娃来玩',
+  '我常来吃美食',
+] as const;
+export const memberPreferenceValueSchema = z.enum(MEMBER_PREFERENCE_VALUES);
+export type MemberPreferenceValue = z.infer<typeof memberPreferenceValueSchema>;
+
+export const MEMBER_PREFERENCE_PROMPTS: ReadonlyArray<{
+  value: MemberPreferenceValue;
+  query: string;
+}> = MEMBER_PREFERENCE_VALUES.map((value) => ({ value, query: value }));
+
+/** 按偏好触发导购能力时使用的检索语句；与用户可见按钮文案解耦。 */
+export const MEMBER_PREFERENCE_RECOMMENDATION_QUERIES: Readonly<Record<MemberPreferenceValue, string>> = {
+  '我常来买衣服': '推荐适合购买的服装门店和商品',
+  '我常带娃来玩': '推荐适合带娃的亲子娱乐门店',
+  '我常来吃美食': '推荐值得去的餐饮美食门店',
+};
+
+/** member-info：账户 + 资料摘要 */
+export const memberInfoCardDataSchema = z.object({
+  userId: z.string().min(1),
+  authState: memberAuthStateSchema,
+  state: memberStateSchema,
+  displayName: z.string().optional(),
+  avatarUrl: z.string().optional(),
+  contactDisplay: z.string().optional(),
+  memberRef: z.string().optional(),
+  registeredAt: z.string().optional(),
+  labels: z.array(z.object({ labelRef: z.string(), name: z.string() })),
+});
+export type MemberInfoCardData = z.infer<typeof memberInfoCardDataSchema>;
+
+/** member-card-summary：会员卡面（真实卡名、卡图与积分摘要） */
+export const memberCardSummaryCardDataSchema = z.object({
+  userId: z.string().min(1),
+  cardRef: z.string(),
+  cardDisplay: z.string(),
+  status: z.enum(['active', 'inactive', 'frozen', 'expired', 'unknown']),
+  levelName: z.string().optional(),
+  availablePoints: z.number().int().min(0),
+  cardImageUrl: z.string().optional(),
+  pointsRuleImageUrl: z.string().url().optional(),
+  pointsRuleContent: z.string().min(1).max(20_000).optional(),
+  pointsUrl: z.string().url().optional(),
+  presentation: z.object({
+    variant: z.enum(['blue', 'silver', 'gold', 'black']),
+    labelsEmbedded: z.boolean().optional(),
+  }).optional(),
+  progress: z.object({
+    daySpentCents: z.number().int().min(0),
+    yearSpentCents: z.number().int().min(0),
+    percent: z.number().min(0).max(100),
+    message: z.string().min(1).max(256),
+  }).optional(),
+  benefits: z.array(z.object({
+    benefitRef: z.string().min(1),
+    name: z.string().min(1).max(128),
+    iconUrl: z.string().url().optional(),
+    description: z.string().min(1).max(128).optional(),
+    action: z.object({
+      kind: z.enum(['miniapp', 'dialog', 'toast']),
+      url: z.string().url().optional(),
+      title: z.string().min(1).max(128).optional(),
+      text: z.string().min(1).max(2_048).optional(),
+    }).optional(),
+  })).max(20).optional(),
+  /** 入会后偏好引导；首批固定三项，保留数组形态便于后续扩展。 */
+  preferencePrompts: z.array(z.object({
+    value: memberPreferenceValueSchema,
+    query: z.string().min(1).max(128),
+  })).max(8).optional(),
+});
+export type MemberCardSummaryCardData = z.infer<typeof memberCardSummaryCardDataSchema>;
+
+/**
+ * member-point-usage-list（011 K3：余额、厂商会员标签与积分流水）。
+ */
+export const memberPointUsageListCardDataSchema = z.object({
+  userId: z.string().min(1),
+  balance: z.number().int(),
+  membershipLabel: z.string().optional(),
+  items: z.array(
+    z.object({
+      usageRecordRef: z.string(),
+      title: z.string(),
+      amount: z.string(),
+      usedAt: z.string().optional(),
+      description: z.string().optional(),
+    }),
+  ),
+  total: z.number().int().min(0),
+});
+export type MemberPointUsageListCardData = z.infer<typeof memberPointUsageListCardDataSchema>;
+
+/** member-enrollment-form（入会表单；015 升级：授权预填 + consent + formVersion） */
+export const memberEnrollmentFormCardDataSchema = z.object({
+  userId: z.string().min(1),
+  state: memberStateSchema,
+  /** 表单版本（幂等键组成部分） */
+  formVersion: z.string().min(1),
+  /** 表单字段（readOnly = 授权预填锁定；prefill = 预填值） */
+  fields: z.array(
+    z.object({
+      fieldId: z.string(),
+      label: z.string(),
+      type: z.enum(['text', 'tel', 'select', 'date']),
+      required: z.boolean(),
+      readOnly: z.boolean().optional(),
+      prefill: z.string().optional(),
+      placeholder: z.string().optional(),
+      options: z.array(z.string()).optional(),
+    }),
+  ),
+  /** 隐私/条款同意项（required 必勾） */
+  consents: z.array(
+    z.object({
+      consentId: z.string(),
+      version: z.string(),
+      title: z.string(),
+      required: z.boolean(),
+      url: z.string().optional(),
+    }),
+  ),
+  /** 支付宝授权状态（required → 渲染授权按钮；authorized → mobile 预填 readOnly） */
+  authorization: z.object({
+    status: z.enum(['required', 'authorized', 'unavailable']),
+    mobileMasked: z.string().optional(),
+  }),
+  /** 手动填写模式提示（授权不可用降级） */
+  manualNotice: z.string().optional(),
+});
+export type MemberEnrollmentFormCardData = z.infer<typeof memberEnrollmentFormCardDataSchema>;
+
+/** member-enrollment-status（入会结果状态卡；pending 态附显式刷新按钮，R4） */
+export const memberEnrollmentStatusCardDataSchema = z.object({
+  userId: z.string().min(1),
+  attemptRef: z.string().optional(),
+  state: z.enum(['pending_confirmation', 'confirmation_timeout', 'active', 'failed']),
+  memberRef: z.string().optional(),
+  message: z.string().optional(),
+});
+export type MemberEnrollmentStatusCardData = z.infer<typeof memberEnrollmentStatusCardDataSchema>;
+
+/** member-enrollment-cta：开卡入会引导卡（点击跳转 alipays 链接） */
+export const memberEnrollmentCtaCardDataSchema = z.object({
+  userId: z.string().min(1),
+  authState: z.literal('authenticated'),
+  state: z.enum(['not_enrolled', 'closed']),
+  /**
+   * alipays:// 深链，由部署配置注入；**可选透传素材**——出卡不依赖它，
+   * 壳能力（getLoginState/openGate）缺席时兜底 openLink 用，未配置恒出卡（无此字段）
+   */
+  enrollUrl: z.string().min(1).refine((value) => value.startsWith('alipays://') || value.startsWith('https://'), {
+    message: 'enrollUrl must use alipays:// or https://',
+  }).optional(),
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  /**
+   * 入会权益提示列表（工具层注入通用文案；不得包含折扣/免费停车等未经系统确认的承诺）。
+   * 缺省不展示，由渲染层按有无决定是否渲染区块。
+   */
+  perks: z.array(z.string()).optional(),
+});
+export type MemberEnrollmentCtaCardData = z.infer<typeof memberEnrollmentCtaCardDataSchema>;
+
+/**
+ * member-login-cta：未登录引导卡（点击跳转商场小程序登录页，登录后回到智能体）。
+ *
+ * 与 member-enrollment-cta 的分界：**登录 ≠ 入会**。这张卡的前提是「还没有身份」，
+ * 故不带 userId / authState——那两个字段此刻根本拿不到。开卡入会是登录之后的下一步。
+ *
+ * 说明文案由组件写死（「登录后可解锁全部功能」）：曾按触发场景分别注入，实测各处理由
+ * 大同小异，留一个 optional 字段只会变成没人写的死字段。真要分场景再加回来。
+ */
+export const memberLoginCtaCardDataSchema = z.object({
+  /**
+   * 商场小程序登录页深链，由部署配置注入；**可选透传素材**——出卡不依赖它，
+   * 壳能力（getLoginState）缺席时兜底 openLink 用，未配置恒出卡（无此字段）
+   */
+  loginUrl: z.string().min(1).refine((value) => value.startsWith('alipays://') || value.startsWith('https://'), {
+    message: 'loginUrl must use alipays:// or https://',
+  }).optional(),
+  title: z.string().optional(),
+});
+export type MemberLoginCtaCardData = z.infer<typeof memberLoginCtaCardDataSchema>;
+
+/** 7 卡 schema map（cardType → dataSchema；券面 0.4.0 净删——promotion 承接） */
+export const memberCardDataSchemas = {
+  'member-info': memberInfoCardDataSchema,
+  'member-card-summary': memberCardSummaryCardDataSchema,
+  'member-point-usage-list': memberPointUsageListCardDataSchema,
+  'member-enrollment-form': memberEnrollmentFormCardDataSchema,
+  'member-enrollment-status': memberEnrollmentStatusCardDataSchema,
+  'member-enrollment-cta': memberEnrollmentCtaCardDataSchema,
+  'member-login-cta': memberLoginCtaCardDataSchema,
+} as const;
+
+export type MemberCardType = keyof typeof memberCardDataSchemas;

package/src/parking/cards.ts

@@ -0,0 +1,233 @@
+/**
+ * 停车域卡片数据契约（015：parking 5 卡 zod schema，TIER1）。
+ * 源：POC parking 11 卡型收敛（V6/D7）；金额展示层字符串化（D11）。
+ */
+import { z } from 'zod';
+
+/** parking-payment：缴费确认主卡（报价 + 权益 + revision） */
+
+/**
+ * 厂商协议 openParkingPay 的 orderInfo zod schema（与 ParkingPayOrderInfo 对齐）。
+ * 壳用这些字段自己拼确认页,不回查费。parkingId 协议已定 string。
+ */
+export const parkingOrderInfoSchema = z.object({
+  /** 停车秒数 */
+  staySecond: z.number().int().nonnegative().optional(),
+  /** 停车费,单位分 */
+  parkingFee: z.number().int().nonnegative().optional(),
+  /** 车牌绑定状态 */
+  bindingStatus: z.number().int().optional(),
+  /** 车牌 */
+  plateNumber: z.string().min(1).optional(),
+  /** 1=在场缴费,2=逃费/欠费 */
+  orderType: z.number().int(),
+  /** 车场侧订单号 */
+  spParkingOrderId: z.string().min(1).optional(),
+  /** 车场 ID(协议定 string) */
+  parkingId: z.string().min(1),
+  /** 入场时间 */
+  entranceTime: z.string().min(1).optional(),
+  /** 逗号分隔的能力枚举,如 "LEVEL_DISCOUNT,POINT_DISCOUNT,COUPON" */
+  supportDiscount: z.string().min(1).optional(),
+});
+export const parkingPaymentCardDataSchema = z.object({
+  quoteRef: z.string().min(1),
+  plateNo: z.string().min(1),
+  entryAtText: z.string().optional(),
+  durationText: z.string().optional(),
+  /** 费用明细（label + 金额字符串） */
+  feeItems: z.array(z.object({ name: z.string(), amountText: z.string() })),
+  totalText: z.string(),
+  discountText: z.string().optional(),
+  payableText: z.string(),
+  /** 当前请求主体的会员状态；旧历史卡可缺省。 */
+  membership: z
+    .object({
+      state: z.enum(['unauthenticated', 'unknown', 'active', 'not_enrolled', 'closed', 'unavailable']),
+      availablePoints: z.number().int().min(0).optional(),
+    })
+    .optional(),
+  /** 服务端归一化后的支付入口；客户端不解析权益标题。 */
+  paymentOptions: z
+    .object({
+      direct: z.object({
+        /** 已应用积分时 Provider 未必能预览无积分金额；缺省时客户端不得提前承诺金额。 */
+        payableText: z.string().optional(),
+        benefitRefs: z.array(z.string()),
+      }),
+      points: z
+        .discriminatedUnion('kind', [
+          z.object({
+            kind: z.literal('exact'),
+            pointsToUse: z.number().int().positive(),
+            payableText: z.string(),
+            benefitRefs: z.array(z.string()).min(1),
+          }),
+          z.object({
+            kind: z.literal('requires_reprice'),
+            title: z.string().min(1),
+            benefitRefs: z.array(z.string()).min(1),
+          }),
+        ])
+        .optional(),
+    })
+    .optional(),
+  /** 已生效权益 */
+  appliedBenefits: z.array(
+    z.object({
+      benefitRef: z.string(),
+      title: z.string(),
+      discountText: z.string().optional(),
+    }),
+  ),
+  /** 可变更权益（reprice 候选；autoSelected 预勾选） */
+  selectableBenefits: z.array(
+    z.object({
+      benefitRef: z.string(),
+      title: z.string(),
+      autoSelected: z.boolean(),
+      description: z.string().optional(),
+      /** 权益类型（券 / 积分抵扣 / 等级权益）；客户端据此分组与判定互斥，不得从标题猜测 */
+      kind: z.enum(['points', 'discount', 'coupon', 'other']).optional(),
+      /** 预估优惠金额文案（本地展示用；权威金额以 reprice 回填为准） */
+      discountText: z.string().optional(),
+      /**
+       * 与本权益互斥的类型。三类优惠默认可叠加，互斥是厂商按券配置的例外——
+       * 标记 ['points'] 表示该券不可与积分抵扣叠加。判定双向生效。
+       */
+      exclusiveWithKinds: z.array(z.enum(['points', 'discount', 'coupon'])).optional(),
+    }),
+  ),
+  /** 乐观锁（提交校验；过期 → 提示重新查询） */
+  revision: z.number().int().min(1),
+  caveats: z.array(z.string()),
+  /**
+   * 支付交接包:客户端卡据 kind 调壳 tbox 能力收款——
+   * kind:'pay' → openParkingPay(传 orderInfo,壳跳确认页/收银台);kind:'unpaid' → openParkingUnpaidOrder(传 orderNo)。
+   * 缺省 = 走内部 confirm-payment(line)支付链。
+   */
+  payHandoff: z
+    .object({
+      kind: z.enum(['pay', 'unpaid']),
+      parkingStoreId: z.string().min(1).optional(),
+      orderInfo: parkingOrderInfoSchema.optional(),
+      orderNo: z.string().min(1).optional(),
+    })
+    .optional(),
+  /**
+   * 支付进度（缺省 = 未发起）：一经写入这张报价单即终结，按钮恒置灰。
+   * 报价是一次性的（token singleUse + revision 乐观锁），发起支付后不可再提交。
+   */
+  settlement: z
+    .object({
+      state: z.enum(['paying', 'paid', 'failed']),
+      text: z.string().min(1),
+    })
+    .optional(),
+});
+export type ParkingPaymentCardData = z.infer<
+  typeof parkingPaymentCardDataSchema
+>;
+
+/** parking-payment-result：支付结果（reconcile 权威） */
+export const parkingPaymentResultCardDataSchema = z.object({
+  paymentRef: z.string().min(1),
+  plateNo: z.string(),
+  status: z.enum(['PAID', 'CANCELLED', 'UNKNOWN']),
+  amountText: z.string().optional(),
+  message: z.string(),
+  /** 失败/取消：可重新发起（重新查询报价） */
+  retryable: z.boolean().optional(),
+  /** 离场时限提醒（PAID：缴费后免费离场窗口，超时重新计费） */
+  leaveNotice: z.string().optional(),
+  /** 回执明细（车牌 / 停车时长 / 缴费时间等，服务端已格式化） */
+  details: z
+    .array(z.object({ label: z.string(), value: z.string() }))
+    .optional(),
+});
+export type ParkingPaymentResultCardData = z.infer<
+  typeof parkingPaymentResultCardDataSchema
+>;
+
+/** parking-payment-records：缴费记录 */
+export const parkingPaymentRecordsCardDataSchema = z.object({
+  items: z.array(
+    z.object({
+      recordRef: z.string().min(1),
+      plateNo: z.string(),
+      amountText: z.string(),
+      paidAtText: z.string(),
+      status: z.enum(['PAID', 'REFUNDED', 'CLOSED', 'UNKNOWN']),
+      statusText: z.string().optional(),
+      parkName: z.string().optional(),
+      plazaName: z.string().optional(),
+      /** 展开态字段（entry/exit/单号脱敏） */
+      entryAtText: z.string().optional(),
+      exitAtText: z.string().optional(),
+      payOrderNoMasked: z.string().optional(),
+      orderCompleted: z.boolean().optional(),
+      invoiceEligible: z.boolean().optional(),
+      invoiceIssued: z.boolean().optional(),
+    }),
+  ),
+  total: z.number().int().min(0),
+  hasMore: z.boolean(),
+  /** 厂商口径 caveats（厂商事实，7 条并入） */
+  caveats: z.array(z.string()),
+  /** 详情加载、开票提交等动作反馈 */
+  message: z.string().optional(),
+});
+export type ParkingPaymentRecordsCardData = z.infer<
+  typeof parkingPaymentRecordsCardDataSchema
+>;
+
+/** parking-vehicle-management：绑定车辆列表（parked 缺省 = provider 无入场查询能力） */
+export const parkingVehicleManagementCardDataSchema = z.object({
+  bound: z.array(z.object({
+    vehicleRef: z.string(),
+    plateNo: z.string(),
+    parked: z.boolean().optional(),
+  })),
+  message: z.string().optional(),
+  /**
+   * 会员状态（缺省 = 未探测）：仅 not_enrolled 才展示入会引导。
+   * 与 parking-payment 的 membership 同源，避免两张卡对同一用户给出不同判断。
+   */
+  membership: z
+    .object({
+      state: z.enum(['unauthenticated', 'unknown', 'active', 'not_enrolled', 'closed', 'unavailable']),
+    })
+    .optional(),
+});
+export type ParkingVehicleManagementCardData = z.infer<
+  typeof parkingVehicleManagementCardDataSchema
+>;
+
+/**
+ * 中国大陆车牌正则（双端单一真源）：server zod 入参与 client plateValid
+ * 同源引用——曾双份漂移（server 严格 / client 宽松 ≥5 字符）。
+ * 首位放开字母：支持省份汉字 + 字母（A-HJ-NP-Z，无 I/O）双形态首位。
+ * 普通牌 = 首位 + 字母 + 5 位字母数字（末位可含挂学警港澳）= 7 字符；
+ * 新能源 = 首位 + 字母 + 字母数字 + 5 位字母数字 = 8 字符。
+ */
+export const PARKING_PLATE_PATTERN =
+  /^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领A-HJ-NP-Z][A-HJ-NP-Z](?:[A-HJ-NP-Z0-9]{6}|[A-HJ-NP-Z0-9]{4}[A-HJ-NP-Z0-9挂学警港澳])$/;
+
+/** parking-info：综合信息（三合一 kind；待支付单已并入 parking-payment） */
+export const parkingInfoCardDataSchema = z.object({
+  kind: z.enum(['chargeRules', 'benefitPolicy', 'vehicleLocation']),
+  title: z.string().min(1),
+  entries: z.array(z.object({ label: z.string(), value: z.string() })),
+});
+export type ParkingInfoCardData = z.infer<typeof parkingInfoCardDataSchema>;
+
+/** 5 卡 schema map（cardType → dataSchema） */
+export const parkingCardDataSchemas = {
+  'parking-payment': parkingPaymentCardDataSchema,
+  'parking-payment-result': parkingPaymentResultCardDataSchema,
+  'parking-payment-records': parkingPaymentRecordsCardDataSchema,
+  'parking-vehicle-management': parkingVehicleManagementCardDataSchema,
+  'parking-info': parkingInfoCardDataSchema,
+} as const;
+
+export type ParkingCardType = keyof typeof parkingCardDataSchemas;