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

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/examples/axios-config-extended.example.d.ts

@@ -0,0 +1,17 @@
+import { HttpClientConfig } from '../interfaces/http-client-config.interface';
+/**
+ * axiosConfig 透传配置示例
+ * 展示如何通过 axiosConfig 直接传递 Axios 原生配置
+ */
+export declare function httpAgentExample(): void;
+export declare function redirectAndValidationExample(): void;
+export declare function responseTypeExample(): void;
+export declare function sizeAndRateLimitExample(): void;
+export declare function paramsSerializationExample(): void;
+export declare function formSerializationExample(): void;
+export declare function securityOptionsExample(): void;
+export declare function abortControllerExample(): void;
+export declare function transitionalOptionsExample(): void;
+export declare function progressEventsExample(): void;
+export declare function comprehensiveConfigExample(): HttpClientConfig;
+export declare function environmentSpecificConfig(): HttpClientConfig;