GAMP5 Category 5 驗證策略 — Git-Based Quality System
本文件定義 GatherSystemTech 針對 FDA 21 CFR Part 11 合規軟體的驗證策略， 以 Git + GitHub + Linear 為核心品質管理工具。
1. 適用範圍
| 項目 | 說明 |
|---|---|
| 適用專案 | Jope-SMB（模擬移動床控制系統）及所有需符合 FDA 21 CFR Part 11 的軟體專案 |
| GAMP5 分類 | Category 5 — 客製化軟體（Custom/Bespoke Software） |
| 法規依據 | FDA 21 CFR Part 11 — Electronic Records; Electronic Signatures |
2. 品質管理工具組合
2.1 工具對應表
| 品質活動 | 工具 | 說明 |
|---|---|---|
| 需求管理 | Linear Issue | 每個需求對應一個 Issue，含描述、優先順序、狀態追蹤 |
| 變更管理 | Git + GitHub PR | 所有程式碼變更透過 PR 流程，含審查與核准 |
| 版本控制 | Git | 完整的變更歷史，不可竄改（搭配 Branch Protection） |
| 程式碼審查 | GitHub PR Review | Reviewer approve = 正式審查紀錄 |
| 測試管理 | Git commit + Test Agent | 測試結果記錄於 commit 與 PR 中 |
| 追蹤鏈 | Linear → Git → GitHub → Test | 端到端可追溯 |
| 文件版控 | Git repo（markdown） | 驗證文件以 markdown 格式納入版本控制 |
| 文件審核 | GitHub PR Review | 文件變更同樣透過 PR 審查流程 |
2.2 Git 已滿足的 FDA Part 11 要求
| FDA Part 11 要求 | Git/GitHub 對應 | 滿足程度 |
|---|---|---|
| Audit Trail（稽核軌跡） | git log、git blame — 記錄誰、何時、改了什麼 | 完全滿足 |
| Change Control（變更控制） | PR review + approve 流程 | 完全滿足 |
| Code Review（程式碼審查） | PR review comments、approve 紀錄永久保留 | 完全滿足 |
| Traceability（可追溯性） | Commit → PR → Linear Issue 完整追蹤鏈 | 完全滿足 |
| Attributable（可歸因） | 每個 commit 含 author + timestamp | 完全滿足 |
2.3 需要補強的部分
| FDA Part 11 要求 | 缺口 | 解決方案 | 複雜度 |
|---|---|---|---|
| Electronic Signature（電子簽章） | Git commit 不等於法規定義的電子簽章 | GPG signed commits + Branch Protection 要求簽章 | 中 |
| System Validation（系統驗證） | Git/GitHub 本身不是 validated system | 撰寫 IQ/OQ/PQ 驗證文件 | 中 |
| Access Control（存取控制） | 需證明權限管理是受控的 | GitHub Branch Protection Rules + 文件化權限矩陣 | 低 |
| Prevent Record Deletion（防止紀錄刪除） | git push --force 可竄改歷史 | 禁用 force push + Branch Protection | 低 |
| Reason for Change（變更理由） | 不一定每次都記錄「為什麼改」 | 強制 commit message 包含 Issue ID | 低 |
| Closed System（封閉系統） | GitHub 是雲端服務 | 撰寫安全控制文件，定義存取範圍 | 低 |
3. Git 工作流程（合規版）
3.1 Merge 策略
Squash Merge 為標準策略，所有 feature branch 合併至 master/develop 時使用。
| 優勢 | 說明 |
|---|---|
| 1:1 對應 | master 上一個 commit = 一個 PR = 一個 Linear Issue |
| 容易 Revert | 回滾一個功能只需 revert 一個 commit |
| 歷史乾淨 | git log --oneline master 直接作為版本變更記錄 |
| 稽核友善 | 每個 commit 都是完整、可追蹤的變更單元 |
3.2 分支生命週期
feature branch 建立 → 開發 → PR 建立 → Review + Approve → Squash Merge → 刪除 branch
- Feature branch 合併後必須刪除，避免分支雜亂
- 開發過程保留在 GitHub PR 中（所有原始 commits、diff、review 討論永久保留）
- Branch 刪除不影響任何歷史紀錄
3.3 追蹤鏈
git log → 查看「改了什麼」（每個 commit 帶 PR 編號）
GitHub PR (#N) → 查看「怎麼開發的」（原始 commits、diff、review）
Linear Issue (JOP-XXX) → 查看「為什麼做」（需求、開發指令、討論）
3.4 Branch Protection Rules（必須啟用）
| 規則 | 設定 |
|---|---|
| Require pull request reviews | 至少 1 位 reviewer approve |
| Require signed commits | GPG 簽章（電子簽章替代） |
| Do not allow force pushes | 禁止竄改歷史 |
| Do not allow deletions | 禁止刪除 protected branch |
4. 驗證文件架構
4.1 文件清單
| 文件編號 | 文件名稱 | 說明 | 狀態 |
|---|---|---|---|
| VP-001 | Validation Plan | 驗證策略、範圍、工具、角色定義 | 待撰寫 |
| SOP-001 | Software Development SOP | 軟體開發生命週期程序（含 Git 工作流程） | 待撰寫 |
| SOP-002 | Change Control SOP | 變更控制程序（含 PR review 流程） | 待撰寫 |
| SOP-003 | Testing SOP | 測試策略與程序 | 待撰寫 |
| RA-001 | Risk Assessment | 風險評估（FMEA 方法） | 待撰寫 |
| RTM-001 | Requirements Traceability Matrix | 需求追溯矩陣 | 待建立 |
| IQ-001 | Installation Qualification | 安裝確認報告 | 待撰寫 |
| OQ-001 | Operational Qualification | 操作確認報告 | 待撰寫 |
| PQ-001 | Performance Qualification | 效能確認報告 | 待撰寫 |
| VSR-001 | Validation Summary Report | 驗證總結報告 | 待撰寫 |
4.2 文件存放位置
{validation-repo}/
├── sop/
│ ├── SOP-001-software-development.md
│ ├── SOP-002-change-control.md
│ └── SOP-003-testing.md
├── validation/
│ ├── VP-001-validation-plan.md
│ ├── RA-001-risk-assessment.md
│ ├── RTM-001-traceability-matrix.md
│ └── reports/
│ ├── IQ-001-installation-qualification.md
│ ├── OQ-001-operational-qualification.md
│ ├── PQ-001-performance-qualification.md
│ └── VSR-001-validation-summary.md
├── templates/
│ └── (文件範本)
└── .github/
└── workflows/
└── pdf-export.yml ← markdown → PDF 自動化（稽核提交用）
4.3 文件管理流程
1. 撰寫/修改文件（markdown in Git）
↓
2. 建立 PR → Reviewer approve（= 正式文件簽核）
↓
3. Squash Merge（signed commit = 電子簽章）
↓
4. CI 自動產生 PDF（稽核提交用）
5. RTM（需求追溯矩陣）
5.1 用途
RTM 證明每個需求都有對應的實作和測試，稽核員可據此確認無遺漏。
5.2 格式
| 需求（Linear Issue） | 設計規格 | 實作（PR） | 測試方法 | 測試結果 | 狀態 |
|---|---|---|---|---|---|
| JOP-99：Recipe 版本控制 | Recipe Version Control Design | PR #14 | 單元測試 + 整合測試 | 通過 | ✅ |
| JOP-101：Alarm/Interlock | Alarm Classification Design | PR #12 | 單元測試 + 整合測試 | 通過 | ✅ |
| JOP-102：Backup/Recovery | Backup System Design | PR #13 | 單元測試 + 整合測試 | 通過 | ✅ |
5.3 自動化方案
現有工具鏈已具備自動產出 RTM 的條件：
Linear Issue（需求）
↓ Issue ID 記錄在 commit message
Git commit / PR（實作）
↓ PR 包含測試結果
Test Report（測試）
↓
腳本自動比對 → 產出 RTM 表格
自動化腳本可從以下來源收集資料：
- Linear API — 撈取所有 Issue（需求清單）
- Git log — 比對哪些 Issue 有對應的 commit/PR
- Test report — 比對測試結果
- 自動組出 RTM — 標記缺少實作或測試的需求
6. 電子簽章策略
6.1 GPG Signed Commits
| 項目 | 說明 |
|---|---|
| 目的 | 證明 commit 來自特定開發者，不可偽造 |
| 機制 | 每位開發者產生 GPG key pair，commit 時自動簽章 |
| 驗證 | GitHub 顯示 "Verified" 標記 |
| SOP 定義 | 在 SOP-001 中定義「GPG signed commit = 電子簽章」 |
6.2 PR Approve 作為簽核
| 角色 | 動作 | 等同於 |
|---|---|---|
| 開發者 | GPG signed commit | 開發者簽名 |
| 審查者 | PR approve | 審查者簽核 |
| 合併者 | Squash merge（signed） | 核准放行 |
7. 現有專案合規狀態
Jope-SMB（主要合規專案）
| 合規項目 | 實作狀態 | 說明 |
|---|---|---|
| User Management | ✅ Done | GST.Plugin.UserManagement（GST-14） |
| Audit Trail | ✅ Done | GST.Plugin.AuditTrail |
| Electronic Signature | ✅ Done（應用層） | 應用內電子簽名機制 |
| Session Idle Timeout | ✅ Done | SessionIdleService（GST-11） |
| NTP Time Sync | ✅ Done | NTP 時間同步（GST-10） |
| Recipe Version Control | ✅ Done | JOP-99 |
| Backup/Recovery | ✅ Done | JOP-102 |
| Alarm/Interlock | ✅ Done | JOP-101 |
| Data Export | ⬜ Backlog | JOP-100 |
| Device Validation | ⬜ Backlog | JOP-103 |
| 驗證文件 | ⬜ 未開始 | 本文件定義的文件架構 |
8. 後續行動
| 優先順序 | 項目 | 說明 |
|---|---|---|
| 1 | 啟用 Branch Protection | 禁止 force push、要求 PR review、要求 signed commits |
| 2 | 設定 GPG Signed Commits | 所有開發者產生 GPG key，設定自動簽章 |
| 3 | 撰寫 SOP-001 ~ SOP-003 | 將現行 Git 工作流程正式文件化 |
| 4 | 撰寫 VP-001 Validation Plan | 定義驗證策略與範圍 |
| 5 | 建立 RTM-001 | 從現有 Linear Issues 產出初版追溯矩陣 |
| 6 | 撰寫 RA-001 Risk Assessment | FMEA 風險評估 |
| 7 | 執行 IQ/OQ/PQ | 安裝/操作/效能確認 |
| 8 | 撰寫 VSR-001 | 彙整所有證據的驗證總結報告 |
| 9 | 建立 PDF Export Pipeline | CI/CD markdown → PDF 自動化 |
| 10 | RTM 自動化腳本 | Linear + Git → 自動產出追溯矩陣 |
文件版本：v1.0 建立日期：2026-03-16 最後更新：2026-03-16 負責人：PM Agent