@tbox.cn/app-provider-mock 0.2.0 → 0.3.0

package/README.md

@@ -7,3 +7,41 @@ promotion×4 / shopping-guide×4 + mall.info，17 槽全 local:true——免传
   中立化（"示例会员卡"）；shopping 域为静态 seed 派生（门店/类目/楼层目录）。
 - 模板缺省绑定（F2）：裸跑即完整 mock 演示——免业务凭据，不免模型密钥。
 - 装配走 `tbox-app module add`（provider 即无卡模块）。
+
+## 实例配置（config schemas，0.3.0）
+
+17 槽全带 `configSchema`（`schemas/` 五文件按域共享：member / parking / promotion / shopping /
+mall-info）——面板动态表单 / CLI / 手编三动线同一真源。config 经平台五层浅合并
+（root.config → root.configByInstance → `domains.<域>.config` → 槽级 config → 实例级 config，
+键级覆盖）以 `input.config` 传入工厂，各实现构造期一次 fail-soft 解析（`src/server/config.ts`）：
+
+- **零配置 = 零行为变化**：33 字段缺省 ≡ 历史硬编码值（回归判据，既有测试零改动锁死）。
+- **非法值静默回退缺省**：类型不符 / NaN / 整数字段分式 / 空串——schema 是表单引导非门禁，
+  守卫在消费侧（`*_CFG_INT_KEYS` 整数约束 + shopping 楼层白名单回退）。
+- **空串语义**：`mall.info.name` 空串 = 动态别名 `示例商场（mallId）` 回退；`shopping.extraShopName`
+  空串 = 不追加门店；`member.levelName` 空串 = 卡面无等级区。
+
+字段速览（域 → 应用可见面）：
+
+| 域 | 字段 | 可见面 |
+|---|---|---|
+| member | cardName / initialPoints / levelName / memberName | 卡面名 / 积分大数字（含流水金额派生）/ 等级区 / 资料标签 |
+| member | enrollUrl / loginUrl | 入会 / 登录 CTA 深链 |
+| parking | parkName / feeName / feeCents | 信息卡标题 / 费用项 / 缴费卡金额（报价·订单·记录同源） |
+| parking | memberBenefitEnabled / memberBenefitDiscountCents / pointsBenefitEnabled | 权益勾选区与 reprice 折扣联动 |
+| parking | invoiceEnabled / remainingSpaces / firstHourRate / vehicleFloor / vehicleZone / vehicleSpaceNo | 开票按钮显隐 / 车位 / 寻车卡 |
+| promotion | couponTitle / couponValueCents / couponThresholdCents / couponValidityDays | 券列表 / 详情 / 资产（标题派生）/ 效期 |
+| promotion | grouponEnabled / activityTitle | 优惠列表项数 / 活动卡标题 |
+| shopping | extraShopName / extraShopCategory / extraShopFloor / extraShopUnit / extraShopOpen | 门店列表 / 类目聚合 / 楼层目录新增一行 |
+| mall-info | name / address / latitude / longitude | 聊天品牌区 mallName / mall-info agent 答问数据面 |
+
+**扩展约定（3 触点 + 1）**：schema 行（`schemas/<域>.config.json`）+ DEFAULTS 行（impl 同文件
+`*_CFG_DEFAULTS`）+ 消费点改引 `this.cfg.*`；整数字段追加 `*_CFG_INT_KEYS` 一项。双锁测试
+（`tests/config-schema.test.ts`）自动覆盖：键集双向 / 缺省漂移 / 整数对偶 / manifest 分发面 /
+楼层 enum 同值。
+
+**运营语义**：手编 `integrations.json` 后 dev 不自动重启（tsx watch 对 config 盲）——手动重启；
+面板保存走 RunManager `onApplied` 自动重启。**域级引导**：mock 同域多槽各自实例化（级联按槽求值）
+——凡跨槽可见的键建议配 `domains.<域>`：member 全部键 / parking.parkName·feeCents /
+promotion.couponTitle（券列表 + 我的券双槽派生）/ shopping-guide.extraShop*（四槽目录联动）；
+槽级仅用于单槽差异键（如 `promotion.offers.couponValueCents`、`mall.info.name`）。

package/dist/server/index.d.ts

@@ -2,16 +2,11 @@ import { ServiceAdapterFactory, ServerContext } from '@tbox.cn/app-sdk/server';
 import { MemberAccountPort, MemberProfilePort, MemberCardPort, MemberBenefitsPort, MemberEnrollmentPort, MemberAccountSnapshot, MemberProfileSnapshot, MemberCardSnapshot, Points, MemberBenefitsSnapshot, PointUsageRecord, DiscountRule, MemberEnrollmentInput, MemberEnrollmentResult, MemberEnrollmentFormDefinition, ParkingQueryPort, ParkingPaymentPort, ParkingVehiclePort, ParkingQueryContext, QuoteSnapshot, ParkingVehicle, ParkingRecordPage, ParkingPaymentRecord, ParkingInfo, ParkingBenefit, ParkingLocation, PromotionOfferQueryPort, PromotionEntitlementPort, PromotionActivityPort, PromotionAcquisitionPort, PromotionQueryContext, PromotionSearchInput, PromotionOfferPage, PromotionOffer, PromotionEntitlementPage, PromotionEntitlement, PromotionActivityPage, PromotionActivityDetail, PromotionOperation, CatalogQueryPort, ShopDirectoryQueryPort, CommercialCategoryQueryPort, MallDirectoryQueryPort, ShopSearchCriteria, ShoppingPage, ShopRecord, ShoppingQueryContext, CategoryRecord, MallDirectoryRecord, ProductSearchCriteria, ProductRecord, ProductFacetsRecord } from '@tbox.cn/app-contracts-mall';
 import { Router } from 'express';
 
-/**
- * Mock member 实现（provider-mock 自持——R3-1 裁决：provider 不得依赖业务模块，实现自持
- * 而非包装 module-member InMemory）。演示面最小集：开户/卡面/积分/流水/入会闭环
- * （demo ref 恒 `demo:` 前缀，厂商中立）。
- */
-
 type MockMemberService = MemberAccountPort & MemberProfilePort & MemberCardPort & MemberBenefitsPort & MemberEnrollmentPort;
 /** mock 壳侧登录用户（换码器固定身份；mock 语义 = 单 demo 用户/部署） */
 declare const MOCK_SHELL_USER_ID = "demo-user";
-/** 入会落地（幂等）：enroll 路由/enroll() 共用；余额缺省 300；登录成功即清除登出态 */
+/** 入会落地（幂等）：enroll 路由/enroll() 共用；余额不写种子——查询侧按实例配置惰性读
+ *（默认 300，见 currentBalanceOf）；登录成功即清除登出态 */
 declare function enrollMockMember(userId: string): void;
 declare function isMockMemberEnrolled(userId: string): boolean;
 /** 登出标记（mock 档登出态模拟：仅对已入会用户有意义；重登录即清除） */
@@ -25,16 +20,20 @@ declare class MockMemberServiceImpl implements MockMemberService {
      * 透传素材，mock 出厂面恒配 demo 值）。demo 值厂商中立（appId=demo），点击在壳内
      * navigateTo 失败即无害降级。
      */
-    readonly enrollUrl = "alipays://platformapi/startapp?appId=demo&page=v/index/index";
+    readonly enrollUrl: string;
     /** 登录页深链（同上，可选透传素材；供未登录引导卡跳转）。 */
-    readonly loginUrl = "alipays://platformapi/startapp?appId=demo&page=v/login/index";
+    readonly loginUrl: string;
+    /** 配置快照（fail-soft，构造期一次解析；键集 ≡ MEMBER_CFG_DEFAULTS） */
+    private readonly cfg;
+    /** 积分流水（金额随 initialPoints 派生——与余额同源） */
+    private readonly usage;
     /** 默认访客（无种子）：demo-user 初始 not_enrolled，经入会闭环翻为 active */
-    constructor(initial?: Record<string, number>);
+    constructor(initial?: Record<string, number>, config?: unknown);
     getAccount(userId: string): Promise<MemberAccountSnapshot>;
     getProfile(_userId: string): Promise<MemberProfileSnapshot>;
     getCard(userId: string): Promise<MemberCardSnapshot | null>;
     queryPoints(userId: string): Promise<Points>;
-    getBenefits(_userId: string): Promise<MemberBenefitsSnapshot>;
+    getBenefits(userId: string): Promise<MemberBenefitsSnapshot>;
     listPointUsage(_userId: string, page: number, pageSize: number): Promise<{
         items: PointUsageRecord[];
         total: number;
@@ -43,6 +42,8 @@ declare class MockMemberServiceImpl implements MockMemberService {
     deductPoints(userId: string, amount: number, _key: string): Promise<boolean>;
     refundPoints(userId: string, amount: number, _key: string): Promise<boolean>;
     awardPoints(userId: string, amount: number): Promise<boolean>;
+    /** 余额单源：显式增减覆盖值 ??（已入会 ? 配置初值 : 0）——入会不写种子（惰性读） */
+    private currentBalanceOf;
     enroll(input: MemberEnrollmentInput): Promise<MemberEnrollmentResult>;
     getEnrollmentStatus(userId: string, _attemptRef: string): Promise<{
         status: "active";
@@ -57,18 +58,21 @@ declare class MockMemberServiceImpl implements MockMemberService {
     getEnrollmentFormDefinition(): Promise<MemberEnrollmentFormDefinition>;
 }
 
-/**
- * Mock parking 实现（provider-mock 自持——R3-1 裁决）。演示面最小集：报价/车辆/记录/
- * 综合信息/权益/寻车 + 三步支付链 mock 闭环（reconcile 恒 PAID 收口）。demo ref 恒
- * `demo:` 前缀，厂商中立；车牌未提供时以演示车（demo-plate）兜底。
- */
-
 type MockParkingService = ParkingQueryPort & ParkingPaymentPort & ParkingVehiclePort;
 declare class MockParkingServiceImpl implements MockParkingService {
     private vehicles;
     private records;
-    constructor(mallId?: string);
+    /** 配置快照（fail-soft，构造期一次解析；键集 ≡ PARKING_CFG_DEFAULTS） */
+    private readonly cfg;
+    constructor(mallId?: string, config?: unknown);
     private mallId;
+    /**
+     * kind 必须下发：客户端按它分流（discount = 自动生效、不进勾选区；points = 积分入口），
+     * 服务端 projectPaymentOptions 也只认 kind==='points'。缺省时整套分流静默失效——
+     * 等级权益会退化成一个可勾选项，积分入口则从不出现。
+     */
+    private benefits;
+    private quote;
     queryFee(q: ParkingQueryContext, input: {
         plateNo?: string;
         vehicleRef?: string;
@@ -108,13 +112,15 @@ declare class MockParkingServiceImpl implements MockParkingService {
     }): Promise<void>;
 }
 
-/**
- * Mock promotion 实现（provider-mock 自持——R3-1 裁决）。演示面最小集：搜索/精查/推荐/
- * 资产列表/活动列表/领取闭环（acquire 恒 SUCCEEDED）。demo ref 恒 `demo:` 前缀，厂商中立。
- */
-
 type MockPromotionService = PromotionOfferQueryPort & PromotionEntitlementPort & PromotionActivityPort & PromotionAcquisitionPort;
 declare class MockPromotionServiceImpl implements MockPromotionService {
+    /** 配置快照（fail-soft，构造期一次解析；键集 ≡ PROMOTION_CFG_DEFAULTS） */
+    private readonly cfg;
+    /** 供/资产/活动三表（构造期按 cfg 构建——请求级实例，成本可忽略） */
+    private readonly offers;
+    private readonly entitlements;
+    private readonly activities;
+    constructor(config?: unknown);
     searchOffers(_q: PromotionQueryContext, input: PromotionSearchInput): Promise<PromotionOfferPage>;
     getOfferDetail(_q: PromotionQueryContext, input: {
         offerRef?: string;
@@ -138,20 +144,6 @@ declare class MockPromotionServiceImpl implements MockPromotionService {
     getOperation(_q: PromotionQueryContext, operationRef: string): Promise<PromotionOperation | null>;
 }
 
-/**
- * Mock shopping 实现（provider-mock 自持——R3-1 裁决：provider 不得依赖业务模块）。
- * 演示面：门店/类目/楼层目录（remote 检索域四键形状的 catalog/shop/category/directory）。
- *
- * 设计决策：
- * - 单一真源：DEMO_BUILDINGS 楼栋→楼层→门店 seed；类目/楼层业态/计数派生聚合；
- *   floorCode/buildingCode 派生同值（code=name，消除 mall-context id ↔ search-shops
- *   过滤键隐式映射）。
- * - 纯 mock：静态数组 + 内存过滤，零 IO、零外部依赖（不依赖知识库/TBOX_API_KEY/datasetId）。
- * - merchantId 连字符格式（demo-shop-NNNN）：LLM 从卡片 value 提取友好；getShop 入参 trim。
- * - catalog 空实现（对齐真实档 C 端）：演示面不覆盖商品目录，门店链路为演示重点。
- * - 构造器接受 seed（默认 DEMO_BUILDINGS）：测试可注入定制数据。
- */
-
 interface ShopSeed {
     merchantId: string;
     name: string;
@@ -172,10 +164,14 @@ interface DemoBuilding {
     floors: DemoFloor[];
 }
 declare class MockShoppingServiceImpl implements CatalogQueryPort, ShopDirectoryQueryPort, CommercialCategoryQueryPort, MallDirectoryQueryPort {
+    /** 配置快照（fail-soft，构造期一次解析；键集 ≡ SHOPPING_CFG_DEFAULTS） */
+    private readonly cfg;
     private readonly buildings;
     private readonly shops;
     private readonly categories;
-    constructor(seed?: readonly DemoBuilding[]);
+    constructor(seed?: readonly DemoBuilding[], config?: unknown);
+    /** extraShopName 非空 → 指定楼层追加演示门店（名称 trim 判空 + 楼层白名单回退——消费点守卫） */
+    private withExtraShop;
     searchShops(criteria: ShopSearchCriteria): Promise<ShoppingPage<ShopRecord>>;
     getShop(shopId: string, _ctx: ShoppingQueryContext): Promise<ShopRecord | null>;
     listCategories(_ctx: ShoppingQueryContext): Promise<readonly CategoryRecord[]>;
@@ -220,6 +216,13 @@ declare function createMockEnrollRouter(): Router;
  * （catalog 空 + shop/category/directory 纯 mock 数据）；assistance/navigation 本地知识库域
  * 归模块本地 adapter，不属 provider 供给面。
  *
+ * config 消费：五域工厂透传 input.config → 各 impl 构造期 fail-soft 快照
+ * （src/server/config.ts；键集/缺省双锁 tests/config-schema.test.ts）；零配置 = 零行为变化。
+ *
+ * 隐式默认单实例（零拓扑部署兜底）：register 期经 ctx.integrations.declareProviderInstances
+ * 声明 mall-demo——显式 instances/defaultInstanceId 恒赢（融合规则见 contracts-mall
+ * mallControlPlaneOf）；值与 .real-env mock 档演示语义一致（星河 Mock 小镇 / mock-demo-app）。
+ *
  * 入会体验闭环（C5）追加两件：
  * - scoped mock 换码器（ctx.authExchanges）：固定 demo-user、GUEST/MEMBER 双形态对齐
  *   真实厂商换码协议（潜客 token=''+openid ↔ 会员 token+memberId）——mock 档冷登走与