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

package/dist/scope.d.ts

@@ -1,6 +1,6 @@
 /**
  * 商圈 scope（011 B2：TIER1 领域语义唯一真源）：
- * MallScope 类型 + zod 解析 + RequestContext 提取器。
+ * MallScope 类型 + zod 解析 + ContextSlot 槽位 + RequestContext 提取器。
  *
  * 消费方（模块）只依赖本文件解析 attributes，不解析原始形状（011 B4）；
  * TIER0（app-contracts）不出现任何 mall 语义（011 B1）。
@@ -11,8 +11,13 @@ import type { RequestContext } from '@tbox.cn/app-contracts';
 export declare const MALL_SCOPE_KEY = "mall";
 /** 商圈 scope（客户端输入形状——HELLO context.attributes.mall；会话边界键：mallId） */
 export interface MallScope {
-    /** 小程序 appId（定位到具体小程序实例） */
-    miniAppId: string;
+    /**
+     * 小程序 appId（可选项——v4 缺陷修复）：
+     * 客户端发送侧本就条件附加（miniAppId 不知则省略），服务端此前必填造成
+     * mallId-only 会话 N1 死锁（默认注入形态被形状守卫拒绝）。miniAppId 是
+     * 尽力回填的展示/定位值，非会话边界（边界恒 mallId）。
+     */
+    miniAppId?: string;
     /** 商圈 id（会话边界：跨 mall 强制新会话，011 F3） */
     mallId: string;
     /** 可选主体 id（会员体系 subject） */
@@ -23,27 +28,49 @@ export interface MallSessionScope extends MallScope {
     sessionId: string;
 }
 export declare const mallScopeSchema: z.ZodObject<{
-    miniAppId: z.ZodString;
+    miniAppId: z.ZodOptional<z.ZodString>;
     mallId: z.ZodString;
     subjectId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    miniAppId: string;
     mallId: string;
+    miniAppId?: string | undefined;
     subjectId?: string | undefined;
 }, {
-    miniAppId: string;
     mallId: string;
+    miniAppId?: string | undefined;
     subjectId?: string | undefined;
 }>;
-/** 解析失败返回 undefined（不 throw），模块自行降级（011 B2 语义） */
+/**
+ * mall 槽位（上下文统一化 Stage 2）：TIER0 ContextSlot 协议上的 TIER1 定义——
+ * attributes.mall 的结构化读取（zod safeParse，fail-soft）。decide / handler / 工具
+ * 内统一经 mallSlot.read(attributes) 取 scope，替代散落的 as 断言。
+ */
+export declare const mallSlot: import("@tbox.cn/app-contracts").ContextSlot<{
+    mallId: string;
+    miniAppId?: string | undefined;
+    subjectId?: string | undefined;
+}, "mall">;
+/** 解析失败返回 undefined（不 throw），模块自行降级（011 B2 语义；mallSlot 薄包装） */
 export declare function parseMallScope(attributes: Record<string, unknown> | undefined): MallScope | undefined;
 /** 从 RequestContext 提取 MallScope（parseMallScope 包装） */
 export declare function extractMallScope(ctx: RequestContext): MallScope | undefined;
-/** mall 领域运行上下文（attributes 含 mall 的 RequestContext 收窄，模块 handler 入参可用） */
-export type MallRequestContext = RequestContext & {
-    attributes: Record<string, unknown> & {
-        [MALL_SCOPE_KEY]: MallScope;
-    };
-};
-/** 从 MallRequestContext 取 MallScope（调用方已确认 scope 存在） */
-export declare function requireMallScope(ctx: MallRequestContext): MallScope;
+/**
+ * 模块 ports 解析槽位统一 scope 形状（017 槽位原子化：resolveService 入参单一来源）。
+ * 行为钉死：返回 `{ mallId } | {}`（flat，不含 miniAppId）——与四模块 ports 既有行为
+ * 逐字等价；补 miniAppId 会改变厂商加签身份解析器的凭据 scope 匹配路径。
+ */
+export declare function mallScopeOf(reqCtx: {
+    attributes?: Record<string, unknown>;
+}): Record<string, string>;
+/** mall 领域运行上下文（attributes 含 mall 的 RequestContext 收窄）
+ *
+ * @deprecated（上下文统一化 Stage 2）：双断言供养的类型收窄已被 mallSlot.read /
+ * parseMallScope 显式解析取代——调用点直接传 RequestContext，消费侧 fail-soft 解析。
+ * 对外移除已随 0.8.0 落地（0.7.3 additive 波次保留至本波次）。
+ */
+/**
+ * 登录 context 宽松读取 mallId（F2：换码器归 provider 包后的共享读取器）。
+ * 登录 URL 可只带 mallId（不套 parseMallScope 全形状）——登录换码先例，与
+ * MALL_SCOPE_KEY 共置单一真源；provider 包 scoped 谓词与换码体共用本入口。
+ */
+export declare function readLoginMallId(context?: Readonly<Record<string, unknown>>): string | undefined;

package/dist/server/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TIER1 服务端子路径出口（F2 模板中立化后）：
+ * 请求凭证读取助手（request-credentials）+ mall 身份视图（mall-context）+
+ * mall 控制平面投影（mall-control-plane）。
+ * 登录换码器已整迁各 provider 包自注册
+ * （ctx.authExchanges.register，@tbox.cn/app-provider-<vendor>/server）；
+ * 本包不再承载任何厂商实现与装配知识。
+ */
+export * from './request-credentials';
+export * from './mall-context';
+export * from './mall-control-plane';

package/dist/server/index.js

@@ -0,0 +1,92 @@
+import {
+  extractMallScope
+} from "../chunk-KIZD6FZ2.js";
+
+// src/server/request-credentials.ts
+function readString(source, key) {
+  if (source === null || typeof source !== "object") return "";
+  const value = source[key];
+  return typeof value === "string" ? value : "";
+}
+function credentialsToken(ctx) {
+  return readString(ctx.credentials, "token");
+}
+function credentialsMemberId(ctx) {
+  const attributes = ctx.credentials?.attributes;
+  return readString(attributes, "memberId");
+}
+function credentialsVisitortoken(ctx) {
+  const attributes = ctx.credentials?.attributes;
+  return readString(attributes, "visitortoken");
+}
+function credentialsOpenId(ctx) {
+  const attributes = ctx.credentials?.attributes;
+  return readString(attributes, "openid");
+}
+
+// src/server/mall-context.ts
+function mallIdentityView(reqCtx) {
+  const memberId = credentialsMemberId(reqCtx);
+  const openId = credentialsOpenId(reqCtx);
+  const scope = extractMallScope(reqCtx);
+  return {
+    identity: reqCtx.identity,
+    ...scope ? { scope } : {},
+    sessionToken: credentialsToken(reqCtx),
+    ...memberId ? { memberId } : {},
+    ...openId ? { openId } : {}
+  };
+}
+
+// src/server/mall-control-plane.ts
+import { z } from "zod";
+import { normalizeInstances } from "@tbox.cn/app-contracts";
+var mallAttributesSchema = z.strictObject({
+  /** 小程序 appId（mall 级共享——默认商圈拼装 HELLO context.mall.miniAppId 的承载） */
+  miniAppId: z.string().min(1).optional(),
+  /** 客服电话（shopping-guide customer-service-faq 卡 link 拨打条目消费，缺省不渲染） */
+  contactPhone: z.string().min(1).optional(),
+  /** 地理坐标（WGS-84；有值时参与 /api/m/mall-home/nearby-mall 就近推荐，缺省不参与排序） */
+  location: z.object({
+    lat: z.number(),
+    lon: z.number(),
+    /** 展示地址（可选；推荐 Banner 展示用） */
+    address: z.string().optional()
+  }).optional()
+  // 门店维度（stores）显式非目标（D13）——新行业拓扑 = 新 TIER1 投影包，不在本文件扩键
+});
+function parseMallAttributes(inst) {
+  const result = mallAttributesSchema.safeParse(inst.attributes ?? {});
+  if (!result.success) {
+    const detail = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+    throw new Error(
+      `integrations instances[${inst.id}].attributes \u8D4B\u4E49\u5931\u8D25\uFF08\u5141\u8BB8\u952E\uFF1AminiAppId/contactPhone/location\uFF09\u2014\u2014${detail}`
+    );
+  }
+  return { mallId: inst.id, name: inst.name, ...result.data };
+}
+function mergeDeclaredInstances(config, declared) {
+  if (!declared) return config;
+  if (config.instances && config.instances.length > 0) return config;
+  if (config.defaultInstanceId !== void 0) return config;
+  const rootProvider = config.provider;
+  if (!rootProvider) return config;
+  const instances = declared[rootProvider];
+  if (!instances || instances.length === 0) return config;
+  return { ...config, instances: [...instances] };
+}
+function mallControlPlaneOf(config, declared) {
+  const { instances, defaultInstanceId } = normalizeInstances(
+    mergeDeclaredInstances(config, declared)
+  );
+  const malls = instances.map(parseMallAttributes);
+  return { malls, ...defaultInstanceId !== null ? { defaultMallId: defaultInstanceId } : {} };
+}
+export {
+  credentialsMemberId,
+  credentialsOpenId,
+  credentialsToken,
+  credentialsVisitortoken,
+  mallControlPlaneOf,
+  mallIdentityView
+};

package/dist/server/mall-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * mall 身份视图（上下文统一化 Stage 2）：RequestContext → 一屏业务身份字段。
+ *
+ * 收敛「怎么带 mallId / userId / token / memberId / openId」的散装读取——
+ * identity 原样保留（source 四态可判；登录态 = source !== 'anonymous'），
+ * scope 经 mallSlot fail-soft 解析，凭证字段经 request-credentials 单源访问器。
+ */
+import type { Identity, RequestContext } from '@tbox.cn/app-contracts';
+import type { MallScope } from '../scope';
+/** mall 域业务身份视图（模块 handler / 工具 / 卡片动作统一消费形态） */
+export interface MallIdentityView {
+    /** 原样保留（source: local/external/dev/anonymous 四态可判） */
+    identity: Identity;
+    /** mall scope（attributes.mall fail-soft 解析；缺失/非法 → undefined，调用方降级） */
+    scope?: MallScope;
+    /** 登录 token（credentials.token；tokenless / 匿名 → ''——空串语义见 request-credentials） */
+    sessionToken: string;
+    /** 厂商 memberId（credentials.attributes.memberId） */
+    memberId?: string;
+    /** 平台 openId（credentials.attributes.openid——绑定场景；契约唯一通道） */
+    openId?: string;
+}
+/** 由 RequestContext 组装 mall 身份视图（纯函数，无 IO） */
+export declare function mallIdentityView(reqCtx: RequestContext): MallIdentityView;

package/dist/server/mall-control-plane.d.ts

@@ -0,0 +1,10 @@
+import type { IntegrationsConfig, ProviderInstanceDeclarations } from '@tbox.cn/app-contracts';
+import type { MallDeploymentControlPlane } from '../deployment';
+/**
+ * integrations config → mall 控制平面（装配链唯一入口）：
+ * - declared = provider 声明快照（缺省关闭——既有调用方零变化；消费方 = mall-core project()）；
+ * - instances 注册表逐条投影（id→mallId、name、attributes 赋义展开——声明实例过同一
+ *   zod strict 校验，坏键 fail-fast 与显式配置同律）；
+ * - defaultMallId = normalizeInstances 解析（显式 ?? 单实例唯一解；无 → undefined）。
+ */
+export declare function mallControlPlaneOf(config: IntegrationsConfig, declared?: ProviderInstanceDeclarations): MallDeploymentControlPlane;

package/dist/server/request-credentials.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 请求级凭证访问器（F5 单源）：从 RequestContext.credentials 提取用户级凭证，
+ * 供 provider adapter factory 构造请求级薄壳 service（E2 不变式：用户凭证只入
+ * service 请求层，禁止写入被缓存的 transport/authStrategy）。
+ *
+ * 空 token 返回空串而非抛错——不需要 token 的工具可正常构造 service；
+ * 真正需要 token 的方法调用时厂商会拒绝，错误在正确边界产生。
+ */
+import type { RequestContext } from '@tbox.cn/app-contracts';
+/** 登录 token（ctx.credentials.token；厂商 body.Header.Token 注入场景） */
+export declare function credentialsToken(ctx: RequestContext): string;
+/** 厂商 memberId（ctx.credentials.attributes.memberId；openapi 会员域场景） */
+export declare function credentialsMemberId(ctx: RequestContext): string;
+/** 访客令牌（ctx.credentials.attributes.visitortoken；L3 访客层全程头携带） */
+export declare function credentialsVisitortoken(ctx: RequestContext): string;
+/**
+ * 平台 openId（ctx.credentials.attributes.openid；外部身份绑定场景）。
+ * 契约唯一通道：ExternalCredentials.attributes 三元组随 external claim 流动
+ *（identity.ts）——曾误读顶层 credentials.openid（契约无此键，恒 undefined，
+ * 致绑定动作 OpenId 恒空），勿改回顶层读取。
+ */
+export declare function credentialsOpenId(ctx: RequestContext): string;

package/dist/services/customer-service.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 客服承接域 Port 契约（2026-08-31 客服模块拆分：自 shopping-guide AssistanceQueryPort
+ * 切出 FAQ/知识库两方法；人工导购 listHumanGuides 留导购域 AssistanceQueryPort）。
+ * 客服承接 = 本地知识库域（与 provider 远程检索面正交，恒本地装配）。
+ */
+import type { ShoppingQueryContext } from './shopping-guide';
+import type { FaqEntry, KnowledgeEntry } from '../domain/shopping-guide';
+export interface CustomerServiceQueryPort {
+    searchFaq(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly FaqEntry[]>;
+    searchKnowledge(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly KnowledgeEntry[]>;
+}

package/dist/services/mall-info.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 商场基础信息 Port（mall.info 槽服务契约；动态商场信息源）。
+ * 厂商 wire 词汇（如厂商侧 plaza 端点词）不进本层——投影后只余平台词汇。
+ * 结构类型子集接口——消费方（模板装配点/模块）仅依赖契约包。
+ */
+export declare const MALL_INFO_SERVICE = "mall.info";
+/** 商场基础信息（动态商场场景下由 mall.info 槽按 mallId 拉取） */
+export interface MallInfo {
+    /** 商场 id（= scope.mallId；投影键） */
+    mallId: string;
+    /** 商场名（品牌区 mallName 动态真源；与 malls 参考表 name 同语义） */
+    name: string;
+    address?: string;
+    latitude?: number;
+    longitude?: number;
+    /** 城市 id（nearby-mall 动态化预留，本期不消费） */
+    cityId?: string;
+}
+/** mall.info 槽供给端口（provider 包 adapter 实现；模板装配点经 integrations 解析） */
+export interface MallInfoPort {
+    /**
+     * 查询商场信息；未知/失败 → undefined（fail-soft，调用方负责缓存与降级）。
+     * mallId 形状守卫由实现方负责（防 path 注入类字符进上游 URL）。
+     */
+    getMallInfo(mallId: string): Promise<MallInfo | undefined>;
+}
+/** 跨模块 'mall.info-cache' 词汇（与 service-slots.json 同锁）。 */
+export declare const MALL_INFO_CACHE_SERVICE = "mall.info-cache";
+/**
+ * mall.info 缓存 Port（缓存 → single-flight → mall.info 槽的读面）。
+ * module-mall-core register 期注册（闭包 integrations）；消费方 resolveService 直读。
+ * 缓存纪律（TTL/负缓存/LRU/single-flight/形状守卫）由实现方收口。
+ */
+export interface MallInfoCachePort {
+    /** 缓存名读取（同步回退通道；过期/负缓存 → undefined） */
+    cachedMallName(mallId: string): string | undefined;
+    /** 缓存 → single-flight → mall.info 槽拉取；失败/未知 → undefined（fail-soft） */
+    resolveMallInfo(mallId: string): Promise<MallInfo | undefined>;
+}

package/dist/services/member.d.ts

@@ -1,12 +1,21 @@
 import type { Points } from '../domain/points';
 import type { DiscountRule } from '../domain/discount';
+import type { Identity, RequestContext } from '@tbox.cn/app-contracts';
 /**
  * 会员域 Port（011 K2：6 Port 替换旧 MemberQueryPort/MemberSettlementPort，breaking 0.2.0）。
  * 结构类型子集接口——模块完整实现 extends 本接口，消费方仅依赖契约包。
  */
-/** 会员状态（含未入会/关闭） */
-export type MemberState = 'active' | 'not_enrolled' | 'closed';
+export declare const MEMBER_ACCOUNT_SERVICE = "member.account";
+export declare const MEMBER_PROFILE_SERVICE = "member.profile";
+export declare const MEMBER_CARD_SERVICE = "member.card";
+export declare const MEMBER_BENEFITS_SERVICE = "member.benefits";
+export declare const MEMBER_ENROLLMENT_SERVICE = "member.enrollment";
+/** 应用登录状态与会员状态相互独立；登录成功不代表已经入会。 */
+export type MemberAuthState = 'authenticated' | 'unauthenticated';
+/** unknown 表示当前身份无法向会员 Provider 确认状态；其余状态仅描述会员资格。 */
+export type MemberState = 'unknown' | 'active' | 'not_enrolled' | 'closed';
 export interface MemberAccountSnapshot {
+    readonly authState: MemberAuthState;
     readonly state: MemberState;
     readonly memberRef?: string;
     readonly primaryMallCardNo?: string;
@@ -31,12 +40,49 @@ export interface MemberProfileSnapshot {
 export interface MemberProfilePort {
     getProfile(userId: string): Promise<MemberProfileSnapshot>;
 }
+/** 通用卡面视觉变体；具体等级到变体的映射由 provider 负责。 */
+export type MemberCardVisualVariant = 'blue' | 'silver' | 'gold' | 'black';
+export interface MemberCardPresentationSnapshot {
+    readonly variant: MemberCardVisualVariant;
+    /** 背景资源是否已包含卡名、积分标签等静态文字。 */
+    readonly labelsEmbedded?: boolean;
+}
+/** 卡面消费进度；金额统一为分，提示文案由 provider 按厂商规则生成。 */
+export interface MemberCardProgressSnapshot {
+    readonly daySpentCents: number;
+    readonly yearSpentCents: number;
+    readonly percent: number;
+    readonly message: string;
+}
+/** 卡片首屏权益摘要；规则正文与跳链不在摘要契约中直接暴露。 */
+export interface MemberBenefitPreview {
+    readonly benefitRef: string;
+    readonly name: string;
+    readonly iconUrl?: string;
+    /** 厂商权益摘要标签，例如源码按 parkingFree 拼出的“可免 X 小时”。 */
+    readonly description?: string;
+    /** 厂商原生权益动作；客户端通过支付宝 startapp 深链交给宿主跳转。 */
+    readonly action?: {
+        readonly kind: 'miniapp' | 'dialog' | 'toast';
+        readonly url?: string;
+        readonly title?: string;
+        readonly text?: string;
+    };
+}
 export interface MemberCardSnapshot {
     readonly cardRef: string;
     readonly cardDisplay: string;
     readonly status: 'active' | 'inactive' | 'frozen' | 'expired' | 'unknown';
     readonly levelName?: string;
     readonly cardImageUrl?: string;
+    /** 积分规则长图；客户端以只读图片弹层展示，不作为通用跳链执行。 */
+    readonly pointsRuleImageUrl?: string;
+    readonly pointsRuleContent?: string;
+    /** C 端原生“我的积分”明细页深链。 */
+    readonly pointsUrl?: string;
+    readonly presentation?: MemberCardPresentationSnapshot;
+    readonly progress?: MemberCardProgressSnapshot;
+    readonly benefits?: ReadonlyArray<MemberBenefitPreview>;
     readonly observedAt: string;
 }
 export interface MemberCardPort {
@@ -74,38 +120,149 @@ export interface PointUsageRecord {
     readonly usedAt?: string;
     readonly description?: string;
 }
-export interface MemberCouponSnapshot {
-    readonly couponRef: string;
-    readonly title: string;
-    readonly type: 'amount' | 'discount' | 'gift' | 'parking' | 'unknown';
-    readonly status: 'effective' | 'used' | 'expired' | 'invalid' | 'unknown';
-    readonly description?: string;
-    readonly benefitText?: string;
-    readonly thresholdText?: string;
+/**
+ * 会员服务解析工厂（上下文统一化 Stage 2）：跨模块 'member.service' 注册面。
+ * member 模块 register 期注册 `(reqCtx) => resolveMemberBenefitsPort(reqCtx, ctx)`
+ * （017 槽位原子化：本面 = benefits 单槽契约，benefits 方法族）；
+ * 跨模块消费方经 ctx.resolveService<MemberBenefitsFactory>('member.service')
+ * 结构解析后 `await factory(reqCtx)`——替代旧 'member' 全局门面（ctx.auth 并发缺陷）。
+ * 身份/会员资格判定请走 'member.status' 注册面（outcome + account），勿经本面取 account 域数据。
+ */
+export type MemberBenefitsFactory = (reqCtx: RequestContext) => Promise<MemberBenefitsPort>;
+/** 入会身份来源（F2：授权 profile 可信度高于手填） */
+export type MemberEnrollmentIdentity = 'alipay_authorized' | 'enrollment_submission';
+export interface MemberEnrollmentInput {
+    readonly userId: string;
+    readonly identity: MemberEnrollmentIdentity;
+    /** 表单字段（mobile 等；授权模式下 mobile 强制以授权 profile 为准） */
+    readonly fieldValues: Readonly<Record<string, string>>;
+    /** 已同意的 consent id 集合（模块侧校验必勾后传入） */
+    readonly acceptedConsentIds: readonly string[];
+    /** 幂等键（模块生成：sha256(userId\0mallId\0formVersion)） */
+    readonly idempotencyKey: string;
+    readonly formVersion?: string;
 }
-export interface MemberCouponPort {
-    listCoupons(userId: string, page: number, pageSize: number): Promise<{
-        items: ReadonlyArray<MemberCouponSnapshot>;
-        total: number;
-    }>;
-    getCoupon(userId: string, couponRef: string): Promise<MemberCouponSnapshot | null>;
+export type MemberEnrollmentResult = {
+    readonly status: 'active';
+    readonly memberRef: string;
 }
+/** 厂商异步确认（pending 卡 + 显式刷新收口，R4） */
+ | {
+    readonly status: 'pending_confirmation';
+    readonly attemptRef: string;
+} | {
+    readonly status: 'rejected';
+    readonly reason?: string;
+};
+export type MemberEnrollmentStatus = 'pending_confirmation' | 'confirmation_timeout' | 'active' | 'failed';
 export interface MemberEnrollmentPort {
-    /** 入会（授权回调后调用；幂等：已入会返回成功） */
-    enroll(input: {
-        userId: string;
-        name?: string;
-        phone?: string;
-    }): Promise<{
-        success: boolean;
+    /** 入会（幂等：同 idempotencyKey 重入返回首果） */
+    enroll(input: MemberEnrollmentInput): Promise<MemberEnrollmentResult>;
+    /** 入会状态查询（attemptRef 归属校验由模块完成） */
+    getEnrollmentStatus(userId: string, attemptRef: string): Promise<{
+        status: MemberEnrollmentStatus;
         memberRef?: string;
-        error?: string;
-    }>;
-    /** 授权回调补签（alipay-user-profile 授权结果 → 会员资料落库） */
-    completeAuthorization(input: {
-        userId: string;
-        scopes: readonly string[];
-    }): Promise<{
-        success: boolean;
+        reason?: string;
     }>;
+    /**
+     * 入会表单定义（厂商端点拉取，如厂商 enrollmentConfig 端点）；无表单端点厂商可缺省——
+     * 调用方 typeof 守卫降级（calculateBestDeal? 同款先例）。017 R13 自 module-member
+     * fat 接口收编。
+     */
+    getEnrollmentFormDefinition?(userId: string): Promise<MemberEnrollmentFormDefinition>;
+}
+/**
+ * 解析平台 userId → 厂商会员外部引用（externalMemberRef）。
+ * member 模块注册实现（ctx.services.register('member.subject-binding', ...)）。
+ * @deprecated 同步派生引用不承载会员身份语义（对任意 userId 恒返回派生值）；
+ * 会员状态判定与真实外部会员引用请改用 'member.status' 服务（MemberStatusFactory）
+ * 与 externalMemberRefOf。保留仅为版本偏斜期兼容。
+ */
+export interface SubjectBindingPort {
+    resolveExternalMemberRef(userId: string): string | undefined;
+}
+export interface MemberEnrollmentFormFieldDefinition {
+    readonly fieldId: string;
+    readonly label: string;
+    readonly type: 'text' | 'tel' | 'select' | 'date';
+    readonly required: boolean;
+    readonly placeholder?: string;
+    readonly options?: readonly string[];
+}
+export interface MemberEnrollmentConsentDefinition {
+    readonly consentId: string;
+    readonly version: string;
+    readonly title: string;
+    readonly required: boolean;
+}
+export interface MemberEnrollmentFormDefinition {
+    readonly formVersion: string;
+    readonly fields: readonly MemberEnrollmentFormFieldDefinition[];
+    readonly consents: readonly MemberEnrollmentConsentDefinition[];
+    readonly authorizationStatus: 'required' | 'unavailable';
+}
+/** 折叠结果：'unauthenticated'（平台匿名短路或凭证轴未认证）或原始会员资格态。 */
+export type MemberOutcome = 'unauthenticated' | MemberState;
+/**
+ * 双轴折叠纯函数（无 IO，唯一真源）：identity 轴（平台登录态）优先短路；
+ * account 轴（凭证态）独立折叠——凭证轴语义由各 provider 自定义，
+ * tokenless 的合法登录可为 unauthenticated。
+ */
+export declare function classifyMemberOutcome(identity: Pick<Identity, 'source'> | null | undefined, account: MemberAccountSnapshot | null | undefined): MemberOutcome;
+/**
+ * 厂商侧会员标识：真实卡号优先，opaque 引用兜底。
+ * 兜底引用仅对不校验真实卡号的 provider 安全——需要真实卡号的厂商接口
+ * 必须由 provider 提供 primaryMallCardNo。
+ */
+export declare function externalMemberRefOf(account: MemberAccountSnapshot): string | undefined;
+/** 跨模块会员状态解析结果（窄读面；实现方注册产物可为超集）。 */
+export interface MemberStatusResolution {
+    readonly outcome: MemberOutcome | 'unavailable';
+    readonly account?: MemberAccountSnapshot;
+    /** 入会引导深链（authenticated 未入会态；未配置缺省） */
+    readonly enrollUrl?: string;
+    /** 登录引导深链（unauthenticated 态；未配置缺省） */
+    readonly loginUrl?: string;
+}
+/** 跨模块 'member.status' 解析工厂（与 MemberBenefitsFactory 并列的注册面契约）。 */
+export type MemberStatusFactory = (reqCtx: RequestContext) => Promise<MemberStatusResolution>;
+/** 门禁卡描述子（形状 = SDK ToolCardSpec { cardType, data, note }，出卡管线兼容）。 */
+export interface MemberGateCard {
+    readonly cardType: 'member-enrollment-cta' | 'member-login-cta';
+    readonly data: Record<string, unknown>;
+    readonly note: string;
+}
+/**
+ * 纯卡映射：outcome → 门禁卡描述子；硬门禁态恒出卡，深链为**可选透传素材**（未配置
+ * 时卡无 URL 字段，客户端禁用按钮/壳能力接管）；软放行态 / userId 空 → undefined，
+ * 调用方退纯文字引导（notice）。
+ * 卡 schema 真源：memberEnrollmentCtaCardDataSchema / memberLoginCtaCardDataSchema（本包 member/cards.ts）。
+ */
+export declare function memberGateCardOf(userId: string, status: Pick<MemberStatusResolution, 'outcome' | 'enrollUrl' | 'loginUrl'>): MemberGateCard | undefined;
+/** resolveMemberGate 返回的拦截块（undefined = 放行）。 */
+export interface MemberGateBlock {
+    readonly card?: MemberGateCard;
+    readonly notice: string;
+}
+/**
+ * 门禁编排单源：工厂缺席 / 调用抛错 → fail-open（undefined 放行）；
+ * active / unknown / unavailable → 软放行（读路径软语义——不误伤瞬时故障的会员）；
+ * 硬门禁（unauthenticated/not_enrolled/closed）→ { card?（未配深链缺省）, notice }。
+ * 实现方（member.status 工厂）应自收口异常；本函数对抛错实现兜底为软放行（横切面鲁棒性）。
+ */
+export declare function resolveMemberGate(factory: MemberStatusFactory | undefined, reqCtx: RequestContext): Promise<MemberGateBlock | undefined>;
+/** 跨模块 'member.snapshot' 词汇（与 service-slots.json 同锁）。 */
+export declare const MEMBER_SNAPSHOT_SERVICE = "member.snapshot";
+/**
+ * 会员快览 Port（linked-panel 消费面：账户/授权三态 + 积分 + 入会引导）。
+ * member 模块 register 期注册工厂（'member.service' 工厂先例）；消费方
+ * resolveService 后 await factory(reqCtx) 取 Port——enrollUrl 随请求态解析。
+ */
+export interface MemberSnapshotPort {
+    getAccount(userId: string): Promise<MemberAccountSnapshot>;
+    queryPoints(userId: string): Promise<Points>;
+    /** 入会引导深链（未入会态引导；enrollment 槽缺席/失败时缺省——fail-soft 不拖垮主面） */
+    readonly enrollUrl?: string;
 }
+/** 跨模块 'member.snapshot' 解析工厂（register 期注册，运行期调用）。 */
+export type MemberSnapshotFactory = (reqCtx: RequestContext) => Promise<MemberSnapshotPort>;