xforge 0.4.4

XForge — 穿透式监管规则锻造平台 | Penetrating Supervision Rule Forge

XForge — 穿透式监管规则全生命周期管理平台

规则的全生命周期管理中心：Excel 导入 → 状态匹配 → 编写 SQL → 审批部署 → DuckDB 直接执行 → 预警工单。

执行架构： DuckDB in-process 直接执行 SQL，不再通过 subprocess 调用外部 regula。DSL 导出作为兼容层保留。

快速开始

git clone ssh://[e-mail]/songwupei/RuleForge.git
cd RuleForge
cp config.yaml.example config.yaml   # 按需修改 Excel 路径和数据绑定
pip install -e "."

# 导入规则（从规则手册 Excel）
python scripts/import_rules.py --excel --clear

# 启动 TUI
python -m src.app

依赖

依赖	要求
textual	≥0.52
duckdb	≥0.9
polars	≥0.19
openpyxl	≥3.1
pyyaml	≥6.0

界面

┌─ 统计面板 (可拖拽) ─┬─ 快速筛选 ─────────────────────────────┐
│ 📊 筛选统计          │ [问题乱象▼] [状态▼]                    │
│                     │ 📋 条件筛选                             │
│ 按问题乱象           │ [字段▼] [运算符▼] [值___] [✕]          │
│ 靠企吃企   6 ████   │ [+条件] [搜索] [重置]                  │
│ 过度负债  11 ████   │ ─────────────────────────────────────  │
│ ...                 │ │模型代码│模型名称│问题乱象│规则序号│..│
│                     │ │KQCQ_11│假期开票│靠企吃企│KQCQ_11_1│  │
│ 按状态              │ │...    │...    │...    │...     │   │
│ 🟢生效中  19 ████   │                                        │
│ 🔍审核中  28 ████   │                                        │
│ 📝草稿   131 ████   │                                        │
└─────────────────────┴────────────────────────────────────────┘

快捷键

键	功能
Enter	查看规则详情（6维度 + 版本历史）
e	编辑规则
n	新建规则
a	推进状态（draft→review→approved→deployed→active）
s	暂停
r	回退
Backspace	废弃
f	聚焦条件筛选
[ / ]	面板变窄/变宽
鼠标拖 ┃	调整面板宽度
x	执行规则（异步，不阻塞 UI）
t	执行历史：全部/汇总切换

| ctrl+1~6 | 切换 Tab | | ? | 帮助 |

命令行工具

# 导入规则（从 Excel 规则手册，--clear 清空重导）
python scripts/import_rules.py --excel --clear

# 导入 SQL 文件（按 sub_code 匹配）
python scripts/import_sql_files.py

# 执行中心（交互式多选 + 实时进度 + 自动备份 + 日志）
python scripts/run_center.py              # 交互选择
python scripts/run_center.py --all        # 全部有 SQL 的规则
python scripts/run_center.py --all --clear  # 清空旧数据后全部执行

# 改写 MySQL SQL 为 DuckDB 语法
python scripts/rewrite_sql_duckdb.py

# 导出 DSL
python scripts/export_dsl.py [--model 靠企吃企] [--status active]

# 生成规则手册（7 步模板 + AI 增强 + PDF/DOCX，默认全部开启）
python scripts/generate_rule_manual.py --all               # 默认：AI, -ai后缀, PDF+DOCX, 已有跳过
python scripts/generate_rule_manual.py --all --no-ai       # 仅 SQL 解析，不调 AI
python scripts/generate_rule_manual.py --all --no-pdf      # 仅生成 DOCX
python scripts/generate_rule_manual.py --all --suffix ''    # 文件名不加 -ai 后缀
python scripts/generate_rule_manual.py --all --force        # 强制重生成 md

# 一键生成全部规则手册（AI 增强 + PDF/DOCX + 自动备份）
./make_all_manual.sh                  # 全部流程
./make_all_manual.sh --no-ai          # 跳过 AI
./make_all_manual.sh --no-pdf         # 仅生成 md + docx
./make_all_manual.sh --rule KQCQ_12   # 仅指定规则

规则手册生成：generate_rule_manual.py 从数据库读取规则 / SQL / 执行历史，按 7 步模板生成 Markdown。默认启用 AI 从 SQL 反向解读业务逻辑（$OPENAI_API_KEY + $OPENAI_BASE_URL 自动适配 DeepSeek/OpenAI），--no-ai 关闭。默认同时输出 PDF + DOCX，--no-pdf / --no-docx 排除。已有文件自动跳过，--force 强制重生成。make_all_manual.sh 一键执行 + 自动备份到 data/manual/backups/。

规则状态流转

规则从录入到退役的完整生命周期，共 8 种状态：

  draft ──→ review ──→ approved ──→ deployed ──→ active ⇄ suspended
    ↑          ↑           ↑            ↑           ↑
    └──────────┴───────────┴────────────┴───────────┘  (r 回退)
                           ↑
                     deprecated ──→ retired

状态	图标	含义	判定来源
draft	📝	草稿	默认状态；开发状态未匹配到其他规则
review	🔍	审核中	Excel 开发状态含「待主责部门确认」（28 条）
active	🟢	生效中	Excel 开发状态含「已上线」（19 条）

状态初值由 Excel 概览 sheet 的「开发状态」字段决定，通过 config.yaml 的 status_rules 关键词匹配。其余状态（approved/deployed/suspended/deprecated/retired）在 TUI 中手动流转。

推进路径（a）： draft → review → approved → deployed → active 回退（r）： 任一步骤逆向前一步 废弃（Backspace）： → deprecated → retired

6维度规则模型

维度	内容	示例
1. 管理要求	国资委文件/内部制度	国资委《关于加强中央企业资金管理有关事项的通知》
2. 规则解读	业务语言翻译	集团合并货币资金<50亿 且 货币资金/带息负债<3%
3. 系统及字段	数据源、表名、字段	司库系统 → account_balance → 货币资金余额
4. SQL代码	可执行查询	SELECT ... WHERE cash < 50e8
5. 输出结果	预警记录结构	alert_record(rule_id, corp_code, metric_value)
6. 输出解读	业务核查指南	比值<3%表明现金紧张，需核查资金归集情况

配置说明

config.yaml 核心配置项：

# Excel 导入
excel:
  excluded_sheets: [封皮, 封面, ...]    # 跳过的 sheet
  excluded_models: [军品工资奖金套取, ...]  # 排除的问题乱象
  column_mapping: {规则代码: rule_code, ...}  # 默认列映射
  sheet_mappings:                     # 特定 sheet 覆盖映射
    概览: {模型: model_name, 开发状态: dev_status, ...}
  status_rules:                       # 开发状态→生命周期状态
    - keyword: "已上线"
      status: "active"
    - keyword: "待主责部门确认"
      status: "review"

# UI 术语
terminology:
  model: "问题乱象"
  rule_code: "模型代码"
  rule_name: "模型名称"
  rule_interpretation: "规则要点"

Roadmap

✅ v0.3.1 — 全部完成

• 6 Tab TUI（仪表盘/查询/审批/执行/预警/分析）
• 执行中心（交互式多选 + 实时进度 + DB 自动备份 + 日志）
• 分析 Tab（覆盖率/触发率/SLA 时效/执行趋势 + 手动更新）
• 仪表盘积压告警（>7/14 天红色标记）
• 执行历史全部/汇总切换（t 键）
• 异步执行（不阻塞 UI）+ 耗时用分秒显示
• 概览 sheet 独立列映射 + 开发状态→生命周期状态自动匹配
• 配置驱动的术语系统 + 排除清单
• 完整子代码（sub_code）支持
• 延续行 logic 拼接（不丢多行规则解析）
• Textual 6.x/8.x NoSelection 兼容
• KQCQ_10_2 SQL 优化 (390s→4s, CTE+coalesce)
• 跨批次去重 (同批次不去重, 不同批次相同数据跳过)
• 设置 Tab (一键备份/还原 + 执行中心快捷入口)
• 启动环境检测 (startup_check)

✅ v0.3.4 — 全部完成

• 字段名映射表：从附件1 parquet 完整提取（80 表 1679 字段，覆盖率 62%→100%），CSV 格式优先加载
• parquet 直查 SQL（rules_dsl/sql/parquet/）：generate_parquet_sql.py 自动生成，列名中文 + read_parquet() 自包含
• 设置 Tab：SQL 导入 + MySQL→DuckDB 转换 + 映射表状态/刷新缓存
• 审批/执行/预警三个 Tab 新增「规则序号」列
• 预警工单批量多选修复（update_cell 单格更新，不重建表格）
• Header 显示版本号（自动读取 pyproject.toml）
• SQL 导入过滤 TODO 占位文件
• sql_adapter 精确匹配优先 + 模糊匹配日志 + 发票代码→fpdm, 单位→dw 修正
• filepulse 自动同步映射表到 RuleForge（kedro hook 集成）
• 删除重复 data/rules_dsl/ 目录