@tbox.cn/app-contracts-mall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tbox.cn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @tbox.cn/app-contracts-mall
+
+商圈领域契约（TIER1，types-only）：Port 接口 + MallEventMap + 领域 DTO。
+
+## 安装
+
+```sh
+pnpm add @tbox.cn/app-contracts-mall
+```
+
+## 说明
+
+商圈业务契约类型真源包；消费方经 `@tbox.cn/app-contracts-mall` 公开入口引用。

package/dist/domain/coupon.d.ts

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

package/dist/domain/discount.d.ts

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

package/dist/domain/parking.d.ts

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

package/dist/domain/points.d.ts

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

package/dist/events/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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/dist/services/member.d.ts

@@ -0,0 +1,19 @@
+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/dist/services/parking.d.ts

@@ -0,0 +1,14 @@
+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/dist/services/promotion.d.ts

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@tbox.cn/app-contracts-mall",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "商圈领域契约（TIER1，types-only）：Port 接口 + MallEventMap + 领域 DTO。",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "tsconfig.build.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/domain/coupon.ts

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

package/src/domain/discount.ts

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

package/src/domain/parking.ts

@@ -0,0 +1,13 @@
+/** 停车费单（商圈领域 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

@@ -0,0 +1,14 @@
+/** 会员积分与等级（商圈领域 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

@@ -0,0 +1,10 @@
+/**
+ * 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

@@ -0,0 +1,13 @@
+/**
+ * @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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,16 @@
+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

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

package/tsconfig.build.json

@@ -0,0 +1,15 @@
+{
+  "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

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