# LeAudit YAML 规则在线编辑设计

## 1. 背景

`LeAudit` 内核当前以本地 YAML/DSL 文件作为规则输入载体执行评查流程。现阶段 **不修改 `leaudit` 核心**，但平台侧需要逐步具备以下能力：

- 在线查看 YAML 规则内容
- 在线编辑 YAML 规则
- 校验规则语法与 DSL 语义
- 规则版本化保存
- 规则发布、回滚、审计

因此需要在 `leaudit-platform` 中补充一套“**规则管理真相源**”方案，使平台能够支持规则后台，而运行时仍然兼容 `leaudit` 只读取本地 YAML 的既有行为。

---

## 2. 结论

**可以不改 `leaudit` 核心，同时把 DSL YAML 存储到 OSS，并把路径、版本、哈希等元数据存入数据库。**

运行时通过 bridge 层完成一次“远端规则 → 本地临时文件”的转换：

```text
数据库读取规则版本信息
  → 获取 rules.yaml 的 oss_url
  → 从 OSS 下载到本地临时文件
  → 调用 leaudit.dsl.loader.load_rules_file(local_tmp_path)
  → 交给 leaudit 原生执行链继续处理
```

也就是说：

- **规则真相源**：OSS + 数据库
- **执行载体**：本地临时 YAML 文件
- **LeAudit 输入接口**：保持不变

这是当前约束下最稳妥、最容易演进的方案。

---

## 3. 为什么不能继续把本地 `rules/` 目录作为正式真相源

如果未来要开放 YAML 在线编辑界面，本地目录方案会迅速暴露问题：

### 3.1 不利于在线编辑

- 前端编辑后的内容最终仍要人工写回服务器目录
- 多实例部署时，需要同步到多台机器
- 容器化部署时，本地文件可能不是稳定持久层

### 3.2 不利于版本管理

- 难以明确记录“这次评查到底使用了哪一版规则”
- 覆盖同一路径的 `rules.yaml` 后，历史执行很难追溯
- 回滚通常会退化为“手工替换文件”

### 3.3 不利于审计与权限

- 谁改的、何时改的、为什么发布，很难形成正式审计链
- 无法自然承载“编辑 / 审核 / 发布 / 回滚”权限流程

### 3.4 不利于多实例一致性

- API 节点 A 和 Worker 节点 B 可能读取到不同版本本地文件
- 扩容后所有节点都要同步规则目录，运维成本高

因此，本地 `rules/` 目录更适合保留为：

- 种子规则导入源
- 紧急回退备份
- 开发环境本地调试资源

而不应该继续承担正式规则真相源角色。

---

## 4. 为什么采用“OSS + DB + 本地临时文件”模式

该方案同时兼顾了 **不改核心** 和 **平台化管理** 两个目标。

### 4.1 对 `leaudit` 零侵入

`leaudit` 仍然读取本地 YAML 文件，无需改造其解析器、执行器或 DSL 加载逻辑。

### 4.2 支持在线编辑界面

前端提交 YAML 文本后，平台可以执行标准流程：

```text
编辑
  → 保存草稿
  → 语法校验
  → DSL 语义校验
  → 上传 OSS
  → 写入规则版本表
  → 发布 / 回滚
```

这让规则成为“平台可管理资产”，而不是“服务器磁盘文件”。

### 4.3 规则版本可追溯

每次评查运行都可以记录：

- `rule_set_id`
- `rule_version_id`
- `rule_source_oss_url`
- `rule_source_sha256`

这样可以准确回答：

- 这个结果用的是哪一版规则？
- 规则文件是否被篡改？
- 是否可以按历史版本回放？

### 4.4 发布与回滚简单

- 发布：切换 `leaudit_rule_sets.current_version_id`
- 回滚：切回旧版本 ID

无需登录服务器替换目录文件，也不要求应用重新发版。

### 4.5 多实例一致

所有 API / Worker 都从同一份 DB + OSS 真相源取规则，不再依赖本地目录是否同步。

---

## 5. 建议的系统分层

### 5.1 真相源

- **OSS**：存储 `rules.yaml` 正文文件
- **数据库**：存储规则集、规则版本、绑定关系、发布状态、哈希、编辑人、发布时间等元数据

### 5.2 执行层

- bridge 层负责把 OSS 文件下载到本地临时路径
- 临时路径交给 `leaudit.dsl.loader.load_rules_file()` 使用

### 5.3 回退层

- 本地 `rules/` 目录保留为 fallback 或 emergency backup
- 当 OSS 不可用或某些历史规则尚未迁移时可临时使用

---

## 6. 在线编辑功能设计

### 6.1 目标能力

平台应逐步具备以下功能：

- 查看规则集列表
- 查看规则版本历史
- 查看某版本 YAML 内容
- 在线编辑 YAML
- 保存草稿版本
- 校验 YAML 语法
- 校验 LeAudit DSL 语义
- 发布指定版本
- 回滚到历史版本
- 查看发布日志与校验日志

### 6.2 推荐流程

#### 编辑保存

```text
前端提交 YAML 文本
  → 后端做 YAML 语法校验
  → 后端做 LeAudit DSL 语义校验
  → 生成新版本号 / version_seq
  → 上传 rules.yaml 到 OSS
  → 写 leaudit_rule_versions
  → 返回版本信息
```

#### 发布生效

```text
选择版本发布
  → 更新 leaudit_rule_sets.current_version_id
  → 记录发布日志
  → 清理规则缓存
  → 后续新 run 自动使用新版本
```

#### 回滚

```text
选择旧版本
  → 切换 current_version_id 到旧版本
  → 写回滚日志
  → 清理规则缓存
```

---

## 7. 运行时加载设计

### 7.1 核心原则

运行时不直接让 `leaudit` 读取 OSS，也不直接读取数据库文本；而是通过 bridge 统一适配。

### 7.2 推荐加载链路

```text
document/type 确定
  → leaudit_rule_type_bindings 查规则集
  → leaudit_rule_sets.current_version_id
  → leaudit_rule_versions.oss_url
  → 下载 OSS 文件到本地临时目录
  → 校验 sha256
  → load_rules_file(local_path)
  → 执行 leaudit pipeline
```

### 7.2.1 当前项目已落地状态

当前 bridge 已按这条路线开始落地，分成两条对称链路：

- 文档文件链：
  - `leaudit_document_files.local_path / oss_url`
  - 下载或读取后落本地临时文件
  - 再交给原生 `AuditCtx.file_path`
- 规则文件链：
  - `leaudit_rule_type_bindings`
  - `leaudit_rule_sets.current_version_id`
  - `leaudit_rule_versions.oss_url`
  - 下载到本地临时 `rules.yaml`
  - `RulesLoader.load(local_path)`
  - `NativeRunner -> AuditService.audit(ctx)`

这意味着后续开放 YAML 在线编辑界面时，不需要改 `leaudit` 核心，只要继续维护 “OSS + DB + 本地临时文件” 这条桥接链即可。

### 7.3 为什么必须保留“本地临时文件”

因为当前约束是：

- 不修改 `leaudit` 核心
- `leaudit` 仍以本地路径作为 DSL 加载输入

所以本地临时文件不是“倒退”，而是一个必要的兼容层。

---

## 8. 与现有文档的一致性

该方案与当前 `docs/leaudit` 目录中的设计方向保持一致：

- `docs/leaudit/dsl_rule_schema_design.md`
  - 已提出“规则真相源 = OSS 文件 + 数据库索引”
  - 已提出“运行时 DB → OSS → 本地临时 YAML → LeAudit loader”
- `docs/leaudit/bridge_directory_design.md`
  - 已明确 bridge 负责规则加载与缓存
- `docs/leaudit/processing_logic.md`
  - 已明确 rules resolve 属于桥接层职责

本文件的重点是把“**为了未来开放 YAML 编辑界面，为什么必须这样设计**”单独说明清楚。

---

## 9. 当前项目建议

### 9.1 短期

- 保持本地 `rules/` 目录可用，确保现有流程可运行
- 将其视为 fallback，而非长期正式真相源

### 9.2 中期

- 增加规则内容查看 / 编辑 / 保存 / 发布接口
- 补齐 `leaudit_rule_versions` 的 OSS 文件上传和版本切换能力
- 补统一 OSS 客户端与 presign / upload / version publish 能力

### 9.3 长期

- 后台提供完整 YAML 在线编辑器
- 支持草稿、发布、回滚、审计
- 清理本地硬编码规则映射，统一走规则绑定表

---

## 10. 最终结论

如果未来要开放 YAML 编辑界面，那么当前项目最合适的规则架构不是“继续依赖本地目录”，而是：

- **OSS 存规则文件正文**
- **数据库存路径、版本、哈希、状态、发布信息**
- **运行时下载到本地临时文件后交给 `leaudit` 执行**

这样既能保证：

- 不修改 `leaudit`
- 兼容现有 DSL 加载方式

又能保证：

- 在线编辑方便
- 版本管理清晰
- 发布回滚简单
- 多实例一致
- 运行结果可审计可追溯

这是当前项目向“规则可运营平台”演进时最合理的方案。
