@nest-omni/core 4.1.3-3 → 4.1.3-31

package/decorators/examples/field-i18n.example.js

@@ -0,0 +1,478 @@
+"use strict";
+/**
+ * 字段装饰器 i18n 翻译使用示例
+ *
+ * 本示例演示如何使用 fieldI18n 选项通过 i18n key 进行多语言转换
+ *
+ * 注意：此示例文件仅供参考，展示如何使用 fieldI18n 选项。
+ * 如果使用 TypeScript 5+ 的新装饰器语法，需要确保 tsconfig.json 中
+ * "experimentalDecorators" 设置为 true。
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegisterUserDto = exports.MixedDto = exports.PureLabelDto = exports.PureI18nDto = exports.UpdateUserDto = exports.CreateProductDto = exports.CreateUserDto = void 0;
+const field_decorators_1 = require("../field.decorators");
+// ============================================
+// 步骤 1: 配置 i18n 翻译函数
+// ============================================
+/**
+ * 在应用启动时（如 app.module.ts 或 main.ts）配置 i18n 翻译函数
+ *
+ * @example
+ * // app.module.ts
+ * import { setI18nTranslate } from '@your-lib/core';
+ *
+ *@Module({
+ *   imports: [
+ *     ConfigModule.forRoot(),
+ *     I18nModule.forRoot({
+ *       fallbackLanguage: 'en',
+ *       loader: TranslationsLoader({
+ *         config: {
+ *           defaultLanguage: 'zh',
+ *           languages: ['zh', 'en'],
+ *           types: ['validation', 'field'],
+ *         },
+ *       }),
+ *     }),
+ *   ],
+ *   providers: [AppService],
+ * })
+ * export class AppModule implements OnModuleInit {
+ *   constructor(private readonly i18n: I18nService) {}
+ *
+ *   async onModuleInit() {
+ *     // 设置全局 i18n 翻译函数
+ *     setI18nTranslate((key, options) => this.i18n.translate(key, options));
+ *   }
+ * }
+ */
+// ============================================
+// 步骤 2: 在翻译文件中定义字段标签
+// ============================================
+/**
+ * 翻译文件结构示例 (src/i18n/zh.json):
+ *
+ * {
+ *   "field": {
+ *     "user": {
+ *       "username": "用户名",
+ *       "email": "邮箱",
+ *       "phone": "手机号",
+ *       "role": "角色",
+ *       "status": "状态",
+ *       "description": "个人简介"
+ *     },
+ *     "product": {
+ *       "name": "产品名称",
+ *       "price": "价格",
+ *       "stock": "库存",
+ *       "status": "产品状态"
+ *     }
+ *   },
+ *   "field.value": {
+ *     "user.role": {
+ *       "user": "普通用户",
+ *       "admin": "管理员",
+ *       "vip": "VIP用户"
+ *     },
+ *     "user.status": {
+ *       "active": "正常",
+ *       "inactive": "未激活",
+ *       "suspended": "已暂停"
+ *     }
+ *   }
+ * }
+ *
+ * 翻译文件结构示例 (src/i18n/en.json):
+ *
+ * {
+ *   "field": {
+ *     "user": {
+ *       "username": "Username",
+ *       "email": "Email",
+ *       "phone": "Phone Number",
+ *       "role": "Role",
+ *       "status": "Status",
+ *       "description": "Bio"
+ *     },
+ *     "product": {
+ *       "name": "Product Name",
+ *       "price": "Price",
+ *       "stock": "Stock",
+ *       "status": "Product Status"
+ *     }
+ *   },
+ *   "field.value": {
+ *     "user.role": {
+ *       "user": "User",
+ *       "admin": "Administrator",
+ *       "vip": "VIP User"
+ *     },
+ *     "user.status": {
+ *       "active": "Active",
+ *       "inactive": "Inactive",
+ *       "suspended": "Suspended"
+ *     }
+ *   }
+ * }
+ */
+// ============================================
+// 步骤 3: 在 DTO 中使用 fieldI18n
+// ============================================
+/**
+ * 用户 DTO - 使用 i18n key
+ */
+class CreateUserDto {
+}
+exports.CreateUserDto = CreateUserDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 3,
+        maxLength: 20,
+        fieldI18n: 'field.user.username',
+        // 注意: 如果同时提供 fieldI18n 和 fieldLabel，fieldLabel 优先级更高
+        // fieldLabel: { zh: '用户名', en: 'Username' },
+    }),
+    __metadata("design:type", String)
+], CreateUserDto.prototype, "username", void 0);
+__decorate([
+    (0, field_decorators_1.StringField)({
+        fieldI18n: 'field.user.email',
+    }),
+    __metadata("design:type", String)
+], CreateUserDto.prototype, "email", void 0);
+__decorate([
+    (0, field_decorators_1.StringFieldOptional)({
+        maxLength: 11,
+        fieldI18n: 'field.user.phone',
+    }),
+    __metadata("design:type", String)
+], CreateUserDto.prototype, "phone", void 0);
+__decorate([
+    (0, field_decorators_1.StringFieldOptional)({
+        maxLength: 500,
+        fieldI18n: 'field.user.description',
+    }),
+    __metadata("design:type", String)
+], CreateUserDto.prototype, "description", void 0);
+__decorate([
+    (0, field_decorators_1.BooleanFieldOptional)({
+        fieldI18n: 'field.user.emailVerified',
+        valueLabels: {
+            // valueLabels 也支持 i18n key
+            true: 'field.user.emailVerified.yes',
+            false: 'field.user.emailVerified.no',
+            // 或者直接使用多语言对象
+            // true: { zh: '已验证', en: 'Verified' },
+            // false: { zh: '未验证', en: 'Not Verified' },
+        },
+    }),
+    __metadata("design:type", Boolean)
+], CreateUserDto.prototype, "emailVerified", void 0);
+/**
+ * 产品 DTO - 使用 i18n key
+ */
+class CreateProductDto {
+}
+exports.CreateProductDto = CreateProductDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 1,
+        maxLength: 200,
+        fieldI18n: 'field.product.name',
+    }),
+    __metadata("design:type", String)
+], CreateProductDto.prototype, "name", void 0);
+__decorate([
+    (0, field_decorators_1.NumberField)({
+        min: 0,
+        fieldI18n: 'field.product.price',
+    }),
+    __metadata("design:type", Number)
+], CreateProductDto.prototype, "price", void 0);
+__decorate([
+    (0, field_decorators_1.NumberField)({
+        min: 0,
+        fieldI18n: 'field.product.stock',
+    }),
+    __metadata("design:type", Number)
+], CreateProductDto.prototype, "stock", void 0);
+// ============================================
+// 步骤 4: 枚举字段的 i18n 使用
+// ============================================
+var UserRole;
+(function (UserRole) {
+    UserRole["USER"] = "user";
+    UserRole["ADMIN"] = "admin";
+    UserRole["VIP"] = "vip";
+})(UserRole || (UserRole = {}));
+var UserStatus;
+(function (UserStatus) {
+    UserStatus["ACTIVE"] = "active";
+    UserStatus["INACTIVE"] = "inactive";
+    UserStatus["SUSPENDED"] = "suspended";
+})(UserStatus || (UserStatus = {}));
+/**
+ * 用户更新 DTO - 枚举字段使用 i18n
+ */
+class UpdateUserDto {
+}
+exports.UpdateUserDto = UpdateUserDto;
+__decorate([
+    (0, field_decorators_1.EnumField)(() => UserRole, {
+        fieldI18n: 'field.user.role',
+        valueLabels: {
+            // 使用 i18n key 指向枚举值的翻译
+            [UserRole.USER]: 'field.value.user.role.user',
+            [UserRole.ADMIN]: 'field.value.user.role.admin',
+            [UserRole.VIP]: 'field.value.user.role.vip',
+        },
+    }),
+    __metadata("design:type", String)
+], UpdateUserDto.prototype, "role", void 0);
+__decorate([
+    (0, field_decorators_1.EnumField)(() => UserStatus, {
+        fieldI18n: 'field.user.status',
+        valueLabels: {
+            [UserStatus.ACTIVE]: 'field.value.user.status.active',
+            [UserStatus.INACTIVE]: 'field.value.user.status.inactive',
+            [UserStatus.SUSPENDED]: 'field.value.user.status.suspended',
+        },
+    }),
+    __metadata("design:type", String)
+], UpdateUserDto.prototype, "status", void 0);
+// ============================================
+// 步骤 5: 在验证错误过滤器中使用 i18n
+// ============================================
+/**
+ * 验证错误过滤器示例
+ *
+ * @example
+ * import { getValidationMetadata, getFieldLabelForValidation } from '@your-lib/core';
+ *
+ * @Catch(ValidationError)
+ * export class ValidationErrorFilter implements ExceptionFilter {
+ *   catch(exception: ValidationError, host: ArgumentsHost) {
+ *     const ctx = host.switchToHttp();
+ *     const response = ctx.getResponse<Response>();
+ *     const request = ctx.getRequest<Request>();
+ *     const language = request.headers['accept-language'] || 'zh';
+ *
+ *     const errors = exception.errors.map(error => {
+ *       const metadata = getValidationMetadata(error.target.constructor, error.property);
+ *       const fieldLabel = getFieldLabelForValidation(metadata, language);
+ *
+ *       // 如果 fieldLabel 是 i18n key，需要翻译
+ *       const displayLabel = fieldLabel.includes('.')
+ *         ? this.i18n.translate(fieldLabel, { lang: language })
+ *         : fieldLabel;
+ *
+ *       return {
+ *         field: error.property,
+ *         fieldLabel: displayLabel,
+ *         constraints: error.constraints,
+ *       };
+ *     });
+ *
+ *     response.status(400).json({
+ *       statusCode: 400,
+ *       message: 'Validation failed',
+ *       errors,
+ *     });
+ *   }
+ * }
+ */
+// ============================================
+// 步骤 6: 在审计日志中使用 i18n
+// ============================================
+/**
+ * 审计日志服务示例
+ *
+ * @example
+ * import { getAuditMetadata } from '@your-lib/core';
+ *
+ * @Injectable()
+ * export class AuditService {
+ *   constructor(private readonly i18n: I18nService) {}
+ *
+ *   async logFieldChange(
+ *     entity: any,
+ *     field: string,
+ *     oldValue: any,
+ *     newValue: any,
+ *     language: string = 'zh',
+ *   ) {
+ *     const metadata = getAuditMetadata(entity.constructor, field);
+ *
+ *     // 翻译字段标签
+ *     let fieldLabel = metadata?.label || field;
+ *     if (typeof fieldLabel === 'string' && fieldLabel.includes('.')) {
+ *       fieldLabel = await this.i18n.translate(fieldLabel, { lang: language });
+ *     } else if (typeof fieldLabel === 'object') {
+ *       fieldLabel = fieldLabel[language] || fieldLabel.zh || fieldLabel.en;
+ *     }
+ *
+ *     // 翻译枚举值
+ *     const valueLabels = metadata?.valueLabels;
+ *     const displayOldValue = valueLabels?.[oldValue]
+ *       ? await this.translateValueLabel(valueLabels[oldValue], language)
+ *       : oldValue;
+ *     const displayNewValue = valueLabels?.[newValue]
+ *       ? await this.translateValueLabel(valueLabels[newValue], language)
+ *       : newValue;
+ *
+ *     return {
+ *       fieldLabel,
+ *       oldValue,
+ *       newValue,
+ *       displayOldValue,
+ *       displayNewValue,
+ *     };
+ *   }
+ *
+ *   private async translateValueLabel(
+ *     label: string | { [lang: string]: string },
+ *     language: string,
+ *   ): Promise<string> {
+ *     if (typeof label === 'string' && label.includes('.')) {
+ *       return await this.i18n.translate(label, { lang: language });
+ *     }
+ *     if (typeof label === 'object') {
+ *       return label[language] || label.zh || label.en || '';
+ *     }
+ *     return label;
+ *   }
+ * }
+ */
+// ============================================
+// 使用场景对比
+// ============================================
+/**
+ * 场景 1: 纯 i18n key 方式（推荐）
+ *
+ * 优点:
+ * - 翻译集中管理，易于维护
+ * - 支持动态切换语言
+ * - 翻译可以复用
+ * - 适合大型项目和国际化需求
+ *
+ * 缺点:
+ * - 需要额外的翻译文件配置
+ * - 增加了一定的复杂度
+ */
+class PureI18nDto {
+}
+exports.PureI18nDto = PureI18nDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 3,
+        maxLength: 20,
+        fieldI18n: 'field.user.username',
+    }),
+    __metadata("design:type", String)
+], PureI18nDto.prototype, "username", void 0);
+/**
+ * 场景 2: 纯多语言对象方式
+ *
+ * 优点:
+ * - 简单直接，无需额外配置
+ * - 适合小型项目或固定语言场景
+ * - 翻译就在代码中，查看方便
+ *
+ * 缺点:
+ * - 翻译分散在各个 DTO 中，难以统一管理
+ * - 不易于动态切换语言
+ * - 翻译无法复用
+ */
+class PureLabelDto {
+}
+exports.PureLabelDto = PureLabelDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 3,
+        maxLength: 20,
+        fieldLabel: { zh: '用户名', en: 'Username' },
+    }),
+    __metadata("design:type", String)
+], PureLabelDto.prototype, "username", void 0);
+/**
+ * 场景 3: 混合方式（fieldLabel 优先）
+ *
+ * 优点:
+ * - 灵活性最高
+ * - 可以为特定字段覆盖 i18n 翻译
+ *
+ * 缺点:
+ * - 可能造成混淆
+ * - 建议统一使用一种方式
+ */
+class MixedDto {
+}
+exports.MixedDto = MixedDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 3,
+        maxLength: 20,
+        fieldI18n: 'field.user.username', // 会被 fieldLabel 覆盖
+        fieldLabel: { zh: '用户名（自定义）', en: 'Username (Custom)' },
+    }),
+    __metadata("design:type", String)
+], MixedDto.prototype, "username", void 0);
+// ============================================
+// 完整示例：用户注册 DTO
+// ============================================
+class RegisterUserDto {
+}
+exports.RegisterUserDto = RegisterUserDto;
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 3,
+        maxLength: 20,
+        fieldI18n: 'field.user.username',
+        fieldDescription: {
+            zh: '用于登录的唯一用户名',
+            en: 'Unique username for login',
+        },
+    }),
+    __metadata("design:type", String)
+], RegisterUserDto.prototype, "username", void 0);
+__decorate([
+    (0, field_decorators_1.StringField)({
+        fieldI18n: 'field.user.email',
+    }),
+    __metadata("design:type", String)
+], RegisterUserDto.prototype, "email", void 0);
+__decorate([
+    (0, field_decorators_1.StringField)({
+        minLength: 6,
+        fieldI18n: 'field.user.password',
+    }),
+    __metadata("design:type", String)
+], RegisterUserDto.prototype, "password", void 0);
+__decorate([
+    (0, field_decorators_1.StringFieldOptional)({
+        minLength: 11,
+        maxLength: 11,
+        fieldI18n: 'field.user.phone',
+    }),
+    __metadata("design:type", String)
+], RegisterUserDto.prototype, "phone", void 0);
+__decorate([
+    (0, field_decorators_1.BooleanFieldOptional)({
+        fieldI18n: 'field.user.agreeTerms',
+        valueLabels: {
+            true: { zh: '同意', en: 'Agreed' },
+            false: { zh: '未同意', en: 'Not Agreed' },
+        },
+    }),
+    __metadata("design:type", Boolean)
+], RegisterUserDto.prototype, "agreeTerms", void 0);

package/decorators/field.decorators.d.ts

@@ -7,6 +7,75 @@ interface IFieldOptions {
     nullable?: boolean;
     group?: string[];
     message?: string;
+    skipValidation?: boolean;
+    /**
+     * i18n 翻译键
+     * 用于通过 i18n key 进行多语言转换
+     *
+     * @example
+     * // 使用 i18n key
+     * @StringField({
+     *   fieldI18n: 'user.username',
+     * })
+     * username: string;
+     *
+     * // 翻译文件中定义:
+     * // {
+     * //   "user": {
+     * //     "username": "用户名"  // 或 "Username" for English
+     * //   }
+     * // }
+     */
+    fieldI18n?: string;
+    /**
+     * 字段标签（多语言）
+     * 用于审计日志、验证错误消息、UI 显示等
+     * 注意：如果同时提供了 fieldI18n 和 fieldLabel，fieldLabel 优先级更高
+     */
+    fieldLabel?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /**
+     * 字段描述（多语言）
+     * 用于 API 文档、审计日志等
+     * 支持两种形式：
+     * 1. i18n key: "user.username.description"
+     * 2. 直接多语言对象: { zh: '...', en: '...' }
+     */
+    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 +127,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;
@@ -69,11 +136,36 @@ export declare function FQDNFieldOptional(options?: Omit<ApiPropertyOptions, 'ty
 export declare function DateField(options?: Omit<ApiPropertyOptions, 'type'> & IDateFieldOptions): PropertyDecorator;
 export declare function DateFieldOptional(options?: Omit<ApiPropertyOptions, 'type' | 'required'> & IDateFieldOptions): PropertyDecorator;
 export declare function IpFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IIPFieldOptions & IStringFieldOptions): PropertyDecorator;
-export declare function IpField(options: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IIPFieldOptions): PropertyDecorator;
+export declare function IpField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions & IIPFieldOptions): PropertyDecorator;
 export declare function ObjectField(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
 export declare function ObjectFieldOptional(options?: Omit<ApiPropertyOptions, 'type'> & IFieldOptions): PropertyDecorator;
 export declare function TimeZoneField(options?: Omit<ApiPropertyOptions, 'type'> & IStringFieldOptions): PropertyDecorator;
 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 {};