xforge 0.4.6

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

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

Penetrating Supervision Rule Forge — Full Lifecycle Rule Management

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

Full lifecycle rule management: Excel import → status matching → SQL authoring → DuckDB in-process execution → alert ticketing.

---

快速开始 · Quick Start

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

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

# 启动 TUI / launch TUI
xforge

依赖 · Dependencies

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

三级数据层次 · Three-Level Data Hierarchy

问题乱象 · Category (model_name)
  示例 / e.g.  资金风险、合规风险、运营风险...
    └─ 模型 · Model (rule_code)
        示例 / e.g.  CAP_01, FIN_12...   同模型可含多条子规则 / one model may contain multiple sub-rules
          └─ 规则 · Rule (rule_code + rule_order)
              最小编排单元，含 6 维度 + SQL / the smallest unit, with 6 dimensions + SQL

去重键为 (rule_code, rule_order)，保证同一模型下的每条规则独立可追溯。 Dedup key: (rule_code, rule_order). Each rule within a model is independently traceable.

---

界面 · Interface

仪表盘 · Dashboard — 三级统计总览

┌─ 规则概览 · Overview ──────────┐
│ 🏛  问题乱象 · Categories: N    │   ← 一级 / L1：业务大类
│ 📐 模型 · Models: N             │   ← 二级 / L2：模型代码 (distinct rule_code)
│ 📋 规则 · Rules: N              │   ← 三级 / L3：具体规则 (rule_code + rule_order)
│ 📝 SQL覆盖 · Coverage: X/N (%) │
│                                 │
│ ── 按状态 · By Status ──       │
│ 📝草稿 Draft      N   ████     │
│ 🔍审核中 Review    N   ██       │
│ 🟢生效中 Active    N   ██       │
│                                 │
│ ── 问题乱象分布 · Distribution ─│
│ 示例类别A  N个模型, N条规则     │
│ 示例类别B  N个模型, N条规则     │
└─────────────────────────────────┘

规则查询 · Rule Query — 三级联动筛选 · Cascading Filters

┌─ 统计面板 · Stats ─┬─ [问题乱象▼] [模型▼] [状态▼] ─────────────┐
│ 筛选结果: N         │ 📋 条件筛选 · Conditions                    │
│                     │ [字段▼] [运算符▼] [值___] [+条件] [搜索]   │
│ 按问题乱象          │ ────────────────────────────────────────  │
│ By Category         │ │模型│规则名称│问题乱象│规则序号│状态│..│  │
│ 类别A  N            │ │CAP │示例规则│类别A  │CAP_01_1│生效│..│  │
│ 类别B  N            │ │FIN │另一规则│类别B  │FIN_12  │草稿│..│  │
│                     │ │... │...    │...    │...     │..  │.. │  │
│ 按状态 · By Status  │                                           │
│ 📝草稿 Draft    N   │                                           │
└─────────────────────┴───────────────────────────────────────────┘

选择"问题乱象"后，"模型"下拉自动过滤；再选"模型"后表格过滤为对应规则。 Select a category → the model dropdown auto-filters; select a model → the table filters accordingly.

预警工单 · Alert Tickets — 批量操作 · Batch Operations

键 · Key	功能 · Function
Space	勾选/取消当前行（随时可用）· Toggle current row
Ctrl+A	全选/取消全选当前筛选结果 · Select/deselect all filtered
a / r / c	有选中行→批量操作，无选中→操作当前行 · Batch if selected, else single
b	批量模式开关 · Batch mode toggle
Enter	查看预警详情 · View alert detail

快捷键 · Keybindings

规则查询 · Rule Query

键 · Key	功能 · Function
Enter	查看规则详情（6维度 + 版本历史）· View rule detail
e	编辑规则 · Edit rule
n	新建规则 · New rule
a	推进状态 (draft→review→approved→deployed→active) · Advance
s	暂停 · Suspend
r	回退 · Rollback
Backspace	废弃 · Deprecate
x	执行规则（异步，不阻塞 UI）· Execute (async)
f	聚焦条件筛选 · Focus filter
[ / ]	面板变窄/变宽 · Resize panel
鼠标拖 ┃	调整面板宽度 · Drag to resize

预警工单 · Alert Tickets

键 · Key	功能 · Function
Enter	查看预警详情 · View alert detail
Space	勾选/取消当前预警 · Toggle current alert
Ctrl+A	全选/取消全选当前筛选结果 · Select/deselect all
a / r / c	推进/回退/关闭（有选中则批量）· Advance/rollback/close
b	批量模式开关 · Batch mode

全局 · Global

键 · Key	功能 · Function
Ctrl+1~6	切换 Tab · Switch tabs
?	帮助 · Help

命令行工具 · CLI Tools

# 导入规则 / import rules
xforge-import --excel --clear

# 导入 SQL 文件 / import SQL files
python scripts/import_sql_files.py

# 执行中心 / execution center（交互多选 / interactive multi-select）
python scripts/run_center.py              # 交互选择
python scripts/run_center.py --all        # 全部有 SQL 的规则
python scripts/run_center.py --all --clear

# 导出 DSL / export DSL
xforge-export [--status active]

# 生成规则手册 / generate rule manual（AI + PDF/DOCX）
xforge-manual --all               # 默认全开 / all on
xforge-manual --all --no-ai       # 跳过 AI / skip AI
xforge-manual --all --no-pdf      # 仅 DOCX / DOCX only
xforge-manual --all --force       # 强制重生成 / force regenerate

规则状态流转 · Rule State Machine

8 种状态 · 8 states，Enter → Deploy → Retire：

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

状态 · State	图标	含义 · Meaning	判定来源 · Source
draft	📝	草稿 · Draft	默认 · Default
review	🔍	审核中 · Under Review	Excel 开发状态关键词匹配
active	🟢	生效中 · Active	Excel 开发状态关键词匹配

状态初值由 config.yaml 的 status_rules 关键词匹配决定，其余状态在 TUI 中手动流转。 Initial status is determined by keyword matching in status_rules; other states are manually transitioned in the TUI.

6维度规则模型 · 6-Dimension Rule Model

#	维度 · Dimension	内容 · Content
1	管理要求 · Mgmt Requirement	制度依据、文件来源 · Policy basis
2	规则解读 · Rule Interpretation	业务逻辑翻译 · Business logic
3	系统及字段 · Systems & Fields	数据源、表名、字段映射 · Data mapping
4	SQL代码 · SQL Code	可执行 DuckDB SQL · Executable SQL
5	输出结果 · Output Spec	预警记录结构 · Alert record schema
6	输出解读 · Output Interpretation	业务核查指南 · Audit guidance

配置说明 · Configuration

config.yaml 核心配置项 · Core options：

# Excel 导入 · Import
excel:
  excluded_sheets: [封皮, 封面, ...]
  excluded_models: [需排除的模型名, ...]
  column_mapping:                       # 表头 → 字段名 · header → field
    规则代码: "rule_code"
    预警规则: "rule_name"
    规则序号: "sub_code"
    ...
  sheet_mappings:                       # 特定 sheet 覆盖映射 · per-sheet override
    概览:
      模型: "model_name"
      开发状态: "dev_status"
  status_rules:                         # 关键词 → 生命周期状态
    - keyword: "已上线"
      status: "active"

# 数据绑定 · Data bindings
data_bindings:
  alias_name: "/path/to/data.parquet"

# UI 术语 · Terminology（可自定义 · customizable）
terminology:
  model: "问题乱象"        # L1：业务大类
  rule_code: "模型"        # L2：模型代码
  rule_name: "规则名称"    # L3：具体规则

版本历史 · Changelog

v0.4.5 — 三级层次 + 批量重构 · Hierarchy & Batch Refactor

• 三级数据层次正式确立：问题乱象 → 模型 → 规则，术语映射统一 Three-level hierarchy: Category → Model → Rule, unified terminology
• 规则查询三级联动筛选：问题乱象 → 模型 → 状态级联下拉 Cascading filter dropdowns in rule query
• 仪表盘显示「问题乱象 / 模型 / 规则」三级统计 + 每类模型数+规则数 Dashboard shows three-level stats with model count per category
• 规则详情标题显示完整层级路径 Rule detail shows full hierarchy path in title
• 预警批量操作重构：Space 勾选、Ctrl+A 全选、Enter 查看详情 Alert batch mode: Space toggle, Ctrl+A select all, Enter detail
• 修复安装后 _get_version() → importlib.metadata.version Fixed version lookup after pip install

v0.4.x — 品牌重塑 + AI 手册 · Rebrand + AI Manual

• 项目更名为 XForge，CLI 入口 xforge · Renamed to XForge
• AI 规则手册生成：SQL → 业务解读，自动 PDF + DOCX AI rule manual: SQL → business interpretation, auto PDF/DOCX
• 三级智能跳过：已有/无SQL/占位符 · Smart skip: existing / no-SQL / placeholder

v0.3.x — TUI 核心框架 · Core TUI

• 6 Tab Textual TUI：仪表盘/查询/审批/执行/预警/分析 6-tab TUI: Dashboard / Query / Approval / Execution / Alerts / Analytics
• DuckDB in-process 直接执行 · In-process SQL execution
• 执行中心：交互多选 + 实时进度 + 自动备份 Execution center: multi-select + live progress + auto-backup
• 分析 Tab：覆盖率/触发率/SLA/趋势 · Analytics: coverage / trigger rate / SLA / trends
• Excel 导入 + 概览 sheet 独立映射 + 状态自动匹配 Excel import + overview sheet mapping + auto status matching
• 配置驱动术语系统 · Config-driven terminology

v0.2.x — DSL 引擎 · DSL Engine

• DSL 导出/导入、规则-数据源绑定 · DSL export/import, rule-data binding

v0.1.x — 项目启动 · Inception

• 6维度规则模型 + Excel 解析器 + 基础 CLI 6-dimension rule model + Excel parser + basic CLI

技术架构 · Architecture

┌──────────────────────────────────────────────────┐
│                  Textual TUI                      │
│  Dashboard │ Query │ Approval │ Exec │ Alert │ Analytics │ Settings │
├──────────────────────────────────────────────────┤
│               Service Layer                       │
│  import_service │ execution_service │ export_service │ sql_adapter │
├──────────────────────────────────────────────────┤
│               Model Layer (SQLite)                │
│  rules │ rule_versions │ executions │ alerts │ models │
├──────────────────────────────────────────────────┤
│          Execution Engine (DuckDB)                │
│  in-process SQL execution │ parquet data sources  │
└──────────────────────────────────────────────────┘

License

MIT