feat: 初始化高校人事请假考勤技能 (process-leave-attendance-default)

基于 skill-template 脚手架开发，包含：
- 5 张业务表（教职工、请假政策、考勤日历、请假记录、假期余额）
- 请假核算引擎（扣薪计算、审批层级判定、年假抵扣）
- CLI 入口（import-employees / calculate-leave / render-html）
- HTML 审批与扣薪报告生成
- 示例数据与完整测试套件（295 tests passed）

scripts/db/connection.py

@@ -0,0 +1,54 @@
+"""SQLite 连接与请假考勤业务表幂等初始化。"""
+
+from __future__ import annotations
+
+import sqlite3
+
+from db.display_metadata import init_display_metadata
+from db.leave_display_metadata import seed_leave_display_metadata
+from db.schema import BUSINESS_TABLES, TABLE_DDL
+from db.timestamp_columns import init_updated_at_trigger
+from util.runtime_paths import get_db_path
+
+
+def get_conn() -> sqlite3.Connection:
+    return sqlite3.connect(get_db_path())
+
+
+def init_db() -> None:
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        for table_name, ddl in TABLE_DDL:
+            cur.execute(ddl)
+            init_updated_at_trigger(cur, table_name)
+        cur.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_leave_requests_employee
+            ON leave_requests(employee_id, status)
+            """
+        )
+        cur.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_leave_balances_employee
+            ON leave_balances(employee_id, balance_type)
+            """
+        )
+        cur.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_leave_policies_type
+            ON leave_policies(leave_type)
+            """
+        )
+        cur.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_attendance_holidays_date
+            ON attendance_holidays(holiday_date)
+            """
+        )
+        init_display_metadata(cur)
+        seed_leave_display_metadata(cur)
+        _ = BUSINESS_TABLES
+        conn.commit()
+    finally:
+        conn.close()

scripts/db/display_metadata.py

@@ -0,0 +1,324 @@
+"""匠厂数据管理展示元数据（_jiangchang_tables / _jiangchang_columns）。
+
+SQLite 无原生表/字段 COMMENT；中文展示名称通过这两张元数据表提供给宿主「数据管理」页面。
+字段在界面上的顺序由 CREATE TABLE / PRAGMA table_info(cid) 决定，**不**使用 display_order 排序。
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+# 宿主会隐藏这些表，不作为业务表展示（见 jiangchang electron/data-management/types.ts）
+INTERNAL_METADATA_TABLES = frozenset({"_jiangchang_tables", "_jiangchang_columns"})
+LEGACY_METADATA_TABLES = frozenset({"_schema_meta"})
+METADATA_TABLES = INTERNAL_METADATA_TABLES | LEGACY_METADATA_TABLES
+
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+
+_JIANGCHANG_TABLES_DDL = """
+CREATE TABLE IF NOT EXISTS _jiangchang_tables (
+    table_name TEXT PRIMARY KEY,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    grid_help TEXT,
+    sort_order INTEGER,
+    visible INTEGER NOT NULL DEFAULT 1,
+    readonly INTEGER NOT NULL DEFAULT 0,
+    default_sort_json TEXT,
+    default_visible_columns_json TEXT
+)
+"""
+
+_JIANGCHANG_COLUMNS_DDL = """
+CREATE TABLE IF NOT EXISTS _jiangchang_columns (
+    table_name TEXT NOT NULL,
+    column_name TEXT NOT NULL,
+    display_name TEXT NOT NULL,
+    description TEXT,
+    grid_help TEXT,
+    display_order INTEGER,
+    visible INTEGER NOT NULL DEFAULT 1,
+    searchable INTEGER NOT NULL DEFAULT 1,
+    editable INTEGER NOT NULL DEFAULT 1,
+    display_type TEXT,
+    options_json TEXT,
+    PRIMARY KEY (table_name, column_name)
+)
+"""
+
+def _pragma_column_names(cursor, table_name: str) -> set[str]:
+    cursor.execute(f"PRAGMA table_info({table_name!r})")
+    return {str(row[1]) for row in cursor.fetchall()}
+
+
+def _ensure_jiangchang_tables_columns(cursor) -> None:
+    """旧库补列：CREATE IF NOT EXISTS 不会给已有表加新字段。"""
+    cols = _pragma_column_names(cursor, "_jiangchang_tables")
+    if "default_sort_json" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN default_sort_json TEXT")
+    if "default_visible_columns_json" not in cols:
+        cursor.execute(
+            "ALTER TABLE _jiangchang_tables ADD COLUMN default_visible_columns_json TEXT"
+        )
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_tables ADD COLUMN grid_help TEXT")
+
+
+def _ensure_jiangchang_columns_columns(cursor) -> None:
+    cols = _pragma_column_names(cursor, "_jiangchang_columns")
+    if "grid_help" not in cols:
+        cursor.execute("ALTER TABLE _jiangchang_columns ADD COLUMN grid_help TEXT")
+
+
+def init_display_metadata_tables(cursor) -> None:
+    cursor.execute(_JIANGCHANG_TABLES_DDL)
+    cursor.execute(_JIANGCHANG_COLUMNS_DDL)
+    _ensure_jiangchang_tables_columns(cursor)
+    _ensure_jiangchang_columns_columns(cursor)
+
+
+def upsert_table_metadata(
+    cursor,
+    *,
+    table_name: str,
+    display_name: str,
+    description: str | None = None,
+    grid_help: str | None = None,
+    visible: int = 1,
+    readonly: int = 0,
+    default_sort_json: str | None = None,
+    default_visible_columns_json: str | None = None,
+) -> None:
+    """写入表级元数据。
+
+    default_sort_json: 宿主数据管理默认排序，JSON 数组，例如
+    '[{"column":"sent_at","direction":"desc"},{"column":"id","direction":"desc"}]'
+    为空则宿主回退到 updated_at → created_at → 主键。
+
+    default_visible_columns_json: 宿主数据管理默认展示列，JSON 字符串数组，例如
+    '["stat_type","period","stage"]'
+    为空则全显；用户改过「列」后以本机偏好为准（软默认，区别于 visible=0 硬隐藏）。
+
+    grid_help: 数据管理表格上方说明；空则不出横幅。与表单用的 description 独立，禁止互拷。
+    """
+    cursor.execute(
+        """
+        INSERT INTO _jiangchang_tables (
+            table_name, display_name, description, grid_help, visible, readonly,
+            default_sort_json, default_visible_columns_json
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(table_name) DO UPDATE SET
+            display_name = excluded.display_name,
+            description = excluded.description,
+            grid_help = excluded.grid_help,
+            visible = excluded.visible,
+            readonly = excluded.readonly,
+            default_sort_json = excluded.default_sort_json,
+            default_visible_columns_json = excluded.default_visible_columns_json
+        """,
+        (
+            table_name,
+            display_name,
+            description,
+            grid_help,
+            visible,
+            readonly,
+            default_sort_json,
+            default_visible_columns_json,
+        ),
+    )
+
+
+def upsert_column_metadata(
+    cursor,
+    *,
+    table_name: str,
+    column_name: str,
+    display_name: str,
+    description: str | None = None,
+    grid_help: str | None = None,
+    visible: int = 1,
+    searchable: int = 1,
+    editable: int = 1,
+    display_type: str | None = None,
+    options_json: str | None = None,
+) -> None:
+    # display_order 保留为 NULL：宿主按 PRAGMA table_info cid 展示字段，不读 display_order。
+    # grid_help: 表头「?」；空则不出。与表单用的 description 独立，禁止互拷。
+    cursor.execute(
+        """
+        INSERT INTO _jiangchang_columns (
+            table_name, column_name, display_name, description, grid_help,
+            display_order, visible, searchable, editable, display_type, options_json
+        )
+        VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?)
+        ON CONFLICT(table_name, column_name) DO UPDATE SET
+            display_name = excluded.display_name,
+            description = excluded.description,
+            grid_help = excluded.grid_help,
+            display_order = NULL,
+            visible = excluded.visible,
+            searchable = excluded.searchable,
+            editable = excluded.editable,
+            display_type = excluded.display_type,
+            options_json = excluded.options_json
+        """,
+        (
+            table_name,
+            column_name,
+            display_name,
+            description,
+            grid_help,
+            visible,
+            searchable,
+            editable,
+            display_type,
+            options_json,
+        ),
+    )
+
+
+def seed_column_metadata_batch(
+    cursor,
+    *,
+    table_name: str,
+    columns: Iterable[dict[str, object]],
+    valid_column_names: Iterable[str] | None = None,
+) -> None:
+    """批量 upsert 字段元数据；传入 valid_column_names 时会在 upsert 后清理陈旧字段元数据。"""
+    for column in columns:
+        upsert_column_metadata(
+            cursor,
+            table_name=table_name,
+            column_name=str(column["column_name"]),
+            display_name=str(column["display_name"]),
+            description=str(column["description"]) if column.get("description") else None,
+            grid_help=str(column["grid_help"]) if column.get("grid_help") else None,
+            visible=int(column.get("visible", 1)),
+            searchable=int(column.get("searchable", 1)),
+            editable=int(column.get("editable", 1)),
+            display_type=str(column["display_type"]) if column.get("display_type") else None,
+            options_json=str(column["options_json"]) if column.get("options_json") else None,
+        )
+    if valid_column_names is not None:
+        prune_stale_column_metadata(cursor, table_name, valid_column_names)
+
+
+def prune_stale_column_metadata(cursor, table_name: str, valid_column_names: Iterable[str]) -> None:
+    """删除表中已不存在物理字段的元数据行（幂等初始化后不得残留旧字段）。"""
+    valid = set(valid_column_names)
+    cursor.execute(
+        "SELECT column_name FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    for (column_name,) in cursor.fetchall():
+        if str(column_name) not in valid:
+            cursor.execute(
+                "DELETE FROM _jiangchang_columns WHERE table_name = ? AND column_name = ?",
+                (table_name, column_name),
+            )
+
+
+def get_table_readonly(cursor, table_name: str) -> int | None:
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def get_column_editable(cursor, table_name: str, column_name: str) -> int | None:
+    cursor.execute(
+        """
+        SELECT editable FROM _jiangchang_columns
+        WHERE table_name = ? AND column_name = ?
+        """,
+        (table_name, column_name),
+    )
+    row = cursor.fetchone()
+    if not row:
+        return None
+    return int(row[0] or 0)
+
+
+def list_editable_business_columns(cursor, table_name: str) -> list[str]:
+    """返回 editable=1 的业务字段名（不含宿主侧主键/generated 等二次过滤）。"""
+    physical = list_physical_column_names(cursor, table_name)
+    cursor.execute(
+        """
+        SELECT column_name, editable
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    editable_set = {
+        str(column_name)
+        for column_name, editable in cursor.fetchall()
+        if editable is not None and int(editable) == 1
+    }
+    return [name for name in physical if name in editable_set]
+
+
+def table_allows_manual_create(cursor, table_name: str) -> bool:
+    """表级 readonly=0 且至少有一个 editable=1 字段时，宿主才应提供空白新增表单。"""
+    readonly = get_table_readonly(cursor, table_name)
+    if readonly is None or int(readonly) != 0:
+        return False
+    return bool(list_editable_business_columns(cursor, table_name))
+
+
+def init_display_metadata(cursor) -> None:
+    init_display_metadata_tables(cursor)
+
+
+def drop_deprecated_user_table(
+    cursor,
+    table_name: str,
+    *,
+    triggers: Iterable[str] | None = None,
+) -> None:
+    """永久退役用户可见表：删 trigger、DROP 物理表、清理展示元数据（幂等）。
+
+    用于废弃 task_logs 等旧表。禁止只删元数据而保留物理表。
+    见 references/SCHEMA.md「表增删改与退役」。
+    """
+    for trigger_name in triggers or ():
+        cursor.execute(f"DROP TRIGGER IF EXISTS {trigger_name}")
+    default_updated_at = f"{table_name}_set_updated_at"
+    cursor.execute(f"DROP TRIGGER IF EXISTS {default_updated_at}")
+    cursor.execute(f"DROP TABLE IF EXISTS {_quote_identifier(table_name)}")
+    cursor.execute(
+        "DELETE FROM _jiangchang_columns WHERE table_name = ?",
+        (table_name,),
+    )
+    cursor.execute(
+        "DELETE FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+
+
+def iter_user_tables(cursor) -> Iterable[str]:
+    cursor.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+    )
+    for (name,) in cursor.fetchall():
+        if name in METADATA_TABLES:
+            continue
+        yield str(name)
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def list_physical_column_names(cursor, table_name: str) -> list[str]:
+    cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})")
+    rows = cursor.fetchall()
+    rows.sort(key=lambda row: int(row[0]))
+    return [str(row[1]) for row in rows]

scripts/db/display_metadata_validator.py

@@ -0,0 +1,592 @@
+"""数据管理展示元数据校验（模板开发自检，不依赖宿主）。"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+from dataclasses import dataclass, field
+
+from db.display_metadata import (
+    DATETIME_UNIX_SECONDS,
+    METADATA_TABLES,
+    STANDARD_TIMESTAMP_COLUMNS,
+    iter_user_tables,
+    list_editable_business_columns,
+    list_physical_column_names,
+    table_allows_manual_create,
+)
+from db.timestamp_columns import has_updated_at_trigger
+from util.constants import SKILL_SLUG
+from util.slug_naming import LEGACY_EXEMPT_SLUGS, validate_slug_semantics
+
+_TEMPLATE_PLACEHOLDER_SLUGS = frozenset({"process-leave-attendance-default", "process_leave_attendance_default"})
+_ENGLISH_PLACEHOLDER_NAME_PATTERNS = (
+    re.compile(r"^my\s+skill$", re.I),
+    re.compile(r"^your[-_\s]?skill", re.I),
+    re.compile(r"^skill[-_\s]?template$", re.I),
+    re.compile(r"^[a-z0-9_-]+$"),
+)
+_KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+_FK_DDL_PATTERN = re.compile(r"\bFOREIGN\s+KEY\b|\bREFERENCES\b", re.I)
+
+
+@dataclass
+class ValidationReport:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+
+def _has_cjk(text: str) -> bool:
+    return bool(_CJK_RE.search(text))
+
+
+def _looks_like_raw_physical_name(display_name: str, physical_name: str) -> bool:
+    if not display_name.strip():
+        return True
+    if display_name.strip().lower() == physical_name.strip().lower():
+        return True
+    compact = display_name.replace(" ", "").replace("_", "").lower()
+    if compact == physical_name.replace("_", "").lower():
+        return True
+    return False
+
+
+def _parse_frontmatter_field(text: str, field_name: str) -> str:
+    parts = text.split("---", 2)
+    if len(parts) < 2:
+        return ""
+    for line in parts[1].splitlines():
+        match = re.match(rf"^{re.escape(field_name)}:\s*(.+)\s*$", line.strip())
+        if match:
+            return match.group(1).strip().strip("\"'")
+    return ""
+
+
+def _parse_openclaw_slug(text: str) -> str:
+    parts = text.split("---", 2)
+    if len(parts) < 2:
+        return ""
+    lines = parts[1].splitlines()
+    for index, line in enumerate(lines):
+        if re.match(r"^\s+openclaw:\s*$", line):
+            for inner in lines[index + 1 :]:
+                if inner.strip() and inner[0] not in (" ", "\t"):
+                    break
+                match = re.match(r"^(\s+)slug:\s*(.+)\s*$", inner)
+                if match:
+                    return match.group(2).strip().strip("\"'")
+    return ""
+
+
+def parse_skill_frontmatter(skill_root: str) -> dict[str, str]:
+    path = os.path.join(skill_root, "SKILL.md")
+    with open(path, encoding="utf-8") as f:
+        text = f.read()
+    return {
+        "name": _parse_frontmatter_field(text, "name"),
+        "slug": _parse_openclaw_slug(text),
+    }
+
+
+def validate_skill_frontmatter(skill_root: str, *, allow_template_placeholders: bool = True) -> ValidationReport:
+    report = ValidationReport()
+    data = parse_skill_frontmatter(skill_root)
+    name = str(data.get("name") or "").strip()
+    slug = str(data.get("slug") or "").strip()
+
+    if not name:
+        report.errors.append("SKILL.md frontmatter.name 缺失")
+    elif not _has_cjk(name):
+        if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS:
+            report.warnings.append("SKILL.md frontmatter.name 建议使用清晰的中文业务名称（模板占位可暂保留）")
+        else:
+            report.errors.append("SKILL.md frontmatter.name 应使用用户可见的中文业务名称")
+    else:
+        for pattern in _ENGLISH_PLACEHOLDER_NAME_PATTERNS:
+            if pattern.fullmatch(name):
+                if allow_template_placeholders and slug in _TEMPLATE_PLACEHOLDER_SLUGS:
+                    report.warnings.append(f"SKILL.md frontmatter.name 仍为占位风格：{name!r}")
+                else:
+                    report.errors.append(f"SKILL.md frontmatter.name 不应为英文占位名：{name!r}")
+                break
+
+    if not slug:
+        report.errors.append("SKILL.md metadata.openclaw.slug 缺失")
+    elif not _KEBAB_SLUG.fullmatch(slug):
+        report.errors.append(f"metadata.openclaw.slug 必须为 kebab-case：{slug!r}")
+    elif slug in _TEMPLATE_PLACEHOLDER_SLUGS and not allow_template_placeholders:
+        report.errors.append(f"metadata.openclaw.slug 仍为模板占位：{slug!r}")
+
+    constants_slug = SKILL_SLUG.strip()
+    if slug and constants_slug and slug != constants_slug:
+        report.warnings.append(
+            f"SKILL.md slug ({slug!r}) 与 util.constants.SKILL_SLUG ({constants_slug!r}) 不一致"
+        )
+
+    if slug and slug not in LEGACY_EXEMPT_SLUGS and _KEBAB_SLUG.fullmatch(slug):
+        naming_errors, naming_warnings = validate_slug_semantics(
+            slug,
+            strict=not allow_template_placeholders,
+        )
+        report.errors.extend(naming_errors)
+        report.warnings.extend(naming_warnings)
+
+    return report
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def _table_column_info(cursor, table_name: str) -> dict[str, dict[str, object]]:
+    cursor.execute(f"PRAGMA table_info({_quote_identifier(table_name)})")
+    info: dict[str, dict[str, object]] = {}
+    for row in cursor.fetchall():
+        info[str(row[1])] = {
+            "cid": int(row[0]),
+            "name": str(row[1]),
+            "type": str(row[2] or ""),
+            "notnull": int(row[3] or 0),
+            "dflt_value": row[4],
+            "pk": int(row[5] or 0),
+        }
+    return info
+
+
+def _table_column_xinfo(cursor, table_name: str) -> dict[str, dict[str, object]]:
+    """PRAGMA table_xinfo 可识别 generated/hidden 字段（SQLite 3.31+）。"""
+    cursor.execute(f"PRAGMA table_xinfo({_quote_identifier(table_name)})")
+    info: dict[str, dict[str, object]] = {}
+    for row in cursor.fetchall():
+        hidden = int(row[6] or 0) if len(row) > 6 else 0
+        info[str(row[1])] = {
+            "cid": int(row[0]),
+            "name": str(row[1]),
+            "type": str(row[2] or ""),
+            "notnull": int(row[3] or 0),
+            "dflt_value": row[4],
+            "pk": int(row[5] or 0),
+            "hidden": hidden,
+        }
+    return info
+
+
+def _is_generated_column(xinfo: dict[str, object]) -> bool:
+    hidden = int(xinfo.get("hidden") or 0)
+    return hidden in (2, 3)
+
+
+def _is_blob_column(column_info: dict[str, object]) -> bool:
+    return "BLOB" in str(column_info.get("type") or "").upper()
+
+
+def _default_uses_unixepoch(default_value: object) -> bool:
+    if default_value is None:
+        return False
+    text = str(default_value).strip().lower()
+    return "unixepoch" in text
+
+
+def validate_options_json(options_json: str | None) -> tuple[list[str], list[str]]:
+    """校验 options_json：静态枚举数组，或 lookup 对象。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if options_json is None or str(options_json).strip() == "":
+        return errors, warnings
+    try:
+        parsed = json.loads(str(options_json))
+    except json.JSONDecodeError as exc:
+        errors.append(f"options_json 不是合法 JSON：{exc}")
+        return errors, warnings
+
+    if isinstance(parsed, dict):
+        for key in ("ref_table", "value_column", "label_column"):
+            if not str(parsed.get(key) or "").strip():
+                errors.append(f"options_json lookup 必须包含非空 {key}")
+        ident = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+        for key in ("ref_table", "value_column", "label_column", "filter_column"):
+            raw = parsed.get(key)
+            if raw is None or raw == "":
+                continue
+            if not ident.match(str(raw)):
+                errors.append(f"options_json.{key} 必须是安全标识符，当前为 {raw!r}")
+        if parsed.get("filter_column") not in (None, "") and "filter_value" not in parsed:
+            warnings.append("options_json lookup 声明了 filter_column 但未提供 filter_value")
+        if "multiple" in parsed and not isinstance(parsed.get("multiple"), bool):
+            errors.append("options_json lookup.multiple 必须是布尔值")
+        return errors, warnings
+
+    if not isinstance(parsed, list):
+        errors.append("options_json 必须是 JSON 数组（静态枚举）或对象（lookup）")
+        return errors, warnings
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            errors.append(f"options_json[{index}] 必须是对象")
+            continue
+        if "value" not in item or "label" not in item:
+            errors.append(f"options_json[{index}] 必须包含 value 与 label")
+    return errors, warnings
+
+
+def validate_filter_search_metadata(
+    cursor,
+    table_name: str,
+) -> tuple[list[str], list[str]]:
+    """对可见但未开启 searchable 的枚举 / boolean 列给出软建议。"""
+    warnings: list[str] = []
+    cursor.execute(
+        """
+        SELECT column_name, visible, searchable, display_type, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    for column_name, visible, searchable, display_type, options_json in cursor.fetchall():
+        if visible is not None and int(visible) == 0:
+            continue
+        if searchable is not None and int(searchable) != 0:
+            continue
+
+        display_type_norm = str(display_type or "").strip()
+        is_boolean = display_type_norm == "boolean"
+
+        has_enum = False
+        if options_json is not None and str(options_json).strip():
+            opt_errors, _ = validate_options_json(options_json)
+            if not opt_errors:
+                try:
+                    parsed = json.loads(str(options_json))
+                except json.JSONDecodeError:
+                    parsed = None
+                has_enum = isinstance(parsed, list) and len(parsed) > 0
+
+        if not has_enum and not is_boolean:
+            continue
+
+        warnings.append(
+            f"{table_name}.{column_name}: 枚举/状态类列建议 searchable=1，"
+            "以便宿主列筛选与按中文 label 全局搜索（见 references/SCHEMA.md）"
+        )
+
+    return [], warnings
+
+
+def validate_column_permissions(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """校验常见系统字段 editable=0，并识别技术上可写但不适合手工新增的表。"""
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+    column_xinfo = _table_column_xinfo(cursor, table_name)
+
+    cursor.execute(
+        """
+        SELECT column_name, editable, options_json
+        FROM _jiangchang_columns
+        WHERE table_name = ?
+        """,
+        (table_name,),
+    )
+    meta_by_column = {
+        str(row[0]): {"editable": row[1], "options_json": row[2]}
+        for row in cursor.fetchall()
+    }
+
+    for column_name, meta in meta_by_column.items():
+        physical = column_info.get(column_name) or {}
+        xinfo = column_xinfo.get(column_name) or physical
+        if not physical and column_name not in column_xinfo:
+            continue
+
+        pk = int(physical.get("pk") or xinfo.get("pk") or 0)
+        editable = meta["editable"]
+        if pk and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是主键，editable 应为 0")
+
+        if column_name == "id" and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.id 的 editable 应为 0（自增主键）")
+
+        if _is_generated_column(xinfo) and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是 generated 字段，editable 应为 0")
+
+        if _is_blob_column(physical or xinfo) and editable is not None and int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 是 BLOB 字段，editable 应为 0")
+
+        opt_errors, _ = validate_options_json(meta.get("options_json"))
+        for item in opt_errors:
+            errors.append(f"{table_name}.{column_name}: {item}")
+
+    cursor.execute(
+        "SELECT readonly FROM _jiangchang_tables WHERE table_name = ?",
+        (table_name,),
+    )
+    readonly_row = cursor.fetchone()
+    readonly = int(readonly_row[0]) if readonly_row else None
+    editable_columns = list_editable_business_columns(cursor, table_name)
+    if readonly == 0 and not editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=0 但所有字段 editable=0，"
+            "宿主不应打开空白新增表单；数据应由技能业务流程产生"
+        )
+    if readonly == 1 and editable_columns:
+        warnings.append(
+            f"{table_name}: 表级 readonly=1 但存在 editable=1 字段，"
+            "宿主应以表级只读为准"
+        )
+
+    return errors, warnings
+
+
+def _expected_timestamp_display_name(column_name: str) -> str:
+    if column_name == "created_at":
+        return "创建时间"
+    if column_name == "updated_at":
+        return "更新时间"
+    return ""
+
+
+def validate_standard_timestamp_columns(
+    cursor,
+    table_name: str,
+    *,
+    physical_columns: list[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    ordered = physical_columns or list_physical_column_names(cursor, table_name)
+    column_info = _table_column_info(cursor, table_name)
+
+    for column_name in STANDARD_TIMESTAMP_COLUMNS:
+        if column_name not in ordered:
+            continue
+
+        physical = column_info.get(column_name)
+        if not physical:
+            errors.append(f"{table_name}.{column_name} 缺少物理字段定义")
+            continue
+
+        if "INT" not in str(physical["type"]).upper():
+            errors.append(
+                f"{table_name}.{column_name} 字段类型应为 INTEGER（Unix 秒级时间戳），当前为 {physical['type']!r}"
+            )
+
+        if column_name == "created_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.created_at 应设置数据库默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+        if column_name == "updated_at" and not _default_uses_unixepoch(physical["dflt_value"]):
+            errors.append(
+                f"{table_name}.updated_at 应设置数据库初始默认值 DEFAULT (unixepoch())，当前默认值为 {physical['dflt_value']!r}"
+            )
+
+        cursor.execute(
+            """
+            SELECT display_name, display_type, editable, searchable, display_order
+            FROM _jiangchang_columns
+            WHERE table_name = ? AND column_name = ?
+            """,
+            (table_name, column_name),
+        )
+        meta_row = cursor.fetchone()
+        if not meta_row:
+            errors.append(f"{table_name}.{column_name} 缺少 _jiangchang_columns 元数据")
+            continue
+
+        display_name, display_type, editable, searchable, display_order = meta_row
+        expected_name = _expected_timestamp_display_name(column_name)
+        if str(display_name or "").strip() != expected_name:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_name 应为 {expected_name!r}，当前为 {display_name!r}"
+            )
+        if str(display_type or "").strip() != DATETIME_UNIX_SECONDS:
+            errors.append(
+                f"{table_name}.{column_name} 的 display_type 应为 {DATETIME_UNIX_SECONDS!r}，当前为 {display_type!r}"
+            )
+        if editable is None or int(editable) != 0:
+            errors.append(f"{table_name}.{column_name} 的 editable 应为 0（系统时间字段不可编辑）")
+        if display_order is not None:
+            errors.append(f"{table_name}.{column_name} 的 display_order 应为 NULL")
+        if searchable is not None and int(searchable) != 0:
+            warnings.append(f"{table_name}.{column_name} 的时间字段通常不必开启 searchable")
+
+    if "created_at" in ordered and "updated_at" in ordered:
+        if ordered.index("updated_at") < ordered.index("created_at"):
+            warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前")
+
+    if "updated_at" in ordered and not has_updated_at_trigger(cursor, table_name):
+        errors.append(
+            f"{table_name}.updated_at 缺少自动维护 trigger（期望 {table_name}_set_updated_at）"
+        )
+
+    return errors, warnings
+
+
+def column_order_warnings(table_name: str, ordered_names: list[str]) -> list[str]:
+    warnings: list[str] = []
+    if "id" in ordered_names and ordered_names.index("id") != 0:
+        warnings.append(f"{table_name}: 字段 id 通常应定义在 CREATE TABLE 的第一列")
+    if "created_at" in ordered_names:
+        idx = ordered_names.index("created_at")
+        trailing = ordered_names[idx + 1 :]
+        if trailing and trailing != ["updated_at"]:
+            warnings.append(
+                f"{table_name}: created_at 之后通常只应跟 updated_at，不应再放置其他业务字段"
+            )
+    if "updated_at" in ordered_names and "created_at" in ordered_names:
+        if ordered_names.index("updated_at") < ordered_names.index("created_at"):
+            warnings.append(f"{table_name}: updated_at 不应出现在 created_at 之前")
+    return warnings
+
+
+def _table_exists(cursor, table_name: str) -> bool:
+    cursor.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1",
+        (table_name,),
+    )
+    return cursor.fetchone() is not None
+
+
+def validate_no_sqlite_foreign_keys(cursor) -> tuple[list[str], list[str]]:
+    """业务表 DDL 不得含 FOREIGN KEY / REFERENCES（关联走 repository/service）。"""
+    errors: list[str] = []
+    cursor.execute(
+        """
+        SELECT name, sql FROM sqlite_master
+        WHERE type = 'table' AND name NOT LIKE 'sqlite_%'
+        """
+    )
+    for table_name, sql in cursor.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        ddl = str(sql or "")
+        if ddl and _FK_DDL_PATTERN.search(ddl):
+            errors.append(
+                f"业务表 {table_name!r} 的 DDL 含 SQLite FOREIGN KEY/REFERENCES；"
+                "请改为业务 id 列 + repository/service 逻辑关联（见 references/SCHEMA.md）"
+            )
+    return errors, []
+
+
+def validate_display_metadata(conn: sqlite3.Connection, *, check_column_order: bool = True) -> ValidationReport:
+    report = ValidationReport()
+    cur = conn.cursor()
+
+    has_tables_meta = _table_exists(cur, "_jiangchang_tables")
+    has_columns_meta = _table_exists(cur, "_jiangchang_columns")
+    if not has_tables_meta:
+        report.errors.append("缺少数据管理元数据表 _jiangchang_tables")
+    if not has_columns_meta:
+        report.errors.append("缺少数据管理元数据表 _jiangchang_columns")
+    if not has_tables_meta or not has_columns_meta:
+        return report
+
+    fk_errors, _ = validate_no_sqlite_foreign_keys(cur)
+    report.errors.extend(fk_errors)
+
+    for table_name in iter_user_tables(cur):
+        cur.execute(
+            "SELECT display_name FROM _jiangchang_tables WHERE table_name = ?",
+            (table_name,),
+        )
+        row = cur.fetchone()
+        if not row or not str(row[0] or "").strip():
+            report.errors.append(f"业务表 {table_name!r} 缺少 _jiangchang_tables.display_name")
+        elif not _has_cjk(str(row[0])):
+            report.errors.append(f"业务表 {table_name!r} 的 display_name 应使用中文业务名称")
+
+        physical_columns = list_physical_column_names(cur, table_name)
+        if check_column_order:
+            report.warnings.extend(column_order_warnings(table_name, physical_columns))
+
+        for column_name in physical_columns:
+            cur.execute(
+                """
+                SELECT display_name, visible
+                FROM _jiangchang_columns
+                WHERE table_name = ? AND column_name = ?
+                """,
+                (table_name, column_name),
+            )
+            col_row = cur.fetchone()
+            if not col_row:
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 缺少 _jiangchang_columns 元数据"
+                )
+                continue
+            display_name = str(col_row[0] or "").strip()
+            visible = col_row[1] is None or int(col_row[1]) != 0
+            if visible and not display_name:
+                report.errors.append(f"字段 {table_name}.{column_name} 的 display_name 为空")
+            elif visible and _looks_like_raw_physical_name(display_name, column_name):
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 的 display_name 不应直接等于英文物理名：{display_name!r}"
+                )
+            elif visible and not _has_cjk(display_name):
+                report.errors.append(
+                    f"字段 {table_name}.{column_name} 的 display_name 应使用中文：{display_name!r}"
+                )
+
+        ts_errors, ts_warnings = validate_standard_timestamp_columns(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(ts_errors)
+        report.warnings.extend(ts_warnings)
+
+        perm_errors, perm_warnings = validate_column_permissions(
+            cur,
+            table_name,
+            physical_columns=physical_columns,
+        )
+        report.errors.extend(perm_errors)
+        report.warnings.extend(perm_warnings)
+
+        _, filter_warnings = validate_filter_search_metadata(cur, table_name)
+        report.warnings.extend(filter_warnings)
+
+    cur.execute("SELECT table_name, column_name FROM _jiangchang_columns")
+    for table_name, column_name in cur.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        cur.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",
+            (table_name,),
+        )
+        if not cur.fetchone():
+            report.errors.append(f"元数据引用了不存在的表：{table_name!r}")
+            continue
+        physical = list_physical_column_names(cur, str(table_name))
+        if str(column_name) not in physical:
+            report.errors.append(f"元数据引用了不存在的字段：{table_name}.{column_name}")
+
+    cur.execute("SELECT table_name FROM _jiangchang_tables")
+    for (table_name,) in cur.fetchall():
+        if table_name in METADATA_TABLES:
+            continue
+        cur.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name = ?",
+            (table_name,),
+        )
+        if not cur.fetchone():
+            report.errors.append(f"元数据引用了不存在的表：{table_name!r}")
+
+    return report
+
+
+def validate_template_database(conn: sqlite3.Connection) -> ValidationReport:
+    """模板自检入口：校验展示元数据完整性，并扫描业务表 DDL 是否含 SQLite 外键。"""
+    return validate_display_metadata(conn)

scripts/db/leave_display_metadata.py

@@ -0,0 +1,442 @@
+"""高校人事请假考勤：数据管理展示元数据。"""
+
+from __future__ import annotations
+
+import json
+
+from db.display_metadata import (
+    DATETIME_UNIX_SECONDS,
+    list_physical_column_names,
+    seed_column_metadata_batch,
+    upsert_table_metadata,
+)
+from db.schema import (
+    ATTENDANCE_HOLIDAYS_TABLE,
+    EMPLOYEES_TABLE,
+    LEAVE_BALANCES_TABLE,
+    LEAVE_POLICIES_TABLE,
+    LEAVE_REQUESTS_TABLE,
+)
+
+IS_ACTIVE_OPTIONS = (
+    '[{"value":"1","label":"启用"},'
+    '{"value":"0","label":"停用"}]'
+)
+
+STATUS_OPTIONS = (
+    '[{"value":"draft","label":"草稿"},'
+    '{"value":"completed","label":"已完成"},'
+    '{"value":"failed","label":"失败"}]'
+)
+
+DAY_BASIS_OPTIONS = (
+    '[{"value":"workday","label":"工作日"},'
+    '{"value":"natural","label":"自然日"}]'
+)
+
+POSITION_CATEGORY_OPTIONS = (
+    '[{"value":"教师","label":"教师"},'
+    '{"value":"行政","label":"行政"},'
+    '{"value":"科研","label":"科研"}]'
+)
+
+HOLIDAY_TYPE_OPTIONS = (
+    '[{"value":"法定假日","label":"法定假日"},'
+    '{"value":"寒暑假","label":"寒暑假"},'
+    '{"value":"校庆","label":"校庆"},'
+    '{"value":"周末","label":"周末"}]'
+)
+
+APPROVAL_LEVEL_OPTIONS = (
+    '[{"value":"系主任","label":"系主任"},'
+    '{"value":"系主任+人事处","label":"系主任+人事处"},'
+    '{"value":"系主任+人事处+校领导","label":"系主任+人事处+校领导"}]'
+)
+
+BALANCE_TYPE_OPTIONS = (
+    '[{"value":"annual","label":"年假"},'
+    '{"value":"sick","label":"病假"},'
+    '{"value":"marriage","label":"婚假"},'
+    '{"value":"maternity","label":"产假"},'
+    '{"value":"bereavement","label":"丧假"}]'
+)
+
+REQUIRES_CERTIFICATE_OPTIONS = (
+    '[{"value":"1","label":"是"},'
+    '{"value":"0","label":"否"}]'
+)
+
+CAN_OFFSET_OPTIONS = (
+    '[{"value":"1","label":"是"},'
+    '{"value":"0","label":"否"}]'
+)
+
+
+def _ts(column: str, label: str, *, editable: int = 0) -> dict[str, object]:
+    return {
+        "column_name": column,
+        "display_name": label,
+        "visible": 1,
+        "searchable": 0,
+        "editable": editable,
+        "display_type": DATETIME_UNIX_SECONDS,
+    }
+
+
+def _lookup(ref_table: str, value_column: str, label_column: str) -> str:
+    return json.dumps(
+        {
+            "ref_table": ref_table,
+            "value_column": value_column,
+            "label_column": label_column,
+        },
+        ensure_ascii=False,
+    )
+
+
+def _seed_table(cursor, table_name: str, columns: tuple[dict[str, object], ...]) -> None:
+    physical = list_physical_column_names(cursor, table_name)
+    seed_column_metadata_batch(
+        cursor,
+        table_name=table_name,
+        columns=columns,
+        valid_column_names=physical,
+    )
+
+
+def seed_leave_display_metadata(cursor) -> None:
+    upsert_table_metadata(
+        cursor,
+        table_name=EMPLOYEES_TABLE,
+        display_name="教职工",
+        description="教职工基本信息：部门、岗位、入职日期、月薪标准、年假余额",
+        grid_help="可用「导入教职工」从 JSON 批量写入；停用教职工不参与请假核算。",
+        readonly=0,
+    )
+    _seed_table(
+        cursor,
+        EMPLOYEES_TABLE,
+        (
+            {"column_name": "id", "display_name": "编号", "editable": 0, "searchable": 1},
+            {"column_name": "name", "display_name": "姓名", "editable": 1, "searchable": 1},
+            {"column_name": "employee_no", "display_name": "工号", "editable": 1, "searchable": 1},
+            {"column_name": "department", "display_name": "部门", "editable": 1, "searchable": 1},
+            {"column_name": "position", "display_name": "岗位", "editable": 1, "searchable": 1},
+            {
+                "column_name": "position_category",
+                "display_name": "岗位类别",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": POSITION_CATEGORY_OPTIONS,
+            },
+            {"column_name": "join_date", "display_name": "入职日期", "editable": 1, "searchable": 1},
+            {
+                "column_name": "monthly_salary",
+                "display_name": "月薪标准",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "annual_leave_remaining",
+                "display_name": "年假余额",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "is_active",
+                "display_name": "启用",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": IS_ACTIVE_OPTIONS,
+            },
+            {"column_name": "notes", "display_name": "备注", "editable": 1, "searchable": 1},
+            _ts("created_at", "创建时间"),
+            _ts("updated_at", "更新时间"),
+        ),
+    )
+
+    upsert_table_metadata(
+        cursor,
+        table_name=LEAVE_POLICIES_TABLE,
+        display_name="请假政策",
+        description="各类假别的扣薪规则、审批阈值与证件要求",
+        grid_help="按学校政策维护各类假别参数；核算时按 leave_type 匹配。",
+        readonly=0,
+    )
+    _seed_table(
+        cursor,
+        LEAVE_POLICIES_TABLE,
+        (
+            {"column_name": "id", "display_name": "编号", "editable": 0, "searchable": 1},
+            {"column_name": "leave_type", "display_name": "请假类型", "editable": 1, "searchable": 1},
+            {
+                "column_name": "max_days",
+                "display_name": "最大可休天数",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "day_basis",
+                "display_name": "计薪日基准",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": DAY_BASIS_OPTIONS,
+            },
+            {
+                "column_name": "paid_days",
+                "display_name": "带薪天数",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "partial_pay_ratio",
+                "display_name": "部分扣薪比例",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "unpaid_after_days",
+                "display_name": "无薪起始天数",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "requires_certificate",
+                "display_name": "需证件",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": REQUIRES_CERTIFICATE_OPTIONS,
+            },
+            {
+                "column_name": "can_offset_annual",
+                "display_name": "可抵年假",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": CAN_OFFSET_OPTIONS,
+            },
+            {
+                "column_name": "approval_threshold_dept",
+                "display_name": "系主任阈值",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "approval_threshold_hr",
+                "display_name": "人事处阈值",
+                "editable": 1,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {"column_name": "notes", "display_name": "备注", "editable": 1, "searchable": 1},
+            _ts("created_at", "创建时间"),
+            _ts("updated_at", "更新时间"),
+        ),
+    )
+
+    upsert_table_metadata(
+        cursor,
+        table_name=ATTENDANCE_HOLIDAYS_TABLE,
+        display_name="考勤日历",
+        description="法定节假日、寒暑假、校庆等非工作日",
+        grid_help="核算工作日时排除此处登记的日期。",
+        readonly=0,
+    )
+    _seed_table(
+        cursor,
+        ATTENDANCE_HOLIDAYS_TABLE,
+        (
+            {"column_name": "id", "display_name": "编号", "editable": 0, "searchable": 1},
+            {"column_name": "holiday_date", "display_name": "日期", "editable": 1, "searchable": 1},
+            {"column_name": "holiday_name", "display_name": "名称", "editable": 1, "searchable": 1},
+            {
+                "column_name": "holiday_type",
+                "display_name": "类型",
+                "editable": 1,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": HOLIDAY_TYPE_OPTIONS,
+            },
+            _ts("created_at", "创建时间"),
+            _ts("updated_at", "更新时间"),
+        ),
+    )
+
+    upsert_table_metadata(
+        cursor,
+        table_name=LEAVE_REQUESTS_TABLE,
+        display_name="请假记录",
+        description="请假申请与核算结果（系统写入）",
+        grid_help="在教职工表执行「请假核算」后查看扣薪明细与审批层级。",
+        readonly=1,
+    )
+    _seed_table(
+        cursor,
+        LEAVE_REQUESTS_TABLE,
+        (
+            {"column_name": "id", "display_name": "编号", "editable": 0, "searchable": 1},
+            {
+                "column_name": "employee_id",
+                "display_name": "教职工",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "lookup",
+                "options_json": _lookup(EMPLOYEES_TABLE, "id", "name"),
+            },
+            {"column_name": "leave_type", "display_name": "请假类型", "editable": 0, "searchable": 1},
+            {"column_name": "start_date", "display_name": "开始日期", "editable": 0, "searchable": 1},
+            {"column_name": "end_date", "display_name": "结束日期", "editable": 0, "searchable": 1},
+            {
+                "column_name": "has_certificate",
+                "display_name": "附证件",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": REQUIRES_CERTIFICATE_OPTIONS,
+            },
+            {"column_name": "certificate_type", "display_name": "证件类型", "editable": 0, "searchable": 1},
+            {
+                "column_name": "natural_days",
+                "display_name": "自然日数",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "working_days",
+                "display_name": "工作日数",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "monthly_salary",
+                "display_name": "月薪",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "working_days_in_month",
+                "display_name": "当月应出勤",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "daily_salary",
+                "display_name": "日薪",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "deduction_amount",
+                "display_name": "应扣工资",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "annual_leave_used",
+                "display_name": "已抵年假",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "remaining_annual_leave",
+                "display_name": "剩余年假",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "approval_level",
+                "display_name": "审批层级",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": APPROVAL_LEVEL_OPTIONS,
+            },
+            {
+                "column_name": "status",
+                "display_name": "状态",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": STATUS_OPTIONS,
+            },
+            {"column_name": "params_json", "display_name": "参数(JSON)", "editable": 0, "searchable": 0},
+            {"column_name": "summary", "display_name": "摘要", "editable": 0, "searchable": 1},
+            {"column_name": "error_message", "display_name": "错误信息", "editable": 0, "searchable": 1},
+            _ts("created_at", "创建时间"),
+            _ts("updated_at", "更新时间"),
+        ),
+    )
+
+    upsert_table_metadata(
+        cursor,
+        table_name=LEAVE_BALANCES_TABLE,
+        display_name="假期余额",
+        description="教职工各类假期余额（系统更新）",
+        grid_help="核算后自动维护已用天数与剩余天数。",
+        readonly=1,
+    )
+    _seed_table(
+        cursor,
+        LEAVE_BALANCES_TABLE,
+        (
+            {"column_name": "id", "display_name": "编号", "editable": 0, "searchable": 1},
+            {
+                "column_name": "employee_id",
+                "display_name": "教职工",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "lookup",
+                "options_json": _lookup(EMPLOYEES_TABLE, "id", "name"),
+            },
+            {
+                "column_name": "balance_type",
+                "display_name": "假期类型",
+                "editable": 0,
+                "searchable": 1,
+                "display_type": "enum",
+                "options_json": BALANCE_TYPE_OPTIONS,
+            },
+            {
+                "column_name": "total_days",
+                "display_name": "总额度",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "used_days",
+                "display_name": "已用",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            {
+                "column_name": "remaining_days",
+                "display_name": "剩余",
+                "editable": 0,
+                "searchable": 0,
+                "display_type": "number",
+            },
+            _ts("created_at", "创建时间"),
+            _ts("updated_at", "更新时间"),
+        ),
+    )

scripts/db/leave_repository.py

@@ -0,0 +1,567 @@
+"""高校人事请假考勤：业务数据访问。"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from typing import Any, Optional
+
+from db.connection import get_conn, init_db
+from db.schema import (
+    ATTENDANCE_HOLIDAYS_TABLE,
+    EMPLOYEES_TABLE,
+    LEAVE_BALANCES_TABLE,
+    LEAVE_POLICIES_TABLE,
+    LEAVE_REQUESTS_TABLE,
+)
+
+
+def ensure_db() -> None:
+    init_db()
+
+
+def _row_dict(row: sqlite3.Row) -> dict[str, Any]:
+    return {k: row[k] for k in row.keys()}
+
+
+def dumps_json(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False)
+
+
+def loads_json(raw: Any, default: Any = None) -> Any:
+    if raw is None or raw == "":
+        return default if default is not None else {}
+    if isinstance(raw, (dict, list)):
+        return raw
+    try:
+        return json.loads(str(raw))
+    except (TypeError, ValueError, json.JSONDecodeError):
+        return default if default is not None else {}
+
+
+# ---------- employees ----------
+
+def get_employee(employee_id: int) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(f"SELECT * FROM {EMPLOYEES_TABLE} WHERE id = ?", (employee_id,))
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def find_employee_by_name(name: str) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(f"SELECT * FROM {EMPLOYEES_TABLE} WHERE name = ?", (name,))
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def list_active_employees() -> list[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(f"SELECT * FROM {EMPLOYEES_TABLE} WHERE is_active = 1 ORDER BY id")
+        return [_row_dict(r) for r in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+def count_employees() -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(f"SELECT COUNT(*) FROM {EMPLOYEES_TABLE}")
+        return int(cur.fetchone()[0])
+    finally:
+        conn.close()
+
+
+def upsert_employee(payload: dict[str, Any]) -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        name = str(payload.get("name", "")).strip()
+        if not name:
+            raise ValueError("教职工姓名不能为空")
+        employee_no = payload.get("employee_no")
+        existing = None
+        if employee_no:
+            cur.execute(
+                f"SELECT id FROM {EMPLOYEES_TABLE} WHERE employee_no = ?",
+                (employee_no,),
+            )
+            existing = cur.fetchone()
+        if existing is None:
+            cur.execute(
+                f"SELECT id FROM {EMPLOYEES_TABLE} WHERE name = ? AND "
+                "(employee_no IS NULL OR employee_no = '')",
+                (name,),
+            )
+            existing = cur.fetchone()
+        if existing is not None:
+            eid = int(existing[0])
+            cur.execute(
+                f"""UPDATE {EMPLOYEES_TABLE} SET
+                    name = ?, employee_no = ?, department = ?, position = ?,
+                    position_category = ?, join_date = ?, monthly_salary = ?,
+                    annual_leave_remaining = ?, is_active = ?, notes = ?,
+                    updated_at = unixepoch()
+                WHERE id = ?""",
+                (
+                    name,
+                    employee_no,
+                    payload.get("department"),
+                    payload.get("position"),
+                    payload.get("position_category"),
+                    payload.get("join_date"),
+                    float(payload.get("monthly_salary", 0) or 0),
+                    float(payload.get("annual_leave_remaining", 0) or 0),
+                    int(payload.get("is_active", 1)),
+                    payload.get("notes"),
+                    eid,
+                ),
+            )
+            conn.commit()
+            return eid
+        cur.execute(
+            f"""INSERT INTO {EMPLOYEES_TABLE} (
+                name, employee_no, department, position, position_category,
+                join_date, monthly_salary, annual_leave_remaining, is_active, notes
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                name,
+                employee_no,
+                payload.get("department"),
+                payload.get("position"),
+                payload.get("position_category"),
+                payload.get("join_date"),
+                float(payload.get("monthly_salary", 0) or 0),
+                float(payload.get("annual_leave_remaining", 0) or 0),
+                int(payload.get("is_active", 1)),
+                payload.get("notes"),
+            ),
+        )
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+def update_employee_annual_leave(employee_id: int, remaining: float) -> None:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            f"UPDATE {EMPLOYEES_TABLE} SET annual_leave_remaining = ?, "
+            "updated_at = unixepoch() WHERE id = ?",
+            (remaining, employee_id),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+# ---------- leave_policies ----------
+
+def get_policy(leave_type: str) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"SELECT * FROM {LEAVE_POLICIES_TABLE} WHERE leave_type = ?",
+            (leave_type,),
+        )
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def list_policies() -> list[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(f"SELECT * FROM {LEAVE_POLICIES_TABLE} ORDER BY id")
+        return [_row_dict(r) for r in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+def count_policies() -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(f"SELECT COUNT(*) FROM {LEAVE_POLICIES_TABLE}")
+        return int(cur.fetchone()[0])
+    finally:
+        conn.close()
+
+
+def upsert_policy(payload: dict[str, Any]) -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        leave_type = str(payload.get("leave_type", "")).strip()
+        if not leave_type:
+            raise ValueError("请假类型不能为空")
+        cur.execute(
+            f"SELECT id FROM {LEAVE_POLICIES_TABLE} WHERE leave_type = ?",
+            (leave_type,),
+        )
+        existing = cur.fetchone()
+        if existing is not None:
+            pid = int(existing[0])
+            cur.execute(
+                f"""UPDATE {LEAVE_POLICIES_TABLE} SET
+                    leave_type = ?, max_days = ?, day_basis = ?, paid_days = ?,
+                    partial_pay_ratio = ?, unpaid_after_days = ?,
+                    requires_certificate = ?, can_offset_annual = ?,
+                    approval_threshold_dept = ?, approval_threshold_hr = ?,
+                    notes = ?, updated_at = unixepoch()
+                WHERE id = ?""",
+                (
+                    leave_type,
+                    payload.get("max_days"),
+                    payload.get("day_basis", "workday"),
+                    float(payload.get("paid_days", 0) or 0),
+                    float(payload.get("partial_pay_ratio", 1.0) or 1.0),
+                    payload.get("unpaid_after_days"),
+                    int(payload.get("requires_certificate", 0)),
+                    int(payload.get("can_offset_annual", 0)),
+                    int(payload.get("approval_threshold_dept", 3)),
+                    int(payload.get("approval_threshold_hr", 10)),
+                    payload.get("notes"),
+                    pid,
+                ),
+            )
+            conn.commit()
+            return pid
+        cur.execute(
+            f"""INSERT INTO {LEAVE_POLICIES_TABLE} (
+                leave_type, max_days, day_basis, paid_days, partial_pay_ratio,
+                unpaid_after_days, requires_certificate, can_offset_annual,
+                approval_threshold_dept, approval_threshold_hr, notes
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                leave_type,
+                payload.get("max_days"),
+                payload.get("day_basis", "workday"),
+                float(payload.get("paid_days", 0) or 0),
+                float(payload.get("partial_pay_ratio", 1.0) or 1.0),
+                payload.get("unpaid_after_days"),
+                int(payload.get("requires_certificate", 0)),
+                int(payload.get("can_offset_annual", 0)),
+                int(payload.get("approval_threshold_dept", 3)),
+                int(payload.get("approval_threshold_hr", 10)),
+                payload.get("notes"),
+            ),
+        )
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+# ---------- attendance_holidays ----------
+
+def list_holidays() -> list[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"SELECT * FROM {ATTENDANCE_HOLIDAYS_TABLE} ORDER BY holiday_date"
+        )
+        return [_row_dict(r) for r in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+def count_holidays() -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(f"SELECT COUNT(*) FROM {ATTENDANCE_HOLIDAYS_TABLE}")
+        return int(cur.fetchone()[0])
+    finally:
+        conn.close()
+
+
+def upsert_holiday(payload: dict[str, Any]) -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        holiday_date = str(payload.get("holiday_date", "")).strip()
+        if not holiday_date:
+            raise ValueError("假日日期不能为空")
+        cur.execute(
+            f"SELECT id FROM {ATTENDANCE_HOLIDAYS_TABLE} WHERE holiday_date = ?",
+            (holiday_date,),
+        )
+        existing = cur.fetchone()
+        if existing is not None:
+            hid = int(existing[0])
+            cur.execute(
+                f"""UPDATE {ATTENDANCE_HOLIDAYS_TABLE} SET
+                    holiday_date = ?, holiday_name = ?, holiday_type = ?,
+                    updated_at = unixepoch()
+                WHERE id = ?""",
+                (
+                    holiday_date,
+                    payload.get("holiday_name"),
+                    payload.get("holiday_type", "法定假日"),
+                    hid,
+                ),
+            )
+            conn.commit()
+            return hid
+        cur.execute(
+            f"""INSERT INTO {ATTENDANCE_HOLIDAYS_TABLE} (
+                holiday_date, holiday_name, holiday_type
+            ) VALUES (?, ?, ?)""",
+            (
+                holiday_date,
+                payload.get("holiday_name"),
+                payload.get("holiday_type", "法定假日"),
+            ),
+        )
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+# ---------- leave_requests ----------
+
+def create_leave_request(payload: dict[str, Any]) -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        cur.execute(
+            f"""INSERT INTO {LEAVE_REQUESTS_TABLE} (
+                employee_id, leave_type, start_date, end_date,
+                has_certificate, certificate_type, natural_days,
+                working_days, monthly_salary, working_days_in_month,
+                daily_salary, deduction_amount, annual_leave_used,
+                remaining_annual_leave, approval_level, status,
+                params_json, summary, error_message
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                int(payload.get("employee_id")),
+                payload.get("leave_type"),
+                payload.get("start_date"),
+                payload.get("end_date"),
+                int(payload.get("has_certificate", 0)),
+                payload.get("certificate_type"),
+                payload.get("natural_days"),
+                payload.get("working_days"),
+                payload.get("monthly_salary"),
+                payload.get("working_days_in_month"),
+                payload.get("daily_salary"),
+                payload.get("deduction_amount"),
+                payload.get("annual_leave_used"),
+                payload.get("remaining_annual_leave"),
+                payload.get("approval_level"),
+                payload.get("status", "draft"),
+                dumps_json(payload.get("params")) if payload.get("params") else None,
+                payload.get("summary"),
+                payload.get("error_message"),
+            ),
+        )
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+def update_leave_request(request_id: int, **fields: Any) -> None:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        sets = []
+        values: list[Any] = []
+        for k, v in fields.items():
+            if k == "params":
+                sets.append("params_json = ?")
+                values.append(dumps_json(v))
+            elif k == "params_json":
+                sets.append("params_json = ?")
+                values.append(v)
+            else:
+                sets.append(f"{k} = ?")
+                values.append(v)
+        if not sets:
+            return
+        sets.append("updated_at = unixepoch()")
+        values.append(request_id)
+        cur.execute(
+            f"UPDATE {LEAVE_REQUESTS_TABLE} SET {', '.join(sets)} WHERE id = ?",
+            values,
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def get_request(request_id: int) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"SELECT * FROM {LEAVE_REQUESTS_TABLE} WHERE id = ?",
+            (request_id,),
+        )
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def get_latest_completed_request(
+    employee_id: Optional[int] = None,
+) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        if employee_id is not None:
+            cur.execute(
+                f"""SELECT * FROM {LEAVE_REQUESTS_TABLE}
+                WHERE status = 'completed' AND employee_id = ?
+                ORDER BY id DESC LIMIT 1""",
+                (employee_id,),
+            )
+        else:
+            cur.execute(
+                f"""SELECT * FROM {LEAVE_REQUESTS_TABLE}
+                WHERE status = 'completed'
+                ORDER BY id DESC LIMIT 1"""
+            )
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def list_requests_for_employee(employee_id: int) -> list[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"""SELECT * FROM {LEAVE_REQUESTS_TABLE}
+            WHERE employee_id = ? ORDER BY id DESC""",
+            (employee_id,),
+        )
+        return [_row_dict(r) for r in cur.fetchall()]
+    finally:
+        conn.close()
+
+
+# ---------- leave_balances ----------
+
+def get_balance(
+    employee_id: int, balance_type: str
+) -> Optional[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"""SELECT * FROM {LEAVE_BALANCES_TABLE}
+            WHERE employee_id = ? AND balance_type = ?""",
+            (employee_id, balance_type),
+        )
+        row = cur.fetchone()
+        return _row_dict(row) if row else None
+    finally:
+        conn.close()
+
+
+def upsert_balance(payload: dict[str, Any]) -> int:
+    ensure_db()
+    conn = get_conn()
+    try:
+        cur = conn.cursor()
+        employee_id = int(payload.get("employee_id"))
+        balance_type = str(payload.get("balance_type", "")).strip()
+        if not balance_type:
+            raise ValueError("balance_type 不能为空")
+        cur.execute(
+            f"""SELECT id FROM {LEAVE_BALANCES_TABLE}
+            WHERE employee_id = ? AND balance_type = ?""",
+            (employee_id, balance_type),
+        )
+        existing = cur.fetchone()
+        total_days = payload.get("total_days")
+        used_days = float(payload.get("used_days", 0) or 0)
+        remaining_days = payload.get("remaining_days")
+        if existing is not None:
+            bid = int(existing[0])
+            cur.execute(
+                f"""UPDATE {LEAVE_BALANCES_TABLE} SET
+                    total_days = ?, used_days = ?, remaining_days = ?,
+                    updated_at = unixepoch()
+                WHERE id = ?""",
+                (total_days, used_days, remaining_days, bid),
+            )
+            conn.commit()
+            return bid
+        cur.execute(
+            f"""INSERT INTO {LEAVE_BALANCES_TABLE} (
+                employee_id, balance_type, total_days, used_days, remaining_days
+            ) VALUES (?, ?, ?, ?, ?)""",
+            (employee_id, balance_type, total_days, used_days, remaining_days),
+        )
+        conn.commit()
+        return int(cur.lastrowid)
+    finally:
+        conn.close()
+
+
+def list_balances_for_employee(employee_id: int) -> list[dict[str, Any]]:
+    ensure_db()
+    conn = get_conn()
+    try:
+        conn.row_factory = sqlite3.Row
+        cur = conn.cursor()
+        cur.execute(
+            f"""SELECT * FROM {LEAVE_BALANCES_TABLE}
+            WHERE employee_id = ? ORDER BY balance_type""",
+            (employee_id,),
+        )
+        return [_row_dict(r) for r in cur.fetchall()]
+    finally:
+        conn.close()

scripts/db/schema.py

@@ -0,0 +1,113 @@
+"""高校人事请假考勤：业务表 DDL 与表名常量。"""
+
+from __future__ import annotations
+
+EMPLOYEES_TABLE = "employees"
+LEAVE_POLICIES_TABLE = "leave_policies"
+ATTENDANCE_HOLIDAYS_TABLE = "attendance_holidays"
+LEAVE_REQUESTS_TABLE = "leave_requests"
+LEAVE_BALANCES_TABLE = "leave_balances"
+
+BUSINESS_TABLES: tuple[str, ...] = (
+    EMPLOYEES_TABLE,
+    LEAVE_POLICIES_TABLE,
+    ATTENDANCE_HOLIDAYS_TABLE,
+    LEAVE_REQUESTS_TABLE,
+    LEAVE_BALANCES_TABLE,
+)
+
+EMPLOYEES_DDL = """
+CREATE TABLE IF NOT EXISTS employees (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    employee_no TEXT,
+    department TEXT,
+    position TEXT,
+    position_category TEXT,
+    join_date TEXT,
+    monthly_salary REAL NOT NULL DEFAULT 0,
+    annual_leave_remaining REAL NOT NULL DEFAULT 0,
+    is_active INTEGER NOT NULL DEFAULT 1,
+    notes TEXT,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+LEAVE_POLICIES_DDL = """
+CREATE TABLE IF NOT EXISTS leave_policies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    leave_type TEXT NOT NULL,
+    max_days REAL,
+    day_basis TEXT NOT NULL DEFAULT 'workday',
+    paid_days REAL NOT NULL DEFAULT 0,
+    partial_pay_ratio REAL NOT NULL DEFAULT 1.0,
+    unpaid_after_days REAL,
+    requires_certificate INTEGER NOT NULL DEFAULT 0,
+    can_offset_annual INTEGER NOT NULL DEFAULT 0,
+    approval_threshold_dept INTEGER NOT NULL DEFAULT 3,
+    approval_threshold_hr INTEGER NOT NULL DEFAULT 10,
+    notes TEXT,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+ATTENDANCE_HOLIDAYS_DDL = """
+CREATE TABLE IF NOT EXISTS attendance_holidays (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    holiday_date TEXT NOT NULL,
+    holiday_name TEXT,
+    holiday_type TEXT NOT NULL DEFAULT '法定假日',
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+LEAVE_REQUESTS_DDL = """
+CREATE TABLE IF NOT EXISTS leave_requests (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    employee_id INTEGER NOT NULL,
+    leave_type TEXT NOT NULL,
+    start_date TEXT NOT NULL,
+    end_date TEXT NOT NULL,
+    has_certificate INTEGER NOT NULL DEFAULT 0,
+    certificate_type TEXT,
+    natural_days INTEGER,
+    working_days INTEGER,
+    monthly_salary REAL,
+    working_days_in_month INTEGER,
+    daily_salary REAL,
+    deduction_amount REAL,
+    annual_leave_used REAL,
+    remaining_annual_leave REAL,
+    approval_level TEXT,
+    status TEXT NOT NULL DEFAULT 'draft',
+    params_json TEXT,
+    summary TEXT,
+    error_message TEXT,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+LEAVE_BALANCES_DDL = """
+CREATE TABLE IF NOT EXISTS leave_balances (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    employee_id INTEGER NOT NULL,
+    balance_type TEXT NOT NULL,
+    total_days REAL,
+    used_days REAL NOT NULL DEFAULT 0,
+    remaining_days REAL,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+)
+"""
+
+TABLE_DDL: tuple[tuple[str, str], ...] = (
+    (EMPLOYEES_TABLE, EMPLOYEES_DDL),
+    (LEAVE_POLICIES_TABLE, LEAVE_POLICIES_DDL),
+    (ATTENDANCE_HOLIDAYS_TABLE, ATTENDANCE_HOLIDAYS_DDL),
+    (LEAVE_REQUESTS_TABLE, LEAVE_REQUESTS_DDL),
+    (LEAVE_BALANCES_TABLE, LEAVE_BALANCES_DDL),
+)

scripts/db/timestamp_columns.py

@@ -0,0 +1,50 @@
+"""标准时间字段：Unix 秒级时间戳、默认值与 updated_at 自动维护。
+
+业务表若包含 created_at / updated_at，在 CREATE TABLE 后调用
+``init_updated_at_trigger(cursor, table_name)``。模板默认不建业务表。
+"""
+
+from __future__ import annotations
+
+STANDARD_TIMESTAMP_COLUMNS = frozenset({"created_at", "updated_at"})
+DATETIME_UNIX_SECONDS = "datetime_unix_seconds"
+
+
+def updated_at_trigger_name(table_name: str) -> str:
+    return f"{table_name}_set_updated_at"
+
+
+def _quote_identifier(name: str) -> str:
+    return '"' + name.replace('"', '""') + '"'
+
+
+def init_updated_at_trigger(cursor, table_name: str) -> None:
+    """幂等创建 {table}_set_updated_at：业务字段 UPDATE 后刷新 updated_at。"""
+    trigger = updated_at_trigger_name(table_name)
+    quoted = _quote_identifier(table_name)
+    quoted_trigger = _quote_identifier(trigger)
+    cursor.execute(
+        f"""
+CREATE TRIGGER IF NOT EXISTS {quoted_trigger}
+AFTER UPDATE ON {quoted}
+FOR EACH ROW
+BEGIN
+    UPDATE {quoted}
+    SET updated_at = unixepoch()
+    WHERE id = NEW.id AND updated_at = OLD.updated_at;
+END
+"""
+    )
+
+
+def has_updated_at_trigger(cursor, table_name: str) -> bool:
+    trigger_name = updated_at_trigger_name(table_name)
+    cursor.execute(
+        """
+        SELECT 1 FROM sqlite_master
+        WHERE type = 'trigger' AND name = ? AND tbl_name = ?
+        LIMIT 1
+        """,
+        (trigger_name, table_name),
+    )
+    return cursor.fetchone() is not None