@tbox.cn/app-module-member 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-member
+
+商圈会员模块：积分查询/扣减/发放/退款、等级（codegen 源）。
+
+## 安装
+
+```sh
+pnpm add @tbox.cn/app-module-member
+```
+
+## 用法
+
+在生成应用中：
+
+```sh
+tbox-app module add @tbox.cn/app-module-member
+```

package/dist/chunk-F6FHBH3N.js

@@ -0,0 +1,160 @@
+// src/server/service.ts
+var InMemoryMemberService = class {
+  balances = /* @__PURE__ */ new Map();
+  levels = /* @__PURE__ */ new Map();
+  idempotentKeys = /* @__PURE__ */ new Set();
+  audit = [];
+  constructor(initial = {}) {
+    for (const [userId, balance] of Object.entries(initial)) {
+      this.balances.set(userId, balance);
+    }
+  }
+  async queryPoints(userId) {
+    return {
+      userId,
+      balance: this.balances.get(userId) ?? 0,
+      level: this.levelOf(userId)
+    };
+  }
+  async queryDiscount(userId) {
+    const level = this.levelOf(userId);
+    const map = {
+      silver: { level: "silver", discount: 0.95 },
+      gold: { level: "gold", discount: 0.9 },
+      platinum: { level: "platinum", discount: 0.85 }
+    };
+    return map[level];
+  }
+  async deductPoints(userId, amount, idempotencyKey) {
+    if (this.idempotentKeys.has(idempotencyKey)) return true;
+    const current = this.balances.get(userId) ?? 0;
+    if (amount <= 0 || current < amount) return false;
+    this.balances.set(userId, current - amount);
+    this.idempotentKeys.add(idempotencyKey);
+    this.audit.push({ action: "deduct", userId, amount, key: idempotencyKey });
+    this.maybeUpgrade(userId);
+    return true;
+  }
+  async refundPoints(userId, amount, idempotencyKey) {
+    if (this.idempotentKeys.has(`refund:${idempotencyKey}`)) return true;
+    const current = this.balances.get(userId) ?? 0;
+    this.balances.set(userId, current + amount);
+    this.idempotentKeys.add(`refund:${idempotencyKey}`);
+    this.audit.push({ action: "refund", userId, amount, key: idempotencyKey });
+    return true;
+  }
+  async awardPoints(userId, amount) {
+    const current = this.balances.get(userId) ?? 0;
+    this.balances.set(userId, current + amount);
+    this.audit.push({ action: "award", userId, amount });
+    this.maybeUpgrade(userId);
+    return true;
+  }
+  levelOf(userId) {
+    const cached = this.levels.get(userId);
+    if (cached) return cached;
+    const balance = this.balances.get(userId) ?? 0;
+    if (balance >= 1e3) return "platinum";
+    if (balance >= 300) return "gold";
+    return "silver";
+  }
+  maybeUpgrade(userId) {
+    const newLevel = this.levelOf(userId);
+    const prev = this.levels.get(userId);
+    this.levels.set(userId, newLevel);
+    if (prev && prev !== newLevel) {
+      this.levelChangeListeners.forEach((fn) => fn({ userId, newLevel }));
+    }
+  }
+  levelChangeListeners = /* @__PURE__ */ new Set();
+  onLevelChange(fn) {
+    this.levelChangeListeners.add(fn);
+  }
+};
+
+// src/server/cards/points/meta.ts
+import { z } from "zod";
+var dataSchema = z.object({
+  userId: z.string(),
+  balance: z.number(),
+  level: z.enum(["silver", "gold", "platinum"])
+});
+var meta = {
+  cardType: "points",
+  dataSchema,
+  allowedTools: ["queryPoints"],
+  displayName: "\u4F1A\u5458\u79EF\u5206\u5361",
+  description: "\u5C55\u793A\u4F1A\u5458\u5F53\u524D\u79EF\u5206\u4F59\u989D\u4E0E\u7B49\u7EA7",
+  sampleData: { userId: "u_1001", balance: 860, level: "gold" },
+  schemaVersion: 1
+};
+var meta_default = meta;
+
+// src/server/tool.ts
+import { createTool } from "@tbox.cn/app-sdk/server";
+import { z as z2 } from "zod";
+function createQueryPointsTool(getMember) {
+  return createTool({
+    id: "queryPoints",
+    description: "\u67E5\u8BE2\u4F1A\u5458\u5F53\u524D\u79EF\u5206\u4F59\u989D\u4E0E\u7B49\u7EA7",
+    inputSchema: z2.object({
+      userId: z2.string().describe("\u4F1A\u5458 userId")
+    }),
+    outputSchema: z2.object({
+      userId: z2.string(),
+      balance: z2.number(),
+      level: z2.enum(["silver", "gold", "platinum"])
+    }),
+    execute: async ({ userId }) => {
+      const member2 = getMember();
+      if (!member2) return { userId, balance: 0, level: "silver" };
+      return member2.queryPoints(userId);
+    }
+  });
+}
+
+// src/server/handler.ts
+function createMemberHandler(ctx) {
+  return {
+    id: "member",
+    handle: async (_action, payload) => {
+      const member2 = ctx.resolveService("member");
+      if (!member2) return { cards: [], text: "\u4F1A\u5458\u670D\u52A1\u4E0D\u53EF\u7528" };
+      const { userId } = payload ?? {};
+      if (!userId) return { cards: [], text: "\u7F3A\u5C11 userId" };
+      const points = await member2.queryPoints(userId);
+      return {
+        cards: [{ cardType: "points", data: points }],
+        text: `\u5F53\u524D\u79EF\u5206 ${points.balance}\uFF0C\u7B49\u7EA7 ${points.level}`
+      };
+    }
+  };
+}
+
+// src/server/index.ts
+var member = new InMemoryMemberService({ u_1001: 860, u_1002: 120 });
+var cards = {
+  points: meta_default
+};
+var serverModule = {
+  cards,
+  register(ctx) {
+    ctx.services.register("member", member);
+    ctx.tools.register(createQueryPointsTool(() => ctx.resolveService("member")));
+    ctx.cards.registerMap(cards);
+    ctx.handlers.register(createMemberHandler(ctx));
+    const mallBus = ctx.bus;
+    mallBus.subscribe("parking.coupon.used", async ({ userId, amount }) => {
+      await member.awardPoints(userId, Math.floor(amount / 10));
+    });
+    member.onLevelChange(({ userId, newLevel }) => {
+      void mallBus.publish("member.level.changed", { userId, newLevel });
+    });
+  }
+};
+
+export {
+  InMemoryMemberService,
+  meta_default,
+  serverModule
+};

package/dist/chunk-OXXT6F5B.js

@@ -0,0 +1,33 @@
+// src/client/cards/points/index.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function PointsCard({ data }) {
+  const levelLabel = {
+    silver: "\u94F6\u5361",
+    gold: "\u91D1\u5361",
+    platinum: "\u94C2\u91D1\u5361"
+  };
+  return /* @__PURE__ */ jsxs("div", { className: "mall-card mall-card--points", children: [
+    /* @__PURE__ */ jsx("div", { className: "mall-card__title", children: "\u4F1A\u5458\u79EF\u5206" }),
+    /* @__PURE__ */ jsx("div", { className: "mall-card__balance", children: data.balance }),
+    /* @__PURE__ */ jsxs("div", { className: "mall-card__meta", children: [
+      levelLabel[data.level],
+      " \xB7 \u7528\u6237 ",
+      data.userId
+    ] })
+  ] });
+}
+
+// src/client/index.ts
+var cards = {
+  points: PointsCard
+};
+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 points: CardComponent;
+    };
+    register(ctx: ClientContext): void;
+};
+
+export { clientModule };

package/dist/client/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { InMemoryMemberService, MemberService, pointsMeta, 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 {
+  InMemoryMemberService,
+  meta_default,
+  serverModule
+} from "./chunk-F6FHBH3N.js";
+import {
+  clientModule
+} from "./chunk-OXXT6F5B.js";
+export {
+  InMemoryMemberService,
+  clientModule,
+  meta_default as pointsMeta,
+  serverModule
+};

package/dist/server/index.d.ts

@@ -0,0 +1,82 @@
+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 { MemberQueryPort, MemberSettlementPort, Points, DiscountRule } from '@tbox.cn/app-contracts-mall';
+
+/**
+ * MemberService：商圈会员完整实现。
+ * extends 契约 Port（保证满足消费方子集约束）；完整接口只在本模块包内。
+ */
+interface MemberService extends MemberQueryPort, MemberSettlementPort {
+    /** 积分变动记录（单测/观测用） */
+    audit: {
+        action: string;
+        userId: string;
+        amount: number;
+        key?: string;
+    }[];
+}
+/** 内存实现（PoC） */
+declare class InMemoryMemberService implements MemberService {
+    private balances;
+    private levels;
+    private idempotentKeys;
+    audit: {
+        action: string;
+        userId: string;
+        amount: number;
+        key?: string;
+    }[];
+    constructor(initial?: Record<string, number>);
+    queryPoints(userId: string): Promise<Points>;
+    queryDiscount(userId: string): Promise<DiscountRule | undefined>;
+    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>;
+    private levelOf;
+    private maybeUpgrade;
+    private levelChangeListeners;
+    onLevelChange(fn: (e: {
+        userId: string;
+        newLevel: 'silver' | 'gold' | 'platinum';
+    }) => void): void;
+}
+
+declare const dataSchema: z.ZodObject<{
+    userId: z.ZodString;
+    balance: z.ZodNumber;
+    level: z.ZodEnum<["silver", "gold", "platinum"]>;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    balance: number;
+    level: "silver" | "gold" | "platinum";
+}, {
+    userId: string;
+    balance: number;
+    level: "silver" | "gold" | "platinum";
+}>;
+declare const meta: CardMeta<typeof dataSchema>;
+
+/** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
+declare const serverModule: {
+    cards: {
+        readonly points: _tbox_cn_app_contracts.CardMeta<zod.ZodObject<{
+            userId: zod.ZodString;
+            balance: zod.ZodNumber;
+            level: zod.ZodEnum<["silver", "gold", "platinum"]>;
+        }, "strip", zod.ZodTypeAny, {
+            userId: string;
+            balance: number;
+            level: "silver" | "gold" | "platinum";
+        }, {
+            userId: string;
+            balance: number;
+            level: "silver" | "gold" | "platinum";
+        }>>;
+    };
+    register(ctx: ServerContext): void;
+};
+
+export { InMemoryMemberService, type MemberService, meta as pointsMeta, serverModule };

package/dist/server/index.js

@@ -0,0 +1,10 @@
+import {
+  InMemoryMemberService,
+  meta_default,
+  serverModule
+} from "../chunk-F6FHBH3N.js";
+export {
+  InMemoryMemberService,
+  meta_default as pointsMeta,
+  serverModule
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tbox.cn/app-module-member",
+  "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/points/index.tsx

@@ -0,0 +1,19 @@
+import type { PointsCardData } from '../../../server/cards/points/meta';
+
+/** 会员积分卡组件 */
+export function PointsCard({ data }: { data: PointsCardData; cardId: string; isHistory: boolean }) {
+  const levelLabel: Record<PointsCardData['level'], string> = {
+    silver: '银卡',
+    gold: '金卡',
+    platinum: '铂金卡',
+  };
+  return (
+    <div className="mall-card mall-card--points">
+      <div className="mall-card__title">会员积分</div>
+      <div className="mall-card__balance">{data.balance}</div>
+      <div className="mall-card__meta">
+        {levelLabel[data.level]} · 用户 {data.userId}
+      </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 { PointsCard } from './cards/points';
+
+/** 客户端卡片组件 map（key 约定 = cardType；CLI sync 装配读取） */
+const cards = {
+  points: PointsCard 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/points/meta.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { CardMeta } from '@tbox.cn/app-contracts';
+
+export const dataSchema = z.object({
+  userId: z.string(),
+  balance: z.number(),
+  level: z.enum(['silver', 'gold', 'platinum']),
+});
+
+export type PointsCardData = z.infer<typeof dataSchema>;
+
+const meta: CardMeta<typeof dataSchema> = {
+  cardType: 'points',
+  dataSchema,
+  allowedTools: ['queryPoints'],
+  displayName: '会员积分卡',
+  description: '展示会员当前积分余额与等级',
+  sampleData: { userId: 'u_1001', balance: 860, level: 'gold' },
+  schemaVersion: 1,
+};
+
+export default meta;

package/src/server/handler.ts

@@ -0,0 +1,24 @@
+import type { HandlerDefinition } from '@tbox.cn/app-sdk/server';
+import type { MemberQueryPort } from '@tbox.cn/app-contracts-mall';
+import type { ServerContext } from '@tbox.cn/app-sdk/server';
+
+/**
+ * member handler：查积分 → 出 points 卡。
+ * 由 scenario / intent 路由按需 dispatch；LLM 路径走 queryPoints tool。
+ */
+export function createMemberHandler(ctx: ServerContext): HandlerDefinition {
+  return {
+    id: 'member',
+    handle: async (_action, payload) => {
+      const member = ctx.resolveService<MemberQueryPort>('member');
+      if (!member) return { cards: [], text: '会员服务不可用' };
+      const { userId } = (payload ?? {}) as { userId?: string };
+      if (!userId) return { cards: [], text: '缺少 userId' };
+      const points = await member.queryPoints(userId);
+      return {
+        cards: [{ cardType: 'points', data: points as unknown as Record<string, unknown> }],
+        text: `当前积分 ${points.balance}，等级 ${points.level}`,
+      };
+    },
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,45 @@
+import type { ServerContext, ServerModule, TypedBus } from '@tbox.cn/app-sdk/server';
+import type { MallEventMap } from '@tbox.cn/app-contracts-mall';
+import { InMemoryMemberService } from './service';
+import pointsMeta from './cards/points/meta';
+import { createQueryPointsTool } from './tool';
+import { createMemberHandler } from './handler';
+
+export { InMemoryMemberService } from './service';
+export type { MemberService } from './service';
+export { default as pointsMeta } from './cards/points/meta';
+
+/**
+ * 模块级单例（B14）：实例在模块包加载时创建，serverModule.register 幂等（重复调用共享状态）。
+ * 服务实例生命周期 = 模块包加载期，而非 register 调用次数。
+ */
+const member = new InMemoryMemberService({ u_1001: 860, u_1002: 120 });
+
+/** 卡片 meta 声明 map（key 约定 = meta.cardType；数据 + 类型源） */
+const cards = {
+  points: pointsMeta,
+} as const;
+
+/** 模块注册入口：自注册闭环（与客户端 clientModule 对称） */
+export const serverModule = {
+  cards,
+  register(ctx: ServerContext): void {
+    ctx.services.register('member', member);
+    ctx.tools.register(createQueryPointsTool(() => ctx.resolveService('member')));
+    ctx.cards.registerMap(cards);
+    ctx.handlers.register(createMemberHandler(ctx));
+
+    // 类型化事件总线：以 MallEventMap 收窄（keyof 约束载荷类型，编译期对齐）
+    const mallBus = ctx.bus as unknown as TypedBus<MallEventMap>;
+
+    // 跨模块异步通知：parking 核销停车券 → member 奖积分（member 不依赖 parking）
+    mallBus.subscribe('parking.coupon.used', async ({ userId, amount }) => {
+      await member.awardPoints(userId, Math.floor(amount / 10));
+    });
+
+    // 等级变更对外发布（member 发事件，其他模块订阅）；publish 为 async（B1，fire-and-forget）
+    member.onLevelChange(({ userId, newLevel }) => {
+      void mallBus.publish('member.level.changed', { userId, newLevel });
+    });
+  },
+} satisfies ServerModule;

package/src/server/service.ts

@@ -0,0 +1,95 @@
+import type { MemberQueryPort, MemberSettlementPort, Points } from '@tbox.cn/app-contracts-mall';
+import type { DiscountRule } from '@tbox.cn/app-contracts-mall';
+
+/**
+ * MemberService：商圈会员完整实现。
+ * extends 契约 Port（保证满足消费方子集约束）；完整接口只在本模块包内。
+ */
+export interface MemberService extends MemberQueryPort, MemberSettlementPort {
+  /** 积分变动记录（单测/观测用） */
+  audit: { action: string; userId: string; amount: number; key?: string }[];
+}
+
+/** 内存实现（PoC） */
+export class InMemoryMemberService implements MemberService {
+  private balances = new Map<string, number>();
+  private levels = new Map<string, 'silver' | 'gold' | 'platinum'>();
+  private idempotentKeys = new Set<string>();
+  audit: { action: string; userId: string; amount: number; key?: string }[] = [];
+
+  constructor(initial: Record<string, number> = {}) {
+    for (const [userId, balance] of Object.entries(initial)) {
+      this.balances.set(userId, balance);
+    }
+  }
+
+  async queryPoints(userId: string): Promise<Points> {
+    return {
+      userId,
+      balance: this.balances.get(userId) ?? 0,
+      level: this.levelOf(userId),
+    };
+  }
+
+  async queryDiscount(userId: string): Promise<DiscountRule | undefined> {
+    const level = this.levelOf(userId);
+    const map: Record<string, DiscountRule> = {
+      silver: { level: 'silver', discount: 0.95 },
+      gold: { level: 'gold', discount: 0.9 },
+      platinum: { level: 'platinum', discount: 0.85 },
+    };
+    return map[level];
+  }
+
+  async deductPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean> {
+    if (this.idempotentKeys.has(idempotencyKey)) return true; // 幂等
+    const current = this.balances.get(userId) ?? 0;
+    if (amount <= 0 || current < amount) return false;
+    this.balances.set(userId, current - amount);
+    this.idempotentKeys.add(idempotencyKey);
+    this.audit.push({ action: 'deduct', userId, amount, key: idempotencyKey });
+    this.maybeUpgrade(userId);
+    return true;
+  }
+
+  async refundPoints(userId: string, amount: number, idempotencyKey: string): Promise<boolean> {
+    if (this.idempotentKeys.has(`refund:${idempotencyKey}`)) return true;
+    const current = this.balances.get(userId) ?? 0;
+    this.balances.set(userId, current + amount);
+    this.idempotentKeys.add(`refund:${idempotencyKey}`);
+    this.audit.push({ action: 'refund', userId, amount, key: idempotencyKey });
+    return true;
+  }
+
+  async awardPoints(userId: string, amount: number): Promise<boolean> {
+    const current = this.balances.get(userId) ?? 0;
+    this.balances.set(userId, current + amount);
+    this.audit.push({ action: 'award', userId, amount });
+    this.maybeUpgrade(userId);
+    return true;
+  }
+
+  private levelOf(userId: string): 'silver' | 'gold' | 'platinum' {
+    const cached = this.levels.get(userId);
+    if (cached) return cached;
+    const balance = this.balances.get(userId) ?? 0;
+    if (balance >= 1000) return 'platinum';
+    if (balance >= 300) return 'gold';
+    return 'silver';
+  }
+
+  private maybeUpgrade(userId: string): void {
+    const newLevel = this.levelOf(userId);
+    const prev = this.levels.get(userId);
+    this.levels.set(userId, newLevel);
+    if (prev && prev !== newLevel) {
+      // 等级变更事件由 serverModule.register 订阅侧转发（保持 service 与 bus 解耦）
+      this.levelChangeListeners.forEach((fn) => fn({ userId, newLevel }));
+    }
+  }
+
+  private levelChangeListeners = new Set<(e: { userId: string; newLevel: 'silver' | 'gold' | 'platinum' }) => void>();
+  onLevelChange(fn: (e: { userId: string; newLevel: 'silver' | 'gold' | 'platinum' }) => void): void {
+    this.levelChangeListeners.add(fn);
+  }
+}

package/src/server/tool.ts

@@ -0,0 +1,31 @@
+import { createTool } from '@tbox.cn/app-sdk/server';
+import { z } from 'zod';
+import type { MemberQueryPort } from '@tbox.cn/app-contracts-mall';
+
+/**
+ * 积分查询工具（LLM function calling；只读查询）。
+ * 经 ToolRegistry 注册，LLM 调用后由 cardResolver（allowedTools 绑定）自动出 points 卡。
+ */
+export function createQueryPointsTool(getMember: () => MemberQueryPort | undefined) {
+  return createTool({
+    id: 'queryPoints',
+    description: '查询会员当前积分余额与等级',
+    inputSchema: z.object({
+      userId: z.string().describe('会员 userId'),
+    }),
+    outputSchema: z.object({
+      userId: z.string(),
+      balance: z.number(),
+      level: z.enum(['silver', 'gold', 'platinum']),
+    }),
+    execute: async ({ userId }: { userId: string }): Promise<{
+      userId: string;
+      balance: number;
+      level: 'silver' | 'gold' | 'platinum';
+    }> => {
+      const member = getMember();
+      if (!member) return { userId, balance: 0, level: 'silver' };
+      return member.queryPoints(userId);
+    },
+  });
+}

package/tbox.component.json

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

package/tests/service.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { createServerContext } from '@tbox.cn/app-sdk/server';
+import { serverModule } from '../src/server/index';
+
+describe('module-member 自注册与积分服务', () => {
+  it('serverModule.register 注册 tool/card/service/handler', () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+
+    expect(ctx.tools.has('queryPoints')).toBe(true);
+    expect(ctx.cards.has('points')).toBe(true);
+    expect(ctx.handlers.has('member')).toBe(true);
+    expect(ctx.resolveService('member')).toBeDefined();
+  });
+
+  it('queryPoints 返回初始积分', async () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+    const member = ctx.resolveService<{ queryPoints(u: string): Promise<{ balance: number; level: string }> }>('member')!;
+    const points = await member.queryPoints('u_1001');
+    expect(points.balance).toBe(860);
+    expect(points.level).toBe('gold');
+  });
+
+  it('deductPoints 幂等（同 idempotencyKey 只扣一次）', async () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+    const member = ctx.resolveService<{ deductPoints(u: string, a: number, k: string): Promise<boolean> }>('member')!;
+
+    expect(await member.deductPoints('u_1001', 100, 'key-1')).toBe(true);
+    expect(await member.deductPoints('u_1001', 100, 'key-1')).toBe(true); // 幂等
+    const after = await ctx.resolveService<{ queryPoints(u: string): Promise<{ balance: number }> }>('member')!.queryPoints('u_1001');
+    expect(after.balance).toBe(760); // 只扣一次
+  });
+
+  it('余额不足扣减失败', async () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+    const member = ctx.resolveService<{ deductPoints(u: string, a: number, k: string): Promise<boolean> }>('member')!;
+    expect(await member.deductPoints('u_1001', 99999, 'key-x')).toBe(false);
+  });
+
+  it('parking.coupon.used 事件 → 奖积分（跨模块解耦）', async () => {
+    const ctx = createServerContext();
+    serverModule.register(ctx);
+    // 模拟 parking 发布事件
+    ctx.bus.emit('parking.coupon.used', { userId: 'u_1002', couponId: 'c_1', amount: 50 });
+    await new Promise((r) => setTimeout(r, 10)); // 等待异步订阅
+    const member = ctx.resolveService<{ queryPoints(u: string): Promise<{ balance: number }> }>('member')!;
+    const after = await member.queryPoints('u_1002');
+    expect(after.balance).toBe(120 + Math.floor(50 / 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';
+  },
+});