@tbox.cn/app-provider-mock 0.2.0

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Mock Provider 包入口（provider 拆包 F1b）。
+ * 服务端能力经 `./server` 子路径（与官方 provider 包同构）。
+ */
+export const providerId = 'provider-mock';

package/src/server/index.ts

@@ -0,0 +1,148 @@
+/**
+ * Mock Provider 包服务端入口（provider 拆包 F1b）。
+ *
+ * 17 槽 local 供给（member×5 / parking×3 / promotion×4 / guide×4 + mall.info；manifest
+ * contributes.providers.slots，local:true）：F2 模块 ports
+ * slot 一行化后经 createIntegrationsRegistry.resolveService 解析——local 短路免传输/
+ * 凭据/实例配置。实现自持（R3-1：provider 不得依赖业务模块——workspace-dag 铁律），
+ * demo ref 恒 `demo:` 前缀，厂商中立。
+ *
+ * F1b 阶段形态：adapter 工厂注册经 ctx.integrations（F2 模板装配 createIntegrationsRegistry
+ * 接线后生效）；F1b 前模块仍走探测链，本包装配无行为影响。shopping-guide 槽四键形状
+ * （catalog 空 + shop/category/directory 纯 mock 数据）；assistance/navigation 本地知识库域
+ * 归模块本地 adapter，不属 provider 供给面。
+ *
+ * 入会体验闭环（C5）追加两件：
+ * - scoped mock 换码器（ctx.authExchanges）：固定 demo-user、GUEST/MEMBER 双形态对齐
+ *   真实厂商换码协议（潜客 token=''+openid ↔ 会员 token+memberId）——mock 档冷登走与
+ *   真实档同一条换码链，H5 侧代码零分叉。刻意不实现 devExternalCredentials：dev-login
+ *   走协议 fail-soft 无 claim 签发（login-routes 三层解析能力口缺席即跳过）。
+ * - mock 入会落地路由（ctx.routes）：POST /demo/member-enroll（容器 mock-enrollment 页
+ *   回调 + curl 联调）。
+ */
+import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import type { ServiceAdapterFactory } from '@tbox.cn/app-sdk/server';
+import type { ExchangeResult } from '@tbox.cn/app-contracts';
+import { readLoginMallId } from '@tbox.cn/app-contracts-mall';
+import {
+  MockMemberServiceImpl,
+  MOCK_SHELL_USER_ID,
+  isMockMemberEnrolled,
+  isMockMemberLoggedOut,
+} from './member';
+import { MockParkingServiceImpl } from './parking';
+import { MockPromotionServiceImpl } from './promotion';
+import { MockShoppingServiceImpl } from './shopping';
+import { MOCK_MALL_INFO_PROVIDER, MOCK_MALL_INFO_IMPL, mockMallInfoFactory } from './mall-info';
+import { createMockEnrollRouter } from './mock-enroll-route';
+
+export const MOCK_PROVIDER = 'mock';
+export const MOCK_MEMBER_IMPL = 'mock-member@1';
+export const MOCK_PARKING_IMPL = 'mock-parking@1';
+export const MOCK_PROMOTION_IMPL = 'mock-promotion@1';
+export const MOCK_SHOPPING_IMPL = 'mock-shopping@1';
+
+export { MockMemberServiceImpl, MOCK_SHELL_USER_ID, enrollMockMember, isMockMemberEnrolled, logoutMockMember, isMockMemberLoggedOut, __resetMockMemberState } from './member';
+export { MockParkingServiceImpl } from './parking';
+export { MockPromotionServiceImpl } from './promotion';
+export { MockShoppingServiceImpl } from './shopping';
+export { MOCK_MALL_INFO_PROVIDER, MOCK_MALL_INFO_IMPL, mockMallInfoFactory } from './mall-info';
+export { createMockEnrollRouter } from './mock-enroll-route';
+
+const memberFactory: ServiceAdapterFactory = () => new MockMemberServiceImpl();
+const parkingFactory: ServiceAdapterFactory = (input) => new MockParkingServiceImpl(input.instanceId || 'mall-demo');
+const promotionFactory: ServiceAdapterFactory = () => new MockPromotionServiceImpl();
+/** shopping-guide：四槽分支（017 槽位原子化）——MockShoppingServiceImpl 实现全部四 Port，
+ *  结构类型满足任一槽产物（catalog 槽 = mock 空商品数据，对齐真实档无商品端点形态）。 */
+const shoppingFactory: ServiceAdapterFactory = (input) => {
+  if (
+    input.service !== 'shopping-guide.catalog'
+    && input.service !== 'shopping-guide.shops'
+    && input.service !== 'shopping-guide.categories'
+    && input.service !== 'shopping-guide.directory'
+  ) {
+    throw new Error(`mock guide 工厂不供给槽：${input.service}`);
+  }
+  return new MockShoppingServiceImpl();
+};
+/** mall.info：动态商场演示源（任意合法 mallId → 确定性别名；对齐真实厂商 mall-info adapter 通用形态） */
+const mallInfoFactory: ServiceAdapterFactory = (input) => mockMallInfoFactory(input);
+
+/**
+ * scoped mock 换码器（register 期闭包 ctx.integrations——matches 谓词零 IO 纪律）：
+ * matches 借 member.account 绑定路由（017 槽位原子化：换码器产出登录态身份 → account 槽
+ * 为语义锚；mock 档无独立 auth 槽；无条件兜底位归部署装配的自定义换码器，本候选恒
+ * scoped 层 first-match）。authCode 忽略（mock 语义：单 demo 用户/部署，无真实授权码可换）。
+ * 统一范式：context 无 mallId（未选择商场）→ 命中本候选，exchangeByCode 显性抛错，
+ * 不落内置本地 alipay（缺 env 报错误导部署）。
+ */
+function createMockAlipayLoginExchange(integrations: ServerContext['integrations']) {
+  return {
+    provider: 'alipay' as const,
+    matches(context?: Readonly<Record<string, unknown>>) {
+      const mallId = readLoginMallId(context);
+      // 未选择商场（context 无 mallId）→ 命中本换码器，由 exchangeByCode 显性抛
+      // AUTH_NOT_CONFIGURED（503）——不落内置本地 alipay（缺 env 报错误导部署）。
+      // 仅当 mallId 在场但不在 mock 绑定时才 return false（继续 fallback，多厂商并存语义）。
+      if (!mallId) return true;
+      if (!integrations) return false;
+      return integrations.hasProviderBinding('member.account', { mallId }, MOCK_PROVIDER, MOCK_MEMBER_IMPL);
+    },
+    async exchangeByCode(
+      _code: string,
+      _platform?: string,
+      context?: Readonly<Record<string, unknown>>,
+    ): Promise<ExchangeResult> {
+      // 未选择商场前置校验（与 matches 语义一致：域缺失显性报错，不产出 demo 身份）
+      if (!readLoginMallId(context)) {
+        throw new Error('AUTH_NOT_CONFIGURED: 未选择商场（登录 context 无 mallId）');
+      }
+      const userId = MOCK_SHELL_USER_ID;
+      // 会员形态需登录态健康：登出态（loggedOut）降级 GUEST 形态——对齐真实档 silentLogin 信封
+      // 非 200 降级（2026-09-02 真机实测）：登出后换码 = 潜客同构结果（token=''），H5 侧
+      // not_enrolled → 入会引导卡 → 半屏 getLoginState 闭环恢复；enroll 清登出态后冷登回 MEMBER。
+      if (isMockMemberEnrolled(userId) && !isMockMemberLoggedOut(userId)) {
+        // MEMBER 形态（对齐真实档会员换码输出）：token + memberId 随 attributes 流动
+        return {
+          identity: { userId, source: 'external' as const },
+          credentials: {
+            token: `demo:token:${userId}`,
+            provider: 'mock',
+            attributes: { memberId: userId },
+          },
+        };
+      }
+      // GUEST 形态（对齐真实档潜客分支）：token='' + openid 身份——「合法登录未入会」；
+      // 登出降级同走此构造（单源）。真实档另携 visitortoken，mock 链路无消费方故极简。
+      return {
+        identity: { userId, source: 'external' as const },
+        credentials: {
+          token: '',
+          provider: 'mock',
+          attributes: { openid: `demo:openid:${userId}` },
+        },
+      };
+    },
+  };
+}
+
+const cards = {} as const;
+
+export const serverModule = {
+  declaration: {
+    moduleId: 'provider-mock',
+  },
+  cards,
+  register(ctx: ServerContext): void {
+    // adapter 注册（v2 双键：provider 厂商名 + implementation）
+    ctx.integrations?.registerAdapter(MOCK_PROVIDER, MOCK_MEMBER_IMPL, memberFactory);
+    ctx.integrations?.registerAdapter(MOCK_PROVIDER, MOCK_PARKING_IMPL, parkingFactory);
+    ctx.integrations?.registerAdapter(MOCK_PROVIDER, MOCK_PROMOTION_IMPL, promotionFactory);
+    ctx.integrations?.registerAdapter(MOCK_PROVIDER, MOCK_SHOPPING_IMPL, shoppingFactory);
+    ctx.integrations?.registerAdapter(MOCK_MALL_INFO_PROVIDER, MOCK_MALL_INFO_IMPL, mallInfoFactory);
+    // scoped mock 换码器（member.account 绑 mock 的部署命中；其他部署不路由本包）
+    ctx.authExchanges.register(createMockAlipayLoginExchange(ctx.integrations));
+    // mock 入会落地路由（POST /api/m/provider-mock/demo/member-enroll）
+    ctx.routes.register('provider-mock', createMockEnrollRouter());
+  },
+} satisfies ServerModule;

package/src/server/mall-info.ts

@@ -0,0 +1,34 @@
+/**
+ * Mock 商场基础信息 adapter（mall.info 槽供给；对齐真实厂商 mall-info adapter 通用形态）。
+ *
+ * 动态商场演示源：任意 mallId → 恒返回确定性别名（`示例商场（<mallId>）`）——
+ * 动态 mallId 会话的品牌区 mallName 有 mock 真源（三级回退链第 2 级命中）。
+ * 固定 demo 地址/经纬度服务 mall-info agent tool 答问演示（融合远端 PR 363 演示语义）。
+ *
+ * 关键约束（对齐真实厂商 adapter 先例）：
+ * - mallId 形状守卫（/^[\w-]{1,32}$/）：畸形 ID 直接返回 undefined（S4 DoS 防线——
+ *   记录≠校验教训：请求形状断言在 provider adapter 单测锁死）
+ * - fail-soft 契约恒满足：本实现无 IO，不可能失败——契约面与真实档保持一致
+ */
+import type { MallInfo, MallInfoPort } from '@tbox.cn/app-contracts-mall';
+import type { ServiceAdapterFactory } from '@tbox.cn/app-sdk/server';
+
+export const MOCK_MALL_INFO_PROVIDER = 'mock';
+export const MOCK_MALL_INFO_IMPL = 'mock-mall-info@1';
+
+/** mallId 形状守卫（防注入类字符；畸形 → undefined——与真实厂商 adapter 同规则） */
+const MALL_ID_RE = /^[\w-]{1,32}$/;
+
+/** mock mall.info adapter 工厂（对齐真实厂商 adapter 工厂形态） */
+export const mockMallInfoFactory: ServiceAdapterFactory = (): MallInfoPort => ({
+  async getMallInfo(mallId: string): Promise<MallInfo | undefined> {
+    if (!MALL_ID_RE.test(mallId)) return undefined;
+    return {
+      mallId,
+      name: `示例商场（${mallId}）`,
+      address: '示例商场地址（demo）',
+      latitude: 30.0,
+      longitude: 120.0,
+    };
+  },
+});

package/src/server/member.ts

@@ -0,0 +1,180 @@
+/**
+ * Mock member 实现（provider-mock 自持——R3-1 裁决：provider 不得依赖业务模块，实现自持
+ * 而非包装 module-member InMemory）。演示面最小集：开户/卡面/积分/流水/入会闭环
+ * （demo ref 恒 `demo:` 前缀，厂商中立）。
+ */
+import type {
+  MemberAccountPort,
+  MemberAccountSnapshot,
+  MemberBenefitsPort,
+  MemberBenefitsSnapshot,
+  MemberCardPort,
+  MemberCardSnapshot,
+  MemberEnrollmentPort,
+  MemberEnrollmentInput,
+  MemberEnrollmentResult,
+  MemberEnrollmentFormDefinition,
+  MemberProfilePort,
+  MemberProfileSnapshot,
+  PointUsageRecord,
+  Points,
+  DiscountRule,
+} from '@tbox.cn/app-contracts-mall';
+
+export type MockMemberService = MemberAccountPort &
+  MemberProfilePort &
+  MemberCardPort &
+  MemberBenefitsPort &
+  MemberEnrollmentPort;
+
+const DEMO_USAGE: PointUsageRecord[] = [
+  { usageRecordRef: 'demo:usage:1', title: '开卡礼', amount: '+300', usedAt: new Date().toISOString(), description: 'mock 演示流水' },
+];
+
+/**
+ * Mock member 状态单源（模块级共享）：factory 每请求新建实例，但状态必须跨实例共享——
+ * 入会闭环（mock-enrollment 容器页回调翻状态 → 冷登换码/业务查询读同一份状态）依赖此可见性。
+ */
+const mockMemberState = {
+  enrolled: new Set<string>(),
+  balances: new Map<string, number>(),
+  loggedOut: new Set<string>(), // 登出态：已入会但登录态失效（对齐真实档 silentLogin 非 200 语义）
+};
+
+/** mock 壳侧登录用户（换码器固定身份；mock 语义 = 单 demo 用户/部署） */
+export const MOCK_SHELL_USER_ID = 'demo-user';
+
+/** 入会落地（幂等）：enroll 路由/enroll() 共用；余额缺省 300；登录成功即清除登出态 */
+export function enrollMockMember(userId: string): void {
+  mockMemberState.enrolled.add(userId);
+  mockMemberState.loggedOut.delete(userId);
+  if (!mockMemberState.balances.has(userId)) mockMemberState.balances.set(userId, 300);
+}
+
+export function isMockMemberEnrolled(userId: string): boolean {
+  return mockMemberState.enrolled.has(userId);
+}
+
+/** 登出标记（mock 档登出态模拟：仅对已入会用户有意义；重登录即清除） */
+export function logoutMockMember(userId: string): void {
+  mockMemberState.loggedOut.add(userId);
+}
+
+export function isMockMemberLoggedOut(userId: string): boolean {
+  return mockMemberState.loggedOut.has(userId);
+}
+
+/** 测试复位（沿 __resetAuthClientSingleton 先例——模块级共享状态可重置） */
+export function __resetMockMemberState(): void {
+  mockMemberState.enrolled.clear();
+  mockMemberState.balances.clear();
+  mockMemberState.loggedOut.clear();
+}
+
+/** 会员判定单谓词：入会 ∧ 登录态健康。登出态 = not_enrolled——对齐真实档降级会话语义
+ *（token 空 + visitortoken 在场 → not_enrolled，驱动入会引导卡/半屏而非误报 active；
+ * M1 全局态判定：mock 单用户不变式下与真实档会话凭证判定可观测等价，M2 会话凭证同构为被拒备选） */
+function isMockMemberActive(userId: string): boolean {
+  return mockMemberState.enrolled.has(userId) && !mockMemberState.loggedOut.has(userId);
+}
+
+export class MockMemberServiceImpl implements MockMemberService {
+  /**
+   * 开卡入会落地页深链（module-member MemberService.enrollUrl 接口面——CTA 卡深链为可选
+   * 透传素材，mock 出厂面恒配 demo 值）。demo 值厂商中立（appId=demo），点击在壳内
+   * navigateTo 失败即无害降级。
+   */
+  readonly enrollUrl = 'alipays://platformapi/startapp?appId=demo&page=v/index/index';
+  /** 登录页深链（同上，可选透传素材；供未登录引导卡跳转）。 */
+  readonly loginUrl = 'alipays://platformapi/startapp?appId=demo&page=v/login/index';
+
+  /** 默认访客（无种子）：demo-user 初始 not_enrolled，经入会闭环翻为 active */
+  constructor(initial: Record<string, number> = {}) {
+    for (const [userId, balance] of Object.entries(initial)) {
+      mockMemberState.enrolled.add(userId);
+      mockMemberState.balances.set(userId, balance);
+    }
+  }
+
+  async getAccount(userId: string): Promise<MemberAccountSnapshot> {
+    const active = isMockMemberActive(userId);
+    return {
+      authState: 'authenticated',
+      state: active ? 'active' : 'not_enrolled',
+      ...(active ? { memberRef: `demo:member:${userId}` } : {}),
+      observedAt: new Date().toISOString(),
+    };
+  }
+
+  async getProfile(_userId: string): Promise<MemberProfileSnapshot> {
+    return { labels: [{ labelRef: 'demo:label:1', name: '示例会员' }], observedAt: new Date().toISOString() };
+  }
+
+  async getCard(userId: string): Promise<MemberCardSnapshot | null> {
+    if (!isMockMemberActive(userId)) return null;
+    return {
+      cardRef: `demo:card:${userId}`,
+      cardDisplay: '示例会员卡',
+      status: 'active',
+      observedAt: new Date().toISOString(),
+    };
+  }
+
+  async queryPoints(userId: string): Promise<Points> {
+    return { userId, balance: mockMemberState.balances.get(userId) ?? 0, membershipLabel: '示例会员卡' };
+  }
+
+  async getBenefits(_userId: string): Promise<MemberBenefitsSnapshot> {
+    return { availablePoints: 300, levelName: '示例等级', observedAt: new Date().toISOString() };
+  }
+
+  async listPointUsage(_userId: string, page: number, pageSize: number) {
+    const start = (page - 1) * pageSize;
+    return { items: DEMO_USAGE.slice(start, start + pageSize), total: DEMO_USAGE.length };
+  }
+
+  async queryDiscount(): Promise<DiscountRule | undefined> {
+    return { level: 'silver', discount: 0.95 };
+  }
+
+  async deductPoints(userId: string, amount: number, _key: string): Promise<boolean> {
+    const balance = mockMemberState.balances.get(userId) ?? 0;
+    if (balance < amount) return false;
+    mockMemberState.balances.set(userId, balance - amount);
+    return true;
+  }
+
+  async refundPoints(userId: string, amount: number, _key: string): Promise<boolean> {
+    mockMemberState.balances.set(userId, (mockMemberState.balances.get(userId) ?? 0) + amount);
+    return true;
+  }
+
+  async awardPoints(userId: string, amount: number): Promise<boolean> {
+    mockMemberState.balances.set(userId, (mockMemberState.balances.get(userId) ?? 0) + amount);
+    return true;
+  }
+
+  async enroll(input: MemberEnrollmentInput): Promise<MemberEnrollmentResult> {
+    enrollMockMember(input.userId);
+    return { status: 'active', memberRef: `demo:member:${input.userId}` };
+  }
+
+  async getEnrollmentStatus(userId: string, _attemptRef: string) {
+    return mockMemberState.enrolled.has(userId)
+      ? { status: 'active' as const, memberRef: `demo:member:${userId}` }
+      : { status: 'failed' as const, reason: 'mock：未入会' };
+  }
+
+  /** 入会表单定义（模块 queryEnrollmentForm 工具消费；无参对齐 InMemory 先例） */
+  async getEnrollmentFormDefinition(): Promise<MemberEnrollmentFormDefinition> {
+    return {
+      formVersion: 'demo-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',
+    };
+  }
+}

package/src/server/mock-enroll-route.ts

@@ -0,0 +1,84 @@
+/**
+ * Mock 入会落地点路由（入会体验闭环 C5）：POST /api/m/provider-mock/demo/member-enroll。
+ *
+ * 容器 mock-enrollment 页（dev 脚手架）与 curl 联调共用：
+ * - body `{userId?}`：缺省 MOCK_SHELL_USER_ID（mock 页无参——与真实 gate 无参协议面一致；
+ *   curl 可定向翻 dev_h5 等浏览器 dev 用户造会员态调试）。
+ * - 幂等（Set.add / 余额保守写）；NODE_ENV=production → 503（provider-mock 不进生产装配，双保险）。
+ * - 经全局 /api 鉴权（AUTH_MODE 缺省 required）——调用方须携 dev-login 令牌；
+ *   匿名写显式拒绝（不随 AUTH_MODE 放宽）。
+ * - doctor naked-write-route：/demo 前缀在白名单内（webhook/upload/demo/run）。
+ *
+ * 决策逻辑抽纯函数 resolveMockEnroll（单测直达，路由层只做 HTTP 形状映射）。
+ */
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import { getRequestContext } from '@tbox.cn/app-sdk/server';
+import { MOCK_SHELL_USER_ID, enrollMockMember, logoutMockMember } from './member';
+
+export type MockEnrollOutcome =
+  | { status: 200; body: { state: 'active'; memberRef: string } }
+  | { status: 401; body: { error: string } }
+  | { status: 503; body: { error: string } };
+
+/** 纯决策：production 拒 503 → 匿名/无身份拒 401 → 翻状态返 200（幂等） */
+export function resolveMockEnroll(input: {
+  body?: unknown;
+  identity?: { source: string } | null;
+  nodeEnv?: string;
+}): MockEnrollOutcome {
+  if ((input.nodeEnv ?? process.env.NODE_ENV) === 'production') {
+    return { status: 503, body: { error: 'mock-only' } };
+  }
+  if (!input.identity || input.identity.source === 'anonymous') {
+    return { status: 401, body: { error: 'unauthorized' } };
+  }
+  const body = (input.body ?? {}) as { userId?: unknown };
+  const userId = typeof body.userId === 'string' && body.userId.trim()
+    ? body.userId.trim()
+    : MOCK_SHELL_USER_ID;
+  enrollMockMember(userId);
+  return { status: 200, body: { state: 'active', memberRef: `demo:member:${userId}` } };
+}
+
+export type MockLogoutOutcome =
+  | { status: 200; body: { state: 'logged_out' } }
+  | { status: 401; body: { error: string } }
+  | { status: 503; body: { error: string } };
+
+/** 纯决策：production 拒 503 → 匿名/无身份拒 401 → 翻登出态返 200（与 enroll 同形） */
+export function resolveMockLogout(input: {
+  body?: unknown;
+  identity?: { source: string } | null;
+  nodeEnv?: string;
+}): MockLogoutOutcome {
+  if ((input.nodeEnv ?? process.env.NODE_ENV) === 'production') {
+    return { status: 503, body: { error: 'mock-only' } };
+  }
+  if (!input.identity || input.identity.source === 'anonymous') {
+    return { status: 401, body: { error: 'unauthorized' } };
+  }
+  const body = (input.body ?? {}) as { userId?: unknown };
+  const userId = typeof body.userId === 'string' && body.userId.trim()
+    ? body.userId.trim()
+    : MOCK_SHELL_USER_ID;
+  logoutMockMember(userId);
+  return { status: 200, body: { state: 'logged_out' } };
+}
+
+export function createMockEnrollRouter(): Router {
+  const router = Router();
+  router.post('/demo/member-enroll', (req: Request, res: Response) => {
+    const identity = getRequestContext(req)?.identity;
+    const outcome = resolveMockEnroll({ body: req.body, identity });
+    res.status(outcome.status).json(outcome.body);
+  });
+  // mock 登出路由（curl 联调/测试：翻登出态 → H5 重进换码降级为访客（与未入会一致），
+  // 调会员服务时经入会半屏 → getLoginState 闭环恢复，enroll 即清登出态）
+  router.post('/demo/member-logout', (req: Request, res: Response) => {
+    const identity = getRequestContext(req)?.identity;
+    const outcome = resolveMockLogout({ body: req.body, identity });
+    res.status(outcome.status).json(outcome.body);
+  });
+  return router;
+}

package/src/server/parking.ts

@@ -0,0 +1,182 @@
+/**
+ * Mock parking 实现（provider-mock 自持——R3-1 裁决）。演示面最小集：报价/车辆/记录/
+ * 综合信息/权益/寻车 + 三步支付链 mock 闭环（reconcile 恒 PAID 收口）。demo ref 恒
+ * `demo:` 前缀，厂商中立；车牌未提供时以演示车（demo-plate）兜底。
+ */
+import type {
+  ParkingBenefit,
+  ParkingInfo,
+  ParkingLocation,
+  ParkingPaymentPort,
+  ParkingPaymentRecord,
+  ParkingQueryPort,
+  ParkingRecordPage,
+  ParkingVehicle,
+  ParkingVehiclePort,
+  ParkingQueryContext,
+  QuoteSnapshot,
+} from '@tbox.cn/app-contracts-mall';
+
+export type MockParkingService = ParkingQueryPort & ParkingPaymentPort & ParkingVehiclePort;
+
+const now = () => new Date().toISOString();
+
+/**
+ * kind 必须下发：客户端按它分流（discount = 自动生效、不进勾选区；points = 积分入口），
+ * 服务端 projectPaymentOptions 也只认 kind==='points'。缺省时整套分流静默失效——
+ * 等级权益会退化成一个可勾选项，积分入口则从不出现。
+ */
+const DEMO_BENEFITS: ParkingBenefit[] = [
+  { benefitRef: 'demo:benefit:member-discount', title: '会员 95 折', description: 'mock 演示权益', kind: 'discount', autoSelected: true, estimatedDiscountCents: 75 },
+  { benefitRef: 'demo:benefit:points-offset', title: '积分抵 5 元', description: 'mock 演示权益', kind: 'points', autoSelected: false, estimatedDiscountCents: 500, requiredPoints: 500, previewPayableCents: 1000 },
+];
+
+function demoQuote(q: ParkingQueryContext, plateNo: string): QuoteSnapshot {
+  return {
+    quoteRef: `demo:quote:${plateNo}`,
+    plateNo,
+    mallId: q.scope.mallId ?? 'demo',
+    entryAt: now(),
+    feeItems: [{ name: '停车费（3 小时）', amountCents: 1500 }],
+    totalCents: 1500,
+    discountCents: 0,
+    payableCents: 1500,
+    appliedBenefits: [],
+    revision: 1,
+    paymentState: 'UNPAID',
+  };
+}
+
+export class MockParkingServiceImpl implements MockParkingService {
+  private vehicles = new Map<string, ParkingVehicle>();
+  private records: ParkingPaymentRecord[] = [
+    {
+      recordRef: 'demo:record:1',
+      plateNo: 'demo-plate',
+      amountCents: 1500,
+      paidAt: now(),
+      status: 'PAID',
+      parkName: '示例停车场',
+      orderCompleted: true,
+    },
+  ];
+
+  constructor(mallId = 'mall-demo') {
+    this.mallId = mallId;
+    void this.mallId;
+  }
+
+  private mallId: string;
+
+  async queryFee(q: ParkingQueryContext, input: { plateNo?: string; vehicleRef?: string }): Promise<readonly QuoteSnapshot[]> {
+    const plateNo = input.plateNo ?? (input.vehicleRef ? this.vehicles.get(input.vehicleRef)?.plateNo : undefined) ?? 'demo-plate';
+    const quote = demoQuote(q, plateNo);
+    return quote ? [quote] : [];
+  }
+
+  async listVehicles(): Promise<{ bound: readonly ParkingVehicle[] }> {
+    // mock 有报价即视作在场：demo 里第一辆车恒有报价，其余按未入场
+    const list = [...this.vehicles.values()];
+    return { bound: list.map((v, i) => ({ ...v, parked: i === 0 })) };
+  }
+
+  async listPaymentRecords(_q: ParkingQueryContext, page: number, pageSize: number): Promise<ParkingRecordPage> {
+    const start = (page - 1) * pageSize;
+    const items = this.records.slice(start, start + pageSize);
+    return { items, total: this.records.length, page, pageSize, hasMore: start + pageSize < this.records.length };
+  }
+
+  async getPaymentRecordDetail(_q: ParkingQueryContext, recordRef: string): Promise<ParkingPaymentRecord> {
+    const record = this.records.find((r) => r.recordRef === recordRef);
+    if (!record) throw new Error(`mock：记录不存在 ${recordRef}`);
+    return record;
+  }
+
+  async getInvoiceSettings(): Promise<{ parkingInvoiceEnabled: boolean }> {
+    return { parkingInvoiceEnabled: true };
+  }
+
+  async listInvoiceableOrders(_q: ParkingQueryContext, page: number, pageSize: number): Promise<ParkingRecordPage> {
+    const all = this.records.filter((r) => r.orderCompleted === true);
+    const start = (page - 1) * pageSize;
+    return { items: all.slice(start, start + pageSize), total: all.length, page, pageSize, hasMore: start + pageSize < all.length };
+  }
+
+  async queryParkingInfo(_q: ParkingQueryContext, kind: ParkingInfo['kind']): Promise<ParkingInfo> {
+    return {
+      kind,
+      title: '示例停车场',
+      entries: [
+        { label: '剩余车位', value: '128' },
+        { label: '首小时费率', value: '免费' },
+        { label: '会员权益', value: '会员 95 折' },
+      ],
+    };
+  }
+
+  async queryApplicableBenefits(_q: ParkingQueryContext, _plateNo: string): Promise<readonly ParkingBenefit[]> {
+    return DEMO_BENEFITS;
+  }
+
+  async locateVehicle(_q: ParkingQueryContext, _plateNo: string): Promise<ParkingLocation | null> {
+    return { floorName: 'B1', zoneName: 'A 区', spaceNo: 'A-128', walkingRoute: '电梯左转 50 米' };
+  }
+
+  // ===== 支付三步链（mock：reconcile 恒 PAID 收口） =====
+
+  async createOrder(_q: ParkingQueryContext, quoteRef: string): Promise<{ payOrderId?: string; paymentRef: string }> {
+    return { payOrderId: `demo:pay:${quoteRef}`, paymentRef: `demo:payment:${quoteRef}` };
+  }
+
+  async getOrderInfo(_q: ParkingQueryContext, _paymentRef: string): Promise<{ orderInfo?: string; channel: string; payableFeeCents: number | undefined }> {
+    return { orderInfo: 'demo-order-info', channel: '50', payableFeeCents: 1500 };
+  }
+
+  async getPaymentSign(_q: ParkingQueryContext, _paymentRef: string): Promise<{ orderInfo: string }> {
+    return { orderInfo: 'demo-order-info' };
+  }
+
+  async uploadResult(): Promise<void> {
+    // mock：仅上报不作收口依据
+  }
+
+  async reconcile(_q: ParkingQueryContext, _paymentRef: string): Promise<'PAID' | 'PAYING' | 'CANCELLED' | 'UNKNOWN'> {
+    return 'PAID';
+  }
+
+  async reprice(q: ParkingQueryContext, quoteRef: string, benefitRefs: readonly string[]): Promise<QuoteSnapshot> {
+    const base = demoQuote(q, 'demo-plate');
+    const discount = DEMO_BENEFITS.filter((b) => benefitRefs.includes(b.benefitRef))
+      .reduce((sum, b) => sum + (b.estimatedDiscountCents ?? 0), 0);
+    return {
+      ...base,
+      quoteRef: `${quoteRef}#r${Date.now()}`,
+      discountCents: discount,
+      payableCents: Math.max(0, base.totalCents - discount),
+    };
+  }
+
+  async applyInvoice(_q: ParkingQueryContext, recordRef: string): Promise<void> {
+    if (!this.records.some((r) => r.recordRef === recordRef)) {
+      throw new Error(`mock：开票记录不存在 ${recordRef}`);
+    }
+  }
+
+  // ===== 车辆管理 =====
+
+  async bindVehicle(_q: ParkingQueryContext, plateNo: string): Promise<ParkingVehicle> {
+    const vehicle = { vehicleRef: `demo:vehicle:${plateNo}`, plateNo, boundAt: now() };
+    this.vehicles.set(vehicle.vehicleRef, vehicle);
+    return vehicle;
+  }
+
+  async unbindVehicle(_q: ParkingQueryContext, input: { plateNo?: string; vehicleRef?: string }): Promise<void> {
+    if (input.vehicleRef) this.vehicles.delete(input.vehicleRef);
+    else if (input.plateNo) {
+      for (const [ref, v] of this.vehicles) {
+        if (v.plateNo === input.plateNo) this.vehicles.delete(ref);
+      }
+    }
+  }
+
+}