kubanapis/proto/kuban/api/validate/rule_groups.proto

// Copyright 2025 Kuban Technologies
//
// 规则分组管理 - 支持场景化验证
// 允许在不同业务场景下应用不同的验证规则集

syntax = "proto3";

package kuban.api.validate;

import "google/protobuf/descriptor.proto";

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

// ============================================================================
// 验证组定义
// ============================================================================

// 验证组 - 用于场景化验证
//
// 使用示例:
// ```proto
// message User {
//   string name = 1 [
//     (kuban.api.validate.field).string = { min_len: 2, max_len: 50 },
//     (kuban.api.validate.field).groups = ["create", "update"]
//   ];
//
//   string password = 2 [
//     (kuban.api.validate.field).string = { min_len: 8 },
//     (kuban.api.validate.field).groups = ["create", "change_password"]
//   ];
// }
// ```
message ValidationGroup {
  // 组名称(唯一标识)
  string name = 1;

  // 组显示名称(中文)
  string display_name = 2;

  // 组显示名称(英文)
  string display_name_en = 3;

  // 组描述
  string description = 4;

  // 是否为默认组(默认启用)
  bool is_default = 5;

  // 优先级(数字越大优先级越高)
  int32 priority = 6;

  // 父组(用于继承规则)
  string parent_group = 7;

  // 互斥组(不能同时激活的组)
  repeated string exclusive_groups = 8;
}

// 常用验证组定义
enum CommonValidationGroup {
  COMMON_VALIDATION_GROUP_UNSPECIFIED = 0;

  // CRUD 操作组
  COMMON_VALIDATION_GROUP_CREATE = 1;    // 创建场景
  COMMON_VALIDATION_GROUP_UPDATE = 2;    // 更新场景
  COMMON_VALIDATION_GROUP_PATCH = 3;     // 部分更新场景
  COMMON_VALIDATION_GROUP_DELETE = 4;    // 删除场景
  COMMON_VALIDATION_GROUP_QUERY = 5;     // 查询场景

  // 严格程度组
  COMMON_VALIDATION_GROUP_STRICT = 10;   // 严格模式
  COMMON_VALIDATION_GROUP_NORMAL = 11;   // 标准模式
  COMMON_VALIDATION_GROUP_LOOSE = 12;    // 宽松模式

  // 用户场景组
  COMMON_VALIDATION_GROUP_REGISTER = 20;        // 用户注册
  COMMON_VALIDATION_GROUP_LOGIN = 21;           // 用户登录
  COMMON_VALIDATION_GROUP_PROFILE = 22;         // 个人资料
  COMMON_VALIDATION_GROUP_CHANGE_PASSWORD = 23; // 修改密码
  COMMON_VALIDATION_GROUP_RESET_PASSWORD = 24;  // 重置密码

  // 审核场景组
  COMMON_VALIDATION_GROUP_DRAFT = 30;    // 草稿
  COMMON_VALIDATION_GROUP_SUBMIT = 31;   // 提交审核
  COMMON_VALIDATION_GROUP_APPROVE = 32;  // 审核通过
  COMMON_VALIDATION_GROUP_REJECT = 33;   // 审核拒绝

  // 实名认证场景
  COMMON_VALIDATION_GROUP_REAL_NAME_AUTH = 40;     // 实名认证
  COMMON_VALIDATION_GROUP_ENTERPRISE_AUTH = 41;    // 企业认证
  COMMON_VALIDATION_GROUP_BANK_CARD_BINDING = 42;  // 银行卡绑定

  // 安全场景组
  COMMON_VALIDATION_GROUP_SENSITIVE_OP = 50;  // 敏感操作
  COMMON_VALIDATION_GROUP_FINANCIAL = 51;     // 金融交易
  COMMON_VALIDATION_GROUP_ADMIN = 52;         // 管理员操作
}

// ============================================================================
// 验证上下文
// ============================================================================

// 验证上下文 - 运行时传递给验证器的上下文信息
message ValidationContext {
  // 激活的验证组
  repeated string active_groups = 1;

  // 用户角色
  repeated string user_roles = 2;

  // 用户权限
  repeated string user_permissions = 3;

  // 租户 ID(多租户场景)
  string tenant_id = 4;

  // 请求来源
  RequestSource source = 5;

  // 是否为管理员操作
  bool is_admin = 6;

  // 自定义元数据
  map<string, string> metadata = 7;

  // 验证时间戳
  int64 timestamp = 8;

  // 语言偏好(用于错误消息)
  string language = 9;
}

// 请求来源
enum RequestSource {
  REQUEST_SOURCE_UNSPECIFIED = 0;
  REQUEST_SOURCE_WEB = 1;          // Web 端
  REQUEST_SOURCE_MOBILE = 2;       // 移动端
  REQUEST_SOURCE_API = 3;          // API 调用
  REQUEST_SOURCE_INTERNAL = 4;     // 内部调用
  REQUEST_SOURCE_BATCH = 5;        // 批量处理
}

// ============================================================================
// 验证策略
// ============================================================================

// 验证策略 - 控制验证行为
message ValidationStrategy {
  // 验证模式
  ValidationMode mode = 1;

  // 是否快速失败(遇到第一个错误就停止)
  bool fail_fast = 2;

  // 是否收集警告(非阻塞性错误)
  bool collect_warnings = 3;

  // 最大错误数(超过后停止验证)
  int32 max_errors = 4;

  // 验证超时(毫秒)
  int64 timeout_ms = 5;

  // 是否启用缓存
  bool enable_cache = 6;

  // 缓存 TTL(秒)
  int32 cache_ttl_seconds = 7;
}

// 验证模式
enum ValidationMode {
  VALIDATION_MODE_UNSPECIFIED = 0;
  VALIDATION_MODE_ALL = 1;         // 验证所有规则
  VALIDATION_MODE_REQUIRED_ONLY = 2; // 仅验证必填项
  VALIDATION_MODE_CHANGED_ONLY = 3;  // 仅验证修改的字段
  VALIDATION_MODE_CUSTOM = 4;        // 自定义(根据组选择)
}

// ============================================================================
// 组合验证规则
// ============================================================================

// 组合验证规则 - 支持复杂的验证逻辑组合
message CompositeRule {
  // 规则组合类型
  CompositeType type = 1;

  // 子规则列表
  repeated RuleRef rules = 2;

  // 错误消息
  string message = 3;

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

// 组合类型
enum CompositeType {
  COMPOSITE_TYPE_UNSPECIFIED = 0;
  COMPOSITE_TYPE_AND = 1;  // 所有规则都必须通过
  COMPOSITE_TYPE_OR = 2;   // 至少一个规则通过
  COMPOSITE_TYPE_XOR = 3;  // 恰好一个规则通过
  COMPOSITE_TYPE_NOT = 4;  // 规则不能通过
}

// 规则引用
message RuleRef {
  // 规则 ID
  string rule_id = 1;

  // 规则权重(用于优先级排序)
  int32 weight = 2;

  // 是否为可选规则
  bool optional = 3;
}

// ============================================================================
// 条件验证
// ============================================================================

// 条件验证规则 - 根据条件决定是否应用规则
message ConditionalRule {
  // 条件表达式(CEL)
  string condition = 1;

  // 条件为真时应用的规则
  repeated RuleRef when_true = 2;

  // 条件为假时应用的规则
  repeated RuleRef when_false = 3;

  // 条件评估失败时的默认行为
  DefaultBehavior on_error = 4;
}

// 默认行为
enum DefaultBehavior {
  DEFAULT_BEHAVIOR_UNSPECIFIED = 0;
  DEFAULT_BEHAVIOR_SKIP = 1;      // 跳过验证
  DEFAULT_BEHAVIOR_APPLY = 2;     // 应用验证
  DEFAULT_BEHAVIOR_FAIL = 3;      // 验证失败
}

// ============================================================================
// 验证规则集
// ============================================================================

// 验证规则集 - 预定义的规则组合,可复用
message ValidationRuleSet {
  // 规则集 ID
  string id = 1;

  // 规则集名称
  string name = 2;

  // 规则集描述
  string description = 3;

  // 规则集版本
  string version = 4;

  // 包含的验证组
  repeated string groups = 5;

  // 包含的规则
  repeated RuleRef rules = 6;

  // 验证策略
  ValidationStrategy strategy = 7;

  // 是否为内置规则集
  bool builtin = 8;

  // 创建时间
  int64 created_at = 9;

  // 更新时间
  int64 updated_at = 10;

  // 创建者
  string created_by = 11;
}

// ============================================================================
// 验证规则集市场(可选 - 用于规则共享)
// ============================================================================

// 规则集模板 - 用于快速创建常见场景的验证规则
message RuleSetTemplate {
  // 模板 ID
  string id = 1;

  // 模板名称
  string name = 2;

  // 模板描述
  string description = 3;

  // 适用场景
  repeated string scenarios = 4;

  // 模板类别
  repeated string categories = 5;

  // 规则集定义
  ValidationRuleSet rule_set = 6;

  // 使用示例
  string usage_example = 7;

  // 下载次数
  int64 download_count = 8;

  // 评分
  float rating = 9;
}

// 规则集类别
enum RuleSetCategory {
  RULE_SET_CATEGORY_UNSPECIFIED = 0;
  RULE_SET_CATEGORY_USER_MANAGEMENT = 1;    // 用户管理
  RULE_SET_CATEGORY_FINANCIAL = 2;          // 金融
  RULE_SET_CATEGORY_ECOMMERCE = 3;          // 电商
  RULE_SET_CATEGORY_CONTENT = 4;            // 内容管理
  RULE_SET_CATEGORY_GOVERNMENT = 5;         // 政务
  RULE_SET_CATEGORY_HEALTHCARE = 6;         // 医疗
  RULE_SET_CATEGORY_EDUCATION = 7;          // 教育
  RULE_SET_CATEGORY_GENERAL = 99;           // 通用
}