client-huashang/query-payslip-default
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 工资查询助手首版 v1.0.105

Browse Source 
基于 skill-template 脚手架开发，包含：
- payroll_config（费率配置，可编辑）+ payslip_snapshots（解析历史，只读）2 张业务表
- 全国默认 + 北上广 4 套费率（社保/公积金/个税起征点/7 级税率表）
- 5 个业务 Action：calculate-payslip-simple / calculate-payslip-full / explain-term / view-config / edit-config
- 个税累计预扣法计算，支持多月历史累加
- 20 个薪资名词库（社保/公积金/个税/全勤/加班费等）
- 完整市场文档（README/TUTORIAL/DEMO/CHANGELOG）
- 296 测试全部通过
This commit is contained in:
skill-dev
2026-09-07 17:02:05 +08:00
commit 3db196e49d
205 changed files with 29927 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
scripts/db/connection.py Normal file
View File

@@ -0,0 +1,280 @@
"""SQLite 连接与幂等初始化。
模板默认只建数据管理元数据表。业务表由复制后的技能自行 CREATE，并同步展示元数据。
本技能建两张业务表：payroll_config（费率配置，可编辑）与 payslip_snapshots（解析历史，只读）。
"""
from __future__ import annotations
import sqlite3
from db.display_metadata import (
init_display_metadata,
seed_column_metadata_batch,
upsert_table_metadata,
)
from db.seed_config import seed_default_config
from util.runtime_paths import get_db_path
def get_conn() -> sqlite3.Connection:
return sqlite3.connect(get_db_path())
_PAYROLL_CONFIG_DDL = """
CREATE TABLE IF NOT EXISTS payroll_config (
config_key TEXT NOT NULL,
region TEXT NOT NULL DEFAULT 'default',
config_value REAL NOT NULL,
display_name TEXT NOT NULL,
description TEXT,
effective_date INTEGER,
created_at INTEGER NOT NULL DEFAULT (unixepoch()),
updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
PRIMARY KEY (config_key, region)
)
"""
_PAYROLL_CONFIG_UPDATED_AT_TRIGGER = """
CREATE TRIGGER IF NOT EXISTS payroll_config_set_updated_at
AFTER UPDATE ON payroll_config
FOR EACH ROW
BEGIN
UPDATE payroll_config SET updated_at = unixepoch() WHERE config_key = NEW.config_key AND region = NEW.region;
END
"""
_PAYSLIP_SNAPSHOTS_DDL = """
CREATE TABLE IF NOT EXISTS payslip_snapshots (
id INTEGER PRIMARY KEY AUTOINCREMENT,
snapshot_date INTEGER NOT NULL,
period TEXT,
base_salary REAL,
gross_total REAL NOT NULL,
deduction_total REAL NOT NULL,
net_salary REAL NOT NULL,
reported_net REAL,
check_match INTEGER,
check_diff REAL,
detail_json TEXT,
raw_payload TEXT,
created_at INTEGER NOT NULL DEFAULT (unixepoch())
)
"""
_PAYROLL_CONFIG_COLUMNS: tuple[dict[str, object], ...] = (
{
"column_name": "config_key",
"display_name": "配置项",
"description": "费率配置键，如 social_pension_rate / tax_threshold。",
"visible": 1,
"searchable": 1,
"editable": 0,
},
{
"column_name": "region",
"display_name": "地区",
"description": "费率适用地区：default（全国默认）/ beijing / shanghai / guangzhou。",
"visible": 1,
"searchable": 1,
"editable": 0,
"options_json": '[{"value":"default","label":"全国默认"},{"value":"beijing","label":"北京"},{"value":"shanghai","label":"上海"},{"value":"guangzhou","label":"广州"}]',
},
{
"column_name": "config_value",
"display_name": "数值",
"description": "费率数值（比例为小数，如 0.08 表示 8%）。",
"visible": 1,
"searchable": 1,
"editable": 1,
"display_type": "number",
},
{
"column_name": "display_name",
"display_name": "中文名",
"description": "配置项的中文展示名。",
"visible": 1,
"searchable": 1,
"editable": 1,
},
{
"column_name": "description",
"display_name": "说明",
"description": "配置项的详细说明。",
"visible": 1,
"searchable": 0,
"editable": 1,
"display_type": "textarea",
},
{
"column_name": "effective_date",
"display_name": "生效日期",
"description": "该费率的生效日期（Unix 秒级时间戳）。",
"visible": 1,
"searchable": 1,
"editable": 1,
"display_type": "datetime_unix_seconds",
},
{
"column_name": "created_at",
"display_name": "创建时间",
"description": "记录创建时间（Unix 秒级时间戳，自动生成）。",
"visible": 1,
"searchable": 0,
"editable": 0,
"display_type": "datetime_unix_seconds",
},
{
"column_name": "updated_at",
"display_name": "更新时间",
"description": "记录最后更新时间（Unix 秒级时间戳，自动维护）。",
"visible": 1,
"searchable": 0,
"editable": 0,
"display_type": "datetime_unix_seconds",
},
)
_PAYSLIP_SNAPSHOTS_COLUMNS: tuple[dict[str, object], ...] = (
{"column_name": "id", "display_name": "编号", "description": "主键", "visible": 1, "searchable": 1, "editable": 0},
{
"column_name": "snapshot_date",
"display_name": "解析时间",
"description": "本次解析执行的时间（Unix 秒级时间戳）。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "datetime_unix_seconds",
},
{
"column_name": "period",
"display_name": "工资期间",
"description": "工资所属期间，如 2026-08。",
"visible": 1, "searchable": 1, "editable": 0,
},
{
"column_name": "base_salary",
"display_name": "基本工资",
"description": "本次解析的基本工资。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "gross_total",
"display_name": "应发合计",
"description": "本次核算的应发合计。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "deduction_total",
"display_name": "扣除合计",
"description": "本次核算的扣除合计。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "net_salary",
"display_name": "实发工资",
"description": "本次核算的实发工资（应发-扣除）。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "reported_net",
"display_name": "用户自报实发",
"description": "用户给出的实发金额，用于核对。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "check_match",
"display_name": "核对一致",
"description": "1=用户自报与计算一致，0=不一致，NULL=未提供自报。",
"visible": 1, "searchable": 1, "editable": 0,
},
{
"column_name": "check_diff",
"display_name": "差异金额",
"description": "用户自报 - 计算实发。正数表示用户多报，负数表示少报。",
"visible": 1, "searchable": 1, "editable": 0,
"display_type": "number",
},
{
"column_name": "detail_json",
"display_name": "完整明细",
"description": "本次核算的完整明细（JSON 字符串），含各项应发/扣除/估算。",
"visible": 1, "searchable": 0, "editable": 0,
"display_type": "textarea",
},
{
"column_name": "raw_payload",
"display_name": "原始文本",
"description": "用户粘贴的原始工资条文本（隐私保护，默认隐藏）。",
"visible": 0, "searchable": 0, "editable": 0,
"display_type": "textarea",
},
{
"column_name": "created_at",
"display_name": "创建时间",
"description": "记录入库时间（Unix 秒级时间戳，自动生成）。",
"visible": 1, "searchable": 0, "editable": 0,
"display_type": "datetime_unix_seconds",
},
)
def _init_payroll_config_metadata(cursor) -> None:
"""建 payroll_config 表 + 展示元数据。"""
cursor.execute(_PAYROLL_CONFIG_DDL)
cursor.execute(_PAYROLL_CONFIG_UPDATED_AT_TRIGGER)
upsert_table_metadata(
cursor,
table_name="payroll_config",
display_name="费率配置",
description="社保/公积金/个税等费率配置，按地区区分。管理员可编辑数值，影响估算结果。",
grid_help="按地区查看费率；双击数值可编辑（仅管理员）。地区 default 为全国默认。",
visible=1,
readonly=0,
)
seed_column_metadata_batch(
cursor,
table_name="payroll_config",
columns=_PAYROLL_CONFIG_COLUMNS,
valid_column_names=[str(c["column_name"]) for c in _PAYROLL_CONFIG_COLUMNS],
)
def _init_payslip_snapshots_metadata(cursor) -> None:
"""建 payslip_snapshots 表 + 展示元数据（只读）。"""
cursor.execute(_PAYSLIP_SNAPSHOTS_DDL)
upsert_table_metadata(
cursor,
table_name="payslip_snapshots",
display_name="解析历史",
description="本人工资条解析历史记录。每次解析自动写入，可回顾/对比多月。",
grid_help="按工资期间或时间排序查看历史；raw_payload 默认隐藏。",
visible=1,
readonly=1,
default_sort_json='[{"column":"snapshot_date","direction":"desc"},{"column":"id","direction":"desc"}]',
default_visible_columns_json='["snapshot_date","period","base_salary","gross_total","deduction_total","net_salary","check_match"]',
)
seed_column_metadata_batch(
cursor,
table_name="payslip_snapshots",
columns=_PAYSLIP_SNAPSHOTS_COLUMNS,
valid_column_names=[str(c["column_name"]) for c in _PAYSLIP_SNAPSHOTS_COLUMNS],
)
def init_db() -> None:
conn = get_conn()
try:
cur = conn.cursor()
init_display_metadata(cur)
_init_payroll_config_metadata(cur)
_init_payslip_snapshots_metadata(cur)
seed_default_config(cur)
conn.commit()
finally:
conn.close()

324
scripts/db/display_metadata.py Normal file
View File

@@ -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]

592
scripts/db/display_metadata_validator.py Normal file
View File

@@ -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({"query-payslip-default", "query_payslip_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)

141
scripts/db/seed_config.py Normal file
View File

@@ -0,0 +1,141 @@
"""费率配置 seed：全国默认 + 北京 + 上海 + 广州 4 套。
幂等：已存在的 (config_key, region) 不会被覆盖，避免用户编辑后被重置。
首次 init_db 时插入；之后用户改的值会保留。
"""
from __future__ import annotations
import sqlite3
from typing import Any
# 7 级累计预扣税率表（2024 起，月度换算为累计）
# 级数：累计预扣预缴应纳税所得额上限 / 税率 / 速算扣除数
TAX_BRACKETS_JSON = """[
{"level":1,"upper":36000,"rate":0.03,"quick_deduction":0},
{"level":2,"upper":144000,"rate":0.10,"quick_deduction":2520},
{"level":3,"upper":300000,"rate":0.20,"quick_deduction":16920},
{"level":4,"upper":420000,"rate":0.25,"quick_deduction":31920},
{"level":5,"upper":660000,"rate":0.30,"quick_deduction":52920},
{"level":6,"upper":960000,"rate":0.35,"quick_deduction":85920},
{"level":7,"upper":null,"rate":0.45,"quick_deduction":181920}
]"""
# 各地区费率配置
# config_key: (display_name, description, default_value, beijing_value, shanghai_value, guangzhou_value)
# None 表示该地区使用全国默认值
_CONFIG_ROWS: list[dict[str, Any]] = [
{
"config_key": "social_pension_rate",
"display_name": "养老保险个人比例",
"description": "基本养老保险个人缴费比例。",
"values": {"default": 0.08, "beijing": 0.08, "shanghai": 0.08, "guangzhou": 0.08},
},
{
"config_key": "social_medical_rate",
"display_name": "医疗保险个人比例",
"description": "基本医疗保险个人缴费比例。",
"values": {"default": 0.02, "beijing": 0.02, "shanghai": 0.02, "guangzhou": 0.02},
},
{
"config_key": "social_unemployment_rate",
"display_name": "失业保险个人比例",
"description": "失业保险个人缴费比例。",
"values": {"default": 0.005, "beijing": 0.0005, "shanghai": 0.005, "guangzhou": 0.002},
},
{
"config_key": "social_base_min",
"display_name": "社保缴费下限",
"description": "社保缴费基数下限；低于此值按下限计。",
"values": {"default": 5000, "beijing": 6326, "shanghai": 7310, "guangzhou": 5500},
},
{
"config_key": "social_base_max",
"display_name": "社保缴费上限",
"description": "社保缴费基数上限；高于此值按上限计。",
"values": {"default": 30000, "beijing": 35283, "shanghai": 36549, "guangzhou": 27501},
},
{
"config_key": "housing_fund_rate",
"display_name": "公积金个人比例",
"description": "住房公积金个人缴费比例。",
"values": {"default": 0.07, "beijing": 0.12, "shanghai": 0.07, "guangzhou": 0.05},
},
{
"config_key": "housing_fund_base_min",
"display_name": "公积金缴费下限",
"description": "公积金缴费基数下限。",
"values": {"default": 2500, "beijing": 2420, "shanghai": 2590, "guangzhou": 2300},
},
{
"config_key": "housing_fund_base_max",
"display_name": "公积金缴费上限",
"description": "公积金缴费基数上限。",
"values": {"default": 30000, "beijing": 33891, "shanghai": 36549, "guangzhou": 36771},
},
{
"config_key": "tax_threshold",
"display_name": "个税起征点",
"description": "个人所得税基本减除费用标准（5000 元/月）。",
"values": {"default": 5000, "beijing": 5000, "shanghai": 5000, "guangzhou": 5000},
},
{
"config_key": "tax_brackets_json",
"display_name": "个税税率表",
"description": "7 级累计预扣税率表（JSON 字符串）。",
"values": {"default": TAX_BRACKETS_JSON, "beijing": None, "shanghai": None, "guangzhou": None},
},
]
_REGIONS = ("default", "beijing", "shanghai", "guangzhou")
def _insert_if_absent(
cursor: sqlite3.Cursor,
*,
config_key: str,
region: str,
config_value: float,
display_name: str,
description: str,
) -> None:
"""幂等插入：已存在则跳过，不覆盖用户编辑。"""
cursor.execute(
"SELECT 1 FROM payroll_config WHERE config_key=? AND region=?",
(config_key, region),
)
if cursor.fetchone() is not None:
return
cursor.execute(
"""
INSERT INTO payroll_config (config_key, region, config_value, display_name, description, effective_date)
VALUES (?, ?, ?, ?, ?, NULL)
""",
(config_key, region, config_value, display_name, description),
)
def seed_default_config(cursor: sqlite3.Cursor) -> None:
"""幂等 seed 4 套地区费率配置。
北上广若某项为 None，则该地区该项使用全国默认值（不插入，查询时回退）。
"""
for row in _CONFIG_ROWS:
key = row["config_key"]
display_name = row["display_name"]
description = row["description"]
values = row["values"]
for region in _REGIONS:
value = values.get(region)
if value is None:
# 该地区该项沿用全国默认（不单独插入）
continue
_insert_if_absent(
cursor,
config_key=key,
region=region,
config_value=value,
display_name=display_name,
description=description,
)

50
scripts/db/timestamp_columns.py Normal file
View File

@@ -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