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

package/src/server/service.ts

@@ -5,38 +5,62 @@ import type {
   MemberBenefitsSnapshot,
   MemberCardPort,
   MemberCardSnapshot,
-  MemberCouponPort,
-  MemberCouponSnapshot,
+  MemberEnrollmentInput,
   MemberEnrollmentPort,
+  MemberEnrollmentResult,
+  MemberEnrollmentStatus,
   MemberProfilePort,
   MemberProfileSnapshot,
   Points,
   PointUsageRecord,
 } from '@tbox.cn/app-contracts-mall';
-import type { DiscountRule } from '@tbox.cn/app-contracts-mall';
+import type {
+  DiscountRule,
+  MemberEnrollmentFormDefinition,
+} from '@tbox.cn/app-contracts-mall';
 
 /**
- * MemberService：商圈会员完整实现（011 K2：6 Port 全量）。
+ * MemberService：商圈会员完整实现（011 K2 六 Port + 015 入会升级）。
  * extends 契约 Port（保证满足消费方子集约束）；完整接口只在本模块包内。
  */
+/**
+ * InMemory 演示实现（仅供隔离单测；运行时注册与 Provider 解析不得使用）。
+ * 017 槽位原子化后非 Port 成员归位：getEnrollmentFormDefinition 已收编
+ * MemberEnrollmentPort optional 方法（R13）；enrollUrl/loginUrl 为槽产物自由属性
+ * （enrollment/account 槽的类型视图见 ports.ts）；audit 转 InMemory 私有观测成员。
+ */
 export interface MemberService
   extends MemberAccountPort,
     MemberProfilePort,
     MemberCardPort,
     MemberBenefitsPort,
-    MemberCouponPort,
     MemberEnrollmentPort {
-  /** 积分变动记录（单测/观测用） */
-  audit: { action: string; userId: string; amount: number; key?: string }[];
+  /** 入会落地页深链（alipays:// 或 H5 链接），从 deployment provider config 注入；空串表示未配置。 */
+  readonly enrollUrl: string;
+  /**
+   * 登录页深链，同样从 deployment provider config 注入。
+   * 可选而非必填——真实 provider 接入前不该被迫实现；缺省时登录引导退回文本。
+   */
+  readonly loginUrl?: string;
 }
 
-/** 内存实现（PoC；真实数据源 = joycity-membership provider 接入点，二期） */
+// Form 族归源 TIER1（F5 下沉：provider 出参与模块投影共用同一契约面）
+export type {
+  MemberEnrollmentConsentDefinition,
+  MemberEnrollmentFormFieldDefinition,
+  MemberEnrollmentFormDefinition,
+} from '@tbox.cn/app-contracts-mall';
+
+/** 仅供隔离单测使用的 fixture；运行时注册与 Provider 解析不得使用。 */
 export class InMemoryMemberService implements MemberService {
+  readonly enrollUrl: string = '';
   private balances = new Map<string, number>();
-  private levels = new Map<string, 'silver' | 'gold' | 'platinum'>();
   private idempotentKeys = new Set<string>();
   private usages: PointUsageRecord[] = [];
   private profiles = new Map<string, MemberProfileSnapshot>();
+  private enrollmentAttempts = new Map<string, { result: MemberEnrollmentResult; userId: string }>();
+  private pendingConfirmations = new Set<string>();
+  private statusQueries = new Map<string, number>();
   audit: { action: string; userId: string; amount: number; key?: string }[] = [];
 
   constructor(initial: Record<string, number> = {}) {
@@ -49,6 +73,7 @@ export class InMemoryMemberService implements MemberService {
 
   async getAccount(userId: string): Promise<MemberAccountSnapshot> {
     return {
+      authState: 'authenticated',
       state: this.balances.has(userId) ? 'active' : 'not_enrolled',
       ...(this.balances.has(userId) ? { memberRef: `member:${userId}` } : {}),
       observedAt: new Date().toISOString(),
@@ -72,9 +97,8 @@ export class InMemoryMemberService implements MemberService {
     if (!this.balances.has(userId)) return null;
     return {
       cardRef: `card:${userId}`,
-      cardDisplay: '大悦城会员卡',
+      cardDisplay: '示例会员卡',
       status: 'active',
-      levelName: this.levelOf(userId),
       observedAt: new Date().toISOString(),
     };
   }
@@ -85,18 +109,29 @@ export class InMemoryMemberService implements MemberService {
     return {
       userId,
       balance: this.balances.get(userId) ?? 0,
-      level: this.levelOf(userId),
+      membershipLabel: '测试会员卡',
     };
   }
 
   async getBenefits(userId: string): Promise<MemberBenefitsSnapshot> {
     return {
       availablePoints: this.balances.get(userId) ?? 0,
-      levelName: this.levelOf(userId),
       observedAt: new Date().toISOString(),
     };
   }
 
+  async getEnrollmentFormDefinition(): Promise<MemberEnrollmentFormDefinition> {
+    return {
+      formVersion: 'fixture-v1',
+      fields: [
+        { fieldId: 'mobile', label: '手机号', type: 'tel', required: true, placeholder: '请输入手机号' },
+        { fieldId: 'displayName', label: '姓名', type: 'text', required: false },
+      ],
+      consents: [{ consentId: 'privacy', version: '1', title: '隐私政策', required: true }],
+      authorizationStatus: 'required',
+    };
+  }
+
   async listPointUsage(
     userId: string,
     page: number,
@@ -108,13 +143,8 @@ export class InMemoryMemberService implements MemberService {
   }
 
   async queryDiscount(userId: string): Promise<DiscountRule | undefined> {
-    const level = this.levelOf(userId);
-    const map: Record<string, DiscountRule> = {
-      silver: { level: 'silver', discount: 0.95 },
-      gold: { level: 'gold', discount: 0.9 },
-      platinum: { level: 'platinum', discount: 0.85 },
-    };
-    return map[level];
+    void userId;
+    return undefined;
   }
 
   async deductPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean> {
@@ -130,7 +160,6 @@ export class InMemoryMemberService implements MemberService {
       amount: `-${amount}`,
       usedAt: new Date().toISOString(),
     });
-    this.maybeUpgrade(userId);
     return true;
   }
 
@@ -159,75 +188,60 @@ export class InMemoryMemberService implements MemberService {
       amount: `+${amount}`,
       usedAt: new Date().toISOString(),
     });
-    this.maybeUpgrade(userId);
     return true;
   }
 
-  // ===== 5. MemberCouponPort =====
-
-  async listCoupons(
-    userId: string,
-    page: number,
-    pageSize: number,
-  ): Promise<{ items: ReadonlyArray<MemberCouponSnapshot>; total: number }> {
-    void userId;
-    void page;
-    void pageSize;
-    return { items: [], total: 0 };
-  }
+  // ===== 5. MemberCouponPort（0.4.0 净删——券域 promotion 承接，恒空面移除） =====
 
-  async getCoupon(_userId: string, _couponRef: string): Promise<MemberCouponSnapshot | null> {
-    return null;
-  }
+  // ===== 6. MemberEnrollmentPort（015：授权预填 + 幂等 + pending 收口） =====
 
-  // ===== 6. MemberEnrollmentPort =====
+  async enroll(input: MemberEnrollmentInput): Promise<MemberEnrollmentResult> {
+    // 幂等：同 idempotencyKey 重入返回首果（015 W3 语义，模块顶层 IdempotencyStore 之上的双保险）
+    const existing = this.enrollmentAttempts.get(input.idempotencyKey);
+    if (existing) return existing.result;
 
-  async enroll(input: { userId: string; name?: string; phone?: string }): Promise<{
-    success: boolean;
-    memberRef?: string;
-    error?: string;
-  }> {
-    if (!this.balances.has(input.userId)) {
-      this.balances.set(input.userId, 0);
+    const mobile = input.fieldValues.mobile ?? '';
+    if (!/^1[3-9]\d{9}$/.test(mobile)) {
+      return { status: 'rejected', reason: '手机号格式不正确' };
     }
-    this.profiles.set(input.userId, {
-      ...(input.name ? { displayName: input.name } : {}),
-      ...(input.phone ? { contactDisplay: input.phone } : {}),
-      labels: [{ labelRef: 'member', name: '会员' }],
-      observedAt: new Date().toISOString(),
-    });
-    return { success: true, memberRef: `member:${input.userId}` };
-  }
-
-  async completeAuthorization(input: { userId: string; scopes: readonly string[] }): Promise<{
-    success: boolean;
-  }> {
-    void input;
-    return { success: true };
-  }
-
-  // ===== 内部 =====
-
-  private levelOf(userId: string): 'silver' | 'gold' | 'platinum' {
-    const cached = this.levels.get(userId);
-    if (cached) return cached;
-    const balance = this.balances.get(userId) ?? 0;
-    if (balance >= 1000) return 'platinum';
-    if (balance >= 300) return 'gold';
-    return 'silver';
+    const result: MemberEnrollmentResult =
+      this.balances.has(input.userId) || this.pendingConfirmations.has(input.userId)
+        ? { status: 'active', memberRef: `member:${input.userId}` }
+        : { status: 'pending_confirmation', attemptRef: input.idempotencyKey };
+    if (result.status === 'active') {
+      this.profiles.set(input.userId, {
+        ...(input.fieldValues.displayName ? { displayName: input.fieldValues.displayName } : {}),
+        contactDisplay: mobile.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2'),
+        labels: [{ labelRef: 'member', name: '会员' }],
+        observedAt: new Date().toISOString(),
+      });
+    } else {
+      this.pendingConfirmations.add(input.userId);
+    }
+    this.enrollmentAttempts.set(input.idempotencyKey, { result, userId: input.userId });
+    return result;
   }
 
-  private maybeUpgrade(userId: string): void {
-    const newLevel = this.levelOf(userId);
-    const prev = this.levels.get(userId);
-    this.levels.set(userId, newLevel);
-    if (prev && prev !== newLevel) {
-      this.levelChangeListeners.forEach((fn) => fn({ userId, newLevel }));
+  async getEnrollmentStatus(
+    userId: string,
+    attemptRef: string,
+  ): Promise<{ status: MemberEnrollmentStatus; memberRef?: string; reason?: string }> {
+    const attempt = this.enrollmentAttempts.get(attemptRef);
+    if (!attempt || attempt.userId !== userId) {
+      return { status: 'failed', reason: '入会记录不存在或不属于当前用户' };
+    }
+    if (this.balances.has(userId)) {
+      return { status: 'active', memberRef: `member:${userId}` };
     }
+    // InMemory 模拟：首次查询 pending，第二次查询确认（厂商异步确认的演示语义）
+    const queried = this.statusQueries.get(attemptRef) ?? 0;
+    this.statusQueries.set(attemptRef, queried + 1);
+    if (queried >= 1) {
+      this.balances.set(userId, 0);
+      this.pendingConfirmations.delete(userId);
+      return { status: 'active', memberRef: `member:${userId}` };
+    }
+    return { status: 'pending_confirmation' };
   }
 
-  private levelChangeListeners = new Set<(e: { userId: string; newLevel: 'silver' | 'gold' | 'platinum' }) => void>();
-  onLevelChange(fn: (e: { userId: string; newLevel: 'silver' | 'gold' | 'platinum' }) => void): void {
-    this.levelChangeListeners.add(fn);
-  }
 }

package/src/server/status.ts

@@ -0,0 +1,87 @@
+/**
+ * 会员状态解析（IO 唯一入口）+ outcome 话术单源。
+ * soft 单档：任何失败收口 unavailable + warn 留痕——不伪装状态、不臆测未入会。
+ */
+import type {
+  MemberAccountSnapshot,
+  MemberOutcome,
+  MemberStatusResolution,
+} from '@tbox.cn/app-contracts-mall';
+import { classifyMemberOutcome } from '@tbox.cn/app-contracts-mall';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+import { resolveMemberAccountPort, resolveMemberEnrollmentPort } from './ports';
+
+/** 模块内超集（跨模块窄面 = 契约 MemberStatusResolution）。
+ *  017 槽位原子化：service 字段退役（跨槽 fat 类型谎言）——深链素材随 resolution 携带，
+ *  调用方（handler/跨模块 gate）按槽另行解析；厂商快照 memo 由共享 impl 的请求级
+ *  transport 缓存承接（多次构造廉价，行为变化声明④）。 */
+export interface ResolvedMemberStatus extends MemberStatusResolution {}
+
+/** 模型面话术（工具 noResultsReason 消费；与现状逐字节一致） */
+export const MEMBER_LOGIN_NOTICE = '请先登录；登录不要求开通会员';
+export const MEMBER_UNKNOWN_NOTICE = '当前无法确认会员状态，请稍后重试';
+/** 已登录未入会（GUEST/潜客）：下一步是入会引导而非「无积分」——与已退会拆分 */
+export const MEMBER_NOT_ENROLLED_NOTICE = '尚未入会，入会后可查询积分与服务';
+/** 已退会/资格关闭：账户在但积分语义为空（入会引导卡可另出，话术不混同） */
+export const MEMBER_NO_POINTS_NOTICE = '当前没有可查询的会员积分';
+
+/** 直聊面穷尽表（handler 消费；active 走业务路径不查表——Exclude 编译锁死） */
+export const MEMBER_QUERY_NOTICES: Record<Exclude<MemberOutcome | 'unavailable', 'active'>, string> = {
+  unauthenticated: '请先登录后再查询会员信息',
+  unknown: MEMBER_UNKNOWN_NOTICE,
+  not_enrolled: MEMBER_NOT_ENROLLED_NOTICE,
+  closed: MEMBER_NO_POINTS_NOTICE,
+  unavailable: '会员服务暂时不可用，请稍后再试',
+};
+
+/** 匿名短路不触 provider；上下文缺席/resolve/getAccount 失败 → unavailable + warn 留痕
+ *  （管路故障收口可用性语义，不冒充身份语义）。 */
+export async function resolveMemberStatus(
+  reqCtx: RequestContext | undefined,
+  ctx: ServerContext,
+): Promise<ResolvedMemberStatus> {
+  if (!reqCtx) {
+    // 上下文缺席 = 调用方管路断裂（匿名身份语义经 identity.source 表达，与此无关）
+    ctx.logger?.warn('会员状态解析失败：运行上下文缺席');
+    return { outcome: 'unavailable' };
+  }
+  if (reqCtx.identity?.source === 'anonymous') {
+    // 匿名也 attempt 取 loginUrl（登录引导卡降级深链）：工厂建实例只读部署配置、零网络 IO；
+    // 未配置/无 mallId/registry 缺失 → fail-soft 无深链（消费方退文字）
+    let loginUrl: string | undefined;
+    try {
+      const accountPort = await resolveMemberAccountPort(reqCtx, ctx);
+      loginUrl = accountPort.loginUrl || undefined;
+    } catch {
+      /* fail-soft */
+    }
+    return loginUrl ? { outcome: 'unauthenticated', loginUrl } : { outcome: 'unauthenticated' };
+  }
+  // N1 双槽编排（017）：account 槽承载身份判定 + loginUrl；enrollment 槽仅承载
+  // enrollUrl 素材——缺席/失败不拖累身份判定（缺省 = 未配置恒出卡、无 URL 字段）。
+  let accountPort;
+  let account: MemberAccountSnapshot;
+  try {
+    accountPort = await resolveMemberAccountPort(reqCtx, ctx);
+    account = await accountPort.getAccount(reqCtx.identity.userId);
+  } catch (error) {
+    ctx.logger?.warn(`会员状态解析失败：err=${(error as Error).message}`);
+    return { outcome: 'unavailable' };
+  }
+  let enrollUrl: string | undefined;
+  try {
+    const enrollmentPort = await resolveMemberEnrollmentPort(reqCtx, ctx);
+    enrollUrl = enrollmentPort.enrollUrl || undefined;
+  } catch (error) {
+    // enrollment 槽缺席/失败 → 无深链素材（CTA 卡仍可出，memberGateCardOf 既有设计）；
+    // warn 留痕供诊断（配置类错误不静默），不拖累身份判定。
+    ctx.logger?.warn(`会员入会深链解析失败：err=${(error as Error).message}`);
+  }
+  return {
+    outcome: classifyMemberOutcome(reqCtx.identity, account),
+    account,
+    ...(enrollUrl ? { enrollUrl } : {}),
+    ...(accountPort.loginUrl ? { loginUrl: accountPort.loginUrl } : {}),
+  };
+}

package/src/server/subject-binding.ts

@@ -0,0 +1,19 @@
+/**
+ * SubjectBindingPort 兼容实现（已 deprecated——见 contracts-mall 契约注释）：
+ * 同步签名对任意非空 userId 恒返回平台侧派生引用，不承载会员身份语义。
+ * 会员状态判定与真实外部会员引用请消费 'member.status' 服务 + externalMemberRefOf。
+ * 保留注册仅为版本偏斜期兼容（旧消费方混装）。
+ */
+import type { SubjectBindingPort } from '@tbox.cn/app-contracts-mall';
+import { createHash } from 'node:crypto';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+
+export function createSubjectBinding(ctx: ServerContext): SubjectBindingPort {
+  return {
+    resolveExternalMemberRef(userId: string): string | undefined {
+      void ctx;
+      // 同步签名无法访问异步 Provider，这里只提供稳定派生 ref。
+      return userId ? `member-ref:${createHash('sha256').update(userId).digest('hex').slice(0, 24)}` : undefined;
+    },
+  };
+}