leaudit-platform-backend/docs/leaudit/dsl_rule_schema_design.md

LeAudit DSL 规则域表结构设计

状态: 核心表已落地 leaudit_platform 数据库
相关: 文档域表设计 | Bridge 目录设计

1. 设计目标

• LeAudit 运行时仍然按 YAML 规则文件执行
• 规则文件的持久真相源不再依赖固定本地目录
• 数据库存储规则元数据、版本、状态、OSS 地址
• YAML 正文作为文件产物放在 OSS
• 运行时根据数据库当前激活版本下载到本地临时文件，再按 LeAudit 原逻辑加载
• 支持规则编辑、校验、发布、回滚、审计

2. 核心原则

2.1 规则真相源是 "OSS 文件 + 数据库索引"

• 执行规则内容：YAML 文件
• 持久位置：OSS
• 数据库：记录元数据、版本、OSS 地址、激活状态

2.2 不让数据库直接变成规则执行解释器

数据库不替代 YAML/DSL 本身，不把规则拆碎存成"行式规则引擎配置"。

原因：

• 会偏离 LeAudit 原逻辑
• 会抬高规则编辑和发布成本
• 会让 DSL 的可读性和兼容性变差

2.3 规则编辑与规则执行分离

• 编辑阶段：编辑 YAML 文本、校验、上传 OSS、写版本记录
• 执行阶段：查 DB 元数据、下 OSS 文件、本地临时加载执行

3. 已落地核心表

#	表名	用途	状态
1	leaudit_rule_sets	规则集主表	✅
2	leaudit_rule_versions	规则版本表	✅
3	leaudit_rule_type_bindings	文档类型与规则集绑定	✅
4	leaudit_evaluation_point_groups	评查点规则组（PID 树形）	✅
5	leaudit_evaluation_points	规则点/评查点元数据	✅

待补充（后续阶段）：

#	表名	用途
6	leaudit_rule_file_artifacts	规则文件产物（校验报告、导出包等）
7	leaudit_rule_publish_logs	规则发布/回滚审计日志
8	leaudit_rule_validation_logs	规则校验日志

4. 核心表结构

4.1 leaudit_rule_sets

规则集主表，描述一个稳定的业务规则集实体。

字段	类型	说明
id	bigint PK	主键
rule_type	varchar(128)	业务规则类型编码，对应 DSL metadata.type_id
rule_name	varchar(512)	规则集名称
domain_type	varchar(64)	contract / admin_license / legal_doc
description	text	规则集描述
entry_module	varchar(64)	对应业务入口模块标识
current_version_id	bigint	当前激活版本 → leaudit_rule_versions.id
status	varchar(32)	draft / active / deprecated / archived
is_builtin	boolean	是否内置规则集（内置不可删除）
owner_user_id	bigint	负责人
create_time / update_time / delete_time	timestamptz	标准时间戳

4.2 leaudit_rule_versions

规则版本表，每次编辑/发布都生成一条新版本。

字段	类型	说明
id	bigint PK	主键
rule_set_id	bigint FK	→ leaudit_rule_sets.id
version_no	varchar(64)	语义版本号
version_seq	int	顺序号（rule_set 内递增）
status	varchar(32)	draft / published / deprecated / rollback
source_type	varchar(32)	oss_yaml / local_yaml / db_snippet
dsl_format	varchar(32)	yaml / json
oss_url	varchar(2048)	YAML 文件 OSS 地址
file_sha256 / file_size	—	文件完整性
metadata_type_id / metadata_name / metadata_version	—	DSL metadata 快照
change_note	text	变更说明
editor_user_id / publisher_user_id / published_at	—	编辑/发布信息
create_time / update_time	timestamptz	标准时间戳

4.3 leaudit_rule_type_bindings

文档类型和规则集的绑定表。

字段	类型	说明
id	bigint PK	主键
doc_type_id	bigint	→ leaudit_document_types.id
doc_type_code	varchar(128)	文档类型编码（冗余快速匹配）
rule_set_id	bigint FK	→ leaudit_rule_sets.id
binding_mode	varchar(32)	explicit / wildcard / fallback
priority	int	优先级（越大越高）
is_active	boolean	是否激活
note	text	备注
create_time / update_time	timestamptz	标准时间戳

5. 规则执行时序

5.1 运行时加载（当前流程）

文档类型确定
  → leaudit_rule_type_bindings 查绑定
  → leaudit_rule_sets.current_version_id
  → leaudit_rule_versions.oss_url
  → 下载 YAML 到本地临时文件
  → leaudit.dsl.loader.load_rules_file()
  → 进入执行链

5.2 编辑保存（后续实现）

前端提交 YAML 文本
  → YAML 语法校验
  → LeAudit DSL 语义校验
  → 上传 YAML 到 OSS
  → 写 leaudit_rule_versions
  → 写 leaudit_rule_validation_logs（可选）

5.3 发布生效（后续实现）

选择某版本发布
  → 更新 leaudit_rule_sets.current_version_id
  → 写 leaudit_rule_publish_logs（可选）
  → 清理/失效本地规则缓存

6. 与 OSS 的配合方式

6.1 路径建议

规则文件必须版本化，不能固定覆盖同一路径：

oss://leaudit/rules/{rule_type}/{version_no}/rules.yaml
oss://leaudit/rules/{rule_type}/{version_no}/validation_report.json

6.2 为什么不能只用固定路径

如果始终覆盖同一个 rules.yaml：

• 难回滚
• 难追踪历史执行结果对应的规则版本
• 本地缓存容易脏
• 无法做结果回放和审计

7. 种子数据：从本地 rules/ 到 OSS + DB

当前项目 rules/ 目录下已有 20+ 个类型目录、每个包含可用的 rules.yaml。需一次性导入。

7.1 初始化脚本逻辑

# 伪代码：把 rules/ 导入 OSS + DB
for each rules_dir in rules/:
    yaml_text = read(rules_dir / "rules.yaml")
    rules_file = parse_rules_yaml_text(yaml_text)

    version_no = rules_file.metadata.version
    oss_url = f"oss://leaudit/rules/{rules_dir.name}/{version_no}/rules.yaml"
    upload_to_oss(oss_url, yaml_text)

    rule_set = upsert_rule_set(
        rule_type=rules_dir.name,
        rule_name=rules_file.metadata.name,
        domain_type=classify_domain(rules_file),
        status="active",
        is_builtin=True,
    )

    version = insert_rule_version(
        rule_set_id=rule_set.id,
        version_no=version_no,
        oss_url=oss_url,
        ...
    )

    update_rule_set(rule_set.id, current_version_id=version.id)

    # 绑定文档类型（如果已知）
    doc_type_id = resolve_doc_type_id(rules_dir.name)
    if doc_type_id:
        insert_type_binding(...)

7.2 初始化后的本地 rules/ 处置

推荐方案：保留为只读紧急回退备份，标记为不再接受编辑。如果 OSS 不可用或规则全损，本地至少有一套可用的规则副本。

7.3 _TYPE_ID_RULES_MAP 硬编码过渡

leaudit_bridge/tasks.py 中的硬编码映射：

_TYPE_ID_RULES_MAP: dict[int, str] = {
    3: "行政处罚",
}

过渡策略：

1. 阶段 A：保留硬编码为 fallback，同时 leaudit_rule_type_bindings 表已有数据
2. 阶段 B：_resolve_rules_path() 先查 leaudit_rule_type_bindings，未命中 fallback 到硬编码
3. 阶段 C：所有绑定入库后，删除 _TYPE_ID_RULES_MAP

8. 推荐接口能力（后续实现）

• GET /api/leaudit/rule-sets
• GET /api/leaudit/rule-sets/{rule_type}
• GET /api/leaudit/rule-sets/{rule_type}/versions
• GET /api/leaudit/rule-versions/{version_id}/content
• POST /api/leaudit/rule-sets/{rule_type}/validate
• POST /api/leaudit/rule-sets/{rule_type}/versions
• POST /api/leaudit/rule-sets/{rule_type}/publish
• POST /api/leaudit/rule-sets/{rule_type}/rollback

9. 最终结论

• 规则内容继续保持 YAML 形态
• 持久真相源从固定本地文件改为 OSS 文件
• 数据库存规则元数据、版本、状态和 OSS 地址
• 运行时通过 "DB → OSS → 本地临时 YAML → LeAudit loader" 保持 LeAudit 原逻辑不变