Metadata-Version: 2.4
Name: xforge
Version: 0.4.7
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 种状态覆盖规则从"录入"到"退役"的完整生命周期，通过 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：

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