# 個人基因風險與用藥交互作用決策支援系統 – 系統規格書

- 版本：v0.1-draft  
- 作者：Gbanyan + 助理規劃  
- 狀態：草案，預期隨實作迭代  
- 目的：提供給 LLM（如 Claude、Codex 等）與開發者閱讀，作為系統設計與實作的基礎規格。

---

## 0. 系統目標與範圍

### 0.1 目標

建立一套「個人化、基因驅動」的決策支援系統，核心功能：

1. **從個人與父母的外顯子定序資料（BAM）出發**，產生可查詢的變異資料庫。
2. **針對特定疾病、症狀或表型**，自動查詢相關基因與已知致病變異，並在個人資料中搜尋對應變異。
3. 依據 **ACMG/AMP 等準則** 與公開資料庫，給出 **機器輔助、具人工介入點的變異詮釋**。
4. 進一步整合：
   - 基因藥物學（Pharmacogenomics, PGx）
   - 藥–藥交互作用（DDI）
   - 保健食品、中藥等成分的潛在交互作用與風險
5. 提供一個自然語言問答介面，使用者可直接問：
   - 「我有沒有 XXX 的遺傳風險？」
   - 「以我現在吃的藥和保健食品，有沒有需要注意的交互作用？」

> 系統定位為：**個人決策支援工具 / 研究工具**，而非正式醫療診斷系統。

### 0.2 核心設計哲學

- **分階段發展**：先穩固「基因本體」與變異詮釋，再往 PGx 與交互作用擴充。
- **明確的人機分工**：對每個模組標記 `Auto / Auto+Review / Human-only`。
- **可追蹤、可回溯**：每一個結論都可追蹤到所用規則、資料庫版本、人工 override。

---

## 1. 發展階段與整體架構

### 1.1 發展階段總覽

| 階段 | 名稱 | 核心產出 | 主要對象 |
|------|------|----------|----------|
| Phase 1 | 基因本體與變異詮釋基礎 | 個人+trio VCF、註解與疾病/基因查詢 | 單基因疾病風險 |
| Phase 2 | 基因藥物學與 DDI | 基因–藥物對應、藥–藥交互作用分析 | 精準用藥建議 |
| Phase 3 | 保健食品與中藥交互作用 | 成分標準化與交互作用風險層級 | 整體用藥＋補充品安全網 |
| Phase 4 | NLP/LLM 問答介面 | 自然語言問答、報告生成 | 一般使用者 / 臨床對話 |

### 1.2 高階架構圖（Mermaid）

```mermaid
flowchart TD

subgraph P1[Phase 1: 基因本體]
  A1[BAM (本人+父母)] --> A2[Variant Calling Pipeline]
  A2 --> A3[Joint VCF (Trio)]
  A3 --> A4[Variant Annotation (ClinVar, gnomAD, VEP...)]
  A4 --> A5[Genomic DB / Query API]
end

subgraph P2[Phase 2: PGx & DDI]
  B1[藥物清單] --> B2[PGx Engine]
  A5 --> B2
  B1 --> B3[DDI Engine]
end

subgraph P3[Phase 3: 補充品 & 中藥]
  C1[保健食品/中藥清單] --> C2[成分標準化]
  C2 --> C3[成分交互作用引擎]
  B1 --> C3
  A5 --> C3
end

subgraph P4[Phase 4: 問答與報告]
  D1[前端 UI / CLI / API Client] --> D2[LLM Orchestrator]
  D2 -->|疾病/症狀詢問| A5
  D2 -->|用藥/成分詢問| B2
  D2 --> B3
  D2 --> C3
  A5 --> D3[報告產生器]
  B2 --> D3
  B3 --> D3
  C3 --> D3
end
```

---

## 2. 通用設計：人機分工標記

所有模組需標記自動化等級：

- `Auto`：可完全自動執行的步驟（例：variant calling、基本註解）。
- `Auto+Review`：系統先產生建議，需人工複核或有條件接受（例：ACMG 部分 evidence scoring）。
- `Human-only`：最終醫療判斷／用語／管理建議，必須由人決策（例：最終 Pathogenic 分類、臨床處置建議）。

每次分析需生成一份 **machine-readable log**，紀錄：

- 使用的模組與版本
- 每一步的自動化等級
- 哪些地方有人工 override（人員、時間、理由）

---

## 3. Phase 1：基因本體與變異詮釋基礎

### 3.1 功能需求

1. **輸入**
   - 本人與雙親外顯子定序 BAM 檔。
2. **輸出**
   - 高品質 joint VCF（含 trio）
   - 每個變異的註解資訊：
     - 基因、轉錄本、蛋白改變
     - 族群頻率（gnomAD 等）
     - ClinVar 註解
     - 功能預測（SIFT/PolyPhen/CADD 等）
   - 對特定疾病/基因清單的變異過濾結果。
3. **對外服務**
   - 以 API / 函式介面提供：
     - 給定基因列表 → 回傳該個體在這些基因中的變異列表
     - 支援疾病名稱/HPO → 基因 → 變異的查詢流程（初期可分步呼叫）

### 3.2 模組設計

#### 3.2.1 Variant Calling Pipeline

- **輸入**：BAM（本人 + 父母）
- **輸出**：個別 gVCF → joint VCF
- **工具候選**：
  - GATK（HaplotypeCaller + GenotypeGVCFs）
  - 或 DeepVariant + joint genotyper
- **自動化等級**：`Auto`
- **需求**：
  - 基本 QC（coverage、duplicate rate、on-target rate）
  - 支援版本標記（如 reference genome 版本）

#### 3.2.2 Annotation Pipeline

- **輸入**：joint VCF
- **輸出**：annotated VCF / 變異表
- **工具候選**：
  - VEP、ANNOVAR 或類似工具
- **資料庫**：
  - ClinVar
  - gnomAD
  - 基因功能與轉錄本資料庫
- **自動化等級**：`Auto`

#### 3.2.3 Genomic DB / Query API

- **目的**：提供高效查詢，作為後續模組（疾病風險、PGx 等）的基底。
- **形式**：
  - 選項 A：基於 VCF + tabix，以封裝函式操作
  - 選項 B：匯入 SQLite / PostgreSQL / 專用 genomic DB
- **關鍵查詢**：
  - `get_variants_by_gene(individual_id, gene_list, filters)`
  - `get_variants_by_region(individual_id, chr, start, end, filters)`
- **自動化等級**：`Auto`

#### 3.2.4 疾病/表型 → 基因 → 變異流程

- 初期可拆成三步：
  1. 使用外部知識庫或手動 panel：疾病/表型 → 基因清單
  2. 透過 Genomic DB 查詢個人變異
  3. 以簡單規則（頻率、ClinVar 標註）做初步排序
- **自動化等級**：`Auto+Review`

### 3.3 ACMG 規則實作（初版）

- **範圍**：僅實作部分機器可自動判定之 evidence（如 PVS1、PM2、BA1、BS1 等）。
- **輸出**：
  - 每個變異的 evidence tag 列表與建議分級（例如：`suggested_class = "VUS"`）
- **人工介入點**：
  - 變異最終分類（Pathogenic / Likely pathogenic / VUS / Likely benign / Benign） → `Human-only`
  - 規則閾值（如頻率 cutoff）以 config 檔管理 → `Auto+Review`

---

## 4. Phase 2：基因藥物學（PGx）與藥–藥交互作用（DDI）

### 4.1 功能需求

1. 接收使用者目前用藥清單（處方藥、成藥）。
2. 透過基因資料，判定與 PGx 相關的 genotype（例如 CYP2D6, CYP2C9, HLA 等）。
3. 根據 CPIC / DPWG 等指南，給出：
   - 適應症相關風險（如 HLA-B*58:01 與 allopurinol）
   - 劑量調整建議 / 藥物替代建議（僅 decision-support 層級）
4. 計算基礎藥–藥交互作用（DDI），例如：
   - CYP 抑制 / 誘導疊加
   - QT prolongation 疊加
   - 出血風險疊加

### 4.2 模組設計

#### 4.2.1 用藥資料標準化

- 使用 ATC / RxNorm / 自訂 ID。
- **自動化等級**：`Auto`

#### 4.2.2 PGx Engine

- **輸入**：個人變異（Phase 1 DB）、藥物清單
- **輸出**：每個藥物的 PGx 評估（genotype → phenotype → 建議）
- **資料庫**：
  - CPIC guidelines
  - PharmGKB 關聯資料
- **自動化等級**：
  - genotype → phenotype：`Auto`
  - phenotype → 臨床建議：`Auto+Review`

#### 4.2.3 DDI Engine

- **輸入**：藥物清單
- **輸出**：已知 DDI 清單與嚴重程度分級
- **資料來源**：公開或商用 DDI 資料庫（視可用性）
- **自動化等級**：`Auto`

---

## 5. Phase 3：保健食品與中藥交互作用模組

### 5.1 功能需求

1. 接收使用者的保健食品與中藥使用資料。
2. 將名稱解析為：
   - 標準化有效成分（如 EPA/DHA mg、Vit D IU、銀杏葉萃取物 mg 等）
   - 中藥材名稱（如 黃耆、當歸、川芎…）
3. 評估：
   - 成分與藥物、基因的交互作用風險
   - 成分間的加乘作用（如抗凝、CNS 抑制等）
4. 按證據等級給出：
   - 高優先級警示（有較強臨床證據）
   - 一般提醒（動物實驗 / case report 等）
   - 資料不足，僅能提醒不確定性

### 5.2 模組設計

#### 5.2.1 成分標準化引擎

- **輸入**：使用者輸入的品名 / 處方
- **輸出**：
  - 標準化成分列表
  - 估計劑量範圍（若無精確資料）
- **資料**：
  - 保健食品常用成分資料表
  - 中藥方與藥材對應表
- **自動化等級**：`Auto+Review`

#### 5.2.2 成分交互作用引擎

- **輸入**：成分列表、藥物清單、基因資料
- **輸出**：交互作用列表與風險層級
- **邏輯**：
  - 成分對 CYP / P-gp / OATP 等的影響
  - 成分對凝血、血壓、中樞神經等系統的影響
- **自動化等級**：
  - 規則推論：`Auto`
  - 最終臨床建議表述：`Human-only`

---

## 6. Phase 4：NLP/LLM 問答介面與報告生成

### 6.1 功能需求

1. 支援使用者以自然語言提問：
   - 疾病/症狀相關風險
   - 用藥安全性
   - 保健食品、中藥併用風險
2. LLM 負責：
   - 問題解析 → 結構化查詢（疾病、HPO、藥物、成分等）
   - 協調呼叫底層 API（Phase 1–3）
   - 整合結果並生成報告草稿
3. 報告形式：
   - 機器可讀 JSON（便於後處理）
   - 人類可讀 Markdown / PDF 報告

### 6.2 Orchestration 設計

- 可採用「LLM + Tool/Function Calling」模式：
  - 工具包括：
    - `query_variants_by_gene`
    - `query_disease_gene_panel`
    - `run_pgx_analysis`
    - `run_ddi_analysis`
    - `run_supplement_herb_interaction`
- LLM 主要負責：
  - 意圖辨識與拆解
  - 工具呼叫順序規劃
  - 結果解釋與用語調整（需符合安全與保守原則）
- **自動化等級**：
  - 工具呼叫：`Auto`
  - 臨床敏感結論：`Auto+Review` / `Human-only`（視場景而定）

---

## 7. 安全性、隱私與版本管理

### 7.1 資料安全與隱私

- 所有基因資料、用藥清單、報告：
  - 儲存於本地或受控環境
  - 若需與外部服務（如雲端 LLM）互動，需：
    - 做脫敏處理（移除個資）
    - 或改用 local/私有 LLM

### 7.2 版本管理

- 對以下物件進行版本控制：
  - 參考基因組版本
  - variant calling pipeline 版本
  - 資料庫版本（ClinVar、gnomAD 等）
  - ACMG 規則 config 版本
  - gene panel / PGx 規則版本
- 每份分析報告需記錄所用版本，以利追蹤與重跑。

### 7.3 人工介入紀錄

- 每次人工 override 或審核需紀錄：
  - 變異 ID / 分析項目
  - 原自動建議
  - 人工調整結果
  - 理由與參考文獻（如有）
  - 審核者與時間

---

## 8. 未來擴充方向（Optional）

- 整合 polygenic risk score（PRS）模組
- 整合 longitudinal data（實驗室數據、症狀日誌）做風險動態追蹤
- 為特定疾病領域建立更深的 expert-curated knowledge base
- 與可穿戴裝置／其他健康資料源整合

---

## 9. 第一階段實作建議路線（Actionable TODO）

1. **規劃 Phase 1 的技術選型**
   - 選擇 variant caller（如 GATK）與 reference genome 版本
   - 選擇 annotation 工具（如 VEP 或 ANNOVAR）
2. **建立基本 pipeline**
   - BAM → gVCF → joint VCF（trio）
   - 加上基本 QC 報表
3. **建置簡單的 Genomic Query 介面**
   - 先以 CLI/Notebook 函式為主（例如 Python 函式庫）
4. **選一個你最關心的疾病領域**
   - 建立第一個 gene panel（例如視覺/聽力相關）
   - 實作 panel-based 查詢與變異列表輸出
5. **撰寫第一版報告模板**
   - 輸入：疾病名稱 + gene panel + 查詢結果
   - 輸出：簡易 Markdown 報告（含變異表 + 限制說明）
6. **逐步加入 ACMG 自動 evidence 標記與人工 review 流程**

這個規格書預期會在實作過程中持續更新，可視此為 v0.1 的起點版本。