@tbox.cn/app-module-promotion 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,17 @@
+# @tbox.cn/app-module-promotion
+
+商圈营销模块：资格校验、推荐降级链、券卡（codegen 源）。
+
+## 安装
+
+```sh
+pnpm add @tbox.cn/app-module-promotion
+```
+
+## 用法
+
+在生成应用中：
+
+```sh
+tbox-app module add @tbox.cn/app-module-promotion
+```

package/dist/chunk-AD6OLHSM.js

@@ -0,0 +1,86 @@
+// src/server/service.ts
+var InMemoryPromotionService = class {
+  constructor(getMember) {
+    this.getMember = getMember;
+  }
+  getMember;
+  async queryEligibleCoupons(userId) {
+    const member = this.getMember();
+    const points = member ? await member.queryPoints(userId) : { level: "silver" };
+    const coupons = [
+      {
+        couponId: `coupon_${userId}_${points.level}`,
+        title: points.level === "platinum" ? "\u94C2\u91D1\u4E13\u4EAB\u505C\u8F66\u5238" : points.level === "gold" ? "\u91D1\u5361\u505C\u8F66\u5238" : "\u505C\u8F66\u4F18\u60E0\u5238",
+        amount: points.level === "platinum" ? 10 : points.level === "gold" ? 5 : 2,
+        status: "AVAILABLE"
+      }
+    ];
+    return coupons;
+  }
+};
+
+// src/server/cards/coupon/meta.ts
+import { z } from "zod";
+var dataSchema = z.object({
+  couponId: z.string(),
+  title: z.string(),
+  amount: z.number(),
+  status: z.enum(["AVAILABLE", "USED", "EXPIRED"])
+});
+var meta = {
+  cardType: "coupon",
+  dataSchema,
+  allowedTools: [],
+  displayName: "\u4F18\u60E0\u5238\u5361",
+  description: "\u5C55\u793A\u63A8\u8350\u53D1\u653E\u7684\u4F18\u60E0\u5238",
+  sampleData: { couponId: "coupon_u_1_gold", title: "\u91D1\u5361\u505C\u8F66\u5238", amount: 5, status: "AVAILABLE" },
+  schemaVersion: 1
+};
+var meta_default = meta;
+
+// src/server/handler.ts
+function createPromotionHandler(ctx) {
+  return {
+    id: "promotion",
+    handle: async (_action, payload) => {
+      const promotion = ctx.resolveService("promotion");
+      if (!promotion) return { cards: [], text: "\u8425\u9500\u670D\u52A1\u4E0D\u53EF\u7528" };
+      const { userId } = payload ?? {};
+      if (!userId) return { cards: [], text: "\u7F3A\u5C11 userId" };
+      const coupons = await promotion.queryEligibleCoupons(userId);
+      if (coupons.length === 0) return { cards: [], text: "\u6682\u65E0\u53EF\u7528\u4F18\u60E0\u5238" };
+      return {
+        cards: [{ cardType: "coupon", data: coupons[0] }],
+        text: `\u63A8\u8350 ${coupons[0].title}\uFF08\u53EF\u62B5 ${coupons[0].amount} \u5143\uFF09`
+      };
+    }
+  };
+}
+
+// src/server/index.ts
+var currentCtx = null;
+var promotionSingleton = null;
+var cards = {
+  coupon: meta_default
+};
+var serverModule = {
+  cards,
+  register(ctx) {
+    currentCtx = ctx;
+    if (!promotionSingleton) {
+      promotionSingleton = new InMemoryPromotionService(
+        () => currentCtx?.resolveService("member")
+      );
+    }
+    const promotion = promotionSingleton;
+    ctx.services.register("promotion", promotion);
+    ctx.cards.registerMap(cards);
+    ctx.handlers.register(createPromotionHandler(ctx));
+  }
+};
+
+export {
+  InMemoryPromotionService,
+  meta_default,
+  serverModule
+};

package/dist/chunk-LQGF6337.js

@@ -0,0 +1,32 @@
+// src/client/cards/coupon/index.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function CouponCard({ data }) {
+  return /* @__PURE__ */ jsxs("div", { className: "mall-card mall-card--coupon", children: [
+    /* @__PURE__ */ jsx("div", { className: "mall-card__title", children: data.title }),
+    /* @__PURE__ */ jsxs("div", { className: "mall-card__amount", children: [
+      "-",
+      data.amount,
+      " \u5143"
+    ] }),
+    /* @__PURE__ */ jsxs("div", { className: "mall-card__meta", children: [
+      data.couponId,
+      " \xB7 ",
+      data.status
+    ] })
+  ] });
+}
+
+// src/client/index.ts
+var cards = {
+  coupon: CouponCard
+};
+var clientModule = {
+  cards,
+  register(ctx) {
+    ctx.cards.registerMap(cards);
+  }
+};
+
+export {
+  clientModule
+};

package/dist/client/index.d.ts

@@ -0,0 +1,12 @@
+import { CardComponent } from '@tbox.cn/app-contracts';
+import { ClientContext } from '@tbox.cn/app-sdk/client';
+
+/** 模块注册入口：自注册闭环（与服务端 serverModule 对称） */
+declare const clientModule: {
+    cards: {
+        readonly coupon: CardComponent;
+    };
+    register(ctx: ClientContext): void;
+};
+
+export { clientModule };

package/dist/client/index.js

@@ -0,0 +1,6 @@
+import {
+  clientModule
+} from "../chunk-LQGF6337.js";
+export {
+  clientModule
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { InMemoryPromotionService, couponMeta, serverModule } from './server/index.js';
+export { clientModule } from './client/index.js';
+import '@tbox.cn/app-contracts';
+import 'zod';
+import '@tbox.cn/app-sdk/server';
+import '@tbox.cn/app-contracts-mall';
+import '@tbox.cn/app-sdk/client';

package/dist/index.js

@@ -0,0 +1,14 @@
+import {
+  InMemoryPromotionService,
+  meta_default,
+  serverModule
+} from "./chunk-AD6OLHSM.js";
+import {
+  clientModule
+} from "./chunk-LQGF6337.js";
+export {
+  InMemoryPromotionService,
+  clientModule,
+  meta_default as couponMeta,
+  serverModule
+};

package/dist/server/index.d.ts

@@ -0,0 +1,62 @@
+import * as _tbox_cn_app_contracts from '@tbox.cn/app-contracts';
+import { CardMeta } from '@tbox.cn/app-contracts';
+import * as zod from 'zod';
+import { z } from 'zod';
+import { ServerContext } from '@tbox.cn/app-sdk/server';
+import { PromotionQueryPort, MemberQueryPort, Coupon } from '@tbox.cn/app-contracts-mall';
+
+/** PromotionService：营销资格与发券 */
+interface PromotionService extends PromotionQueryPort {
+}
+/**
+ * 资格校验 + 推荐降级链（001 安全铁律：模型只读，发券为写入需确认——PoC 只做查询资格）。
+ * 通过注入 getMember 访问会员数据，不依赖 member 实现包（结构类型子集接口）。
+ */
+declare class InMemoryPromotionService implements PromotionService {
+    private getMember;
+    constructor(getMember: () => MemberQueryPort | undefined);
+    queryEligibleCoupons(userId: string): Promise<Coupon[]>;
+}
+
+declare const dataSchema: z.ZodObject<{
+    couponId: z.ZodString;
+    title: z.ZodString;
+    amount: z.ZodNumber;
+    status: z.ZodEnum<["AVAILABLE", "USED", "EXPIRED"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "AVAILABLE" | "USED" | "EXPIRED";
+    couponId: string;
+    title: string;
+    amount: number;
+}, {
+    status: "AVAILABLE" | "USED" | "EXPIRED";
+    couponId: string;
+    title: string;
+    amount: number;
+}>;
+declare const meta: CardMeta<typeof dataSchema>;
+
+/** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
+declare const serverModule: {
+    cards: {
+        readonly coupon: _tbox_cn_app_contracts.CardMeta<zod.ZodObject<{
+            couponId: zod.ZodString;
+            title: zod.ZodString;
+            amount: zod.ZodNumber;
+            status: zod.ZodEnum<["AVAILABLE", "USED", "EXPIRED"]>;
+        }, "strip", zod.ZodTypeAny, {
+            status: "AVAILABLE" | "USED" | "EXPIRED";
+            couponId: string;
+            title: string;
+            amount: number;
+        }, {
+            status: "AVAILABLE" | "USED" | "EXPIRED";
+            couponId: string;
+            title: string;
+            amount: number;
+        }>>;
+    };
+    register(ctx: ServerContext): void;
+};
+
+export { InMemoryPromotionService, meta as couponMeta, serverModule };

package/dist/server/index.js

@@ -0,0 +1,10 @@
+import {
+  InMemoryPromotionService,
+  meta_default,
+  serverModule
+} from "../chunk-AD6OLHSM.js";
+export {
+  InMemoryPromotionService,
+  meta_default as couponMeta,
+  serverModule
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tbox.cn/app-module-promotion",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "商圈营销模块：资格校验、推荐降级链、券卡（codegen 源）。",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    }
+  },
+  "dependencies": {
+    "@tbox.cn/app-sdk": "^0.1.0",
+    "@tbox.cn/app-contracts": "^0.1.0",
+    "@tbox.cn/app-contracts-mall": "^0.1.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.24.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "vitest": "^4.1.4",
+    "zod": "^3.24.0",
+    "tsup": "^8.0.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tests",
+    "tbox.component.json",
+    "tsconfig.json",
+    "tsup.config.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
+  }
+}

package/src/client/cards/coupon/index.tsx

@@ -0,0 +1,12 @@
+import type { CouponCardData } from '../../../server/cards/coupon/meta';
+
+/** 优惠券卡组件 */
+export function CouponCard({ data }: { data: CouponCardData; cardId: string; isHistory: boolean }) {
+  return (
+    <div className="mall-card mall-card--coupon">
+      <div className="mall-card__title">{data.title}</div>
+      <div className="mall-card__amount">-{data.amount} 元</div>
+      <div className="mall-card__meta">{data.couponId} · {data.status}</div>
+    </div>
+  );
+}

package/src/client/index.ts

@@ -0,0 +1,16 @@
+import type { CardComponent } from '@tbox.cn/app-contracts';
+import type { ClientContext, ClientModule } from '@tbox.cn/app-sdk/client';
+import { CouponCard } from './cards/coupon';
+
+/** 客户端卡片组件 map（key 约定 = cardType；CLI sync 装配读取） */
+const cards = {
+  coupon: CouponCard as CardComponent,
+} as const;
+
+/** 模块注册入口：自注册闭环（与服务端 serverModule 对称） */
+export const clientModule = {
+  cards,
+  register(ctx: ClientContext): void {
+    ctx.cards.registerMap(cards);
+  },
+} satisfies ClientModule;

package/src/index.ts

@@ -0,0 +1,6 @@
+/**
+ * 模块主入口（package.json exports "." 指向）。
+ * 消费方通常走 ./server / ./client 子路径；主入口聚合导出便于直接引用。
+ */
+export * from './server';
+export * from './client';

package/src/server/cards/coupon/meta.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { CardMeta } from '@tbox.cn/app-contracts';
+
+export const dataSchema = z.object({
+  couponId: z.string(),
+  title: z.string(),
+  amount: z.number(),
+  status: z.enum(['AVAILABLE', 'USED', 'EXPIRED']),
+});
+
+export type CouponCardData = z.infer<typeof dataSchema>;
+
+const meta: CardMeta<typeof dataSchema> = {
+  cardType: 'coupon',
+  dataSchema,
+  allowedTools: [],
+  displayName: '优惠券卡',
+  description: '展示推荐发放的优惠券',
+  sampleData: { couponId: 'coupon_u_1_gold', title: '金卡停车券', amount: 5, status: 'AVAILABLE' },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/handler.ts

@@ -0,0 +1,22 @@
+import type { HandlerDefinition } from '@tbox.cn/app-sdk/server';
+import type { PromotionQueryPort } from '@tbox.cn/app-contracts-mall';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+
+/** promotion handler：查询可领券 → 出 coupon 卡 */
+export function createPromotionHandler(ctx: ServerContext): HandlerDefinition {
+  return {
+    id: 'promotion',
+    handle: async (_action, payload) => {
+      const promotion = ctx.resolveService<PromotionQueryPort>('promotion');
+      if (!promotion) return { cards: [], text: '营销服务不可用' };
+      const { userId } = (payload ?? {}) as { userId?: string };
+      if (!userId) return { cards: [], text: '缺少 userId' };
+      const coupons = await promotion.queryEligibleCoupons(userId);
+      if (coupons.length === 0) return { cards: [], text: '暂无可用优惠券' };
+      return {
+        cards: [{ cardType: 'coupon', data: coupons[0] as unknown as Record<string, unknown> }],
+        text: `推荐 ${coupons[0].title}（可抵 ${coupons[0].amount} 元）`,
+      };
+    },
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,39 @@
+import type { ServerContext, ServerModule } from '@tbox.cn/app-sdk/server';
+import type { MemberQueryPort } from '@tbox.cn/app-contracts-mall';
+import { InMemoryPromotionService } from './service';
+import couponMeta from './cards/coupon/meta';
+import { createPromotionHandler } from './handler';
+
+export { InMemoryPromotionService } from './service';
+export { default as couponMeta } from './cards/coupon/meta';
+
+/**
+ * 模块级单例（B14）：实例在首次 register 时创建，重复调用复用同一实例（状态共享）。
+ * member 查询经可变 currentCtx 引用解析到"最近注册的 ctx"——运行期（handle/事件回调）调用
+ * resolveService（注册期纯净），测试多 ctx 场景也正确。
+ */
+let currentCtx: ServerContext | null = null;
+let promotionSingleton: InMemoryPromotionService | null = null;
+
+/** 卡片 meta 声明 map（key 约定 = meta.cardType；数据 + 类型源） */
+const cards = {
+  coupon: couponMeta,
+} as const;
+
+/** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
+export const serverModule = {
+  cards,
+  register(ctx: ServerContext): void {
+    currentCtx = ctx;
+    if (!promotionSingleton) {
+      promotionSingleton = new InMemoryPromotionService(() =>
+        currentCtx?.resolveService<MemberQueryPort>('member'),
+      );
+    }
+    const promotion = promotionSingleton;
+
+    ctx.services.register('promotion', promotion);
+    ctx.cards.registerMap(cards);
+    ctx.handlers.register(createPromotionHandler(ctx));
+  },
+} satisfies ServerModule;

package/src/server/service.ts

@@ -0,0 +1,29 @@
+import type { Coupon } from '@tbox.cn/app-contracts-mall';
+import type { MemberQueryPort, PromotionQueryPort } from '@tbox.cn/app-contracts-mall';
+
+/** PromotionService：营销资格与发券 */
+export interface PromotionService extends PromotionQueryPort {}
+
+/**
+ * 资格校验 + 推荐降级链（001 安全铁律：模型只读，发券为写入需确认——PoC 只做查询资格）。
+ * 通过注入 getMember 访问会员数据，不依赖 member 实现包（结构类型子集接口）。
+ */
+export class InMemoryPromotionService implements PromotionService {
+  constructor(private getMember: () => MemberQueryPort | undefined) {}
+
+  async queryEligibleCoupons(userId: string): Promise<Coupon[]> {
+    const member = this.getMember();
+    const points = member ? await member.queryPoints(userId) : { level: 'silver' as const };
+
+    // 推荐降级链：按会员等级降级推荐券面额
+    const coupons: Coupon[] = [
+      {
+        couponId: `coupon_${userId}_${points.level}`,
+        title: points.level === 'platinum' ? '铂金专享停车券' : points.level === 'gold' ? '金卡停车券' : '停车优惠券',
+        amount: points.level === 'platinum' ? 10 : points.level === 'gold' ? 5 : 2,
+        status: 'AVAILABLE',
+      },
+    ];
+    return coupons;
+  }
+}

package/tbox.component.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "name": "module-promotion",
+  "version": "0.1.0",
+  "kind": "business",
+  "risk": { "level": "low", "writeBoundary": "source" },
+  "distribution": { "defaultMode": "codegen" },
+  "contributes": {
+    "handlers": ["promotion"],
+    "tools": [],
+    "cards": [{ "cardType": "coupon", "schemaVersion": 1 }],
+    "routes": [],
+    "pages": [],
+    "tabs": []
+  },
+  "dependencies": {
+    "modules": [{ "id": "contracts-mall", "required": true }]
+  },
+  "env": []
+}

package/tests/service.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import { createServerContext } from '@tbox.cn/app-sdk/server';
+import { serverModule } from '../src/server/index';
+
+describe('module-promotion 资格校验与降级链', () => {
+  it('serverModule.register 注册 card/service/handler', () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+    expect(ctx.cards.has('coupon')).toBe(true);
+    expect(ctx.handlers.has('promotion')).toBe(true);
+    expect(ctx.resolveService('promotion')).toBeDefined();
+  });
+
+  it('降级链：silver → 2 元券 / gold → 5 元券 / platinum → 10 元券', async () => {
+    const ctx = createServerContext();
+    // stub member 供 promotion 查询等级
+    ctx.services.register('member', {
+      queryPoints: async (userId: string) => {
+        const level = userId === 'u_gold' ? 'gold' : userId === 'u_platinum' ? 'platinum' : 'silver';
+        return { userId, balance: 100, level: level as 'silver' | 'gold' | 'platinum' };
+      },
+      queryDiscount: async () => undefined,
+    });
+    serverModule.register(ctx);
+    const promotion = ctx.resolveService<{ queryEligibleCoupons(u: string): Promise<{ amount: number }[]> }>('promotion')!;
+
+    expect((await promotion.queryEligibleCoupons('u_silver'))[0].amount).toBe(2);
+    expect((await promotion.queryEligibleCoupons('u_gold'))[0].amount).toBe(5);
+    expect((await promotion.queryEligibleCoupons('u_platinum'))[0].amount).toBe(10);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "types": ["node"]
+  },
+  "include": ["src", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,29 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    'server/index': 'src/server/index.ts',
+    'client/index': 'src/client/index.ts',
+  },
+  format: ['esm'],
+  target: 'node20',
+  platform: 'node',
+  outDir: 'dist',
+  clean: true,
+  sourcemap: false,
+  dts: true,
+  external: [
+    '@tbox.cn/app-sdk',
+    '@tbox.cn/app-contracts',
+    '@tbox.cn/app-contracts-mall',
+    'react',
+    'react-dom',
+    'zod',
+    '@mastra/core',
+    'express',
+  ],
+  esbuildOptions(options) {
+    options.jsx = 'automatic';
+  },
+});