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

Project description

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://git@codeberg.org/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 种状态覆盖规则从"录入"到"退役"的完整生命周期，通过 TUI 键盘操作手动流转。

8 states covering the full rule lifecycle from "entry" to "retirement", manually transitioned via TUI keyboard shortcuts.

状态一览 · State Overview

#	状态 · State	图标	含义 · Meaning	说明 · Description
1	`draft`	📝	草稿 · Draft	规则初建，尚未提交审核 · Rule created, not yet submitted
2	`review`	🔍	审核中 · Under Review	已提交，等待审核确认 · Submitted, awaiting review
3	`approved`	✅	已批准 · Approved	审核通过，待部署 · Approved, ready to deploy
4	`deployed`	🚀	已部署 · Deployed	已部署到执行环境 · Deployed to execution environment
5	`active`	🟢	生效中 · Active	正在执行，产生预警 · Running, generating alerts
6	`suspended`	⏸️	已暂停 · Suspended	临时停用，可恢复 · Temporarily stopped, resumable
7	`deprecated`	⚠️	已废弃 · Deprecated	标记废弃，待退役 · Marked obsolete, pending retirement
8	`retired`	🏁	已退役 · Retired	终态，不可变更 · Terminal state, immutable

初始状态：导入时由 config.yaml 的 status_rules 关键词匹配决定（匹配"已上线"→active，"主责部门确认"→review），其余默认为 draft。 Initial status: determined by keyword matching in status_rules during import; defaults to draft.

状态流转图 · Transition Diagram

                        ┌──────────┐
                        │  draft   │  📝 草稿
                        └─────┬────┘
                              │ 提交审核
                    ┌─────────┼─────────┐
                    │                   │
                    ▼                   ▼
              ┌──────────┐       ┌─────────────┐
              │  review  │       │ deprecated  │  ⚠️ 废弃
              │  🔍 审核  │       └──────┬──────┘
              └─────┬────┘              │
                    │ 批准               │ 退役
              ┌─────┼─────┐             ▼
              │           │       ┌──────────┐
              ▼           │       │ retired  │  🏁 退役（终态）
        ┌──────────┐      │       └──────────┘
        │ approved │      │
        │ ✅ 已批准  │      │ (回退到草稿)
        └─────┬────┘      │
              │ 部署       │
              ▼           │
        ┌──────────┐      │
        │ deployed │      │
        │ 🚀 已部署  │      │
        └─────┬────┘      │
              │ 激活       │
              ▼           │
        ┌──────────┐      │
   ┌───→│ active   │←─────┘
   │    │ 🟢 生效中  │
   │    └─────┬────┘
   │          │ 暂停
   │          ▼
   │    ┌───────────┐
   │    │ suspended │  ⏸️ 暂停
   │    └─────┬─────┘
   │          │ 恢复
   └──────────┘

完整流转矩阵 · Complete Transition Matrix

下表列出每种状态允许的所有目标状态及触发方式：

All allowed transitions per source state, with trigger method.

当前状态 · From	可流转至 · Can Go To	触发方式 · Trigger
`draft`	→ `review`	`a` 推进 · Advance
	→ `deprecated`	`Backspace` 废弃 · Deprecate
`review`	→ `approved`	`a` 推进 · Advance
	→ `draft`	`r` 回退 · Rollback
	→ `deprecated`	`Backspace` 废弃 · Deprecate
`approved`	→ `deployed`	`a` 推进 · Advance
	→ `draft`	`r` 回退 · Rollback
	→ `deprecated`	`Backspace` 废弃 · Deprecate
`deployed`	→ `active`	`a` 推进 · Advance
	→ `suspended`	`s` 暂停 · Suspend
	→ `approved`	`r` 回退 · Rollback
`active`	→ `suspended`	`s` 暂停 · Suspend
	→ `deprecated`	`Backspace` 废弃 · Deprecate
	→ `deployed`	`r` 回退 · Rollback
`suspended`	→ `active`	`a` 推进 / `r` 回退 · Advance / Rollback
	→ `deprecated`	`Backspace` 废弃 · Deprecate
`deprecated`	→ `retired`	（终态，不可逆 · terminal）
	→ `draft`	`r` 回退（复活）· Rollback (revive)
`retired`	—	🚫 终态，无出口 · Terminal, no exit

键盘操作语义 · Keybinding Semantics

键 · Key	操作 · Action	语义 · Meaning
`a`	推进 · Advance	沿主线正向推进：`draft→review→approved→deployed→active`；`suspended→active`（恢复）
`r`	回退 · Rollback	逆向回退或复活：`deprecated→draft`（复活）、`active→deployed`、`deployed→approved`、`approved/review→draft`
`s`	暂停 · Suspend	暂停生效中的规则：`active/deployed→suspended`
`Backspace`	废弃 · Deprecate	标记废弃（除 `retired` 外均可）：均可 → `deprecated`

注意：retired 是终态，进入后不可再做任何流转。废弃规则可通过 r 回退复活到 draft，但退役后不行。 Note: retired is terminal — no further transitions allowed. Deprecated rules can be revived back to draft via r, but retired rules cannot.

时间戳自动记录 · Auto Timestamps

流转至 approved 时自动记录 approved_at；流转至 deployed 时自动记录 deployed_at。所有流转均更新 updated_at。

approved_at is auto-set when entering approved; deployed_at when entering deployed. All transitions update updated_at.

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

Project details

Release history Release notifications | RSS feed

This version

0.4.7

Jul 17, 2026

0.4.6

Jul 3, 2026

0.4.5

Jul 3, 2026

0.4.4

Jun 26, 2026

0.4.3

Jun 26, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

xforge-0.4.7.tar.gz (95.2 kB view details)

Uploaded Jul 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

xforge-0.4.7-py3-none-any.whl (115.0 kB view details)

Uploaded Jul 17, 2026 Python 3

File details

Details for the file xforge-0.4.7.tar.gz.

File metadata

Download URL: xforge-0.4.7.tar.gz
Upload date: Jul 17, 2026
Size: 95.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.13

File hashes

Hashes for xforge-0.4.7.tar.gz
Algorithm	Hash digest
SHA256	`ce770f72edacd5aeb59dff3fe60a181b5c9ffe036a49ad7d36249542934d2943`
MD5	`7eee66ddd71e5772a57dbdd9bf7f6df5`
BLAKE2b-256	`8e9f7272faed89ae6ec4022c53f51ae73d3066d77add4d83b3601a583d2a451f`

See more details on using hashes here.

File details

Details for the file xforge-0.4.7-py3-none-any.whl.

File metadata

Download URL: xforge-0.4.7-py3-none-any.whl
Upload date: Jul 17, 2026
Size: 115.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.13

File hashes

Hashes for xforge-0.4.7-py3-none-any.whl
Algorithm	Hash digest
SHA256	`3b261c5d1d1e7f8ab45e5373619b87b7c9ce3640ae7261353e99a42f565f9001`
MD5	`168c95fae4d8102bae3695521ba91a27`
BLAKE2b-256	`ab1459399fde5fc90b566aaa9ccaacccc42e61a6f9efbc413630b35eb71b2ddb`

See more details on using hashes here.

xforge 0.4.7

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

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

快速开始 · Quick Start

依赖 · Dependencies

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

界面 · Interface

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

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

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

快捷键 · Keybindings

规则查询 · Rule Query

预警工单 · Alert Tickets

全局 · Global

命令行工具 · CLI Tools

规则状态流转 · Rule State Machine

状态一览 · State Overview

状态流转图 · Transition Diagram

完整流转矩阵 · Complete Transition Matrix

键盘操作语义 · Keybinding Semantics

时间戳自动记录 · Auto Timestamps

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

配置说明 · Configuration

版本历史 · Changelog

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

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

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

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

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

技术架构 · Architecture

License

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes