@nest-omni/core 4.1.3-20 → 4.1.3-22

package/decorators/field.decorators.d.ts

@@ -7,6 +7,52 @@ interface IFieldOptions {
     nullable?: boolean;
     group?: string[];
     message?: string;
+    skipValidation?: boolean;
+    /**
+     * 字段标签（多语言）
+     * 用于审计日志、验证错误消息、UI 显示等
+     */
+    fieldLabel?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /**
+     * 字段描述（多语言）
+     * 用于 API 文档、审计日志等
+     */
+    fieldDescription?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /**
+     * 示例值
+     * 用于 API 文档
+     */
+    fieldExample?: any;
+    /**
+     * 值标签映射（多语言）
+     * 用于枚举、布尔值的友好显示（审计日志、UI）
+     */
+    valueLabels?: {
+        [value: string]: string | {
+            zh?: string;
+            en?: string;
+            [lang: string]: string | undefined;
+        };
+    };
+    /**
+     * 格式化函数
+     * 用于自定义显示格式（审计日志）
+     * 注意：命名为 displayFormatter 避免与 ApiPropertyOptions.format 冲突
+     */
+    displayFormatter?: (value: any, language?: string) => string;
+    /**
+     * 是否敏感字段
+     * 用于审计日志脱敏
+     */
+    sensitive?: boolean;
 }
 interface INumberFieldOptions extends IFieldOptions {
     min?: number;
@@ -58,8 +104,6 @@ export declare function EnumFieldOptional<TEnum extends object>(getEnum: () => T
 export declare function ClassFieldOptional<TClass extends object>(getClass: () => TClass, options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IClassFieldOptions): PropertyDecorator;
 export declare function EmailField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IEmailFieldOptions): PropertyDecorator;
 export declare function EmailFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IEmailFieldOptions): PropertyDecorator;
-export declare function PhoneField(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
-export declare function PhoneFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IFieldOptions): PropertyDecorator;
 export declare function UUIDField(options?: Omit<ApiPropertyOptions, 'type' | 'format' | 'isArray'> & IFieldOptions): PropertyDecorator;
 export declare function UUIDFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required' | 'isArray'> & IFieldOptions): PropertyDecorator;
 export declare function URLField(options?: Omit<ApiPropertyOptions, 'type'> & IURLFieldOptions & IStringFieldOptions): PropertyDecorator;
@@ -76,4 +120,29 @@ export declare function TimeZoneField(options?: Omit<ApiPropertyOptions, 'type'>
 export declare function TimeZoneFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 export declare function LocaleField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 export declare function LocaleFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
+/**
+ * @Field 装饰器
+ *
+ * 用于只需要元数据（Swagger、审计、UI配置）而不需要验证的字段
+ *
+ * @example
+ * // 只需要 Swagger 文档和审计元数据，不需要验证
+ * @Field({
+ *   label: { zh: '备注', en: 'Remarks' },
+ *   description: { zh: '用户备注信息', en: 'User remarks' },
+ *   ui: { showInList: true, showInDetail: true },
+ * })
+ * remarks: string;
+ */
+export declare function Field(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions & {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+}): PropertyDecorator;
+/**
+ * @FieldOptional 装饰器
+ *
+ * 可选的元数据专用字段
+ */
+export declare function FieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IFieldOptions & {
+    type?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+}): PropertyDecorator;
 export {};

package/decorators/field.decorators.js

@@ -19,8 +19,6 @@ exports.EnumFieldOptional = EnumFieldOptional;
 exports.ClassFieldOptional = ClassFieldOptional;
 exports.EmailField = EmailField;
 exports.EmailFieldOptional = EmailFieldOptional;
-exports.PhoneField = PhoneField;
-exports.PhoneFieldOptional = PhoneFieldOptional;
 exports.UUIDField = UUIDField;
 exports.UUIDFieldOptional = UUIDFieldOptional;
 exports.URLField = URLField;
@@ -37,6 +35,8 @@ exports.TimeZoneField = TimeZoneField;
 exports.TimeZoneFieldOptional = TimeZoneFieldOptional;
 exports.LocaleField = LocaleField;
 exports.LocaleFieldOptional = LocaleFieldOptional;
+exports.Field = Field;
+exports.FieldOptional = FieldOptional;
 const common_1 = require("@nestjs/common");
 const swagger_1 = require("@nestjs/swagger");
 const nestjs_i18n_1 = require("nestjs-i18n");
@@ -46,6 +46,62 @@ const constants_1 = require("../constants");
 const property_decorators_1 = require("./property.decorators");
 const transform_decorators_1 = require("./transform.decorators");
 const validator_decorators_1 = require("./validator.decorators");
+// ========================================
+// Unified Field Options Integration
+// ========================================
+const validation_metadata_helper_1 = require("../common/helpers/validation-metadata-helper");
+// ========================================
+// Helper: Apply Audit Metadata from Unified Options
+// ========================================
+/**
+ * 应用审计元数据装饰器
+ *
+ * 将字段元数据存储到 Reflect metadata，供审计日志系统使用
+ */
+function applyAuditMetadata(options) {
+    return (target, propertyKey) => {
+        // 只有当有相关元数据时才存储
+        if (options.fieldLabel ||
+            options.fieldDescription ||
+            options.valueLabels ||
+            options.displayFormatter ||
+            options.sensitive) {
+            const constructor = target.constructor;
+            const AUDIT_FIELD_OPTIONS_KEY = 'FIELD_AUDIT_OPTIONS';
+            // 获取现有的审计元数据
+            const existingOptions = Reflect.getMetadata(AUDIT_FIELD_OPTIONS_KEY, constructor) || {};
+            // 合并元数据
+            existingOptions[propertyKey] = {
+                label: options.fieldLabel,
+                description: options.fieldDescription,
+                example: options.fieldExample,
+                valueLabels: options.valueLabels,
+                formatter: options.displayFormatter,
+                sensitive: options.sensitive,
+            };
+            // 存储回 Reflect
+            Reflect.defineMetadata(AUDIT_FIELD_OPTIONS_KEY, existingOptions, constructor);
+        }
+    };
+}
+/**
+ * 应用验证元数据装饰器
+ *
+ * 存储验证元数据到 Reflect metadata，供验证错误过滤器使用
+ * 生成友好的多语言错误消息
+ */
+function applyValidationMetadata(options) {
+    return (target, propertyKey) => {
+        // 只有当有相关元数据时才存储
+        if (options.fieldLabel) {
+            (0, validation_metadata_helper_1.setValidationMetadata)(target.constructor, String(propertyKey), {
+                fieldName: String(propertyKey),
+                label: options.fieldLabel,
+                description: options.fieldDescription,
+            });
+        }
+    };
+}
 function NumberField(options = {}) {
     const decorators = [(0, class_transformer_1.Type)(() => Number)];
     if (options.nullable) {
@@ -95,6 +151,10 @@ function NumberField(options = {}) {
             message: (0, nestjs_i18n_1.i18nValidationMessage)('validation.IS_POSITIVE'),
         }));
     }
+    // 应用审计元数据（如果有）
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于友好的错误消息）
+    decorators.push(applyValidationMetadata(options));
     return (0, common_1.applyDecorators)(...decorators);
 }
 function NumberFieldOptional(options = {}) {
@@ -138,6 +198,10 @@ function StringField(options = {}) {
     if (options.toUpperCase) {
         decorators.push((0, transform_decorators_1.ToUpperCase)());
     }
+    // 应用审计元数据（如果有）
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于友好的错误消息）
+    decorators.push(applyValidationMetadata(options));
     return (0, common_1.applyDecorators)(...decorators);
 }
 function StringFieldOptional(options = {}) {
@@ -172,6 +236,10 @@ function BooleanField(options = {}) {
     if (options.swagger !== false) {
         decorators.push((0, swagger_1.ApiProperty)(Object.assign({ type: Boolean }, options)));
     }
+    // 应用审计元数据（如果有）
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于友好的错误消息）
+    decorators.push(applyValidationMetadata(options));
     return (0, common_1.applyDecorators)(...decorators);
 }
 function BooleanFieldOptional(options = {}) {
@@ -245,6 +313,10 @@ function EnumField(getEnum, options = {}) {
     if (options.swagger !== false) {
         decorators.push((0, property_decorators_1.ApiEnumProperty)(getEnum, Object.assign(Object.assign({}, options), { isArray: options.each })));
     }
+    // 应用审计元数据（如果有）
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于友好的错误消息）
+    decorators.push(applyValidationMetadata(options));
     return (0, common_1.applyDecorators)(...decorators);
 }
 // eslint-disable-next-line @typescript-eslint/ban-types
@@ -303,22 +375,6 @@ function EmailField(options = {}) {
 function EmailFieldOptional(options = {}) {
     return (0, common_1.applyDecorators)((0, validator_decorators_1.IsEmptyable)(), EmailField(Object.assign({ required: false }, options)));
 }
-function PhoneField(options = {}) {
-    const decorators = [(0, validator_decorators_1.IsPhoneNumber)(), (0, transform_decorators_1.PhoneNumberSerializer)()];
-    if (options.nullable) {
-        decorators.push((0, validator_decorators_1.IsNullable)());
-    }
-    else {
-        decorators.push((0, class_validator_1.NotEquals)(null));
-    }
-    if (options.swagger !== false) {
-        decorators.push((0, swagger_1.ApiProperty)(Object.assign({ type: String }, options)));
-    }
-    return (0, common_1.applyDecorators)(...decorators);
-}
-function PhoneFieldOptional(options = {}) {
-    return (0, common_1.applyDecorators)((0, validator_decorators_1.IsEmptyable)(), PhoneField(Object.assign({ required: false }, options)));
-}
 function UUIDField(options = {}) {
     const decorators = [
         (0, class_transformer_1.Type)(() => String),
@@ -417,6 +473,10 @@ function DateField(options = {}) {
         const swaggerOptions = Object.assign({ type: Date, example: (_a = options.example) !== null && _a !== void 0 ? _a : new Date() }, options);
         decorators.push((0, swagger_1.ApiProperty)(swaggerOptions));
     }
+    // 应用审计元数据（如果有）
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于友好的错误消息）
+    decorators.push(applyValidationMetadata(options));
     return (0, common_1.applyDecorators)(...decorators);
 }
 function DateFieldOptional(options = {}) {
@@ -504,3 +564,72 @@ function LocaleField(options = {}) {
 function LocaleFieldOptional(options = {}) {
     return (0, common_1.applyDecorators)((0, validator_decorators_1.IsEmptyable)(), LocaleField(Object.assign({ required: false }, options)));
 }
+// ========================================
+// @Field - 元数据专用装饰器
+// ========================================
+/**
+ * @Field 装饰器
+ *
+ * 用于只需要元数据（Swagger、审计、UI配置）而不需要验证的字段
+ *
+ * @example
+ * // 只需要 Swagger 文档和审计元数据，不需要验证
+ * @Field({
+ *   label: { zh: '备注', en: 'Remarks' },
+ *   description: { zh: '用户备注信息', en: 'User remarks' },
+ *   ui: { showInList: true, showInDetail: true },
+ * })
+ * remarks: string;
+ */
+function Field(options = {}) {
+    const decorators = [];
+    // 标准化选项
+    // 添加类型转换（仅用于序列化）
+    const fieldType = options.type || 'string';
+    switch (fieldType) {
+        case 'number':
+            decorators.push((0, class_transformer_1.Type)(() => Number));
+            break;
+        case 'boolean':
+            decorators.push((0, class_transformer_1.Type)(() => Boolean));
+            break;
+        case 'object':
+            decorators.push((0, class_transformer_1.Type)(() => Object));
+            break;
+        case 'array':
+            decorators.push((0, class_transformer_1.Type)(() => Array));
+            if (options.each)
+                decorators.push((0, transform_decorators_1.ToArray)());
+            break;
+        case 'string':
+        default:
+            decorators.push((0, class_transformer_1.Type)(() => String));
+            break;
+    }
+    // Swagger 文档
+    if (options.swagger !== false) {
+        const swaggerType = fieldType === 'array'
+            ? String
+            : fieldType === 'object'
+                ? Object
+                : fieldType === 'boolean'
+                    ? Boolean
+                    : fieldType === 'number'
+                        ? Number
+                        : String;
+        decorators.push((0, swagger_1.ApiProperty)(Object.assign({ type: swaggerType, isArray: fieldType === 'array' || options.each }, options)));
+    }
+    // 应用审计元数据
+    decorators.push(applyAuditMetadata(options));
+    // 应用验证元数据（用于错误消息）
+    decorators.push(applyValidationMetadata(options));
+    return (0, common_1.applyDecorators)(...decorators);
+}
+/**
+ * @FieldOptional 装饰器
+ *
+ * 可选的元数据专用字段
+ */
+function FieldOptional(options = {}) {
+    return (0, common_1.applyDecorators)((0, validator_decorators_1.IsEmptyable)(), Field(Object.assign({ required: false }, options)));
+}

package/decorators/transform.decorators.d.ts

@@ -31,5 +31,3 @@ export declare function ToInt(): PropertyDecorator;
 export declare function ToArray(): PropertyDecorator;
 export declare function ToLowerCase(): PropertyDecorator;
 export declare function ToUpperCase(): PropertyDecorator;
-export declare function S3UrlParser(): PropertyDecorator;
-export declare function PhoneNumberSerializer(): PropertyDecorator;

package/decorators/transform.decorators.js

@@ -6,12 +6,8 @@ exports.ToInt = ToInt;
 exports.ToArray = ToArray;
 exports.ToLowerCase = ToLowerCase;
 exports.ToUpperCase = ToUpperCase;
-exports.S3UrlParser = S3UrlParser;
-exports.PhoneNumberSerializer = PhoneNumberSerializer;
 const class_transformer_1 = require("class-transformer");
-const libphonenumber_js_1 = require("libphonenumber-js");
 const lodash_1 = require("lodash");
-const providers_1 = require("../providers");
 /**
  * @description trim spaces from start and end, replace multiple spaces with one.
  * @example
@@ -108,22 +104,3 @@ function ToUpperCase() {
         toClassOnly: true,
     });
 }
-function S3UrlParser() {
-    return (0, class_transformer_1.Transform)((params) => {
-        const key = params.value;
-        switch (params.type) {
-            case class_transformer_1.TransformationType.CLASS_TO_PLAIN: {
-                return providers_1.GeneratorProvider.getS3PublicUrl(key);
-            }
-            case class_transformer_1.TransformationType.PLAIN_TO_CLASS: {
-                return providers_1.GeneratorProvider.getS3Key(key);
-            }
-            default: {
-                return key;
-            }
-        }
-    });
-}
-function PhoneNumberSerializer() {
-    return (0, class_transformer_1.Transform)((params) => (0, libphonenumber_js_1.parsePhoneNumber)(params.value).number);
-}

package/filters/bad-request.filter.js

@@ -10,9 +10,10 @@ exports.HttpExceptionFilter = void 0;
 const common_1 = require("@nestjs/common");
 const typeorm_1 = require("typeorm");
 const nestjs_i18n_1 = require("nestjs-i18n");
+const validation_metadata_helper_1 = require("../common/helpers/validation-metadata-helper");
 let HttpExceptionFilter = class HttpExceptionFilter {
     catch(exception, host) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         const i18n = nestjs_i18n_1.I18nContext.current(host);
         const ctx = host.switchToHttp();
         const response = ctx.getResponse();
@@ -48,12 +49,26 @@ let HttpExceptionFilter = class HttpExceptionFilter {
             return error;
         };
         if (exception instanceof nestjs_i18n_1.I18nValidationException) {
-            const firstErros = getFirstError(exception.errors[0], exception.errors[0].property);
-            const constraint = Object.values(firstErros.constraints)[0];
+            const firstError = getFirstError(exception.errors[0], exception.errors[0].property);
+            const constraint = Object.values(firstError.constraints)[0];
             const [translationKey, argsString] = constraint.split('|');
             const args = !!argsString ? JSON.parse(argsString) : {};
+            // 获取当前语言
+            const lang = i18n.lang || 'zh';
+            // 在 stringify 之前获取 target
+            // firstError.target 可能是实例而不是构造函数，所以需要获取 constructor
+            let target = ((_e = firstError.target) === null || _e === void 0 ? void 0 : _e.constructor) || firstError.target;
+            if (!target && (firstError === null || firstError === void 0 ? void 0 : firstError.object)) {
+                target = firstError.object.constructor;
+            }
+            // 尝试从验证元数据中获取字段标签
+            const metadata = target ? (0, validation_metadata_helper_1.getValidationMetadata)(target, firstError.property) : undefined;
+            const fieldLabel = metadata
+                ? (0, validation_metadata_helper_1.getFieldLabelForValidation)(metadata, lang)
+                : firstError.property;
+            // 使用字段标签作为 property 参数
             error = i18n.translate(translationKey, {
-                args: Object.assign({ property: firstErros.property, value: firstErros.value, constraints: firstErros.constraints }, args),
+                args: Object.assign({ field: fieldLabel, property: fieldLabel, fieldName: fieldLabel, value: firstError.value, constraints: firstError.constraints }, args),
             });
         }
         const parseJson = {

package/http-client/utils/context-extractor.util.js

@@ -15,6 +15,7 @@ class ContextExtractor {
             const requestId = providers_1.ContextProvider.getRequestId();
             const authUser = providers_1.ContextProvider.getAuthUser();
             const router = providers_1.ContextProvider.getRouter();
+            const source = providers_1.ContextProvider.getSource();
             return {
                 requestId,
                 userId: authUser === null || authUser === void 0 ? void 0 : authUser.uid,
@@ -23,6 +24,7 @@ class ContextExtractor {
                 metadata: {
                     authUser,
                     router,
+                    source, // 添加 source 字段
                 },
                 tags: [],
             };

package/ip-filter/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * IP过滤元数据键名
+ * 用于在路由元数据中存储IP过滤配置
+ */
+export declare const IP_FILTER_KEY = "ip_filter";
+/**
+ * IP过滤选项依赖注入键名
+ */
+export declare const IP_FILTER_OPTIONS = "IP_FILTER_OPTIONS";
+/**
+ * 默认错误消息
+ */
+export declare const DEFAULT_ERROR_MESSAGE = "Access denied: Your IP address is not authorized";
+/**
+ * 默认HTTP状态码
+ */
+export declare const DEFAULT_ERROR_STATUS_CODE = 403;
+/**
+ * 默认优先级
+ */
+export declare const DEFAULT_PRIORITY = 50;

package/ip-filter/constants.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PRIORITY = exports.DEFAULT_ERROR_STATUS_CODE = exports.DEFAULT_ERROR_MESSAGE = exports.IP_FILTER_OPTIONS = exports.IP_FILTER_KEY = void 0;
+/**
+ * IP过滤元数据键名
+ * 用于在路由元数据中存储IP过滤配置
+ */
+exports.IP_FILTER_KEY = 'ip_filter';
+/**
+ * IP过滤选项依赖注入键名
+ */
+exports.IP_FILTER_OPTIONS = 'IP_FILTER_OPTIONS';
+/**
+ * 默认错误消息
+ */
+exports.DEFAULT_ERROR_MESSAGE = 'Access denied: Your IP address is not authorized';
+/**
+ * 默认HTTP状态码
+ */
+exports.DEFAULT_ERROR_STATUS_CODE = 403;
+/**
+ * 默认优先级
+ */
+exports.DEFAULT_PRIORITY = 50;

package/ip-filter/decorators/index.d.ts

@@ -0,0 +1 @@
+export * from './ip-filter.decorator';

package/ip-filter/decorators/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ip-filter.decorator"), exports);

package/ip-filter/decorators/ip-filter.decorator.d.ts

@@ -0,0 +1,58 @@
+import { IpFilterMetadata } from '../interfaces';
+/**
+ * IP过滤装饰器
+ * 用于控制器或方法级别配置IP访问控制
+ *
+ * @example
+ * ```typescript
+ * // 控制器级别
+ * @IpFilter({
+ *   mode: 'whitelist',
+ *   ipRanges: ['192.168.1.0/24', '10.0.0.0/8'],
+ *   priority: 100
+ * })
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 方法级别
+ * @Get()
+ * @IpFilter({
+ *   mode: 'blacklist',
+ *   ipRanges: ['203.0.113.0/24']
+ * })
+ * getData() {}
+ * ```
+ *
+ * @param options IP过滤配置选项
+ */
+export declare const IpFilter: (options: IpFilterMetadata) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * 白名单装饰器（快捷方式）
+ * 仅允许指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpWhitelist(['192.168.1.0/24', '10.0.0.0/8'], 'Office network')
+ * @Get('admin')
+ * adminDashboard() {}
+ * ```
+ *
+ * @param ipRanges 允许的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+export declare const IpWhitelist: (ipRanges: string[], description?: string) => import("@nestjs/common").CustomDecorator<string>;
+/**
+ * 黑名单装饰器（快捷方式）
+ * 禁止指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpBlacklist(['203.0.113.0/24'], 'Blocked malicious IPs')
+ * @Get('sensitive')
+ * sensitiveData() {}
+ * ```
+ *
+ * @param ipRanges 禁止的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+export declare const IpBlacklist: (ipRanges: string[], description?: string) => import("@nestjs/common").CustomDecorator<string>;

package/ip-filter/decorators/ip-filter.decorator.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IpBlacklist = exports.IpWhitelist = exports.IpFilter = void 0;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("../constants");
+/**
+ * IP过滤装饰器
+ * 用于控制器或方法级别配置IP访问控制
+ *
+ * @example
+ * ```typescript
+ * // 控制器级别
+ * @IpFilter({
+ *   mode: 'whitelist',
+ *   ipRanges: ['192.168.1.0/24', '10.0.0.0/8'],
+ *   priority: 100
+ * })
+ * @Controller('admin')
+ * export class AdminController {}
+ *
+ * // 方法级别
+ * @Get()
+ * @IpFilter({
+ *   mode: 'blacklist',
+ *   ipRanges: ['203.0.113.0/24']
+ * })
+ * getData() {}
+ * ```
+ *
+ * @param options IP过滤配置选项
+ */
+const IpFilter = (options) => (0, common_1.SetMetadata)(constants_1.IP_FILTER_KEY, options);
+exports.IpFilter = IpFilter;
+/**
+ * 白名单装饰器（快捷方式）
+ * 仅允许指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpWhitelist(['192.168.1.0/24', '10.0.0.0/8'], 'Office network')
+ * @Get('admin')
+ * adminDashboard() {}
+ * ```
+ *
+ * @param ipRanges 允许的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+const IpWhitelist = (ipRanges, description) => {
+    return (0, exports.IpFilter)({
+        mode: 'whitelist',
+        ipRanges,
+        priority: 100,
+        description,
+    });
+};
+exports.IpWhitelist = IpWhitelist;
+/**
+ * 黑名单装饰器（快捷方式）
+ * 禁止指定的IP范围访问
+ *
+ * @example
+ * ```typescript
+ * @IpBlacklist(['203.0.113.0/24'], 'Blocked malicious IPs')
+ * @Get('sensitive')
+ * sensitiveData() {}
+ * ```
+ *
+ * @param ipRanges 禁止的IP范围列表（CIDR格式）
+ * @param description 规则描述
+ */
+const IpBlacklist = (ipRanges, description) => {
+    return (0, exports.IpFilter)({
+        mode: 'blacklist',
+        ipRanges,
+        priority: 100,
+        description,
+    });
+};
+exports.IpBlacklist = IpBlacklist;

package/ip-filter/guards/index.d.ts

@@ -0,0 +1 @@
+export * from './ip-filter.guard';

package/ip-filter/guards/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ip-filter.guard"), exports);