@nest-omni/core 4.1.3-10 → 4.1.3-11

package/audit/interfaces/audit.interfaces.d.ts

@@ -1,4 +1,4 @@
-import { AuditOperation, MaskingStrategy, RecordStrategy } from '../enums/audit.enums';
+import { AuditOperation, MaskingStrategy, RecordStrategy, RollbackActionType, ChangeType } from '../enums/audit.enums';
 /**
  * 审计上下文
  */
@@ -124,12 +124,38 @@ export interface AuditConfig {
 /**
  * 实体级别审计配置
  */
+/**
+ * 实体审计配置
+ *
+ * @description
+ * 支持基础审计配置
+ *
+ * @example
+ * ```typescript
+ * @EntityAudit({
+ *   enabled: true,
+ *   excludeFields: ['password'],
+ *   maskFields: ['email', 'phone'],
+ *   templateKey: 'user',
+ * })
+ * ```
+ */
 export interface EntityAuditConfig {
     enabled?: boolean;
     strategy?: RecordStrategy;
     includeFields?: string[];
     excludeFields?: string[];
     maskFields?: string[];
+    /**
+     * 操作模板键前缀
+     * @example 'user' -> 生成 'user.create', 'user.update', 'user.delete'
+     */
+    templateKey?: string;
+    /**
+     * @deprecated 使用 maskFields 代替
+     * 敏感字段列表（别名，用于兼容旧版本）
+     */
+    sensitiveFields?: string[];
 }
 /**
  * 操作级别审计配置
@@ -142,7 +168,25 @@ export interface OperationAuditConfig {
  * 字段显示选项
  */
 export interface FieldDisplayOptions {
-    displayName?: string;
+    /**
+     * 字段标签（支持多语言）
+     * @example
+     * // 单语言
+     * label: '姓名'
+     *
+     * // 多语言
+     * label: { zh: '姓名', en: 'Name' }
+     */
+    label?: string | Record<string, string>;
+    /**
+     * 字段值的多语言标签映射
+     * @example
+     * valueLabels: {
+     *   active: { zh: '激活', en: 'Active' },
+     *   inactive: { zh: '未激活', en: 'Inactive' }
+     * }
+     */
+    valueLabels?: Record<string, Record<string, string>>;
     sensitive?: boolean;
     formatter?: (value: any) => string;
 }
@@ -159,3 +203,97 @@ export interface ControllerAuditOptions {
 export interface MethodAuditOptions {
     enabled?: boolean;
 }
+/**
+ * 变更详情
+ */
+export interface ChangeDetail {
+    fieldName: string;
+    fieldLabels?: Record<string, string>;
+    oldValue: any;
+    newValue: any;
+    displayOldValue?: Record<string, string>;
+    displayNewValue?: Record<string, string>;
+    changeType: ChangeType;
+}
+/**
+ * 回滚操作
+ */
+export interface RollbackAction {
+    type: RollbackActionType;
+    action: string;
+    params: Record<string, any>;
+    order: number;
+    handler?: string;
+}
+/**
+ * 操作模板配置（用于数据库存储）
+ */
+export interface OperationTemplateData {
+    key: string;
+    entityName: string;
+    operation: AuditOperation;
+    nameTemplates: Record<string, string>;
+    descriptionTemplates: Record<string, string>;
+    fieldLabels?: Record<string, Record<string, string>>;
+    valueDisplays?: Record<string, Record<string, Record<string, string>>>;
+}
+/**
+ * 手动操作日志数据
+ */
+export interface ManualOperationData {
+    transactionId: string;
+    operationTemplateKey: string;
+    descriptionParams: Record<string, any>;
+    userId?: string;
+    username?: string;
+    requestIp?: string;
+    rollbackActions?: RollbackAction[];
+}
+/**
+ * 手动日志记录选项（支持三种模式）
+ */
+export interface ManualLogOptions {
+    templateKey?: string;
+    descriptionParams?: Record<string, any>;
+    description?: string | Record<string, string>;
+    descriptionTemplate?: Record<string, string>;
+    userId?: string;
+    username?: string;
+    requestIp?: string;
+    rollbackActions?: RollbackAction[];
+    transactionId?: string;
+    autoCreateTransaction?: boolean;
+}
+/**
+ * 方法审计选项（支持模板和回滚）
+ */
+export interface AuditOperationOptions {
+    templateKey: string;
+    descriptionParams?: (args: any[], result: any, context: any) => Record<string, any>;
+    rollbackActions?: (args: any[], result: any, context: any) => RollbackAction[];
+    autoTransaction?: boolean;
+}
+/**
+ * 增强的实体审计配置（支持多语言）
+ */
+export interface EnhancedEntityAuditConfig extends EntityAuditConfig {
+    templateKey?: string;
+    fieldLabels?: Record<string, Record<string, string>>;
+    valueDisplays?: Record<string, Record<string, Record<string, string>>>;
+}
+/**
+ * 事务描述结果
+ */
+export interface TransactionDescription {
+    operationName: string;
+    description: string;
+    changes: Array<{
+        entityName?: string;
+        entityId?: string;
+        operation?: AuditOperation;
+        type?: string;
+        description: string;
+        details: any;
+        createdAt: Date;
+    }>;
+}

package/audit/services/entity-audit.service.d.ts

@@ -1,7 +1,7 @@
 import { Repository, EntityManager } from 'typeorm';
-import { EntityAuditLogEntity, EntityTransactionEntity } from '../entities';
+import { EntityAuditLogEntity, EntityTransactionEntity, ManualOperationLogEntity } from '../entities';
 import { AuditOperation } from '../enums';
-import { AuditConfig, IAuditStrategy, EntityDifference, RestoreOptions, RestoreResult, PreCheckResult } from '../interfaces';
+import { AuditConfig, IAuditStrategy, EntityDifference, RestoreOptions, RestoreResult, PreCheckResult, ManualOperationData, ChangeDetail, RollbackAction } from '../interfaces';
 import { AuditContextService } from './audit-context.service';
 import { MultiDatabaseService } from './multi-database.service';
 import { PageDto } from '../../common/dto';
@@ -12,13 +12,14 @@ import { AuditLogQueryDto } from '../dto';
 export declare class EntityAuditService {
     private readonly auditLogRepository;
     private readonly transactionRepository;
+    private readonly manualOperationRepository;
     private readonly entityManager;
     private readonly contextService;
     private readonly multiDbService;
     private readonly auditStrategy;
     private readonly config?;
     private readonly auditConnectionName;
-    constructor(auditLogRepository: Repository<EntityAuditLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, entityManager: EntityManager, contextService: AuditContextService, multiDbService: MultiDatabaseService, auditStrategy?: IAuditStrategy, config?: AuditConfig, auditConnectionName?: string);
+    constructor(auditLogRepository: Repository<EntityAuditLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, manualOperationRepository: Repository<ManualOperationLogEntity>, entityManager: EntityManager, contextService: AuditContextService, multiDbService: MultiDatabaseService, auditStrategy?: IAuditStrategy, config?: AuditConfig, auditConnectionName?: string);
     /**
      * 记录实体变更
      */
@@ -91,4 +92,72 @@ export declare class EntityAuditService {
      * 检测冲突
      */
     private detectConflicts;
+    /**
+     * 增强的记录实体变更（支持模板和结构化变更详情）
+     * @param data 审计数据
+     * @returns 审计日志实体
+     */
+    logEntityChangeWithTemplate(data: {
+        entityType: string;
+        entityId: string;
+        operation: AuditOperation;
+        oldValue?: Record<string, any>;
+        newValue?: Record<string, any>;
+        changedFields?: string[];
+        operationTemplateKey?: string;
+        descriptionParams?: Record<string, any>;
+        changeDetails?: ChangeDetail[];
+        rollbackActions?: RollbackAction[];
+        metadata?: Record<string, any>;
+    }): Promise<EntityAuditLogEntity | null>;
+    /**
+     * 记录手动操作
+     * @param data 手动操作数据
+     * @returns 手动操作日志实体
+     */
+    logManualOperation(data: ManualOperationData): Promise<ManualOperationLogEntity>;
+    /**
+     * 在事务中执行操作
+     * @param fn 执行函数
+     * @param options 事务选项
+     * @returns 执���结果
+     */
+    withTransaction<T>(fn: (transactionId: string) => Promise<T>, options?: {
+        userId?: string;
+        username?: string;
+        requestIp?: string;
+        operationTemplateKey?: string;
+        descriptionParams?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<T>;
+    /**
+     * 获取当前事务ID
+     * @returns 当前事务ID或null
+     */
+    getCurrentTransactionId(): Promise<string | null>;
+    /**
+     * 设置当前事务ID
+     * @param transactionId 事务ID
+     */
+    setCurrentTransactionId(transactionId: string | null): Promise<void>;
+    /**
+     * 开始事务
+     * @param userId 用户ID
+     * @param userName 用户名
+     * @param ip IP地址
+     * @param operationTemplateKey 操作模板键
+     * @param descriptionParams 描述参数
+     * @returns 事务ID
+     */
+    beginTransaction(userId?: string, userName?: string, ip?: string, operationTemplateKey?: string, descriptionParams?: Record<string, any>): Promise<string>;
+    /**
+     * 提交事务
+     * @param transactionId 事务ID
+     */
+    commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 回滚事务
+     * @param transactionId 事务ID
+     */
+    rollbackTransaction(transactionId: string): Promise<void>;
 }

package/audit/services/entity-audit.service.js

@@ -36,9 +36,10 @@ const dto_1 = require("../../common/dto");
  * 实体审计服务
  */
 let EntityAuditService = class EntityAuditService {
-    constructor(auditLogRepository, transactionRepository, entityManager, contextService, multiDbService, auditStrategy = new audit_strategy_service_1.DefaultAuditStrategy(), config, auditConnectionName) {
+    constructor(auditLogRepository, transactionRepository, manualOperationRepository, entityManager, contextService, multiDbService, auditStrategy = new audit_strategy_service_1.DefaultAuditStrategy(), config, auditConnectionName) {
         this.auditLogRepository = auditLogRepository;
         this.transactionRepository = transactionRepository;
+        this.manualOperationRepository = manualOperationRepository;
         this.entityManager = entityManager;
         this.contextService = contextService;
         this.multiDbService = multiDbService;
@@ -554,20 +555,223 @@ let EntityAuditService = class EntityAuditService {
         }
         return conflicts;
     }
+    // ========== 新增方法：支持模板和手动操作 ==========
+    /**
+     * 增强的记录实体变更（支持模板和结构化变更详情）
+     * @param data 审计数据
+     * @returns 审计日志实体
+     */
+    logEntityChangeWithTemplate(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g;
+            // 检查是否应该记录
+            if (!this.auditStrategy.shouldRecord(data.entityType, data.operation)) {
+                return null;
+            }
+            // 获取记录策略
+            const recordStrategy = this.auditStrategy.getRecordStrategy(data.entityType, data.operation);
+            if (recordStrategy === enums_1.RecordStrategy.DISABLED) {
+                return null;
+            }
+            // 获取字段过滤器
+            const fieldFilter = this.auditStrategy.getFieldFilter(data.entityType);
+            // 过滤和脱敏字段
+            const filteredOldValue = this.filterAndMaskFields(data.oldValue || {}, fieldFilter);
+            const filteredNewValue = this.filterAndMaskFields(data.newValue || {}, fieldFilter);
+            // 计算变更字段
+            const changedFields = data.changedFields || this.calculateChangedFields(filteredOldValue, filteredNewValue);
+            const changedFieldPaths = this.calculateChangedFieldPaths(filteredOldValue, filteredNewValue);
+            // 获取上下文信息
+            const context = yield this.contextService.getCurrentContext();
+            // 如果没有提供操作模板键，使用默认模板
+            const operationTemplateKey = data.operationTemplateKey || `${data.entityType}.${data.operation}`;
+            // 如果没有提供描述参数，使用实体数据
+            const descriptionParams = data.descriptionParams || Object.assign(Object.assign(Object.assign({}, filteredOldValue), filteredNewValue), { changedFields, changedFieldsCount: changedFields.length });
+            // 创建审计日志
+            const auditLog = this.auditLogRepository.create({
+                entityType: data.entityType,
+                entityId: data.entityId,
+                operation: data.operation,
+                oldValue: filteredOldValue,
+                newValue: filteredNewValue,
+                changedFields,
+                changedFieldPaths: changedFieldPaths.join(','),
+                userId: context.userId || ((_a = data.metadata) === null || _a === void 0 ? void 0 : _a.userId),
+                username: context.username || ((_b = data.metadata) === null || _b === void 0 ? void 0 : _b.username),
+                requestId: context.requestId || ((_c = data.metadata) === null || _c === void 0 ? void 0 : _c.requestId),
+                requestIp: context.requestIp || ((_d = data.metadata) === null || _d === void 0 ? void 0 : _d.requestIp),
+                userAgent: context.userAgent || ((_e = data.metadata) === null || _e === void 0 ? void 0 : _e.userAgent),
+                description: this.generateDescription(data.operation, data.entityType, data.entityId, changedFields),
+                hashChain: ((_g = (_f = this.config) === null || _f === void 0 ? void 0 : _f.security) === null || _g === void 0 ? void 0 : _g.hashChainEnabled)
+                    ? yield this.generateHashChain(data.entityType, data.entityId, filteredNewValue)
+                    : undefined,
+                // 新增字段
+                operationTemplateKey,
+                descriptionParams,
+                changeDetails: data.changeDetails,
+                rollbackActions: data.rollbackActions,
+            });
+            // 保存变更日志
+            const savedLog = yield this.auditLogRepository.save(auditLog);
+            return savedLog;
+        });
+    }
+    /**
+     * 记录手动操作
+     * @param data 手动操作数据
+     * @returns 手动操作日志实体
+     */
+    logManualOperation(data) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 获取上下文信息
+            const context = yield this.contextService.getCurrentContext();
+            const manualLog = this.manualOperationRepository.create({
+                transactionId: data.transactionId,
+                operationTemplateKey: data.operationTemplateKey,
+                descriptionParams: data.descriptionParams,
+                userId: data.userId || context.userId,
+                username: data.username || context.username,
+                requestIp: data.requestIp || context.requestIp,
+                rollbackActions: data.rollbackActions || [],
+            });
+            return yield this.manualOperationRepository.save(manualLog);
+        });
+    }
+    /**
+     * 在事务中执行操作
+     * @param fn 执行函数
+     * @param options 事务选项
+     * @returns 执���结果
+     */
+    withTransaction(fn, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // 获取上下文信息
+            const context = yield this.contextService.getCurrentContext();
+            // 创建事务
+            const transaction = this.transactionRepository.create({
+                description: ((_a = options === null || options === void 0 ? void 0 : options.descriptionParams) === null || _a === void 0 ? void 0 : _a.description) || 'Transaction',
+                status: 'PENDING',
+                entities: [],
+                userId: (options === null || options === void 0 ? void 0 : options.userId) || context.userId,
+                username: (options === null || options === void 0 ? void 0 : options.username) || context.username,
+                requestIp: (options === null || options === void 0 ? void 0 : options.requestIp) || context.requestIp,
+                operationTemplateKey: options === null || options === void 0 ? void 0 : options.operationTemplateKey,
+                descriptionParams: options === null || options === void 0 ? void 0 : options.descriptionParams,
+                metadata: options === null || options === void 0 ? void 0 : options.metadata,
+            });
+            const savedTransaction = yield this.transactionRepository.save(transaction);
+            const transactionId = savedTransaction.id;
+            try {
+                // 设置事务ID到上下文
+                yield this.contextService.setContext(Object.assign(Object.assign({}, context), { transactionId }));
+                // 执行操作
+                const result = yield fn(transactionId);
+                // 提交事务
+                yield this.transactionRepository.update(transactionId, {
+                    status: 'COMMITTED',
+                    completedAt: new Date(),
+                });
+                return result;
+            }
+            catch (error) {
+                // 回滚事务
+                yield this.transactionRepository.update(transactionId, {
+                    status: 'ROLLED_BACK',
+                    completedAt: new Date(),
+                });
+                throw error;
+            }
+        });
+    }
+    /**
+     * 获取当前事务ID
+     * @returns 当前事务ID或null
+     */
+    getCurrentTransactionId() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = yield this.contextService.getCurrentContext();
+            return context.transactionId || null;
+        });
+    }
+    /**
+     * 设置当前事务ID
+     * @param transactionId 事务ID
+     */
+    setCurrentTransactionId(transactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = yield this.contextService.getCurrentContext();
+            yield this.contextService.setContext(Object.assign(Object.assign({}, context), { transactionId }));
+        });
+    }
+    /**
+     * 开始事务
+     * @param userId 用户ID
+     * @param userName 用户名
+     * @param ip IP地址
+     * @param operationTemplateKey 操作模板键
+     * @param descriptionParams 描述参数
+     * @returns 事务ID
+     */
+    beginTransaction(userId, userName, ip, operationTemplateKey, descriptionParams) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 获取上下文信息
+            const context = yield this.contextService.getCurrentContext();
+            // 创建事务
+            const transaction = this.transactionRepository.create({
+                description: (descriptionParams === null || descriptionParams === void 0 ? void 0 : descriptionParams.description) || 'Transaction',
+                status: 'pending',
+                entities: [],
+                userId: userId || context.userId,
+                username: userName || context.username,
+                requestIp: ip || context.requestIp,
+                operationTemplateKey,
+                descriptionParams,
+            });
+            const savedTransaction = yield this.transactionRepository.save(transaction);
+            return savedTransaction.id;
+        });
+    }
+    /**
+     * 提交事务
+     * @param transactionId 事务ID
+     */
+    commitTransaction(transactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.transactionRepository.update(transactionId, {
+                status: 'committed',
+                completedAt: new Date(),
+            });
+        });
+    }
+    /**
+     * 回滚事务
+     * @param transactionId 事务ID
+     */
+    rollbackTransaction(transactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.transactionRepository.update(transactionId, {
+                status: 'rolled_back',
+                completedAt: new Date(),
+            });
+        });
+    }
 };
 exports.EntityAuditService = EntityAuditService;
 exports.EntityAuditService = EntityAuditService = __decorate([
     (0, common_1.Injectable)(),
     __param(0, (0, typeorm_1.InjectRepository)(entities_1.EntityAuditLogEntity)),
     __param(1, (0, typeorm_1.InjectRepository)(entities_1.EntityTransactionEntity)),
-    __param(2, (0, common_1.Inject)('AUDIT_ENTITY_MANAGER')),
-    __param(5, (0, common_1.Optional)()),
-    __param(5, (0, common_1.Inject)('AUDIT_STRATEGY')),
+    __param(2, (0, typeorm_1.InjectRepository)(entities_1.ManualOperationLogEntity)),
+    __param(3, (0, common_1.Inject)('AUDIT_ENTITY_MANAGER')),
     __param(6, (0, common_1.Optional)()),
-    __param(6, (0, common_1.Inject)('AUDIT_CONFIG')),
+    __param(6, (0, common_1.Inject)('AUDIT_STRATEGY')),
     __param(7, (0, common_1.Optional)()),
-    __param(7, (0, common_1.Inject)('AUDIT_CONNECTION_NAME')),
+    __param(7, (0, common_1.Inject)('AUDIT_CONFIG')),
+    __param(8, (0, common_1.Optional)()),
+    __param(8, (0, common_1.Inject)('AUDIT_CONNECTION_NAME')),
     __metadata("design:paramtypes", [typeorm_2.Repository,
+        typeorm_2.Repository,
         typeorm_2.Repository,
         typeorm_2.EntityManager,
         audit_context_service_1.AuditContextService,

package/audit/services/index.d.ts

@@ -3,3 +3,5 @@ export * from './audit-strategy.service';
 export * from './entity-audit.service';
 export * from './transaction-audit.service';
 export * from './multi-database.service';
+export * from './operation-description.service';
+export * from './manual-audit-log.service';

package/audit/services/index.js

@@ -19,3 +19,5 @@ __exportStar(require("./audit-strategy.service"), exports);
 __exportStar(require("./entity-audit.service"), exports);
 __exportStar(require("./transaction-audit.service"), exports);
 __exportStar(require("./multi-database.service"), exports);
+__exportStar(require("./operation-description.service"), exports);
+__exportStar(require("./manual-audit-log.service"), exports);

package/http-client/http-client.module.js

@@ -18,7 +18,6 @@ var HttpClientModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClientModule = void 0;
 const common_1 = require("@nestjs/common");
-const schedule_1 = require("@nestjs/schedule");
 const config_1 = require("@nestjs/config");
 const typeorm_1 = require("@nestjs/typeorm");
 const cache_service_1 = require("../cache/cache.service");
@@ -41,7 +40,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
      * 动态注册HTTP客户端模块
      */
     static forRoot(config = {}) {
-        var _a, _b, _c;
+        var _a, _b;
         // 基础服务提供者
         const baseProviders = [
             {
@@ -87,9 +86,6 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
         if ((_b = (_a = config.logging) === null || _a === void 0 ? void 0 : _a.databaseLogging) === null || _b === void 0 ? void 0 : _b.enabled) {
             dynamicImports.push(typeorm_1.TypeOrmModule.forFeature([entities_1.HttpLogEntity]));
         }
-        if ((_c = config.logCleanup) === null || _c === void 0 ? void 0 : _c.enabled) {
-            dynamicImports.push(schedule_1.ScheduleModule.forRoot());
-        }
         return {
             module: HttpClientModule_1,
             imports: dynamicImports,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-omni/core",
-  "version": "4.1.3-10",
+  "version": "4.1.3-11",
   "description": "A comprehensive NestJS framework for building enterprise-grade applications with best practices",
   "main": "index.js",
   "types": "index.d.ts",

package/redis-lock/lock-heartbeat.service.d.ts

@@ -23,12 +23,12 @@ export declare class LockHeartbeatService implements OnModuleInit, OnModuleDestr
     private heartbeatTimer;
     /**
      * Heartbeat interval in milliseconds
-     * @default 10000 (10 seconds)
+     * @default 5000 (5 seconds) - reduced for faster failure detection
      */
     private readonly heartbeatInterval;
     /**
      * Heartbeat TTL in seconds (3x interval for safety)
-     * @default 30 (30 seconds)
+     * @default 15 (15 seconds) - adjusted to match new interval
      */
     private readonly heartbeatTtl;
     constructor();

package/redis-lock/lock-heartbeat.service.js

@@ -44,14 +44,14 @@ let LockHeartbeatService = LockHeartbeatService_1 = class LockHeartbeatService {
         this.heartbeatTimer = null;
         /**
          * Heartbeat interval in milliseconds
-         * @default 10000 (10 seconds)
+         * @default 5000 (5 seconds) - reduced for faster failure detection
          */
-        this.heartbeatInterval = 10000;
+        this.heartbeatInterval = 5000;
         /**
          * Heartbeat TTL in seconds (3x interval for safety)
-         * @default 30 (30 seconds)
+         * @default 15 (15 seconds) - adjusted to match new interval
          */
-        this.heartbeatTtl = 30;
+        this.heartbeatTtl = 15;
         this.instanceId = this.getInstanceId();
     }
     onModuleInit() {

package/redis-lock/redis-lock.service.d.ts

@@ -69,6 +69,24 @@ export interface LockOptions {
      * @default 0 (no automatic extension)
      */
     autoExtend?: number;
+    /**
+     * Whether to use exponential backoff for retry attempts
+     * If true, retry delay will increase exponentially: retryDelay * 2^(attempt-1)
+     * @default false
+     */
+    useExponentialBackoff?: boolean;
+    /**
+     * Maximum retry delay in milliseconds when using exponential backoff
+     * Ensures retry delay doesn't grow indefinitely
+     * @default 60000 (60 seconds)
+     */
+    maxRetryDelay?: number;
+    /**
+     * Random jitter to add to retry delay in milliseconds
+     * Helps prevent synchronized retries across multiple instances
+     * @default 0 (no jitter)
+     */
+    retryJitter?: number;
 }
 export interface LockResult {
     /**