@dofe/infra-common 0.1.1

package/dist/decorators/tenant/tenant.decorator.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TeamInfo = exports.CurrentTenantMember = exports.CurrentTenant = exports.TenantApi = exports.RequirePermissions = exports.TenantScope = exports.Public = void 0;
+exports.getTeamId = getTeamId;
+const common_1 = require("@nestjs/common");
+const infra_contracts_1 = require("@dofe/infra-contracts");
+const guards_1 = require("@/common/guards");
+const tenant_context_guard_1 = require("@/common/guards/tenant-context.guard");
+const permission_guard_1 = require("@/common/guards/permission.guard");
+/**
+ * 公共端点装饰器 - 标记不需要认证的端点
+ */
+const Public = () => (0, common_1.SetMetadata)(infra_contracts_1.PUBLIC_ENDPOINT_KEY, true);
+exports.Public = Public;
+/**
+ * 租户范围装饰器 - 标记需要租户上下文的端点
+ */
+const TenantScope = () => (0, common_1.SetMetadata)(infra_contracts_1.TENANT_SCOPE_KEY, true);
+exports.TenantScope = TenantScope;
+/**
+ * 要求权限装饰器 - 标记需要特定权限的端点
+ *
+ * @example
+ * ```typescript
+ * @RequirePermissions(PERMISSION.GATEWAY_READ)
+ * async listGateways() { ... }
+ *
+ * @RequirePermissions([PERMISSION.BOT_CREATE, PERMISSION.BOT_UPDATE])
+ * async createOrUpdateBot() { ... }
+ * ```
+ */
+const RequirePermissions = (permissions) => (0, common_1.SetMetadata)(infra_contracts_1.REQUIRE_PERMISSIONS_KEY, Array.isArray(permissions) ? permissions : [permissions]);
+exports.RequirePermissions = RequirePermissions;
+/**
+ * 租户 API 装饰器 - 组合认证、租户上下文和权限检查
+ * 应用于需要租户上下文和权限检查的 API 端点
+ *
+ * @param permissions 需要的权限
+ *
+ * @example
+ * ```typescript
+ * @TenantApi(PERMISSION.GATEWAY_READ)
+ * async listGateways() { ... }
+ * ```
+ */
+const TenantApi = (permissions) => (0, common_1.applyDecorators)((0, exports.TenantScope)(), (0, exports.RequirePermissions)(permissions), (0, common_1.UseGuards)(guards_1.AuthGuard, tenant_context_guard_1.TenantContextGuard, permission_guard_1.PermissionGuard));
+exports.TenantApi = TenantApi;
+/**
+ * 当前租户参数装饰器 - 从请求中提取当前租户 ID
+ *
+ * @example
+ * ```typescript
+ * async list(@CurrentTenant() tenantId: string) { ... }
+ * ```
+ */
+exports.CurrentTenant = (0, common_1.createParamDecorator)((_data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.tenantId;
+});
+/**
+ * 当前租户成员参数装饰器 - 从请求中提取当前租户成员信息
+ *
+ * @example
+ * ```typescript
+ * async getInfo(@CurrentTenantMember() member: TenantMember) { ... }
+ * ```
+ */
+exports.CurrentTenantMember = (0, common_1.createParamDecorator)((_data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return request.tenantMember;
+});
+/**
+ * 当前团队参数装饰器 - 从请求中提取团队上下文
+ * 别名装饰器，与 @CurrentTenant() 提供相同的租户上下文，但语义更偏向"团队"
+ *
+ * @example
+ * ```typescript
+ * async list(@TeamInfo() teamInfo: TeamContext) { ... }
+ * ```
+ */
+exports.TeamInfo = (0, common_1.createParamDecorator)((_data, ctx) => {
+    const request = ctx.switchToHttp().getRequest();
+    return {
+        tenantId: request.tenantId,
+    };
+});
+/**
+ * 从请求中提取团队 ID
+ *
+ * @example
+ * ```typescript
+ * const teamId = getTeamId(req);
+ * ```
+ */
+function getTeamId(request) {
+    return request.tenantId;
+}
+//# sourceMappingURL=tenant.decorator.js.map

package/dist/decorators/tenant/tenant.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant.decorator.js","sourceRoot":"","sources":["../../../src/decorators/tenant/tenant.decorator.ts"],"names":[],"mappings":";;;AAgIA,8BAEC;AAlID,2CAMwB;AACxB,2DAK+B;AAC/B,4CAA4C;AAC5C,+EAA0E;AAC1E,uEAAmE;AAEnE;;GAEG;AACI,MAAM,MAAM,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,qCAAmB,EAAE,IAAI,CAAC,CAAC;AAAtD,QAAA,MAAM,UAAgD;AAEnE;;GAEG;AACI,MAAM,WAAW,GAAG,GAAG,EAAE,CAAC,IAAA,oBAAW,EAAC,kCAAgB,EAAE,IAAI,CAAC,CAAC;AAAxD,QAAA,WAAW,eAA6C;AAErE;;;;;;;;;;;GAWG;AACI,MAAM,kBAAkB,GAAG,CAAC,WAAsC,EAAE,EAAE,CAC3E,IAAA,oBAAW,EACT,yCAAuB,EACvB,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CACzD,CAAC;AAJS,QAAA,kBAAkB,sBAI3B;AAEJ;;;;;;;;;;;GAWG;AACI,MAAM,SAAS,GAAG,CAAC,WAAsC,EAAE,EAAE,CAClE,IAAA,wBAAe,EACb,IAAA,mBAAW,GAAE,EACb,IAAA,0BAAkB,EAAC,WAAW,CAAC,EAC/B,IAAA,kBAAS,EAAC,kBAAS,EAAE,yCAAkB,EAAE,kCAAe,CAAC,CAC1D,CAAC;AALS,QAAA,SAAS,aAKlB;AAEJ;;;;;;;GAOG;AACU,QAAA,aAAa,GAAG,IAAA,6BAAoB,EAC/C,CAAC,KAAc,EAAE,GAAqB,EAAE,EAAE;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;IAChD,OAAO,OAAO,CAAC,QAAQ,CAAC;AAC1B,CAAC,CACF,CAAC;AAEF;;;;;;;GAOG;AACU,QAAA,mBAAmB,GAAG,IAAA,6BAAoB,EACrD,CAAC,KAAc,EAAE,GAAqB,EAAE,EAAE;IACxC,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;IAChD,OAAO,OAAO,CAAC,YAAY,CAAC;AAC9B,CAAC,CACF,CAAC;AAUF;;;;;;;;GAQG;AACU,QAAA,QAAQ,GAAG,IAAA,6BAAoB,EAC1C,CAAC,KAAc,EAAE,GAAqB,EAAe,EAAE;IACrD,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,CAAC;IAChD,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC,CACF,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,SAAS,CAAC,OAA8B;IACtD,OAAQ,OAAe,CAAC,QAAQ,CAAC;AACnC,CAAC"}

package/dist/decorators/transaction/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Transaction Decorators Export
+ * 事务装饰器导出
+ */
+export { Transactional, TransactionalService, getTransactionClient, type TransactionOptions, type TransactionIsolationLevel, } from './transactional.decorator';
+//# sourceMappingURL=index.d.ts.map

package/dist/decorators/transaction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/decorators/transaction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC"}

package/dist/decorators/transaction/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Transaction Decorators Export
+ * 事务装饰器导出
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionClient = exports.TransactionalService = exports.Transactional = void 0;
+var transactional_decorator_1 = require("./transactional.decorator");
+Object.defineProperty(exports, "Transactional", { enumerable: true, get: function () { return transactional_decorator_1.Transactional; } });
+Object.defineProperty(exports, "TransactionalService", { enumerable: true, get: function () { return transactional_decorator_1.TransactionalService; } });
+Object.defineProperty(exports, "getTransactionClient", { enumerable: true, get: function () { return transactional_decorator_1.getTransactionClient; } });
+//# sourceMappingURL=index.js.map

package/dist/decorators/transaction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/decorators/transaction/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,qEAMmC;AALjC,wHAAA,aAAa,OAAA;AACb,+HAAA,oBAAoB,OAAA;AACpB,+HAAA,oBAAoB,OAAA"}

package/dist/decorators/transaction/transactional.decorator.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Transactional Decorator
+ * 事务处理装饰器
+ *
+ * Automatically wraps method execution in a Prisma transaction.
+ * Works with the project's read/write separation architecture.
+ * Supports optional retry mechanism for deadlock and write conflict errors.
+ *
+ * 自动将方法执行包装在 Prisma 事务中。
+ * 与项目的读写分离架构配合工作。
+ * 支持可选的死锁和写冲突错误重试机制。
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class ApiService {
+ *   constructor(private readonly prisma: PrismaService) {}
+ *
+ *   // Basic usage
+ *   @Transactional()
+ *   async createWithOwner(userId: string, data: CreateInput) {
+ *     const data = await this.prisma.write.create({ data });
+ *     return data;
+ *   }
+ *
+ *   // With retry enabled
+ *   @Transactional({ retry: true, maxRetries: 3 })
+ *   async updateCriticalData(id: string, data: UpdateInput) {
+ *     // Automatically retries on deadlock or write conflict
+ *     return this.prisma.write.data.update({ where: { id }, data });
+ *   }
+ *
+ *   // With custom isolation level
+ *   @Transactional({ isolationLevel: 'Serializable', retry: true })
+ *   async transferOwnership(fromId: string, toId: string) {
+ *     // Critical operation requiring serializable isolation
+ *   }
+ * }
+ * ```
+ */
+import { PrismaClient, Prisma } from '@prisma/client';
+/**
+ * Transaction isolation levels
+ * 事务隔离级别
+ */
+export type TransactionIsolationLevel = Prisma.TransactionIsolationLevel;
+/**
+ * Transaction options
+ * 事务选项
+ */
+export interface TransactionOptions {
+    /**
+     * Maximum wait time to acquire a transaction lock (ms)
+     * 获取事务锁的最大等待时间（毫秒）
+     * @default 5000
+     */
+    maxWait?: number;
+    /**
+     * Maximum transaction execution time (ms)
+     * 事务执行的最大时间（毫秒）
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Transaction isolation level
+     * 事务隔离级别
+     */
+    isolationLevel?: TransactionIsolationLevel;
+    /**
+     * Enable retry mechanism for transient failures
+     * 启用瞬态失败的重试机制
+     * @default false
+     */
+    retry?: boolean;
+    /**
+     * Maximum number of retry attempts
+     * 最大重试次数
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Base delay between retries in milliseconds
+     * 重试之间的基础延迟（毫秒）
+     * @default 100
+     */
+    retryDelay?: number;
+    /**
+     * Exponential backoff multiplier
+     * 指数退避倍数
+     * @default 2
+     */
+    retryBackoffMultiplier?: number;
+    /**
+     * Maximum retry delay in milliseconds
+     * 最大重试延迟（毫秒）
+     * @default 5000
+     */
+    maxRetryDelay?: number;
+}
+/**
+ * Transaction result for monitoring
+ * 用于监控的事务结果
+ */
+export interface TransactionResult {
+    success: boolean;
+    duration: number;
+    retryCount: number;
+    error?: Error;
+    methodName: string;
+}
+/**
+ * Transaction context for monitoring
+ * 用于监控的事务上下文
+ */
+export interface TransactionContextData {
+    startTime: number;
+    methodName: string;
+    retryCount: number;
+    sqlCount: number;
+    tablesInvolved: Set<string>;
+}
+/**
+ * Get the current transaction client or undefined if not in a transaction
+ * 获取当前事务客户端，如果不在事务中则返回 undefined
+ */
+export declare function getTransactionClient(context: object): PrismaClient | undefined;
+/**
+ * Get the current transaction context for monitoring
+ * 获取当前事务上下文用于监控
+ */
+export declare function getTransactionContext(context: object): TransactionContextData | undefined;
+/**
+ * Transactional decorator
+ * 事务装饰器
+ *
+ * Wraps the decorated method in a Prisma transaction.
+ * The service class must have a `prisma` property with a `write` client.
+ *
+ * @param options - Transaction options
+ */
+export declare function Transactional(options?: TransactionOptions): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * DbMetricsService interface for loose coupling
+ * 松耦合的 DbMetricsService 接口
+ */
+interface DbMetricsServiceInterface {
+    recordTransactionStart(): {
+        startTime: number;
+        traceId: string;
+    };
+    recordTransactionEnd(ctx: {
+        startTime: number;
+        traceId: string;
+    }, status: 'success' | 'error' | 'rollback', metadata?: {
+        retryCount?: number;
+        methodName?: string;
+        errorType?: string;
+        errorMessage?: string;
+    }): void;
+    isEnabled(): boolean;
+}
+/**
+ * Set the metrics service getter
+ * 设置指标服务获取器
+ *
+ * 应该在应用启动时调用，例如在 AppModule 的 onModuleInit 中
+ */
+export declare function setTransactionMetricsService(getter: () => DbMetricsServiceInterface | undefined): void;
+/**
+ * TransactionalService mixin
+ * 事务服务 Mixin
+ *
+ * Provides helper methods for transaction-aware services.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class ApiService extends TransactionalService {
+ *   constructor(prisma: PrismaService) {
+ *     super(prisma);
+ *   }
+ *
+ *   async create(data: CreateInput) {
+ *     // Uses transaction client if in a transaction, otherwise uses write client
+ *     return this.getWriteClient().create({ data });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class TransactionalService {
+    protected readonly prisma: {
+        write: PrismaClient;
+        read: PrismaClient;
+    };
+    constructor(prisma: {
+        write: PrismaClient;
+        read: PrismaClient;
+    });
+    /**
+     * Get the write client (transaction-aware)
+     * 获取写客户端（事务感知）
+     *
+     * Returns the transaction client if currently in a transaction,
+     * otherwise returns the regular write client.
+     */
+    protected getWriteClient(): PrismaClient;
+    /**
+     * Get the read client
+     * 获取读客户端
+     *
+     * Always returns the read client (transactions are for writes only).
+     */
+    protected getReadClient(): PrismaClient;
+    /**
+     * Get current transaction context for monitoring
+     * 获取当前事务上下文用于监控
+     */
+    protected getTransactionContext(): TransactionContextData | undefined;
+    /**
+     * Record a table access in the current transaction
+     * 在当前事务中记录表访问
+     */
+    protected recordTableAccess(tableName: string): void;
+    /**
+     * Execute a callback within a transaction
+     * 在事务中执行回调
+     *
+     * @param callback - The callback to execute
+     * @param options - Transaction options
+     */
+    protected runInTransaction<T>(callback: (tx: PrismaClient) => Promise<T>, options?: TransactionOptions): Promise<T>;
+}
+export {};
+//# sourceMappingURL=transactional.decorator.d.ts.map

package/dist/decorators/transaction/transactional.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional.decorator.d.ts","sourceRoot":"","sources":["../../../src/decorators/transaction/transactional.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAGtD;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,CAAC,yBAAyB,CAAC;AAoEzE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,yBAAyB,CAAC;IAE3C;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAYD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,GACd,YAAY,GAAG,SAAS,CAE1B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GACd,sBAAsB,GAAG,SAAS,CAIpC;AAuDD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,kBAAuB,IAI1D,QAAQ,MAAM,EACd,aAAa,MAAM,EACnB,YAAY,kBAAkB,wBA0CjC;AAyJD;;;GAGG;AACH,UAAU,yBAAyB;IACjC,sBAAsB,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,oBAAoB,CAClB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAC3C,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,EACxC,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,GACA,IAAI,CAAC;IACR,SAAS,IAAI,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,yBAAyB,GAAG,SAAS,GAClD,IAAI,CAEN;AAuDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,oBAAoB;IAEtC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE;gBAAnD,MAAM,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,YAAY,CAAA;KAAE;IAGxE;;;;;;OAMG;IACH,SAAS,CAAC,cAAc,IAAI,YAAY;IAKxC;;;;;OAKG;IACH,SAAS,CAAC,aAAa,IAAI,YAAY;IAIvC;;;OAGG;IACH,SAAS,CAAC,qBAAqB,IAAI,sBAAsB,GAAG,SAAS;IAIrE;;;OAGG;IACH,SAAS,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAQpD;;;;;;OAMG;cACa,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,CAAC,CAAC;CAmBd"}