docs: add document-type and rule-binding analysis and migration plan

2026-04-30 12:37:00 +08:00
parent 9e1b7a6de7
commit 32f56f7bf6
1 changed files with 127 additions and 0 deletions
@@ -0,0 +1,127 @@
+# 文档类型与评查组关联 — 老项目分析 & 新方案
+
+## 一、老项目模型（docauditai）
+
+### 三层间接绑定
+
+```
+DocumentType → TopLevelGroup(s) → ChildGroups → EvaluationPoints
+     │                │               │               │
+     │    evaluation_  │   pid=0       │   pid={top}   │   evaluation_
+     │    point_groups │               │               │   point_groups_id
+     │    _ids (JSONB) │               │               │
+```
+
+- `document_types.evaluation_point_groups_ids` — JSONB 数组，存顶层组 ID，如 `[3]` 或 `[1,5]`
+- `evaluation_point_groups` — 两级树：`pid=0` 是顶层组，"pid>0" 是子组
+- `evaluation_points` — 属于子组，含 `extraction_config`（提取规则）和 `evaluation_config`（评查规则），按 `area` + `document_attribute_type` 过滤
+
+### 运行时解析流程
+
+```
+doc_type_code
+  → 查 document_types.evaluation_point_groups_ids[0]
+    → 查 evaluation_point_groups WHERE pid = {top_group_id}
+      → 查 evaluation_points WHERE evaluation_point_groups_id = {child_id}
+        → 按 area + attribute_type 过滤
+          → 返回最终评查点列表
+```
+
+---
+
+## 二、新平台模型（leaudit-platform）
+
+### 直接绑定
+
+```
+DocumentType ──→ RuleTypeBinding ──→ RuleSet ──→ RuleVersions
+```
+
+**`leaudit_rule_type_bindings`**:
+| 字段 | 说明 |
+|------|------|
+| `doc_type_id` | FK → leaudit_document_types.id |
+| `rule_set_id` | FK → leaudit_rule_sets.id |
+| `binding_mode` | "explicit"（一对一）/ "inherit"（继承） |
+| `region` | 地区隔离 |
+| `priority` | 同一 doc_type 多个 rule_set 时的优先级 |
+
+**运行时**（已在 auditServiceImpl.py 实现）:
+```sql
+SELECT b.rule_set_id, rs.current_version_id
+FROM leaudit_rule_type_bindings b
+JOIN leaudit_rule_sets rs ON rs.id = b.rule_set_id
+WHERE b.doc_type_id = :doc_type_id
+  AND b.region = :region
+  AND b.is_active = true
+ORDER BY b.priority DESC
+```
+
+### 与老模型的关键差异
+
+| | 老 | 新 |
+|---|---|---|
+| 绑定粒度 | 文档类型 → 顶层组（间接） | 文档类型 → 规则集（直接） |
+| 评查点层级 | 三级（类型→组→子组→点） | 两级（类型→规则集→版本） |
+| 地区隔离 | evaluation_points.area | rule_type_bindings.region |
+| 规则版本 | 无版本概念 | 规则集 + 版本管理 |
+
+实际上新模型更简洁：老系统里的"顶层组"≈新系统的"规则集"，老系统里的"子组+评查点"≈新系统的"规则版本内容"。新系统去掉了中间的子组层级。
+
+---
+
+## 三、已落地 vs 待落地
+
+### ✅ 已落地
+
+| 项 | 说明 |
+|----|------|
+| `leaudit_document_types` 表 | 有 20 条种子数据，含 code/name/entry_module_id/prompt_config |
+| `leaudit_rule_sets` 表 | 规则集 + 版本管理 |
+| `leaudit_rule_type_bindings` 表 | 20 条绑定记录，已全部配对 |
+| 运行时绑定解析 | auditServiceImpl.Run() 中查 bindings → 找 rule_set + version |
+| `GET /api/document-types` | 刚加的，返回 id/name/code |
+
+### ❌ 待落地
+
+| 优先 | 项 | 说明 |
+|------|----|------|
+| 高 | 文档类型 CRUD 后端 | POST/PUT/DELETE /api/document-types |
+| 高 | 规则绑定 CRUD 后端 | 在文档类型编辑中配 rule_set_id(s) |
+| 高 | 前端文档类型管理页 | 对应旧 `document-types._index.tsx` |
+| 中 | 规则绑定前端 UI | 文档类型编辑页中选规则集的控件 |
+| 中 | 前端规则集选择器 | 对接 `/api/rule-sets` 或现有规则接口 |
+| 低 | prompt_config 编辑 | 每个文档类型的提示词模板配置 |
+
+---
+
+## 四、推荐接入方案
+
+### 第 1 步：文档类型 CRUD 后端
+
+```
+GET    /api/document-types          ← 已实现
+POST   /api/document-types          ← 新增
+PUT    /api/document-types/{id}     ← 新增
+DELETE /api/document-types/{id}     ← 新增
+```
+
+字段：`code`, `name`, `description`, `entry_module_id`, `prompt_config`, `rule_set_ids`（一次性处理绑定）
+
+### 第 2 步：规则绑定 CRUD
+
+两种方案：
+- **方案 A**（推荐）：绑定内嵌到文档类型接口。创建/更新文档类型时传 `rule_set_ids: [21, 31]`，后端自动维护 `leaudit_rule_type_bindings`。
+- **方案 B**：独立绑定接口 `POST/DELETE /api/rule-type-bindings`。
+
+推荐方案 A，因为绑定是文档类型的属性，一起管理更自然。
+
+### 第 3 步：前端文档类型管理页
+
+参考旧前端 `document-types._index.tsx` / `document-types.new.tsx`，用新 API 重写：
+- 列表页：表格展示 code/name/entry_module/规则集数量
+- 新建/编辑页：表单填 code/name/entry_module，多选规则集
+
+### 第 4 步：上传页关联
+
+上传时将 `typeCode` 写入 `leaudit_documents.type_id` → 运行时自动找绑定 → 加载规则集 → 执行评查。整个链路已通，只需确保文档类型数据存在。