Metadata-Version: 2.4
Name: xforge
Version: 0.4.5
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 — 穿透式监管规则全生命周期管理平台

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

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

## 快速开始

```bash
git clone ssh://git@codeberg.org/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│靠企吃企│..│..│...│   │
│ 按状态              │ │   │... │...    │...    │..│..│...│   │
│ 🟢生效中  19 ████   │                                        │
│ 🔍审核中  28 ████   │                                        │
│ 📝草稿   131 ████   │                                        │
└─────────────────────┴────────────────────────────────────────┘
```

### 仪表盘

```
🏛  问题乱象: 12 个
📐 模型: 154 个      ← 三级层次：问题乱象 → 模型 → 规则
📋 规则: 178 条
📝 SQL覆盖: 7/178 (3%)
```

### 预警工单批量操作

```
Space     → 勾选/取消当前行（随时可用）
Ctrl+A    → 全选/取消全选当前筛选结果
a / r / c → 有选中行则批量操作，否则操作当前行
b         → 切换批量模式信息栏
Enter     → 查看预警详情
```

## 快捷键

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

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

## 命令行工具

```bash
# 导入规则（从 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` 核心配置项：

```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: "问题乱象"        # 一级：12 个业务大类
  rule_code: "模型"        # 二级：154 个模型代码
  rule_name: "规则名称"    # 三级：178 条具体规则
  rule_interpretation: "规则要点"
```

## Roadmap

### ✅ v0.3.1 — 全部完成

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

### ✅ v0.3.4 — 全部完成

- [x] 字段名映射表：从附件1 parquet 完整提取（80 表 1679 字段，覆盖率 62%→100%），CSV 格式优先加载
- [x] parquet 直查 SQL（`rules_dsl/sql/parquet/`）：`generate_parquet_sql.py` 自动生成，列名中文 + `read_parquet()` 自包含
- [x] 设置 Tab：SQL 导入 + MySQL→DuckDB 转换 + 映射表状态/刷新缓存
- [x] 审批/执行/预警三个 Tab 新增「规则序号」列
- [x] 预警工单批量多选修复（`update_cell` 单格更新，不重建表格）

### ✅ v0.4.5 — 全部完成

- [x] 三级层次结构：问题乱象 (12) → 模型 (154) → 规则 (178)，术语映射统一
- [x] 规则查询三级联动筛选：问题乱象 → 模型 → 状态级联下拉
- [x] 仪表盘三级统计展示 + 每个问题乱象显示模型数+规则数
- [x] 规则详情标题显示完整层级路径：问题乱象 → 模型 → 规则名
- [x] 预警批量操作重构：Space 勾选、Ctrl+A 全选、Enter 详情，职责分离
- [x] 修复 `_get_version()` 安装后读 pyproject.toml 报错 → `importlib.metadata.version`
- [x] Header 显示版本号（自动读取 pyproject.toml）
- [x] SQL 导入过滤 TODO 占位文件
- [x] sql_adapter 精确匹配优先 + 模糊匹配日志 + `发票代码→fpdm, 单位→dw` 修正
- [x] filepulse 自动同步映射表到 RuleForge（kedro hook 集成）
- [x] 删除重复 `data/rules_dsl/` 目录
