kubanapis/proto/kuban/api/validate/business_rules.proto

// Copyright 2025 Kuban Technologies
//
// 业务规则库 - 针对中国业务场景的预定义验证规则
// 提供开箱即用的常用业务验证

syntax = "proto3";

package kuban.api.validate;

import "google/protobuf/descriptor.proto";
import "kuban/api/validate/validate.proto";

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

// ============================================================================
// 业务规则定义
// ============================================================================
//
// 注意: Proto3 不支持 extend 语法,这些业务规则应该通过以下方式使用:
// 1. 在 FieldRules 中使用 CEL 表达式引用这些规则
// 2. 在应用层直接使用这些独立的规则消息
// 3. 使用 StringRules 中已有的 well_known 字段(如 chinese_mobile, chinese_id_card 等)
//
// ============================================================================

// 中国手机号验证规则
message ChineseMobileRules {
  // 是否启用验证
  bool enabled = 1;

  // 允许的运营商
  repeated MobileOperator allowed_operators = 2;

  // 是否允许虚拟运营商号码
  bool allow_virtual = 3;

  // 自定义错误消息
  string error_message = 4;
}

// 手机运营商枚举
enum MobileOperator {
  MOBILE_OPERATOR_UNSPECIFIED = 0;
  MOBILE_OPERATOR_CHINA_MOBILE = 1;    // 中国移动
  MOBILE_OPERATOR_CHINA_UNICOM = 2;    // 中国联通
  MOBILE_OPERATOR_CHINA_TELECOM = 3;   // 中国电信
  MOBILE_OPERATOR_CHINA_BROADNET = 4;  // 中国广电
}

// 中国身份证验证规则
message ChineseIdCardRules {
  // 是否启用验证
  bool enabled = 1;

  // 是否验证校验位
  bool verify_checksum = 2;

  // 是否验证出生日期有效性
  bool verify_birth_date = 3;

  // 是否验证地区码有效性
  bool verify_area_code = 4;

  // 允许的身份证类型
  repeated IdCardType allowed_types = 5;

  // 年龄范围限制
  optional int32 min_age = 6;
  optional int32 max_age = 7;

  // 性别限制
  optional Gender required_gender = 8;

  // 自定义错误消息
  string error_message = 9;
}

// 身份证类型
enum IdCardType {
  ID_CARD_TYPE_UNSPECIFIED = 0;
  ID_CARD_TYPE_18_DIGIT = 1;  // 18位身份证
  ID_CARD_TYPE_15_DIGIT = 2;  // 15位身份证(旧版)
}

// 性别枚举
enum Gender {
  GENDER_UNSPECIFIED = 0;
  GENDER_MALE = 1;      // 男性
  GENDER_FEMALE = 2;    // 女性
}

// 统一社会信用代码验证规则
message UnifiedSocialCreditCodeRules {
  // 是否启用验证
  bool enabled = 1;

  // 是否验证校验位
  bool verify_checksum = 2;

  // 允许的机构类型
  repeated OrganizationType allowed_types = 3;

  // 自定义错误消息
  string error_message = 4;
}

// 机构类型
enum OrganizationType {
  ORGANIZATION_TYPE_UNSPECIFIED = 0;
  ORGANIZATION_TYPE_ENTERPRISE = 1;        // 企业
  ORGANIZATION_TYPE_INSTITUTION = 2;       // 事业单位
  ORGANIZATION_TYPE_SOCIAL_GROUP = 3;      // 社会团体
  ORGANIZATION_TYPE_GOVERNMENT = 9;        // 机关
}

// 银行卡号验证规则
message BankCardRules {
  // 是否启用验证
  bool enabled = 1;

  // 是否使用 Luhn 算法验证
  bool verify_luhn = 2;

  // 允许的卡类型
  repeated BankCardType allowed_types = 3;

  // 允许的银行
  repeated string allowed_banks = 4;  // 银行代码列表

  // 自定义错误消息
  string error_message = 5;
}

// 银行卡类型
enum BankCardType {
  BANK_CARD_TYPE_UNSPECIFIED = 0;
  BANK_CARD_TYPE_DEBIT = 1;   // 借记卡
  BANK_CARD_TYPE_CREDIT = 2;  // 信用卡
}

// 中文姓名验证规则
message ChineseNameRules {
  // 是否启用验证
  bool enabled = 1;

  // 最小长度(字符数)
  optional uint32 min_length = 2;

  // 最大长度(字符数)
  optional uint32 max_length = 3;

  // 是否允许少数民族姓名(可能包含·等特殊字符)
  bool allow_ethnic_minority = 4;

  // 是否允许英文名
  bool allow_english = 5;

  // 自定义错误消息
  string error_message = 6;
}

// 邮政编码验证规则
message PostcodeRules {
  // 是否启用验证
  bool enabled = 1;

  // 国家/地区代码(默认为中国 CN)
  string country_code = 2;

  // 允许的省份代码(中国邮编前两位)
  repeated string allowed_provinces = 3;

  // 自定义错误消息
  string error_message = 4;
}

// ============================================================================
// 常用业务场景验证规则组合
// ============================================================================

// 用户注册验证规则
message UserRegistrationRules {
  // 用户名规则
  StringRules username = 1;

  // 手机号规则
  ChineseMobileRules mobile = 2;

  // 邮箱规则
  StringRules email = 3;

  // 密码规则
  PasswordRules password = 4;

  // 真实姓名规则(可选)
  ChineseNameRules real_name = 5;

  // 身份证规则(可选)
  ChineseIdCardRules id_card = 6;
}

// 密码强度验证规则
message PasswordRules {
  // 最小长度
  uint32 min_length = 1;

  // 最大长度
  uint32 max_length = 2;

  // 是否要求包含大写字母
  bool require_uppercase = 3;

  // 是否要求包含小写字母
  bool require_lowercase = 4;

  // 是否要求包含数字
  bool require_digit = 5;

  // 是否要求包含特殊字符
  bool require_special = 6;

  // 特殊字符集合(默认: !@#$%^&*()_+-=[]{}|;:,.<>?)
  string special_chars = 7;

  // 是否禁止常见弱密码
  bool reject_common_weak = 8;

  // 自定义错误消息
  string error_message = 9;
}

// 企业信息验证规则
message EnterpriseInfoRules {
  // 企业名称规则
  StringRules company_name = 1;

  // 统一社会信用代码规则
  UnifiedSocialCreditCodeRules uscc = 2;

  // 法人姓名规则
  ChineseNameRules legal_person_name = 3;

  // 注册资本范围
  optional int64 min_registered_capital = 4;
  optional int64 max_registered_capital = 5;

  // 营业执照号码(旧格式)
  StringRules business_license = 6;
}

// 地址验证规则
message AddressRules {
  // 省份
  StringRules province = 1;

  // 城市
  StringRules city = 2;

  // 区县
  StringRules district = 3;

  // 详细地址
  StringRules detail = 4;

  // 邮政编码
  PostcodeRules postcode = 5;

  // 是否要求完整地址
  bool require_complete = 6;
}

// 金融交易验证规则
message FinancialTransactionRules {
  // 交易金额范围
  optional double min_amount = 1;
  optional double max_amount = 2;

  // 银行卡号验证
  BankCardRules bank_card = 3;

  // 交易密码规则
  PasswordRules transaction_password = 4;

  // 是否要求二次确认
  bool require_confirmation = 5;
}

// ============================================================================
// 验证规则辅助消息
// ============================================================================

// 验证错误详情
message ValidationError {
  // 字段路径
  string field_path = 1;

  // 规则 ID
  string rule_id = 2;

  // 错误消息(中文)
  string message = 3;

  // 错误消息(英文)
  string message_en = 4;

  // 失败的值
  string value = 5;

  // 附加信息
  map<string, string> metadata = 6;
}

// 批量验证结果
message ValidationResult {
  // 是否验证通过
  bool valid = 1;

  // 错误列表
  repeated ValidationError errors = 2;

  // 警告列表(非阻塞性)
  repeated ValidationError warnings = 3;

  // 验证组
  string group = 4;
}