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

package/dist/shopping-guide/ports.d.ts

@@ -0,0 +1,216 @@
+/**
+ * 导购域 Port 接口（011 S7：shopping-guide 6 Port，TIER1 结构类型子集）。
+ * 模块完整实现 extends 本接口；消费方（其他模块）仅依赖契约包。
+ */
+import type { MallRequestContext, MallScope } from '../scope';
+export interface ShoppingQueryContext {
+    /** mall scope（session 绑定） */
+    readonly scope: MallScope;
+    /** 当前主体（会员体系 subjectId；匿名缺省） */
+    readonly subjectId?: string;
+    /** 请求上下文（handler 内可用；跨模块消费方仅依赖本契约） */
+    readonly requestContext: MallRequestContext;
+}
+export interface ShoppingPage<T> {
+    readonly items: readonly T[];
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total: number;
+    readonly hasMore: boolean;
+}
+export interface ProductSearchCriteria {
+    readonly ctx: ShoppingQueryContext;
+    readonly keyword?: string;
+    readonly keywords?: readonly string[];
+    readonly categoryCode?: string;
+    readonly brandCode?: string;
+    readonly minPriceMinor?: number;
+    readonly maxPriceMinor?: number;
+    readonly floorCode?: string;
+    readonly buildingCode?: string;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly marketableOnly?: boolean;
+}
+export interface CatalogQueryPort {
+    searchProducts(criteria: ProductSearchCriteria): Promise<ShoppingPage<ProductRecord>>;
+    getProduct(productId: string, ctx: ShoppingQueryContext): Promise<ProductRecord | null>;
+    getFacets(criteria: ProductSearchCriteria): Promise<ProductFacetsRecord>;
+}
+export interface ProductRecord {
+    readonly productId: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly imageUrls: readonly string[];
+    readonly brand?: string;
+    readonly categoryPath: readonly string[];
+    readonly price: {
+        readonly sale?: MoneyRecord;
+        readonly original?: MoneyRecord;
+        readonly promotion?: MoneyRecord;
+    };
+    readonly availability: {
+        readonly status: 'in_stock' | 'out_of_stock' | 'limited' | 'unknown';
+        readonly label: string;
+        readonly marketable: boolean;
+        readonly observedAt: string;
+    };
+    readonly merchant: {
+        readonly merchantId: string;
+        readonly name: string;
+        readonly location?: MerchantLocationRecord;
+    };
+    readonly labels: readonly string[];
+    readonly attributes: ReadonlyArray<{
+        readonly name: string;
+        readonly value: string;
+    }>;
+    readonly promotionFacts: readonly string[];
+    readonly observedAt: string;
+}
+export interface MoneyRecord {
+    readonly currency: 'CNY';
+    readonly amountMinor: number;
+    readonly display: string;
+}
+export interface MerchantLocationRecord {
+    readonly buildingName?: string;
+    readonly floorName?: string;
+    readonly unitName?: string;
+    readonly displayText: string;
+    readonly poiId?: string;
+}
+export interface ProductFacetsRecord {
+    readonly brands: ReadonlyArray<{
+        readonly code: string;
+        readonly name: string;
+        readonly count: number;
+    }>;
+    readonly categories: ReadonlyArray<{
+        readonly code: string;
+        readonly name: string;
+        readonly count: number;
+    }>;
+    readonly priceRanges: ReadonlyArray<{
+        readonly minMinor: number;
+        readonly maxMinor: number;
+        readonly displayLabel: string;
+        readonly count: number;
+    }>;
+    readonly floors: ReadonlyArray<{
+        readonly code: string;
+        readonly displayName: string;
+        readonly count: number;
+    }>;
+}
+export interface MerchantSearchCriteria {
+    readonly ctx: ShoppingQueryContext;
+    readonly keyword?: string;
+    readonly keywords?: readonly string[];
+    readonly brandCode?: string;
+    readonly businessCategory?: string;
+    readonly floorCode?: string;
+    readonly buildingCode?: string;
+    readonly page: number;
+    readonly pageSize: number;
+}
+export interface MerchantDirectoryQueryPort {
+    searchMerchants(criteria: MerchantSearchCriteria): Promise<ShoppingPage<MerchantRecord>>;
+    getMerchant(merchantId: string, ctx: ShoppingQueryContext): Promise<MerchantRecord | null>;
+}
+export interface MerchantRecord {
+    readonly merchantId: string;
+    readonly name: string;
+    readonly logoUrl?: string;
+    readonly coverUrls: readonly string[];
+    readonly brand?: string;
+    readonly businessCategories: readonly string[];
+    readonly location: MerchantLocationRecord;
+    readonly status: {
+        readonly code: 'enabled' | 'disabled' | 'unknown';
+        readonly label: string;
+        readonly observedAt: string;
+    };
+    readonly description?: string;
+    readonly contactInfo?: ReadonlyArray<{
+        readonly channel: string;
+        readonly value: string;
+    }>;
+    readonly services: readonly string[];
+    readonly promotionFacts: readonly string[];
+    readonly observedAt: string;
+}
+export interface CommercialCategoryQueryPort {
+    listCategories(ctx: ShoppingQueryContext): Promise<readonly CategoryRecord[]>;
+}
+export interface CategoryRecord {
+    readonly code: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly merchantCount: number;
+    readonly subCategories?: ReadonlyArray<{
+        readonly code: string;
+        readonly name: string;
+        readonly merchantCount: number;
+    }>;
+}
+export interface MallDirectoryQueryPort {
+    getDirectory(ctx: ShoppingQueryContext): Promise<MallDirectoryRecord | null>;
+}
+export interface MallDirectoryRecord {
+    readonly mallId: string;
+    readonly mallName: string;
+    readonly buildings: ReadonlyArray<{
+        readonly buildingCode: string;
+        readonly buildingName: string;
+        readonly floors: ReadonlyArray<{
+            readonly floorCode: string;
+            readonly floorName: string;
+            readonly businessCategories: readonly string[];
+            readonly merchantCount: number;
+        }>;
+    }>;
+    readonly observedAt: string;
+}
+export interface FaqEntry {
+    readonly question: string;
+    readonly answer: string;
+    readonly category?: string;
+    readonly relevanceScore: number;
+}
+export interface AssistanceQueryPort {
+    searchFaq(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly FaqEntry[]>;
+    searchKnowledge(ctx: ShoppingQueryContext, query: string, topK?: number): Promise<readonly KnowledgeEntry[]>;
+    listHumanGuides(merchantId: string, ctx: ShoppingQueryContext): Promise<readonly HumanGuideRecord[]>;
+}
+export interface KnowledgeEntry {
+    readonly content: string;
+    readonly title?: string;
+    readonly score: number;
+}
+export interface HumanGuideRecord {
+    readonly guideId: string;
+    readonly name: string;
+    readonly title?: string;
+    readonly avatarUrl?: string;
+    readonly contactInfo?: ReadonlyArray<{
+        readonly channel: string;
+        readonly value: string;
+    }>;
+    readonly available: boolean;
+}
+export interface NavigationPort {
+    getLocation(merchantId: string, ctx: ShoppingQueryContext): Promise<MerchantLocationRecord | null>;
+    listNearbyMalls(ctx: ShoppingQueryContext, query?: string): Promise<readonly NearbyMallRecord[]>;
+    listBrowsingHistory(ctx: ShoppingQueryContext, page: number, pageSize: number): Promise<ShoppingPage<ProductRecord>>;
+}
+export interface NearbyMallRecord {
+    readonly mallId: string;
+    readonly name: string;
+    readonly address: string;
+    readonly distanceKm?: number;
+    readonly status: {
+        readonly code: 'open' | 'closed' | 'unknown';
+        readonly label: string;
+    };
+}

package/package.json

@@ -1,18 +1,16 @@
 {
   "name": "@tbox.cn/app-contracts-mall",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
-  "description": "商圈领域契约（TIER1，types-only）：Port 接口 + MallEventMap + 领域 DTO。",
+  "description": "商圈领域契约（TIER1，types + runtime）：Port 接口 + MallEventMap + 领域 DTO + scope/装配器运行时。",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/runtime.js"
     }
   },
   "files": [
     "dist",
-    "src",
-    "tsconfig.json",
-    "tsconfig.build.json",
     "README.md",
     "LICENSE"
   ],
@@ -22,15 +20,17 @@
   "publishConfig": {
     "access": "public"
   },
-  "peerDependencies": {
+  "dependencies": {
+    "@tbox.cn/app-contracts": "^0.1.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "tsup": "^8.0.0",
     "typescript": "^5.7.0"
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && tsup src/runtime.ts --format esm --external @ag-ui/core --out-dir dist",
     "typecheck": "tsc --noEmit"
   }
 }

package/src/domain/coupon.ts

@@ -1,8 +0,0 @@
-/** 优惠券（商圈领域 DTO） */
-export interface Coupon {
-  couponId: string;
-  title: string;
-  /** 可抵扣金额（元） */
-  amount: number;
-  status: 'AVAILABLE' | 'USED' | 'EXPIRED';
-}

package/src/domain/discount.ts

@@ -1,6 +0,0 @@
-/** 折扣规则（商圈领域 DTO） */
-export interface DiscountRule {
-  level: 'silver' | 'gold' | 'platinum';
-  /** 折扣率 0-1（0.9 = 9 折） */
-  discount: number;
-}

package/src/domain/parking.ts

@@ -1,13 +0,0 @@
-/** 停车费单（商圈领域 DTO，同时是 parking-fee 卡片数据契约） */
-export interface ParkingFee {
-  orderId: string;
-  userId: string;
-  plate: string;
-  /** 应付金额（元） */
-  fee: number;
-  /** 实付金额（抵扣后，元） */
-  paidAmount?: number;
-  /** 使用积分 */
-  pointsUsed?: number;
-  status: 'PENDING' | 'PAID' | 'CANCELLED';
-}

package/src/domain/points.ts

@@ -1,14 +0,0 @@
-/** 会员积分与等级（商圈领域 DTO） */
-export interface Points {
-  userId: string;
-  /** 当前积分余额 */
-  balance: number;
-  level: 'silver' | 'gold' | 'platinum';
-}
-
-/** 积分余额变动结果 */
-export interface PointsChangeResult {
-  success: boolean;
-  balance: number;
-  reason?: string;
-}

package/src/events/index.ts

@@ -1,10 +0,0 @@
-/**
- * MallEventMap：商圈跨模块事件（类型化事件总线 keyof 约束，001 §5.4）。
- * 用 type（非 interface）以获得隐式索引签名，满足 SDK EventMap（Record<string, unknown>）约束。
- */
-export type MallEventMap = {
-  /** 会员等级变更 */
-  'member.level.changed': { userId: string; newLevel: 'silver' | 'gold' | 'platinum' };
-  /** 停车券核销 */
-  'parking.coupon.used': { userId: string; couponId: string; amount: number };
-};

package/src/index.ts

@@ -1,13 +0,0 @@
-/**
- * @tbox.cn/app-contracts-mall：商圈领域契约（TIER1，types-only 纯类型包）。
- * 消费方（module-parking / module-promotion / scenario）只依赖本契约，
- * 不依赖任何模块实现包——结构类型子集接口 + 事件总线破环双向依赖。
- */
-export * from './domain/points';
-export * from './domain/coupon';
-export * from './domain/discount';
-export * from './domain/parking';
-export * from './services/member';
-export * from './services/parking';
-export * from './services/promotion';
-export * from './events';

package/src/services/member.ts

@@ -1,21 +0,0 @@
-import type { Points } from '../domain/points';
-import type { DiscountRule } from '../domain/discount';
-
-/**
- * MemberQueryPort：消费方（parking / scenario）需要的 member 查询子集。
- * 结构类型子集接口——模块完整实现 extends 此接口，消费方仅依赖契约包（001 §5.3）。
- */
-export interface MemberQueryPort {
-  queryPoints(userId: string): Promise<Points>;
-  queryDiscount(userId: string): Promise<DiscountRule | undefined>;
-}
-
-/**
- * MemberSettlementPort：跨模块写操作（scenario 编排 + 补偿用）。
- * 幂等键由调用方（scenario handler）生成。
- */
-export interface MemberSettlementPort {
-  deductPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean>;
-  refundPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean>;
-  awardPoints(userId: string, amount: number): Promise<boolean>;
-}

package/src/services/parking.ts

@@ -1,16 +0,0 @@
-import type { ParkingFee } from '../domain/parking';
-
-/** ParkingQueryPort：消费方（scenario / member）需要的停车查询子集 */
-export interface ParkingQueryPort {
-  queryParkingFee(userId: string, orderId?: string): Promise<ParkingFee | undefined>;
-}
-
-/** ParkingSettlementPort：停车结算写操作（scenario 编排用） */
-export interface ParkingSettlementPort {
-  /** 计算停车费（无订单则生成） */
-  calcFee(userId: string, orderId: string): Promise<ParkingFee>;
-  /** 核销停车券 */
-  useCoupon(userId: string, orderId: string, couponId: string): Promise<boolean>;
-  /** 结算停车费（抵扣后支付剩余金额） */
-  settlePayment(userId: string, orderId: string, amount: number): Promise<boolean>;
-}

package/src/services/promotion.ts

@@ -1,6 +0,0 @@
-import type { Coupon } from '../domain/coupon';
-
-/** PromotionQueryPort：营销资格查询（scenario 出券用） */
-export interface PromotionQueryPort {
-  queryEligibleCoupons(userId: string): Promise<Coupon[]>;
-}

package/tsconfig.build.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "declaration": true,
-    "emitDeclarationOnly": true,
-    "outDir": "dist",
-    "skipLibCheck": true,
-    "esModuleInterop": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}

package/tsconfig.json

@@ -1,5 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {},
-  "include": ["src"]
-}