kubanapis/proto/kuban/api/validate/validate_example.proto

// Copyright 2025 Kuban Technologies
//
// 验证系统使用示例
// 展示如何使用 kuban.api.validate 验证框架

syntax = "proto3";

package kuban.api.example;

import "kuban/api/validate/validate.proto";
// import "kuban/api/validate/business_rules.proto";  // 未使用
// import "kuban/api/validate/rule_groups.proto";  // 未使用

option go_package = "git.ikuban.com/server/kubanapis/kuban/api/example;example";

// ============================================================================
// 示例 1: 基本字段验证
// ============================================================================

message BasicValidationExample {
  // 必填字符串,长度 2-50
  string name = 1 [(kuban.api.validate.field) = {
    required: true,
    string: {
      min_len: 2,
      max_len: 50
    }
  }];

  // 必填邮箱
  string email = 2 [(kuban.api.validate.field) = {
    required: true,
    string: {
      email: true
    }
  }];

  // 年龄范围 0-150
  int32 age = 3 [(kuban.api.validate.field) = {
    int32: {
      gte: 0,
      lte: 150
    }
  }];

  // 可选字段,设置时必须符合 URL 格式
  optional string website = 4 [(kuban.api.validate.field) = {
    string: {
      uri: true
    }
  }];
}

// ============================================================================
// 示例 2: 中文业务验证
// ============================================================================

message ChineseBusinessExample {
  // 中国手机号验证(简化方式)
  string mobile = 1 [(kuban.api.validate.field) = {
    required: true,
    string: {
      chinese_mobile: true  // 使用内置的中国手机号验证
    }
  }];

  // 中国手机号验证(带自定义错误消息)
  string mobile_advanced = 2 [(kuban.api.validate.field) = {
    required: true,
    error_message: "请输入有效的中国大陆手机号",
    string: {
      chinese_mobile: true
    }
  }];

  // 中国身份证验证
  string id_card = 3 [(kuban.api.validate.field) = {
    required: true,
    error_message: "请输入有效的18位身份证号",
    string: {
      chinese_id_card: true
    }
  }];

  // 中文姓名验证
  string chinese_name = 4 [(kuban.api.validate.field) = {
    required: true,
    error_message: "请输入2-20个字符的中文姓名",
    string: {
      chinese_name: true,
      min_len: 2,
      max_len: 20
    }
  }];

  // 统一社会信用代码(使用 CEL 或正则表达式验证)
  string uscc = 5 [(kuban.api.validate.field) = {
    error_message: "请输入有效的企业统一社会信用代码(18位)",
    string: {
      pattern: "^[0-9A-HJ-NPQRTUWXY]{2}\\d{6}[0-9A-HJ-NPQRTUWXY]{10}$",
      len: 18
    }
  }];

  // 银行卡号(使用正则表达式和长度验证)
  string bank_card = 6 [(kuban.api.validate.field) = {
    error_message: "请输入有效的银行卡号(16-19位)",
    string: {
      pattern: "^\\d{16,19}$",
      min_len: 16,
      max_len: 19
    }
  }];

  // 中国邮政编码
  string postcode = 7 [(kuban.api.validate.field) = {
    error_message: "请输入有效的6位邮政编码",
    string: {
      chinese_postcode: true
    }
  }];
}

// ============================================================================
// 示例 3: 使用 CEL 自定义验证
// ============================================================================

message CustomCELExample {
  string username = 1 [(kuban.api.validate.field) = {
    required: true,
    cel: [
      {
        id: "username.format",
        message: "用户名只能包含字母、数字和下划线",
        expression: "this.matches('^[a-zA-Z0-9_]+$')"
      },
      {
        id: "username.no_admin",
        message: "用户名不能包含 'admin'",
        expression: "!this.contains('admin')"
      }
    ],
    string: {
      min_len: 3,
      max_len: 20
    }
  }];

  int32 score = 2 [(kuban.api.validate.field) = {
    cel: [
      {
        id: "score.range",
        message: "分数必须在 0-100 之间",
        message_en: "Score must be between 0 and 100",
        expression: "this >= 0 && this <= 100"
      }
    ]
  }];

  // 跨字段验证
  string password = 3;
  string password_confirm = 4 [(kuban.api.validate.field) = {
    cel: [
      {
        id: "password.match",
        message: "两次输入的密码不一致",
        expression: "this == this.password"  // 引用同一消息的其他字段
      }
    ]
  }];
}

// ============================================================================
// 示例 4: 分组验证
// ============================================================================

message GroupValidationExample {
  // 用户名在创建和更新时都需要验证
  string username = 1 [(kuban.api.validate.field) = {
    required: true,
    groups: ["create", "update"],
    string: {
      min_len: 3,
      max_len: 20
    }
  }];

  // 密码仅在创建和修改密码时需要验证
  string password = 2 [(kuban.api.validate.field) = {
    required: true,
    groups: ["create", "change_password"],
    string: {
      min_len: 8,
      max_len: 32
    }
  }];

  // 手机号在实名认证时必填
  string mobile = 3 [(kuban.api.validate.field) = {
    groups: ["real_name_auth"],
    required: true,
    string: {
      chinese_mobile: true
    }
  }];

  // 可选字段,但在严格模式下必填
  optional string nickname = 4 [(kuban.api.validate.field) = {
    groups: ["strict"],
    required: true,
    string: {
      min_len: 2,
      max_len: 30
    }
  }];
}

// ============================================================================
// 示例 5: 复杂类型验证
// ============================================================================

message ComplexTypeExample {
  // 重复字段验证
  repeated string tags = 1 [(kuban.api.validate.field) = {
    repeated: {
      min_items: 1,
      max_items: 10,
      unique: true,
      items: {
        string: {
          min_len: 2,
          max_len: 20
        }
      }
    }
  }];

  // Map 验证
  map<string, int32> scores = 2 [(kuban.api.validate.field) = {
    map: {
      min_pairs: 1,
      max_pairs: 100,
      keys: {
        string: {
          min_len: 1,
          max_len: 50
        }
      },
      values: {
        int32: {
          gte: 0,
          lte: 100
        }
      }
    }
  }];

  // 嵌套消息验证
  Address address = 3 [(kuban.api.validate.field) = {
    required: true
  }];
}

message Address {
  string province = 1 [(kuban.api.validate.field) = {
    required: true,
    string: {
      min_len: 2,
      max_len: 20
    }
  }];

  string city = 2 [(kuban.api.validate.field) = {
    required: true,
    string: {
      min_len: 2,
      max_len: 20
    }
  }];

  string detail = 3 [(kuban.api.validate.field) = {
    required: true,
    string: {
      min_len: 5,
      max_len: 200
    }
  }];

  string postcode = 4 [(kuban.api.validate.field) = {
    string: {
      chinese_postcode: true
    }
  }];
}

// ============================================================================
// 示例 6: 消息级别验证
// ============================================================================

message MessageLevelExample {
  option (kuban.api.validate.message) = {
    cel: [
      {
        id: "date_range.valid",
        message: "结束日期必须大于开始日期",
        expression: "this.end_date > this.start_date"
      },
      {
        id: "required_fields",
        message: "姓名和手机号至少需要填写一个",
        expression: "has(this.name) || has(this.mobile)"
      }
    ],
    groups: ["create", "update"]
  };

  optional string name = 1;
  optional string mobile = 2;
  int64 start_date = 3;
  int64 end_date = 4;
}

// ============================================================================
// 示例 7: Oneof 验证
// ============================================================================

message OneofExample {
  // 联系方式:邮箱和手机号必须选择一个
  oneof contact {
    option (kuban.api.validate.oneof).required = true;

    string email = 1 [(kuban.api.validate.field) = {
      string: { email: true }
    }];

    string mobile = 2 [(kuban.api.validate.field) = {
      string: { chinese_mobile: true }
    }];
  }
}

// ============================================================================
// 示例 8: 忽略策略
// ============================================================================

message IgnoreRuleExample {
  // 仅在值不为空时验证
  optional string optional_url = 1 [(kuban.api.validate.field) = {
    ignore: IGNORE_IF_ZERO,
    string: {
      uri: true
    }
  }];

  // 始终验证(即使未设置)
  optional string required_email = 2 [(kuban.api.validate.field) = {
    ignore: IGNORE_NEVER,
    required: true,
    string: {
      email: true
    }
  }];

  // 暂时忽略验证(用于开发阶段)
  string temp_field = 3 [(kuban.api.validate.field) = {
    ignore: IGNORE_ALWAYS,
    string: {
      min_len: 10  // 这个规则不会生效
    }
  }];
}

// ============================================================================
// 示例 9: 实际业务场景 - 用户注册
// ============================================================================

message UserRegistrationRequest {
  option (kuban.api.validate.message) = {
    groups: ["register"]
  };

  // 用户名
  string username = 1 [(kuban.api.validate.field) = {
    required: true,
    groups: ["register"],
    string: {
      min_len: 3,
      max_len: 20,
      pattern: "^[a-zA-Z0-9_]+$"
    },
    cel: [
      {
        id: "username.reserved",
        message: "该用户名为系统保留,不可使用",
        expression: "!['admin', 'root', 'system'].contains(this.toLowerCase())"
      }
    ]
  }];

  // 密码
  string password = 2 [(kuban.api.validate.field) = {
    required: true,
    groups: ["register"],
    string: {
      min_len: 8,
      max_len: 32
    },
    cel: [
      {
        id: "password.complexity",
        message: "密码必须包含大小写字母、数字和特殊字符",
        expression: "this.matches('(?=.*[a-z])(?=.*[A-Z])(?=.*\\\\d)(?=.*[@$!%*?&])[A-Za-z\\\\d@$!%*?&]+')"
      }
    ]
  }];

  // 手机号
  string mobile = 3 [(kuban.api.validate.field) = {
    required: true,
    groups: ["register"],
    string: {
      chinese_mobile: true
    }
  }];

  // 验证码
  string verification_code = 4 [(kuban.api.validate.field) = {
    required: true,
    groups: ["register"],
    string: {
      len: 6,
      numeric: true
    }
  }];

  // 邮箱(可选)
  optional string email = 5 [(kuban.api.validate.field) = {
    groups: ["register"],
    ignore: IGNORE_IF_ZERO,
    string: {
      email: true
    }
  }];

  // 同意服务条款
  bool agree_terms = 6 [(kuban.api.validate.field) = {
    required: true,
    groups: ["register"],
    bool: {
      const: true
    },
    cel: [
      {
        id: "agree_terms.must_true",
        message: "必须同意服务条款才能注册",
        expression: "this == true"
      }
    ]
  }];
}

// ============================================================================
// 示例 10: 实际业务场景 - 企业认证
// ============================================================================

message EnterpriseAuthRequest {
  option (kuban.api.validate.message) = {
    groups: ["enterprise_auth"],
    cel: [
      {
        id: "complete_info",
        message: "企业认证信息不完整",
        expression: "has(this.company_name) && has(this.uscc) && has(this.legal_person)"
      }
    ]
  };

  // 企业名称
  string company_name = 1 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    string: {
      min_len: 2,
      max_len: 100
    }
  }];

  // 统一社会信用代码
  string uscc = 2 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    error_message: "请输入有效的企业统一社会信用代码(18位)",
    string: {
      pattern: "^[0-9A-HJ-NPQRTUWXY]{2}\\d{6}[0-9A-HJ-NPQRTUWXY]{10}$",
      len: 18
    }
  }];

  // 法人代表姓名
  string legal_person = 3 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    error_message: "请输入2-20个字符的中文姓名",
    string: {
      chinese_name: true,
      min_len: 2,
      max_len: 20
    }
  }];

  // 法人身份证号
  string legal_person_id_card = 4 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    error_message: "请输入有效的18位身份证号",
    string: {
      chinese_id_card: true
    }
  }];

  // 企业联系电话
  string contact_phone = 5 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    string: {
      chinese_mobile: true
    }
  }];

  // 营业执照附件
  bytes business_license_image = 6 [(kuban.api.validate.field) = {
    required: true,
    groups: ["enterprise_auth"],
    bytes: {
      min_len: 1024,           // 至少 1KB
      max_len: 5242880         // 最大 5MB
    }
  }];
}