Files

HaHafeng 0b29fe88b5 feat(iit): QC deep fix + V3.1 architecture plan + project member management

QC System Deep Fix:
- HardRuleEngine: add null tolerance + field availability pre-check (skipped status)
- SkillRunner: baseline data merge for follow-up events + field availability check
- QcReportService: record-level pass rate calculation + accurate LLM XML report
- iitBatchController: legacy log cleanup (eventId=null) + upsert RecordSummary
- seed-iit-qc-rules: null/empty string tolerance + applicableEvents config

V3.1 Architecture Design (docs only, no code changes):
- QC engine V3.1 plan: 5-level data structure (CDISC ODM) + D1-D7 dimensions
- Three-batch implementation strategy (A: foundation, B: bubbling, C: new engines)
- Architecture team review: 4 whitepapers reviewed + feedback doc + 4 critical suggestions
- CRA Agent strategy roadmap + CRA 4-tool explanation doc for clinical experts

Project Member Management:
- Cross-tenant member search and assignment (remove tenant restriction)
- IIT project detail page enhancement with tabbed layout (KB + members)
- IitProjectContext for business-side project selection
- System-KB route access control adjustment for project operators

Frontend:
- AdminLayout sidebar menu restructure
- IitLayout with project context provider
- IitMemberManagePage new component
- Business-side pages adapt to project context

Prisma:
- 2 new migrations (user-project RBAC + is_demo flag)
- Schema updates for project member management

Made-with: Cursor

2026-03-01 15:27:05 +08:00

4.6 KiB

Raw Blame History

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 交互层)

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

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

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

4.6 KiB Raw Blame History Unescape Escape