定版參考文件 · 只寫現況

分類完成之後,檔案真的掛進任務了

這頁是 FR-107 的定版交付規格——只回答「現在長什麼樣」。要看「當初為什麼這樣決定」去 design.md,要看「哪一棒做了什麼」去 handoff/LOG。本頁不記沿革、不 append 進度,內容變了就整段改寫。

兩條線並存 25 支對外端點 套件 1.2.0 定版參考
§1

一句話

證據自動分類不再需要 Google Drive,而且分完之後檔案會真的掛進對應的稽核任務。 使用者把一批檔上傳到暫存批次 → AI 判斷每個檔對應哪些檢查點 → 人工逐項確認 → 按歸檔,檔案改綁任務並在任務證據表寫入一筆,帶「AI 分類」標籤。框架知識從程式碼搬進資料表,任何自匯框架都能跑。


§2

使用者看到的流程

入口在專案總覽頁動作列的「自動分類證據」(限專案管理者,輪次路徑才出現),點進去是該輪的歷史清單,再點一批進四步流程頁:

步 畫面 使用者做什麼 批次狀態
① 上傳證據 拖拉多檔進來,可逐檔刪除;按「完成上傳」 uploading → ready
② AI 分類中 按「開始 AI 分類」(先開設定視窗),之後可以離開頁面 ready → classifying
③ 確認分類 逐檔看 AI 判到哪些檢查點,加一個/移除/標不適用/刪檔,儲存 classifying → review
④ 歸檔完成 按「歸檔進任務」,看摘要;可再決定要不要清掉沒歸檔的暫存檔 review → archived

分類失敗落 failed,已上傳的檔都還在、重新分類不必重傳。分類進行中可以離開頁面,回清單按「繼續」接著做——AI 會跑很久,這是入口做成歷史清單而不是上傳畫面的原因。

開始分類前的設定視窗四個欄位:信心門檻(滑桿)、AI 模型(僅系統管理員可見)、思考深度(低/中/高,預設中)、歸檔方式(分類並歸檔/只分析不歸檔)。

稽核員(auditor)進得去但按鈕整組隱藏,並顯示一行說明——反灰會讓人一直想「怎樣才能按」。


§3

兩條線並存,差別在哪

分類有兩條線,批次線是現行主線,Drive 線保留是為了讓既有分類結果仍打得開:

批次線 Drive 線
檔案來源 使用者上傳進暫存批次,落在租戶自己的儲存後端(本機/MinIO/SeaweedFS/遠端 agent 皆可) Google Drive 的 Evidences/ 資料夾
掛在誰身上 稽核輪次,每次新上傳開一個新批次 專案的 AP
分完之後 歸檔進任務——檔案改綁控制任務,job_evidences 真正寫入一筆 複製進 Drive 的 per-AO 資料夾,任務證據表一筆都不寫
定址 run_uid(UUID) run_folder_id(Drive 資料夾 ID)
檢查點代號 part_id + ao_letter(如 IA.L1-3.5.1_obj.1) {ControlId}[{letter}](如 AC.L1-3.1.1[a])
目標集 run 的 catalog_snapshot(分類當下凍結) living SSP 的 in-scope 控制集
覆核權限 寫入鎖專案管理者、讀要是專案參與者 僅驗 JWT(未鎖專案角色)

兩條線的審閱畫面是同一支元件,只換資料來源。

落地版客戶沒有 Google Drive,批次線是讓分類功能對他們也能用的前提。


§4

歸檔做了什麼(整案的重點)

這是 FR-107 相對於前一代最實質的差別:以前分完只是把檔搬到另一個資料夾,系統的任務證據表一筆都沒寫;現在會真的寫入。

  • 一檔多掛、不複製:一個檔命中幾個檢查點,就在那幾個任務底下各掛一筆證據,但實體檔只有一份、多筆證據指向同一個檔案 id。
  • 重複不重掛:歸檔是冪等的,已經在任務底下的證據會被略過。摘要分開報「新掛幾筆/已存在幾筆」。
  • 標了不適用或已刪除的檔不會掛上:審閱頁標這兩個旗標時不會一併清掉判定結果,只看判定結果的話,使用者標了「不適用」的檔還是會被掛上任務——而畫面上它顯示的是「不適用」。
  • 沒有對應任務的檔不會憑空掛上:AI 判到的檢查點若這一輪沒人被指派任務,那些檔留在批次裡標「無對應任務」,摘要會講還有幾份是這個狀況。
  • 可以重按:已歸檔批次的按鈕降級為「重新歸檔」,只補上次歸檔後才新建的任務。擋掉第二次的話,歸檔後才建出來的任務永遠拿不到證據,而使用者看到的是一個無法補救的錯誤。

歸檔回傳四個數字:掛進任務的檔數、新產生的證據筆數、已存在所以略過的筆數、沒有對應任務的檔數。

在任務那一側,證據列依 job_evidences.source 顯示標籤:AI_CLASSIFIED →「AI 分類」(綠)、DRIVE_SYNC →「Google Drive」(藍)、SYSTEM_UPLOAD(手動上傳)不掛標籤(每個檔都掛等於沒有資訊)。AI_CLASSIFIED 另有 classification_run_id 記得是哪一次分類來的。

🔴 清理(purge)永遠不動已歸檔的檔:那些檔背後有任務證據指著同一個檔案 id,實刪後任務上的證據會變成打不開的死連結。清理只動沒歸檔的暫存檔,且只對已歸檔的批次開放。


§5

框架知識搬進資料表

「換一個合規框架就換一組 AI 講法」那組講法存在 compliance.classification_profiles,支援新框架是新增一筆設定,不是改程式。維護介面在框架版本管理頁的「AI 分類設定」分頁。

欄位:設定名稱、適用範圍(通用/某個框架版本)、AI 角色(必填)、判斷指引、證據提示(檢查點代號 → 提示陣列)、預設模型、預設信心門檻、預設思考深度、啟用狀態。

四層退路(由精確到通用,找到第一筆啟用的就用):這個租戶 × 這個框架版本 → 出廠針對此版本 → 這個租戶的通用設定 → 出廠通用設定;全落空才用內建最小版。內建那份刻意不含任何框架名——寫死 CMMC 等於把框架名焊回分類引擎。

停用一筆設定不是關掉分類,是讓它改用上一層。 出廠那份(ROOT 租戶)對業務租戶唯讀,但清單上一起回是刻意的:使用者要看得到「我沒設定時系統實際會用什麼」,看不到的話「為什麼 AI 這樣講話」無從查起。

守門軸與框架版本寫入不同:框架版本是全域共用資源(只有平台管理員能寫),分類設定是租戶級的(走 storage-config.update 能力點)。把它也鎖成平台管理員,等於所有客戶都不能自己調 AI 講法。


§6

可用的 AI 模型怎麼決定

該租戶已設定金鑰的供應商 × 系統支援的型號表,取交集,由 GET /api/1.0/classification/available-models 動態算出。

  • 型號表(套件 domain/llm_models.py)是資料不是邏輯——支援新型號=加一列,不改程式。
  • 沒設定任何金鑰時回空清單,畫面提示去填金鑰,不列出選了才會 401 的型號。
  • 不支援讀圖的型號在選單上標明,且遇到圖片證據會明確標「此模型不支援圖片,未分類」——不靜默跳過(靜默跳過會讓使用者以為那張截圖被看過且判定為無關)。

金鑰不在分類設定頁:只有 ROOT 平台管理員能填,讀取時遮成「有沒有設定」的旗標、不回明文;加密後才落地。第一版不開放客戶自填。三個 AI 功能(AI 小幫手/AI Dashboard/證據分類)共用同一套解析順序:租戶自己的設定 → ROOT 原廠鑰 → 環境變數。

本頁刻意不列型號名。型號隨供應商發版換代,寫進手冊等於保證下次換代時這頁是錯的——要看當下有哪些,打上面那支端點。


§7

交付物現況

項目 現況
套件 jedi-evidence-classification 1.2.0(主專案已 pin,離開 path dependency)
套件 jedi-file-upload 1.2.0(同上)
對外端點 25 支(套件 FROZEN_URLS 凍結清單,測試對實際掛載結果做集合比對)
套件內 migration 5 支(001~005;不寫 schema_migrations,屬套件自己的管線)
新增資料表 compliance.evidence_batches、evidence_batch_files、classification_profiles
任務證據表擴充 job_evidences.source 增加 AI_CLASSIFIED;新增 classification_run_id 追溯欄
分類容器 image evidence-classifier:dev(宿主不覆寫名稱,固定用套件預設)
SPEC 頁 五頁已更新(專案總覽/審閱頁/框架版本管理/我的任務/證據管理總覽)

端點分組:暫存批次 8 支、AI 分類設定 3 支、run 新定址 4 支、Drive 線 legacy 與報表 10 支。


§8

這一輪沒做完的

沒做完的事 白話說明 誰接
分類容器 image 進出貨包 現在全新裝機要手動拉 image 才跑得動分類,還沒進安裝包 T-6.4(CM-1871)
AI 模型碼表換代 + 思考深度落地 型號表要換成當代型號;「思考深度」三檔要從前端一路穿到容器(批次表與設定表各加一欄)。SPEC 兩處已標「CM-1885 落地中」 CM-1885
端到端回歸測試 走完「上傳→分類→確認→歸檔→任務看到證據」的自動化測試。前置是含 FR-107 的 image 進 190 測試機——目前該機所有 image 都不含本案端點,測試寫了也會在第二步就停 T-6.3b(CM-1886)
舊 Drive 線退場 舊入口已隱藏、舊路徑標 legacy 保留一版,尚未真正移除 下一版另議

子任務卡 25 張:22 張已驗收完成,未完成的就是上表前三項(另有一張前端設計稿卡不計入)。全案未 push,等決策者明示。


§9

延伸出去的 FR

FR 在做什麼 為什麼會長出來 狀態
FR-030 第一代分類(Drive 線) 本案取代的前身;它的分類結果仍要打得開,故舊線保留一版 已上線,退場中
FR-031 分類成效報表(驗證/誤判) 報表要算「歸檔後的正解」,靠本案寫入的 classification_run_id 追溯 已上線
FR-069 套件化與插件契約 本案的新功能一律進套件、主專案只留宿主接線,遵循的是那一案定下的插件形狀 已上線

閱讀順序:先看本頁 → 要懂分類報表看 FR-031 → 要懂套件為什麼長這樣看 FR-069。


§10

這份文件的定位

你想知道 看哪份
最後長什麼樣、規則是什麼 本頁
當初為什麼這樣決定、哪些方案被排除 design.md(D1–D13)
需求怎麼來的、決策者表態過什麼 discussion.md、README 的「需求討論紀錄」
哪一棒做了什麼、踩過什麼坑 handoff/fr107-LOG.md 與 git log
這些頁面實際怎麼運作(給工程師查) SPEC 手冊的五頁(見上方「交付物現況」)