@tbox.cn/app-module-member 0.2.0 → 0.8.7

package/src/client/types/css.d.ts

@@ -0,0 +1,2 @@
+/** 0.4.0 D1：模块自持 CSS（经 tsup loader: { '.css': 'copy' } 出货，样式在应用侧生效） */
+declare module '*.css';

package/src/server/action.ts

@@ -0,0 +1,348 @@
+/**
+ * member 写动作（015 S4：入会协议首验切片）。
+ *
+ * 四动作（全 singleUse + grant 闭环；cards key = meta.cardType）：
+ * - member.request-alipay-authorization：返回授权 effect（dispatcher 补签 → client getAuthCode）
+ * - member.complete-alipay-authorization：回调动作——消费 SDK createAlipayUserAuthorization
+ *   （011 J7 下沉物首个消费方），PII 经 ctx.state TTL 30min 最小集暂存（F2）
+ * - member.enroll：身份解析（授权 profile 可信 mobile 强制覆盖 / manual 正则）+ consent 校验
+ *   + 幂等键 sha256(userId\0mallId\0formVersion)（W3：模块顶层 InMemoryIdempotencyStore）
+ * - member.query-enrollment-status：显式刷新（R4：POC 自动轮询不迁）
+ */
+import { createHash } from 'node:crypto';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import { createAlipayUserAuthorization, InMemoryIdempotencyStore } from '@tbox.cn/app-sdk/server';
+import { parseMallScope } from '@tbox.cn/app-contracts-mall';
+import type { CardActionResult, RequestContext } from '@tbox.cn/app-contracts';
+import { z } from 'zod';
+
+/** PII 暂存命名空间（F2：TTL 30min + 最小字段 + enroll 成功即 consume 删除） */
+export const MEMBER_PROFILE_NAMESPACE = 'member.enrollment.profile';
+const PROFILE_TTL_MS = 30 * 60 * 1000;
+
+const MOBILE_PATTERN = /^1[3-9]\d{9}$/;
+
+/** 授权 profile 最小集（F2：不落完整厂商响应） */
+export interface StoredAuthorizationProfile {
+  readonly mobile?: string;
+  readonly displayName?: string;
+  readonly gender?: string;
+  readonly birthday?: string;
+}
+
+/** 入会表单形状（formVersion 随表单卡下发；与 contracts memberEnrollmentFormCardDataSchema 对齐） */
+export const ENROLLMENT_FORM_VERSION = 'v2026.08';
+const ENROLLMENT_CONSENTS = [
+  { consentId: 'privacy', version: '1', title: '隐私政策', required: true },
+  { consentId: 'membership-terms', version: '1', title: '会员服务条款', required: false },
+] as const;
+
+/** 模块顶层幂等单例（W3：IdempotencyStore 挂 HTTP gateway 非 ctx，模块自持） */
+const enrollmentIdempotency = new InMemoryIdempotencyStore();
+
+export function buildEnrollmentIdempotencyKey(userId: string, mallId: string, formVersion: string): string {
+  return createHash('sha256').update(`${userId}\u0000${mallId}\u0000${formVersion}`).digest('hex');
+}
+
+function maskMobile(mobile: string): string {
+  return mobile.length >= 7 ? `${mobile.slice(0, 3)}****${mobile.slice(-4)}` : '***';
+}
+
+function mallIdOf(ctx: RequestContext): string {
+  return parseMallScope(ctx.attributes)?.mallId ?? 'unknown';
+}
+
+function buildFormCard(input: {
+  userId: string;
+  state: 'active' | 'not_enrolled' | 'closed';
+  authorization: { status: 'required' | 'authorized' | 'unavailable'; mobileMasked?: string };
+  prefilled?: StoredAuthorizationProfile;
+  manualNotice?: string;
+}): CardActionResult['card'] {
+  return {
+    cardType: 'member-enrollment-form',
+    data: {
+      userId: input.userId,
+      state: input.state,
+      formVersion: ENROLLMENT_FORM_VERSION,
+      fields: [
+        {
+          fieldId: 'mobile',
+          label: '手机号',
+          type: 'tel',
+          required: true,
+          ...(input.authorization.status === 'authorized'
+            ? { readOnly: true, prefill: input.prefilled?.mobile ?? '', placeholder: maskMobile(input.authorization.mobileMasked ?? '') }
+            : { placeholder: '请输入手机号' }),
+        },
+        { fieldId: 'displayName', label: '姓名', type: 'text', required: false, ...(input.prefilled?.displayName ? { prefill: input.prefilled.displayName } : {}) },
+        ...(input.prefilled?.birthday ? [{ fieldId: 'birthday', label: '生日', type: 'date', required: false, prefill: input.prefilled.birthday }] : []),
+      ],
+      consents: ENROLLMENT_CONSENTS,
+      authorization: input.authorization,
+      ...(input.manualNotice ? { manualNotice: input.manualNotice } : {}),
+    },
+  };
+}
+
+/** 动作集工厂：register(ctx) 内调用（闭包 ctx.state——PII/attempt 落 SDK StateStore 实例） */
+export function createMemberActions(
+  ctx: ServerContext,
+  resolveMember: (reqCtx: RequestContext) => Promise<import('./ports').MemberEnrollmentService>,
+): Record<string, Parameters<ServerContext['cardActions']['register']>[0]> {
+  const state = ctx.state;
+
+  return {
+    /** 1. 发起支付宝授权（效果动作；resultActionId 由 dispatcher 补签校验） */
+    requestAuthorization: {
+      actionId: 'member.request-alipay-authorization',
+      moduleId: 'member',
+      cardType: 'member-enrollment-form',
+      label: '支付宝授权并填充',
+      singleUse: true,
+      inputSchema: z.object({}).passthrough(),
+      async execute(): Promise<CardActionResult> {
+        return {
+          text: '正在拉起支付宝授权…',
+          effects: [
+            {
+              type: 'authorization.alipay-user-profile',
+              scopes: ['auth_user'],
+              resultActionId: 'member.complete-alipay-authorization',
+            },
+          ],
+        };
+      },
+    },
+
+    /** 2. 授权回调（client getAuthCode → status/authCode 回传；补签 grant 单次消费；不渲染按钮） */
+    completeAuthorization: {
+      actionId: 'member.complete-alipay-authorization',
+      moduleId: 'member',
+      cardType: 'member-enrollment-form',
+      label: '授权结果回调',
+      singleUse: true,
+      hidden: true,
+      inputSchema: z.object({
+        status: z.enum(['success', 'cancel', 'failure', 'unavailable']),
+        authCode: z.string().optional(),
+      }),
+      async execute(input, reqCtx): Promise<CardActionResult> {
+        const { status, authCode } = (input ?? {}) as { status?: string; authCode?: string };
+        const userId = reqCtx?.identity?.userId ?? '';
+        if (!userId) {
+          return { text: '授权失败：缺少会话身份' };
+        }
+        if (status !== 'success' || !authCode) {
+          // cancel/failure/unavailable → manual 模式降级（保留重新授权入口）
+          return {
+            card: buildFormCard({
+              userId,
+              state: 'not_enrolled',
+              authorization: { status: 'unavailable' },
+              manualNotice: status === 'unavailable' ? '当前环境不支持支付宝授权，可手动填写手机号入会' : '授权未完成，可手动填写手机号入会',
+            }),
+            text: '授权未完成，已切换手动填写模式',
+          };
+        }
+        // 011 J7 下沉物首个消费方：authCode → alipay.user.info.share
+        let profile: StoredAuthorizationProfile;
+        try {
+          const authorized = await createAlipayUserAuthorization().authorizeUserProfile(authCode);
+          profile = {
+            ...(authorized.mobile ? { mobile: authorized.mobile } : {}),
+            ...(authorized.displayName ? { displayName: authorized.displayName } : {}),
+            ...(authorized.gender ? { gender: authorized.gender } : {}),
+            ...(authorized.birthday ? { birthday: authorized.birthday } : {}),
+          };
+        } catch (e) {
+          ctx.logger?.warn(`授权完成降级手动卡：err=${(e as Error).message}`);
+          return {
+            card: buildFormCard({
+              userId,
+              state: 'not_enrolled',
+              authorization: { status: 'unavailable' },
+              manualNotice: `授权资料获取失败（${(e as Error).message}），可手动填写`,
+            }),
+            text: '授权资料获取失败，已切换手动填写模式',
+          };
+        }
+        // F2：PII 最小集 TTL 30min 暂存（enroll 时 consume 取走 = 用后即删）
+        await state.put(MEMBER_PROFILE_NAMESPACE, userId, profile, PROFILE_TTL_MS);
+        return {
+          card: buildFormCard({
+            userId,
+            state: 'not_enrolled',
+            authorization: { status: 'authorized', mobileMasked: profile.mobile ?? '' },
+            prefilled: profile,
+          }),
+          text: '授权成功，已为你预填手机号，确认无误后提交入会',
+        };
+      },
+    },
+
+    /** 3. 提交入会（身份解析 + consent 校验 + 幂等 + PII consume） */
+    enroll: {
+      actionId: 'member.enroll',
+      moduleId: 'member',
+      cardType: 'member-enrollment-form',
+      label: '提交入会',
+      singleUse: true,
+      inputSchema: z.object({
+        fieldValues: z.record(z.string(), z.string()).optional(),
+        acceptedConsentIds: z.array(z.string()).optional(),
+        formVersion: z.string().optional(),
+      }),
+      async execute(input, reqCtx): Promise<CardActionResult> {
+        const { fieldValues = {}, acceptedConsentIds = [] } = (input ?? {}) as {
+          fieldValues?: Record<string, string>;
+          acceptedConsentIds?: string[];
+        };
+        const userId = reqCtx?.identity?.userId ?? '';
+        if (!userId) {
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId: '', state: 'failed', message: '缺少会话身份' } },
+            text: '入会失败：缺少身份信息',
+          };
+        }
+        const member = await resolveMember(reqCtx);
+        if (!member) {
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId, state: 'failed', message: '会员服务不可用' } },
+            text: '入会失败：会员服务不可用',
+          };
+        }
+
+        // consent 必勾校验
+        const missing = ENROLLMENT_CONSENTS.filter((c) => c.required && !acceptedConsentIds.includes(c.consentId));
+        if (missing.length > 0) {
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId, state: 'failed', message: `请先同意：${missing.map((c) => c.title).join('、')}` } },
+            text: '入会失败：未完成必选同意项',
+          };
+        }
+
+        // 身份解析：授权 profile（consume 取走 = F2 用后即删）可信 mobile 强制覆盖
+        const authorized = (await state.consume<StoredAuthorizationProfile>(MEMBER_PROFILE_NAMESPACE, userId)) ?? undefined;
+        const manualMobile = fieldValues.mobile ?? '';
+        const mobile = authorized?.mobile ?? manualMobile;
+        const identity = authorized?.mobile ? 'alipay_authorized' : 'enrollment_submission';
+        if (!mobile || !MOBILE_PATTERN.test(mobile)) {
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId, state: 'failed', message: '手机号格式不正确（授权预填失效请重新授权或手填）' } },
+            text: '入会失败：手机号格式不正确',
+          };
+        }
+
+        // 幂等（W3：同键重入返回首果）
+        // 评审修复（015 #5）：payload 存 sha256 摘要——幂等占位不再驻留明文手机号（F2 单一暂存位语义）
+        const idempotencyKey = buildEnrollmentIdempotencyKey(userId, mallIdOf(reqCtx), ENROLLMENT_FORM_VERSION);
+        const payloadTag = createHash('sha256').update(`${identity}:${mobile}`).digest('hex').slice(0, 16);
+        const acquired = await enrollmentIdempotency.tryAcquire(idempotencyKey, payloadTag);
+        if (!acquired.acquired) {
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId, state: 'failed', message: '重复提交，请稍后在入会状态中刷新确认结果' } },
+            text: '请勿重复提交，可刷新查看入会状态',
+          };
+        }
+
+        // 评审修复（015 #3）：厂商异常 = 瞬时失败——释放幂等占位可重试，不固化 24h 拒绝
+        let result: Awaited<ReturnType<typeof member.enroll>>;
+        try {
+          result = await member.enroll({
+            userId,
+            identity,
+            fieldValues: {
+              ...fieldValues,
+              mobile,
+              ...(fieldValues.displayName || authorized?.displayName ? { displayName: fieldValues.displayName || authorized?.displayName } : {}),
+              ...(fieldValues.birthday || authorized?.birthday ? { birthday: fieldValues.birthday || authorized?.birthday } : {}),
+              ...(fieldValues.gender || authorized?.gender ? { gender: fieldValues.gender || authorized?.gender } : {}),
+            },
+            acceptedConsentIds,
+            idempotencyKey,
+            formVersion: ENROLLMENT_FORM_VERSION,
+          });
+        } catch (e) {
+          enrollmentIdempotency.release?.(idempotencyKey);
+          ctx.logger?.warn(`入会失败（幂等已释放 key=${idempotencyKey.slice(0, 8)}…）：err=${(e as Error).message}`);
+          return {
+            card: { cardType: 'member-enrollment-status', data: { userId, state: 'failed', message: '入会请求失败，请稍后重试' } },
+            text: '入会请求失败，请重试',
+          };
+        }
+
+        const cardForResult = (r: typeof result): { cardType: string; data: Record<string, unknown> } => ({
+          cardType: 'member-enrollment-status',
+          data:
+            r.status === 'active'
+              ? { userId, state: 'active', memberRef: r.memberRef, message: '入会成功' }
+              : r.status === 'pending_confirmation'
+                ? { userId, attemptRef: r.attemptRef, state: 'pending_confirmation', message: '已提交，等待厂商确认（可点击刷新状态查看结果）' }
+                : { userId, state: 'failed', message: r.reason ?? '入会被拒绝' },
+        });
+        await enrollmentIdempotency.commit(idempotencyKey, result);
+        return {
+          card: cardForResult(result),
+          text:
+            result.status === 'active'
+              ? '入会成功，欢迎加入！'
+              : result.status === 'pending_confirmation'
+                ? '已提交入会申请，厂商确认中'
+                : `入会失败：${result.status === 'rejected' ? result.reason : '未知原因'}`,
+        };
+      },
+    },
+
+    /** 4. 入会状态显式刷新（R4：无自动轮询） */
+    queryEnrollmentStatus: {
+      actionId: 'member.query-enrollment-status',
+      moduleId: 'member',
+      cardType: 'member-enrollment-status',
+      label: '刷新状态',
+      singleUse: true,
+      inputSchema: z.object({ attemptRef: z.string().min(1) }),
+      async execute(input, reqCtx): Promise<CardActionResult> {
+        const { attemptRef } = (input ?? {}) as { attemptRef?: string };
+        const userId = reqCtx?.identity?.userId ?? '';
+        const member = await resolveMember(reqCtx);
+        if (!userId || !attemptRef || !member) {
+          // P0 原地更新：防御分支返回可见失败态（原 text 在 update 路径无消费者）
+          return {
+            update: {
+              data: {
+                userId,
+                state: 'failed',
+                message: '缺少入会记录引用',
+              },
+            },
+          };
+        }
+        const status = await member.getEnrollmentStatus(userId, attemptRef);
+        return {
+          update: {
+            data: {
+              userId,
+              attemptRef,
+              state: status.status,
+              ...(status.memberRef ? { memberRef: status.memberRef } : {}),
+              ...(status.status === 'active'
+                ? { message: '入会成功，欢迎加入！' }
+                : status.status === 'pending_confirmation'
+                  ? { message: '厂商确认中，可稍后再刷新' }
+                  : { message: status.reason ?? '入会未完成，请重新提交' }),
+            },
+          },
+        };
+      },
+    },
+  };
+}
+
+/** 供 index.ts 消费的动作 id 常量（装配/测试共用） */
+export const MEMBER_ACTION_IDS = {
+  requestAuthorization: 'member.request-alipay-authorization',
+  completeAuthorization: 'member.complete-alipay-authorization',
+  enroll: 'member.enroll',
+  queryEnrollmentStatus: 'member.query-enrollment-status',
+} as const;

package/src/server/cards/index.ts

@@ -1,31 +1,31 @@
 /**
- * 会员 7 卡 meta 聚合导出（每卡一个 meta.ts，doctor AST 约定）。
+ * 会员 7 卡 meta 聚合导出（每卡一个 meta.ts，doctor AST 约定；券面 0.4.0 净删——promotion 承接）。
  */
 import memberInfoMeta from './member-info/meta';
 import memberCardSummaryMeta from './member-card-summary/meta';
-import memberCouponListMeta from './member-coupon-list/meta';
-import memberCouponDetailMeta from './member-coupon-detail/meta';
 import memberPointUsageListMeta from './member-point-usage-list/meta';
 import memberEnrollmentFormMeta from './member-enrollment-form/meta';
 import memberEnrollmentStatusMeta from './member-enrollment-status/meta';
+import memberEnrollmentCtaMeta from './member-enrollment-cta/meta';
+import memberLoginCtaMeta from './member-login-cta/meta';
 
 export {
   memberInfoMeta,
   memberCardSummaryMeta,
-  memberCouponListMeta,
-  memberCouponDetailMeta,
   memberPointUsageListMeta,
   memberEnrollmentFormMeta,
   memberEnrollmentStatusMeta,
+  memberEnrollmentCtaMeta,
+  memberLoginCtaMeta,
 };
 
 /** 7 卡 meta map（key 约定 = cardType） */
 export const memberCards = {
   'member-info': memberInfoMeta,
   'member-card-summary': memberCardSummaryMeta,
-  'member-coupon-list': memberCouponListMeta,
-  'member-coupon-detail': memberCouponDetailMeta,
   'member-point-usage-list': memberPointUsageListMeta,
   'member-enrollment-form': memberEnrollmentFormMeta,
   'member-enrollment-status': memberEnrollmentStatusMeta,
+  'member-enrollment-cta': memberEnrollmentCtaMeta,
+  'member-login-cta': memberLoginCtaMeta,
 } as const;

package/src/server/cards/member-card-summary/meta.ts

@@ -1,21 +1,42 @@
 import type { CardMeta } from '@tbox.cn/app-contracts';
 import { memberCardSummaryCardDataSchema } from '@tbox.cn/app-contracts-mall';
+import { samples } from './samples';
 
 const meta: CardMeta<typeof memberCardSummaryCardDataSchema> = {
   cardType: 'member-card-summary',
   dataSchema: memberCardSummaryCardDataSchema,
-  allowedTools: ['queryMemberCard'],
   displayName: '会员卡面',
-  description: '会员卡信息（等级、积分摘要）',
+  description: '会员卡信息（真实卡名、动态卡面、积分与消费进度摘要）',
   sampleData: {
     userId: 'u_1001',
     cardRef: 'card:u_1001',
-    cardDisplay: '大悦城会员卡',
+    cardDisplay: '金卡会员',
     status: 'active',
-    levelName: 'gold',
     availablePoints: 860,
+    cardImageUrl: 'https://assets.example.com/member/gold-card.png',
+    pointsRuleImageUrl: 'https://assets.example.com/member/points-rule.jpg',
+    presentation: { variant: 'gold', labelsEmbedded: true },
+    progress: {
+      daySpentCents: 12_345,
+      yearSpentCents: 500_000,
+      percent: 25,
+      message: '今日已消费123.45元，年累计已消费5000.00元',
+    },
+    benefits: [
+      { benefitRef: 'benefit:parking', name: '免费停车', iconUrl: 'https://assets.example.com/member/parking.png' },
+      { benefitRef: 'benefit:points', name: '消费积分', iconUrl: 'https://assets.example.com/member/points.png' },
+      { benefitRef: 'benefit:gifts', name: '积分换礼', iconUrl: 'https://assets.example.com/member/gifts.png' },
+      { benefitRef: 'benefit:events', name: '会员活动', iconUrl: 'https://assets.example.com/member/events.png' },
+    ],
+    preferencePrompts: [
+      { value: '我常来买衣服', query: '我常来买衣服' },
+      { value: '我常带娃来玩', query: '我常带娃来玩' },
+      { value: '我常来吃美食', query: '我常来吃美食' },
+    ],
   },
-  schemaVersion: 1,
+  samples,
+  schemaVersion: 5,
+  migrate: (oldData) => oldData as Record<string, unknown>,
 };
 
 export default meta;