feat: 工资查询助手首版 v1.0.105
基于 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
209
scripts/cli/app.py
Normal file
209
scripts/cli/app.py
Normal file
@@ -0,0 +1,209 @@
|
||||
"""CLI：argparse 与分发模板。
|
||||
|
||||
只负责参数解析并转交 service；业务内核在 domain / task_service，勿在此按入口复制逻辑。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
from typing import List, Optional
|
||||
|
||||
from service.task_service import (
|
||||
cmd_calculate_full,
|
||||
cmd_calculate_simple,
|
||||
cmd_config_path,
|
||||
cmd_edit_config,
|
||||
cmd_explain,
|
||||
cmd_health,
|
||||
cmd_init_db,
|
||||
cmd_run,
|
||||
cmd_version,
|
||||
cmd_view_config,
|
||||
_parse_float_or_none,
|
||||
)
|
||||
from util.config_bootstrap import bootstrap_skill_config
|
||||
from util.argparse_zh import ZhArgumentParser
|
||||
from util.constants import LOG_LOGGER_NAME, SKILL_SLUG
|
||||
from util.logging_config import get_skill_logger, setup_skill_logging
|
||||
|
||||
|
||||
def _cli_str_or_none(raw: Optional[str]) -> Optional[str]:
|
||||
if raw is None:
|
||||
return None
|
||||
v = str(raw).strip()
|
||||
return v or None
|
||||
|
||||
|
||||
def _handle_run(args: argparse.Namespace) -> int:
|
||||
tail = [str(x).strip() for x in (args.run_tail or []) if str(x).strip()]
|
||||
if len(tail) > 2:
|
||||
print("参数过多。")
|
||||
print("用法：python main.py run [target [input_id]] | run [-t target] [-i input_id]")
|
||||
return 1
|
||||
|
||||
t_target: Optional[str] = None
|
||||
t_input: Optional[str] = None
|
||||
if len(tail) == 2:
|
||||
t_target, t_input = tail[0], tail[1]
|
||||
elif len(tail) == 1:
|
||||
if tail[0].isdigit():
|
||||
t_input = tail[0]
|
||||
else:
|
||||
t_target = tail[0]
|
||||
|
||||
pick_t = _cli_str_or_none(getattr(args, "target", None))
|
||||
pick_i = _cli_str_or_none(getattr(args, "input_id", None))
|
||||
target = pick_t or t_target
|
||||
input_id = pick_i or t_input
|
||||
return cmd_run(target=target, input_id=input_id)
|
||||
|
||||
|
||||
def _handle_calculate_simple(args: argparse.Namespace) -> int:
|
||||
base_salary = float(args.base_salary)
|
||||
period = _cli_str_or_none(args.period) or ""
|
||||
reported_net = _parse_float_or_none(_cli_str_or_none(args.reported_net))
|
||||
region = _cli_str_or_none(args.region) or "default"
|
||||
return cmd_calculate_simple(base_salary=base_salary, period=period, reported_net=reported_net, region=region)
|
||||
|
||||
|
||||
def _handle_calculate_full(args: argparse.Namespace) -> int:
|
||||
region = _cli_str_or_none(args.region) or "default"
|
||||
period = _cli_str_or_none(args.period) or ""
|
||||
raw_payload = _cli_str_or_none(args.raw_payload) or ""
|
||||
return cmd_calculate_full(
|
||||
base_salary=float(args.base_salary or 0),
|
||||
performance=float(args.performance or 0),
|
||||
full_attendance=float(args.full_attendance or 0),
|
||||
meal_allowance=float(args.meal_allowance or 0),
|
||||
transport_allowance=float(args.transport_allowance or 0),
|
||||
overtime_pay=float(args.overtime_pay or 0),
|
||||
other_gross=float(args.other_gross or 0),
|
||||
social_personal=_parse_float_or_none(_cli_str_or_none(args.social_personal)),
|
||||
housing_fund_personal=_parse_float_or_none(_cli_str_or_none(args.housing_fund_personal)),
|
||||
tax=_parse_float_or_none(_cli_str_or_none(args.tax)),
|
||||
leave_deduction=float(args.leave_deduction or 0),
|
||||
other_deduction=float(args.other_deduction or 0),
|
||||
period=period,
|
||||
reported_net=_parse_float_or_none(_cli_str_or_none(args.reported_net)),
|
||||
raw_payload=raw_payload,
|
||||
region=region,
|
||||
)
|
||||
|
||||
|
||||
def _handle_explain(args: argparse.Namespace) -> int:
|
||||
term = _cli_str_or_none(args.term) or ""
|
||||
return cmd_explain(term)
|
||||
|
||||
|
||||
def _handle_view_config(args: argparse.Namespace) -> int:
|
||||
region = _cli_str_or_none(args.region)
|
||||
return cmd_view_config(region=region)
|
||||
|
||||
|
||||
def _handle_edit_config(args: argparse.Namespace) -> int:
|
||||
return cmd_edit_config(
|
||||
config_key=_cli_str_or_none(args.config_key) or "",
|
||||
region=_cli_str_or_none(args.region) or "default",
|
||||
config_value=float(args.config_value),
|
||||
)
|
||||
|
||||
|
||||
def _print_full_usage() -> None:
|
||||
print("工资查询助手（main.py）可用命令：")
|
||||
print(" python main.py calculate-simple --base-salary N --period YYYY-MM [--reported-net N] [--region default|beijing|shanghai|guangzhou]")
|
||||
print(" python main.py calculate-full [全字段参数] --period YYYY-MM [--region ...]")
|
||||
print(" python main.py explain --term 名词")
|
||||
print(" python main.py view-config [--region ...]")
|
||||
print(" python main.py edit-config --config-key KEY --region R --config-value V")
|
||||
print(" python main.py run [target [input_id]] [-t target] [-i input_id]")
|
||||
print(" python main.py health")
|
||||
print(" python main.py config-path")
|
||||
print(" python main.py version")
|
||||
print(" python main.py init-db")
|
||||
|
||||
|
||||
def build_parser() -> ZhArgumentParser:
|
||||
p = ZhArgumentParser(
|
||||
prog="main.py",
|
||||
description="工资查询助手：核算应发/扣除/实发，核对差异，解释名词，估算个税。",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
)
|
||||
sub = p.add_subparsers(dest="cmd", required=True, parser_class=ZhArgumentParser)
|
||||
|
||||
# calculate-simple
|
||||
sp = sub.add_parser("calculate-simple", help="快速估算（仅基本工资+period）")
|
||||
sp.add_argument("--base-salary", required=True, type=float, metavar="基本工资")
|
||||
sp.add_argument("--period", required=True, metavar="YYYY-MM")
|
||||
sp.add_argument("--reported-net", default=None, metavar="用户自报实发")
|
||||
sp.add_argument("--region", default=None, metavar="地区")
|
||||
sp.set_defaults(handler=_handle_calculate_simple)
|
||||
|
||||
# calculate-full
|
||||
sp = sub.add_parser("calculate-full", help="精确核算（全字段）")
|
||||
sp.add_argument("--base-salary", type=float, default=0, metavar="基本工资")
|
||||
sp.add_argument("--performance", type=float, default=0, metavar="绩效")
|
||||
sp.add_argument("--full-attendance", type=float, default=0, metavar="全勤", dest="full_attendance")
|
||||
sp.add_argument("--meal-allowance", type=float, default=0, metavar="餐补", dest="meal_allowance")
|
||||
sp.add_argument("--transport-allowance", type=float, default=0, metavar="交通补", dest="transport_allowance")
|
||||
sp.add_argument("--overtime-pay", type=float, default=0, metavar="加班费", dest="overtime_pay")
|
||||
sp.add_argument("--other-gross", type=float, default=0, metavar="其他应发", dest="other_gross")
|
||||
sp.add_argument("--social-personal", default=None, metavar="社保个人", dest="social_personal")
|
||||
sp.add_argument("--housing-fund-personal", default=None, metavar="公积金个人", dest="housing_fund_personal")
|
||||
sp.add_argument("--tax", default=None, metavar="个税")
|
||||
sp.add_argument("--leave-deduction", type=float, default=0, metavar="事假扣款", dest="leave_deduction")
|
||||
sp.add_argument("--other-deduction", type=float, default=0, metavar="其他扣款", dest="other_deduction")
|
||||
sp.add_argument("--period", default="", metavar="YYYY-MM")
|
||||
sp.add_argument("--reported-net", default=None, metavar="用户自报实发", dest="reported_net")
|
||||
sp.add_argument("--raw-payload", default=None, metavar="原始工资条文本", dest="raw_payload")
|
||||
sp.add_argument("--region", default=None, metavar="地区")
|
||||
sp.set_defaults(handler=_handle_calculate_full)
|
||||
|
||||
# explain
|
||||
sp = sub.add_parser("explain", help="名词解释")
|
||||
sp.add_argument("--term", required=True, metavar="名词")
|
||||
sp.set_defaults(handler=_handle_explain)
|
||||
|
||||
# view-config
|
||||
sp = sub.add_parser("view-config", help="查看费率配置")
|
||||
sp.add_argument("--region", default=None, metavar="地区")
|
||||
sp.set_defaults(handler=_handle_view_config)
|
||||
|
||||
# edit-config
|
||||
sp = sub.add_parser("edit-config", help="编辑费率配置")
|
||||
sp.add_argument("--config-key", required=True, metavar="配置键", dest="config_key")
|
||||
sp.add_argument("--region", default="default", metavar="地区")
|
||||
sp.add_argument("--config-value", required=True, type=float, metavar="新值", dest="config_value")
|
||||
sp.set_defaults(handler=_handle_edit_config)
|
||||
|
||||
sp = sub.add_parser("run", help="任务执行命令骨架")
|
||||
sp.add_argument("--target", "-t", default=None, metavar="目标")
|
||||
sp.add_argument("--input-id", "-i", default=None, metavar="输入id", dest="input_id")
|
||||
sp.add_argument("run_tail", nargs="*", metavar="位置参数")
|
||||
sp.set_defaults(handler=_handle_run)
|
||||
|
||||
sp = sub.add_parser("health", help="健康检查")
|
||||
sp.set_defaults(handler=lambda _a: cmd_health())
|
||||
|
||||
sp = sub.add_parser("config-path", help="输出用户 .env 与模板路径")
|
||||
sp.set_defaults(handler=lambda _a: cmd_config_path())
|
||||
|
||||
sp = sub.add_parser("version", help="版本信息(JSON)")
|
||||
sp.set_defaults(handler=lambda _a: cmd_version())
|
||||
|
||||
sp = sub.add_parser("init-db", help="幂等初始化本地数据库与数据管理元数据")
|
||||
sp.set_defaults(handler=lambda _a: cmd_init_db())
|
||||
return p
|
||||
|
||||
|
||||
def main(argv: Optional[List[str]] = None) -> int:
|
||||
argv = argv if argv is not None else sys.argv[1:]
|
||||
bootstrap_skill_config()
|
||||
setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)
|
||||
get_skill_logger().info("cli_start argv=%s", sys.argv)
|
||||
if not argv:
|
||||
_print_full_usage()
|
||||
return 1
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(argv)
|
||||
return int(args.handler(args))
|
||||
280
scripts/db/connection.py
Normal file
280
scripts/db/connection.py
Normal 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
324
scripts/db/display_metadata.py
Normal 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
592
scripts/db/display_metadata_validator.py
Normal 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
141
scripts/db/seed_config.py
Normal 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
50
scripts/db/timestamp_columns.py
Normal 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
|
||||
38
scripts/main.py
Normal file
38
scripts/main.py
Normal file
@@ -0,0 +1,38 @@
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
skill-template CLI 入口。
|
||||
|
||||
复制为新技能后，请修改注释与常量，但保留当前分层结构：
|
||||
cli（argv）→ service（业务编排）→ db（持久化）→ util（通用工具）。
|
||||
|
||||
jiangchang_skill_core 来自宿主共享 Python runtime 安装的 jiangchang-platform-kit，
|
||||
不在技能仓库内 vendored。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import sys
|
||||
|
||||
if sys.platform == "win32":
|
||||
import io
|
||||
|
||||
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
|
||||
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
|
||||
|
||||
_scripts_dir = os.path.dirname(os.path.abspath(__file__))
|
||||
if _scripts_dir not in sys.path:
|
||||
sys.path.insert(0, _scripts_dir)
|
||||
|
||||
from jiangchang_skill_core.runtime_env import apply_cli_local_defaults
|
||||
|
||||
apply_cli_local_defaults()
|
||||
|
||||
from util.config_bootstrap import bootstrap_skill_config
|
||||
|
||||
bootstrap_skill_config()
|
||||
|
||||
from cli.app import main
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
147
scripts/service/config_service.py
Normal file
147
scripts/service/config_service.py
Normal file
@@ -0,0 +1,147 @@
|
||||
"""费率配置读取服务。
|
||||
|
||||
从 payroll_config 表读取指定地区的费率；地区未单独插入时回退到全国默认。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from typing import Any
|
||||
|
||||
from db.connection import get_conn
|
||||
from util.logging_config import get_skill_logger
|
||||
|
||||
log = get_skill_logger()
|
||||
|
||||
|
||||
def get_config_value(config_key: str, region: str = "default") -> float | str | None:
|
||||
"""读取单个配置项的值。
|
||||
|
||||
优先取 (config_key, region)；若该地区无记录，回退到 (config_key, 'default')。
|
||||
"""
|
||||
conn = get_conn()
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
cur.execute(
|
||||
"SELECT config_value FROM payroll_config WHERE config_key=? AND region=?",
|
||||
(config_key, region),
|
||||
)
|
||||
row = cur.fetchone()
|
||||
if row is None and region != "default":
|
||||
cur.execute(
|
||||
"SELECT config_value FROM payroll_config WHERE config_key=? AND region='default'",
|
||||
(config_key,),
|
||||
)
|
||||
row = cur.fetchone()
|
||||
if row is None:
|
||||
return None
|
||||
return row[0]
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
def get_tax_brackets(region: str = "default") -> list[dict[str, Any]]:
|
||||
"""读取 7 级累计预扣税率表。"""
|
||||
raw = get_config_value("tax_brackets_json", region)
|
||||
if raw is None or not isinstance(raw, str):
|
||||
return []
|
||||
try:
|
||||
brackets = json.loads(raw)
|
||||
return brackets if isinstance(brackets, list) else []
|
||||
except (json.JSONDecodeError, TypeError):
|
||||
return []
|
||||
|
||||
|
||||
def get_region_config(region: str = "default") -> dict[str, Any]:
|
||||
"""读取一个地区的全部费率配置，返回 dict。"""
|
||||
keys = [
|
||||
"social_pension_rate",
|
||||
"social_medical_rate",
|
||||
"social_unemployment_rate",
|
||||
"social_base_min",
|
||||
"social_base_max",
|
||||
"housing_fund_rate",
|
||||
"housing_fund_base_min",
|
||||
"housing_fund_base_max",
|
||||
"tax_threshold",
|
||||
]
|
||||
result: dict[str, Any] = {"region": region}
|
||||
for key in keys:
|
||||
result[key] = get_config_value(key, region)
|
||||
result["tax_brackets"] = get_tax_brackets(region)
|
||||
return result
|
||||
|
||||
|
||||
def list_all_config(region: str | None = None) -> list[dict[str, Any]]:
|
||||
"""列出费率配置（供 view-config Action）。
|
||||
|
||||
region 为 None 时列出全部地区；否则只列该地区（含回退默认值）。
|
||||
"""
|
||||
conn = get_conn()
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
if region is None:
|
||||
cur.execute(
|
||||
"SELECT config_key, region, config_value, display_name, description FROM payroll_config ORDER BY region, config_key"
|
||||
)
|
||||
else:
|
||||
cur.execute(
|
||||
"SELECT config_key, region, config_value, display_name, description FROM payroll_config WHERE region=? ORDER BY config_key",
|
||||
(region,),
|
||||
)
|
||||
rows = cur.fetchall()
|
||||
return [
|
||||
{
|
||||
"config_key": r[0],
|
||||
"region": r[1],
|
||||
"config_value": r[2],
|
||||
"display_name": r[3],
|
||||
"description": r[4],
|
||||
}
|
||||
for r in rows
|
||||
]
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
def update_config_value(config_key: str, region: str, config_value: float) -> dict[str, Any]:
|
||||
"""更新单个费率配置（供 edit-config Action）。
|
||||
|
||||
返回 {ok, skill, config_key, region, old_value, new_value}。
|
||||
"""
|
||||
log.info("config_update key=%s region=%s value=%s", config_key, region, config_value)
|
||||
conn = get_conn()
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
cur.execute(
|
||||
"SELECT config_value FROM payroll_config WHERE config_key=? AND region=?",
|
||||
(config_key, region),
|
||||
)
|
||||
row = cur.fetchone()
|
||||
if row is None:
|
||||
return {
|
||||
"ok": False,
|
||||
"skill": "query-payslip-default",
|
||||
"error_code": "CONFIG_NOT_FOUND",
|
||||
"error": f"配置项 {config_key}（地区 {region}）不存在",
|
||||
}
|
||||
old_value = row[0]
|
||||
cur.execute(
|
||||
"""
|
||||
UPDATE payroll_config
|
||||
SET config_value=?, updated_at=strftime('%s','now')
|
||||
WHERE config_key=? AND region=?
|
||||
""",
|
||||
(config_value, config_key, region),
|
||||
)
|
||||
conn.commit()
|
||||
return {
|
||||
"ok": True,
|
||||
"skill": "query-payslip-default",
|
||||
"config_key": config_key,
|
||||
"region": region,
|
||||
"old_value": old_value,
|
||||
"new_value": config_value,
|
||||
}
|
||||
finally:
|
||||
conn.close()
|
||||
46
scripts/service/entitlement_service.py
Normal file
46
scripts/service/entitlement_service.py
Normal file
@@ -0,0 +1,46 @@
|
||||
"""在线鉴权（可选模板）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Tuple
|
||||
|
||||
import requests
|
||||
from jiangchang_skill_core import config
|
||||
|
||||
|
||||
def check_entitlement(skill_slug: str) -> Tuple[bool, str]:
|
||||
auth_base = (config.get("JIANGCHANG_AUTH_BASE_URL") or "").strip().rstrip("/")
|
||||
if not auth_base:
|
||||
return True, ""
|
||||
user_id = (config.get("JIANGCHANG_USER_ID") or "").strip()
|
||||
if not user_id:
|
||||
return False, "鉴权失败：缺少用户身份（JIANGCHANG_USER_ID）"
|
||||
|
||||
auth_api_key = (config.get("JIANGCHANG_AUTH_API_KEY") or "").strip()
|
||||
timeout = int((config.get("JIANGCHANG_AUTH_TIMEOUT_SECONDS") or "5").strip())
|
||||
headers = {"Content-Type": "application/json"}
|
||||
if auth_api_key:
|
||||
headers["Authorization"] = f"Bearer {auth_api_key}"
|
||||
payload = {
|
||||
"user_id": user_id,
|
||||
"skill_slug": skill_slug,
|
||||
"trace_id": (config.get("JIANGCHANG_TRACE_ID") or "").strip(),
|
||||
"context": {"entry": "main.py"},
|
||||
}
|
||||
try:
|
||||
res = requests.post(f"{auth_base}/api/entitlements/check", json=payload, headers=headers, timeout=timeout)
|
||||
except requests.RequestException as exc:
|
||||
return False, f"鉴权请求失败：{exc}"
|
||||
if res.status_code != 200:
|
||||
return False, f"鉴权服务异常：HTTP {res.status_code}"
|
||||
try:
|
||||
body = res.json()
|
||||
except ValueError:
|
||||
return False, "鉴权服务异常：返回非 JSON"
|
||||
code = body.get("code")
|
||||
data = body.get("data") or {}
|
||||
if code != 200:
|
||||
return False, str(body.get("msg") or "鉴权失败")
|
||||
if not data.get("allow", False):
|
||||
return False, str(data.get("reason") or "未购买或已过期")
|
||||
return True, ""
|
||||
95
scripts/service/glossary_service.py
Normal file
95
scripts/service/glossary_service.py
Normal file
@@ -0,0 +1,95 @@
|
||||
"""名词解释服务。
|
||||
|
||||
从 assets/glossary.json 读取词条，按 key/display/category 查询。
|
||||
不做 LLM 生成，纯静态数据查询。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from typing import Any, Optional
|
||||
|
||||
from util.constants import SKILL_SLUG
|
||||
from util.logging_config import get_skill_logger
|
||||
from util.runtime_paths import get_skill_root
|
||||
|
||||
log = get_skill_logger()
|
||||
|
||||
|
||||
def _load_glossary() -> list[dict[str, Any]]:
|
||||
"""从 assets/glossary.json 加载全部词条。"""
|
||||
glossary_path = get_skill_root() / "assets" / "glossary.json"
|
||||
try:
|
||||
with open(glossary_path, "r", encoding="utf-8") as f:
|
||||
data = json.load(f)
|
||||
terms = data.get("terms", []) if isinstance(data, dict) else []
|
||||
return terms if isinstance(terms, list) else []
|
||||
except (FileNotFoundError, json.JSONDecodeError, OSError):
|
||||
return []
|
||||
|
||||
|
||||
def explain_term(term: str) -> dict[str, Any]:
|
||||
"""查询单个名词解释。
|
||||
|
||||
支持按 key（精确）或 display（包含）匹配。
|
||||
未命中返回结构化空（ok=True, found=False）。
|
||||
"""
|
||||
log.info("glossary_explain term=%s", term)
|
||||
terms = _load_glossary()
|
||||
term_lower = (term or "").strip().lower()
|
||||
|
||||
hit: Optional[dict[str, Any]] = None
|
||||
for t in terms:
|
||||
if str(t.get("key", "")).lower() == term_lower:
|
||||
hit = t
|
||||
break
|
||||
if term_lower in str(t.get("display", "")).lower():
|
||||
hit = t
|
||||
break
|
||||
|
||||
if hit is None:
|
||||
return {
|
||||
"ok": True,
|
||||
"skill": SKILL_SLUG,
|
||||
"found": False,
|
||||
"term": term,
|
||||
"explanation": None,
|
||||
"suggestions": [str(t.get("display", "")) for t in terms[:5]],
|
||||
}
|
||||
|
||||
return {
|
||||
"ok": True,
|
||||
"skill": SKILL_SLUG,
|
||||
"found": True,
|
||||
"term": term,
|
||||
"key": hit.get("key"),
|
||||
"display": hit.get("display"),
|
||||
"category": hit.get("category"),
|
||||
"explanation": hit.get("explanation"),
|
||||
"example": hit.get("example"),
|
||||
}
|
||||
|
||||
|
||||
def list_terms(category: str | None = None) -> dict[str, Any]:
|
||||
"""列出全部或按分类的词条。"""
|
||||
terms = _load_glossary()
|
||||
if category:
|
||||
filtered = [t for t in terms if str(t.get("category", "")).lower() == category.lower()]
|
||||
else:
|
||||
filtered = terms
|
||||
return {
|
||||
"ok": True,
|
||||
"skill": SKILL_SLUG,
|
||||
"count": len(filtered),
|
||||
"categories": sorted({str(t.get("category", "")) for t in terms}),
|
||||
"terms": [
|
||||
{
|
||||
"key": t.get("key"),
|
||||
"display": t.get("display"),
|
||||
"category": t.get("category"),
|
||||
"explanation": t.get("explanation"),
|
||||
"example": t.get("example"),
|
||||
}
|
||||
for t in filtered
|
||||
],
|
||||
}
|
||||
78
scripts/service/html_page_service.py
Normal file
78
scripts/service/html_page_service.py
Normal file
@@ -0,0 +1,78 @@
|
||||
"""技能 HTML 报告页：写入 `{skill_data}/html/*.html`（宿主扫描预览）。
|
||||
|
||||
契约要点（权威说明见 `references/ACTIONS.md`「HTML 页面报告」）：
|
||||
|
||||
- 目录：仅一层 `html/*.html`（非递归）
|
||||
- 重新生成 Action id 必须为 `render-html`（宿主硬编码）
|
||||
- 页面布局底线见 `references/ACTIONS.md`「宿主预览布局」；模板壳 `assets/html/example-report.html`
|
||||
- 成功后建议 `steps: refreshCatalog` 以重扫侧栏
|
||||
- 本模块只提供路径/模板/原子写；业务 KPI/表格由各技能自行填充
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
from typing import Mapping
|
||||
|
||||
from util.logging_config import get_skill_logger
|
||||
from util.runtime_paths import get_html_dir, get_skill_root
|
||||
|
||||
# Host Data Management looks up this exact Skill Action id for「重新生成」.
|
||||
HOST_HTML_RENDER_ACTION_ID = "render-html"
|
||||
|
||||
_UNSAFE_NAME = re.compile(r"[\\/]|^\.\.|\.\.$")
|
||||
|
||||
|
||||
def _log():
|
||||
try:
|
||||
return get_skill_logger()
|
||||
except RuntimeError:
|
||||
return None
|
||||
|
||||
|
||||
def assert_html_filename(filename: str) -> str:
|
||||
name = (filename or "").strip()
|
||||
if not name.lower().endswith(".html"):
|
||||
raise ValueError(f"html filename must end with .html: {filename!r}")
|
||||
if _UNSAFE_NAME.search(name) or "/" in name or "\\" in name:
|
||||
raise ValueError(f"html filename must be a basename only: {filename!r}")
|
||||
if len(name) > 200:
|
||||
raise ValueError(f"html filename too long: {filename!r}")
|
||||
return name
|
||||
|
||||
|
||||
def html_page_path(filename: str, *, create_dir: bool = True) -> str:
|
||||
return os.path.join(get_html_dir(create=create_dir), assert_html_filename(filename))
|
||||
|
||||
|
||||
def load_html_template(relative_under_skill_root: str) -> str:
|
||||
"""Load UTF-8 template from skill root (e.g. ``assets/html/example-report.html``)."""
|
||||
rel = (relative_under_skill_root or "").strip().replace("\\", "/")
|
||||
if not rel or rel.startswith("/") or ".." in rel.split("/"):
|
||||
raise ValueError(f"invalid template path: {relative_under_skill_root!r}")
|
||||
path = os.path.join(get_skill_root(), *rel.split("/"))
|
||||
with open(path, encoding="utf-8") as f:
|
||||
return f.read()
|
||||
|
||||
|
||||
def render_html_placeholders(template: str, mapping: Mapping[str, str]) -> str:
|
||||
"""Replace ``{{KEY}}`` tokens. Unknown keys are left as-is."""
|
||||
page = template
|
||||
for key, value in mapping.items():
|
||||
page = page.replace("{{" + str(key) + "}}", str(value))
|
||||
return page
|
||||
|
||||
|
||||
def write_html_page(filename: str, html: str) -> str:
|
||||
"""Atomically write UTF-8 HTML under ``html/``. Returns absolute path."""
|
||||
dest = html_page_path(filename, create_dir=True)
|
||||
tmp = dest + ".tmp"
|
||||
text = html if isinstance(html, str) else str(html)
|
||||
with open(tmp, "w", encoding="utf-8", newline="\n") as f:
|
||||
f.write(text)
|
||||
os.replace(tmp, dest)
|
||||
log = _log()
|
||||
if log:
|
||||
log.info("html_page_written path=%s bytes=%s", dest, len(text.encode("utf-8")))
|
||||
return dest
|
||||
328
scripts/service/payslip_service.py
Normal file
328
scripts/service/payslip_service.py
Normal file
@@ -0,0 +1,328 @@
|
||||
"""工资条核算引擎（唯一业务内核）。
|
||||
|
||||
职责：
|
||||
- 接收结构化字段（应发项、扣除项、period、自报实发）
|
||||
- 确定性核算：应发合计 / 扣除合计 / 实发 / 核对差异
|
||||
- 缺扣除项时按费率估算（社保/公积金/个税累计预扣）
|
||||
- 落库到 payslip_snapshots（含完整明细 JSON）
|
||||
|
||||
不做：LLM 文本解析、自然语言生成。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import time
|
||||
from typing import Any, Optional
|
||||
|
||||
from db.connection import get_conn, init_db
|
||||
from service.config_service import get_config_value
|
||||
from service.tax_service import compute_cumulative_tax
|
||||
from util.constants import SKILL_SLUG
|
||||
from util.logging_config import get_skill_logger
|
||||
|
||||
|
||||
def _clamp_base(base: float, lower: float, upper: float) -> float:
|
||||
"""按上下限裁剪缴费基数。"""
|
||||
if base < lower:
|
||||
return lower
|
||||
if base > upper:
|
||||
return upper
|
||||
return base
|
||||
|
||||
|
||||
def _estimate_social(base_salary: float, region: str = "default") -> dict[str, Any]:
|
||||
"""按费率估算社保个人部分。"""
|
||||
pension_rate = float(get_config_value("social_pension_rate", region) or 0.08)
|
||||
medical_rate = float(get_config_value("social_medical_rate", region) or 0.02)
|
||||
unemploy_rate = float(get_config_value("social_unemployment_rate", region) or 0.005)
|
||||
base_min = float(get_config_value("social_base_min", region) or 5000)
|
||||
base_max = float(get_config_value("social_base_max", region) or 30000)
|
||||
|
||||
base = _clamp_base(base_salary, base_min, base_max)
|
||||
pension = round(base * pension_rate, 2)
|
||||
medical = round(base * medical_rate, 2)
|
||||
unemployment = round(base * unemploy_rate, 2)
|
||||
personal_total = round(pension + medical + unemployment, 2)
|
||||
|
||||
return {
|
||||
"base_used": round(base, 2),
|
||||
"pension": pension,
|
||||
"medical": medical,
|
||||
"unemployment": unemployment,
|
||||
"personal_total": personal_total,
|
||||
"estimated": True,
|
||||
}
|
||||
|
||||
|
||||
def _estimate_housing_fund(base_salary: float, region: str = "default") -> dict[str, Any]:
|
||||
"""按费率估算公积金个人部分。"""
|
||||
rate = float(get_config_value("housing_fund_rate", region) or 0.07)
|
||||
base_min = float(get_config_value("housing_fund_base_min", region) or 2500)
|
||||
base_max = float(get_config_value("housing_fund_base_max", region) or 30000)
|
||||
|
||||
base = _clamp_base(base_salary, base_min, base_max)
|
||||
personal = round(base * rate, 2)
|
||||
|
||||
return {
|
||||
"base_used": round(base, 2),
|
||||
"personal_rate": rate,
|
||||
"personal": personal,
|
||||
"estimated": True,
|
||||
}
|
||||
|
||||
|
||||
def calculate_payslip(
|
||||
*,
|
||||
base_salary: float = 0.0,
|
||||
performance: float = 0.0,
|
||||
full_attendance: float = 0.0,
|
||||
meal_allowance: float = 0.0,
|
||||
transport_allowance: float = 0.0,
|
||||
overtime_pay: float = 0.0,
|
||||
other_gross: float = 0.0,
|
||||
# 扣除项（可选，None 表示缺值→估算）
|
||||
social_personal: Optional[float] = None,
|
||||
housing_fund_personal: Optional[float] = None,
|
||||
tax: Optional[float] = None,
|
||||
leave_deduction: float = 0.0,
|
||||
other_deduction: float = 0.0,
|
||||
period: str = "",
|
||||
reported_net: Optional[float] = None,
|
||||
raw_payload: str = "",
|
||||
region: str = "default",
|
||||
) -> dict[str, Any]:
|
||||
"""工资条核算入口。
|
||||
|
||||
缺扣除项时按费率估算；估算项标 estimated=True，note 附"仅供参考"。
|
||||
落库到 payslip_snapshots，返回结构化 JSON。
|
||||
"""
|
||||
log = get_skill_logger()
|
||||
log.info(
|
||||
"payslip_calculate_start period=%s base=%s reported_net=%s region=%s",
|
||||
period, base_salary, reported_net, region,
|
||||
)
|
||||
|
||||
# 确保 DB 已初始化（agent/CLI 都可能首次调用）
|
||||
init_db()
|
||||
|
||||
# 应发合计
|
||||
bonus_total = round(performance + full_attendance, 2)
|
||||
allowance_total = round(meal_allowance + transport_allowance, 2)
|
||||
gross_total = round(
|
||||
base_salary + performance + full_attendance
|
||||
+ meal_allowance + transport_allowance + overtime_pay + other_gross,
|
||||
2,
|
||||
)
|
||||
|
||||
# 扣除项：缺失则估算
|
||||
estimated = False
|
||||
social_detail: dict[str, Any]
|
||||
if social_personal is None:
|
||||
social_detail = _estimate_social(base_salary, region)
|
||||
estimated = True
|
||||
else:
|
||||
social_detail = {"personal_total": round(float(social_personal), 2), "estimated": False}
|
||||
|
||||
housing_detail: dict[str, Any]
|
||||
if housing_fund_personal is None:
|
||||
housing_detail = _estimate_housing_fund(base_salary, region)
|
||||
estimated = True
|
||||
else:
|
||||
housing_detail = {"personal": round(float(housing_fund_personal), 2), "estimated": False}
|
||||
|
||||
# 个税：缺失则按累计预扣估算
|
||||
tax_detail: dict[str, Any]
|
||||
if tax is None:
|
||||
social_for_tax = float(social_detail.get("personal_total", 0))
|
||||
housing_for_tax = float(housing_detail.get("personal", 0))
|
||||
tax_result = compute_cumulative_tax(
|
||||
current_gross=gross_total,
|
||||
period=period or "1970-01",
|
||||
current_social=social_for_tax,
|
||||
current_housing_fund=housing_for_tax,
|
||||
region=region,
|
||||
)
|
||||
tax_detail = {
|
||||
"actual": tax_result["actual_tax"],
|
||||
"cumulative_taxable": tax_result["cumulative_taxable"],
|
||||
"brackets_used": tax_result["brackets_used"],
|
||||
"has_history": tax_result["has_history"],
|
||||
"estimated": True,
|
||||
"note": tax_result["note"],
|
||||
}
|
||||
estimated = True
|
||||
else:
|
||||
tax_detail = {"actual": round(float(tax), 2), "estimated": False}
|
||||
|
||||
social_total = float(social_detail.get("personal_total", 0))
|
||||
housing_total = float(housing_detail.get("personal", 0))
|
||||
tax_total = float(tax_detail.get("actual", 0))
|
||||
leave_total = float(leave_deduction)
|
||||
other_ded_total = float(other_deduction)
|
||||
|
||||
deduction_total = round(
|
||||
social_total + housing_total + tax_total + leave_total + other_ded_total, 2
|
||||
)
|
||||
net_salary = round(gross_total - deduction_total, 2)
|
||||
|
||||
# 核对
|
||||
check: dict[str, Any] = {"reported": None, "calculated": net_salary, "match": None, "diff": None}
|
||||
if reported_net is not None:
|
||||
reported_net = round(float(reported_net), 2)
|
||||
diff = round(reported_net - net_salary, 2)
|
||||
check = {
|
||||
"reported": reported_net,
|
||||
"calculated": net_salary,
|
||||
"match": abs(diff) < 0.01,
|
||||
"diff": diff,
|
||||
}
|
||||
|
||||
# 完整明细（供历史查询与个税累计）
|
||||
detail = {
|
||||
"gross": {
|
||||
"base_salary": base_salary,
|
||||
"performance": performance,
|
||||
"full_attendance": full_attendance,
|
||||
"meal_allowance": meal_allowance,
|
||||
"transport_allowance": transport_allowance,
|
||||
"overtime_pay": overtime_pay,
|
||||
"other_gross": other_gross,
|
||||
"bonus_total": bonus_total,
|
||||
"allowance_total": allowance_total,
|
||||
"total": gross_total,
|
||||
},
|
||||
"deduction": {
|
||||
"social": social_detail,
|
||||
"housing_fund": housing_detail,
|
||||
"tax": tax_detail,
|
||||
"leave": leave_total,
|
||||
"other": other_ded_total,
|
||||
"total": deduction_total,
|
||||
},
|
||||
"net": net_salary,
|
||||
"check": check,
|
||||
"region": region,
|
||||
}
|
||||
|
||||
estimates = []
|
||||
if estimated:
|
||||
notes = []
|
||||
if social_detail.get("estimated"):
|
||||
estimates.append({"item": "社保个人", "value": social_total, "note": "按费率估算，仅供参考"})
|
||||
if housing_detail.get("estimated"):
|
||||
estimates.append({"item": "公积金个人", "value": housing_total, "note": "按费率估算，仅供参考"})
|
||||
if tax_detail.get("estimated"):
|
||||
estimates.append({"item": "个税", "value": tax_total, "note": tax_detail.get("note", "仅供参考")})
|
||||
if not estimates:
|
||||
notes.append("所有扣除项均已由用户给定，无估算")
|
||||
else:
|
||||
estimates.append({"item": "无估算", "value": 0, "note": "所有扣除项均由用户给定"})
|
||||
|
||||
# 落库
|
||||
snapshot_date = int(time.time())
|
||||
conn = get_conn()
|
||||
snapshot_id = None
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
cur.execute(
|
||||
"""
|
||||
INSERT INTO payslip_snapshots (
|
||||
snapshot_date, period, base_salary,
|
||||
gross_total, deduction_total, net_salary,
|
||||
reported_net, check_match, check_diff,
|
||||
detail_json, raw_payload
|
||||
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
""",
|
||||
(
|
||||
snapshot_date, period or None, base_salary,
|
||||
gross_total, deduction_total, net_salary,
|
||||
reported_net,
|
||||
int(check["match"]) if check["match"] is not None else None,
|
||||
check["diff"],
|
||||
json.dumps(detail, ensure_ascii=False),
|
||||
raw_payload or None,
|
||||
),
|
||||
)
|
||||
snapshot_id = cur.lastrowid
|
||||
conn.commit()
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
log.info(
|
||||
"payslip_calculate_done period=%s gross=%s deduction=%s net=%s match=%s snapshot_id=%s",
|
||||
period, gross_total, deduction_total, net_salary, check["match"], snapshot_id,
|
||||
)
|
||||
|
||||
return {
|
||||
"ok": True,
|
||||
"skill": SKILL_SLUG,
|
||||
"period": period,
|
||||
"gross": detail["gross"],
|
||||
"deduction": detail["deduction"],
|
||||
"net": net_salary,
|
||||
"check": check,
|
||||
"estimates": estimates,
|
||||
"snapshot_id": snapshot_id,
|
||||
}
|
||||
|
||||
|
||||
def calculate_payslip_simple(
|
||||
*,
|
||||
base_salary: float,
|
||||
period: str,
|
||||
reported_net: Optional[float] = None,
|
||||
region: str = "default",
|
||||
) -> dict[str, Any]:
|
||||
"""快速估算：仅基本工资+period，按费率估全部扣除项。"""
|
||||
return calculate_payslip(
|
||||
base_salary=base_salary,
|
||||
period=period,
|
||||
reported_net=reported_net,
|
||||
region=region,
|
||||
)
|
||||
|
||||
|
||||
def list_snapshots(period: str | None = None, limit: int = 50) -> list[dict[str, Any]]:
|
||||
"""列出解析历史（供数据管理 / CLI 查看）。"""
|
||||
conn = get_conn()
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
if period:
|
||||
cur.execute(
|
||||
"""
|
||||
SELECT id, snapshot_date, period, base_salary, gross_total,
|
||||
deduction_total, net_salary, reported_net, check_match, check_diff
|
||||
FROM payslip_snapshots WHERE period=?
|
||||
ORDER BY snapshot_date DESC LIMIT ?
|
||||
""",
|
||||
(period, limit),
|
||||
)
|
||||
else:
|
||||
cur.execute(
|
||||
"""
|
||||
SELECT id, snapshot_date, period, base_salary, gross_total,
|
||||
deduction_total, net_salary, reported_net, check_match, check_diff
|
||||
FROM payslip_snapshots
|
||||
ORDER BY snapshot_date DESC LIMIT ?
|
||||
""",
|
||||
(limit,),
|
||||
)
|
||||
rows = cur.fetchall()
|
||||
return [
|
||||
{
|
||||
"id": r[0],
|
||||
"snapshot_date": r[1],
|
||||
"period": r[2],
|
||||
"base_salary": r[3],
|
||||
"gross_total": r[4],
|
||||
"deduction_total": r[5],
|
||||
"net_salary": r[6],
|
||||
"reported_net": r[7],
|
||||
"check_match": r[8],
|
||||
"check_diff": r[9],
|
||||
}
|
||||
for r in rows
|
||||
]
|
||||
finally:
|
||||
conn.close()
|
||||
57
scripts/service/sibling_bridge.py
Normal file
57
scripts/service/sibling_bridge.py
Normal file
@@ -0,0 +1,57 @@
|
||||
"""兄弟技能 CLI 调用工具。
|
||||
|
||||
通过子进程调用同级其他 skill 的 main.py，并解析 JSON 输出。
|
||||
具体调用哪些兄弟技能，由复制后的业务 skill 在 service 层按需决定。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
from typing import Any, Dict, List, Optional
|
||||
|
||||
from util.logging_config import subprocess_env_with_trace
|
||||
from util.runtime_paths import get_skills_root
|
||||
|
||||
|
||||
def call_sibling_json(skill_slug: str, args: List[str]) -> Optional[Dict[str, Any]]:
|
||||
"""通用兄弟技能调用器。
|
||||
|
||||
Args:
|
||||
skill_slug: 兄弟技能的 slug（即同级目录名）。
|
||||
args: 传给 main.py 的命令行参数列表。
|
||||
|
||||
Returns:
|
||||
若兄弟技能输出可解析的 JSON 对象则返回 dict；否则返回 None。
|
||||
"""
|
||||
script_path = os.path.join(get_skills_root(), skill_slug, "scripts", "main.py")
|
||||
if not os.path.isfile(script_path):
|
||||
return None
|
||||
proc = subprocess.run(
|
||||
[sys.executable, script_path, *args],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
encoding="utf-8",
|
||||
errors="replace",
|
||||
env=subprocess_env_with_trace(),
|
||||
)
|
||||
raw = (proc.stdout or "").strip()
|
||||
if not raw or raw.startswith("ERROR"):
|
||||
return None
|
||||
try:
|
||||
data = json.loads(raw)
|
||||
except json.JSONDecodeError:
|
||||
return None
|
||||
return data if isinstance(data, dict) else None
|
||||
|
||||
|
||||
def get_sibling_main_path(skill_slug: str) -> str:
|
||||
"""获取兄弟技能的 main.py 绝对路径。
|
||||
|
||||
使用示例（在 task_service.py 中）：
|
||||
from service.sibling_bridge import get_sibling_main_path, call_sibling_json
|
||||
result = call_sibling_json("account-manager", ["list", "--limit", "10"])
|
||||
"""
|
||||
return os.path.join(get_skills_root(), skill_slug, "scripts", "main.py")
|
||||
84
scripts/service/task_run_support.py
Normal file
84
scripts/service/task_run_support.py
Normal file
@@ -0,0 +1,84 @@
|
||||
"""任务运行辅助：录屏信息组装与 CLI 输出（通用模板，无业务逻辑）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any, Dict, Optional
|
||||
|
||||
|
||||
def build_video_info(
|
||||
video_summary: dict[str, Any],
|
||||
compose_context_before: Optional[dict[str, Any]] = None,
|
||||
compose_context_after: Optional[dict[str, Any]] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""将 RpaVideoSession.summary() 转为 finish() / CLI 可用的 video 块。"""
|
||||
return {
|
||||
"enabled": video_summary.get("enabled", False),
|
||||
"path": video_summary.get("path"),
|
||||
"capture_path": video_summary.get("capture_path"),
|
||||
"record_log_path": video_summary.get("record_log_path"),
|
||||
"warnings": list(video_summary.get("warnings") or []),
|
||||
"voiceover_path": video_summary.get("voiceover_path"),
|
||||
"music_path": video_summary.get("music_path"),
|
||||
"audio_warnings": list(video_summary.get("audio_warnings") or []),
|
||||
"compose_context": {
|
||||
**(compose_context_before or {}),
|
||||
"after_compose": compose_context_after or {},
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def merge_video_into_result_summary(
|
||||
payload: dict[str, Any],
|
||||
video_info: Optional[dict[str, Any]],
|
||||
) -> dict[str, Any]:
|
||||
"""把 video artifact 字段写入 finish() 结果对象（video / video_path 等）。"""
|
||||
if not video_info:
|
||||
return payload
|
||||
payload = dict(payload)
|
||||
payload["video"] = video_info
|
||||
payload["video_path"] = video_info.get("path")
|
||||
payload["raw_video"] = video_info.get("capture_path")
|
||||
payload["video_log"] = video_info.get("record_log_path")
|
||||
payload["video_warnings"] = list(video_info.get("warnings") or [])
|
||||
payload["voiceover_path"] = video_info.get("voiceover_path")
|
||||
payload["music_path"] = video_info.get("music_path")
|
||||
payload["audio_warnings"] = list(video_info.get("audio_warnings") or [])
|
||||
return payload
|
||||
|
||||
|
||||
def _print_video_summary(video_block: Optional[dict[str, Any]]) -> None:
|
||||
"""任务完成后在 CLI 打印录屏路径、日志与诊断信息。"""
|
||||
if not isinstance(video_block, dict) or not video_block.get("enabled"):
|
||||
return
|
||||
record_log = video_block.get("record_log_path")
|
||||
if record_log:
|
||||
print(f"录屏日志：{record_log}")
|
||||
path = video_block.get("path")
|
||||
if path:
|
||||
print(f"录屏路径：{path}")
|
||||
else:
|
||||
print("录屏路径：未生成")
|
||||
warnings = video_block.get("warnings") or []
|
||||
if warnings:
|
||||
print(f"视频诊断：{'; '.join(str(w) for w in warnings)}")
|
||||
capture = video_block.get("capture_path")
|
||||
if capture:
|
||||
print(f"原始录屏路径：{capture}")
|
||||
voiceover = video_block.get("voiceover_path")
|
||||
if voiceover:
|
||||
print(f"旁白路径：{voiceover}")
|
||||
music = video_block.get("music_path")
|
||||
if music:
|
||||
print(f"背景音乐：{music}")
|
||||
audio_warnings = video_block.get("audio_warnings") or []
|
||||
if audio_warnings:
|
||||
print(f"音频诊断：{'; '.join(str(w) for w in audio_warnings)}")
|
||||
compose_ctx = video_block.get("compose_context")
|
||||
if isinstance(compose_ctx, dict):
|
||||
print(
|
||||
"视频合成上下文："
|
||||
f"media_assets_root={compose_ctx.get('media_assets_root', '')}; "
|
||||
f"ffmpeg_path={compose_ctx.get('ffmpeg_path', '')}; "
|
||||
f"background_music_issue={compose_ctx.get('background_music_issue') or ''}; "
|
||||
f"background_music_sample_path={compose_ctx.get('background_music_sample_path', '')}"
|
||||
)
|
||||
387
scripts/service/task_service.py
Normal file
387
scripts/service/task_service.py
Normal file
@@ -0,0 +1,387 @@
|
||||
"""任务编排模板。
|
||||
|
||||
编排层：job_context / emit / checkpoint / finish、鉴权与错误转换。
|
||||
过程看统一文件日志；进度/终态看任务中心；业务结果写入业务表（有才建）。
|
||||
领域业务请放在 ``service/<domain>_service.py``，由本模块调用；多入口（CLI/Action/cron）复用同一内核。
|
||||
复制后在 cmd_run（或 cmd_sync_*）中接线到真实 domain service，勿按 toolbar/cron/agent 分叉业务。
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import json
|
||||
import os
|
||||
import uuid
|
||||
from typing import Any, Optional
|
||||
|
||||
from jiangchang_skill_core import collect_runtime_diagnostics, config, format_runtime_health_lines
|
||||
from jiangchang_skill_core.activity import JobStopped, emit, finish, job_context
|
||||
|
||||
from jiangchang_skill_core.rpa.video_session import RpaVideoSession
|
||||
from service.entitlement_service import check_entitlement
|
||||
from service.task_run_support import (
|
||||
_print_video_summary,
|
||||
build_video_info,
|
||||
merge_video_into_result_summary,
|
||||
)
|
||||
from util.constants import LOG_LOGGER_NAME, PLATFORM_KIT_MIN_VERSION, SKILL_SLUG, SKILL_VERSION
|
||||
from util.logging_config import get_skill_logger, setup_skill_logging
|
||||
from util.runtime_paths import get_db_path, get_skill_data_dir, get_skill_root
|
||||
from db.connection import init_db
|
||||
|
||||
|
||||
def _get_task_logger():
|
||||
try:
|
||||
return get_skill_logger()
|
||||
except RuntimeError:
|
||||
setup_skill_logging(SKILL_SLUG, LOG_LOGGER_NAME)
|
||||
return get_skill_logger()
|
||||
|
||||
|
||||
async def _run_template_demo(target: Optional[str], input_id: Optional[str]) -> tuple[int, dict[str, Any]]:
|
||||
"""最小 RpaVideoSession 示范：不启动浏览器、不执行业务，仅演示录屏包裹范式。"""
|
||||
batch_id = uuid.uuid4().hex[:12]
|
||||
data_dir = get_skill_data_dir()
|
||||
|
||||
async with RpaVideoSession(
|
||||
skill_slug=SKILL_SLUG,
|
||||
skill_data_dir=data_dir,
|
||||
batch_id=batch_id,
|
||||
title="开始执行示例任务",
|
||||
closing_title="示例任务执行完成",
|
||||
) as video:
|
||||
video.add_step("准备执行示例任务")
|
||||
if target:
|
||||
video.add_step(f"接收目标参数：{target}")
|
||||
if input_id:
|
||||
video.add_step(f"接收输入标识：{input_id}")
|
||||
video.add_step("示例任务执行完成")
|
||||
|
||||
video_summary = video.summary()
|
||||
video_info = build_video_info(video_summary, {}, {})
|
||||
return 1, video_info
|
||||
|
||||
|
||||
def cmd_run(target: Optional[str] = None, input_id: Optional[str] = None) -> int:
|
||||
"""通用任务执行入口模板。复制后请实现真实业务逻辑。"""
|
||||
log = _get_task_logger()
|
||||
task_type = "demo"
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info(
|
||||
"task_start task_type=%s target_id=%s input_id=%s stage=run",
|
||||
task_type,
|
||||
target,
|
||||
input_id,
|
||||
)
|
||||
emit("开始处理任务", skill=SKILL_SLUG, stage="run")
|
||||
try:
|
||||
ok, reason = check_entitlement(SKILL_SLUG)
|
||||
if not ok:
|
||||
log.warning(
|
||||
"entitlement_failed task_type=%s stage=auth error_code=ENTITLEMENT_DENIED",
|
||||
task_type,
|
||||
)
|
||||
emit("鉴权失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="auth")
|
||||
finish(
|
||||
status="failed",
|
||||
message=reason,
|
||||
skill=SKILL_SLUG,
|
||||
error_code="ENTITLEMENT_DENIED",
|
||||
stage="auth",
|
||||
)
|
||||
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
|
||||
return 1
|
||||
|
||||
log.info("entitlement_ok task_type=%s stage=auth", task_type)
|
||||
log.info("rpa_start stage=demo_prepare task_type=%s", task_type)
|
||||
log.info("task_run_demo_start target_id=%s input_id=%s stage=demo_prepare", target, input_id)
|
||||
rc, video_info = asyncio.run(_run_template_demo(target, input_id))
|
||||
log.info("rpa_done stage=demo_prepare status=ok")
|
||||
log.info(
|
||||
"task_run_demo_done target_id=%s input_id=%s stage=demo_finish status=failed",
|
||||
target,
|
||||
input_id,
|
||||
)
|
||||
_print_video_summary(video_info)
|
||||
|
||||
summary_payload = merge_video_into_result_summary(
|
||||
{
|
||||
"template_demo": True,
|
||||
"target": target,
|
||||
"input_id": input_id,
|
||||
},
|
||||
video_info,
|
||||
)
|
||||
|
||||
log.warning(
|
||||
"task_failed task_type=%s stage=demo_finish error_code=TEMPLATE_STUB",
|
||||
task_type,
|
||||
)
|
||||
finish(
|
||||
status="failed",
|
||||
message="模板仓库未实现真实业务",
|
||||
skill=SKILL_SLUG,
|
||||
error_code="TEMPLATE_STUB",
|
||||
**summary_payload,
|
||||
)
|
||||
print("ERROR:TEMPLATE_STUB 这是模板仓库，请复制后在 scripts/service/task_service.py 中实现 cmd_run 的真实业务逻辑。")
|
||||
return rc
|
||||
except JobStopped:
|
||||
raise
|
||||
except Exception:
|
||||
log.exception(
|
||||
"task_failed task_type=%s target_id=%s input_id=%s",
|
||||
task_type,
|
||||
target,
|
||||
input_id,
|
||||
)
|
||||
emit("任务失败，已记录诊断信息", type="warn", skill=SKILL_SLUG, stage="run")
|
||||
finish(
|
||||
status="failed",
|
||||
message="任务执行异常，详见统一日志",
|
||||
skill=SKILL_SLUG,
|
||||
stage="run",
|
||||
)
|
||||
return 1
|
||||
|
||||
|
||||
def cmd_config_path() -> int:
|
||||
example_path = os.path.join(get_skill_root(), ".env.example")
|
||||
env_path = config.get_env_file_path() or ""
|
||||
print(
|
||||
json.dumps(
|
||||
{
|
||||
"skill": SKILL_SLUG,
|
||||
"env_path": env_path,
|
||||
"example_path": os.path.abspath(example_path),
|
||||
},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_health() -> int:
|
||||
runtime = collect_runtime_diagnostics(
|
||||
skill_slug=SKILL_SLUG,
|
||||
platform_kit_min_version=PLATFORM_KIT_MIN_VERSION,
|
||||
skill_root=get_skill_root(),
|
||||
)
|
||||
example_path = os.path.join(get_skill_root(), ".env.example")
|
||||
env_path = config.get_env_file_path() or ""
|
||||
env_exists = bool(env_path and os.path.isfile(env_path))
|
||||
|
||||
health_status = "failed" if runtime.has_fatal_issues else "ok"
|
||||
lines = [
|
||||
f"{SKILL_SLUG} health: {health_status}",
|
||||
*format_runtime_health_lines(runtime),
|
||||
f"env_path: {env_path}",
|
||||
f"env_exists: {env_exists}",
|
||||
f"example_path: {os.path.abspath(example_path)}",
|
||||
]
|
||||
for line in lines:
|
||||
print(line)
|
||||
return 1 if runtime.has_fatal_issues else 0
|
||||
|
||||
|
||||
def cmd_version() -> int:
|
||||
print(json.dumps({"version": SKILL_VERSION, "skill": SKILL_SLUG}, ensure_ascii=False))
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_init_db() -> int:
|
||||
"""幂等创建/迁移本地 SQLite 与数据管理元数据（宿主 install/upgrade 可调用）。"""
|
||||
try:
|
||||
init_db()
|
||||
except Exception as exc: # noqa: BLE001 — CLI 边界，统一成可机读失败
|
||||
print(
|
||||
json.dumps(
|
||||
{"ok": False, "skill": SKILL_SLUG, "error": str(exc)},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
)
|
||||
return 1
|
||||
print(
|
||||
json.dumps(
|
||||
{
|
||||
"ok": True,
|
||||
"skill": SKILL_SLUG,
|
||||
"db_path": get_db_path(),
|
||||
},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
def _parse_float_or_none(value: Optional[str]) -> Optional[float]:
|
||||
if value is None or value == "":
|
||||
return None
|
||||
try:
|
||||
return float(value)
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def cmd_calculate_full(
|
||||
*,
|
||||
base_salary: float = 0.0,
|
||||
performance: float = 0.0,
|
||||
full_attendance: float = 0.0,
|
||||
meal_allowance: float = 0.0,
|
||||
transport_allowance: float = 0.0,
|
||||
overtime_pay: float = 0.0,
|
||||
other_gross: float = 0.0,
|
||||
social_personal: Optional[float] = None,
|
||||
housing_fund_personal: Optional[float] = None,
|
||||
tax: Optional[float] = None,
|
||||
leave_deduction: float = 0.0,
|
||||
other_deduction: float = 0.0,
|
||||
period: str = "",
|
||||
reported_net: Optional[float] = None,
|
||||
raw_payload: str = "",
|
||||
region: str = "default",
|
||||
) -> int:
|
||||
"""精确核算：全字段核算，缺失项按费率估算。"""
|
||||
log = _get_task_logger()
|
||||
from service.payslip_service import calculate_payslip
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info("task_start task_type=calculate_full period=%s region=%s", period, region)
|
||||
emit("开始核算工资", skill=SKILL_SLUG, stage="calculate")
|
||||
try:
|
||||
ok, reason = check_entitlement(SKILL_SLUG)
|
||||
if not ok:
|
||||
log.warning("entitlement_failed task_type=calculate_full")
|
||||
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
|
||||
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
|
||||
return 1
|
||||
|
||||
result = calculate_payslip(
|
||||
base_salary=base_salary, performance=performance, full_attendance=full_attendance,
|
||||
meal_allowance=meal_allowance, transport_allowance=transport_allowance,
|
||||
overtime_pay=overtime_pay, other_gross=other_gross,
|
||||
social_personal=social_personal, housing_fund_personal=housing_fund_personal,
|
||||
tax=tax, leave_deduction=leave_deduction, other_deduction=other_deduction,
|
||||
period=period, reported_net=reported_net, raw_payload=raw_payload, region=region,
|
||||
)
|
||||
print(json.dumps(result, ensure_ascii=False))
|
||||
finish(
|
||||
status="success",
|
||||
message=f"应发 {result['gross']['total']}，扣除 {result['deduction']['total']}，实发 {result['net']}",
|
||||
skill=SKILL_SLUG, stage="calculate",
|
||||
)
|
||||
return 0
|
||||
except JobStopped:
|
||||
raise
|
||||
except Exception:
|
||||
log.exception("task_failed task_type=calculate_full")
|
||||
emit("核算失败", type="warn", skill=SKILL_SLUG, stage="calculate")
|
||||
finish(status="failed", message="核算执行异常", skill=SKILL_SLUG, stage="calculate")
|
||||
return 1
|
||||
|
||||
|
||||
def cmd_calculate_simple(
|
||||
*,
|
||||
base_salary: float,
|
||||
period: str,
|
||||
reported_net: Optional[float] = None,
|
||||
region: str = "default",
|
||||
) -> int:
|
||||
"""快速估算：仅基本工资+period，按费率估全部扣除。"""
|
||||
log = _get_task_logger()
|
||||
from service.payslip_service import calculate_payslip_simple
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info("task_start task_type=calculate_simple period=%s base=%s", period, base_salary)
|
||||
emit("开始估算工资", skill=SKILL_SLUG, stage="calculate_simple")
|
||||
try:
|
||||
ok, reason = check_entitlement(SKILL_SLUG)
|
||||
if not ok:
|
||||
log.warning("entitlement_failed task_type=calculate_simple")
|
||||
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
|
||||
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
|
||||
return 1
|
||||
|
||||
result = calculate_payslip_simple(
|
||||
base_salary=base_salary, period=period, reported_net=reported_net, region=region,
|
||||
)
|
||||
print(json.dumps(result, ensure_ascii=False))
|
||||
finish(
|
||||
status="success",
|
||||
message=f"估算实发 {result['net']}（仅供参考）",
|
||||
skill=SKILL_SLUG, stage="calculate_simple",
|
||||
)
|
||||
return 0
|
||||
except JobStopped:
|
||||
raise
|
||||
except Exception:
|
||||
log.exception("task_failed task_type=calculate_simple")
|
||||
emit("估算失败", type="warn", skill=SKILL_SLUG, stage="calculate_simple")
|
||||
finish(status="failed", message="估算执行异常", skill=SKILL_SLUG, stage="calculate_simple")
|
||||
return 1
|
||||
|
||||
|
||||
def cmd_explain(term: str) -> int:
|
||||
"""名词解释。"""
|
||||
log = _get_task_logger()
|
||||
from service.glossary_service import explain_term
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info("task_start task_type=explain term=%s", term)
|
||||
try:
|
||||
result = explain_term(term)
|
||||
print(json.dumps(result, ensure_ascii=False))
|
||||
return 0
|
||||
except Exception:
|
||||
log.exception("task_failed task_type=explain")
|
||||
return 1
|
||||
|
||||
|
||||
def cmd_view_config(region: Optional[str] = None) -> int:
|
||||
"""查看费率配置。"""
|
||||
log = _get_task_logger()
|
||||
from service.config_service import list_all_config
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info("task_start task_type=view_config region=%s", region)
|
||||
try:
|
||||
result = list_all_config(region)
|
||||
print(json.dumps({"ok": True, "skill": SKILL_SLUG, "count": len(result), "items": result}, ensure_ascii=False))
|
||||
return 0
|
||||
except Exception:
|
||||
log.exception("task_failed task_type=view_config")
|
||||
return 1
|
||||
|
||||
|
||||
def cmd_edit_config(config_key: str, region: str, config_value: float) -> int:
|
||||
"""编辑费率配置（仅管理员）。"""
|
||||
log = _get_task_logger()
|
||||
from service.config_service import update_config_value
|
||||
|
||||
with job_context(skill=SKILL_SLUG):
|
||||
log.info("task_start task_type=edit_config key=%s region=%s", config_key, region)
|
||||
emit("开始更新费率", skill=SKILL_SLUG, stage="edit_config")
|
||||
try:
|
||||
ok, reason = check_entitlement(SKILL_SLUG)
|
||||
if not ok:
|
||||
log.warning("entitlement_failed task_type=edit_config")
|
||||
finish(status="failed", message=reason, skill=SKILL_SLUG, error_code="ENTITLEMENT_DENIED", stage="auth")
|
||||
print(f"ERROR:ENTITLEMENT_DENIED {reason}")
|
||||
return 1
|
||||
|
||||
result = update_config_value(config_key, region, config_value)
|
||||
print(json.dumps(result, ensure_ascii=False))
|
||||
if result.get("ok"):
|
||||
finish(status="success", message=f"已更新 {config_key}", skill=SKILL_SLUG, stage="edit_config")
|
||||
return 0
|
||||
else:
|
||||
finish(status="failed", message=result.get("error", ""), skill=SKILL_SLUG, stage="edit_config")
|
||||
return 1
|
||||
except JobStopped:
|
||||
raise
|
||||
except Exception:
|
||||
log.exception("task_failed task_type=edit_config")
|
||||
finish(status="failed", message="更新执行异常", skill=SKILL_SLUG, stage="edit_config")
|
||||
return 1
|
||||
161
scripts/service/tax_service.py
Normal file
161
scripts/service/tax_service.py
Normal file
@@ -0,0 +1,161 @@
|
||||
"""个税累计预扣计算服务。
|
||||
|
||||
按"累计预扣法"计算当月个税：
|
||||
累计预扣预缴应纳税所得额 = 累计收入 - 累计减除费用 - 累计专项扣除 - 累计专项附加扣除 - 累计依法确定的其他扣除
|
||||
当月应预扣预缴税额 = (累计预扣预缴应纳税所得额 × 预扣率 - 速算扣除数) - 已预扣预缴税额
|
||||
|
||||
简化假设：
|
||||
- 专项附加扣除与其他扣除暂不计入（数据不可得）
|
||||
- 累计减除费用 = 5000 × 当年至本月份数
|
||||
- 累计专项扣除 = 累计社保+公积金个人部分（从历史 snapshots 读取）
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from typing import Any
|
||||
|
||||
from service.config_service import get_config_value, get_tax_brackets
|
||||
from db.connection import get_conn
|
||||
from util.logging_config import get_skill_logger
|
||||
|
||||
log = get_skill_logger()
|
||||
|
||||
|
||||
def _month_index(period: str) -> int:
|
||||
"""从 'YYYY-MM' 提取月份数（1-12）。"""
|
||||
try:
|
||||
return int(period.split("-")[1])
|
||||
except (ValueError, IndexError):
|
||||
return 1
|
||||
|
||||
|
||||
def _year_of_period(period: str) -> str:
|
||||
"""从 'YYYY-MM' 提取年份。"""
|
||||
try:
|
||||
return period.split("-")[0]
|
||||
except (ValueError, IndexError):
|
||||
return "1970"
|
||||
|
||||
|
||||
def get_cumulative_deduction_before(period: str) -> dict[str, float]:
|
||||
"""读取同一年的历史 snapshots，累计社保/公积金个人部分。
|
||||
|
||||
period 之前的同一年 snapshots（按 period 字符串排序 < 当前 period）。
|
||||
返回 {social_cum, housing_fund_cum, tax_cum}。
|
||||
"""
|
||||
year = _year_of_period(period)
|
||||
conn = get_conn()
|
||||
try:
|
||||
cur = conn.cursor()
|
||||
cur.execute(
|
||||
"""
|
||||
SELECT detail_json FROM payslip_snapshots
|
||||
WHERE period LIKE ? AND period < ?
|
||||
ORDER BY period ASC
|
||||
""",
|
||||
(f"{year}-%", period),
|
||||
)
|
||||
import json
|
||||
social_cum = 0.0
|
||||
housing_fund_cum = 0.0
|
||||
tax_cum = 0.0
|
||||
for (detail_str,) in cur.fetchall():
|
||||
if not detail_str:
|
||||
continue
|
||||
try:
|
||||
detail = json.loads(detail_str)
|
||||
except (json.JSONDecodeError, TypeError):
|
||||
continue
|
||||
ded = detail.get("deduction", {}) if isinstance(detail, dict) else {}
|
||||
social_cum += float(ded.get("social", {}).get("personal_total", 0) or 0)
|
||||
housing_fund_cum += float(ded.get("housing_fund", {}).get("personal", 0) or 0)
|
||||
tax_cum += float(ded.get("tax", {}).get("actual", 0) or 0)
|
||||
return {"social_cum": social_cum, "housing_fund_cum": housing_fund_cum, "tax_cum": tax_cum}
|
||||
finally:
|
||||
conn.close()
|
||||
|
||||
|
||||
def compute_cumulative_tax(
|
||||
*,
|
||||
current_gross: float,
|
||||
period: str,
|
||||
current_social: float,
|
||||
current_housing_fund: float,
|
||||
region: str = "default",
|
||||
) -> dict[str, Any]:
|
||||
"""按累计预扣法计算当月个税。
|
||||
|
||||
返回 {
|
||||
actual_tax: float, # 本次应预扣个税
|
||||
cumulative_income: float,
|
||||
cumulative_deduction: float,
|
||||
cumulative_taxable: float,
|
||||
cumulative_tax: float, # 累计应预扣
|
||||
prior_tax_paid: float, # 之前已预扣
|
||||
brackets_used: dict, # 命中的税率档
|
||||
has_history: bool, # 是否有历史累计数据
|
||||
note: str,
|
||||
}
|
||||
"""
|
||||
log.info(
|
||||
"tax_compute_start period=%s gross=%s social=%s housing=%s region=%s",
|
||||
period, current_gross, current_social, current_housing_fund, region,
|
||||
)
|
||||
threshold = get_config_value("tax_threshold", region) or 5000
|
||||
brackets = get_tax_brackets(region)
|
||||
|
||||
month_idx = _month_index(period)
|
||||
cumulative_threshold = float(threshold) * month_idx
|
||||
|
||||
prior = get_cumulative_deduction_before(period)
|
||||
has_history = prior["social_cum"] > 0 or prior["tax_cum"] > 0
|
||||
|
||||
cumulative_income = current_gross + prior.get("income_cum", 0.0) if has_history else current_gross
|
||||
# 简化：累计专项扣除 = 累计社保+公积金个人
|
||||
cumulative_special_deduction = (
|
||||
prior["social_cum"] + prior["housing_fund_cum"]
|
||||
+ current_social + current_housing_fund
|
||||
)
|
||||
|
||||
cumulative_taxable = cumulative_income - cumulative_threshold - cumulative_special_deduction
|
||||
if cumulative_taxable < 0:
|
||||
cumulative_taxable = 0.0
|
||||
|
||||
cumulative_tax = 0.0
|
||||
bracket_hit = None
|
||||
if brackets and cumulative_taxable > 0:
|
||||
for bracket in brackets:
|
||||
upper = bracket.get("upper")
|
||||
rate = float(bracket.get("rate", 0))
|
||||
quick = float(bracket.get("quick_deduction", 0))
|
||||
if upper is None or cumulative_taxable <= float(upper):
|
||||
cumulative_tax = cumulative_taxable * rate - quick
|
||||
bracket_hit = bracket
|
||||
break
|
||||
if bracket_hit is None and brackets:
|
||||
bracket_hit = brackets[-1]
|
||||
rate = float(bracket_hit.get("rate", 0))
|
||||
quick = float(bracket_hit.get("quick_deduction", 0))
|
||||
cumulative_tax = cumulative_taxable * rate - quick
|
||||
|
||||
cumulative_tax = max(0.0, cumulative_tax)
|
||||
prior_tax_paid = prior["tax_cum"] if has_history else 0.0
|
||||
actual_tax = max(0.0, cumulative_tax - prior_tax_paid)
|
||||
|
||||
note = "仅供参考，非官方数据"
|
||||
if not has_history:
|
||||
note = "仅供参考（无累计历史数据，累计按本月单月计算），非官方数据"
|
||||
|
||||
return {
|
||||
"actual_tax": round(actual_tax, 2),
|
||||
"cumulative_income": round(cumulative_income, 2),
|
||||
"cumulative_threshold": round(cumulative_threshold, 2),
|
||||
"cumulative_special_deduction": round(cumulative_special_deduction, 2),
|
||||
"cumulative_taxable": round(cumulative_taxable, 2),
|
||||
"cumulative_tax": round(cumulative_tax, 2),
|
||||
"prior_tax_paid": round(prior_tax_paid, 2),
|
||||
"brackets_used": bracket_hit,
|
||||
"has_history": has_history,
|
||||
"note": note,
|
||||
}
|
||||
12
scripts/util/argparse_zh.py
Normal file
12
scripts/util/argparse_zh.py
Normal file
@@ -0,0 +1,12 @@
|
||||
"""argparse 中文错误说明。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
|
||||
|
||||
class ZhArgumentParser(argparse.ArgumentParser):
|
||||
def error(self, message: str) -> None:
|
||||
print(f"参数错误：{message}\n请执行：python main.py -h 查看帮助", file=sys.stderr)
|
||||
self.exit(2)
|
||||
19
scripts/util/config_bootstrap.py
Normal file
19
scripts/util/config_bootstrap.py
Normal file
@@ -0,0 +1,19 @@
|
||||
"""技能配置初始化：.env.example 落盘与用户 .env 缺失项合并。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
|
||||
from jiangchang_skill_core import config
|
||||
|
||||
from util.constants import SKILL_SLUG, SKILL_VERSION
|
||||
from util.runtime_paths import get_skill_root
|
||||
|
||||
|
||||
def bootstrap_skill_config() -> str:
|
||||
"""确保用户数据目录 .env 存在，并追加 .env.example 中的新配置项。"""
|
||||
example_path = os.path.join(get_skill_root(), ".env.example")
|
||||
env_path = config.ensure_env_file(SKILL_SLUG, example_path)
|
||||
comment = f"{SKILL_SLUG} v{SKILL_VERSION}" if SKILL_VERSION else None
|
||||
config.merge_missing_env_keys(example_path, env_path, comment_skill=comment)
|
||||
return env_path
|
||||
6
scripts/util/constants.py
Normal file
6
scripts/util/constants.py
Normal file
@@ -0,0 +1,6 @@
|
||||
"""技能标识、版本与平台公共库约束（复制后请修改 slug/version/logger）。"""
|
||||
|
||||
SKILL_SLUG = "query-payslip-default"
|
||||
SKILL_VERSION = "1.0.105"
|
||||
LOG_LOGGER_NAME = "openclaw.skill.query_payslip_default"
|
||||
PLATFORM_KIT_MIN_VERSION = "1.2.11"
|
||||
21
scripts/util/logging_config.py
Normal file
21
scripts/util/logging_config.py
Normal file
@@ -0,0 +1,21 @@
|
||||
"""Re-export unified logging (implementation: jiangchang_skill_core.unified_logging)."""
|
||||
|
||||
from jiangchang_skill_core.unified_logging import (
|
||||
attach_unified_file_handler,
|
||||
ensure_trace_for_process,
|
||||
get_skill_log_file_path,
|
||||
get_skill_logger,
|
||||
get_unified_logs_dir,
|
||||
setup_skill_logging,
|
||||
subprocess_env_with_trace,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"attach_unified_file_handler",
|
||||
"ensure_trace_for_process",
|
||||
"get_skill_log_file_path",
|
||||
"get_skill_logger",
|
||||
"get_unified_logs_dir",
|
||||
"setup_skill_logging",
|
||||
"subprocess_env_with_trace",
|
||||
]
|
||||
155
scripts/util/runtime_paths.py
Normal file
155
scripts/util/runtime_paths.py
Normal file
@@ -0,0 +1,155 @@
|
||||
"""数据根、技能目录、兄弟技能根路径与用户数据子目录解析。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
|
||||
from jiangchang_skill_core.runtime_env import get_data_root, get_sibling_skills_root, get_user_id
|
||||
|
||||
from util.constants import SKILL_SLUG
|
||||
|
||||
_SCRIPTS_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
# 用户可见的上行/下行目录（数据管理「输入/输出」文件浏览器）
|
||||
STANDARD_SUBDIR_INPUT = "input"
|
||||
STANDARD_SUBDIR_OUTPUT = "output"
|
||||
|
||||
# 宿主扫描的 HTML 报告页（数据管理侧栏 htmlPages，非 input/output 文件浏览器）
|
||||
STANDARD_SUBDIR_HTML = "html"
|
||||
|
||||
# 内部/可选目录（不上侧栏）
|
||||
STANDARD_SUBDIR_UPLOADS = "uploads"
|
||||
STANDARD_SUBDIR_CACHE = "cache"
|
||||
STANDARD_SUBDIR_TEMP = "temp"
|
||||
STANDARD_SUBDIR_RPA_ARTIFACTS = "rpa-artifacts"
|
||||
STANDARD_SUBDIR_VIDEOS = "videos"
|
||||
|
||||
CONFIG_KEY_INPUT_DIR = "SKILL_INPUT_DIR"
|
||||
CONFIG_KEY_OUTPUT_DIR = "SKILL_OUTPUT_DIR"
|
||||
CONFIG_KEY_UPLOAD_DIR = "SKILL_UPLOAD_DIR"
|
||||
CONFIG_KEY_CACHE_DIR = "SKILL_CACHE_DIR"
|
||||
CONFIG_KEY_TEMP_DIR = "SKILL_TEMP_DIR"
|
||||
|
||||
|
||||
def get_skill_root() -> str:
|
||||
return os.path.dirname(_SCRIPTS_DIR)
|
||||
|
||||
|
||||
def get_openclaw_root() -> str:
|
||||
return get_sibling_skills_root(_SCRIPTS_DIR)
|
||||
|
||||
|
||||
def get_skills_root() -> str:
|
||||
return get_sibling_skills_root(_SCRIPTS_DIR)
|
||||
|
||||
|
||||
def get_skill_data_dir() -> str:
|
||||
path = os.path.join(get_data_root(), get_user_id(), SKILL_SLUG)
|
||||
os.makedirs(path, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def get_db_path(filename: str | None = None) -> str:
|
||||
name = filename or f"{SKILL_SLUG}.db"
|
||||
return os.path.join(get_skill_data_dir(), name)
|
||||
|
||||
|
||||
def _normalize_subdir(value: str) -> str:
|
||||
cleaned = value.strip().strip("/\\")
|
||||
if not cleaned or cleaned.startswith(".."):
|
||||
raise ValueError(f"invalid skill data subdir: {value!r}")
|
||||
return cleaned.replace("/", os.sep).replace("\\", os.sep)
|
||||
|
||||
|
||||
def resolve_data_path(
|
||||
config_key: str | None,
|
||||
default_subdir: str,
|
||||
*,
|
||||
create: bool = True,
|
||||
) -> str:
|
||||
"""解析技能拥有路径：空配置 → 数据目录下 default_subdir；相对 → 相对数据目录；绝对 → 原样。"""
|
||||
from jiangchang_skill_core import config
|
||||
|
||||
base = get_skill_data_dir()
|
||||
raw = (config.get(config_key) or "").strip() if config_key else ""
|
||||
if not raw:
|
||||
path = os.path.join(base, _normalize_subdir(default_subdir))
|
||||
elif os.path.isabs(raw):
|
||||
path = os.path.abspath(os.path.expanduser(raw))
|
||||
else:
|
||||
path = os.path.join(base, _normalize_subdir(raw))
|
||||
|
||||
if create:
|
||||
os.makedirs(path, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def resolve_input_path(raw_path: str, *, create_parent: bool = False) -> str:
|
||||
"""解析 CLI 输入路径：绝对路径原样；相对路径相对 {skill_data_dir}/input/。"""
|
||||
text = (raw_path or "").strip()
|
||||
if not text:
|
||||
return text
|
||||
expanded = os.path.expanduser(text)
|
||||
if os.path.isabs(expanded):
|
||||
return os.path.abspath(expanded)
|
||||
input_dir = get_input_dir(create=create_parent)
|
||||
return os.path.abspath(os.path.join(input_dir, os.path.normpath(expanded)))
|
||||
|
||||
|
||||
def get_input_dir(*, create: bool = True) -> str:
|
||||
"""上行：用户/Agent 放入的待处理文件（清单、CSV、产品表等）。"""
|
||||
return resolve_data_path(CONFIG_KEY_INPUT_DIR, STANDARD_SUBDIR_INPUT, create=create)
|
||||
|
||||
|
||||
def get_output_dir(*, create: bool = True) -> str:
|
||||
"""下行：技能/宿主交给用户拿走的文件（视频、报表、导出 CSV 等）。"""
|
||||
return resolve_data_path(CONFIG_KEY_OUTPUT_DIR, STANDARD_SUBDIR_OUTPUT, create=create)
|
||||
|
||||
|
||||
def get_uploads_dir(*, create: bool = True) -> str:
|
||||
return resolve_data_path(CONFIG_KEY_UPLOAD_DIR, STANDARD_SUBDIR_UPLOADS, create=create)
|
||||
|
||||
|
||||
def get_cache_dir(*, create: bool = True) -> str:
|
||||
return resolve_data_path(CONFIG_KEY_CACHE_DIR, STANDARD_SUBDIR_CACHE, create=create)
|
||||
|
||||
|
||||
def get_temp_dir(*, create: bool = True) -> str:
|
||||
return resolve_data_path(CONFIG_KEY_TEMP_DIR, STANDARD_SUBDIR_TEMP, create=create)
|
||||
|
||||
|
||||
def get_rpa_artifacts_dir(batch_id: str, *, create: bool = True) -> str:
|
||||
batch = (batch_id or "").strip() or "default"
|
||||
path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_RPA_ARTIFACTS, batch)
|
||||
if create:
|
||||
os.makedirs(path, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def get_videos_dir(*, create: bool = True) -> str:
|
||||
path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_VIDEOS)
|
||||
if create:
|
||||
os.makedirs(path, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def get_html_dir(*, create: bool = True) -> str:
|
||||
"""HTML 报告页目录：宿主扫描 `{skill_data}/html/*.html`（一层、非递归）。"""
|
||||
path = os.path.join(get_skill_data_dir(), STANDARD_SUBDIR_HTML)
|
||||
if create:
|
||||
os.makedirs(path, exist_ok=True)
|
||||
return path
|
||||
|
||||
|
||||
def list_resolved_data_paths() -> dict[str, str]:
|
||||
"""供 health / config-path 输出已解析的数据子目录（不创建目录）。"""
|
||||
return {
|
||||
"skill_data_dir": get_skill_data_dir(),
|
||||
"input_dir": get_input_dir(create=False),
|
||||
"output_dir": get_output_dir(create=False),
|
||||
"html_dir": get_html_dir(create=False),
|
||||
"uploads_dir": get_uploads_dir(create=False),
|
||||
"cache_dir": get_cache_dir(create=False),
|
||||
"temp_dir": get_temp_dir(create=False),
|
||||
"videos_dir": get_videos_dir(create=False),
|
||||
}
|
||||
227
scripts/util/slug_naming.py
Normal file
227
scripts/util/slug_naming.py
Normal file
@@ -0,0 +1,227 @@
|
||||
"""技能 slug 语义校验（verb-noun-platform 规范，见 development/NAMING.md）。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
|
||||
_KEBAB_SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
|
||||
_MAX_SLUG_LENGTH = 48
|
||||
_MIN_SEGMENTS = 3
|
||||
_MAX_SEGMENTS = 5
|
||||
_MAX_NOUN_SEGMENTS = 3
|
||||
|
||||
_SKILL_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||||
_NAMING_DIR = os.path.join(_SKILL_ROOT, "assets", "naming")
|
||||
|
||||
_BUILTIN_VERBS = frozenset(
|
||||
{
|
||||
"scrape",
|
||||
"receive",
|
||||
"download",
|
||||
"export",
|
||||
"add",
|
||||
"fill",
|
||||
"enter",
|
||||
"bind",
|
||||
"withdraw",
|
||||
"reconcile",
|
||||
"verify",
|
||||
"submit",
|
||||
"query",
|
||||
"process",
|
||||
"reply",
|
||||
"generate",
|
||||
"draft",
|
||||
"review",
|
||||
"confirm",
|
||||
"track",
|
||||
"upload",
|
||||
"match",
|
||||
"triage",
|
||||
"ship",
|
||||
"reprice",
|
||||
}
|
||||
)
|
||||
_BUILTIN_PLATFORMS = frozenset(
|
||||
{
|
||||
"amazon",
|
||||
"shopee",
|
||||
"xinghang",
|
||||
"alibaba",
|
||||
"kingdee",
|
||||
"icbc",
|
||||
"pingpong",
|
||||
"worldfirst",
|
||||
"paypal",
|
||||
"lianlian",
|
||||
"single-window",
|
||||
"export-rebate",
|
||||
"etax",
|
||||
}
|
||||
)
|
||||
_BUILTIN_SCOPES = frozenset({"all", "batch", "multi", "default"})
|
||||
|
||||
LEGACY_EXEMPT_SLUGS: frozenset[str] = frozenset(
|
||||
{
|
||||
"account-manager",
|
||||
"skill-template",
|
||||
"query-payslip-default",
|
||||
"query_payslip_default",
|
||||
}
|
||||
)
|
||||
|
||||
|
||||
def load_wordlist(filename: str) -> frozenset[str]:
|
||||
"""从 assets/naming/{filename} 加载词表；文件不存在时 fallback 内置集合。"""
|
||||
fallbacks = {
|
||||
"verbs.txt": _BUILTIN_VERBS,
|
||||
"platforms.txt": _BUILTIN_PLATFORMS,
|
||||
"scopes.txt": _BUILTIN_SCOPES,
|
||||
}
|
||||
fallback = fallbacks.get(filename, frozenset())
|
||||
path = os.path.join(_NAMING_DIR, filename)
|
||||
if not os.path.isfile(path):
|
||||
return fallback
|
||||
words: set[str] = set()
|
||||
with open(path, encoding="utf-8") as f:
|
||||
for line in f:
|
||||
word = line.strip()
|
||||
if word and not word.startswith("#"):
|
||||
words.add(word)
|
||||
return frozenset(words) if words else fallback
|
||||
|
||||
|
||||
def parse_slug_segments(slug: str) -> list[str]:
|
||||
"""按 '-' 分割；非法字符由上层 kebab 校验处理。"""
|
||||
slug = slug.strip()
|
||||
if not slug:
|
||||
return []
|
||||
return slug.split("-")
|
||||
|
||||
|
||||
def _match_platform_suffix(
|
||||
segments: list[str],
|
||||
platforms: frozenset[str],
|
||||
) -> tuple[str, int] | None:
|
||||
"""返回 (platform_name, platform_part_count) 或 None。"""
|
||||
for platform in sorted(platforms, key=lambda item: (-item.count("-"), item)):
|
||||
parts = platform.split("-")
|
||||
part_count = len(parts)
|
||||
if len(segments) < part_count + 2:
|
||||
continue
|
||||
if segments[-part_count:] == parts:
|
||||
return platform, part_count
|
||||
return None
|
||||
|
||||
|
||||
def classify_slug_form(segments: list[str], *, slug: str = "") -> str:
|
||||
"""
|
||||
返回: 'legacy_exempt' | 'standard' | 'scope' | 'invalid'
|
||||
|
||||
- legacy_exempt: slug in LEGACY_EXEMPT_SLUGS
|
||||
- standard: 末段匹配 platforms, 首段 in verbs, 3<=len<=5
|
||||
- scope: 末段 in scopes, 首段 in verbs, 3<=len<=5
|
||||
- invalid: 其他
|
||||
"""
|
||||
if slug in LEGACY_EXEMPT_SLUGS:
|
||||
return "legacy_exempt"
|
||||
|
||||
if not segments or not (_MIN_SEGMENTS <= len(segments) <= _MAX_SEGMENTS):
|
||||
return "invalid"
|
||||
|
||||
verbs = load_wordlist("verbs.txt")
|
||||
platforms = load_wordlist("platforms.txt")
|
||||
scopes = load_wordlist("scopes.txt")
|
||||
|
||||
if segments[0] not in verbs:
|
||||
return "invalid"
|
||||
|
||||
if segments[-1] in scopes:
|
||||
return "scope"
|
||||
|
||||
if _match_platform_suffix(segments, platforms) is not None:
|
||||
return "standard"
|
||||
|
||||
return "invalid"
|
||||
|
||||
|
||||
def validate_slug_semantics(
|
||||
slug: str,
|
||||
*,
|
||||
strict: bool = True,
|
||||
) -> tuple[list[str], list[str]]:
|
||||
"""返回 (errors, warnings)。"""
|
||||
slug = slug.strip()
|
||||
if slug in LEGACY_EXEMPT_SLUGS:
|
||||
return [], []
|
||||
|
||||
errors: list[str] = []
|
||||
warnings: list[str] = []
|
||||
|
||||
if not _KEBAB_SLUG.fullmatch(slug):
|
||||
msg = f"slug 必须为 kebab-case（小写字母、数字、连字符）：{slug!r}"
|
||||
(errors if strict else warnings).append(msg)
|
||||
return errors, warnings
|
||||
|
||||
if len(slug) > _MAX_SLUG_LENGTH:
|
||||
msg = f"slug 长度不得超过 {_MAX_SLUG_LENGTH} 字符（当前 {len(slug)}）：{slug!r}"
|
||||
(errors if strict else warnings).append(msg)
|
||||
|
||||
segments = parse_slug_segments(slug)
|
||||
segment_count = len(segments)
|
||||
|
||||
if segment_count < _MIN_SEGMENTS:
|
||||
msg = (
|
||||
f"slug 段数应为 {_MIN_SEGMENTS}～{_MAX_SEGMENTS}（verb-noun-platform），"
|
||||
f"当前为 {segment_count} 段：{slug!r}；新技能禁止 2 段无平台形态（如 reconcile-finance）"
|
||||
)
|
||||
(errors if strict else warnings).append(msg)
|
||||
return errors, warnings
|
||||
|
||||
if segment_count > _MAX_SEGMENTS:
|
||||
msg = f"slug 段数不得超过 {_MAX_SEGMENTS}（当前 {segment_count}）：{slug!r}"
|
||||
(errors if strict else warnings).append(msg)
|
||||
|
||||
verbs = load_wordlist("verbs.txt")
|
||||
platforms = load_wordlist("platforms.txt")
|
||||
scopes = load_wordlist("scopes.txt")
|
||||
|
||||
if segments[0] in platforms and segments[0] not in verbs:
|
||||
msg = f"平台名不应放在 slug 最前：{slug!r}（应为 verb-noun-platform）"
|
||||
(errors if strict else warnings).append(msg)
|
||||
|
||||
if segments[0] not in verbs:
|
||||
msg = f"slug 首段应为动词白名单中的词：{segments[0]!r}（slug={slug!r}）"
|
||||
(errors if strict else warnings).append(msg)
|
||||
|
||||
form = classify_slug_form(segments, slug=slug)
|
||||
if form == "scope":
|
||||
if segments[-1] not in scopes:
|
||||
msg = f"slug 末段应为 scope 白名单中的词：{segments[-1]!r}（slug={slug!r}）"
|
||||
(errors if strict else warnings).append(msg)
|
||||
noun_count = segment_count - 2
|
||||
elif form == "standard":
|
||||
platform_match = _match_platform_suffix(segments, platforms)
|
||||
if platform_match is None:
|
||||
msg = f"slug 末段应匹配平台白名单：{slug!r}"
|
||||
(errors if strict else warnings).append(msg)
|
||||
noun_count = 0
|
||||
else:
|
||||
_platform_name, platform_part_count = platform_match
|
||||
noun_count = segment_count - 1 - platform_part_count
|
||||
else:
|
||||
if segment_count >= _MIN_SEGMENTS:
|
||||
if segments[-1] not in scopes:
|
||||
platform_match = _match_platform_suffix(segments, platforms)
|
||||
if platform_match is None:
|
||||
msg = f"slug 末段应匹配平台或 scope 白名单：{slug!r}"
|
||||
(errors if strict else warnings).append(msg)
|
||||
noun_count = 0
|
||||
|
||||
if noun_count > _MAX_NOUN_SEGMENTS:
|
||||
warnings.append(
|
||||
f"slug 中间名词段建议不超过 {_MAX_NOUN_SEGMENTS} 个词（当前 {noun_count}）：{slug!r}"
|
||||
)
|
||||
|
||||
return errors, warnings
|
||||
20
scripts/util/timeutil.py
Normal file
20
scripts/util/timeutil.py
Normal file
@@ -0,0 +1,20 @@
|
||||
"""时间戳与 ISO 展示。"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from datetime import datetime
|
||||
from typing import Optional
|
||||
|
||||
|
||||
def now_unix() -> int:
|
||||
return int(time.time())
|
||||
|
||||
|
||||
def unix_to_iso(ts: Optional[int]) -> Optional[str]:
|
||||
if ts is None:
|
||||
return None
|
||||
try:
|
||||
return datetime.fromtimestamp(int(ts)).isoformat(timespec="seconds")
|
||||
except (ValueError, OSError, OverflowError):
|
||||
return None
|
||||
Reference in New Issue
Block a user