火線超人 FHIRLinebot 操作及技術手冊
本手冊說明如何使用火線超人 FHIRLinebot 連結衛福部 THAS FHIR Server、進行病患身份綁定，以及使用地端 AI 分析健康資料。
目錄
1. 系統概觀
架構圖
flowchart LR
subgraph 使用者端
A[LINE 使用者<br/>手機 App]
end
subgraph 雲端服務 DigitalOcean
B[FHIRLinebot]
K[Kafka]
end
subgraph 衛福部
C[THAS FHIR<br/>Server]
end
subgraph 醫院內網
D[Kafka Consumer]
E[地端 AI 服務<br/>LLM]
D <--> E
end
A -->|LINE Messaging API| B
B -->|SMART on FHIR| C
B <--> K
K <-.->|Kafka Protocol| D
style 雲端服務 DigitalOcean fill:#e3f2fd
style 醫院內網 fill:#e8f5e9
style 衛福部 fill:#fff3e0
支援的 FHIR 資源
| 資源類型 | 說明 | 用途 |
|---|---|---|
| Patient | 病患基本資料 | 身份驗證、綁定 |
| Observation | 檢驗數值、生命徵象 | 健康趨勢分析 |
| MedicationRequest | 用藥紀錄 | 用藥提醒、交互作用檢查 |
| Condition | 診斷紀錄 | 病史摘要 |
| Encounter | 就診紀錄 | 就醫歷程追蹤 |
2. 與 THAS FHIR Server 綁定驗證
FHIRLinebot 提供兩種綁定方式，適用於不同情境：
| 方式 | 指令 | 適用情境 | 驗證方式 |
|---|---|---|---|
| OAuth 綁定 | /fhir bind |
THAS 等支援 OAuth 的伺服器 | FHIR Server 登入驗證 |
| 手動綁定 | /bind <病歷號> <生日> |
不支援 OAuth 的伺服器 | 生日驗證 |
2.1 OAuth 綁定（推薦）
使用 SMART on FHIR 標準進行 OAuth2 授權，適用於衛福部 THAS 等支援 OAuth 的 FHIR Server。
流程圖
sequenceDiagram
participant U as 使用者
participant L as LINE Bot
participant T as THAS FHIR Server
U->>L: /fhir bind 指令
L->>T: 產生授權連結
L-->>U: 回傳授權按鈕
rect rgb(240, 248, 255)
Note over U,T: 使用者點擊按鈕，跳轉 THAS 登入頁
U->>T: 登入並授權
end
T-->>L: 授權碼 (code)
L->>T: 交換 Access Token
T-->>L: Token + Patient ID
L-->>U: 綁定成功
操作步驟
步驟 1：發起綁定
在 LINE 聊天室輸入：
/fhir bind
或指定特定伺服器：
/fhir bind -s thas
步驟 2：點擊授權按鈕
系統會回傳 Flex Message，包含「開始授權」按鈕。點擊後會跳轉至 THAS 登入頁面。
步驟 3：登入授權
- 在 THAS 頁面使用您的帳號登入
- 確認授權 FHIRLinebot 存取您的健康資料
- 授權完成後自動跳轉回 LINE
授權範圍 (Scopes)：
| Scope | 說明 |
|---|---|
patient/Patient.read |
讀取病患基本資料 |
patient/Observation.read |
讀取檢驗數值 |
patient/Condition.read |
讀取診斷紀錄 |
patient/MedicationStatement.read |
讀取用藥紀錄 |
patient/Encounter.read |
讀取就診紀錄 |
步驟 4：綁定完成
授權成功後，您會收到確認訊息：
已連結
衛福部 THAS
病患 ID: Patient/123456
狀態: 有效
OAuth 相關指令
| 指令 | 說明 |
|---|---|
/fhir bind |
綁定預設 FHIR Server |
/fhir bind -s thas |
綁定指定 Server |
/fhir unbind |
解除連結 |
/fhir status |
查看連線狀態 |
2.2 手動綁定（生日驗證）
適用於不支援 OAuth 的 FHIR Server，或需要綁定他人（如家屬）的情境。
流程圖
sequenceDiagram
participant U as 使用者
participant L as LINE Bot
participant F as FHIR Server
U->>L: /bind Patient/123 1990-01-15
L->>F: 查詢 Patient/123
F-->>L: 病患資料（含生日）
L->>L: 比對生日是否相符
alt 生日相符
L-->>U: 綁定成功
else 生日不符
L-->>U: 驗證失敗
end
操作步驟
步驟 1：輸入綁定指令
格式：/bind <病歷號> <生日>
/bind Patient/123456 1990-01-15
或使用中文指令：
綁定 Patient/123456 1990-01-15
支援的日期格式：
- YYYY-MM-DD（例如：1990-01-15）
- YYYY/MM/DD（例如：1990/01/15）
- YYYYMMDD（例如：19900115）
步驟 2：系統驗證
系統會從 FHIR Server 取得病患資料，比對您輸入的生日是否與記錄相符。
步驟 3：綁定結果
驗證成功：
綁定成功！已綁定病患：王小明
驗證失敗：
驗證失敗，請確認病歷號和生日是否正確。
手動綁定相關指令
| 指令 | 說明 |
|---|---|
/bind <病歷號> <生日> |
綁定並驗證 |
/unbind <病歷號> |
解除綁定 |
/mypatients |
列出所有綁定 |
/switch <病歷號> |
切換主要病患 |
2.3 多病患綁定
FHIRLinebot 支援一個 LINE 帳號綁定多個病患（例如家庭成員）：
- OAuth 綁定：可連結多個支援 OAuth 的 FHIR Server
- 手動綁定：可綁定多個病患，用生日驗證身份
查看所有綁定：
/mypatients
輸出範例：
您綁定的病人：
- 王小明 (Patient/123456) [主要] [OAuth]
衛福部 THAS
- 王媽媽 (Patient/789012)
衛福部 THAS
切換主要病患：
/switch Patient/789012
2.4 Token 管理（OAuth 綁定）
- Access Token 有效期：依 THAS 設定（通常 1 小時）
- Refresh Token：系統自動刷新，使用者無需重新登入
- Token 加密儲存：所有 Token 使用 Rails 加密機制保護
查看連線狀態：
/fhir status
輸出範例：
FHIR 連線狀態
衛福部 THAS 有效
Patient: Patient/123456
3. LINE Bot 基本指令
健康資料查詢
| 指令 | 中文指令 | 說明 |
|---|---|---|
/myrecord |
我的病歷 |
顯示完整病歷（生命徵象+檢驗+診斷） |
/vitals |
生命徵象 |
查看生命徵象 |
/vitals 體重 |
- | 查看體重歷史圖表 |
/vitals 血壓 |
- | 查看血壓歷史圖表 |
/labs |
檢驗報告 |
查看檢驗報告 |
支援的歷史查詢項目：
| 指令 | 說明 |
|---|---|
/vitals weight 或 /vitals 體重 |
體重趨勢 |
/vitals height 或 /vitals 身高 |
身高記錄 |
/vitals bp 或 /vitals 血壓 |
血壓趨勢 |
/vitals hr 或 /vitals 心跳 |
心率趨勢 |
/vitals glucose 或 /vitals 血糖 |
血糖趨勢 |
/vitals hba1c 或 /vitals 糖化血色素 |
HbA1c 趨勢 |
帳號管理 - OAuth 綁定
| 指令 | 說明 |
|---|---|
/fhir bind |
OAuth 綁定（跳轉登入頁） |
/fhir bind -s <server> |
綁定指定 FHIR Server |
/fhir unbind |
解除 OAuth 連結 |
/fhir status |
查看 OAuth 連線狀態 |
帳號管理 - 手動綁定
| 指令 | 說明 |
|---|---|
/bind <病歷號> <生日> |
手動綁定（需生日驗證） |
/unbind <病歷號> |
解除手動綁定 |
/mypatients |
列出所有綁定（含 OAuth 和手動） |
/switch <病歷號> |
切換主要病患 |
AI 分析
| 指令 | 中文指令 | 說明 | 狀態 |
|---|---|---|---|
/ai |
AI分析 或 健康分析 |
顯示分析類別選單 | 已支援 Kafka |
/ai <問題> |
- | 直接詢問特定問題 | Pending |
注意：
/ai <問題>目前尚未整合 Kafka 機制，暫時無法使用。待後續版本實作。
分析類別（透過選單選擇）：
- 完整分析 - 分析所有健康資料
- 用藥分析 - 分析用藥紀錄
- 檢驗分析 - 分析檢驗數值
- 診斷分析 - 分析診斷紀錄
- 就診分析 - 分析就診紀錄
4. 地端 AI 健康分析
4.1 架構說明
FHIRLinebot 使用 Kafka 訊息佇列 將健康資料傳送至醫院內網的 AI 服務進行分析，確保敏感資料由院內 AI 處理。
flowchart LR
subgraph 雲端服務 DigitalOcean
A[FHIRLinebot]
K[Kafka Broker]
end
subgraph 醫院內網
B[Kafka Consumer<br/>Python]
C[地端 AI 服務<br/>LLM]
B <--> C
end
A -->|"Produce<br/>ai.request topic"| K
K -.->|"Consume"| B
B -.->|"Produce<br/>ai.response topic"| K
K -->|"Consume"| A
style 雲端服務 DigitalOcean fill:#e3f2fd
style 醫院內網 fill:#e8f5e9
資料流向：
1. FHIRLinebot 從 THAS 取得健康資料後，發送至 Kafka ai.request topic
2. 醫院內網的 Consumer 消費訊息，呼叫地端 LLM 進行分析
3. 分析結果發送回 Kafka ai.response topic
4. FHIRLinebot 接收結果並推送給用戶
4.2 使用 AI 分析
步驟 1：發起分析
輸入指令：
/ai
系統會顯示分析選項：
AI 健康分析
請選擇分析類型：
[完整分析] - 分析所有健康資料
[用藥分析] - 分析用藥紀錄與交互作用
[檢驗分析] - 分析檢驗數值趨勢
[診斷分析] - 分析診斷紀錄與建議
步驟 2：等待分析
點選分析類型後，系統會：
- 從 FHIR Server 取得您的健康資料
- 透過 Kafka 發送至地端 AI 服務
- AI 模型進行分析（使用醫院內部 LLM）
正在分析您的健康資料...
此過程可能需要 30-60 秒，分析完成後會通知您。
[查看進度]
步驟 3：查看結果
分析完成後，您暫時不會收到通知，請手動查詢：
AI 分析完成！
[查看分析報告]
點選按鈕查看詳細報告：
健康分析報告
分析時間：2024-01-15 14:30
【用藥摘要】
目前使用 3 種藥物，無明顯交互作用風險。
【檢驗趨勢】
- 血糖：近 3 個月呈下降趨勢，控制良好
- 血壓：維持在正常範圍
- 膽固醇：略高，建議持續監測
【健康建議】
1. 持續目前的用藥計畫
2. 建議每日監測血壓
3. 飲食上減少高脂肪食物攝取
---
本分析由 AI 產生，僅供參考，如有疑問請諮詢醫師。
4.3 自訂問題分析
您也可以針對特定問題進行分析：
/ai 我的血糖控制得如何？
或
/ai 這些藥物有沒有交互作用的風險？
4.4 資料安全保障
| 保護措施 | 說明 |
|---|---|
| 網路隔離 | DigitalOcean 防火牆限制來源 IP |
| 地端處理 | AI 分析在醫院內網執行 |
| 資料不留存 | 分析完成後原始資料自動刪除 |
| 結果快取 | 僅保留 30 分鐘供查閱 |
注意：目前 Kafka 外部連線使用 PLAINTEXT，建議生產環境啟用 TLS 加密。
5. Kafka 安全機制
5.1 架構安全設計
FHIRLinebot 的 Kafka 部署採用多層安全架構：
flowchart TB
subgraph 雲端服務 DigitalOcean
subgraph docker["Docker Network"]
A[FHIRLinebot]
B[Kafka Broker<br/>KRaft Mode]
A <-->|"INTERNAL<br/>Port 9095"| B
end
end
subgraph 防火牆
FW{{"DigitalOcean 防火牆<br/>Port 9094 限制來源 IP"}}
end
subgraph 醫院內網
C[Kafka Consumer<br/>Python]
D[地端 AI<br/>LLM]
C <--> D
end
B -->|"EXTERNAL<br/>Port 9094"| FW
FW <-.-> C
style 雲端服務 DigitalOcean fill:#e3f2fd
style 醫院內網 fill:#e8f5e9
5.2 網路層安全
防火牆規則
| 來源 | 目的埠 | 用途 | 狀態 |
|---|---|---|---|
| 雲端服務 IP | 9094 | Kafka EXTERNAL | 已啟用 |
| 醫院 VPN | 9095 | Kafka INTERNAL | 已啟用 |
| 其他 | * | 拒絕 | 已啟用 |
Listener 隔離
# config/deploy.yml (Kamal accessories)
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093,EXTERNAL://:9094,INTERNAL://:9095"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://localhost:9092,EXTERNAL://fhirlinebot.turbos.tw:9094,INTERNAL://fhirlinebot-kafka:9095"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,EXTERNAL:PLAINTEXT,INTERNAL:PLAINTEXT"
| Listener | Port | 用途 | 安全協議 |
|---|---|---|---|
| PLAINTEXT | 9092 | 本機測試 | 無加密 |
| CONTROLLER | 9093 | KRaft 控制器 | 無加密 |
| EXTERNAL | 9094 | 外部連線 | PLAINTEXT（建議升級 SSL） |
| INTERNAL | 9095 | 容器間通訊 | 無加密 |
6. 常見問題排解
Q1: OAuth 綁定時出現「授權失敗」
可能原因：
- THAS 帳號密碼錯誤
- 授權逾時（超過 10 分鐘）
- 該 FHIR Server 不支援 OAuth
解決方法：
1. 重新輸入 /fhir bind 發起綁定
2. 確認 THAS 帳號密碼正確
3. 在 10 分鐘內完成授權流程
4. 如伺服器不支援 OAuth，改用手動綁定 /bind
Q2: 手動綁定時生日驗證失敗
可能原因：
- 輸入格式錯誤
- 生日與 FHIR Server 記錄不符
- 病歷號不存在
解決方法：
1. 確認格式為 YYYY-MM-DD（例如：1990-01-15）
2. 確認與醫院登記的出生日期一致
3. 確認病歷號正確（通常格式為 Patient/123456）
4. 如資料有誤，請聯繫醫院更正
Q3: OAuth Token 過期
可能原因：
- Refresh Token 已過期
- THAS 伺服器撤銷授權
解決方法：
1. 輸入 /fhir status 確認狀態
2. 如顯示「需要重新授權」或「已過期」，請重新 /fhir bind
Q4: AI 分析沒有回應
可能原因：
- Kafka 連線問題
- AI 服務暫停
解決方法：
1. 等待 5 分鐘後重試
2. 輸入 /ai status 查看服務狀態
3. 如持續無回應，請聯繫管理員
Q5: 看不到健康資料
可能原因：
- 尚未完成綁定
- 授權 Scope 不足
- FHIR Server 無該項資料
解決方法：
1. 輸入 /mypatients 確認綁定狀態
2. 確認授權時已勾選所有項目
3. 該項資料可能尚未在 FHIR Server 建立
A. 聯絡資訊
如有問題或建議，請聯繫：