Metadata-Version: 2.4
Name: xforge
Version: 0.4.6
Summary: XForge — 穿透式监管规则锻造平台 | Penetrating Supervision Rule Forge
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual>=0.52
Requires-Dist: duckdb>=0.9
Requires-Dist: polars>=0.19
Requires-Dist: openpyxl>=3.1
Requires-Dist: pyyaml>=6.0

# 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

```bash
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

```bash
# 导入规则 / 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：

```yaml
# 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
