@roll-agent/octopus-agent 0.0.1 → 0.0.2

package/src/octopus_sponge_skill/sql_generator.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from datetime import date, timedelta
 import re
 from dataclasses import dataclass
 from typing import Any
@@ -14,6 +15,29 @@ 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
+
+
+@dataclass(frozen=True)
+class TimeRange:
+    field: str
+    alias: str
+    start: str
+    end: str
+
+
+@dataclass(frozen=True)
+class FieldRef:
+    name: str
+    alias: str
+
+
+@dataclass(frozen=True)
+class SchemaValidationIssue:
+    code: str
+    message: str
 
 
 @dataclass
@@ -26,30 +50,92 @@ class RuleBasedSqlGenerator:
         *,
         question: str,
         schema: dict[str, Any],
-        scope_hints: dict[str, Any],
     ) -> GeneratedSql:
         table_names = _table_names(schema)
         lowered = question.lower()
 
-        if ("品牌" in question or "brand" in lowered) and {"brand", "brand_project"}.issubset(table_names):
+        if _is_monthly_recruiting_conversion_query(question):
+            return _generate_monthly_recruiting_conversion_sql(question, schema, self.default_limit)
+        if is_recruiting_match_effect_query(question):
+            return _generate_recruiting_match_effect_sql(question, schema, self.default_limit)
+        if _is_recruiting_supply_multi_metric_query(question):
+            return _generate_recruiting_supply_metric_sql(question, schema, self.default_limit)
+        if _is_work_order_detail_query(question):
+            return _generate_work_order_detail_sql(question, schema, self.default_limit)
+        if _is_multi_metric_query(question):
+            raise SqlGenerationError("Multi-metric query requires schema-driven metric generation")
+
+        if ("品牌" in question or "brand" in lowered) and "brand" in table_names:
+            brand_filter = _extract_brand_filter(question)
+            brand_where = "b.is_delete = 0"
+            if brand_filter is not None:
+                operator, brand_name = brand_filter
+                if operator == "contains":
+                    brand_where = f"b.is_delete = 0 AND b.name LIKE '%{_escape_sql_string(brand_name)}%'"
+                else:
+                    brand_where = f"b.is_delete = 0 AND b.name = '{_escape_sql_string(brand_name)}'"
             sql = (
-                "SELECT b.id AS brand_id, b.name AS brand_name "
+                "SELECT b.id AS 品牌ID, b.name AS 品牌名称 "
                 "FROM brand b "
-                "JOIN brand_project bp ON bp.brand_id = b.id "
-                "WHERE bp.project_id IN (:scope.project_ids) "
-                "AND b.id IN (:scope.brand_ids) "
+                f"WHERE {brand_where} "
                 f"LIMIT {self.default_limit}"
             )
-            return GeneratedSql(sql, ["brand", "brand_project"], _placeholders(scope_hints))
+            return GeneratedSql(sql, ["brand"], [])
 
         if ("项目" in question or "project" in lowered) and "sponge_project" in table_names:
             sql = (
-                "SELECT p.id AS project_id, p.name AS project_name "
+                "SELECT p.id AS 项目ID, p.name AS 项目名称 "
                 "FROM sponge_project p "
-                "WHERE p.id IN (:scope.project_ids) "
+                "WHERE p.is_delete = 0 "
                 f"LIMIT {self.default_limit}"
             )
-            return GeneratedSql(sql, ["sponge_project"], [":scope.project_ids"])
+            return GeneratedSql(sql, ["sponge_project"], [])
+
+        if _is_recruiting_job_question(question) and _requires_recruiting_detail_joins(question):
+            return _generate_recruiting_detail_sql(question, schema, self.default_limit)
+
+        if _is_recruiting_remaining_signup_query(question):
+            raise SqlGenerationError("Remaining signup metrics require schema-driven metric generation")
+
+        location = _extract_location_for_recruiting_job_question(question)
+        if location and _has_recruiting_location_tables(table_names):
+            escaped_location = _escape_sql_string(location)
+            from_and_where = _append_job_time_range_condition(
+                _recruiting_location_from_and_where(escaped_location),
+                question,
+                schema,
+            )
+            if _question_requests_count(question):
+                sql = f"SELECT COUNT(DISTINCT jbi.id) AS 在招岗位数量 {from_and_where} LIMIT {self.default_limit}"
+            else:
+                select_items = _job_basic_select_items(question, schema)
+                order_by = _job_order_by(question, schema)
+                sql = (
+                    f"SELECT DISTINCT {select_items} "
+                    f"{from_and_where} "
+                    f"{order_by} "
+                    f"LIMIT {self.default_limit}"
+                )
+            return GeneratedSql(
+                sql,
+                ["job_basic_info", "job_address", "job_store", "store", "province", "city", "region"],
+                [],
+            )
+
+        if _is_recruiting_job_question(question) and _has_recruiting_tables(table_names):
+            from_and_where = _append_job_time_range_condition(_recruiting_from_and_where(), question, schema)
+            if _question_requests_count(question):
+                sql = f"SELECT COUNT(DISTINCT jbi.id) AS 在招岗位数量 {from_and_where} LIMIT {self.default_limit}"
+            else:
+                select_items = _job_basic_select_items(question, schema)
+                order_by = _job_order_by(question, schema)
+                sql = (
+                    f"SELECT DISTINCT {select_items} "
+                    f"{from_and_where} "
+                    f"{order_by} "
+                    f"LIMIT {self.default_limit}"
+                )
+            return GeneratedSql(sql, ["job_basic_info"], [])
 
         raise SqlGenerationError("No safe SQL template matched the question")
 
@@ -64,6 +150,10 @@ def enforce_sql_rules(sql: str, *, max_limit: int) -> None:
         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 ":scope." in normalized:
+        raise SqlGenerationError("SQL must not contain scope placeholders")
+    _enforce_chinese_select_aliases(sql)
+    _enforce_no_null_placeholder_select_items(sql)
     limit = re.search(r"\blimit\s+(\d+)\b", normalized)
     if limit is None:
         raise SqlGenerationError("SQL must contain LIMIT")
@@ -71,6 +161,164 @@ def enforce_sql_rules(sql: str, *, max_limit: int) -> None:
         raise SqlGenerationError(f"SQL LIMIT must not exceed {max_limit}")
 
 
+def is_low_quality_sql_for_question(question: str, sql: str) -> bool:
+    normalized = re.sub(r"\s+", " ", sql.strip().lower())
+    brand_filter = _extract_brand_filter(question)
+    if brand_filter is not None and _sql_references_brand_table(sql) and not _sql_contains_brand_name_filter(sql, brand_filter[1]):
+        return True
+    if _is_work_order_detail_query(question):
+        if "mvp_applied_jobs_by_helped_account" not in normalized:
+            return True
+        if re.search(r"\bfrom\s+brand\b", normalized) and "mvp_applied_jobs_by_helped_account" not in normalized:
+            return True
+        if _has_work_order_job_id_to_job_pk_join(normalized):
+            return True
+        if "面试成功" in question and "interview_pass_status" in normalized:
+            return True
+    return False
+
+
+def validate_sql_against_schema(sql: str, schema: dict[str, Any]) -> list[SchemaValidationIssue]:
+    issues: list[SchemaValidationIssue] = []
+    table_aliases = _sql_table_aliases(sql)
+    schema_tables = _table_names(schema)
+    for table in table_aliases.values():
+        if table not in schema_tables:
+            issues.append(
+                SchemaValidationIssue(
+                    code="UNKNOWN_TABLE",
+                    message=f"SQL 使用了 schema 中不存在的表：{table}",
+                )
+            )
+
+    if {"mvp_applied_jobs_by_helped_account", "job_basic_info"} <= set(table_aliases.values()):
+        join_pairs = _sql_equality_pairs(sql, table_aliases)
+        allowed_pairs = _schema_allowed_join_pairs(schema)
+        work_order_job_pairs = {
+            pair
+            for pair in join_pairs
+            if {pair[0][0], pair[1][0]} == {"mvp_applied_jobs_by_helped_account", "job_basic_info"}
+            and (pair[0][1] == "job_id" or pair[1][1] == "job_id")
+        }
+        if not any(pair in allowed_pairs for pair in work_order_job_pairs):
+            issues.append(
+                SchemaValidationIssue(
+                    code="JOIN_NOT_IN_SCHEMA",
+                    message="报名工单和岗位表必须使用 schema 声明的 mvp_applied_jobs_by_helped_account.job_id = job_basic_info.job_id 关联。",
+                )
+            )
+    return issues
+
+
+def _has_work_order_job_id_to_job_pk_join(normalized_sql: str) -> bool:
+    table_aliases = _sql_table_aliases(normalized_sql)
+    pairs = _sql_equality_pairs(normalized_sql, table_aliases)
+    return any(
+        {left[0], right[0]} == {"mvp_applied_jobs_by_helped_account", "job_basic_info"}
+        and (
+            (left[0] == "mvp_applied_jobs_by_helped_account" and left[1] == "job_id" and right[1] == "id")
+            or (right[0] == "mvp_applied_jobs_by_helped_account" and right[1] == "job_id" and left[1] == "id")
+        )
+        for left, right in pairs
+    )
+
+
+def _sql_table_aliases(sql: str) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    for match in re.finditer(
+        r"\b(?:from|join)\s+([a-zA-Z_][a-zA-Z0-9_]*)(?:\s+(?:as\s+)?([a-zA-Z_][a-zA-Z0-9_]*))?",
+        sql,
+        flags=re.IGNORECASE,
+    ):
+        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
+    return aliases
+
+
+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()
+    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,
+    ):
+        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()
+    joins = schema.get("joins", [])
+    if isinstance(joins, list):
+        for join in joins:
+            if not isinstance(join, dict):
+                continue
+            left_table = str(join.get("leftTable") or join.get("from") or "").lower()
+            left_column = str(join.get("leftColumn") or join.get("fromColumn") or "").lower()
+            right_table = str(join.get("rightTable") or join.get("to") or "").lower()
+            right_column = str(join.get("rightColumn") or join.get("toColumn") or "").lower()
+            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_name in ("metrics", "glossary", "examples"):
+        section = schema.get(section_name, [])
+        if isinstance(section, list):
+            for item in section:
+                if isinstance(item, dict):
+                    pairs.update(_join_pairs_from_text(str(item)))
+    return pairs
+
+
+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 sql_satisfies_time_range(sql: str, question: str, schema: dict[str, Any] | None = None) -> bool:
+    time_range = _extract_time_range(question, schema)
+    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
+    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 _table_names(schema: dict[str, Any]) -> set[str]:
     tables = schema.get("tables", [])
     if not isinstance(tables, list):
@@ -85,9 +333,1101 @@ def _table_names(schema: dict[str, Any]) -> set[str]:
     return names
 
 
-def _placeholders(scope_hints: dict[str, Any]) -> list[str]:
-    placeholders: list[str] = []
-    for value in scope_hints.values():
-        if isinstance(value, dict) and value.get("placeholder"):
-            placeholders.append(str(value["placeholder"]))
-    return placeholders
+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 name == table_name and isinstance(table.get("columns"), list):
+            return [column for column in table["columns"] if isinstance(column, dict)]
+    return []
+
+
+def _generate_recruiting_detail_sql(question: str, schema: dict[str, Any], default_limit: int) -> GeneratedSql:
+    table_names = _table_names(schema)
+    if "job_basic_info" not in table_names:
+        raise SqlGenerationError("job_basic_info is required for recruiting detail query")
+
+    select_items = _recruiting_detail_select_items(question, schema)
+    from_and_where = _append_job_time_range_condition(_recruiting_detail_from_and_where(table_names), question, schema)
+    order_by = _job_order_by(question, schema)
+    sql = f"SELECT DISTINCT {', '.join(select_items)} {from_and_where} {order_by} LIMIT {default_limit}"
+    tables = [
+        table
+        for table in ("job_basic_info", "job_store", "store", "job_salary", "job_hiring_requirement")
+        if table in table_names
+    ]
+    return GeneratedSql(sql, tables, [])
+
+
+def _generate_work_order_detail_sql(question: str, schema: dict[str, Any], default_limit: int) -> GeneratedSql:
+    example = _find_work_order_detail_example(schema)
+    if example is None:
+        raise SqlGenerationError("Work order detail query requires a schema example")
+    brand_name = _extract_brand_name(question)
+    if brand_name is None:
+        raise SqlGenerationError("Work order detail query requires a brand name")
+    sql = str(example.get("sql") or "")
+    if not sql:
+        raise SqlGenerationError("Work order detail schema example has no SQL")
+    sql = re.sub(
+        r"b\.name\s*=\s*'[^']*'",
+        f"b.name = '{_escape_sql_string(brand_name)}'",
+        sql,
+        count=1,
+        flags=re.IGNORECASE,
+    )
+    tables = [str(table) for table in example.get("tables", []) if table]
+    return GeneratedSql(sql, tables, [])
+
+
+def _find_work_order_detail_example(schema: dict[str, Any]) -> dict[str, Any] | None:
+    examples = schema.get("examples", [])
+    if not isinstance(examples, list):
+        return None
+    for example in examples:
+        if not isinstance(example, dict):
+            continue
+        text = f"{example.get('question') or ''} {example.get('sql') or ''}"
+        if (
+            "mvp_applied_jobs_by_helped_account" in text
+            and "account_name" in text
+            and "work_order_status" in text
+            and "报名" in text
+            and "候选人状态" in text
+        ):
+            return example
+    return None
+
+
+def _generate_recruiting_supply_metric_sql(question: str, schema: dict[str, Any], default_limit: int) -> GeneratedSql:
+    table_names = _table_names(schema)
+    required = {"job_basic_info", "job_store", "store"}
+    if not required <= table_names:
+        raise SqlGenerationError("Recruiting supply metrics require job_basic_info, job_store and store")
+
+    select_items: list[str] = []
+    group_by: list[str] = []
+    joins = [
+        "FROM job_basic_info jbi",
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0",
+        "LEFT JOIN store s ON s.id = js.store_id AND s.delete_at IS NULL",
+    ]
+    tables = ["job_basic_info", "job_store", "store"]
+
+    if "品牌" in question and "brand" in table_names and _has_column(schema, "job_basic_info", "brand_id"):
+        joins.append("LEFT JOIN brand b ON b.id = jbi.brand_id")
+        select_items.extend(["b.id AS 品牌ID", "b.name AS 品牌名称"])
+        group_by.extend(["b.id", "b.name"])
+        tables.append("brand")
+    if "项目" in question and "sponge_project" in table_names and _has_column(schema, "job_basic_info", "organization_id"):
+        joins.append("LEFT JOIN sponge_project p ON p.id = jbi.organization_id")
+        select_items.extend(["p.id AS 项目ID", "p.name AS 项目名称"])
+        group_by.extend(["p.id", "p.name"])
+        tables.append("sponge_project")
+    if "城市" in question and "city" in table_names and _has_column(schema, "store", "city_id"):
+        joins.append("LEFT JOIN city c ON c.id = s.city_id")
+        select_items.extend(["c.id AS 城市ID", "c.name AS 城市名称"])
+        group_by.extend(["c.id", "c.name"])
+        tables.append("city")
+    if "区域" in question and "region" in table_names and _has_column(schema, "store", "region_id"):
+        joins.append("LEFT JOIN region r ON r.id = s.region_id")
+        select_items.extend(["r.id AS 区域ID", "r.name AS 区域名称"])
+        group_by.extend(["r.id", "r.name"])
+        tables.append("region")
+
+    if not select_items:
+        raise SqlGenerationError("Recruiting supply metric query requires at least one grouping dimension")
+    select_items.extend(
+        [
+            "COUNT(DISTINCT jbi.id) AS 在招岗位数",
+            "SUM(COALESCE(js.requirement_num, 0)) AS 招聘人数",
+            "COUNT(DISTINCT js.store_id) AS 招聘门店数",
+        ]
+    )
+    from_and_where = _append_job_time_range_condition(" ".join(joins) + " WHERE jbi.is_deleted = 0 AND jbi.status = 1", question, schema)
+    sql = (
+        f"SELECT {', '.join(select_items)} {from_and_where} "
+        f"GROUP BY {', '.join(group_by)} "
+        "ORDER BY 在招岗位数 DESC "
+        f"LIMIT {default_limit}"
+    )
+    return GeneratedSql(sql, list(dict.fromkeys(tables)), [])
+
+
+def _generate_monthly_recruiting_conversion_sql(question: str, schema: dict[str, Any], default_limit: int) -> GeneratedSql:
+    table_names = _table_names(schema)
+    required = {"mvp_applied_jobs_by_helped_account", "job_basic_info", "brand", "sponge_project"}
+    if not required <= table_names:
+        raise SqlGenerationError("Monthly recruiting conversion requires work order, job, brand and project tables")
+    year_bounds = _extract_year_bounds(question)
+    if year_bounds is None:
+        raise SqlGenerationError("Monthly recruiting conversion query requires a year range")
+    start, end = year_bounds
+    has_store = "store" in table_names
+    store_join = "LEFT JOIN store st ON st.id = wo.store_id AND st.delete_at IS NULL" if has_store else ""
+    brand_expr = "COALESCE(jbi.brand_id, st.brand_id)" if has_store else "jbi.brand_id"
+    project_expr = "COALESCE(jbi.organization_id, st.organization_id)" if has_store else "jbi.organization_id"
+    tables = ["mvp_applied_jobs_by_helped_account", "job_basic_info", "brand", "sponge_project"]
+    if has_store:
+        tables.append("store")
+
+    signup_sql = _monthly_conversion_event_sql(
+        start=start,
+        end=end,
+        date_field="wo.sign_up_time",
+        brand_expr=brand_expr,
+        project_expr=project_expr,
+        store_join=store_join,
+        signup_value=1,
+        onboard_value=0,
+        extra_condition="",
+    )
+    onboard_sql = _monthly_conversion_event_sql(
+        start=start,
+        end=end,
+        date_field="wo.on_work_time",
+        brand_expr=brand_expr,
+        project_expr=project_expr,
+        store_join=store_join,
+        signup_value=0,
+        onboard_value=1,
+        extra_condition="AND wo.on_work_status = 1",
+    )
+    sql = (
+        "SELECT monthly.月份 AS 月份, b.id AS 品牌ID, b.name AS 品牌名称, "
+        "p.id AS 项目ID, p.name AS 项目名称, "
+        "SUM(monthly.报名人数) AS 报名人数, "
+        "SUM(monthly.入职人数) AS 入职人数, "
+        "ROUND(SUM(monthly.入职人数) / NULLIF(SUM(monthly.报名人数), 0), 4) AS 报名转化率, "
+        "ROUND(SUM(monthly.入职人数) / NULLIF(SUM(monthly.报名人数), 0), 4) AS 入职转化率 "
+        f"FROM (({signup_sql}) UNION ALL ({onboard_sql})) monthly "
+        "LEFT JOIN brand b ON b.id = monthly.brand_id "
+        "LEFT JOIN sponge_project p ON p.id = monthly.project_id "
+        "GROUP BY monthly.月份, b.id, b.name, p.id, p.name "
+        "ORDER BY monthly.月份 ASC, 报名人数 DESC, 入职人数 DESC "
+        f"LIMIT {default_limit}"
+    )
+    return GeneratedSql(sql, tables, [])
+
+
+def _monthly_conversion_event_sql(
+    *,
+    start: str,
+    end: str,
+    date_field: str,
+    brand_expr: str,
+    project_expr: str,
+    store_join: str,
+    signup_value: int,
+    onboard_value: int,
+    extra_condition: str,
+) -> str:
+    return (
+        f"SELECT DATE_FORMAT({date_field}, '%Y-%m') AS 月份, "
+        f"{brand_expr} AS brand_id, {project_expr} AS project_id, "
+        f"COUNT(DISTINCT wo.id) * {signup_value} AS 报名人数, "
+        f"COUNT(DISTINCT wo.id) * {onboard_value} AS 入职人数 "
+        "FROM mvp_applied_jobs_by_helped_account wo "
+        "JOIN job_basic_info jbi ON jbi.job_id = wo.job_id AND jbi.is_deleted = 0 "
+        f"{store_join} "
+        f"WHERE wo.delete_at IS NULL AND {date_field} >= '{start}' AND {date_field} < '{end}' "
+        f"{extra_condition} "
+        f"GROUP BY DATE_FORMAT({date_field}, '%Y-%m'), {brand_expr}, {project_expr}"
+    )
+
+
+def _generate_recruiting_match_effect_sql(question: str, schema: dict[str, Any], default_limit: int) -> GeneratedSql:
+    table_names = _table_names(schema)
+    required = {
+        "job_basic_info",
+        "job_store",
+        "store",
+        "brand",
+        "sponge_project",
+        "city",
+        "mvp_applied_jobs_by_helped_account",
+    }
+    if not required <= table_names:
+        raise SqlGenerationError("Recruiting match effect requires job, store, brand, project, city and work order tables")
+
+    time_bounds = _extract_time_bounds(question)
+    if time_bounds is None:
+        raise SqlGenerationError("Recruiting match effect query requires a time range")
+    start, end = time_bounds
+    candidate_expr = "wo.c_helped_account_id"
+    signup_join = ""
+    signup_city = "st.city_id"
+    tables = [
+        "job_basic_info",
+        "job_store",
+        "store",
+        "brand",
+        "sponge_project",
+        "city",
+        "mvp_applied_jobs_by_helped_account",
+    ]
+    if "sign_up" in table_names:
+        signup_join = "LEFT JOIN sign_up su ON su.id = wo.sign_up_id AND su.delete_at IS NULL"
+        candidate_expr = "COALESCE(wo.c_helped_account_id, su.resume_id)"
+        signup_city = "COALESCE(st.city_id, su.city_id)"
+        tables.append("sign_up")
+
+    supply_dimension_sql = _match_effect_supply_dimension_sql(start, end)
+    match_dimension_sql = _match_effect_match_dimension_sql(start, end, signup_join, signup_city)
+    supply_metric_sql = _match_effect_supply_metric_sql(start, end)
+    match_metric_sql = _match_effect_match_metric_sql(start, end, signup_join, signup_city, candidate_expr)
+
+    sql = (
+        "SELECT b.id AS 品牌ID, b.name AS 品牌名称, p.id AS 项目ID, p.name AS 项目名称, "
+        "c.id AS 城市ID, c.name AS 城市名称, "
+        "COALESCE(supply.在招岗位数, 0) AS 在招岗位数, "
+        "COALESCE(supply.招聘人数, 0) AS 招聘人数, "
+        "COALESCE(supply.招聘门店数, 0) AS 招聘门店数, "
+        "COALESCE(match_data.报名人数, 0) AS 报名人数, "
+        "COALESCE(match_data.入职人数, 0) AS 入职人数, "
+        "COALESCE(match_data.候选人数, 0) AS 候选人数, "
+        "COALESCE(match_data.报名人数, 0) - COALESCE(match_data.入职人数, 0) AS 报名入职差, "
+        "ROUND(COALESCE(match_data.报名人数, 0) / NULLIF(COALESCE(supply.在招岗位数, 0), 0), 2) AS 岗位报名比, "
+        "ROUND(COALESCE(match_data.候选人数, 0) / NULLIF(COALESCE(supply.在招岗位数, 0), 0), 2) AS 候选岗位比, "
+        "COALESCE(NULLIF(CONCAT_WS('、', "
+        "IF(COALESCE(match_data.报名人数, 0) > COALESCE(match_data.入职人数, 0), '报名多但入职少', NULL), "
+        "IF(COALESCE(supply.在招岗位数, 0) > COALESCE(match_data.报名人数, 0), '在招多但报名少', NULL), "
+        "IF(COALESCE(match_data.候选人数, 0) > COALESCE(supply.在招岗位数, 0), '候选人多但岗位少', NULL)"
+        "), ''), '正常') AS 问题类型 "
+        f"FROM (({supply_dimension_sql}) UNION ({match_dimension_sql})) dimension_base "
+        "LEFT JOIN brand b ON b.id = dimension_base.brand_id "
+        "LEFT JOIN sponge_project p ON p.id = dimension_base.project_id "
+        "LEFT JOIN city c ON c.id = dimension_base.city_id "
+        f"LEFT JOIN ({supply_metric_sql}) supply ON supply.brand_id <=> dimension_base.brand_id "
+        "AND supply.project_id <=> dimension_base.project_id AND supply.city_id <=> dimension_base.city_id "
+        f"LEFT JOIN ({match_metric_sql}) match_data ON match_data.brand_id <=> dimension_base.brand_id "
+        "AND match_data.project_id <=> dimension_base.project_id AND match_data.city_id <=> dimension_base.city_id "
+        "WHERE COALESCE(match_data.报名人数, 0) > COALESCE(match_data.入职人数, 0) "
+        "OR COALESCE(supply.在招岗位数, 0) > COALESCE(match_data.报名人数, 0) "
+        "OR COALESCE(match_data.候选人数, 0) > COALESCE(supply.在招岗位数, 0) "
+        "ORDER BY 报名入职差 DESC, 在招岗位数 DESC, 候选岗位比 DESC "
+        f"LIMIT {default_limit}"
+    )
+    return GeneratedSql(sql, list(dict.fromkeys(tables)), [])
+
+
+def _match_effect_supply_dimension_sql(start: str, end: str) -> str:
+    return (
+        "SELECT jbi.brand_id AS brand_id, jbi.organization_id AS project_id, st.city_id AS city_id "
+        "FROM job_basic_info jbi "
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0 "
+        "LEFT JOIN store st ON st.id = js.store_id AND st.delete_at IS NULL "
+        "WHERE jbi.is_deleted = 0 AND jbi.status = 1 "
+        f"AND jbi.create_at >= '{start}' AND jbi.create_at < '{end}' "
+        "GROUP BY jbi.brand_id, jbi.organization_id, st.city_id"
+    )
+
+
+def _match_effect_match_dimension_sql(start: str, end: str, signup_join: str, signup_city: str) -> str:
+    return (
+        f"SELECT jbi.brand_id AS brand_id, jbi.organization_id AS project_id, {signup_city} AS city_id "
+        "FROM mvp_applied_jobs_by_helped_account wo "
+        "JOIN job_basic_info jbi ON jbi.job_id = wo.job_id AND jbi.is_deleted = 0 "
+        f"{signup_join} "
+        "LEFT JOIN store st ON st.id = wo.store_id AND st.delete_at IS NULL "
+        "WHERE wo.delete_at IS NULL AND ("
+        f"(wo.sign_up_time >= '{start}' AND wo.sign_up_time < '{end}') "
+        f"OR (wo.on_work_time >= '{start}' AND wo.on_work_time < '{end}')"
+        ") "
+        f"GROUP BY jbi.brand_id, jbi.organization_id, {signup_city}"
+    )
+
+
+def _match_effect_supply_metric_sql(start: str, end: str) -> str:
+    return (
+        "SELECT jbi.brand_id AS brand_id, jbi.organization_id AS project_id, st.city_id AS city_id, "
+        "COUNT(DISTINCT jbi.id) AS 在招岗位数, "
+        "SUM(COALESCE(js.requirement_num, 0)) AS 招聘人数, "
+        "COUNT(DISTINCT js.store_id) AS 招聘门店数 "
+        "FROM job_basic_info jbi "
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0 "
+        "LEFT JOIN store st ON st.id = js.store_id AND st.delete_at IS NULL "
+        "WHERE jbi.is_deleted = 0 AND jbi.status = 1 "
+        f"AND jbi.create_at >= '{start}' AND jbi.create_at < '{end}' "
+        "GROUP BY jbi.brand_id, jbi.organization_id, st.city_id"
+    )
+
+
+def _match_effect_match_metric_sql(
+    start: str,
+    end: str,
+    signup_join: str,
+    signup_city: str,
+    candidate_expr: str,
+) -> str:
+    return (
+        f"SELECT jbi.brand_id AS brand_id, jbi.organization_id AS project_id, {signup_city} AS city_id, "
+        f"COUNT(DISTINCT CASE WHEN wo.sign_up_time >= '{start}' AND wo.sign_up_time < '{end}' THEN wo.id END) AS 报名人数, "
+        "COUNT(DISTINCT CASE WHEN wo.on_work_status = 1 "
+        f"AND wo.on_work_time >= '{start}' AND wo.on_work_time < '{end}' THEN wo.id END) AS 入职人数, "
+        f"COUNT(DISTINCT CASE WHEN wo.sign_up_time >= '{start}' AND wo.sign_up_time < '{end}' THEN {candidate_expr} END) AS 候选人数 "
+        "FROM mvp_applied_jobs_by_helped_account wo "
+        "JOIN job_basic_info jbi ON jbi.job_id = wo.job_id AND jbi.is_deleted = 0 "
+        f"{signup_join} "
+        "LEFT JOIN store st ON st.id = wo.store_id AND st.delete_at IS NULL "
+        "WHERE wo.delete_at IS NULL AND ("
+        f"(wo.sign_up_time >= '{start}' AND wo.sign_up_time < '{end}') "
+        f"OR (wo.on_work_time >= '{start}' AND wo.on_work_time < '{end}')"
+        ") "
+        f"GROUP BY jbi.brand_id, jbi.organization_id, {signup_city}"
+    )
+
+
+def _recruiting_detail_from_and_where(table_names: set[str]) -> str:
+    parts = ["FROM job_basic_info jbi"]
+    if "job_store" in table_names:
+        parts.append("LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0")
+    if {"job_store", "store"} <= table_names:
+        parts.append("LEFT JOIN store s ON s.id = js.store_id AND s.delete_at IS NULL")
+    if "job_salary" in table_names:
+        parts.append("LEFT JOIN job_salary jsa ON jsa.job_basic_info_id = jbi.id AND jsa.is_deleted = 0")
+    if "job_hiring_requirement" in table_names:
+        parts.append("LEFT JOIN job_hiring_requirement jhr ON jhr.job_basic_info_id = jbi.id AND jhr.is_deleted = 0")
+    parts.append("WHERE jbi.is_deleted = 0 AND jbi.status = 1")
+    return " ".join(parts)
+
+
+def _recruiting_detail_select_items(question: str, schema: dict[str, Any]) -> list[str]:
+    items = [
+        "jbi.id AS 岗位ID",
+        "jbi.job_name AS 岗位名称",
+    ]
+    for item in (
+        _select_field_item(schema, "job_basic_info", "jbi", ("岗位类别", "岗位类型", "职能类别"), "岗位类型", ("job_type",)),
+        _select_field_item(schema, "job_store", "js", ("招聘人数",), "招聘人数", ("requirement_num",)),
+        _select_field_item(schema, "job_basic_info", "jbi", ("状态", "岗位状态"), "岗位状态", ("status",)),
+    ):
+        if item is not None:
+            items.append(item)
+    time_range = _extract_time_range(question, schema)
+    if time_range is not None:
+        items.append(f"jbi.{time_range.field} AS {time_range.alias}")
+    if "门店" in question:
+        for item in (
+            _select_field_item(schema, "store", "s", ("门店名称",), "门店名称", ("name",)),
+            _select_field_item(schema, "store", "s", ("门店地址", "详细地址", "精确地址"), "门店地址", ("address", "exact_address")),
+            _select_field_item(schema, "store", "s", ("门店ID",), "门店ID", ("id",)),
+        ):
+            if item is not None:
+                items.append(item)
+    if "薪资" in question:
+        for item in (
+            _select_field_item(schema, "job_salary", "jsa", ("最低综合薪资", "最低薪资", "薪资范围最低"), "最低薪资", ("min_comprehensive_salary",)),
+            _select_field_item(schema, "job_salary", "jsa", ("最高综合薪资", "最高薪资", "薪资范围最高"), "最高薪资", ("max_comprehensive_salary",)),
+            _select_field_item(schema, "job_salary", "jsa", ("薪资类型", "类型", "薪资结构"), "薪资类型", ("type", "salary_period")),
+        ):
+            if item is not None:
+                items.append(item)
+    if re.search(r"(用人要求|学历|经验|年龄|技能)", question):
+        for item in (
+            _select_field_item(schema, "job_hiring_requirement", "jhr", ("学历", "最低学历"), "学历要求", ("education_id",)),
+            _select_field_item(schema, "job_hiring_requirement", "jhr", ("最少工作时长", "工作经验", "工作年限"), "经验要求", ("min_work_time",)),
+            _select_age_requirement_item(schema),
+            _select_field_item(schema, "job_hiring_requirement", "jhr", ("软性技能", "技能要求"), "技能要求", ("soft_skill",)),
+        ):
+            if item is not None:
+                items.append(item)
+    if re.search(r"(岗位描述|工作内容|技能要求)", question):
+        item = _select_field_item(schema, "job_basic_info", "jbi", ("工作内容", "岗位描述"), "岗位描述", ("job_content",))
+        if item is not None:
+            items.append(item)
+    return list(dict.fromkeys(items))
+
+
+def _select_age_requirement_item(schema: dict[str, Any]) -> str | None:
+    if _has_column(schema, "job_hiring_requirement", "min_age") and _has_column(schema, "job_hiring_requirement", "max_age"):
+        return "CONCAT(jhr.min_age, '-', jhr.max_age) AS 年龄要求"
+    return _select_field_item(schema, "job_hiring_requirement", "jhr", ("年龄",), "年龄要求", ("min_age", "max_age"))
+
+
+def _select_field_item(
+    schema: dict[str, Any],
+    table_name: str,
+    table_alias: str,
+    terms: tuple[str, ...],
+    output_alias: str,
+    fallback_names: tuple[str, ...],
+) -> str | None:
+    column = _select_column(schema, table_name, terms, fallback_names)
+    if column is None:
+        return None
+    return f"{table_alias}.{column} AS {output_alias}"
+
+
+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 _has_recruiting_location_tables(table_names: set[str]) -> bool:
+    required = {"job_basic_info", "job_address", "job_store", "store", "province", "city", "region"}
+    return required <= table_names
+
+
+def _has_recruiting_tables(table_names: set[str]) -> bool:
+    return "job_basic_info" in table_names
+
+
+def _recruiting_from_and_where() -> str:
+    return "FROM job_basic_info jbi WHERE jbi.is_deleted = 0 AND jbi.status = 1"
+
+
+def _recruiting_location_from_and_where(location: str) -> str:
+    return (
+        "FROM job_basic_info jbi "
+        "LEFT JOIN job_address ja ON ja.job_id = jbi.job_id AND ja.delete_at IS NULL "
+        "LEFT JOIN job_store js ON js.job_basic_info_id = jbi.id AND js.is_deleted = 0 "
+        "LEFT JOIN store s ON s.id = js.store_id AND s.delete_at IS NULL "
+        f"WHERE jbi.is_deleted = 0 AND jbi.status = 1 AND {_recruiting_location_condition(location)}"
+    )
+
+
+def _recruiting_location_condition(location: str) -> str:
+    return (
+        "("
+        "EXISTS ("
+        "SELECT 1 FROM province p JOIN city c ON c.province_id = p.id "
+        f"WHERE ({_province_name_matches(location)}) "
+        "AND (ja.city_id = c.id OR s.city_id = c.id OR FIND_IN_SET(c.id, jbi.city_ids) > 0)"
+        ") OR EXISTS ("
+        "SELECT 1 FROM city c "
+        f"WHERE ({_city_name_matches(location)}) "
+        "AND (ja.city_id = c.id OR s.city_id = c.id OR FIND_IN_SET(c.id, jbi.city_ids) > 0)"
+        ") OR EXISTS ("
+        "SELECT 1 FROM region r "
+        f"WHERE ({_region_name_matches(location)}) "
+        "AND (ja.region_id = r.id OR s.region_id = r.id)"
+        "))"
+    )
+
+
+def _append_job_time_range_condition(from_and_where: str, question: str, schema: dict[str, Any]) -> str:
+    time_range = _extract_time_range(question, schema)
+    if time_range is None:
+        return from_and_where
+    return (
+        f"{from_and_where} AND jbi.{time_range.field} >= '{time_range.start}' "
+        f"AND jbi.{time_range.field} < '{time_range.end}'"
+    )
+
+
+def _extract_time_range(question: str, schema: dict[str, Any] | None = None) -> TimeRange | None:
+    field = _resolve_job_time_field(question, schema or {})
+    if field is None:
+        return None
+    bounds = _extract_time_bounds(question)
+    if bounds is None:
+        return None
+    return TimeRange(field=field.name, alias=field.alias, start=bounds[0], end=bounds[1])
+
+
+def _job_basic_select_items(question: str, schema: dict[str, Any]) -> str:
+    items = [
+        "jbi.id AS 岗位ID",
+        "jbi.job_name AS 岗位名称",
+        "jbi.job_content AS 工作内容",
+    ]
+    time_range = _extract_time_range(question, schema)
+    if time_range is not None:
+        items.append(f"jbi.{time_range.field} AS {time_range.alias}")
+    else:
+        items.append("jbi.publish_at AS 发布时间")
+    items.append("jbi.status AS 状态")
+    return ", ".join(items)
+
+
+def _job_order_by(question: str, schema: dict[str, Any]) -> str:
+    time_range = _extract_time_range(question, schema)
+    if time_range is not None:
+        direction = "ASC" if re.search(r"(正序|升序|从早到晚)", question) else "DESC"
+        return f"ORDER BY jbi.{time_range.field} {direction}"
+    return "ORDER BY jbi.publish_at DESC"
+
+
+def _resolve_job_time_field(question: str, schema: dict[str, Any]) -> FieldRef | None:
+    columns = _table_columns(schema, "job_basic_info")
+    question_text = _normalize_semantic_text(question)
+    best: tuple[int, FieldRef] | None = None
+    for column in columns:
+        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
+        field_ref = FieldRef(name=name, alias=_column_alias(name, comment))
+        if best is None or score > best[0]:
+            best = (score, field_ref)
+    if best is not None:
+        return best[1]
+    if _extract_time_bounds(question) is not None and re.search(r"(在招岗位数|岗位供给|招聘人数|招聘门店数|供给)", question):
+        created_column = _select_column(schema, "job_basic_info", ("创建时间",), ("create_at",))
+        if created_column is not None:
+            return FieldRef(created_column, _column_alias(created_column, "创建时间"))
+    fallback = _select_time_field(question)
+    if fallback is None:
+        return None
+    return fallback
+
+
+def _select_time_field(question: str) -> FieldRef | None:
+    if re.search(r"(发布|上架)", question):
+        return FieldRef("publish_at", "发布时间")
+    if re.search(r"(下架)", question):
+        return FieldRef("off_at", "下架时间")
+    if re.search(r"(更新|修改)", question):
+        return FieldRef("update_at", "更新时间")
+    if re.search(r"(创建|新建|新增)", question):
+        return FieldRef("create_at", "创建时间")
+    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
+    for term in ("创建", "发布", "下架", "更新"):
+        if term in question_text and term in field_text:
+            score += 100
+    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
+    return score
+
+
+def _normalize_semantic_text(text: str) -> str:
+    normalized = text.lower()
+    replacements = {
+        "新建": "创建",
+        "新增": "创建",
+        "录入": "创建",
+        "生成": "创建",
+        "上架": "发布",
+        "上线": "发布",
+        "修改": "更新",
+        "下线": "下架",
+    }
+    for source, target in replacements.items():
+        normalized = normalized.replace(source, target)
+    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
+    fallback_aliases = {
+        "create_at": "创建时间",
+        "publish_at": "发布时间",
+        "off_at": "下架时间",
+        "update_at": "更新时间",
+    }
+    return fallback_aliases.get(name, name)
+
+
+def _extract_time_bounds(question: str) -> tuple[str, str] | None:
+    date_range = _extract_explicit_date_range(question)
+    if date_range is not None:
+        return date_range
+    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)
+    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 _extract_year_bounds(question: str) -> tuple[str, str] | None:
+    relative_year_match = re.search(r"(?P<relative_year>今年|去年|前年|明年|后年)(?:全年|年内|全年内)?", question)
+    if relative_year_match is not None:
+        year = _today().year + _relative_year_offset(relative_year_match.group("relative_year"))
+        return _year_bounds(year)
+    if re.search(r"(全年|年内|全年内)", question):
+        return _year_bounds(_today().year)
+    year_match = re.search(r"(?P<year>20\d{2})\s*年(?:全年|年内|全年内)?", question)
+    if year_match is None:
+        return None
+    return _year_bounds(int(year_match.group("year")))
+
+
+def _year_bounds(year: int) -> tuple[str, str]:
+    return _format_datetime(date(year, 1, 1)), _format_datetime(date(year + 1, 1, 1))
+
+
+def _relative_year_offset(relative_year: str) -> int:
+    offsets = {
+        "今年": 0,
+        "去年": -1,
+        "前年": -2,
+        "明年": 1,
+        "后年": 2,
+    }
+    return offsets[relative_year]
+
+
+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 _extract_location_for_recruiting_job_question(question: str) -> str | None:
+    if not _is_recruiting_job_question(question):
+        return None
+    text = re.sub(r"(查询|查看|看看|列出|给我|帮我查|当前|目前|现在)", "", question)
+    text = re.sub(r"(所有|全部|每个|各个)", "", text)
+    patterns = [
+        r"(?P<location>[\u4e00-\u9fff]{2,12}?)(?:有)?(?:多少|几|数量|总数).*?(?:在招|招聘)(?:岗位|职位)",
+        r"(?P<location>[\u4e00-\u9fff]{2,12}?)(?:的)?(?:在招|招聘)(?:岗位|职位)",
+        r"(?P<location>[\u4e00-\u9fff]{2,12}?)(?:有|有哪些|有什么).*?(?:在招|招聘)(?:岗位|职位)",
+        r"(?:在|位于)(?P<location>[\u4e00-\u9fff]{2,12}?)(?:的)?(?:岗位|职位)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match is not None:
+            return _clean_location_candidate(match.group("location"), require_location_signal=True)
+    return None
+
+
+def _is_recruiting_job_question(question: str) -> bool:
+    return bool(re.search(r"(岗位|职位|招聘|在招)", question))
+
+
+def _is_recruiting_remaining_signup_query(question: str) -> bool:
+    return bool("岗位" in question and "报名" in question and re.search(r"(剩余|还剩|余量|可报名)", question))
+
+
+def _is_work_order_detail_query(question: str) -> bool:
+    return bool(
+        "品牌" in question
+        and re.search(r"(报名|工单)", question)
+        and re.search(r"(候选人状态|候选人|面试成功)", question)
+        and re.search(r"(姓名|名字|岗位|职位|项目)", question)
+    )
+
+
+def _extract_brand_filter(question: str) -> tuple[str, str] | None:
+    contains_patterns = [
+        r"品牌(?:名称)?(?:包含|含有|模糊匹配|like)(?P<brand>.+?)(?:，|,|。|；|;|的品牌|品牌信息|包括|返回|$)",
+        r"(?:name|名称)\s+LIKE\s+[\"'“”‘’%]*(?P<brand>[\u4e00-\u9fffA-Za-z0-9（）()·_\-]{1,40})",
+    ]
+    for pattern in contains_patterns:
+        match = re.search(pattern, question, flags=re.IGNORECASE)
+        if match is None:
+            continue
+        brand = _clean_brand_candidate(match.group("brand"))
+        if brand is not None:
+            return "contains", brand
+
+    exact_patterns = [
+        r"品牌(?:名称)?(?:为|是|=|等于)(?P<brand>.+?)(?:，|,|。|；|;|候选人|工单|报名|提供|输出|通过|包括|返回|$)",
+        r"(?P<brand>[\u4e00-\u9fffA-Za-z0-9（）()·_\-]{2,40})品牌(?:下|的)?",
+    ]
+    for pattern in exact_patterns:
+        match = re.search(pattern, question)
+        if match is None:
+            continue
+        brand = _clean_brand_candidate(match.group("brand"))
+        if brand is not None:
+            return "exact", brand
+    return None
+
+
+def _extract_brand_name(question: str) -> str | None:
+    brand_filter = _extract_brand_filter(question)
+    return brand_filter[1] if brand_filter is not None else None
+
+
+def _clean_brand_candidate(value: str) -> str | None:
+    brand = re.sub(r"\s+", "", value)
+    brand = brand.strip("\"'“”‘’%")
+    brand = re.sub(r"^(名称为|名称是|为|是|=|等于)", "", brand)
+    brand = re.sub(r"(的品牌信息|品牌信息|的品牌|品牌|的|下)$", "", brand)
+    brand = brand.strip("\"'“”‘’%")
+    if 2 <= len(brand) <= 40 and re.search(r"(查询|查看|给我|帮我|根据|roll-core|岗位|候选人|报名|入职|在招|招聘|数量|多少)", brand) is None:
+        return brand
+    return None
+
+
+def _sql_references_brand_table(sql: str) -> bool:
+    return "brand" in _sql_table_aliases(sql.lower()).values()
+
+
+def _sql_contains_brand_name_filter(sql: str, brand_name: str) -> bool:
+    normalized = sql.lower()
+    escaped = re.escape(_escape_sql_string(brand_name).lower())
+    return bool(
+        re.search(rf"\b[a-zA-Z_][a-zA-Z0-9_]*\.name\s*(?:=|like)\s*['\"]%?{escaped}%?['\"]", normalized)
+        or re.search(rf"\bname\s*(?:=|like)\s*['\"]%?{escaped}%?['\"]", normalized)
+    )
+
+
+def _is_monthly_recruiting_conversion_query(question: str) -> bool:
+    return bool(
+        re.search(r"(全年|年内|每月|月度)", question)
+        and re.search(r"(报名人数|报名数)", question)
+        and re.search(r"(入职人数|入职数|上岗人数|上岗数)", question)
+        and re.search(r"(转化率|转化)", question)
+        and "品牌" in question
+        and "项目" in question
+    )
+
+
+def is_recruiting_match_effect_query(question: str) -> bool:
+    return bool(
+        "岗位" in question
+        and re.search(r"(候选人|报名|入职|上岗)", question)
+        and re.search(r"(匹配效果|报名多|入职少|在招多|报名少|候选人多|岗位少)", question)
+        and re.search(r"(品牌|项目|城市)", question)
+    )
+
+
+def _is_recruiting_supply_multi_metric_query(question: str) -> bool:
+    return bool(
+        _is_multi_metric_query(question)
+        and re.search(r"(在招岗位数|岗位供给|招聘人数|招聘门店数)", question)
+        and re.search(r"(品牌|项目|城市|区域)", question)
+    )
+
+
+def _is_multi_metric_query(question: str) -> bool:
+    metric_terms = (
+        "岗位供给数量",
+        "候选人供给数量",
+        "报名人数",
+        "入职人数",
+        "报名转化率",
+        "入职转化率",
+        "在招岗位数",
+        "招聘人数",
+        "招聘门店数",
+    )
+    dimension_terms = ("品牌", "项目", "城市", "区域")
+    metric_count = sum(1 for term in metric_terms if term in question)
+    dimension_count = sum(1 for term in dimension_terms if term in question)
+    has_list_separator = bool(re.search(r"[、,，]", question))
+    return (metric_count >= 2) or (metric_count >= 1 and dimension_count >= 2 and has_list_separator)
+
+
+def _requires_recruiting_detail_joins(question: str) -> bool:
+    if re.search(r"(明细|详情|包含|需要|显示|带上|返回)", question) is None:
+        return False
+    return bool(
+        re.search(
+            r"(门店|薪资|学历|经验|年龄|技能|用人要求|招聘人数|岗位类型|职能类别|工作年限|薪资范围|薪资类型|岗位描述)",
+            question,
+        )
+    )
+
+
+def _question_requests_count(question: str) -> bool:
+    if re.search(r"(每个|各个|分别|列表|明细|详情|有哪些|有什么|剩余|还剩|所有.*(?:岗位|职位)|全部.*(?:岗位|职位))", question):
+        return False
+    return bool(re.search(r"(多少|几|数量|总数|count|统计)", question, flags=re.IGNORECASE))
+
+
+def _clean_location_candidate(candidate: str, *, require_location_signal: bool = False) -> str | None:
+    cleaned = re.sub(r"[，,。；;？?\s]", "", candidate)
+    cleaned = re.sub(r"(有哪些|有什么|所有|全部|每个|各个|多少|数量|列表|明细|信息|数据|情况|都|的|有)$", "", cleaned)
+    if not 2 <= len(cleaned) <= 12:
+        return None
+    if re.search(r"[\u4e00-\u9fff]", cleaned) is None:
+        return None
+    if re.search(r"(岗位|职位|招聘|在招|品牌|项目|查询|查看|当前|目前|现在)", cleaned):
+        return None
+    if _is_generic_recruiting_term(cleaned):
+        return None
+    if require_location_signal and not _has_location_signal(cleaned):
+        return None
+    return cleaned
+
+
+def _has_location_signal(candidate: str) -> bool:
+    if re.search(r"(省|市|区|县|镇|乡|街道|路|街|大道|广场|商圈|附近|地铁|站|商场|门店)$", candidate):
+        return True
+    return 2 <= len(candidate) <= 4 and not _is_generic_recruiting_term(candidate)
+
+
+def _is_generic_recruiting_term(candidate: str) -> bool:
+    generic_terms = {
+        "兼职",
+        "全职",
+        "小时工",
+        "暑假工",
+        "寒假工",
+        "长期工",
+        "短期工",
+        "服务员",
+        "店员",
+        "骑手",
+        "厨师",
+        "收银员",
+        "营业员",
+        "理货员",
+        "分拣",
+        "补货",
+        "打包",
+        "餐厅",
+        "门店",
+        "品牌",
+        "项目",
+        "高薪",
+        "急招",
+        "最新",
+        "全部",
+        "所有",
+        "热门",
+        "附近",
+        "本周",
+        "今天",
+        "明天",
+    }
+    return candidate in generic_terms
+
+
+def _escape_sql_string(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("'", "''")
+
+
+def _province_name_matches(location: str) -> str:
+    literal = f"'{location}'"
+    return (
+        f"p.name = {literal} OR "
+        "REPLACE(REPLACE(REPLACE(REPLACE(p.name, '特别行政区', ''), '自治区', ''), '省', ''), '市', '') = "
+        f"REPLACE(REPLACE(REPLACE(REPLACE({literal}, '特别行政区', ''), '自治区', ''), '省', ''), '市', '')"
+    )
+
+
+def _city_name_matches(location: str) -> str:
+    literal = f"'{location}'"
+    return (
+        f"c.name = {literal} OR "
+        "REPLACE(REPLACE(REPLACE(c.name, '自治州', ''), '地区', ''), '市', '') = "
+        f"REPLACE(REPLACE(REPLACE({literal}, '自治州', ''), '地区', ''), '市', '')"
+    )
+
+
+def _region_name_matches(location: str) -> str:
+    literal = f"'{location}'"
+    return (
+        f"r.name = {literal} OR "
+        "REPLACE(REPLACE(REPLACE(r.name, '自治县', ''), '区', ''), '县', '') = "
+        f"REPLACE(REPLACE(REPLACE({literal}, '自治县', ''), '区', ''), '县', '')"
+    )
+
+
+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(
+            r"\s+as\s+(`[^`]+`|\"[^\"]+\"|'[^']+'|[\u4e00-\u9fff][\w\u4e00-\u9fff]*)\s*$",
+            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(
+        r"\s+as\s+(`[^`]+`|\"[^\"]+\"|'[^']+'|[\u4e00-\u9fff][\w\u4e00-\u9fff]*)\s*$",
+        "",
+        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