---
title: FR-163 專案總覽證據視角：設計
status: 定案（2026-10-25 決策者口頭核可 D2 雛形）
---

# FR-163 專案總覽「證據視角」

## 一句話

專案總覽頁右上加一組「控制項視角｜證據視角」切換；切到證據視角後，左樹沿用並多一層到評估目標，右邊永遠是一張平的證據清單（檔案可預覽／下載、連結直接開），每列寫它掛在哪些評估目標、屬於哪個任務。只看不改。

## 為什麼

現在要看某條評估目標交了哪些檔，得點群組 → 展開控制項 → 展開評估目標 → 展開任務 → 開抽屜，四層才看到檔名。PM／顧問要盤「這個控制項證據齊不齊」「哪些 AO 一份都沒有」，只能一條條點。

## 決策

| # | 決策 | 理由 | 被排除 |
|---|---|---|---|
| D1 | **入口在專案總覽頁本身**，右上切換，不另開頁 | 左樹、麵包屑、輪次切換都已在這頁，使用者的心智是「同一個專案換個角度看」 | 獨立頁（多一條路徑、多一次載入） |
| D2 | **右邊永遠一張表、一組表頭**；左樹只縮範圍（像 Google Drive 點資料夾） | 決策者實看巢狀分段版後退回「很難看、不友善」。業界（Drata／Vanta 證據庫、Finder／SharePoint）一致：清單平鋪、歸屬用欄位表達。表格 UX 共識：巢狀上限兩層、不准手風琴包手風琴 | D 版「選群組→依控制項分段卡片→再依 AO 分段卡片」 |
| D3 | **「位置」欄**寫每份證據掛在哪些評估目標（編號標籤＋**完整名稱**，一個 AO 一行，超過三個收成「還有 N 個…」）；選群組時行首多控制項代號；選到 AO 時此欄不顯示 | 一個檔對到五個 AO 只出一列，同時解掉「同檔重複五次」；完整名稱是決策者明示（只有 obj.N 看不懂） | 只顯示 obj.N 標籤 |
| D4 | **分段是選配**：工具列「不分段｜依控制項｜依評估目標」，開了只在同一張表插群組標題列；無證據的 AO 在分段模式出一列灰字「尚無證據」 | 缺口不能被藏掉，但預設不逼使用者看分段 | 預設分段 |
| D5 | **沒有狀態欄**（不顯示已採納／待審／退回） | 查過：`compliance.job_evidences` 沒有審核狀態欄；FR-142 的「採用」記在稽核結果那邊且明寫「不改任務端資料、不標有效無效」。雛形早期假資料的「退回原因」是編的，已拿掉 | 自己發明一套證據狀態 |
| D6 | **連結型證據**照 Drata 做法當正式證據列出（標題＋網址，點了開新分頁） | `job_evidences.evidence_type=LINK`、`reference_url`、`description` 早就存在，任務抽屜已能加；Drata 的來源型別本來就是 File／URL／Ticket 並列 | — |
| D7 | 每列帶「所屬任務」，點了開現有 `JobExecutionDrawer`；**要加檔、改連結回抽屜做**，本頁不提供寫入 | 寫入的守門、上傳、Drive 同步全在抽屜，不重做一套 | 列上直接刪／改對應 |
| D8 | **左右分隔用 PrimeVue `Splitter`**，照 `EvidenceClassificationReview.vue:433` 的用法（`:gutter-size="6"`、`state-key`、`state-storage="local"`） | 決策者明示「有現成的就不要自己硬寫」；雛形的純 JS 版只是模擬行為 | 自寫拖曳 |
| D9 | **資料來源沿用 control-tree**（`GET /ssp/<ssp_uid>/control-tree`），不開新的彙總端點；BE 只把 tree 裡每筆證據的欄位補齊（上傳者、時間、檔案 uid、大小） | 專案總覽頁本來就一次載入整棵樹，每個任務底下已帶 `evidences[]`（`ssp_control_implementation_service.py:554`），缺的只是四個欄位；再開一支端點＝第二套真相 | 新 `GET /audit-round/<uid>/evidences` 彙總端點 |
| D10 | 問卷型證據（SURVEY）第一版不列 | tree 把問卷放在 `job.surveys[]` 另一條路、欄位形狀不同；問卷不是「檔」，使用者口述的痛點是檔案與連結 | 三型合一 |

## 畫面（以 D2 雛形為準）

雛形：`prototype/d2-evidence-flat.html`（決策者 2026-10-25 核可）。雛形只取結構與行為，**不取字級、字型、配色**——FE 一律 `dark-card`＋全站字級。

- 頁首右側：`SelectButton`「控制項視角｜證據視角」，放在「匯出」類按鈕左邊；切換狀態記 `localStorage`（key 含專案 uid）。
- 左欄（`SplitterPanel` 約 320px，min 220）：沿用現有群組→控制項樹，證據視角下**控制項可再展開評估目標**；群組與控制項列尾顯示「N 份」（去重後的證據數），評估目標列尾顯示該 AO 的份數，0 份紅字。搜尋框沿用。
- 右欄（`SplitterPanel`）一張 `dark-card`：
  - 標題列：選取路徑（群組 ／ 控制項 ／ 評估目標）＋摘要（評估目標數、證據份數（檔案 N、連結 N）、無證據的 AO 數紅字）。
  - 工具列：型別 chip「全部｜檔案｜連結」；右側「分段：不分段｜依控制項｜依評估目標」（選群組時三個、選控制項時兩個、選 AO 時不顯示）。
  - 表格欄：型別標（PDF／XLSX／PNG／LINK…）｜證據（檔名＋大小，連結為標題＋網址）｜位置（D3）｜來源（`SourceBadge`）｜上傳者（暱稱）｜時間｜所屬任務｜操作（檔案：預覽、下載；連結：開啟）。
  - 空狀態：「這個範圍還沒有證據」。
- 一格一值、不用進度條（memory `feedback_table_one_value_per_cell_and_side_by_side_colors`）。

## 資料

### control-tree 每筆證據現況（`infra/readmodel/oscal/ssp_control_implementation_query.py:184`）

```
id, jid, evidence_type, source, ref_id, reference_url, classification_run_id, file_name
```

### 要補的欄位（BE 卡）

| 欄位 | 來源 | 用途 |
|---|---|---|
| `uid` | `je.uid` | 列 key、與 `JOB_EVIDENCES` 回傳對齊 |
| `file_uid` | `uf.uid` | 預覽／下載（`FilePreviewDialog.open(fileUid, name)`、`openFileDownload(fileUid)`） |
| `file_size` | `uf.size` | 顯示大小 |
| `description` | `je.description` | 連結標題（LINK 的 `name` 目前退到 `reference_url`，顯示不友善） |
| `created_user` | `je.created_user` | 上傳者（login_name） |
| `created_user_name` | app service 層 `enrich_audit_nickname_objs` | 上傳者暱稱（CLAUDE.md 審計欄位規範：有 `created_user` 必配 `created_user_name`） |
| `created_at` | `je.created_at` | 時間 |

位置（控制項／AO）不用補——tree 的巢狀結構就是位置：`groups[].controls[].assessment_objects[].jobs[].evidences[]`，FE 攤平時把路徑帶在每列上。同一份證據掛多個 AO 時會在多個 `jobs[]` 下各出現一次（同 `uid`），FE 以 `uid` 去重、把路徑收進「位置」欄。

### 權限

沿用 control-tree 既有守門（專案參與者可讀）。不新增能力點、不新增端點、不新增 migration。

## 拆卡

| 卡 | 做什麼 | Repo | 規模 |
|---|---|---|---|
| FR-163.1 | control-tree 證據欄位補齊（上表七欄）＋ nickname enrich | BE | 小：一支 SQL 加欄＋一處 dict 加鍵＋enrich 一行 |
| FR-163.2 | 證據視角：切換鈕、左樹加 AO 層與份數、右欄平表、Splitter、i18n | FE | 中：新子元件一支＋總覽頁掛載 |

批 1：FR-163.1。批 2：FR-163.2（等 .1 合入並重啟 BE）。FE 在 .1 之前可先用既有欄位開工（名稱、型別、來源、連結都已在 tree），只有上傳者／時間／預覽下載等 .1。

## 不做

- 匯出證據清單 Excel（雛形有按鈕；等實際用過再議）
- 問卷型證據（D10）
- 列上改對應／刪證據（D7）
- 跨輪次／跨專案（那是 FR-162 證據沿用的事）

## 相關

- 雛形：`prototype/index.html`（A／B／C 是 10/23 的三個早期方向，D 是第一版巢狀、**D2 是定案**）
- 現況頁：FE `src/views/project/ProjectAuditorOverview.vue`（2,114 行，已超標，新邏輯一律新子元件）
- 資料：BE `app/oscal/service/ssp_control_implementation_service.py:536-562`、`infra/readmodel/oscal/ssp_control_implementation_query.py:184-199`
- FR-142 稽核結果（「採用」語意在那邊）、FR-162 證據沿用（`source=REUSED` 徽章沿用 `SourceBadge`）
- 業界參考：Drata Evidence Library（平鋪清單＋linked controls）、表格 UX「巢狀上限兩層」