# **Skill 化配置架构与业务流转技术设计文档**

**文档版本**：V2.1 (5层架构与语义解耦全景版)

**核心理念**：规则必须脱离底层代码；质控逻辑必须基于“医学语义”而非“物理字段”进行配置，以适应不同的 IIT 项目。

## **第一章 架构总览：从“硬编码”到“Skill 驱动”**

我们将数据、规则与报告的生成链路设计为高度解耦的三段式架构：

\[阶段一：基建与抽象\]       \[阶段二：Skill 编排配置\]        \[阶段三：执行与映射\]  
  (项目前置准备)                 (DM 规则配置)                  (引擎自动计算)

1\. REDCap 字典同步        1\. 选择 Skill 模板           1\. 监听数据变化 (Webhook)  
2\. 知识库向量化 (RAG)  \-\> 2\. 绑定语义标签        \-\>    2\. 提取 5 层级联坐标  
3\. LLM 语义映射对齐       3\. 设定阈值与报警级别        3\. 引擎执行逻辑 (硬/软)  
  (AutoMapper)            (赋能 D1-D7 维度)            4\. 结果落入 5层数据底座  
                                                       5\. 自动组装 5大 GCP 报告

## **第二章 配置前置准备 (Project Initialization)**

在配置具体的质控 Skill 前，系统必须完成项目的“数字孪生”构建：

### **2.1 结构化数据基建：REDCap 元数据同步**

* **动作**：调用 exportMetadata 获取字典，包含分支逻辑（Branching Logic）。这为 D2 (缺失率) 计算打下基石。

### **2.2 非结构化知识基建：建立专属 RAG 大脑**

* **动作**：上传方案 Protocol、ICF，进行向量化。为 D5/D6 的 SoftRule 模糊推理提供依据。

### **2.3 核心解耦：AutoMapper 语义映射 (重中之重)**

* **动作**：利用 LLM，将 REDCap 毫无规律的物理变量名（如 ie\_01, ae\_term），映射为**系统内置标准医学语义标签**（如 \[入选标准\_年龄\], \[不良事件\_名称\]）。  
* **价值**：DM 面向通用语义配置规则，无需关心物理表名，实现通用 Skill 的跨项目复用。

## **第三章 Skill 核心数据模型设计 (The Skill Schema)**

### **3.1 数据库表结构 (iit\_skills)**

model IitSkill {  
  id              String   @id @default(cuid())  
  projectId       String   // 绑定到具体项目  
  name            String   // e.g., "ALT 重度异常监测"  
    
  category        String   // 关键！挂载到 7 大维度: D1, D2, D3, D5, D6  
  // 质控深度，全面升级支持 5 层架构  
  targetLevel     String   // RECORD, EVENT, FORM, INSTANCE, FIELD  
    
  engineType      String   // HARD\_RULE (JSON Logic) 或 SOFT\_RULE (LLM)  
  triggerType     String   // WEBHOOK (实时) 或 CRON (定时)  
    
  configuration   Json     // JSON 配置体  
  isActive        Boolean  @default(true)  
}

### **3.2 Configuration 字段设计 (配置解析)**

**A. HardRule (硬规则 \- 适用于 D1, D3, D7)**

采用 JSON Logic 语法，实现毫秒级绝对判定。

{  
  "semantic\_tags": \["实验室\_谷丙转氨酶"\],   
  "logic": {  
    "\>": \[{"var": "实验室\_谷丙转氨酶"}, 150\]  
  },  
  "on\_fail\_message": "谷丙转氨酶(ALT)达到重度异常标准，触发安全预警。",  
  "severity": "CRITICAL"  
}

**B. SoftRule (软规则 \- 适用于 D5, D6)**

采用 Prompt 模板，供 LLM 结合 RAG 在各个 Instance 间进行推理。

{  
  "semantic\_tags": \["不良事件\_症状描述", "合并用药\_药物名称"\],  
  "prompt\_template": "患者主诉发生了 {不良事件\_症状描述}，请检索知识库禁忌药目录，评估这是否与患者填报的第 {InstanceID} 行用药 {合并用药\_药物名称} 存在禁忌冲突？",  
  "rag\_enabled": true,  
  "severity": "WARNING"  
}

## **第四章 配置工作流与执行链路 (How it works in action)**

### **4.1 DM 配置工作流 (UI 交互层)**

1. **选择维度**：DM 选择配置【D1 入排标准】。  
2. **选择模板**：选择“数值范围检验”。  
3. **绑定语义**：下拉选择 \[入选标准\_年龄\]。  
4. **设置条件**：\>= 18 且 \<= 75。保存发布。

### **4.2 引擎自动化执行链路 (Execution Pipeline)**

1. **触发与拦截**：REDCap Webhook 抵达。  
2. **提取五层坐标**：解析出 Record:P005 \-\> Event:V2 \-\> Form:AE\_Log \-\> Instance:2 \-\> Field:ae\_term。  
3. **加载 Skills**：查询匹配的 active Skills。  
4. **装填数据**：按 AutoMapper 映射装填数值。  
5. **引擎计算**：调起 HardRuleEngine 或 SoftRuleEngine。  
6. **状态回写**：若失败，将原因写入 qc\_field\_status，携带 Category (如 D5)，红灯沿五层坐标向上一路冒泡至 Record 级。