package gudusoft.gsqlparser.sqlenv;

import gudusoft.gsqlparser.EDbVendor;

import java.util.Collections;
import java.util.EnumMap;
import java.util.EnumSet;
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.ConcurrentHashMap;

/**
 * 厂商标识符配置档案（Vendor Identifier Profile）
 *
 * <p>封装每个数据库厂商的完整标识符配置，包括：
 * <ul>
 * <li>按对象组（NAME_GROUP, COLUMN_GROUP, ROUTINE_GROUP）的标识符规则
 * <li>按对象类别（catalog/project、schema、table、column…）的独立覆盖，见
 *     {@link Builder#withObjectRules(ESQLDataObjectType, IdentifierRules)}
 * <li>Vendor-specific flags（如 MySQL lower_case_table_names, SQL Server collation）
 * </li>
 *
 * <p>设计目标：
 * <ul>
 * <li>集中管理所有 vendor-specific 配置
 * <li>统一注入路径，避免配置散落在各处
 * <li>支持缓存失效（通过 fingerprint）
 * </ul>
 *
 * <p>使用示例：
 * <pre>
 * // 创建 Oracle profile（使用默认 flags）
 * IdentifierProfile oracleProfile = IdentifierProfile.forVendor(
 *     EDbVendor.dbvoracle,
 *     VendorFlags.defaults()
 * );
 *
 * // 创建 MySQL profile（指定 lower_case_table_names）
 * IdentifierProfile mysqlProfile = IdentifierProfile.forVendor(
 *     EDbVendor.dbvmysql,
 *     new VendorFlags(1, null, false, false)  // lower_case_table_names = 1
 * );
 *
 * // 查询规则
 * IdentifierRules tableRules = oracleProfile.getRules(ESQLDataObjectType.dotTable);
 * </pre>
 *
 * @since 3.1.0.9
 */
public final class IdentifierProfile {

    private final EDbVendor vendor;

    // ===== 按对象组的规则 =====
    private final EnumMap<ObjectGroup, IdentifierRules> rulesByGroup;

    /**
     * Explicit per-object-category overrides, the finest granularity
     * ({@link Builder#withObjectRules}). Empty for a plain vendor profile.
     *
     * <p>Kept separately from {@link #effectiveRules} so {@link #toBuilder()} can hand the
     * overrides back as overrides rather than as a new seed — re-seeding with
     * {@link Builder#withFlags} must not silently freeze an override into a vendor default.
     */
    private final EnumMap<ESQLDataObjectType, IdentifierRules> rulesByType;

    /**
     * The groups whose rule a caller set ({@link Builder#withRules}) rather than the vendor seed.
     * A caller's group rule outranks the vendor's own per-category rules
     * ({@link #defaultTypeRulesFor}), so this has to be remembered to resolve a category.
     */
    private final EnumSet<ObjectGroup> overriddenGroups;

    /**
     * The resolved rule of EVERY object type — the profile's complete effective strategy.
     *
     * <p>Selection order (design §5.1): explicit object-category override &gt; group override
     * or vendor-seeded group rule. Precomputed for two reasons: {@link #getRules} is on the
     * per-compare hot path, and equality/fingerprint have to compare the whole strategy, not
     * the three group slots (two profiles built by different routes — a group override versus
     * an override on every type of that group — are the same strategy and must compare equal).
     */
    private final EnumMap<ESQLDataObjectType, IdentifierRules> effectiveRules;

    // ===== Vendor-specific flags =====
    private final VendorFlags flags;

    // ===== 对象组定义 =====

    /**
     * 对象组（用于区分不同对象类型的标识符规则）
     *
     * <p>某些数据库对不同对象类型使用不同的大小写规则：
     * <ul>
     * <li>BigQuery: 表名敏感，列名不敏感
     * <li>MySQL: 表名根据 lower_case_table_names，列名始终不敏感
     * </ul>
     */
    public enum ObjectGroup {
        /**
         * 名称组（catalog, schema, table, view, procedure, trigger）
         */
        NAME_GROUP,

        /**
         * 列组（column）
         */
        COLUMN_GROUP,

        /**
         * 函数组（function）
         * <p>某些数据库函数名规则与表名不同
         */
        ROUTINE_GROUP
    }

    // ===== Vendor flags 封装 =====

    /**
     * Vendor-specific flags（厂商特定配置）
     *
     * <p>封装各数据库厂商的特殊配置参数
     */
    public static class VendorFlags {
        /**
         * MySQL: lower_case_table_names 系统变量（0, 1, 2）
         * <ul>
         * <li>0: 大小写敏感（Unix/Linux）
         * <li>1: 存储为小写，比较不敏感（Windows）
         * <li>2: 存储保留原样，比较不敏感（macOS）
         * </ul>
         */
        public final int mysqlLowerCaseTableNames;

        /**
         * SQL Server / Azure SQL: 默认 collation 名称
         * <p>例如: "SQL_Latin1_General_CP1_CI_AS"
         */
        public final String defaultCollation;

        /**
         * Redshift: enable_case_sensitive_identifier 参数
         * <p>默认 false（与 PostgreSQL 一致）
         */
        public final boolean redshiftEnableCaseSensitive;

        /**
         * Snowflake: QUOTED_IDENTIFIERS_IGNORE_CASE 会话参数
         * <p>默认 false（quoted 标识符大小写敏感）
         */
        public final boolean snowflakeQuotedIdentifiersIgnoreCase;

        /**
         * MySQL 家族: sql_mode 中的 ANSI_QUOTES 选项
         *
         * <p>为 true 时，双引号 {@code "} 界定标识符（而非字符串字面量）。
         * 只影响 {@link IdentifierCodec} 的引号识别/编解码，不影响大小写
         * 折叠/比较规则（fold/compare 与 ANSI_QUOTES 无关）。
         * <p>默认 false（MySQL 出厂默认，{@code "} 是字符串定界符）。
         */
        public final boolean mysqlAnsiQuotes;

        /**
         * 构造 vendor flags（ansiQuotes 取默认值 false）
         *
         * @param mysqlLowerCaseTableNames MySQL lower_case_table_names (0, 1, 2)
         * @param defaultCollation SQL Server collation 名称
         * @param redshiftEnableCaseSensitive Redshift case sensitive 开关
         * @param snowflakeQuotedIdentifiersIgnoreCase Snowflake quoted ignore case 开关
         */
        public VendorFlags(int mysqlLowerCaseTableNames,
                          String defaultCollation,
                          boolean redshiftEnableCaseSensitive,
                          boolean snowflakeQuotedIdentifiersIgnoreCase) {
            this(mysqlLowerCaseTableNames, defaultCollation, redshiftEnableCaseSensitive,
                 snowflakeQuotedIdentifiersIgnoreCase, false);
        }

        /**
         * 构造 vendor flags（完整参数）
         *
         * @param mysqlLowerCaseTableNames MySQL lower_case_table_names (0, 1, 2)
         * @param defaultCollation SQL Server collation 名称
         * @param redshiftEnableCaseSensitive Redshift case sensitive 开关
         * @param snowflakeQuotedIdentifiersIgnoreCase Snowflake quoted ignore case 开关
         * @param mysqlAnsiQuotes MySQL 家族 sql_mode ANSI_QUOTES 开关
         */
        public VendorFlags(int mysqlLowerCaseTableNames,
                          String defaultCollation,
                          boolean redshiftEnableCaseSensitive,
                          boolean snowflakeQuotedIdentifiersIgnoreCase,
                          boolean mysqlAnsiQuotes) {
            this.mysqlLowerCaseTableNames = mysqlLowerCaseTableNames;
            this.defaultCollation = defaultCollation;
            this.redshiftEnableCaseSensitive = redshiftEnableCaseSensitive;
            this.snowflakeQuotedIdentifiersIgnoreCase = snowflakeQuotedIdentifiersIgnoreCase;
            this.mysqlAnsiQuotes = mysqlAnsiQuotes;
        }

        /**
         * 默认 flags（用于大部分数据库）
         */
        public static VendorFlags defaults() {
            return new VendorFlags(
                // MySQL lower_case_table_names = 1 (P0d.2): the unconfigured default keeps
                // the legacy case-INSENSITIVE table equality, and mode 1's LOWER fold keeps
                // keyForMap bucket keys coherent with that relation (mode 2 would bucket
                // case-variants apart while areEqual equates them). Mode 0 (Linux
                // case-sensitive) remains available through explicit configuration.
                1,
                "SQL_Latin1_General_CP1_CI_AS",  // SQL Server 默认 collation
                false,                        // Redshift case sensitive = false
                false                         // Snowflake quoted ignore case = false
            );
        }

        @Override
        public boolean equals(Object o) {
            if (this == o) return true;
            if (o == null || getClass() != o.getClass()) return false;
            VendorFlags that = (VendorFlags) o;
            return mysqlLowerCaseTableNames == that.mysqlLowerCaseTableNames &&
                   redshiftEnableCaseSensitive == that.redshiftEnableCaseSensitive &&
                   snowflakeQuotedIdentifiersIgnoreCase == that.snowflakeQuotedIdentifiersIgnoreCase &&
                   mysqlAnsiQuotes == that.mysqlAnsiQuotes &&
                   Objects.equals(defaultCollation, that.defaultCollation);
        }

        @Override
        public int hashCode() {
            return Objects.hash(mysqlLowerCaseTableNames, defaultCollation,
                              redshiftEnableCaseSensitive, snowflakeQuotedIdentifiersIgnoreCase,
                              mysqlAnsiQuotes);
        }
    }

    // ===== 构造函数 =====

    /**
     * 构造标识符配置档案
     *
     * @param vendor 数据库厂商
     * @param rulesByGroup 按对象组的规则
     * @param flags vendor-specific flags
     */
    private IdentifierProfile(EDbVendor vendor,
                             EnumMap<ObjectGroup, IdentifierRules> rulesByGroup,
                             EnumSet<ObjectGroup> overriddenGroups,
                             EnumMap<ESQLDataObjectType, IdentifierRules> rulesByType,
                             VendorFlags flags) {
        this.vendor = Objects.requireNonNull(vendor, "vendor");
        this.rulesByGroup = new EnumMap<>(Objects.requireNonNull(rulesByGroup, "rulesByGroup"));
        this.overriddenGroups = overriddenGroups == null || overriddenGroups.isEmpty()
            ? EnumSet.noneOf(ObjectGroup.class)
            : EnumSet.copyOf(overriddenGroups);
        this.rulesByType = rulesByType == null || rulesByType.isEmpty()
            ? new EnumMap<ESQLDataObjectType, IdentifierRules>(ESQLDataObjectType.class)
            : new EnumMap<>(rulesByType);
        this.flags = Objects.requireNonNull(flags, "flags");

        // Resolve every object type ONCE: explicit category override > a caller's group override
        // > the vendor's own rule for the category (defaultTypeRulesFor; MySQL indexes and
        // parameters) > the group's vendor-seeded rule. A type no rule singles out inherits its
        // group's rule, so a default profile keeps exactly the rules it had before per-category
        // configuration existed.
        EnumMap<ESQLDataObjectType, IdentifierRules> vendorTypeRules = defaultTypeRulesFor(vendor, flags);
        this.effectiveRules = new EnumMap<>(ESQLDataObjectType.class);
        for (ESQLDataObjectType type : ESQLDataObjectType.values()) {
            IdentifierRules override = this.rulesByType.get(type);
            if (override == null && !this.overriddenGroups.contains(mapToGroup(type))) {
                override = vendorTypeRules.get(type);
            }
            if (override == null) {
                override = this.rulesByGroup.get(mapToGroup(type));
            }
            if (override == null) {
                // A group slot is missing: the seed tables fill all three, so this can only be a
                // programming error inside this class. Fail loudly instead of comparing under null.
                throw new IllegalStateException("No identifier rules for " + type
                        + " (group " + mapToGroup(type) + ") on vendor " + vendor);
            }
            this.effectiveRules.put(type, override);
        }

        // Immutable → compute once; getFingerprint sits on the per-compare hot path
        // since areEqual/canonKey stamp keys with it (P0d). Since per-category configuration
        // exists the fingerprint must cover the WHOLE effective strategy: hashing only the three
        // group slots would let a table-only override share a fingerprint with the vendor default
        // and make two different policies look like one rule domain.
        this.fingerprint = Objects.hash(vendor, flags, this.effectiveRules);
    }

    private final long fingerprint;

    // ===== 工厂方法：根据厂商和 flags 创建 =====

    /**
     * 为指定厂商创建标识符配置档案
     *
     * @param vendor 数据库厂商
     * @param flags vendor-specific flags
     * @return 标识符配置档案
     */
    public static IdentifierProfile forVendor(EDbVendor vendor, VendorFlags flags) {
        Objects.requireNonNull(vendor, "vendor");
        Objects.requireNonNull(flags, "flags");
        if (DEFAULT_FLAGS.equals(flags)) {
            // The overwhelmingly common call. Profiles are immutable, so one shared instance per
            // vendor is safe, and it keeps the per-type resolution below off hot paths that build
            // a profile per AST node (TObjectName.getIdentifierService).
            IdentifierProfile cached = DEFAULT_FLAG_PROFILES.get(vendor);
            if (cached == null) {
                cached = new IdentifierProfile(vendor, defaultRulesFor(vendor, flags), null, null, flags);
                IdentifierProfile raced = DEFAULT_FLAG_PROFILES.putIfAbsent(vendor, cached);
                if (raced != null) {
                    cached = raced;
                }
            }
            return cached;
        }
        return new IdentifierProfile(vendor, defaultRulesFor(vendor, flags), null, null, flags);
    }

    /**
     * {@code configured} when it is a configuration for {@code vendor}, else that vendor's
     * default profile.
     *
     * <p>For the places that build an object of a dialect an analysis may or may not be configured
     * for — a metadata file that declares its own {@code dbVendor}, nested SQL in another dialect.
     * A profile belongs to exactly one vendor, so it is never transplanted onto another: rules
     * chosen for BigQuery tables say nothing about Oracle's.
     *
     * @param configured the analysis's configuration, or null when there is none
     * @param vendor the vendor the caller actually needs a profile for
     * @return a profile for {@code vendor}; never null
     */
    public static IdentifierProfile forVendorOr(IdentifierProfile configured, EDbVendor vendor) {
        if (configured != null && configured.getVendor() == vendor) {
            return configured;
        }
        return forVendor(vendor, VendorFlags.defaults());
    }

    private static final VendorFlags DEFAULT_FLAGS = VendorFlags.defaults();

    private static final ConcurrentHashMap<EDbVendor, IdentifierProfile> DEFAULT_FLAG_PROFILES =
            new ConcurrentHashMap<EDbVendor, IdentifierProfile>();

    // ===== Builder entry points =====

    /**
     * Create a builder seeded from default rules for the given vendor
     * with default VendorFlags.
     *
     * @param vendor database vendor
     * @return a new Builder
     */
    public static Builder builder(EDbVendor vendor) {
        return builder(vendor, VendorFlags.defaults());
    }

    /**
     * Create a builder seeded from default rules for the given vendor
     * and the specified VendorFlags.
     *
     * @param vendor database vendor
     * @param flags vendor-specific flags
     * @return a new Builder
     */
    public static Builder builder(EDbVendor vendor, VendorFlags flags) {
        Objects.requireNonNull(vendor, "vendor");
        Objects.requireNonNull(flags, "flags");
        return new Builder(vendor, flags, defaultRulesFor(vendor, flags));
    }

    /**
     * Create a builder pre-populated from this profile's current state.
     * Enables deriving a variant without re-specifying everything.
     *
     * @return a new Builder seeded from this profile
     */
    public Builder toBuilder() {
        Builder builder = new Builder(this.vendor, this.flags, new EnumMap<>(this.rulesByGroup));
        builder.typeOverrides.putAll(this.rulesByType);
        // The seed now holds this profile's group overrides; remember which they are, so they keep
        // outranking the vendor's per-category rules in the derived profile too.
        builder.seededGroupOverrides.addAll(this.overriddenGroups);
        return builder;
    }

    // ===== Internal: single source of truth for default rules =====

    /**
     * Compute the default per-group rules for the given vendor and flags.
     * This is the sole source of truth for default rules -- both forVendor()
     * and the Builder use this method.
     *
     * @param vendor database vendor
     * @param flags vendor-specific flags
     * @return mutable EnumMap with rules for all three groups
     */
    static EnumMap<ObjectGroup, IdentifierRules> defaultRulesFor(EDbVendor vendor, VendorFlags flags) {
        EnumMap<ObjectGroup, IdentifierRules> rules = new EnumMap<>(ObjectGroup.class);

        switch (vendor) {
            case dbvoracle: {
                // Verified on Oracle 23.26 (2026-10-11). The Oracle-shaped forks below keep
                // forOracle() until their own engines are verified.
                IdentifierRules rule = IdentifierRules.forOracleNative();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvdameng: {
                IdentifierRules rule = IdentifierRules.forDameng();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvpostgresql: {
                // Verified on PostgreSQL 16.15, UTF8 (2026-10-11).
                IdentifierRules rule = IdentifierRules.forPostgreSQLNative();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvgreenplum:
            case dbvgaussdb:
            case dbvedb: {
                // PostgreSQL forks: not verified on their own engines, so they keep the shape they
                // shared with PostgreSQL before 2026-10-11.
                IdentifierRules rule = IdentifierRules.forPostgreSQL();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvduckdb: {
                IdentifierRules rule = IdentifierRules.forDuckDB();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvsqlite: {
                IdentifierRules rule = IdentifierRules.forSqlite();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvfirebird: {
                IdentifierRules rule = IdentifierRules.forFirebird();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvsybase:
            case dbvsybasease: {
                IdentifierRules rule = IdentifierRules.forSybase();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvsybaseiq:
            case dbvsqlanywhere: {
                IdentifierRules rule = IdentifierRules.forSqlAnywhere();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvaccess: {
                IdentifierRules rule = IdentifierRules.forAccess();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvdax: {
                IdentifierRules rule = IdentifierRules.forDax();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvmdx: {
                IdentifierRules rule = IdentifierRules.forMdx();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvpowerquery: {
                IdentifierRules rule = IdentifierRules.forPowerQuery();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvansi:
            case dbvgeneric:
            case dbvodbc: {
                IdentifierRules rule = IdentifierRules.forAnsi();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvredshift: {
                IdentifierRules rule = flags.redshiftEnableCaseSensitive
                    ? IdentifierRules.forCouchbase()
                    : IdentifierRules.forRedshift();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvclickhouse: {
                IdentifierRules rule = IdentifierRules.forCouchbase();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvcouchbase: {
                IdentifierRules rule = IdentifierRules.forCouchbase();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvmssql:
            case dbvazuresql: {
                IdentifierRules rule = IdentifierRules.forSQLServer(flags.defaultCollation);
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvmysql: {
                // Verified on MySQL 8.4.10 (2026-10-11); indexes and parameters get their own
                // rules in defaultTypeRulesFor. OceanBase, Doris and StarRocks keep the old cells.
                rules.put(ObjectGroup.NAME_GROUP,
                         IdentifierRules.forMySQLNative(flags.mysqlLowerCaseTableNames));
                rules.put(ObjectGroup.COLUMN_GROUP, IdentifierRules.forMySQLNativeColumn());
                rules.put(ObjectGroup.ROUTINE_GROUP, IdentifierRules.forMySQLNativeRoutine());
                break;
            }

            case dbvoceanbase: {
                // Phase 1: identifier rules mirror MySQL because the default
                // EOBTenantMode is MYSQL and the IdentifierProfile is built
                // before the user has had a chance to call setOBTenantMode.
                // TODO(oceanbase Phase 3): split this into MYSQL/ORACLE
                // branches once the EOBTenantMode is queryable from
                // IdentifierProfileFlags or wherever the profile is built.
                rules.put(ObjectGroup.NAME_GROUP,
                         IdentifierRules.forMySQL(flags.mysqlLowerCaseTableNames));
                rules.put(ObjectGroup.COLUMN_GROUP, IdentifierRules.forMySQLColumn());
                rules.put(ObjectGroup.ROUTINE_GROUP, IdentifierRules.forMySQLRoutine());
                break;
            }

            case dbvdoris: {
                rules.put(ObjectGroup.NAME_GROUP, IdentifierRules.forDoris());
                rules.put(ObjectGroup.COLUMN_GROUP, IdentifierRules.forDorisColumn());
                rules.put(ObjectGroup.ROUTINE_GROUP, IdentifierRules.forMySQLRoutine());
                break;
            }

            case dbvstarrocks: {
                rules.put(ObjectGroup.NAME_GROUP, IdentifierRules.forStarrocks());
                rules.put(ObjectGroup.COLUMN_GROUP, IdentifierRules.forStarrocksColumn());
                rules.put(ObjectGroup.ROUTINE_GROUP, IdentifierRules.forMySQLRoutine());
                break;
            }

            case dbvbigquery: {
                rules.put(ObjectGroup.NAME_GROUP, IdentifierRules.forBigQueryTable());
                rules.put(ObjectGroup.COLUMN_GROUP, IdentifierRules.forBigQueryColumn());
                rules.put(ObjectGroup.ROUTINE_GROUP, IdentifierRules.forBigQueryTable());
                break;
            }

            case dbvdb2:
            case dbvnetezza:
            case dbvexasol: {
                IdentifierRules rule = IdentifierRules.forDB2();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvsnowflake: {
                IdentifierRules rule = IdentifierRules.forSnowflake(
                    flags.snowflakeQuotedIdentifiersIgnoreCase);
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvhana: {
                IdentifierRules rule = IdentifierRules.forHANA();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvpresto:
            case dbvtrino: {
                IdentifierRules rule = IdentifierRules.forPresto();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvvertica: {
                IdentifierRules rule = IdentifierRules.forVertica();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvhive:
            case dbvsparksql:
            case dbvimpala:
            case dbvdatabricks: {
                IdentifierRules rule = IdentifierRules.forHive();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvflink: {
                IdentifierRules rule = IdentifierRules.forFlink();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvteradata: {
                IdentifierRules rule = IdentifierRules.forTeradata();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            case dbvathena: {
                IdentifierRules rule = IdentifierRules.forAthena();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }

            default: {
                // Vendors without a documented rule of their own here (Informix, OpenEdge, SOQL)
                // keep the PostgreSQL shape they have always had.
                IdentifierRules rule = IdentifierRules.forPostgreSQL();
                rules.put(ObjectGroup.NAME_GROUP, rule);
                rules.put(ObjectGroup.COLUMN_GROUP, rule);
                rules.put(ObjectGroup.ROUTINE_GROUP, rule);
                break;
            }
        }

        return rules;
    }

    /**
     * A vendor's own rule for single object categories that do not follow their group, under the
     * given flags. Empty for every vendor but MySQL.
     *
     * <p>MySQL (verified on 8.4.10): index names do not follow {@code lower_case_table_names} —
     * they compare like column names (under mode 0, {@code INDEX Idx} then {@code ADD INDEX idx}
     * fails with ERROR 1061) — and routine parameters compare like routine names
     * ({@code CREATE PROCEDURE pr(P int, p int)} fails with ERROR 1330). Both categories stay in
     * NAME_GROUP (moving them would regroup them for every vendor); only their rule differs.
     *
     * <p>Precedence: an explicit category override and a caller's group override both win over
     * these; they win over the group's vendor-seeded rule.
     */
    static EnumMap<ESQLDataObjectType, IdentifierRules> defaultTypeRulesFor(EDbVendor vendor,
                                                                           VendorFlags flags) {
        EnumMap<ESQLDataObjectType, IdentifierRules> rules = new EnumMap<>(ESQLDataObjectType.class);
        if (vendor == EDbVendor.dbvmysql) {
            rules.put(ESQLDataObjectType.dotIndex, IdentifierRules.forMySQLNativeColumn());
            rules.put(ESQLDataObjectType.dotParameter, IdentifierRules.forMySQLNativeRoutine());
        }
        return rules;
    }

    // ===== Builder inner class =====

    /**
     * Builder for creating customized IdentifierProfile instances.
     *
     * <p>The builder is seeded from vendor defaults. Overrides can be applied
     * per object group. The built profile is immutable.
     *
     * <p>Usage example:
     * <pre>
     * IdentifierProfile profile = IdentifierProfile
     *     .builder(EDbVendor.dbvmssql)
     *     .withColumnRules(customColumnRules)
     *     .build();
     * </pre>
     */
    public static final class Builder {

        private EDbVendor vendor;
        private VendorFlags flags;
        private EnumMap<ObjectGroup, IdentifierRules> seededRules;
        private final EnumMap<ObjectGroup, IdentifierRules> overrides;
        private final EnumMap<ESQLDataObjectType, IdentifierRules> typeOverrides;
        /** Groups whose SEED came from a profile's group override ({@link IdentifierProfile#toBuilder}). */
        private final EnumSet<ObjectGroup> seededGroupOverrides = EnumSet.noneOf(ObjectGroup.class);

        Builder(EDbVendor vendor, VendorFlags flags,
                EnumMap<ObjectGroup, IdentifierRules> seedRules) {
            this.vendor = vendor;
            this.flags = flags;
            this.seededRules = new EnumMap<>(seedRules);
            this.overrides = new EnumMap<>(ObjectGroup.class);
            this.typeOverrides = new EnumMap<>(ESQLDataObjectType.class);
        }

        /**
         * Override VendorFlags (replaces default-seeded flags).
         * Re-seeds rules that depend on flags while preserving
         * explicit overrides set via withRules().
         *
         * @param flags new vendor flags
         * @return this builder
         */
        public Builder withFlags(VendorFlags flags) {
            this.flags = Objects.requireNonNull(flags, "flags");
            this.seededRules = defaultRulesFor(this.vendor, flags);
            // The seed is the vendor's again: nothing in it is a caller's override any more.
            this.seededGroupOverrides.clear();
            return this;
        }

        /**
         * Override the rules for a specific object group.
         *
         * @param group the object group to override
         * @param rules the custom rules
         * @return this builder
         */
        public Builder withRules(ObjectGroup group, IdentifierRules rules) {
            Objects.requireNonNull(group, "group");
            Objects.requireNonNull(rules, "rules");
            overrides.put(group, rules);
            return this;
        }

        /**
         * Convenience: override NAME_GROUP rules.
         *
         * @param rules the custom rules for names
         * @return this builder
         */
        public Builder withNameRules(IdentifierRules rules) {
            return withRules(ObjectGroup.NAME_GROUP, rules);
        }

        /**
         * Convenience: override COLUMN_GROUP rules.
         *
         * @param rules the custom rules for columns
         * @return this builder
         */
        public Builder withColumnRules(IdentifierRules rules) {
            return withRules(ObjectGroup.COLUMN_GROUP, rules);
        }

        /**
         * Convenience: override ROUTINE_GROUP rules.
         *
         * @param rules the custom rules for routines
         * @return this builder
         */
        public Builder withRoutineRules(IdentifierRules rules) {
            return withRules(ObjectGroup.ROUTINE_GROUP, rules);
        }

        /**
         * Override the rules of ONE object category — catalog/project, schema, table, column,
         * function … — independently of every other category (design §5.1).
         *
         * <p>This is the finest granularity and wins over a {@link #withRules(ObjectGroup,
         * IdentifierRules) group} override and over the vendor default. It is deliberately a new
         * name rather than an overload of {@code withRules}: {@code withRules(null, rules)} would
         * become ambiguous, and an object CATEGORY is not an object group.
         *
         * <p>The argument is a category, never the name of a particular dataset, table or column —
         * a profile expresses "how table names compare here", not "this table compares like that".
         *
         * <p>Repeating a category keeps the LAST value. To go back to inheriting, call
         * {@link #withoutObjectRules(ESQLDataObjectType)}; {@code null} rules are rejected rather
         * than treated as some implicit rule.
         *
         * <p>Note what a category override does and does not claim: it is the analysis assumption
         * the CALLER supplies. It is not read from a live server, and an arbitrary override is not
         * automatically a vendor's native semantics.
         *
         * @param objectType the object category to configure
         * @param rules the complete rule cell (unquoted fold/compare, quoted fold/compare)
         * @return this builder
         */
        public Builder withObjectRules(ESQLDataObjectType objectType, IdentifierRules rules) {
            Objects.requireNonNull(objectType, "objectType");
            Objects.requireNonNull(rules, "rules");
            typeOverrides.put(objectType, rules);
            return this;
        }

        /**
         * Drop a category override set earlier, so the category inherits its group / vendor rule
         * again. A category that was never overridden is unaffected.
         *
         * @param objectType the object category to stop overriding
         * @return this builder
         */
        public Builder withoutObjectRules(ESQLDataObjectType objectType) {
            Objects.requireNonNull(objectType, "objectType");
            typeOverrides.remove(objectType);
            return this;
        }

        /**
         * Drop a group override set earlier, so the group falls back to the vendor-seeded rule.
         * Category overrides are untouched — they sit above the group level.
         *
         * @param group the object group to stop overriding
         * @return this builder
         */
        public Builder withoutRules(ObjectGroup group) {
            Objects.requireNonNull(group, "group");
            overrides.remove(group);
            return this;
        }

        /**
         * Build an immutable IdentifierProfile.
         * Merges seeded rules with overrides (overrides win), then applies per-category overrides.
         *
         * @return the built profile
         */
        public IdentifierProfile build() {
            EnumMap<ObjectGroup, IdentifierRules> merged = new EnumMap<>(seededRules);
            merged.putAll(overrides);
            EnumSet<ObjectGroup> overridden = EnumSet.copyOf(seededGroupOverrides);
            overridden.addAll(overrides.keySet());
            return new IdentifierProfile(vendor, merged, overridden, typeOverrides, flags);
        }
    }

    // ===== 查询接口 =====

    /**
     * 获取指定对象类型的标识符规则
     *
     * @param objectType 对象类型
     * @return 标识符规则
     */
    public IdentifierRules getRules(ESQLDataObjectType objectType) {
        if (objectType == null) {
            // Historic behavior of mapToGroup(null): an unstated category is a plain name.
            return rulesByGroup.get(ObjectGroup.NAME_GROUP);
        }
        return effectiveRules.get(objectType);
    }

    /**
     * The effective rule cell of one object category with {@code SAME_AS_UNQUOTED} resolved —
     * the <em>rule domain</em> a {@link CanonKey} of that category belongs to.
     *
     * <p>Since categories inside one {@link ObjectGroup} may now carry different rules, the
     * group alone no longer identifies the domain a canonical payload was produced in: with
     * tables insensitive and schemas sensitive, a table keyed as {@code orders} and a schema
     * literally named {@code orders} would otherwise produce equal keys. Two categories with the
     * same effective cell share a domain, which is what keeps a default profile's
     * table/schema/catalog keys interchangeable exactly as before.
     *
     * @param objectType the object category
     * @return the resolved rule cell; never null
     */
    public IdentifierRules ruleDomainOf(ESQLDataObjectType objectType) {
        return getRules(objectType).resolvedCell();
    }

    /**
     * Whether this profile and {@code other} are the SAME effective strategy: same vendor, same
     * flags, and the same resolved rule for every object category — regardless of how each was
     * built (vendor default, group override, category override) or of object identity.
     *
     * <p>The {@link #getFingerprint() fingerprint} is a hash: it can accelerate this answer but
     * must never stand in for it, since distinct strategies can collide in 32 bits.
     *
     * @param other the profile to compare with; null is never the same strategy
     * @return true if the two profiles decide every identifier question identically
     */
    public boolean hasSameEffectivePolicyAs(IdentifierProfile other) {
        if (this == other) {
            return true;
        }
        if (other == null) {
            return false;
        }
        return vendor == other.vendor
                && flags.equals(other.flags)
                && effectiveRules.equals(other.effectiveRules);
    }

    /**
     * Value equality over the complete effective strategy — see
     * {@link #hasSameEffectivePolicyAs}. Two profiles that decide every identifier question the
     * same way ARE the same profile, so an equivalent instance passed at a second entry point
     * does not read as a conflicting configuration.
     */
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof IdentifierProfile)) {
            return false;
        }
        return hasSameEffectivePolicyAs((IdentifierProfile) o);
    }

    @Override
    public int hashCode() {
        return (int) fingerprint;
    }

    /**
     * The categories this profile configures explicitly, finest granularity first. Diagnostics
     * only — the strategy itself is {@link #getRules}.
     *
     * @return an unmodifiable view of the per-category overrides
     */
    public Map<ESQLDataObjectType, IdentifierRules> getObjectRuleOverrides() {
        return Collections.unmodifiableMap(rulesByType);
    }

    /**
     * 获取 vendor flags
     *
     * @return vendor flags
     */
    public VendorFlags getFlags() {
        return flags;
    }

    /**
     * 获取数据库厂商
     *
     * @return 厂商
     */
    public EDbVendor getVendor() {
        return vendor;
    }

    /**
     * 按对象组获取规则（内部使用）
     *
     * <p>This is the GROUP-level rule — the value a category inherits when it carries no
     * {@link Builder#withObjectRules} override. It is NOT what governs a comparison; only
     * {@link #getRules(ESQLDataObjectType)} is. Nothing that decides equality may read this.
     *
     * @param group 对象组
     * @return 标识符规则
     */
    IdentifierRules getRulesByGroup(ObjectGroup group) {
        return rulesByGroup.get(group);
    }

    /**
     * 将对象类型映射到对象组（公开访问器，供 {@link CanonKey} 的规则域标识使用）
     *
     * @param objectType 对象类型
     * @return 对象组
     */
    public ObjectGroup groupOf(ESQLDataObjectType objectType) {
        return mapToGroup(objectType);
    }

    /**
     * 将对象类型映射到对象组
     */
    private ObjectGroup mapToGroup(ESQLDataObjectType type) {
        if (type == null) return ObjectGroup.NAME_GROUP;

        // Fail-closed and exhaustive on purpose (stage S0R). A `default: NAME_GROUP` looked
        // harmless but meant a NEW object type silently acquired the name rules — and a test
        // asserting "the group is non-null" could not tell the difference. Every value is listed;
        // a new one fails here until someone assigns it deliberately.
        switch (type) {
            case dotColumn:
                return ObjectGroup.COLUMN_GROUP;

            // All four routine-like types share the routine comparison group. Only dotFunction
            // used to, which was a defect rather than a namespace statement:
            // CatalogModelValidator works around it by comparing every routine as dotFunction,
            // and its test proves why — MySQL with lower_case_table_names=0 still treats `Proc`
            // and `proc` as one procedure name. The four ESQLDataObjectType values stay distinct
            // because quoting can differ per type (DAX), but their CASE rules are the same.
            case dotRoutine:
            case dotFunction:
            case dotProcedure:
            case dotOraclePackage:
                return ObjectGroup.ROUTINE_GROUP;

            case dotUnknown:
            case dotCatalog:
            case dotSchema:
            case dotTable:
            case dotTrigger:
            case dotSynonyms:
            case dotDblink:
            case dotDataType:
            case dotParameter:
            case dotServer:
            case dotSequence:
            case dotIndex:
            case dotConstraint:
                return ObjectGroup.NAME_GROUP;

            default:
                throw new IllegalStateException("No object group for " + type
                        + " - add it explicitly to IdentifierProfile.mapToGroup");
        }
    }

    // ===== 指纹计算（用于缓存失效） =====

    /**
     * 计算配置指纹（用于 TObjectName 缓存失效）
     *
     * <p>当 vendor 或 flags 变化时，指纹会改变，触发缓存失效
     *
     * @return 配置指纹（64位哈希值）
     */
    public long getFingerprint() {
        return fingerprint;
    }

    // ===== toString 方法（用于调试） =====

    @Override
    public String toString() {
        if (rulesByType.isEmpty()) {
            return String.format("IdentifierProfile{vendor=%s, flags=%s}", vendor, flags);
        }
        return String.format("IdentifierProfile{vendor=%s, flags=%s, objectRules=%s}",
            vendor, flags, rulesByType);
    }
}