專案受評範圍合併（Audit Scope Consolidation）— 設計文件

狀態：設計確認中｜範圍：Frontend only｜估時：3-5 天 建立日期：2026-04-25｜作者：Raymond + Claude

「資訊系統 (Information System, IS)」與「設備 (Device)」目前在兩個專案設定畫面裡分別佔據獨立的步驟 / Tab。從 user 視角來看，兩者都是「這個專案要稽核的範圍」之組成元件，分散在不同 step / tab 造成認知負擔。

本次需求：將兩者在 UI 層合併到單一區塊「受評範圍」，但保留現有資料模型與後端不動，作為將來 OSCAL SSP 匯出 / 跨模組引用的階段性踏腳石。

涉及的兩個畫面

✅ 目標

• 把 IS 和 Device 的 picker 合併到一個 section「受評範圍」（Audit Scope）
• ProjectSettings：4 tabs → 3 tabs
• ProjectCreate：5 steps → 4 steps，順序調整為「基本資訊 → 參與者 → 受評範圍 → 確認」
• 兩個畫面共用一個新元件 AuditScopeSection.vue（包裝既有 SystemPicker + DevicePicker）
• 不影響任何既有功能 / API / DB 行為

❌ 非目標（明確排除）

• 不動 BE：update_project API、PUT /api/1.0/grc-project/<id> request shape、各 service 全部維持
• 不動 schema：information_systems、devices、project_information_systems、project_device_mapping、job_execution_device_mapping、evidence 全部不動
• 不動既有元件本身：SystemPicker.vue / DevicePicker.vue / DeviceManage.vue / InformationSystemManage.vue
• 不動 jedi-device 套件 / jedi_information_system 模組
• 不引入 ComponentService / ComponentPicker / FK 關聯
• 不做 OSCAL SSP exporter
• 不動 device 相關的高耦合區（job_execution_device_mapping、evidence.ref_id、device_view 聚合 SQL）

3.1 評估的方案

針對「合併」二字，討論過 5 個層次的方案：

3.2 為什麼選 E

關鍵發現（透過外部 reference 掃描）：

1. Device 在 runtime 重度耦合：

   • job_execution_device_mapping — job 完成判定要 device 全完成
   • evidence.ref_id == device_uid — 證據檔靠 device_uid 分類
   • 有獨立 device_view 複雜聚合 SQL（job × device × evidence × subtask × assignee）

2. IS 相對輕量：只在 project 啟動時做一次性 OSCAL SSP system_characteristic 快照，settings 改 IS 不會影響跑中的 job

3. 存檔流程超簡單：project_service.update_project 對 audit_systems / devices 都是 M2M replace，沒有任何 cascade。UI 怎麼合都不會打壞 BE

4. OSCAL SSP 匯出是 future：用戶確認 Phase 1 不做匯出。匯出時可選 (a) 純讀現有表 (b) 加 mapping 小表 (c) 加 FK 到 device — 三條路在 Phase 1 都不需 lock-in

5. E → 任一條 Phase 2 路線的 throwaway 小：picker UI 元件約 3-5 天會被換掉，但 tab 結構、版面、route 都能保留

3.3 Phase 2 方向（不在本次計畫）

當未來決定要做 OSCAL SSP 匯出時，可選擇：

• (a) 純讀既有表：直接 query information_systems + devices，產出兩個獨立的 OSCAL component / inventory-item 區塊，不改 schema
• (b) 加 mapping 小表：新增 device_system_mapping(device_id, system_id)，只在匯出時用，不動既有表
• (c) 加 FK 到 device + ComponentService（D 方案完整版）：device.information_system_id + 樹狀 ComponentPicker + UI 表達層級

Phase 1 的設計對以上三條路徑都中立。

ProjectCreateView.vue           ProjectSettingsView.vue
       │                                 │
       └────────────┬────────────────────┘
                    │
                    ▼
         AuditScopeSection.vue  ◄── 新元件（本次新增）
                    │
        ┌───────────┴───────────┐
        ▼                       ▼
SystemPicker.vue (既有)    DevicePicker.vue (既有)
        │                       │
        ▼                       ▼
   API.INFORMATION_       API.DEVICES /
   SYSTEMS_MENU           menuStore.deviceMenu

存檔仍走既有 API：

SystemPicker.@change → syncProjectSystems()
   → PUT /api/1.0/grc-project/<id>  body: { audit_systems: [...] }

DevicePicker.@change → syncProjectDevices()
   → PUT /api/1.0/grc-project/<id>  body: { devices: [...] }

兩支 sync function 維持獨立呼叫（不做合併呼叫）。

5.1 ProjectSettingsView：4 tabs → 3 tabs

Tab header 計數：分開顯示「3 系統 / 5 設備」格式（不用加總）。

5.2 ProjectCreateView：5 steps → 4 steps

確認頁區段：原本 4 區段（基本 / 系統 / 參與者 / 設備）→ 3 區段（基本 / 參與者 / 受評範圍）。受評範圍區段內部展開兩個子區塊：「資訊系統」+「設備」。

5.3 新元件：AuditScopeSection.vue

位置：src/components/grc/AuditScopeSection.vue

版面（上下堆疊，stacked）：

┌─ 受評範圍 ───────────────────────────┐
├─────────────────────────────────────┤
│ 📦 資訊系統  [+ 新增] [搜尋...]        │
│   • 人事系統                         │
│   • 財務系統                         │
├─────────────────────────────────────┤
│ 💻 設備  [+ 新增] [搜尋...]           │
│   • ap-server-01                    │
│   • db-server-01                    │
└─────────────────────────────────────┘

Props：

interface Props {
  // System
  selectedSystemIds: string[]
  selectedSystemDetails: Record<string, any>
  infoSystemMenu: { id: string; name: string; abbreviation: string | null }[]
  // Device
  selectedDevices: string[]
  selectedDeviceDetails: Record<string, any>
  deviceMenu: any[]
  // Shared
  userMenu: any[]
  readonly?: boolean
  confirmBeforeRemove?: boolean
}

Emits：

defineEmits<{
  // System
  'update:selectedSystemIds': [string[]]
  'update:selectedSystemDetails': [Record<string, any>]
  'update:infoSystemMenu': [{...}[]]
  'change-systems': []
  // Device
  'update:selectedDevices': [string[]]
  'update:selectedDeviceDetails': [Record<string, any>]
  'change-devices': []
  'device-created': []
  'device-detail-saved': []
}>()

內部結構：使用 v-model 雙向綁定既有 SystemPicker / DevicePicker 的所有 props，emit 透傳父層。元件本身不做 API 呼叫、不存狀態，純粹是 layout wrapper。

不顯示：「未來支援層級關聯」hint（user 確認不要）。

後續調整（v0.2）：實作後 user 試用發現「合併 tab 沒有 Save 按鈕」與其他有 Save 的 tab 並列產生違和感（沿用原本即時 sync 設計）。後加上：

• Settings 模式下加 ⓘ 小字 hint「本區塊變更會即時自動儲存」（i18n key section_audit_scope_autosave_hint）
• syncProjectSystems / syncProjectDevices 成功後 toast「已自動儲存」（life 1500ms，i18n key toast_autosaved）
• Create 模式（wizard）不顯示此 hint，因為 wizard 是 deferred save 不是即時 sync

6.1 新增 key（zh-tw + en 同步）

註：project_settings.section_audit_scope（純標題、不含 desc）原本也有定義但未被消費，留待 cleanup PR 移除。

6.2 保留 key

section_audit_systems / section_devices / tab_audit_systems / tab_devices 仍由內部 SystemPicker / DevicePicker 使用，保留不刪。PR review 時再決定要不要清理舊的 tab key。

6.3 檔案路徑

依專案既有 i18n 切分慣例（待 implementer 在 implementation 階段確認實際 file 結構）：

• src/config/locales/i18n/zh-tw/project-settings.json（或對應檔）
• src/config/locales/i18n/en/project-settings.json

PUT /api/1.0/grc-project/<id> 已支援以下三種 request body：

// 只更新系統
{ "audit_systems": [{"information_system_uid": "..."}, ...] }

// 只更新設備
{ "devices": [{"device_uid": "..."}, ...] }

// 同時更新（也支援，但 Phase 1 不使用此模式）
{ "audit_systems": [...], "devices": [...] }

Phase 1 維持目前 FE 的「即時 sync 各自呼叫」模式：使用者勾選系統 → 立刻 PUT audit_systems；勾選設備 → 立刻 PUT devices。不做合併呼叫。

1. 建 AuditScopeSection.vue：先獨立元件，定義 props/emits 介面
2. i18n 加 key：兩語系同步加（zh-tw + en），先不刪舊 key
3. 改 ProjectSettingsView.vue：tab 合併（4 → 3），用 AuditScopeSection 取代原 tab 2 + tab 4
4. 改 ProjectCreateView.vue：step 重排（5 → 4，順序 (2)），確認頁區段更新
5. i18n key audit：grep 確認沒有 dead key
6. 建立 changelog：docs/changelog/2026-04-25-audit-scope-merge.md

9.1 ProjectSettings 手測

• 既有專案開啟 → 「受評範圍」tab 顯示，原選的系統 / 設備正確帶出
• 系統區塊：搜尋、選 / 取消、展開詳情、新增系統 → 即時 sync（network tab 看 PUT request body 含 audit_systems）
• 設備區塊：搜尋、選 / 取消、展開詳情、新增設備 → 即時 sync（PUT body 含 devices）
• 切到別的 tab 再切回，狀態保留
• readonly user（非 manager）→ 兩區塊都 readonly
• tab header 計數正確顯示「3 系統 / 5 設備」格式
• 系統 / 設備數量為 0 時也正確顯示

9.2 ProjectCreate 手測

• 4 step 流程順走：基本資訊 → 參與者 → 受評範圍 → 確認 → 建立成功
• 受評範圍 step：兩區塊都能新增 / 移除
• 確認頁：受評範圍區段內列出系統 + 設備兩個子清單
• 從確認頁回上一步編輯，回來資料還在
• 跳過受評範圍（兩區塊都空）→ 建立成功（既有 BE 允許 audit_systems / devices 為空 list）

9.3 Regression（重點顧及，必跑）

• ProjectAuditorOverview 不受影響（顯示 systems / devices 正確）
• JobExecutionDrawer 不受影響（device 列表正常）
• DeviceManage（獨立管理頁）不受影響
• InformationSystemManage（獨立管理頁）不受影響
• BE log 確認 PUT request body 結構不變（重點：仍是 audit_systems / devices 兩個 key 各自獨立 sync）
• OSCAL Project start 流程（POST /oscal-project/start）不受影響

9.4 i18n 測試

• zh-tw 語系：所有新加 key 顯示正確、無 raw key 漏翻
• en 語系：同上
• 切換語系時 tab header / step header 即時更新

依 CLAUDE.md 規範，PR 落地時必須建立：

• docs/changelog/2026-04-25-audit-scope-merge.md

內容包含：需求說明 / 變更檔案清單 / 行為差異（無 API 變更）/ 參考連結到本 design doc。

• 實作計畫文件（之後寫）：docs/features/FR-017-2604-audit-scope-merge/implementation-plan.md
• 變更紀錄：docs/changelog/2026-04-25-audit-scope-merge.md（PR 落地時建立）