@roll-agent/octopus-agent 0.1.3 → 0.2.0

package/src/octopus_skill/sql_generator.py

@@ -1,2866 +0,0 @@
-from __future__ import annotations
-
-from datetime import date, timedelta
-import re
-from dataclasses import dataclass
-from typing import Any
-
-from .schema_context_retriever import _schema_enums as merged_schema_enums
-
-
-class SqlGenerationError(RuntimeError):
-    pass
-
-
-@dataclass(frozen=True)
-class GeneratedSql:
-    sql: str
-    tables: list[str]
-    placeholders: list[str]
-    used_columns: list[str] | None = None
-    used_joins: list[str] | None = None
-    metric_refs: list[str] | None = None
-    clarification: dict[str, Any] | None = None
-
-
-@dataclass(frozen=True)
-class TimeRange:
-    field: str
-    alias: str
-    start: str
-    end: str
-    table_name: str = ""
-
-
-@dataclass(frozen=True)
-class FieldRef:
-    name: str
-    alias: str
-    table_name: str = ""
-
-
-@dataclass(frozen=True)
-class SchemaValidationIssue:
-    code: str
-    message: str
-
-
-@dataclass(frozen=True)
-class LowQualitySqlIssue:
-    code: str
-    message: str
-    missing_items: tuple[str, ...] = ()
-    current_problem: str = ""
-    repair_hint: str = ""
-
-
-_SELECT_AS_ALIAS_PATTERN = (
-    r"\s+as\s+(`[^`]+`|\"[^\"]+\"|'[^']+'|\w+)\s*$"
-)
-
-_FORBIDDEN_DML_KEYWORDS = re.compile(
-    r"\b(insert|update|delete|drop|alter|create|truncate)\b",
-    flags=re.IGNORECASE,
-)
-
-
-def _sql_without_string_literals(sql: str) -> str:
-    return re.sub(r"'([^']|'')*'", "''", sql)
-
-
-def contains_forbidden_dml_keyword(sql: str) -> bool:
-    stripped = _sql_without_string_literals(sql.strip())
-    return _FORBIDDEN_DML_KEYWORDS.search(stripped) is not None
-
-
-def enforce_sql_rules(sql: str, *, max_limit: int) -> None:
-    normalized = sql.strip().lower()
-    if not normalized.startswith("select "):
-        raise SqlGenerationError("SQL must be SELECT only")
-    if ";" in normalized.rstrip(";"):
-        raise SqlGenerationError("SQL must be a single statement")
-    if contains_forbidden_dml_keyword(sql):
-        raise SqlGenerationError("SQL contains a forbidden keyword")
-    if re.search(r"\b(password|token|secret|credential|private_key)\b", normalized):
-        raise SqlGenerationError("SQL contains a sensitive field")
-    if _sql_selects_sensitive_field(sql):
-        raise SqlGenerationError("SQL contains a sensitive field")
-    if ":scope." in normalized:
-        raise SqlGenerationError("SQL must not contain scope placeholders")
-    _enforce_text_filters_use_like(sql)
-    _enforce_join_on_uses_equality_keys(sql)
-    _enforce_no_aggregate_functions_in_row_filters(sql)
-    _enforce_chinese_select_aliases(sql)
-    _enforce_no_null_placeholder_select_items(sql)
-    _enforce_no_tautological_join_conditions(sql)
-    limit = re.search(r"\blimit\s+(\d+)\b", normalized)
-    if limit is None:
-        raise SqlGenerationError("SQL must contain LIMIT")
-    if int(limit.group(1)) > max_limit:
-        raise SqlGenerationError(f"SQL LIMIT must not exceed {max_limit}")
-
-
-def build_schema_validation_error(
-    sql: str,
-    issues: list[SchemaValidationIssue],
-    schema: dict[str, Any],
-    *,
-    attempt: int | None = None,
-    max_attempts: int | None = None,
-) -> dict[str, Any]:
-    """Build a repair payload listing every schema violation and column hints."""
-    schema_issues = [{"code": issue.code, "message": issue.message} for issue in issues]
-    codes = {issue.code for issue in issues}
-    if len(codes) == 1:
-        code = next(iter(codes))
-    else:
-        code = "SCHEMA_VALIDATION"
-    if len(issues) == 1:
-        message = issues[0].message
-    elif issues:
-        message = f"共 {len(issues)} 项 schema 校验失败：{issues[0].message}"
-    else:
-        message = "schema 校验失败"
-    payload: dict[str, Any] = {
-        "code": code,
-        "message": message,
-        "originalSql": sql,
-        "schemaIssues": schema_issues,
-    }
-    unknown_refs = _unknown_column_refs_from_issues(issues)
-    if unknown_refs:
-        payload["suggestedColumns"] = suggest_columns_for_unknown(unknown_refs, schema)
-    if any(issue.code == "MISSING_TABLE_REFERENCE" for issue in issues):
-        payload["tableReferenceRepairHint"] = (
-            "SQL 引用了未在 FROM/JOIN 中声明的表名或别名。"
-            "如果该字段确实需要参与查询，必须按 schema relations / joins 补 JOIN；"
-            "如果不需要该表，则删除对应 SELECT/WHERE/ON/GROUP/ORDER 条件。"
-        )
-    if any(issue.code == "INVALID_JOIN" for issue in issues):
-        payload["joinRepairHint"] = (
-            "禁止用 ON 1=0 / ON 1=1 / ON false / ON true 规避 JOIN 校验；"
-            "必须按 schemaContext.exampleGuidance、exampleJoinPatterns 与 structureHints 重建真实 JOIN。"
-        )
-        payload["suggestedJoinPatterns"] = suggest_join_patterns_for_schema(schema)
-    if attempt is not None:
-        payload["attempt"] = attempt
-    if max_attempts is not None:
-        payload["maxAttempts"] = max_attempts
-    return payload
-
-
-def build_execute_unknown_column_error(
-    sql: str,
-    column_ref: str,
-    schema: dict[str, Any],
-    *,
-    attempt: int | None = None,
-    max_attempts: int | None = None,
-) -> dict[str, Any]:
-    """Build a repair payload when execute_sql reports a missing column."""
-    table_name, column_name = _split_sql_column_ref(column_ref)
-    if table_name and column_name:
-        message = f"SQL 使用了数据库中不存在的列：{table_name}.{column_name}"
-        issue = SchemaValidationIssue(code="UNKNOWN_COLUMN", message=message)
-    else:
-        message = f"SQL 使用了数据库中不存在的列：{column_ref}"
-        issue = SchemaValidationIssue(code="UNKNOWN_COLUMN", message=message)
-    return build_schema_validation_error(
-        sql,
-        [issue],
-        schema,
-        attempt=attempt,
-        max_attempts=max_attempts,
-    )
-
-
-def _split_sql_column_ref(column_ref: str) -> tuple[str, str]:
-    cleaned = column_ref.strip().strip("`")
-    if "." not in cleaned:
-        return "", cleaned
-    table_name, column_name = cleaned.rsplit(".", 1)
-    return table_name, column_name
-
-
-def _unknown_column_refs_from_issues(issues: list[SchemaValidationIssue]) -> list[tuple[str, str]]:
-    refs: list[tuple[str, str]] = []
-    seen: set[tuple[str, str]] = set()
-    for issue in issues:
-        if issue.code != "UNKNOWN_COLUMN":
-            continue
-        match = re.search(
-            r"不存在的列：([A-Za-z_][\w]*)\.([A-Za-z_][\w]*)",
-            issue.message,
-        )
-        if not match:
-            continue
-        key = (match.group(1).lower(), match.group(2).lower())
-        if key in seen:
-            continue
-        seen.add(key)
-        refs.append(key)
-    return refs
-
-
-def suggest_columns_for_unknown(
-    missing: list[tuple[str, str]],
-    schema: dict[str, Any],
-) -> list[dict[str, str]]:
-    """Find same column name on other tables when SQL references a non-existent column."""
-    column_map = _schema_table_column_map(schema)
-    suggestions: list[dict[str, str]] = []
-    seen: set[tuple[str, str]] = set()
-    for wrong_table, column in missing:
-        for table, columns in sorted(column_map.items()):
-            if table == wrong_table or column not in columns:
-                continue
-            key = (table, column)
-            if key in seen:
-                continue
-            seen.add(key)
-            suggestions.append(
-                {
-                    "table": table,
-                    "column": column,
-                    "message": f"列 {column} 存在于 {table}，不存在于 {wrong_table}",
-                }
-            )
-    return suggestions
-
-
-def build_sql_rule_validation_error(
-    sql: str,
-    exc: SqlGenerationError,
-    *,
-    max_limit: int,
-    attempt: int | None = None,
-    max_attempts: int | None = None,
-) -> dict[str, Any]:
-    """Build a repair payload with the failing SQL and concrete violating SELECT items."""
-    message = str(exc)
-    payload: dict[str, Any] = {
-        "code": "SQL_RULE_VIOLATION",
-        "message": message,
-        "originalSql": sql,
-        "violatingColumns": list_sql_rule_violating_items(sql, message, max_limit=max_limit),
-    }
-    if attempt is not None:
-        payload["attempt"] = attempt
-    if max_attempts is not None:
-        payload["maxAttempts"] = max_attempts
-    return payload
-
-
-def list_sql_rule_violating_items(sql: str, message: str, *, max_limit: int) -> list[str]:
-    lowered = message.lower()
-    if "chinese alias" in lowered:
-        return _list_missing_chinese_alias_select_items(sql)
-    if "null placeholders" in lowered:
-        return _list_null_placeholder_select_items(sql)
-    if "sensitive field" in lowered:
-        return _list_sensitive_select_items(sql)
-    if "must be select only" in lowered:
-        return ["(entire statement is not a single SELECT)"]
-    if "must contain limit" in lowered:
-        return ["(missing LIMIT clause)"]
-    if "must not exceed" in lowered and "limit" in lowered:
-        return ["(LIMIT exceeds allowed maximum)"]
-    if "scope placeholders" in lowered:
-        return re.findall(r":scope\.\w+", sql, flags=re.IGNORECASE)
-    if "like" in lowered:
-        return _list_text_filter_violations(sql)
-    return []
-
-
-def _list_missing_chinese_alias_select_items(sql: str) -> list[str]:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return ["(missing top-level FROM clause)"]
-    violations: list[str] = []
-    for item in _split_top_level_select_items(select_list):
-        cleaned = item.strip()
-        if not cleaned:
-            continue
-        alias_match = re.search(
-            _SELECT_AS_ALIAS_PATTERN,
-            cleaned,
-            flags=re.IGNORECASE,
-        )
-        if alias_match is None:
-            violations.append(cleaned)
-            continue
-        alias = alias_match.group(1).strip("`\"'")
-        if re.search(r"[\u4e00-\u9fff]", alias) is None:
-            violations.append(cleaned)
-    return violations
-
-
-def _list_null_placeholder_select_items(sql: str) -> list[str]:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return []
-    return [
-        item.strip()
-        for item in _split_top_level_select_items(select_list)
-        if item.strip() and _is_null_placeholder_expression(_select_expression_without_alias(item))
-    ]
-
-
-def _list_sensitive_select_items(sql: str) -> list[str]:
-    select_clause = _top_level_select_clause(sql)
-    if select_clause is None:
-        return []
-    return [item.strip() for item in _split_select_items(select_clause) if _select_item_contains_sensitive_field(item)]
-
-
-def _list_text_filter_violations(sql: str) -> list[str]:
-    return re.findall(
-        r"(?i)(?:\b[\w.]+\b)\s*=\s*'[^']*(?:名称|状态|品牌|城市|项目|门店|供应商|工单)[^']*'",
-        sql,
-    )
-
-
-SENSITIVE_FIELD_NAMES = {
-    "phone",
-    "mobile",
-    "tel",
-    "telephone",
-    "phone_number",
-    "mobile_number",
-    "mobile_phone",
-    "contact_phone",
-    "contact_mobile",
-    "contact_tel",
-    "id_card",
-    "idcard",
-    "identity_card",
-    "cert_no",
-    "certificate_no",
-    "password",
-    "token",
-    "secret",
-    "credential",
-    "private_key",
-}
-SENSITIVE_FIELD_SUFFIXES = ("_phone", "_mobile", "_tel")
-SENSITIVE_FIELD_LABELS = (
-    "手机号",
-    "手机号码",
-    "电话",
-    "电话号码",
-    "联系方式",
-    "身份证",
-    "身份证号",
-    "身份证号码",
-    "密码",
-    "令牌",
-    "密钥",
-    "凭证",
-)
-
-
-def sensitive_terms_in_text(text: str) -> list[str]:
-    lowered = text.lower()
-    terms: list[str] = []
-    for label in SENSITIVE_FIELD_LABELS:
-        if label in text:
-            terms.append(label)
-    english_terms = {
-        "phone": "手机号",
-        "mobile": "手机号",
-        "tel": "电话",
-        "telephone": "电话",
-        "id_card": "身份证",
-        "idcard": "身份证",
-        "password": "密码",
-        "token": "令牌",
-        "secret": "密钥",
-    }
-    for term, label in english_terms.items():
-        if re.search(rf"\b{re.escape(term)}\b", lowered) and label not in terms:
-            terms.append(label)
-    return list(dict.fromkeys(terms))
-
-
-def _sql_selects_sensitive_field(sql: str) -> bool:
-    select_clause = _top_level_select_clause(sql)
-    if select_clause is None:
-        return False
-    return any(_select_item_contains_sensitive_field(item) for item in _split_select_items(select_clause))
-
-
-def _top_level_select_clause(sql: str) -> str | None:
-    match = re.search(r"\bselect\b(?P<select>.*?)\bfrom\b", sql, flags=re.IGNORECASE | re.DOTALL)
-    if match is None:
-        return None
-    return match.group("select")
-
-
-def _split_select_items(select_clause: str) -> list[str]:
-    items: list[str] = []
-    start = 0
-    depth = 0
-    quote: str | None = None
-    for index, char in enumerate(select_clause):
-        if quote is not None:
-            if char == quote:
-                quote = None
-            continue
-        if char in {"'", '"', "`"}:
-            quote = char
-        elif char == "(":
-            depth += 1
-        elif char == ")" and depth > 0:
-            depth -= 1
-        elif char == "," and depth == 0:
-            items.append(select_clause[start:index].strip())
-            start = index + 1
-    tail = select_clause[start:].strip()
-    if tail:
-        items.append(tail)
-    return items
-
-
-def _select_item_contains_sensitive_field(item: str) -> bool:
-    if any(label in item for label in SENSITIVE_FIELD_LABELS):
-        return True
-    identifiers = re.findall(r"\b[a-zA-Z_][a-zA-Z0-9_]*\b", item.lower())
-    for identifier in identifiers:
-        if identifier in {"select", "case", "when", "then", "else", "end", "as", "if", "null", "coalesce"}:
-            continue
-        if identifier in SENSITIVE_FIELD_NAMES or identifier.endswith(SENSITIVE_FIELD_SUFFIXES):
-            return True
-    return False
-
-
-_TEXT_EQUALITY_FILTER_RE = re.compile(
-    r"(?P<prefix>\b(?:WHERE|AND|OR|HAVING)\s+\(?\s*)"
-    r"(?P<column>(?:[a-zA-Z_][A-Za-z0-9_]*\.)?[a-zA-Z_][A-Za-z0-9_]*)"
-    r"\s*=\s*'(?P<value>[^']*)'",
-    flags=re.IGNORECASE,
-)
-
-
-def normalize_text_filters_to_like(sql: str) -> str:
-    """Rewrite name/status text equality filters to LIKE before rule enforcement."""
-
-    def replace(match: re.Match[str]) -> str:
-        column = match.group("column")
-        column_name = column.rsplit(".", 1)[-1].lower()
-        value = match.group("value").strip()
-        if not _should_normalize_text_filter_to_like(column_name, value):
-            return match.group(0)
-        like_value = value if value.startswith("%") and value.endswith("%") else f"%{value.strip('%')}%"
-        return f"{match.group('prefix')}{column} LIKE '{like_value}'"
-
-    return _TEXT_EQUALITY_FILTER_RE.sub(replace, sql)
-
-
-def normalize_chinese_select_aliases(sql: str, schema: dict[str, Any] | None) -> str:
-    """Add or replace SELECT aliases with Chinese labels from schema column comments."""
-    if not schema or not sql.strip():
-        return sql
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return sql
-
-    table_aliases = _sql_table_aliases(sql)
-    used_labels: set[str] = set()
-    new_items: list[str] = []
-    changed = False
-    for item in _split_top_level_select_items(select_list):
-        cleaned = item.strip()
-        if not cleaned:
-            new_items.append(cleaned)
-            continue
-        if _select_item_has_chinese_alias(cleaned):
-            alias = _extract_select_alias(cleaned)
-            if alias:
-                used_labels.add(alias)
-            new_items.append(cleaned)
-            continue
-        expr = _select_expression_without_alias(cleaned)
-        label = _infer_chinese_select_alias(expr, table_aliases=table_aliases, schema=schema)
-        if label is None or re.search(r"[\u4e00-\u9fff]", label) is None:
-            new_items.append(cleaned)
-            continue
-        label = _dedupe_chinese_alias(label, used_labels)
-        used_labels.add(label)
-        new_items.append(f"{expr} AS {label}")
-        changed = True
-    if not changed:
-        return sql
-    return _replace_top_level_select_list(sql, ", ".join(new_items))
-
-
-def question_requests_id_field(question: str) -> bool:
-    lowered = question.lower()
-    return "id" in lowered or "编号" in question or "主键" in question
-
-
-def strip_identifier_columns_from_select(sql: str, question: str) -> str:
-    """Drop bare id / *_id columns from SELECT unless the question explicitly asks for ids."""
-    if question_requests_id_field(question):
-        return sql
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return sql
-    table_aliases = _sql_table_aliases(sql)
-    kept: list[str] = []
-    for item in _split_top_level_select_items(select_list):
-        cleaned = item.strip()
-        if not cleaned:
-            continue
-        expr = _select_expression_without_alias(cleaned)
-        if _select_expr_is_identifier_column(expr, table_aliases):
-            continue
-        kept.append(cleaned)
-    if not kept or len(kept) == len(_split_top_level_select_items(select_list)):
-        return sql
-    return _replace_top_level_select_list(sql, ", ".join(kept))
-
-
-def apply_enum_case_to_select(sql: str, schema: dict[str, Any] | None) -> str:
-    """Wrap enum-backed scalar columns in CASE WHEN so SELECT shows Chinese labels."""
-    if not schema or not sql.strip():
-        return sql
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return sql
-    enums_by_field = {
-        str(entry.get("field") or ""): entry.get("values")
-        for entry in merged_schema_enums(schema)
-        if isinstance(entry, dict) and entry.get("field")
-    }
-    table_aliases = _sql_table_aliases(sql)
-    used_labels: set[str] = set()
-    new_items: list[str] = []
-    changed = False
-    for item in _split_top_level_select_items(select_list):
-        cleaned = item.strip()
-        if not cleaned:
-            new_items.append(cleaned)
-            continue
-        if re.match(r"case\s+", _select_expression_without_alias(cleaned), flags=re.IGNORECASE):
-            alias = _extract_select_alias(cleaned)
-            if alias:
-                used_labels.add(alias)
-            new_items.append(cleaned)
-            continue
-        expr = _select_expression_without_alias(cleaned)
-        case_expr = _enum_case_expression_for_select_item(
-            expr,
-            table_aliases=table_aliases,
-            enums_by_field=enums_by_field,
-            schema=schema,
-            used_labels=used_labels,
-            existing_alias=_extract_select_alias(cleaned),
-        )
-        if case_expr is None:
-            alias = _extract_select_alias(cleaned)
-            if alias:
-                used_labels.add(alias)
-            new_items.append(cleaned)
-            continue
-        used_labels.add(_extract_select_alias(case_expr) or "")
-        new_items.append(case_expr)
-        changed = True
-    if not changed:
-        return sql
-    return _replace_top_level_select_list(sql, ", ".join(new_items))
-
-
-def suggest_join_patterns_for_schema(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    suggestions: list[dict[str, Any]] = []
-    for example in _schema_examples(schema):
-        if not isinstance(example, dict):
-            continue
-        join_pattern = example.get("joinPattern")
-        if not isinstance(join_pattern, dict):
-            continue
-        item: dict[str, Any] = {"joinPattern": join_pattern}
-        for key in ("id", "intent", "notes", "questionExamples"):
-            value = example.get(key)
-            if value:
-                item[key] = value
-        suggestions.append(item)
-    return suggestions[:6]
-
-
-def finalize_generated_sql(
-    sql: str,
-    question: str,
-    *,
-    schema: dict[str, Any] | None = None,
-) -> str:
-    normalized = normalize_text_filters_to_like(sql)
-    normalized = strip_identifier_columns_from_select(normalized, question)
-    normalized = apply_enum_case_to_select(normalized, schema)
-    normalized = normalize_chinese_select_aliases(normalized, schema)
-    return normalized
-
-
-def _select_expr_is_identifier_column(expr: str, table_aliases: dict[str, str]) -> bool:
-    normalized = expr.strip()
-    match = re.fullmatch(r"([a-zA-Z_][\w]*)\.([a-zA-Z_][\w]*)", normalized)
-    if match is None:
-        return normalized.lower() in {"id"} or normalized.lower().endswith("_id")
-    alias, column = match.group(1).lower(), match.group(2).lower()
-    if column == "id" or column.endswith("_id"):
-        return True
-    table = table_aliases.get(alias)
-    if table and (column == "id" or column.endswith("_id")):
-        return True
-    return False
-
-
-def _enum_case_expression_for_select_item(
-    expr: str,
-    *,
-    table_aliases: dict[str, str],
-    enums_by_field: dict[str, Any],
-    schema: dict[str, Any],
-    used_labels: set[str],
-    existing_alias: str | None,
-) -> str | None:
-    match = re.fullmatch(r"([a-zA-Z_][\w]*)\.([a-zA-Z_][\w]*)", expr.strip())
-    if match is None:
-        return None
-    alias, column = match.group(1), match.group(2)
-    table = table_aliases.get(alias.lower())
-    if table is None:
-        return None
-    values = enums_by_field.get(f"{table}.{column}")
-    if not isinstance(values, list) or not values:
-        return None
-    when_parts: list[str] = []
-    for item in values:
-        if not isinstance(item, dict):
-            continue
-        value = item.get("value")
-        label = str(item.get("label") or "").strip()
-        if value is None or not label:
-            continue
-        literal = repr(str(value)) if isinstance(value, str) else str(value)
-        when_parts.append(f"WHEN {expr} = {literal} THEN {_sql_string_literal(label)}")
-    if not when_parts:
-        return None
-    alias_label = existing_alias or _chinese_label_for_column(schema, table, column) or column
-    alias_label = _dedupe_chinese_alias(alias_label, used_labels)
-    return f"CASE {' '.join(when_parts)} ELSE CAST({expr} AS CHAR) END AS {alias_label}"
-
-
-def _sql_string_literal(value: str) -> str:
-    return "'" + value.replace("'", "''") + "'"
-
-
-def _enforce_no_tautological_join_conditions(sql: str) -> None:
-    if re.search(
-        r"\b(?:left|right|inner|full|cross)?\s*join\b[\s\S]*?\bon\s+(?:1\s*=\s*0|0\s*=\s*1|1\s*=\s*1|true|false)\b",
-        sql,
-        flags=re.IGNORECASE,
-    ):
-        raise SqlGenerationError(
-            "SQL JOIN must not use tautological ON conditions such as ON 1=0 or ON 1=1; "
-            "use schema exampleJoinPatterns and structureHints to build real joins"
-        )
-
-
-_JOIN_ON_START_RE = re.compile(
-    r"\b(?:(?:left|right|inner|full|cross)\s+)?join\s+(?:\([^)]+\)|[a-zA-Z_][\w]*(?:\s+(?:as\s+)?[a-zA-Z_][\w]*)?)\s+on\s+",
-    re.IGNORECASE,
-)
-_JOIN_ON_END_RE = re.compile(
-    r"\b(where|group\s+by|order\s+by|limit|(?:left|right|inner|full|cross)\s+join)\b",
-    re.IGNORECASE,
-)
-_CROSS_TABLE_EQUALITY_RE = re.compile(
-    r"(?:"
-    r"\b[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*"
-    r"(?:cast\s*\(\s*[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*\s+as\s+\w+\s*\)"
-    r"|[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*)"
-    r"|"
-    r"cast\s*\(\s*[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*\s+as\s+\w+\s*\)\s*=\s*"
-    r"[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*)",
-    re.IGNORECASE,
-)
-
-
-def _iter_join_on_clauses(sql: str) -> list[str]:
-    clauses: list[str] = []
-    for match in _JOIN_ON_START_RE.finditer(sql):
-        rest = sql[match.end() :]
-        end_match = _JOIN_ON_END_RE.search(rest)
-        end = end_match.start() if end_match else len(rest)
-        clause = rest[:end].strip()
-        if clause:
-            clauses.append(clause)
-    return clauses
-
-
-def _list_join_on_violations(sql: str) -> list[str]:
-    violations: list[str] = []
-    for on_clause in _iter_join_on_clauses(sql):
-        preview = re.sub(r"\s+", " ", on_clause).strip()[:120]
-        if re.search(r"\blike\b", on_clause, re.IGNORECASE):
-            violations.append(
-                "JOIN ON 禁止写 LIKE 筛选，请按 schema relations 写主表与关联表的等值键，"
-                f"把实体筛选放到 WHERE：{preview}"
-            )
-            continue
-        if re.search(r"\bin\s*\(", on_clause, re.IGNORECASE):
-            violations.append(
-                "JOIN ON 禁止写 IN 筛选，请按 schema relations 写主表与关联表的等值键，"
-                f"把实体筛选放到 WHERE：{preview}"
-            )
-            continue
-        if _CROSS_TABLE_EQUALITY_RE.search(on_clause) is None:
-            violations.append(
-                "JOIN ON 必须使用主表与关联表的等值关联（如 store.organization_id = sponge_project.id），"
-                f"不能只有筛选条件：{preview}"
-            )
-    return violations
-
-
-def _enforce_join_on_uses_equality_keys(sql: str) -> None:
-    violations = _list_join_on_violations(sql)
-    if violations:
-        raise SqlGenerationError(violations[0])
-
-
-_AGGREGATE_FUNCTION_RE = re.compile(
-    r"\b(?:count|sum|avg|min|max|group_concat)\s*\(",
-    flags=re.IGNORECASE,
-)
-
-
-def _enforce_no_aggregate_functions_in_row_filters(sql: str) -> None:
-    for clause in _iter_join_on_clauses(sql):
-        if _AGGREGATE_FUNCTION_RE.search(clause):
-            raise SqlGenerationError(
-                "SQL aggregate functions must not be used in JOIN ON; "
-                "aggregate first in a subquery or move aggregate predicates to HAVING"
-            )
-    where_clause = _top_level_where_clause(sql)
-    if where_clause and _AGGREGATE_FUNCTION_RE.search(where_clause):
-        raise SqlGenerationError(
-            "SQL aggregate functions must not be used in WHERE; "
-            "move aggregate predicates to HAVING or aggregate first in a subquery"
-        )
-
-
-def _top_level_where_clause(sql: str) -> str:
-    where_index = _find_top_level_keyword(sql, "where", start=0)
-    if where_index is None:
-        return ""
-    body_start = where_index + len("where")
-    suffix_starts = [
-        index
-        for keyword in ("group by", "having", "order by", "limit")
-        if (index := _find_top_level_keyword(sql, keyword, start=body_start)) is not None
-    ]
-    body_end = min(suffix_starts) if suffix_starts else len(sql)
-    return sql[body_start:body_end]
-
-
-def _select_item_has_chinese_alias(item: str) -> bool:
-    alias = _extract_select_alias(item)
-    return alias is not None and re.search(r"[\u4e00-\u9fff]", alias) is not None
-
-
-def _extract_select_alias(item: str) -> str | None:
-    alias_match = re.search(
-        _SELECT_AS_ALIAS_PATTERN,
-        item.strip(),
-        flags=re.IGNORECASE,
-    )
-    if alias_match is None:
-        return None
-    return alias_match.group(1).strip("`\"'")
-
-
-def _dedupe_chinese_alias(label: str, used: set[str]) -> str:
-    if label not in used:
-        return label
-    index = 2
-    while f"{label}{index}" in used:
-        index += 1
-    return f"{label}{index}"
-
-
-def _infer_chinese_select_alias(
-    expr: str,
-    *,
-    table_aliases: dict[str, str],
-    schema: dict[str, Any],
-) -> str | None:
-    normalized = expr.strip()
-    if not normalized:
-        return None
-
-    aggregate_match = re.match(r"(count|sum|avg|min|max)\s*\(", normalized, flags=re.IGNORECASE)
-    if aggregate_match is not None:
-        labels = {
-            "count": "数量",
-            "sum": "合计",
-            "avg": "平均值",
-            "min": "最小值",
-            "max": "最大值",
-        }
-        return labels.get(aggregate_match.group(1).lower())
-
-    if re.match(r"case\s+", normalized, flags=re.IGNORECASE):
-        return "结果"
-
-    qualified_match = re.search(
-        r"(?:([a-zA-Z_][a-zA-Z0-9_]*)\.)?([a-zA-Z_][a-zA-Z0-9_]*)\s*$",
-        normalized,
-    )
-    if qualified_match is not None:
-        alias_part, column_name = qualified_match.group(1), qualified_match.group(2)
-        if alias_part is not None:
-            table_name = table_aliases.get(alias_part.lower())
-            if table_name is not None:
-                return _chinese_label_for_column(schema, table_name, column_name)
-        return _chinese_label_for_bare_column(schema, table_aliases, column_name)
-    return None
-
-
-def _chinese_label_for_column(schema: dict[str, Any], table_name: str, column_name: str) -> str | None:
-    for column in _table_columns(schema, table_name):
-        name = str(column.get("columnName") or column.get("name") or "")
-        if name.lower() != column_name.lower():
-            continue
-        label = _column_alias(name, str(column.get("comment") or ""))
-        if re.search(r"[\u4e00-\u9fff]", label):
-            return label
-    return None
-
-
-def _chinese_label_for_bare_column(
-    schema: dict[str, Any],
-    table_aliases: dict[str, str],
-    column_name: str,
-) -> str | None:
-    labels = [
-        label
-        for table_name in set(table_aliases.values())
-        if (label := _chinese_label_for_column(schema, table_name, column_name)) is not None
-    ]
-    if len(labels) == 1:
-        return labels[0]
-    return None
-
-
-def _replace_top_level_select_list(sql: str, select_list: str) -> str:
-    stripped = sql.strip().rstrip(";")
-    match = re.match(r"select\s+(?:distinct\s+)?", stripped, flags=re.IGNORECASE)
-    if match is None:
-        return sql
-    start = match.end()
-    from_index = _find_top_level_keyword(stripped, "from", start=start)
-    if from_index is None:
-        return sql
-    prefix = stripped[:start].rstrip()
-    suffix = stripped[from_index:].lstrip()
-    return f"{prefix} {select_list} {suffix}"
-
-
-def _should_normalize_text_filter_to_like(column_name: str, value: str) -> bool:
-    if not value or _is_numeric_literal(value):
-        return False
-    return _is_name_filter_column(column_name) or _is_status_text_filter_column(column_name)
-
-
-def _enforce_text_filters_use_like(sql: str) -> None:
-    for match in _TEXT_EQUALITY_FILTER_RE.finditer(sql):
-        column = match.group("column").rsplit(".", 1)[-1].lower()
-        value = match.group("value").strip()
-        if _should_normalize_text_filter_to_like(column, value):
-            raise SqlGenerationError("SQL text filters must use LIKE")
-
-
-def _is_name_filter_column(column: str) -> bool:
-    return column == "name" or column == "job_name" or column.endswith("_name")
-
-
-def _is_status_text_filter_column(column: str) -> bool:
-    return column in {"status", "state"} or column.endswith("_status") or column.endswith("_state")
-
-
-def _is_numeric_literal(value: str) -> bool:
-    return bool(re.fullmatch(r"-?\d+(?:\.\d+)?", value))
-
-
-def is_low_quality_sql_for_question(question: str, sql: str, *, schema: dict[str, Any] | None = None) -> bool:
-    return low_quality_sql_issue_for_question(question, sql, schema=schema) is not None
-
-
-def low_quality_sql_issue_for_question(question: str, sql: str, *, schema: dict[str, Any] | None = None) -> LowQualitySqlIssue | None:
-    if schema is None:
-        return None
-    from .schema_context_retriever import match_concepts_for_question
-
-    matched_concepts = match_concepts_for_question(_schema_concepts(schema), question)
-    normalized = sql.strip().lower()
-    for concept in matched_concepts:
-        checks = concept.get("sqlQualityChecks")
-        if not _concept_quality_check_applies(concept, question):
-            continue
-        time_range_issue = _concept_time_range_field_issue(question, sql, concept)
-        if time_range_issue is not None:
-            return time_range_issue
-        if not isinstance(checks, dict):
-            continue
-        for table_name in checks.get("requireTables") or []:
-            table = str(table_name or "").strip().lower()
-            if table and table not in normalized:
-                message = str(checks.get("message") or f"SQL 必须引用 schema 要求的表：{table_name}")
-                concept_label = str(concept.get("comment") or concept.get("name") or "命中的 schema concept")
-                return LowQualitySqlIssue(
-                    code="SCHEMA_SQL_QUALITY",
-                    message=message,
-                    missing_items=(f"必须引用表 {table_name}",),
-                    current_problem=(
-                        f"当前 SQL 没有使用 {table_name}，无法覆盖“{concept_label}”要求的查询口径。"
-                    ),
-                    repair_hint=(
-                        f"按 schema.concepts 中“{concept_label}”的定义补充 {table_name} 及对应 JOIN/WHERE 条件。"
-                    ),
-                )
-    aggregate_issue = _aggregate_sql_quality_issue(question, sql)
-    if aggregate_issue is not None:
-        return aggregate_issue
-    return None
-
-
-def _concept_time_range_field_issue(
-    question: str,
-    sql: str,
-    concept: dict[str, Any],
-) -> LowQualitySqlIssue | None:
-    qualified = str(concept.get("timeRangeField") or "").strip()
-    if "." not in qualified or _extract_time_bounds(question) is None:
-        return None
-    table_name, field_name = qualified.rsplit(".", 1)
-    time_range = TimeRange(field=field_name, alias="时间范围", start="", end="", table_name=table_name)
-    if not _sql_has_time_filter_for_range(sql, time_range):
-        return LowQualitySqlIssue(
-            code="SCHEMA_TIME_RANGE_FIELD_REQUIRED",
-            message=(
-                f"用户问题包含时间范围，且 schema concept 指定时间字段为 {qualified}；"
-                "SQL 必须使用该字段过滤时间范围，不要改用关联维表的同名时间字段。"
-            ),
-            missing_items=(f"时间范围字段 {qualified}",),
-            current_problem=f"当前 SQL 没有使用 {qualified} 过滤用户要求的时间范围。",
-            repair_hint=f"在 WHERE 中使用 {qualified} 补充时间范围过滤。",
-        )
-    unexpected = _unexpected_time_filter_fields(sql, expected_field=qualified)
-    if unexpected:
-        return LowQualitySqlIssue(
-            code="SCHEMA_TIME_RANGE_FIELD_REQUIRED",
-            message=(
-                f"用户问题包含时间范围，且 schema concept 指定时间字段为 {qualified}；"
-                f"SQL 不应同时使用 {'、'.join(unexpected)} 过滤时间范围。"
-            ),
-            missing_items=(f"唯一时间范围字段 {qualified}",),
-            current_problem=f"当前 SQL 还使用了 {'、'.join(unexpected)} 过滤时间范围，可能把口径切到关联表时间。",
-            repair_hint=f"删除关联表时间过滤，只保留 {qualified} 的时间范围条件。",
-        )
-    return None
-
-
-_TIME_RANGE_DATE_LITERAL = r"'20\d{2}-\d{1,2}-\d{1,2}(?:\s+\d{1,2}:\d{2}:\d{2})?'"
-
-
-def _sql_has_time_filter_for_range(sql: str, time_range: TimeRange) -> bool:
-    if _scope_has_time_filter_for_range(sql, time_range):
-        return True
-    for subquery in _sql_derived_subqueries(sql).values():
-        if _sql_has_time_filter_for_range(subquery, time_range):
-            return True
-    return False
-
-
-def _mask_derived_subqueries(sql: str) -> str:
-    spans = _sql_derived_subquery_spans(sql)
-    if not spans:
-        return sql
-    chars = list(sql)
-    for start, end in spans:
-        for index in range(start, min(end, len(chars))):
-            chars[index] = " "
-    return "".join(chars)
-
-
-def _scope_has_time_filter_for_range(sql: str, time_range: TimeRange) -> bool:
-    """Return True if the designated time field is compared to a date literal in this
-    query scope.
-
-    Nested derived subqueries are masked out here and evaluated separately by
-    ``_sql_has_time_filter_for_range`` so alias resolution stays scoped. The check
-    scans the whole scope (not just the top-level WHERE) so the field can satisfy the
-    requirement whether it is used in WHERE or inside a conditional aggregate such as
-    ``SUM(CASE WHEN sign_up_time >= ... THEN 1 ELSE 0 END)``, which some schema concepts
-    mandate for period metrics.
-    """
-    scope_text = _mask_derived_subqueries(sql)
-    op = r"(?:>=|<=|>|<|=)"
-    date = _TIME_RANGE_DATE_LITERAL
-    field_patterns: list[str] = [_time_range_sql_field_pattern(scope_text, time_range)]
-    base_tables = set(_sql_top_level_table_aliases(scope_text).values())
-    if not time_range.table_name or base_tables == {time_range.table_name.lower()}:
-        # Single base table in scope: an unqualified column reference is unambiguous.
-        field_patterns.append(rf"(?<![.\w]){re.escape(time_range.field.lower())}\b")
-    for field_pattern in field_patterns:
-        checks = (
-            rf"{field_pattern}\s*{op}\s*{date}",
-            rf"{date}\s*{op}\s*{field_pattern}",
-            rf"{field_pattern}\s+between\s+{date}\s+and\s+{date}",
-        )
-        if any(re.search(pattern, scope_text, flags=re.IGNORECASE) for pattern in checks):
-            return True
-    return False
-
-
-def _unexpected_time_filter_fields(sql: str, *, expected_field: str) -> list[str]:
-    expected_table, expected_column = expected_field.lower().rsplit(".", 1)
-    aliases = _sql_table_aliases(sql)
-    unexpected: list[str] = []
-    seen: set[str] = set()
-    where_index = _find_top_level_keyword(sql, "where", start=0)
-    if where_index is None:
-        return []
-    clause_start = where_index + len("where")
-    clause_end = _where_filter_insert_pos(sql[clause_start:])
-    if clause_end < len(sql[clause_start:]):
-        clause_end += clause_start
-    else:
-        clause_end = len(sql)
-    for predicate in _split_top_level_and_predicates(sql[clause_start:clause_end].strip()):
-        if re.search(r"'20\d{2}-\d{1,2}-\d{1,2}", predicate) is None:
-            continue
-        if re.search(r"(?:\bbetween\b|>=|>|<=|<|=)", predicate, flags=re.IGNORECASE) is None:
-            continue
-        for match in re.finditer(r"\b([a-zA-Z_][\w]*)\.([a-zA-Z_][\w]*)\b", predicate):
-            qualifier = match.group(1).lower()
-            column = match.group(2).lower()
-            if column != expected_column:
-                continue
-            table = aliases.get(qualifier, qualifier)
-            qualified = f"{table}.{column}"
-            if qualified == f"{expected_table}.{expected_column}" or qualified in seen:
-                continue
-            seen.add(qualified)
-            unexpected.append(qualified)
-    return unexpected
-
-
-def _aggregate_sql_quality_issue(question: str, sql: str) -> LowQualitySqlIssue | None:
-    if not _question_requires_aggregate_sql(question):
-        return None
-    normalized = sql.lower()
-    if re.search(r"\b(count|sum|avg|min|max)\s*\(", normalized):
-        return None
-    return LowQualitySqlIssue(
-        code="AGGREGATE_SQL_REQUIRED",
-        message="用户问题要求统计数量/最多值及对应维度，SQL 必须使用 COUNT/SUM/AVG/MIN/MAX 等聚合函数，不能只返回明细行。",
-        missing_items=("聚合函数 COUNT/SUM/AVG/MIN/MAX",),
-        current_problem="当前 SQL 返回明细行，不能回答数量、最多值、排名或按维度统计问题。",
-        repair_hint="按用户问题中的统计维度 GROUP BY，并用聚合函数生成指标。",
-    )
-
-
-def format_sql_quality_issue(issue: LowQualitySqlIssue) -> str:
-    parts = [f"当前 SQL 不满足查询口径：{issue.message}"]
-    if issue.missing_items:
-        parts.append(f"缺失口径：{'；'.join(issue.missing_items)}")
-    if issue.current_problem:
-        parts.append(f"当前 SQL 的问题：{issue.current_problem}")
-    if issue.repair_hint:
-        parts.append(f"建议修复方向：{issue.repair_hint}")
-    return "；".join(parts)
-
-
-def _question_requires_aggregate_sql(question: str) -> bool:
-    if not re.search(r"(计数|统计|数量|个数|总数|多少)", question):
-        return False
-    return bool(re.search(r"(最多|最少|最大|最小|排行|排名|对应|按.+?统计|根据.+?计数)", question))
-
-
-def _concept_quality_check_applies(concept: dict[str, Any], question: str) -> bool:
-    question_text = _compact_quality_match_text(question)
-    if not question_text:
-        return False
-    for example in concept.get("negativeExamples") or []:
-        if _quality_phrase_matches(question_text, example):
-            return False
-    for example in concept.get("positiveExamples") or []:
-        if _quality_phrase_matches(question_text, example):
-            return True
-    for example in concept.get("questionExamples") or []:
-        if _quality_phrase_matches(question_text, example):
-            return True
-    for key in ("comment", "description", "intent", "name", "term"):
-        if _quality_phrase_matches(question_text, concept.get(key)):
-            return True
-    return False
-
-
-def _quality_phrase_matches(question_text: str, phrase: Any) -> bool:
-    phrase_text = _compact_quality_match_text(str(phrase or ""))
-    return len(phrase_text) >= 2 and phrase_text in question_text
-
-
-def _compact_quality_match_text(text: str) -> str:
-    normalized = text.translate(str.maketrans("０１２３４５６７８９", "0123456789")).lower()
-    return "".join(re.findall(r"[a-z0-9\u4e00-\u9fff]+", normalized))
-
-
-def _sql_select_metric_aliases(sql: str) -> list[str]:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return []
-    aliases: list[str] = []
-    for item in _split_top_level_select_items(select_list):
-        alias_match = re.search(
-            r"\s+as\s+(`[^`]+`|\"[^\"]+\"|'[^']+'|[\u4e00-\u9fff][\w\u4e00-\u9fff]*)\s*$",
-            item.strip(),
-            flags=re.IGNORECASE,
-        )
-        if alias_match is not None:
-            aliases.append(alias_match.group(1).strip("`\"'"))
-    return aliases
-
-
-def _replace_primary_metric_alias(sql: str, alias: str) -> str:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        return sql
-    items = _split_top_level_select_items(select_list)
-    if not items:
-        return sql
-    last_item = items[-1].strip()
-    updated_last = re.sub(
-        r"\s+as\s+(`[^`]+`|\"[^\"]+\"|'[^']+'|[\u4e00-\u9fff][\w\u4e00-\u9fff]*)\s*$",
-        f" AS {alias}",
-        last_item,
-        count=1,
-        flags=re.IGNORECASE,
-    )
-    if updated_last == last_item:
-        return sql
-    items[-1] = updated_last
-    rebuilt_select = ", ".join(items)
-    return re.sub(
-        r"(?is)\bselect\b(.*?)\bfrom\b",
-        lambda match: f"SELECT {rebuilt_select} FROM",
-        sql,
-        count=1,
-    )
-
-
-def _schema_enums(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    enums = schema.get("enums")
-    if isinstance(enums, list):
-        return [enum for enum in enums if isinstance(enum, dict)]
-    structure = schema.get("structure")
-    concepts = structure.get("concepts") if isinstance(structure, dict) else None
-    if not isinstance(concepts, list):
-        return []
-    by_field: dict[str, dict[Any, str]] = {}
-    for concept in concepts:
-        if not isinstance(concept, dict):
-            continue
-        enum_refs = concept.get("enumRefs")
-        if not isinstance(enum_refs, list):
-            continue
-        label_parts = [
-            str(concept.get("comment") or ""),
-            str(concept.get("name") or ""),
-            str(concept.get("description") or ""),
-        ]
-        for enum_ref in enum_refs:
-            if not isinstance(enum_ref, dict):
-                continue
-            field_name = str(enum_ref.get("field") or "")
-            if not field_name or "value" not in enum_ref:
-                continue
-            label = " / ".join(part for part in label_parts + [str(enum_ref.get("meaning") or "")] if part)
-            by_field.setdefault(field_name, {})[enum_ref["value"]] = label
-    return [
-        {"field": field_name, "values": [{"value": value, "label": label} for value, label in values.items()]}
-        for field_name, values in by_field.items()
-    ]
-
-
-def _enum_label_terms(label: str) -> set[str]:
-    terms = {label.strip()}
-    terms.update(part.strip() for part in re.split(r"[/、,，;；\s]+", label) if part.strip())
-    return {term for term in terms if term}
-
-
-def validate_sql_against_schema(sql: str, schema: dict[str, Any]) -> list[SchemaValidationIssue]:
-    issues: list[SchemaValidationIssue] = []
-    for subquery in _sql_derived_subqueries(sql).values():
-        issues.extend(validate_sql_against_schema(subquery, schema))
-    table_aliases = _sql_table_aliases(sql)
-    derived_columns = _sql_derived_subquery_aliases(sql)
-    schema_tables = _schema_table_column_map(schema)
-    for alias, columns in derived_columns.items():
-        schema_tables[alias] = columns
-    for table in set(table_aliases.values()):
-        if table in derived_columns:
-            continue
-        if table not in schema_tables:
-            issues.append(
-                SchemaValidationIssue(
-                    code="UNKNOWN_TABLE",
-                    message=f"SQL 使用了 schema 中不存在的表：{table}",
-                )
-            )
-    issues.extend(_schema_missing_table_reference_issues(sql, table_aliases))
-    issues.extend(_schema_unknown_column_issues(sql, table_aliases, schema_tables))
-    for message in _list_join_on_violations(sql):
-        issues.append(SchemaValidationIssue(code="JOIN_ON_FILTER", message=message))
-    if not any(issue.code == "UNKNOWN_TABLE" for issue in issues):
-        issues.extend(_schema_invalid_join_issues(sql, table_aliases, schema))
-    return issues
-
-
-def _schema_table_column_map(schema: dict[str, Any]) -> dict[str, set[str]]:
-    column_map: dict[str, set[str]] = {}
-    tables = schema.get("tables")
-    if not isinstance(tables, list):
-        nested_schema = schema.get("schema")
-        if isinstance(nested_schema, dict) and isinstance(nested_schema.get("tables"), list):
-            tables = nested_schema["tables"]
-        else:
-            tables = []
-    for table in tables:
-        if not isinstance(table, dict):
-            continue
-        name = table.get("name") or table.get("tableName")
-        if not name:
-            continue
-        table_key = str(name).lower()
-        columns = table.get("columns")
-        if not isinstance(columns, list):
-            continue
-        column_map[table_key] = {
-            str(column.get("columnName") or column.get("name") or "").lower()
-            for column in columns
-            if isinstance(column, dict) and (column.get("columnName") or column.get("name"))
-        }
-    return column_map
-
-
-def _schema_missing_table_reference_issues(
-    sql: str,
-    table_aliases: dict[str, str],
-) -> list[SchemaValidationIssue]:
-    declared = set(table_aliases)
-    issues: list[SchemaValidationIssue] = []
-    seen: set[tuple[str, str]] = set()
-    for alias, column in _sql_qualified_column_refs(sql):
-        if alias in declared:
-            continue
-        key = (alias, column)
-        if key in seen:
-            continue
-        seen.add(key)
-        issues.append(
-            SchemaValidationIssue(
-                code="MISSING_TABLE_REFERENCE",
-                message=(
-                    "SQL 引用了未在 FROM/JOIN 中声明的表或别名："
-                    f"{alias}.{column}；如果需要该字段必须先 JOIN 对应表，否则删除该引用。"
-                ),
-            )
-        )
-    return issues
-
-
-def _schema_unknown_column_issues(
-    sql: str,
-    table_aliases: dict[str, str],
-    schema_tables: dict[str, set[str]],
-) -> list[SchemaValidationIssue]:
-    issues: list[SchemaValidationIssue] = []
-    seen: set[tuple[str, str]] = set()
-    for alias, column in _sql_qualified_column_refs(sql):
-        table = table_aliases.get(alias)
-        if table is None or table not in schema_tables:
-            continue
-        key = (table, column)
-        if key in seen:
-            continue
-        seen.add(key)
-        if column not in schema_tables[table]:
-            issues.append(
-                SchemaValidationIssue(
-                    code="UNKNOWN_COLUMN",
-                    message=f"SQL 使用了 schema 中不存在的列：{table}.{column}",
-                )
-            )
-    return issues
-
-
-def _schema_invalid_join_issues(
-    sql: str,
-    table_aliases: dict[str, str],
-    schema: dict[str, Any],
-) -> list[SchemaValidationIssue]:
-    allowed_pairs = _schema_allowed_join_pairs(schema)
-    if not allowed_pairs:
-        return []
-    derived_aliases = set(_sql_derived_subquery_aliases(sql))
-    issues: list[SchemaValidationIssue] = []
-    seen: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    for pair in _sql_equality_pairs(sql, table_aliases):
-        if pair in seen:
-            continue
-        seen.add(pair)
-        if pair in allowed_pairs:
-            continue
-        left, right = pair
-        if left[0] in derived_aliases or right[0] in derived_aliases:
-            continue
-        issues.append(
-            SchemaValidationIssue(
-                code="INVALID_JOIN",
-                message=(
-                    "SQL JOIN 使用了 schema relations / joinPattern 未定义的关联："
-                    f"{left[0]}.{left[1]} = {right[0]}.{right[1]}"
-                ),
-            )
-        )
-    return issues
-
-
-def _sql_qualified_column_refs(sql: str) -> list[tuple[str, str]]:
-    refs: list[tuple[str, str]] = []
-    seen: set[tuple[str, str]] = set()
-    derived_spans = _sql_derived_subquery_spans(sql)
-    for match in re.finditer(
-        r"\b([a-zA-Z_][a-zA-Z0-9_]*)\.((?:[a-zA-Z_][a-zA-Z0-9_]*\.)*[a-zA-Z_][a-zA-Z0-9_]*)\b",
-        sql,
-        flags=re.IGNORECASE,
-    ):
-        if _position_in_spans(match.start(), derived_spans):
-            continue
-        alias = match.group(1).lower()
-        column_path = match.group(2).lower()
-        column = column_path.rsplit(".", 1)[-1]
-        key = (alias, column)
-        if key in seen:
-            continue
-        seen.add(key)
-        refs.append(key)
-    return refs
-
-
-def _sql_table_aliases(sql: str) -> dict[str, str]:
-    aliases = dict(_sql_top_level_table_aliases(sql))
-    for alias in _sql_derived_subquery_aliases(sql):
-        aliases[alias] = alias
-    return aliases
-
-
-def _sql_top_level_table_aliases(sql: str) -> dict[str, str]:
-    aliases: dict[str, str] = {}
-    depth = 0
-    quote: str | None = None
-    index = 0
-    length = len(sql)
-    while index < length:
-        char = sql[index]
-        if quote is not None:
-            if char == quote:
-                quote = None
-            elif char == "\\":
-                index += 1
-            index += 1
-            continue
-        if char in ("'", '"', "`"):
-            quote = char
-            index += 1
-            continue
-        if char == "(":
-            depth += 1
-            index += 1
-            continue
-        if char == ")":
-            depth = max(0, depth - 1)
-            index += 1
-            continue
-        if depth == 0:
-            match = re.match(
-                r"(?i)(?:from|join)\s+([a-zA-Z_][a-zA-Z0-9_]*)(?:\s+(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*))?",
-                sql[index:],
-            )
-            if match:
-                table = match.group(1).lower()
-                alias = (match.group(2) or table).lower()
-                if alias in {"on", "where", "left", "right", "inner", "outer", "join"}:
-                    alias = table
-                aliases[alias] = table
-                aliases[table] = table
-                index += match.end()
-                continue
-        index += 1
-    return aliases
-
-
-def _sql_derived_subquery_aliases(sql: str) -> dict[str, set[str]]:
-    return {
-        alias: _extract_subquery_output_columns(subquery)
-        for alias, subquery in _sql_derived_subqueries(sql).items()
-    }
-
-
-def _sql_derived_subqueries(sql: str) -> dict[str, str]:
-    derived: dict[str, str] = {}
-    for alias, subquery_start, subquery_end in _sql_derived_subquery_matches(sql):
-        derived[alias] = sql[subquery_start + 1 : subquery_end]
-    return derived
-
-
-def _sql_derived_subquery_spans(sql: str) -> list[tuple[int, int]]:
-    return [
-        (subquery_start + 1, subquery_end)
-        for _alias, subquery_start, subquery_end in _sql_derived_subquery_matches(sql)
-    ]
-
-
-_DERIVED_SUBQUERY_TRAILING = (
-    r"on\b"
-    r"|(?:(?:left|right|inner|outer|cross|natural)\s+)?join\b"
-    r"|where\b|group\b|order\b|having\b|limit\b"
-    r"|,"
-    r"|\)(?!\s*[a-zA-Z_])"
-    r"|;"
-)
-_DERIVED_SUBQUERY_ALIAS_PATTERN = re.compile(
-    rf"\)\s*(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*)(?:\s+(?:{_DERIVED_SUBQUERY_TRAILING})|\s*$)",
-    flags=re.IGNORECASE,
-)
-_RESERVED_DERIVED_ALIASES = frozenset(
-    {"on", "where", "left", "right", "inner", "outer", "join", "select", "cross", "natural", "group", "order", "having", "limit"}
-)
-
-
-def _sql_derived_subquery_matches(sql: str) -> list[tuple[str, int, int]]:
-    matches: list[tuple[str, int, int]] = []
-    seen_ranges: set[tuple[int, int]] = set()
-    for match in _DERIVED_SUBQUERY_ALIAS_PATTERN.finditer(sql):
-        alias = match.group(1).lower()
-        if alias in _RESERVED_DERIVED_ALIASES:
-            continue
-        subquery_start = _find_matching_open_paren(sql, match.start())
-        if subquery_start is None:
-            continue
-        range_key = (subquery_start, match.start())
-        if range_key in seen_ranges:
-            continue
-        seen_ranges.add(range_key)
-        matches.append((alias, subquery_start, match.start()))
-    return matches
-
-
-def _position_in_spans(position: int, spans: list[tuple[int, int]]) -> bool:
-    return any(start <= position < end for start, end in spans)
-
-
-def _find_matching_open_paren(sql: str, close_index: int) -> int | None:
-    depth = 0
-    for index in range(close_index, -1, -1):
-        char = sql[index]
-        if char == ")":
-            depth += 1
-        elif char == "(":
-            depth -= 1
-            if depth == 0:
-                return index
-    return None
-
-
-def _extract_subquery_output_columns(subquery: str) -> set[str]:
-    select_match = re.search(r"\bselect\b(.*?)\bfrom\b", subquery, flags=re.IGNORECASE | re.DOTALL)
-    if select_match is None:
-        return set()
-    columns: set[str] = set()
-    for expr in _split_select_items(select_match.group(1)):
-        cleaned = expr.strip()
-        if not cleaned:
-            continue
-        alias_match = re.search(r"\bas\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*$", cleaned, flags=re.IGNORECASE)
-        if alias_match:
-            columns.add(alias_match.group(1).lower())
-            continue
-        qualified_match = re.match(
-            r"^([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)$",
-            cleaned,
-            flags=re.IGNORECASE,
-        )
-        if qualified_match:
-            columns.add(qualified_match.group(2).lower())
-            continue
-        bare_match = re.match(r"^([a-zA-Z_][a-zA-Z0-9_]*)$", cleaned, flags=re.IGNORECASE)
-        if bare_match:
-            columns.add(bare_match.group(1).lower())
-    return columns
-
-
-def _sql_equality_pairs(sql: str, table_aliases: dict[str, str]) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    derived_spans = _sql_derived_subquery_spans(sql)
-    for match in re.finditer(
-        r"\b([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\b",
-        sql,
-        flags=re.IGNORECASE,
-    ):
-        if _position_in_spans(match.start(), derived_spans):
-            continue
-        left_alias, left_column, right_alias, right_column = (part.lower() for part in match.groups())
-        left_table = table_aliases.get(left_alias)
-        right_table = table_aliases.get(right_alias)
-        if left_table is None or right_table is None:
-            continue
-        pairs.add(_canonical_join_pair((left_table, left_column), (right_table, right_column)))
-    return pairs
-
-
-def _schema_allowed_join_pairs(schema: dict[str, Any]) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    relations = _schema_relations(schema)
-    if isinstance(relations, list):
-        for relation in relations:
-            if not isinstance(relation, dict):
-                continue
-            left_table, left_column = _relation_left(relation)
-            right_table, right_column = _relation_right(relation)
-            if left_table and left_column and right_table and right_column:
-                pairs.add(_canonical_join_pair((left_table, left_column), (right_table, right_column)))
-    for section in (_schema_metrics(schema), _schema_business_terms(schema), _schema_concepts(schema), _schema_examples(schema)):
-        if isinstance(section, list):
-            for item in section:
-                if isinstance(item, dict):
-                    pairs.update(_join_pairs_from_text(str(item)))
-    pairs.update(_schema_example_join_pattern_pairs(schema))
-    pairs.update(_schema_work_order_failure_reason_join_pairs(schema))
-    pairs.update(_schema_inferred_foreign_key_join_pairs(schema))
-    return pairs
-
-
-def _schema_inferred_foreign_key_join_pairs(
-    schema: dict[str, Any],
-) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    """Allow `{ref_table}_id` columns to join `{ref_table}.id` when no explicit relation exists."""
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    table_names = {
-        str(table.get("tableName") or table.get("name") or "")
-        for table in schema.get("tables") or []
-        if isinstance(table, dict) and (table.get("tableName") or table.get("name"))
-    }
-    for table in schema.get("tables") or []:
-        if not isinstance(table, dict):
-            continue
-        table_name = str(table.get("tableName") or table.get("name") or "")
-        if not table_name:
-            continue
-        for column in table.get("columns") or []:
-            if not isinstance(column, dict):
-                continue
-            column_name = str(column.get("columnName") or column.get("name") or "")
-            if not column_name.endswith("_id") or column_name == "id":
-                continue
-            ref_table = column_name[:-3]
-            if ref_table not in table_names:
-                continue
-            pairs.add(_canonical_join_pair((table_name, column_name), (ref_table, "id")))
-    return pairs
-
-
-def _schema_work_order_failure_reason_join_pairs(
-    schema: dict[str, Any],
-) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    mappings = _schema_structure(schema).get("workOrderFailureReasonMappings")
-    if not isinstance(mappings, list):
-        return pairs
-    for mapping in mappings:
-        if not isinstance(mapping, dict):
-            continue
-        reason_join = mapping.get("reasonJoin")
-        if isinstance(reason_join, str) and reason_join.strip():
-            pairs.update(_join_pairs_from_text(reason_join))
-    unpivot = _schema_structure(schema).get("workOrderFailureReasonUnpivot")
-    if isinstance(unpivot, dict):
-        base_table = str(unpivot.get("baseTable") or "mvp_applied_jobs_by_helped_account")
-        for branch in unpivot.get("branches") or []:
-            if not isinstance(branch, dict):
-                continue
-            reason_field = str(branch.get("reasonField") or "")
-            if reason_field:
-                pairs.add(
-                    _canonical_join_pair(
-                        ("failure_reasons", "id"),
-                        (base_table, reason_field),
-                    )
-                )
-    return pairs
-
-
-def _schema_example_join_pattern_pairs(schema: dict[str, Any]) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    example = schema.get("example")
-    examples: list[Any] = []
-    if isinstance(example, dict) and isinstance(example.get("examples"), list):
-        examples = example["examples"]
-    examples.extend(_schema_examples(schema))
-    for item in examples:
-        if not isinstance(item, dict):
-            continue
-        join_pattern = item.get("joinPattern")
-        if isinstance(join_pattern, dict):
-            pairs.update(_join_pattern_equality_pairs(join_pattern))
-    return pairs
-
-
-def _join_pattern_equality_pairs(join_pattern: dict[str, Any]) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    aliases = _parse_table_alias_clause(str(join_pattern.get("from") or ""))
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    joins = join_pattern.get("joins")
-    if not isinstance(joins, list):
-        return pairs
-    for join in joins:
-        if not isinstance(join, dict):
-            continue
-        aliases.update(_parse_table_alias_clause(str(join.get("table") or "")))
-        on_conditions = join.get("on")
-        if not isinstance(on_conditions, list):
-            continue
-        for condition in on_conditions:
-            pairs.update(_join_pairs_from_on_text(str(condition), aliases))
-    return pairs
-
-
-def _parse_table_alias_clause(clause: str) -> dict[str, str]:
-    cleaned = clause.strip()
-    if not cleaned:
-        return {}
-    match = re.match(
-        r"^([a-zA-Z_][a-zA-Z0-9_]*)(?:\s+(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*))?$",
-        cleaned,
-        flags=re.IGNORECASE,
-    )
-    if match is None:
-        return {}
-    table = match.group(1).lower()
-    alias = (match.group(2) or table).lower()
-    return {alias: table, table: table}
-
-
-def _join_pairs_from_on_text(
-    on: str,
-    aliases: dict[str, str],
-) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    for match in re.finditer(
-        r"\b([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\b",
-        on,
-        flags=re.IGNORECASE,
-    ):
-        left_alias, left_column, right_alias, right_column = (part.lower() for part in match.groups())
-        left_table = aliases.get(left_alias)
-        right_table = aliases.get(right_alias)
-        if left_table is None or right_table is None:
-            continue
-        pairs.add(_canonical_join_pair((left_table, left_column), (right_table, right_column)))
-    return pairs
-
-
-def _schema_structure(schema: dict[str, Any]) -> dict[str, Any]:
-    structure = schema.get("structure")
-    return structure if isinstance(structure, dict) else {}
-
-
-def _schema_relations(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    relations = _schema_structure(schema).get("relations")
-    if isinstance(relations, list):
-        return [relation for relation in relations if isinstance(relation, dict)]
-    joins = schema.get("joins")
-    if isinstance(joins, list):
-        return [join for join in joins if isinstance(join, dict)]
-    return []
-
-
-def _schema_metrics(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    metrics = _schema_structure(schema).get("metrics")
-    if isinstance(metrics, list):
-        return [metric for metric in metrics if isinstance(metric, dict)]
-    legacy_metrics = schema.get("metrics")
-    if isinstance(legacy_metrics, list):
-        return [metric for metric in legacy_metrics if isinstance(metric, dict)]
-    return []
-
-
-def _schema_business_terms(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    business_terms = _schema_structure(schema).get("businessTerms")
-    if isinstance(business_terms, list):
-        return [term for term in business_terms if isinstance(term, dict)]
-    legacy_glossary = schema.get("glossary")
-    if isinstance(legacy_glossary, list):
-        return [term for term in legacy_glossary if isinstance(term, dict)]
-    return []
-
-
-def _schema_concepts(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    concepts = _schema_structure(schema).get("concepts")
-    if isinstance(concepts, list):
-        return [concept for concept in concepts if isinstance(concept, dict)]
-    return []
-
-
-def _schema_examples(schema: dict[str, Any]) -> list[dict[str, Any]]:
-    example = schema.get("example")
-    if isinstance(example, dict) and isinstance(example.get("examples"), list):
-        return [item for item in example["examples"] if isinstance(item, dict)]
-    legacy_examples = schema.get("examples")
-    if isinstance(legacy_examples, list):
-        return [item for item in legacy_examples if isinstance(item, dict)]
-    return []
-
-
-def _relation_left(relation: dict[str, Any]) -> tuple[str, str]:
-    table = str(relation.get("leftTable") or "").lower()
-    column = str(relation.get("leftColumn") or relation.get("fromColumn") or "").lower()
-    if table:
-        return table, column
-    return _split_field_ref(str(relation.get("from") or "").lower())
-
-
-def _relation_right(relation: dict[str, Any]) -> tuple[str, str]:
-    table = str(relation.get("rightTable") or "").lower()
-    column = str(relation.get("rightColumn") or relation.get("toColumn") or "").lower()
-    if table:
-        return table, column
-    return _split_field_ref(str(relation.get("to") or "").lower())
-
-
-def _split_field_ref(value: str) -> tuple[str, str]:
-    if "." not in value:
-        return value, ""
-    return tuple(value.split(".", 1))  # type: ignore[return-value]
-
-
-def _join_pairs_from_text(text: str) -> set[tuple[tuple[str, str], tuple[str, str]]]:
-    pairs: set[tuple[tuple[str, str], tuple[str, str]]] = set()
-    for match in re.finditer(
-        r"\b([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*([a-zA-Z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)\b",
-        text,
-        flags=re.IGNORECASE,
-    ):
-        left_table, left_column, right_table, right_column = (part.lower() for part in match.groups())
-        pairs.add(_canonical_join_pair((left_table, left_column), (right_table, right_column)))
-    return pairs
-
-
-def _canonical_join_pair(
-    left: tuple[str, str],
-    right: tuple[str, str],
-) -> tuple[tuple[str, str], tuple[str, str]]:
-    return tuple(sorted((left, right)))  # type: ignore[return-value]
-
-
-def question_has_time_range(question: str) -> bool:
-    return _extract_time_range(question) is not None
-
-
-def extract_time_range(question: str, schema: dict[str, Any] | None = None) -> TimeRange | None:
-    """Parse a question time window; month/day without year defaults to the current year."""
-    return _extract_time_range(question, schema)
-
-
-def time_range_from_query_plan(query_plan: dict[str, Any] | None) -> TimeRange | None:
-    """Extract a confirmed time window from query-plan filters."""
-    if not isinstance(query_plan, dict):
-        return None
-    start_value = ""
-    end_value = ""
-    field_name = ""
-    for flt in _query_plan_sql_filters(query_plan):
-        if not isinstance(flt, dict):
-            continue
-        if str(flt.get("source") or "") != "question.timeRange":
-            continue
-        operator = str(flt.get("operator") or "").strip()
-        value = str(flt.get("value") or "").strip()
-        field = str(flt.get("field") or "").strip()
-        if operator == ">=":
-            start_value = value
-            field_name = field or field_name
-        elif operator == "<":
-            end_value = value
-            field_name = field or field_name
-    if not start_value or not end_value or not field_name:
-        return None
-    table_name, column = field_name.split(".", 1) if "." in field_name else ("", field_name)
-    return TimeRange(
-        field=column,
-        alias="时间范围",
-        start=start_value,
-        end=end_value,
-        table_name=table_name,
-    )
-
-
-def resolve_time_range(
-    question: str,
-    schema: dict[str, Any] | None = None,
-    *,
-    query_plan: dict[str, Any] | None = None,
-) -> TimeRange | None:
-    plan_range = time_range_from_query_plan(query_plan)
-    if plan_range is not None:
-        return plan_range
-    return extract_time_range(question, schema)
-
-
-def time_range_plan_filters(
-    question: str,
-    schema: dict[str, Any] | None,
-    *,
-    concepts: list[dict[str, Any]] | None = None,
-) -> list[dict[str, str]]:
-    """Build query-plan filters for an extracted time range."""
-    time_range = resolve_time_range_for_question(question, schema, concepts=concepts)
-    if time_range is None:
-        return []
-    qualified_field = (
-        f"{time_range.table_name}.{time_range.field}"
-        if time_range.table_name
-        else time_range.field
-    )
-    label = time_range.alias or "时间范围"
-    return [
-        {
-            "field": qualified_field,
-            "operator": ">=",
-            "value": time_range.start[:10],
-            "description": f"{label}起",
-            "source": "question.timeRange",
-        },
-        {
-            "field": qualified_field,
-            "operator": "<",
-            "value": time_range.end[:10],
-            "description": f"{label}止",
-            "source": "question.timeRange",
-        },
-    ]
-
-
-_FILLED_JOB_PERIOD_CONCEPT = "filled_job_by_period"
-
-
-def _query_plan_has_matched_concept(query_plan: dict[str, Any], concept_name: str) -> bool:
-    for concept in query_plan.get("matchedConcepts") or []:
-        if isinstance(concept, dict) and str(concept.get("name") or "") == concept_name:
-            return True
-    return False
-
-
-def _uses_subquery_period_time_range(sql: str, query_plan: dict[str, Any] | None) -> bool:
-    if isinstance(query_plan, dict) and _query_plan_has_matched_concept(
-        query_plan,
-        _FILLED_JOB_PERIOD_CONCEPT,
-    ):
-        return True
-    return "period_active_apply_count" in sql.lower()
-
-
-def _period_time_bounds(time_range: TimeRange) -> tuple[str, str]:
-    start = time_range.start
-    end = time_range.end
-    if len(start) <= 10:
-        start = f"{start[:10]} 00:00:00"
-    if len(end) <= 10:
-        end = f"{end[:10]} 00:00:00"
-    return start, end
-
-
-def _apply_subquery_period_time_range(sql: str, time_range: TimeRange) -> str:
-    """Apply confirmed time bounds inside apply_stat CASE WHEN, not outer WHERE."""
-    stripped = _remove_time_range_filters_from_sql(
-        sql.rstrip().rstrip(";"),
-        time_range,
-        allow_any_alias=True,
-    )
-    period_start, period_end = _period_time_bounds(time_range)
-    result = stripped
-    for old, new in (
-        ("'<period_start>'", f"'{period_start}'"),
-        ("'<period_end>'", f"'{period_end}'"),
-        ("<period_start>", f"'{period_start}'"),
-        ("<period_end>", f"'{period_end}'"),
-    ):
-        result = result.replace(old, new)
-    field_pattern = rf"(?:\w+\.)?{re.escape(time_range.field)}"
-    time_expr = (
-        r"(?:date_add\s*\(\s*curdate\s*\(\s*\)\s*,\s*interval\s+\d+\s+day\s*\)"
-        r"|curdate\s*\(\s*\)|current_date(?:\s*\(\s*\))?|'[^']+')"
-    )
-    return re.sub(
-        rf"(?is)(case\s+when\s+{field_pattern}\s*>=\s*){time_expr}(\s+and\s+{field_pattern}\s*<\s*){time_expr}(\s+then)",
-        lambda match: f"{match.group(1)}'{period_start}'{match.group(2)}'{period_end}'{match.group(3)}",
-        result,
-    )
-
-
-def apply_time_range_filters_from_plan(sql: str, query_plan: dict[str, Any] | None) -> str:
-    """Force generated SQL to use the confirmed query-plan time filters."""
-    if not isinstance(query_plan, dict):
-        return sql
-    time_range = time_range_from_query_plan(query_plan)
-    if time_range is None:
-        return sql
-    stripped = _remove_time_range_filters_from_sql(sql.rstrip().rstrip(";"), time_range)
-    if _uses_subquery_period_time_range(stripped, query_plan):
-        return _apply_subquery_period_time_range(stripped, time_range)
-    qualified_field = _time_range_sql_qualified_field(stripped, time_range)
-    extra = (
-        f"{qualified_field} >= '{time_range.start[:10]}' "
-        f"AND {qualified_field} < '{time_range.end[:10]}'"
-    )
-    insert_pos = _where_filter_insert_pos(stripped)
-    head = stripped[:insert_pos].rstrip()
-    tail = stripped[insert_pos:].lstrip()
-    if _find_top_level_keyword(head, "where", start=0) is not None:
-        return f"{head} AND {extra} {tail}".strip()
-    return f"{head} WHERE {extra} {tail}".strip()
-
-
-def apply_time_range_filters_from_question(
-    sql: str,
-    question: str,
-    schema: dict[str, Any] | None,
-) -> str:
-    """Force a question-level time range into SQL when queryPlan missed it."""
-    time_range = resolve_time_range_for_sql(question, schema, sql)
-    if time_range is None:
-        return sql
-    query_plan = {
-        "filters": [
-            {
-                "field": _qualified_time_range_field(time_range),
-                "operator": ">=",
-                "value": time_range.start[:10],
-                "source": "question.timeRange",
-            },
-            {
-                "field": _qualified_time_range_field(time_range),
-                "operator": "<",
-                "value": time_range.end[:10],
-                "source": "question.timeRange",
-            },
-        ]
-    }
-    return apply_time_range_filters_from_plan(sql, query_plan)
-
-
-def resolve_time_range_for_sql(
-    question: str,
-    schema: dict[str, Any] | None,
-    sql: str,
-) -> TimeRange | None:
-    if not schema:
-        return None
-    from .schema_context_retriever import match_concepts_for_question
-
-    concepts = match_concepts_for_question(_schema_concepts(schema), question)
-    sql_schema = _schema_limited_to_sql_tables(schema, sql)
-    if sql_schema is None and _sql_referenced_table_names(sql):
-        return None
-    if sql_schema is not None:
-        return resolve_time_range_for_question(
-            question,
-            sql_schema,
-            concepts=_concepts_limited_to_schema_tables(concepts, sql_schema),
-        )
-    return resolve_time_range_for_question(question, schema, concepts=concepts)
-
-
-def _concepts_limited_to_schema_tables(
-    concepts: list[dict[str, Any]],
-    schema: dict[str, Any],
-) -> list[dict[str, Any]]:
-    table_names = {name.lower() for name in _table_names(schema)}
-    if not table_names:
-        return []
-    limited: list[dict[str, Any]] = []
-    for concept in concepts:
-        qualified = str(concept.get("timeRangeField") or "").strip()
-        if "." not in qualified:
-            limited.append(concept)
-            continue
-        table_name = qualified.split(".", 1)[0].lower()
-        if table_name in table_names:
-            limited.append(concept)
-    return limited
-
-
-def _qualified_time_range_field(time_range: TimeRange) -> str:
-    if time_range.table_name:
-        return f"{time_range.table_name}.{time_range.field}"
-    return time_range.field
-
-
-def _where_filter_insert_pos(sql: str) -> int:
-    positions = [
-        pos
-        for keyword in ("group by", "order by", "limit")
-        if (pos := _find_top_level_keyword(sql, keyword, start=0)) is not None
-    ]
-    return min(positions) if positions else len(sql)
-
-
-def _remove_time_range_filters_from_sql(
-    sql: str,
-    time_range: TimeRange,
-    *,
-    allow_any_alias: bool = False,
-) -> str:
-    where_index = _find_top_level_keyword(sql, "where", start=0)
-    if where_index is None:
-        return sql
-    clause_start = where_index + len("where")
-    clause_end = _where_filter_insert_pos(sql[clause_start:])
-    if clause_end < len(sql[clause_start:]):
-        clause_end += clause_start
-    else:
-        clause_end = len(sql)
-    where_body = sql[clause_start:clause_end].strip()
-    if not where_body:
-        return sql
-    predicates = _split_top_level_and_predicates(where_body)
-    kept = [
-        predicate.strip()
-        for predicate in predicates
-        if predicate.strip()
-        and not _is_time_range_predicate(
-            predicate,
-            sql=sql,
-            time_range=time_range,
-            allow_any_alias=allow_any_alias,
-        )
-    ]
-    prefix = sql[:where_index].rstrip()
-    suffix = sql[clause_end:].lstrip()
-    if not kept:
-        return f"{prefix} {suffix}".strip()
-    return f"{prefix} WHERE {' AND '.join(kept)} {suffix}".strip()
-
-
-def _split_top_level_and_predicates(where_body: str) -> list[str]:
-    predicates: list[str] = []
-    depth = 0
-    quote: str | None = None
-    start = 0
-    index = 0
-    while index < len(where_body):
-        char = where_body[index]
-        if quote is not None:
-            if char == quote:
-                quote = None
-            elif char == "\\":
-                index += 1
-            index += 1
-            continue
-        if char in ("'", '"', "`"):
-            quote = char
-            index += 1
-            continue
-        if char == "(":
-            depth += 1
-            index += 1
-            continue
-        if char == ")":
-            depth = max(0, depth - 1)
-            index += 1
-            continue
-        if depth == 0 and where_body[index : index + 3].lower() == "and":
-            before = where_body[index - 1] if index > 0 else " "
-            after_index = index + 3
-            after = where_body[after_index] if after_index < len(where_body) else " "
-            if not (before.isalnum() or before == "_") and not (after.isalnum() or after == "_"):
-                predicates.append(where_body[start:index])
-                start = after_index
-                index = after_index
-                continue
-        index += 1
-    predicates.append(where_body[start:])
-    return predicates
-
-
-def _is_time_range_predicate(
-    predicate: str,
-    *,
-    sql: str,
-    time_range: TimeRange,
-    allow_any_alias: bool = False,
-) -> bool:
-    field_pattern = _time_range_sql_field_pattern(sql, time_range, allow_any_alias=allow_any_alias)
-    if re.search(field_pattern, predicate, flags=re.IGNORECASE) is None:
-        return False
-    if re.search(r"'20\d{2}-\d{1,2}-\d{1,2}(?:\s+\d{1,2}:\d{2}:\d{2})?'", predicate) is None:
-        return False
-    return bool(re.search(r"(?:\bbetween\b|>=|>|<=|<|=)", predicate, flags=re.IGNORECASE))
-
-
-def _time_range_sql_field_pattern(
-    sql: str,
-    time_range: TimeRange,
-    *,
-    allow_any_alias: bool = False,
-) -> str:
-    field = re.escape(time_range.field.lower())
-    if allow_any_alias or not time_range.table_name:
-        return rf"(?:\b\w+\.)?{field}\b"
-    aliases = [
-        re.escape(alias)
-        for alias, table in _sql_table_aliases(sql).items()
-        if table == time_range.table_name.lower()
-    ]
-    aliases.append(re.escape(time_range.table_name.lower()))
-    qualifier = "|".join(sorted(set(aliases), key=len, reverse=True))
-    return rf"\b(?:{qualifier})\.{field}\b"
-
-
-def _time_range_sql_qualified_field(sql: str, time_range: TimeRange) -> str:
-    if not time_range.table_name:
-        return time_range.field
-    aliases = _sql_top_level_table_aliases(sql)
-    alias_candidates = [
-        alias
-        for alias, table in aliases.items()
-        if table == time_range.table_name.lower() and alias != time_range.table_name.lower()
-    ]
-    if alias_candidates:
-        return f"{sorted(alias_candidates, key=len)[0]}.{time_range.field}"
-    return f"{time_range.table_name}.{time_range.field}"
-
-
-def sql_missing_query_plan_filters(sql: str, query_plan: dict[str, Any] | None) -> list[str]:
-    """Return table.column LIKE filters from query_plan that are absent in sql."""
-    if not isinstance(query_plan, dict):
-        return []
-    missing: list[str] = []
-    normalized_sql = sql.lower()
-    grouped_filters: dict[str, list[dict[str, Any]]] = {}
-    plan_filters = [flt for flt in _query_plan_sql_filters(query_plan) if isinstance(flt, dict)]
-    for flt in plan_filters:
-        if str(flt.get("operator") or "").upper() != "LIKE":
-            continue
-        logical_group = str(flt.get("logicalGroup") or "").strip()
-        if logical_group:
-            grouped_filters.setdefault(logical_group, []).append(flt)
-        field = str(flt.get("field") or "").strip()
-        if "." not in field:
-            continue
-        table, column = field.split(".", 1)
-        value = str(flt.get("value") or "").strip().strip("%")
-        if not value:
-            continue
-        table_l = table.lower()
-        column_l = column.lower()
-        table_present = bool(re.search(rf"\b{re.escape(table_l)}\b", normalized_sql))
-        column_present = bool(re.search(rf"\b{re.escape(column_l)}\b", normalized_sql))
-        value_present = value.lower() in normalized_sql
-        if not table_present or not column_present or not value_present:
-            missing.append(f"{field} LIKE {flt.get('value')}")
-    for group_name, filters in grouped_filters.items():
-        if len(filters) <= 1:
-            continue
-        group_missing = [
-            f"{flt.get('field')} LIKE {flt.get('value')}"
-            for flt in filters
-            if f"{flt.get('field')} LIKE {flt.get('value')}" in missing
-        ]
-        if group_missing:
-            continue
-        if not _or_group_filters_connected_by_or(normalized_sql, filters):
-            missing.append(f"{group_name} requires OR between matched entities")
-    and_pairs = _hierarchical_location_and_filter_pairs(plan_filters)
-    for city_flt, region_flt in and_pairs:
-        city_token = f"{city_flt.get('field')} LIKE {city_flt.get('value')}"
-        region_token = f"{region_flt.get('field')} LIKE {region_flt.get('value')}"
-        if city_token in missing or region_token in missing:
-            continue
-        if _filters_connected_by_or(normalized_sql, [city_flt, region_flt]):
-            missing.append(
-                "city.name and region.name require AND for hierarchical location filters "
-                f"({city_flt.get('value')} AND {region_flt.get('value')})"
-            )
-            break
-    return missing
-
-
-def sql_satisfies_query_plan_filters(sql: str, query_plan: dict[str, Any] | None) -> bool:
-    return not sql_missing_query_plan_filters(sql, query_plan)
-
-
-def _query_plan_sql_filters(query_plan: dict[str, Any]) -> list[Any]:
-    filters = query_plan.get("_sqlFilters")
-    if isinstance(filters, list):
-        return filters
-    filters = query_plan.get("filters")
-    return filters if isinstance(filters, list) else []
-
-
-def _location_place_key_for_filter(value: str) -> str:
-    cleaned = str(value or "").strip().strip("%")
-    if not cleaned:
-        return ""
-    for suffix in ("自治州", "地区", "市", "区", "县", "旗"):
-        if cleaned.endswith(suffix) and len(cleaned) > len(suffix):
-            return cleaned[: -len(suffix)]
-    return cleaned
-
-
-def _hierarchical_location_and_filter_pairs(
-    filters: list[dict[str, Any]],
-) -> list[tuple[dict[str, Any], dict[str, Any]]]:
-    """City/region filters that must be AND-ed (distinct places, not same-place OR)."""
-    city_filters = [
-        flt
-        for flt in filters
-        if str(flt.get("field") or "") == "city.name" and str(flt.get("operator") or "").upper() == "LIKE"
-    ]
-    region_filters = [
-        flt
-        for flt in filters
-        if str(flt.get("field") or "") == "region.name" and str(flt.get("operator") or "").upper() == "LIKE"
-    ]
-    if not city_filters or not region_filters:
-        return []
-    pairs: list[tuple[dict[str, Any], dict[str, Any]]] = []
-    for city_flt in city_filters:
-        city_key = _location_place_key_for_filter(str(city_flt.get("value") or ""))
-        city_group = str(city_flt.get("logicalGroup") or "").strip()
-        city_op = str(city_flt.get("logicalOperator") or "").upper()
-        for region_flt in region_filters:
-            region_key = _location_place_key_for_filter(str(region_flt.get("value") or ""))
-            region_group = str(region_flt.get("logicalGroup") or "").strip()
-            region_op = str(region_flt.get("logicalOperator") or "").upper()
-            same_or_group = bool(
-                city_group
-                and city_group == region_group
-                and city_op == "OR"
-                and region_op == "OR"
-            )
-            if same_or_group:
-                continue
-            if city_key and region_key and city_key == region_key:
-                continue
-            pairs.append((city_flt, region_flt))
-    return pairs
-
-
-def _or_group_filters_connected_by_or(normalized_sql: str, filters: list[dict[str, Any]]) -> bool:
-    if not re.search(r"\bor\b", normalized_sql):
-        return False
-    positions: list[int] = []
-    for flt in filters:
-        value = str(flt.get("value") or "").strip().strip("%").lower()
-        if not value:
-            continue
-        found = normalized_sql.find(value)
-        if found >= 0:
-            positions.append(found)
-    if len(positions) < 2:
-        return True
-    start, end = min(positions), max(positions)
-    between = normalized_sql[start:end]
-    return bool(re.search(r"\bor\b", between))
-
-
-def _filters_connected_by_or(normalized_sql: str, filters: list[dict[str, Any]]) -> bool:
-    if not re.search(r"\bor\b", normalized_sql):
-        return False
-    positions: list[int] = []
-    for flt in filters:
-        value = str(flt.get("value") or "").strip().strip("%").lower()
-        if not value:
-            continue
-        found = normalized_sql.find(value)
-        if found >= 0:
-            positions.append(found)
-    if len(positions) < 2:
-        return False
-    start, end = min(positions), max(positions)
-    between = normalized_sql[start:end]
-    return bool(re.search(r"\bor\b", between))
-
-
-def sql_missing_query_plan_select_fields(sql: str, query_plan: dict[str, Any] | None) -> list[str]:
-    """Return required SELECT display fields from query_plan that are absent in sql."""
-    if not isinstance(query_plan, dict):
-        return []
-    select_clause = _select_clause(sql).lower()
-    if not select_clause:
-        return []
-    missing: list[str] = []
-    for item in query_plan.get("fields") or []:
-        if not isinstance(item, dict):
-            continue
-        if item.get("required") is not True and str(item.get("source") or "") != "search_entities":
-            continue
-        table = str(item.get("table") or "").strip()
-        field = str(item.get("field") or "").strip()
-        description = str(item.get("description") or "").strip()
-        if not table or not field:
-            continue
-        qualified = f"{table}.{field}".lower()
-        description_present = bool(description and description.lower() in select_clause)
-        qualified_present = qualified in select_clause
-        if not description_present and not qualified_present:
-            missing.append(f"{qualified} AS {description or field}")
-    return missing
-
-
-def sql_satisfies_query_plan_select_fields(sql: str, query_plan: dict[str, Any] | None) -> bool:
-    return not sql_missing_query_plan_select_fields(sql, query_plan)
-
-
-def _select_clause(sql: str) -> str:
-    match = re.search(r"\bselect\b(?P<select>.*?)\bfrom\b", sql, flags=re.IGNORECASE | re.DOTALL)
-    return match.group("select") if match else ""
-
-
-def sql_satisfies_time_range(
-    sql: str,
-    question: str,
-    schema: dict[str, Any] | None = None,
-    *,
-    query_plan: dict[str, Any] | None = None,
-) -> bool:
-    time_range = resolve_time_range(question, schema, query_plan=query_plan)
-    if time_range is None:
-        return True
-    normalized = sql.lower()
-    field_pattern = rf"(?:\b\w+\.)?{re.escape(time_range.field.lower())}\b"
-    if re.search(field_pattern, normalized) is None:
-        return False
-    if time_range.start[:10] in sql and time_range.end[:10] in sql:
-        return True
-    end_date = _parse_date(time_range.end[:10])
-    if end_date is not None:
-        inclusive_end = (end_date - timedelta(days=1)).isoformat()
-        if time_range.start[:10] in sql and inclusive_end in sql:
-            return True
-    year = time_range.start[:4]
-    month = str(int(time_range.start[5:7]))
-    padded_month = time_range.start[5:7]
-    return bool(
-        re.search(rf"\byear\s*\([^)]*{re.escape(time_range.field)}[^)]*\)\s*=\s*{year}\b", normalized)
-        and re.search(rf"\bmonth\s*\([^)]*{re.escape(time_range.field)}[^)]*\)\s*=\s*(?:{month}|{padded_month})\b", normalized)
-    )
-
-
-def _schema_limited_to_sql_tables(schema: dict[str, Any], sql: str) -> dict[str, Any] | None:
-    used_tables = _sql_referenced_table_names(sql)
-    if not used_tables:
-        return None
-    tables = schema.get("tables", [])
-    if not isinstance(tables, list):
-        return None
-    matched_tables = []
-    for table in tables:
-        if not isinstance(table, dict):
-            continue
-        table_name = str(table.get("tableName") or table.get("name") or "").lower()
-        if table_name in used_tables:
-            matched_tables.append(table)
-    if not matched_tables:
-        return None
-    limited = dict(schema)
-    limited["tables"] = matched_tables
-    return limited
-
-
-def _sql_referenced_table_names(sql: str) -> set[str]:
-    normalized = _strip_sql_string_literals(sql)
-    names: set[str] = set()
-    for match in re.finditer(
-        r"\b(?:from|join)\s+([a-zA-Z_][a-zA-Z0-9_]*)\b",
-        normalized,
-        flags=re.IGNORECASE,
-    ):
-        names.add(match.group(1).lower())
-    return names
-
-
-def _strip_sql_string_literals(sql: str) -> str:
-    result: list[str] = []
-    quote: str | None = None
-    index = 0
-    while index < len(sql):
-        char = sql[index]
-        if quote is not None:
-            if char == quote:
-                quote = None
-            result.append(" ")
-            index += 1
-            continue
-        if char in ("'", '"'):
-            quote = char
-            result.append(" ")
-            index += 1
-            continue
-        result.append(char)
-        index += 1
-    return "".join(result)
-
-
-def _table_names(schema: dict[str, Any]) -> set[str]:
-    tables = schema.get("tables", [])
-    if not isinstance(tables, list):
-        return set()
-    names: set[str] = set()
-    for table in tables:
-        if not isinstance(table, dict):
-            continue
-        name = table.get("name") or table.get("tableName")
-        if name:
-            names.add(str(name))
-    return names
-
-
-def _table_columns(schema: dict[str, Any], table_name: str) -> list[dict[str, Any]]:
-    tables = schema.get("tables", [])
-    if not isinstance(tables, list):
-        return []
-    for table in tables:
-        if not isinstance(table, dict):
-            continue
-        name = table.get("name") or table.get("tableName")
-        if str(name).lower() == str(table_name).lower() and isinstance(table.get("columns"), list):
-            return [column for column in table["columns"] if isinstance(column, dict)]
-    return []
-
-
-def _select_column(
-    schema: dict[str, Any],
-    table_name: str,
-    terms: tuple[str, ...],
-    fallback_names: tuple[str, ...],
-) -> str | None:
-    columns = _table_columns(schema, table_name)
-    best: tuple[int, str] | None = None
-    normalized_terms = [_normalize_semantic_text(term) for term in terms]
-    for column in columns:
-        name = str(column.get("columnName") or column.get("name") or "")
-        if not name:
-            continue
-        text = _normalize_semantic_text(f"{name}{column.get('comment') or ''}")
-        score = sum(10 for term in normalized_terms if term and term in text)
-        if name in fallback_names:
-            score += 5
-        if score > 0 and (best is None or score > best[0]):
-            best = (score, name)
-    if best is not None:
-        return best[1]
-    for name in fallback_names:
-        if _has_column(schema, table_name, name):
-            return name
-    return None
-
-
-def _has_column(schema: dict[str, Any], table_name: str, column_name: str) -> bool:
-    return any((column.get("columnName") or column.get("name")) == column_name for column in _table_columns(schema, table_name))
-
-
-def resolve_time_range_for_question(
-    question: str,
-    schema: dict[str, Any] | None = None,
-    *,
-    concepts: list[dict[str, Any]] | None = None,
-) -> TimeRange | None:
-    bounds = _extract_time_bounds(question)
-    if bounds is None:
-        return None
-    for concept in concepts or []:
-        qualified = str(concept.get("timeRangeField") or "").strip()
-        if "." not in qualified:
-            continue
-        table_name, field_name = qualified.rsplit(".", 1)
-        return TimeRange(
-            field=field_name,
-            alias="时间范围",
-            start=bounds[0],
-            end=bounds[1],
-            table_name=table_name,
-        )
-    field = _resolve_time_field(question, schema or {})
-    if field is None:
-        return None
-    return TimeRange(
-        field=field.name,
-        alias=field.alias,
-        start=bounds[0],
-        end=bounds[1],
-        table_name=field.table_name,
-    )
-
-
-def _extract_time_range(question: str, schema: dict[str, Any] | None = None) -> TimeRange | None:
-    return resolve_time_range_for_question(question, schema)
-
-
-def _resolve_time_field(question: str, schema: dict[str, Any]) -> FieldRef | None:
-    question_text = _normalize_semantic_text(question)
-    best: tuple[int, FieldRef] | None = None
-    for table in schema.get("tables", []) if isinstance(schema.get("tables"), list) else []:
-        if not isinstance(table, dict):
-            continue
-        columns = table.get("columns")
-        if not isinstance(columns, list):
-            continue
-        for column in columns:
-            if not isinstance(column, dict):
-                continue
-            name = str(column.get("columnName") or column.get("name") or "")
-            if not name:
-                continue
-            data_type = str(column.get("dataType") or column.get("type") or "")
-            comment = str(column.get("comment") or "")
-            if not _is_time_like_column(name, data_type, comment):
-                continue
-            score = _time_field_match_score(question_text, name, comment)
-            if score <= 0:
-                continue
-            table_name = str(table.get("tableName") or table.get("name") or "")
-            field_ref = FieldRef(
-                name=name,
-                alias=_column_alias(name, comment),
-                table_name=table_name,
-            )
-            if best is None or score > best[0]:
-                best = (score, field_ref)
-    if best is not None:
-        return best[1]
-    return None
-
-
-def _is_time_like_column(name: str, data_type: str, comment: str) -> bool:
-    lowered = f"{name} {data_type}".lower()
-    return bool(
-        re.search(r"(date|time|datetime|timestamp|_at$)", lowered)
-        or re.search(r"(时间|日期)", comment)
-    )
-
-
-def _time_field_match_score(question_text: str, name: str, comment: str) -> int:
-    field_text = _normalize_semantic_text(f"{name}{comment}")
-    score = 0
-    comment_text = _normalize_semantic_text(comment)
-    if comment_text and comment_text in question_text:
-        score += 50
-    name_text = _normalize_semantic_text(name)
-    if name_text and name_text in question_text:
-        score += 30
-    if "时间" in question_text and "时间" in field_text:
-        score += 5
-    if "日期" in question_text and ("时间" in field_text or "日期" in field_text):
-        score += 5
-    if "报名" in question_text and "报名" in comment_text:
-        score += 40
-    if re.search(r"(上架|发布|新上架)", question_text):
-        if "publish" in name.lower() or "发布" in comment_text:
-            score += 40
-    return score
-
-
-def _normalize_semantic_text(text: str) -> str:
-    normalized = text.lower()
-    return re.sub(r"[^0-9a-z\u4e00-\u9fff]+", "", normalized)
-
-
-def _column_alias(name: str, comment: str) -> str:
-    cleaned = re.sub(r"[。；;，,\s].*$", "", comment.strip())
-    if cleaned:
-        return cleaned
-    return name
-
-
-def _normalize_fullwidth_digits(text: str) -> str:
-    return text.translate(str.maketrans("０１２３４５６７８９", "0123456789"))
-
-
-def _extract_time_bounds(question: str) -> tuple[str, str] | None:
-    question = _normalize_fullwidth_digits(question)
-    date_range = _extract_explicit_date_range(question)
-    if date_range is not None:
-        return date_range
-    if re.search(r"(近|最近|过去)\s*(?:1|一)\s*年", question):
-        today = _today()
-        return _format_datetime(_one_year_before(today)), _format_datetime(today + timedelta(days=1))
-    if re.search(r"(今天|今日)", question):
-        today = _today()
-        return _format_datetime(today), _format_datetime(today + timedelta(days=1))
-    if re.search(r"(昨天|昨日)", question):
-        today = _today()
-        yesterday = today - timedelta(days=1)
-        return _format_datetime(yesterday), _format_datetime(today)
-    relative_month_match = re.search(r"(?P<relative_year>今年|去年|前年|明年|后年)\s*(?P<month>\d{1,2})\s*月(?:份)?", question)
-    if relative_month_match is not None:
-        year = _today().year + _relative_year_offset(relative_month_match.group("relative_year"))
-        month = int(relative_month_match.group("month"))
-        return _month_bounds(year, month)
-    if not re.search(r"20\d{2}\s*年", question):
-        cn_day_range = re.search(
-            r"(?P<month>\d{1,2})\s*月\s*(?P<start_day>\d{1,2})\s*日?\s*"
-            r"(?:到|至|~|～|-)\s*"
-            r"(?:(?P<end_month>\d{1,2})\s*月\s*)?(?P<end_day>\d{1,2})\s*日?",
-            question,
-        )
-        if cn_day_range is not None:
-            year = _today().year
-            month = int(cn_day_range.group("month"))
-            end_month_text = cn_day_range.group("end_month")
-            end_month = int(end_month_text) if end_month_text else month
-            if end_month != month:
-                return None
-            start_day = int(cn_day_range.group("start_day"))
-            end_day = int(cn_day_range.group("end_day"))
-            try:
-                start = date(year, month, start_day)
-                end = date(year, month, end_day)
-            except ValueError:
-                return None
-            if end >= start:
-                return _format_datetime(start), _format_datetime(end + timedelta(days=1))
-        single_cn_day = re.search(r"(?P<month>\d{1,2})\s*月\s*(?P<day>\d{1,2})\s*日", question)
-        if single_cn_day is not None and not re.search(r"(到|至|~|～|-)", question):
-            year = _today().year
-            try:
-                day = date(year, int(single_cn_day.group("month")), int(single_cn_day.group("day")))
-            except ValueError:
-                day = None
-            if day is not None:
-                return _format_datetime(day), _format_datetime(day + timedelta(days=1))
-        cn_month_only = re.search(
-            r"(?:整个|整)\s*(?P<month>\d{1,2})\s*月(?:份)?|(?P<month_only>\d{1,2})\s*月(?:份)?(?!\s*\d{1,2}\s*日)",
-            question,
-        )
-        if cn_month_only is not None:
-            month_text = cn_month_only.group("month") or cn_month_only.group("month_only")
-            if month_text is not None:
-                return _month_bounds(_today().year, int(month_text))
-    month_match = re.search(r"(?P<year>20\d{2})\s*年\s*(?P<month>\d{1,2})\s*月(?:份)?", question)
-    if month_match is None:
-        month_match = re.search(r"(?P<year>20\d{2})[-/](?P<month>\d{1,2})(?![-/]\d)", question)
-    if month_match is None:
-        return None
-    year = int(month_match.group("year"))
-    month = int(month_match.group("month"))
-    return _month_bounds(year, month)
-
-
-def _relative_year_offset(relative_year: str) -> int:
-    offsets = {
-        "今年": 0,
-        "去年": -1,
-        "前年": -2,
-        "明年": 1,
-        "后年": 2,
-    }
-    return offsets[relative_year]
-
-
-def _one_year_before(value: date) -> date:
-    try:
-        return value.replace(year=value.year - 1)
-    except ValueError:
-        return value.replace(year=value.year - 1, day=28)
-
-
-def _month_bounds(year: int, month: int) -> tuple[str, str] | None:
-    if not 1 <= month <= 12:
-        return None
-    start = date(year, month, 1)
-    end = date(year + 1, 1, 1) if month == 12 else date(year, month + 1, 1)
-    return _format_datetime(start), _format_datetime(end)
-
-
-def _extract_explicit_date_range(question: str) -> tuple[str, str] | None:
-    date_pattern = r"20\d{2}[-/]\d{1,2}[-/]\d{1,2}"
-    match = re.search(rf"(?P<start>{date_pattern})\s*(?:到|至|~|～)\s*(?P<end>{date_pattern})", question)
-    if match is None:
-        match = re.search(rf"(?P<start>{date_pattern})\s+-\s+(?P<end>{date_pattern})", question)
-    if match is None:
-        return None
-    start = _parse_date(match.group("start"))
-    end = _parse_date(match.group("end"))
-    if start is None or end is None or end < start:
-        return None
-    return _format_datetime(start), _format_datetime(end + timedelta(days=1))
-
-
-def _parse_date(value: str) -> date | None:
-    normalized = value.replace("/", "-")
-    parts = normalized.split("-")
-    if len(parts) != 3:
-        return None
-    try:
-        return date(int(parts[0]), int(parts[1]), int(parts[2]))
-    except ValueError:
-        return None
-
-
-def _format_datetime(value: date) -> str:
-    return f"{value.isoformat()} 00:00:00"
-
-
-def _today() -> date:
-    return date.today()
-
-
-def _is_business_query(question: str) -> bool:
-    return bool(
-        re.search(
-            r"(查询|查看|看看|搜索|统计|多少|几|哪些|有哪些|列表|明细|清单|展示|返回|输出|分析|报告|count|sum|avg|min|max)",
-            question,
-            flags=re.IGNORECASE,
-        )
-    )
-
-
-def _escape_sql_string(value: str) -> str:
-    return value.replace("\\", "\\\\").replace("'", "''")
-
-
-def _enforce_chinese_select_aliases(sql: str) -> None:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        raise SqlGenerationError("SQL must contain a top-level FROM")
-    for item in _split_top_level_select_items(select_list):
-        cleaned = item.strip()
-        if not cleaned:
-            continue
-        alias_match = re.search(
-            _SELECT_AS_ALIAS_PATTERN,
-            cleaned,
-            flags=re.IGNORECASE,
-        )
-        if alias_match is None:
-            raise SqlGenerationError("Every SELECT field must use AS with a Chinese alias")
-        alias = alias_match.group(1).strip("`\"'")
-        if re.search(r"[\u4e00-\u9fff]", alias) is None:
-            raise SqlGenerationError("Every SELECT alias must contain Chinese characters")
-
-
-def _enforce_no_null_placeholder_select_items(sql: str) -> None:
-    select_list = _top_level_select_list(sql)
-    if select_list is None:
-        raise SqlGenerationError("SQL must contain a top-level FROM")
-    for item in _split_top_level_select_items(select_list):
-        expression = _select_expression_without_alias(item)
-        if _is_null_placeholder_expression(expression):
-            raise SqlGenerationError("SELECT fields must not use NULL placeholders")
-
-
-def _select_expression_without_alias(item: str) -> str:
-    return re.sub(
-        _SELECT_AS_ALIAS_PATTERN,
-        "",
-        item.strip(),
-        flags=re.IGNORECASE,
-    ).strip()
-
-
-def _is_null_placeholder_expression(expression: str) -> bool:
-    normalized = expression.strip().rstrip(";")
-    if re.fullmatch(r"null", normalized, flags=re.IGNORECASE):
-        return True
-    if re.fullmatch(r"cast\s*\(\s*null\s+as\s+[^)]+\)", normalized, flags=re.IGNORECASE):
-        return True
-    return bool(re.fullmatch(r"convert\s*\(\s*null\s*,\s*[^)]+\)", normalized, flags=re.IGNORECASE))
-
-
-def _top_level_select_list(sql: str) -> str | None:
-    stripped = sql.strip().rstrip(";")
-    match = re.match(r"select\s+(?:distinct\s+)?", stripped, flags=re.IGNORECASE)
-    if match is None:
-        return None
-    start = match.end()
-    from_index = _find_top_level_keyword(stripped, "from", start=start)
-    if from_index is None:
-        return None
-    return stripped[start:from_index]
-
-
-def _find_top_level_keyword(sql: str, keyword: str, *, start: int) -> int | None:
-    depth = 0
-    quote: str | None = None
-    keyword_lower = keyword.lower()
-    index = start
-    while index < len(sql):
-        char = sql[index]
-        if quote is not None:
-            if char == quote:
-                quote = None
-            elif char == "\\":
-                index += 1
-            index += 1
-            continue
-        if char in ("'", '"', "`"):
-            quote = char
-            index += 1
-            continue
-        if char == "(":
-            depth += 1
-            index += 1
-            continue
-        if char == ")":
-            depth = max(0, depth - 1)
-            index += 1
-            continue
-        if depth == 0 and sql[index : index + len(keyword_lower)].lower() == keyword_lower:
-            before = sql[index - 1] if index > 0 else " "
-            after_index = index + len(keyword_lower)
-            after = sql[after_index] if after_index < len(sql) else " "
-            if not (before.isalnum() or before == "_") and not (after.isalnum() or after == "_"):
-                return index
-        index += 1
-    return None
-
-
-def _split_top_level_select_items(select_list: str) -> list[str]:
-    items: list[str] = []
-    depth = 0
-    quote: str | None = None
-    start = 0
-    for index, char in enumerate(select_list):
-        if quote is not None:
-            if char == quote:
-                quote = None
-            elif char == "\\":
-                continue
-            continue
-        if char in ("'", '"', "`"):
-            quote = char
-            continue
-        if char == "(":
-            depth += 1
-            continue
-        if char == ")":
-            depth = max(0, depth - 1)
-            continue
-        if char == "," and depth == 0:
-            items.append(select_list[start:index])
-            start = index + 1
-    items.append(select_list[start:])
-    return items