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

package/src/promotion/cards.ts

@@ -0,0 +1,290 @@
+/**
+ * 营销域卡片数据契约。
+ * 传输层维持 9 个稳定 CardType；presentation 显式保留 legacy marketing 的 19 个业务展示语义。
+ */
+import { z } from 'zod';
+import { actionDraftSchema } from '../shared/cards';
+
+/** 券/活动封面（厂商 CDN，可缺省） */
+const imageUrlSchema = z.string().max(2048).optional();
+const freeCouponClaimModeSchema = z.enum(['DIRECT', 'REDIRECT']);
+
+/** Offer 摘要（列表条目） */
+const offerSummarySchema = z.object({
+  offerRef: z.string().min(1),
+  title: z.string().min(1),
+  subtitle: z.string().optional(),
+  offerType: z.enum(['COUPON', 'BUNDLE', 'PROMOTION', 'ACTIVITY', 'GROUPON']),
+  /** 主 facet 一句话（如「满 100 减 20」） */
+  benefitText: z.string().optional(),
+  /** 使用门槛（如「满 300 元可用」） */
+  thresholdText: z.string().optional(),
+  /**
+   * 券的**售价**展示，与 benefitText 是两回事——后者说优惠内容，这里说买这张券要花多少。
+   * 免费券给「免费」，付费券给「¥28.8」。文案由 provider 直接给：各厂商币种、小数位与
+   * 「免费/0 元」措辞不一，客户端不做数值运算也不反解金额。
+   */
+  priceText: z.string().optional(),
+  /** 划线原价（如「¥38.8」）。与 priceText 成对出现才有意义，单独给不渲染。 */
+  originalPriceText: z.string().optional(),
+  /** 折扣角标（如「7.5折」）。同样是 provider 直出文案，不由前端拿两个价格算。 */
+  discountLabel: z.string().optional(),
+  /**
+   * 领取按钮文案：免费券「领取」、付费券「抢购」。由 provider 给而非前端按 priceText
+   * 猜——「免费」的写法各家不同，猜错就把付费券写成领取。缺省回落「领取」。
+   */
+  claimActionLabel: z.string().optional(),
+  purchaseUrl: z.string().max(2048).optional(),
+  freeCouponClaimMode: freeCouponClaimModeSchema.optional(),
+  /**
+   * 下面三条供**列表内的详情浮层**渲染——浮层就地展开，没有二次请求可拉，
+   * 需要的信息必须随列表一起下发。厂商不给就不渲染对应区块。
+   */
+  stockText: z.string().optional(),
+  usageNoticeText: z.string().optional(),
+  guaranteeText: z.string().optional(),
+  usageSceneText: z.string().optional(),
+  usageTimeText: z.string().optional(),
+  claimTimeText: z.string().optional(),
+  usageRuleText: z.string().optional(),
+  /** 可领取（availability.status === 'AVAILABLE'） */
+  claimable: z.boolean(),
+  availabilityStatus: z
+    .enum(['AVAILABLE', 'UNAVAILABLE', 'REQUIRES_ACTION', 'UNKNOWN'])
+    .optional(),
+  validityText: z.string().optional(),
+  imageUrl: imageUrlSchema,
+  /** 0.3.2 D4：条目动作（send：查看详情） */
+  itemActions: z.array(actionDraftSchema).optional(),
+  tags: z.array(z.string()),
+});
+
+/** promotion-offer-list：搜索/可领/推荐 三态列表 */
+export const promotionOfferListCardDataSchema = z.object({
+  presentation: z.enum(['offer', 'promotion', 'coupon', 'recommendation']).optional(),
+  mode: z.enum(['search', 'claimable', 'recommend']),
+  /** 客户端默认展示 4 条；传入正整数可覆盖该上限。 */
+  maxItems: z.number().int().positive().optional(),
+  summary: z.string().optional(),
+  items: z.array(offerSummarySchema),
+  noResultsReason: z.string().optional(),
+  nextCursor: z.string().optional(),
+});
+export type PromotionOfferListCardData = z.infer<typeof promotionOfferListCardDataSchema>;
+
+/** promotion-offer-detail：详情 + 领取/券码动作 */
+export const promotionOfferDetailCardDataSchema = z.object({
+  presentation: z
+    .enum(['offer', 'promotion', 'promotion-guide', 'coupon', 'package'])
+    .optional(),
+  offerRef: z.string().min(1),
+  title: z.string().min(1),
+  offerType: z.enum(['COUPON', 'BUNDLE', 'PROMOTION', 'ACTIVITY', 'GROUPON']),
+  subtitle: z.string().optional(),
+  description: z.string().optional(),
+  imageUrl: imageUrlSchema,
+  benefitText: z.string().optional(),
+  thresholdText: z.string().optional(),
+  validityText: z.string().optional(),
+  /** 售价三件套，语义同 offerSummary（provider 直出文案，前端不做运算） */
+  priceText: z.string().optional(),
+  originalPriceText: z.string().optional(),
+  discountLabel: z.string().optional(),
+  claimActionLabel: z.string().optional(),
+  purchaseUrl: z.string().max(2048).optional(),
+  /** 剩余库存文案（如「剩余：29」）；厂商不给就不展示，别拿 0 当「售罄」用 */
+  stockText: z.string().optional(),
+  usageNoticeText: z.string().optional(),
+  /** 核销场景（如「万铺小二核销」）——告诉用户这张券在哪、怎么用掉 */
+  usageSceneText: z.string().optional(),
+  usageTimeText: z.string().optional(),
+  claimTimeText: z.string().optional(),
+  usageRuleText: z.string().optional(),
+  guaranteeText: z.string().optional(),
+  /** 使用规则/参与步骤 */
+  rules: z.array(z.string()),
+  participationMode: z
+    .enum([
+      'AUTOMATIC_DISCOUNT',
+      'CLAIM_THEN_PURCHASE',
+      'REGISTER_THEN_ATTEND',
+      'GROUP_PURCHASE',
+      'UNKNOWN',
+    ])
+    .optional(),
+  steps: z
+    .array(z.object({ title: z.string(), description: z.string().optional() }))
+    .optional(),
+  requirements: z.array(z.string()).optional(),
+  notice: z.string().optional(),
+  /** 厂商可提供时展示适用门店；可选以兼容历史卡数据。 */
+  stores: z.array(z.object({
+    storeId: z.string().min(1),
+    storeName: z.string().min(1),
+    businessName: z.string().optional(),
+    address: z.string().optional(),
+    floor: z.string().optional(),
+  })).optional(),
+  bundleItems: z
+    .array(z.object({ name: z.string(), quantity: z.number().int().positive() }))
+    .optional(),
+  /** 领取动作是否可用（未登录会员/不可用 → false + unavailableReason） */
+  claimable: z.boolean(),
+  unavailableReason: z.string().optional(),
+  caveats: z.array(z.string()),
+});
+export type PromotionOfferDetailCardData = z.infer<typeof promotionOfferDetailCardDataSchema>;
+
+/** promotion-entitlement-list：我的券 */
+export const promotionEntitlementListCardDataSchema = z.object({
+  mallId: z.string().optional(),
+  miniAppId: z.string().optional(),
+  /** 客户端默认展示 4 条；传入正整数可覆盖该上限。 */
+  maxItems: z.number().int().positive().optional(),
+  items: z.array(
+    z.object({
+      entitlementRef: z.string().min(1),
+      title: z.string().min(1),
+      imageUrl: imageUrlSchema,
+      entitlementType: z.enum(['COUPON', 'BUNDLE', 'PROMOTION', 'ACTIVITY', 'GROUPON']),
+      status: z.enum(['EFFECTIVE', 'USED', 'EXPIRED', 'INVALID', 'UNKNOWN']),
+      codeMasked: z.string().optional(),
+      code: z.string().optional(),
+      qrCodeEnabled: z.boolean().optional(),
+      benefitText: z.string().optional(),
+      thresholdText: z.string().optional(),
+      usageNotice: z.string().optional(),
+      guaranteeText: z.string().optional(),
+      usageSceneText: z.string().optional(),
+      usageTimeText: z.string().optional(),
+      claimTimeText: z.string().optional(),
+      usageRuleText: z.string().optional(),
+      validityText: z.string().optional(),
+      validUntilText: z.string().optional(),
+      /** 0.3.2 D4：条目动作（send：查看详情） */
+      itemActions: z.array(actionDraftSchema).optional(),
+  stores: z.array(z.object({
+    storeId: z.string(),
+    storeName: z.string(),
+    businessName: z.string().optional(),
+    imageUrl: imageUrlSchema,
+    address: z.string().optional(),
+    floor: z.string().optional(),
+    latitude: z.number().optional(),
+    longitude: z.number().optional(),
+  })).optional(),
+    }),
+  ),
+  noResultsReason: z.string().optional(),
+  nextCursor: z.string().optional(),
+});
+export type PromotionEntitlementListCardData = z.infer<typeof promotionEntitlementListCardDataSchema>;
+
+/** promotion-activity-category-list：活动分类入口。 */
+export const promotionActivityCategoryListCardDataSchema = z.object({
+  items: z.array(
+    z.object({
+      categoryId: z.string().min(1),
+      name: z.string().min(1),
+      parentId: z.string().optional(),
+      itemActions: z.array(actionDraftSchema).optional(),
+    }),
+  ),
+  noResultsReason: z.string().optional(),
+});
+export type PromotionActivityCategoryListCardData = z.infer<
+  typeof promotionActivityCategoryListCardDataSchema
+>;
+
+/** promotion-best-deal：确定性测算或厂商不支持时的候选说明。 */
+export const promotionBestDealCardDataSchema = z.object({
+  authoritative: z.boolean(),
+  originalAmountCents: z.number().int().min(0),
+  savingsCents: z.number().int().min(0).optional(),
+  expectedPayCents: z.number().int().min(0).optional(),
+  appliedOfferRefs: z.array(z.string()),
+  candidates: z.array(offerSummarySchema).optional(),
+  message: z.string().optional(),
+});
+export type PromotionBestDealCardData = z.infer<typeof promotionBestDealCardDataSchema>;
+
+/** promotion-activity-list */
+export const promotionActivityListCardDataSchema = z.object({
+  items: z.array(
+    z.object({
+      activityRef: z.string().min(1),
+      title: z.string().min(1),
+      subtitle: z.string().optional(),
+      coverUrl: imageUrlSchema,
+      registrationRequired: z.boolean(),
+      jumpOnly: z.boolean().optional(),
+      jumpLabel: z.string().min(1).optional(),
+      remainingQuota: z.number().int().min(0).optional(),
+      periodText: z.string().optional(),
+      categoryName: z.string().optional(),
+      availabilityStatus: z
+        .enum(['AVAILABLE', 'FULL', 'ENDED', 'UPCOMING', 'UNKNOWN'])
+        .optional(),
+      itemActions: z.array(actionDraftSchema).optional(),
+    }),
+  ),
+  noResultsReason: z.string().optional(),
+  nextCursor: z.string().optional(),
+});
+export type PromotionActivityListCardData = z.infer<typeof promotionActivityListCardDataSchema>;
+
+/** promotion-activity-detail：详情 + 场次 + 指南 */
+export const promotionActivityDetailCardDataSchema = z.object({
+  presentation: z.enum(['detail', 'schedule', 'guide']).optional(),
+  activityRef: z.string().min(1),
+  title: z.string().min(1),
+  subtitle: z.string().optional(),
+  categoryName: z.string().optional(),
+  description: z.string().optional(),
+  coverUrl: imageUrlSchema,
+  periodText: z.string().optional(),
+  location: z.string().optional(),
+  registrationRequired: z.boolean(),
+  jumpOnly: z.boolean().optional(),
+  jumpLabel: z.string().min(1).optional(),
+  /** 需报名时直达厂商支付宝小程序活动详情；由客户端 openLink 本地处理。 */
+  registrationUrl: z.string().max(2048).optional(),
+  remainingQuota: z.number().int().min(0).optional(),
+  sessions: z.array(
+    z.object({
+      sessionRef: z.string(),
+      title: z.string(),
+      startText: z.string(),
+      endText: z.string().optional(),
+      location: z.string().optional(),
+      remainingQuota: z.number().int().min(0).optional(),
+      status: z.enum(['OPEN', 'FULL', 'CLOSED', 'UNKNOWN']),
+    }),
+  ),
+  guideSteps: z.array(z.string()),
+  guideItems: z
+    .array(z.object({ title: z.string(), description: z.string().optional() }))
+    .optional(),
+  conditions: z.array(z.string()),
+  notice: z.string().optional(),
+});
+export type PromotionActivityDetailCardData = z.infer<typeof promotionActivityDetailCardDataSchema>;
+
+/** promotion-bumpin-activity card schema 已迁移至 alipay-activity/cards.ts，此处 re-export 保持向后兼容 */
+export {
+  promotionBumpInActivityCardDataSchema,
+  type PromotionBumpInActivityCardData,
+} from '../alipay-activity/cards';
+
+/** 10 个稳定传输卡型；其 presentation 变体覆盖 19 个 legacy 业务展示语义。 */
+export const promotionCardDataSchemas = {
+  'promotion-offer-list': promotionOfferListCardDataSchema,
+  'promotion-offer-detail': promotionOfferDetailCardDataSchema,
+  'promotion-entitlement-list': promotionEntitlementListCardDataSchema,
+  'promotion-activity-category-list': promotionActivityCategoryListCardDataSchema,
+  'promotion-best-deal': promotionBestDealCardDataSchema,
+  'promotion-activity-list': promotionActivityListCardDataSchema,
+  'promotion-activity-detail': promotionActivityDetailCardDataSchema,
+} as const;
+
+export type PromotionCardType = keyof typeof promotionCardDataSchemas;

package/src/query-context.ts

@@ -0,0 +1,81 @@
+/**
+ * mall 查询上下文组装单源（读/写/消费三层中的消费层 + query 写入口）。
+ *
+ * 原子 + 组合子分层：mallScopeOrEmpty / mallSubjectIdOf 为原子，toMallQueryContext 为
+ * 宽松组合子；strict 语义（member 域 throw / shopping-guide toShoppingQueryContext）
+ * 留在模块内，不在本文件。
+ *
+ * plazaId 边界（不可变约束）：plazaId 归一是客户端 mall-scope-url 单点职责，
+ * 本文件只认 mallId 契约键，不接受别名（四道防护见 docs/plans/mall-scope-unification）。
+ */
+import type { RequestContext } from '@tbox.cn/app-contracts';
+import { MALL_SCOPE_KEY, extractMallScope } from './scope';
+import type { MallScope } from './scope';
+
+/** C 端查询上下文公共形状（三域 *QueryContext extends；未来新域直接继承） */
+export interface MallQueryContext {
+  readonly scope: MallScope;
+  readonly subjectId?: string;
+  readonly requestContext: RequestContext;
+}
+
+/**
+ * 空 mall scope 兜底（demo/单实例部署：scope 缺席时以空 mallId 命中 mock 单实例）。
+ * 函数化而非共享常量——miss 返回新对象，免疫「调用方原地改写」共享引用事故。
+ */
+export function mallScopeOrEmpty(reqCtx: RequestContext): MallScope {
+  return extractMallScope(reqCtx) ?? { miniAppId: '', mallId: '' };
+}
+
+/**
+ * C 端主体归一（登录态 = source !== 'anonymous'，与 mall-context.ts 定义同源）。
+ * 五模块 subjectId 判式三态分裂（!=='anonymous' / 无条件 / local‖external）的归一点。
+ */
+export function mallSubjectIdOf(reqCtx: RequestContext): string | undefined {
+  return reqCtx.identity && reqCtx.identity.source !== 'anonymous'
+    ? reqCtx.identity.userId
+    : undefined;
+}
+
+/**
+ * GET 路由 mall scope 供给：query 部分形状 → attributes 注入（唯一写入口）。
+ *
+ * - mallId 非空 string（trim）才注入，覆盖既有 attributes.mall（与既有 spread 覆盖语义一致）；
+ * - miniAppId = query 透传优先 → opts.miniAppId 兜底（模块路由 = 卡片 data 链回传；
+ *   模板路由 = 配置面 root config/malls 表——两种真实并存的真源策略）；双缺 → 注入
+ *   mallId-only（v4：miniAppId 可选——URL 明确携带 mallId 却落全局会话是与恒动态
+ *   语义矛盾的倒退；parseMallScope 对 mallId-only 恒成功，旧「注入了却 parse 不了」
+ *   中间态不复存在）；
+ * - 只认 mallId 契约键；plazaId 归一是客户端 mall-scope-url 单点职责，本入口不接受别名；
+ * - 安全模型同登录面：无入口白名单，registry per-service scope 绑定兜底
+ *   （伪造 mallId → resolveService 预期缺席 → 各域兜底/fail-loud）；
+ * - query 结构型参数 Readonly<Record<string, unknown>> 不耦合 express（ParsedQs 结构兼容）。
+ */
+export function withMallScopeFromQuery(
+  reqCtx: RequestContext,
+  query: Readonly<Record<string, unknown>>,
+  opts?: { miniAppId?: string },
+): RequestContext {
+  const text = (value: unknown): string | undefined =>
+    typeof value === 'string' && value.trim() ? value.trim() : undefined;
+  const mallId = text(query['mallId']);
+  if (!mallId) return reqCtx;
+  const miniAppId = text(query['miniAppId']) ?? text(opts?.miniAppId);
+  return {
+    ...reqCtx,
+    attributes: {
+      ...reqCtx.attributes,
+      [MALL_SCOPE_KEY]: miniAppId ? { mallId, miniAppId } : { mallId },
+    },
+  };
+}
+
+/** 宽松组合子：空兜底 + 主体归一一键组装（零参数——无覆盖口） */
+export function toMallQueryContext(reqCtx: RequestContext): MallQueryContext {
+  const subjectId = mallSubjectIdOf(reqCtx);
+  return {
+    scope: mallScopeOrEmpty(reqCtx),
+    ...(subjectId ? { subjectId } : {}),
+    requestContext: reqCtx,
+  };
+}

package/src/runtime.ts

@@ -0,0 +1,43 @@
+/**
+ * @tbox.cn/app-contracts-mall runtime 入口（011 A5：types-only → types + runtime）。
+ * 本文件为唯一运行时 JS（经 tsup/esbuild 出 dist/runtime.js）；
+ * 类型面仍经 tsc emitDeclarationOnly 出 dist/*.d.ts。
+ * 依赖方向：contracts-mall → contracts（TIER0）；SDK 不 import 本包（011 B3）。
+ */
+export { MALL_SCOPE_KEY, mallScopeSchema, mallSlot, parseMallScope, extractMallScope, mallScopeOf, readLoginMallId } from './scope';
+export { mallScopeOrEmpty, mallSubjectIdOf, withMallScopeFromQuery, toMallQueryContext } from './query-context';
+export { createMallRuntimeAssembly, createMallContextValidator, withMallName, AUTH_LOGIN_SERVICE } from './assembly';
+export { readMallIdFromUrl, readMiniAppIdFromUrl } from './mall-scope-url';
+export {
+  MEMBER_ACCOUNT_SERVICE,
+  MEMBER_PROFILE_SERVICE,
+  MEMBER_CARD_SERVICE,
+  MEMBER_BENEFITS_SERVICE,
+  MEMBER_ENROLLMENT_SERVICE,
+  MEMBER_SNAPSHOT_SERVICE,
+  classifyMemberOutcome,
+  externalMemberRefOf,
+  memberGateCardOf,
+  resolveMemberGate,
+} from './services/member';
+export { PARKING_QUERY_SERVICE, PARKING_PAYMENT_SERVICE, PARKING_VEHICLE_SERVICE, PARKING_SNAPSHOT_SERVICE } from './services/parking';
+export {
+  PROMOTION_OFFERS_SERVICE,
+  PROMOTION_ENTITLEMENTS_SERVICE,
+  PROMOTION_ACTIVITIES_SERVICE,
+  PROMOTION_ACQUISITION_SERVICE,
+  PROMOTION_ACTIVITY_ROUTING_POLICY,
+} from './services/promotion';
+export {
+  SHOPPING_CATALOG_SERVICE,
+  SHOPPING_SHOPS_SERVICE,
+  SHOPPING_CATEGORIES_SERVICE,
+  SHOPPING_DIRECTORY_SERVICE,
+} from './services/shopping-guide';
+export { MALL_INFO_SERVICE, MALL_INFO_CACHE_SERVICE } from './services/mall-info';
+export { mallLocationSchema, parseMallLocation, mallUserRefSchema, parseMallUserRef } from './guard';
+export * from './shopping-guide/cards';
+export * from './member/cards';
+export * from './promotion/cards';
+export * from './parking/cards';
+export * from './shared/cards';

package/src/scope.ts

@@ -0,0 +1,92 @@
+/**
+ * 商圈 scope（011 B2：TIER1 领域语义唯一真源）：
+ * MallScope 类型 + zod 解析 + ContextSlot 槽位 + RequestContext 提取器。
+ *
+ * 消费方（模块）只依赖本文件解析 attributes，不解析原始形状（011 B4）；
+ * TIER0（app-contracts）不出现任何 mall 语义（011 B1）。
+ */
+import { z } from 'zod';
+import { defineContextSlot } from '@tbox.cn/app-contracts';
+import type { RequestContext } from '@tbox.cn/app-contracts';
+
+/** attributes 键名（TIER0 槽位内 TIER1 自定键，单一来源） */
+export const MALL_SCOPE_KEY = 'mall';
+
+/** 商圈 scope（客户端输入形状——HELLO context.attributes.mall；会话边界键：mallId） */
+export interface MallScope {
+  /**
+   * 小程序 appId（可选项——v4 缺陷修复）：
+   * 客户端发送侧本就条件附加（miniAppId 不知则省略），服务端此前必填造成
+   * mallId-only 会话 N1 死锁（默认注入形态被形状守卫拒绝）。miniAppId 是
+   * 尽力回填的展示/定位值，非会话边界（边界恒 mallId）。
+   */
+  miniAppId?: string;
+  /** 商圈 id（会话边界：跨 mall 强制新会话，011 F3） */
+  mallId: string;
+  /** 可选主体 id（会员体系 subject） */
+  subjectId?: string;
+}
+
+/** 011 S7：服务端回显形状（= MallScope + 服务端生成的 sessionId；与输入形状分离） */
+export interface MallSessionScope extends MallScope {
+  sessionId: string;
+}
+
+export const mallScopeSchema = z.object({
+  miniAppId: z.string().min(1).optional(),
+  mallId: z.string().min(1),
+  subjectId: z.string().optional(),
+});
+
+/**
+ * mall 槽位（上下文统一化 Stage 2）：TIER0 ContextSlot 协议上的 TIER1 定义——
+ * attributes.mall 的结构化读取（zod safeParse，fail-soft）。decide / handler / 工具
+ * 内统一经 mallSlot.read(attributes) 取 scope，替代散落的 as 断言。
+ */
+export const mallSlot = defineContextSlot({
+  key: MALL_SCOPE_KEY,
+  parse: (raw) => {
+    if (!raw || typeof raw !== 'object') return undefined;
+    const result = mallScopeSchema.safeParse(raw);
+    return result.success ? result.data : undefined;
+  },
+});
+
+/** 解析失败返回 undefined（不 throw），模块自行降级（011 B2 语义；mallSlot 薄包装） */
+export function parseMallScope(attributes: Record<string, unknown> | undefined): MallScope | undefined {
+  return mallSlot.read(attributes);
+}
+
+/** 从 RequestContext 提取 MallScope（parseMallScope 包装） */
+export function extractMallScope(ctx: RequestContext): MallScope | undefined {
+  return parseMallScope(ctx.attributes);
+}
+
+/**
+ * 模块 ports 解析槽位统一 scope 形状（017 槽位原子化：resolveService 入参单一来源）。
+ * 行为钉死：返回 `{ mallId } | {}`（flat，不含 miniAppId）——与四模块 ports 既有行为
+ * 逐字等价；补 miniAppId 会改变厂商加签身份解析器的凭据 scope 匹配路径。
+ */
+export function mallScopeOf(reqCtx: { attributes?: Record<string, unknown> }): Record<string, string> {
+  const mallId = parseMallScope(reqCtx.attributes ?? {})?.mallId;
+  return mallId ? { mallId } : {};
+}
+
+/** 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 function readLoginMallId(context?: Readonly<Record<string, unknown>>): string | undefined {
+  const mall = context?.[MALL_SCOPE_KEY];
+  if (!mall || typeof mall !== 'object') return undefined;
+  const mallId = (mall as Record<string, unknown>).mallId;
+  return typeof mallId === 'string' && mallId.length > 0 ? mallId : undefined;
+}

package/src/server/index.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/src/server/mall-context.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { extractMallScope } from '../scope';
+import type { MallScope } from '../scope';
+import { credentialsToken, credentialsMemberId, credentialsOpenId } from './request-credentials';
+
+/** 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 function mallIdentityView(reqCtx: RequestContext): MallIdentityView {
+  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 } : {}),
+  };
+}

package/src/server/mall-control-plane.ts

@@ -0,0 +1,92 @@
+/**
+ * mall 控制平面投影（integrations v4）：root instances 注册表 → MallDeploymentControlPlane。
+ * 恒返回控制平面（无表 → 空平面）——模板装配零拓扑分支。
+ * attributes 赋义 zod 单源（原双模板 deployment.ts 内嵌 zod 上收——消灭 base/mall 双份漂移）：
+ * strict 拒拼错键（strip 会让消费点恒 undefined——静默配置失效），错误消息列允许键清单。
+ * TIER0 attributes 全程 opaque，域赋义唯一发生地 = 本文件（011 B1 边界保持）。
+ *
+ * 隐式默认单实例融合（provider 声明）：零拓扑 config（无 instances/defaultInstanceId）+
+ * root.provider 命中声明键 → 注入声明实例（default 经 normalizeInstances 单实例唯一解派生
+ * ——零新规则）。显式配置恒赢；规则细节见 mergeDeclaredInstances。
+ */
+import { z } from 'zod';
+import { normalizeInstances } from '@tbox.cn/app-contracts';
+import type { DeploymentInstance, IntegrationsConfig, ProviderInstanceDeclarations } from '@tbox.cn/app-contracts';
+import type { MallDeploymentControlPlane, MallDeploymentMall } from '../deployment';
+
+/** mall 域 attributes 赋义（strict——拼错键 fail-fast，报错附允许键清单） */
+const 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 投影包，不在本文件扩键
+});
+
+/** attributes 逐条赋义（safeParse 包装——ZodError 裸 JSON 难读，重抛附实例 id 与允许键清单） */
+function parseMallAttributes(
+  inst: DeploymentInstance,
+): MallDeploymentMall {
+  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 赋义失败（允许键：miniAppId/contactPhone/location）——${detail}`,
+    );
+  }
+  return { mallId: inst.id, name: inst.name, ...result.data };
+}
+
+/**
+ * 隐式默认单实例融合（五规则；no-op 分支零分配——原 config 引用返回）：
+ * 1. declared 缺席 → 原样；
+ * 2. config.instances 非空 → 原样（显式表赢）；
+ * 3. config.defaultInstanceId 显式在场（含 null——「显式无默认」即真值）→ 原样；
+ * 4. 零拓扑 + root.provider（root 层恒 string——inline 仅 service 层）命中声明键且声明
+ *    非空 → 注入声明实例（default 走 normalizeInstances 既有唯一解）；
+ * 5. 其余（root.provider 缺席 / 声明无该键 / 空声明数组）→ 原样。
+ * 空声明数组短路守 wire 空表不变量（zod 拒空 instances 数组——「无表 = 键缺席唯一写法」；
+ * 融合发生在加载校验后，注入空表会绕过 zod 制造非法形态）。
+ */
+function mergeDeclaredInstances(
+  config: IntegrationsConfig,
+  declared: ProviderInstanceDeclarations | undefined,
+): IntegrationsConfig {
+  if (!declared) return config;
+  if (config.instances && config.instances.length > 0) return config;
+  if (config.defaultInstanceId !== undefined) 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] };
+}
+
+/**
+ * integrations config → mall 控制平面（装配链唯一入口）：
+ * - declared = provider 声明快照（缺省关闭——既有调用方零变化；消费方 = mall-core project()）；
+ * - instances 注册表逐条投影（id→mallId、name、attributes 赋义展开——声明实例过同一
+ *   zod strict 校验，坏键 fail-fast 与显式配置同律）；
+ * - defaultMallId = normalizeInstances 解析（显式 ?? 单实例唯一解；无 → undefined）。
+ */
+export function mallControlPlaneOf(
+  config: IntegrationsConfig,
+  declared?: ProviderInstanceDeclarations,
+): MallDeploymentControlPlane {
+  const { instances, defaultInstanceId } = normalizeInstances(
+    mergeDeclaredInstances(config, declared),
+  );
+  const malls: MallDeploymentMall[] = instances.map(parseMallAttributes);
+  return { malls, ...(defaultInstanceId !== null ? { defaultMallId: defaultInstanceId } : {}) };
+}