分類線搬回系統儲存、分完搬進任務、框架不寫死

狀態：🟢 16/31 張 Done，3 張派出中（T-3.4／T-4.1／T-5.3b）｜建立日期：2026-09-16｜決策者裁示日：2026-09-16／17 Notion：母卡 CM-1843｜子需求 CM-1844～1849｜子任務 CM-1850～1871、1877～1879 討論稿（含現況盤點原文）：discussion.html｜前作：FR-030（Drive 版自動分類）／FR-031（分類結果報表）

🔴 這份是設計決策，不是現況。 內文的座標與數字停在 2026-09-16 定稿當時，之後實作改動的結果不回頭改寫這裡——現況一律看 FINAL-SPEC.md（收口時產出）。

整案一句話：把「證據自動分類」從 Google Drive 搬回系統自己的儲存空間，分完的檔直接搬進任務變成正式證據，而且不管哪個合規框架都能用——新功能全長在套件 jedi-evidence-classification 裡，主專案只負責「接線」與前端。

先解釋幾個詞（白話）：

• 儲存後端：系統把上傳檔案實際放在哪裡——主機硬碟、物件儲存（MinIO／SeaweedFS，類似自架雲端硬碟）、或客戶內網的遠端 agent。設定切一下就換，程式不用改。
• 暫存批次：使用者一次上傳的一堆證據檔，還沒分類、還沒掛任何任務，先放在一個「籃子」裡。
• AO（Assessment Objective，評估目標）：一條控制項底下的細分檢查點。分類就是把每份檔對到它證明的那幾個檢查點。
• 任務：稽核輪次裡每個檢查點對應的工作項；證據最終要掛在任務上，稽核員才看得到。
• port：套件開出來的「插座」——套件只說「我需要有人幫我拿檔／找任務」，怎麼拿由主專案（宿主）插上去的 adapter 決定。
• 宿主 adapter：主專案為每個 port 寫的實作，本案落在 core/plugins/evidence_classification.py。

依賴：.1 → .2 → .3 → .4 直線；.5 可與 .3／.4 平行（只碰 prompt、catalog 讀法與 profile 表，不碰批次流程）；.6 最後。所有裁決已於 2026-09-16 完成，開工不再有前置裁決。

動套件的棒（.1／.2／.3／.4／.5）一律走 poetry path dependency 開發、feature 完成才發版（jedi-package-dev skill）；path 改動不 commit，.6 統一還原 pin。

前作 FR-030 把自動分類做在 Google Drive 上：檔案從 Drive 來、結果寫回 Drive 的 _state.json、歸檔只是把檔複製到 Drive 的另一個資料夾，系統的任務證據表 job_evidences 一筆都沒寫。落地版（FR-063～FR-065）客戶沒有 Drive，這條線等於不存在。同時 FR-069 模組化後儲存層已統一走 jedi-file-upload 的 IUploadFileProvider，分類線是唯一還直接綁 Drive 的功能。

四個結構性問題（詳見討論稿 §2）：來源與終點都是 Drive；容器自己連 DB、解密 Drive token、下載檔案；框架知識寫死在程式裡（CMMC L1 的 17 條、[a] 字母硬剝、套件內 cmmc_l1_aos.json）；upload_files 沒有租戶／擁有者／RLS，暫存的孤兒檔沒人管。

端到端流程（目標）

專案經理選輪次 → 開新批次 → 拖入 N 份檔（存進系統儲存後端，upload_files 帶 tenant）
  → 按「開始分類」（批次封口）
  → 套件解析 profile ＋ 動態目標集 → 宿主把整批檔拉到 job 工作目錄 ＋ 寫 prompt.json
  → docker run evidence-classifier（只掛目錄、只帶 AI 金鑰）→ 回結果 JSON
  → 結果存 evidence_classification_runs（掛批次）→ 批次進「審閱」
  → 審閱頁加減檢查點、標不適用、儲存
  → 按「歸檔進任務」→ 每檔每檢查點寫一筆 job_evidences（source=AI_CLASSIFIED，冪等）
  → 沒任務的標「無對應任務」→ 問要不要清掉剩餘檔（實刪）

決策者 2026-09-16 一次裁完。每項含定案理由與被排除方案，之後若推翻，改這裡並在 LOG 記錄。

| D12 | 分類要不要支援其他 AI 供應商 | 要，動態算：金鑰存 system_configs 新 group AI_PROVIDER_CONFIG（租戶級，比照 STORAGE_CONFIG：ROOT 給預設、新租戶從 ROOT 複製、值加密不回顯明文），每家一格（anthropic.api_key／openai.api_key／預留 azure_openai＋endpoint／ollama＋base_url 無金鑰）；環境變數 ANTHROPIC_API_KEY／OPENAI_API_KEY（.env.sample:140-141 已存在）保留為後備，設定表沒填就退回讀 env。可選模型＝「有填金鑰（或 env）的供應商 × 該供應商的型號碼表」，碼表放套件一支 llm_models.py。容器抽 LlmClient 介面，兩實作 AnthropicClient／OpenAIClient（相容 API 的 Azure／Ollama 都走 OpenAI 實作），image 同時裝兩家 SDK，宿主起容器時只塞該供應商那把金鑰。碼表 supports_vision=False 的型號對圖片證據明確標「此模型不支援圖片，未分類」，不靜默跳過。詳見 §6.11 | 落地版客戶環境差異大，有些只有 OpenAI 額度、有些走內部 Azure OpenAI 代理；金鑰放系統設定才能讓客戶自己在畫面上切換與覆寫，且與現有 STORAGE_CONFIG 租戶級管理模式一致；型號碼表獨立於程式邏輯，之後加新模型只改碼表不改程式；容器不寫死供應商，換一顆 image 不必重 build | 只放環境變數、畫面唯讀——落地版客戶不會自己改伺服器上的 .env，改了也要重啟才生效，客戶端幾乎不可能自助切換供應商 | | D13 | 原廠 AI 金鑰放哪、三個 AI 功能怎麼統一 | 原廠給客戶機一組 AI 金鑰，存 ROOT 租戶（tenant_id=1）的 AI_PROVIDER_CONFIG/CONFIG，值走 Fernet 加密落 DB（沿用 infra/cloud_integration/crypto/fernet_crypto.py 實作，另開獨立環境變數存加密鑰，不與 DRIVE_TOKEN_ENCRYPTION_KEY 共用），不寫 guidant.env。AI 小幫手（core/plugins/ai_bot.py）、AI Dashboard（di_containers/ai_dashboard/ai_dashboard_containers.py）、證據分類三功能統一金鑰解析順序：租戶自己有設定 → 用租戶的；沒有 → fallback ROOT（原廠）；ROOT 也沒有 → 環境變數後備（開發機用）。三功能共用同一支解析器（從 SystemConfigAiProviderAdapter 抽出）。第一版不開放客戶自填——金鑰設定頁鎖 ROOT 平台管理員（T-5.4 已改），未來開放只改守門旗標。install.sh 裝機時把原廠鑰寫進 ROOT（來源 install.conf，比照 S3 憑證處理，值不入版控）；--upgrade 不覆寫既有值 | 落地版客戶機是原廠人員裝機，開箱即用 AI 功能不必客戶自己申請金鑰；DB 加密欄位比 .env 明文檔案風險低（防不小心操作與資料庫外洩，不防客戶機 root 有心人——解密鑰與密文同機，這是落地版天花板）；三功能各自一套讀法會讓以後換鑰或開放自填要改三處還可能漏改，統一成一份省掉這個風險 | 明文寫 DB——同樣風險等級但少一層防護，沒有理由不加密；加密鑰與密文同處——防護等於沒加；做「原廠代理」把金鑰整個藏在原廠伺服器後面——防護等級更高（防客戶 root），但屬獨立需求，另立案不塞進本案 |

D11 落點表

以下座標 2026-09-16 逐一開檔核對。套件路徑 ~/Projects/Jedicogy/module/jedi-python-package/（下稱 PK/）。

6.1 資料模型

6.1.1 upload_files 補三樣（套件 jedi-file-upload 的表）

回填規則（D10）：migration 先列舉所有 FK 或邏輯參照 upload_files.id／uid 的表（.1 runner 以 grep -rn "upload_files\|file_id\|file_uid" infra/ PK/*/infra 實查，至少含 job_evidences→workflow_execution→專案→租戶），逐表 UPDATE ... FROM 回填；storage_scope='system' 歸 ROOT；剩下孤兒歸 ROOT（tenant_id=1），migration 末尾 RAISE NOTICE '孤兒列 N 筆歸 ROOT' 並在卡片回報筆數。

6.1.2 新表 compliance.evidence_batches（批次；套件 jedi-evidence-classification）

RLS：四條 policy 照範本；GRANT ... TO cm_app＋sequence 權限。

6.1.3 新表 compliance.evidence_batch_files（批次檔；套件 jedi-evidence-classification）

UNIQUE (batch_id, file_id)；RLS 四條 policy。

6.1.4 evidence_classification_runs 改動（D5；套件 jedi-evidence-classification）

一個批次可有多次 run（重新分類），evidence_batches.current_run_id 指最新。

6.1.5 新表 compliance.classification_profiles（AI 分類設定；套件 jedi-evidence-classification）

放 compliance schema 而非 oscal：表由本套件擁有，schema 跟著擁有者；與 framework_versions 的關聯是軟參照。UNIQUE (tenant_id, framework_version_id)（每租戶每框架版本一筆，NULL 視為通用那筆）。

6.1.6 job_evidences 改動（主專案）

6.1.7 migration 落點與順序

每支只套 DEV（localhost:5432）；收尾 INSERT public.schema_migrations；每棒回報「出貨基線待重產」，.6 一次重產。

6.2 批次狀態機

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
stateDiagram-v2
    [*] --> uploading : 建批次
    uploading --> uploading : 加檔／刪檔
    uploading --> ready : 至少一檔且按「完成上傳」（或按分類時自動）
    ready --> uploading : 再加檔（分類尚未開始）
    ready --> classifying : 按「開始分類」（封口，加檔 409）
    classifying --> review : 容器回結果
    classifying --> failed : 容器失敗／逾時／心跳逾時 30 分
    failed --> classifying : 重跑（同批次，不必重傳）
    review --> review : 審閱調整、儲存
    review --> classifying : 重新分類（換 model／threshold）
    review --> archived : 歸檔進任務
    archived --> archived : 清掉剩餘檔（purge，只動未掛任務的檔）
    archived --> [*]

轉換規則表（套件 EvidenceBatchService 內以一張 ALLOWED_TRANSITIONS dict 實作，非法轉換一律 ConflictError）：

6.3 port 簽名（套件 domain/ports.py 新增）

@dataclass(frozen=True)
class StagedFile:
    file_id: int          # 內部 int（upload_files.id）
    file_uid: str         # 對外 uid
    original_name: str
    local_path: Path      # 已拉到 job 目錄的實體路徑
    content_hash: str | None


class IEvidenceStorage(Protocol):
    """證據檔的取檔／放檔。主專案接 jedi-file-upload 的 IUploadFileProvider。
    套件與容器只認這個；後端是 local／minio／seaweedfs／remote_agent 由宿主決定。"""

    def is_configured(self, tenant_id: int) -> bool: ...
    # D6：未設 STORAGE_CONFIG 回 False，套件在批次上傳路徑拋 412 EC_STORAGE_NOT_CONFIGURED

    def save(self, tenant_id: int, owner_user_id: int, file: FileStorage) -> tuple[int, str, str | None]: ...
    # 存一份檔，回 (file_id, file_uid, sha256)；宿主帶 tenant 脈絡寫 upload_files

    def get_bytes(self, tenant_id: int, file_uid: str) -> bytes: ...
    # 拉一份檔的內容（審閱頁預覽用）

    def stage_to_dir(self, tenant_id: int, file_uids: list[str], work_dir: Path) -> list[StagedFile]: ...
    # 甲案：把整批拉到本機工作目錄；宿主一律走 upload_files_for_tenant 對應的 provider 解析

    def delete(self, tenant_id: int, file_uid: str) -> bool: ...
    # D7 實刪；宿主走 IUploadFileProvider.delete_file


@dataclass(frozen=True)
class AttachResult:
    evidence_uid: str
    existed: bool         # True＝冪等命中既有列，沒有新寫


class ITaskEvidenceSink(Protocol):
    """AO → 任務對照，與把檔掛進任務。主專案接 get_jobs_by_round_id 與 job_evidences。"""

    def resolve_jobs(self, round_id: int) -> dict[str, int]: ...
    # 回 {part_id: job_execution_id}；同一 part_id 只會有一個任務（DEV 792 筆實查成立）

    def attach(self, *, job_execution_id: int, file_id: int, file_uid: str,
               classification_run_id: int, actor_user_id: int,
               content_hash: str | None, description: str | None) -> AttachResult: ...
    # 寫 job_evidences(source="AI_CLASSIFIED")；命中 (job_execution_id, file_id) 既有未刪列時回 existed=True

    def find_same_content(self, round_id: int, content_hash: str) -> list[tuple[int, str]]: ...
    # D9 提示：回 [(job_execution_id, evidence_uid)]，不阻擋


class IClassificationContext(Protocol):
    """解析 profile 要用的框架版本鏈，與輪次存在性。全是宿主（OSCAL／稽核輪次）的疆界。"""

    def resolve_round(self, round_uid: str) -> tuple[int, int] | None: ...
    # 回 (round_id, project_id)；不存在回 None

    def framework_version_chain(self, project_id: int) -> list[int]: ...
    # 依「專案指定 → living SSP → catalog」順序回 framework_version_id 清單（去重、有序）

IProjectRoleGuard 加一支 is_project_participant(project_id, user_id) -> bool（D8 auditor 只看）；宿主 adapter 委派 common/authz/project.py:101 assert_project_participant。

6.4 容器工作目錄契約（D2 甲案）

宿主起容器前把 jobs_base_dir/<batch_uid>-<run_uid>/ 準備成：

/job/
  files/<file_uid>.<ext>      ← IEvidenceStorage.stage_to_dir 拉下來的實體檔
  manifest.json               ← [{file_uid, original_name, mimetype, size}]
  catalog.json                ← 目標集（含 part_id／group_id／group_title／ao_letter／prose）
  prompt.json                 ← {persona, guidance, hints_by_part_id}  三段（§6.5）

容器指令：docker run --rm --network <只允許 AI API 的 network 或 host 代理> -v <job_dir>:/job -e ANTHROPIC_API_KEY=... evidence-classifier:<tag> service-classify --input-dir /job --output-dir /job --model ... --min-confidence ... --workers ...。沒有 --tenant-id、沒有 --evidence-folder-id、沒有 DB／Drive 環境變數。

容器回：

/job/
  _report-original.json       ← {"files":[{"file_uid","matches":[{"part_id","confidence"}],"primary":part_id|null,"error":null}], "usage":{...}, "estimated_cost_usd":...}
  _container.log

宿主讀回 _report-original.json → 寫 run（report_original、初始 state＝report 過門檻的部分、catalog_snapshot、prompt_snapshot）→ 批次 review → 刪 files/（工作目錄不留實體檔，避免第二份真相；log 與 json 留 7 天供排查）。

6.5 prompt 三段組裝與 profile 解析順序

宿主（套件 app service，非容器）組 prompt.json：

容器 build_system_block() 改成純讀 prompt.json 拼接，不再有任何字串常數提到 CMMC；AI 回傳的 key 一律 part_id，容器驗 part_id ∈ catalog。

profile 解析順序（定案 5）：

for fv_id in context.framework_version_chain(project_id):   # 專案指定 → living SSP → catalog
    p = profiles.find(tenant_id, fv_id, enable=True) or profiles.find(ROOT, fv_id, enable=True)
    if p: return p
p = profiles.find(tenant_id, None, enable=True) or profiles.find(ROOT, None, enable=True)   # 通用
return p or BUILTIN_MINIMAL

批次觸發時把解析到的 profile_id 寫進 evidence_batches.profile_id，批次的 provider／model／confidence_threshold 取「使用者覆寫 → profile 預設 → 系統預設」（D12，§6.11）。

6.6 API（套件 route，prefix /api/1.0）

舊 route（/project/<project_uid>/ap/<ap_uid>/classify-evidence、/classification-run/<run_folder_id>/...）原樣保留，只在 docstring 標 legacy（D3）。

error code 新增（套件 error_code.py，前綴沿用套件既有 EC_）：EC_STORAGE_NOT_CONFIGURED（412）、EC_BATCH_SEALED（409）、EC_BATCH_INVALID_TRANSITION（409）、EC_BATCH_NOT_FOUND（404）、EC_ROUND_NOT_FOUND（404）、EC_NO_TARGET_CATALOG（412）；FE error-code.json 同步。

6.7 歸檔演算法（.4）

輸入：batch（status=review）、run＝batch.current_run、actor
1. jobs = sink.resolve_jobs(batch.round_id)              # {part_id: job_execution_id}
2. for bf in batch_files where status in (pending, classified):
     parts = run.state[bf.file_uid].parts                 # 審閱後最終判定（含人工加減；標「不適用」的已排除）
     if not parts: continue                               # 沒判定的檔留 pending
     hit = [p for p in parts if p in jobs]
     if not hit:
         bf.status = no_task; bf.classification = parts; continue
     for p in hit:                                        # 一檔多 AO → 多筆
         r = sink.attach(job_execution_id=jobs[p], file_id=bf.file_id, file_uid=bf.file_uid,
                         classification_run_id=run.id, actor_user_id=actor,
                         content_hash=bf.content_hash, description=f"AI 分類：{p}")
         created += (not r.existed); existed += r.existed
         bf.archived_evidence_uids.append(r.evidence_uid)
     bf.status = archived; bf.classification = parts
     miss = [p for p in parts if p not in jobs]           # 部分沒任務：檔仍算 archived，缺的記在 classification 內 no_task=true
3. batch.status = archived; 統計回寫（archived_count／no_task_count）；run.archived_at
4. 回 {attached_files, evidence_created, evidence_existed, no_task_files}

冪等：整段在一個 @transaction 內；重按第二次時每個 attach 都 existed=True、created=0，狀態不變。不複製實體檔——job_evidences.file_id 指向同一筆 upload_files。清理（purge）只刪 status IN (pending, classified, no_task) 的檔，archived 列永不刪。

6.8 背景 thread 的租戶脈絡

分類 thread 沒有 request 脈絡，讀 STORAGE_CONFIG 會挑錯租戶（memory feedback_background_job_storage_config_no_context_trap）。規則：classify 端點在 request 內先解析好 tenant_id、profile、catalog、provider 設定，全部以參數傳進 thread；thread 內 IEvidenceStorage.stage_to_dir(tenant_id, ...) 由宿主 adapter 以 tenant_id 明確解析 provider（走 managed_file_upload_service.py:324 upload_files_for_tenant 同一條解析路徑），不靠 thread-local。心跳每 60 秒 UPDATE evidence_batches SET job_heartbeat_at = now()（獨立短 transaction）。

6.9 架構圖與時序圖

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  subgraph FE[前端]
    U1[上傳到批次頁]
    U2[審閱頁（沿用、改資料來源）]
    U3[歸檔對話框]
    U4[AI 分類設定分頁]
  end
  subgraph PKG[套件 jedi-evidence-classification]
    R[route：批次／分類／歸檔／profile]
    S[EvidenceBatchService 狀態機 ＋ 分類編排 ＋ 歸檔演算法]
    T[(evidence_batches ／ evidence_batch_files ／ runs ／ classification_profiles)]
    P1[port IEvidenceStorage]
    P2[port IControlCatalog]
    P3[port IClassificationContext]
    P4[port ITaskEvidenceSink]
    P5[port IProjectRoleGuard]
  end
  subgraph HOST[主專案 core/plugins/evidence_classification.py]
    A1[adapter → IUploadFileProvider]
    A2[adapter → build_classifier_catalog_by_ssp_id]
    A3[adapter → living SSP／framework_version／輪次]
    A4[adapter → get_jobs_by_round_id ＋ job_evidences]
    A5[adapter → common.authz project 軸]
    DB[(upload_files ／ job_evidences ／ oscal ／ rounds)]
  end
  subgraph STOR[儲存後端（擇一）]
    L[local]
    M[minio／seaweedfs]
    RA[remote agent]
  end
  C[容器 evidence-classifier：只讀 /job/files ＋ prompt.json ＋ catalog.json，寫 _report-original.json]
  U1 --> R
  U2 --> R
  U3 --> R
  U4 --> R
  R --> S
  S --> T
  S --> P1
  S --> P2
  S --> P3
  S --> P4
  S --> P5
  P1 -.-> A1
  P2 -.-> A2
  P3 -.-> A3
  P4 -.-> A4
  P5 -.-> A5
  A1 --> L
  A1 --> M
  A1 --> RA
  A2 --> DB
  A3 --> DB
  A4 --> DB
  A5 --> DB
  S -->|stage 檔到 job 目錄後 docker run| C
  C -->|結果 JSON| S

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant U as 使用者（專案經理）
    participant FE as 前端
    participant PKG as 套件（在 BE 內）
    participant HOST as 主專案 adapter
    participant ST as 儲存後端
    participant C as 容器 evidence-classifier
    participant DB as PostgreSQL

    U->>FE: 選輪次，開新批次，拖入 N 份檔
    FE->>PKG: POST /evidence-batches（round_uid）
    PKG->>HOST: IEvidenceStorage.is_configured(tenant)
    HOST-->>PKG: False → 412 EC_STORAGE_NOT_CONFIGURED（D6）／True → 建批次
    loop 每一份檔
      FE->>PKG: POST /evidence-batches/{uid}/files
      PKG->>HOST: IEvidenceStorage.save(tenant, owner, file)
      HOST->>ST: IUploadFileProvider.save_file()
      HOST->>DB: upload_files（tenant_id／owner_user_id）
      PKG->>DB: evidence_batch_files（pending）
    end
    U->>FE: 按「開始分類」
    FE->>PKG: POST /evidence-batches/{uid}/classify
    PKG->>DB: status → classifying（之後加檔 409）
    PKG->>HOST: IClassificationContext.framework_version_chain(project)
    PKG->>DB: 解析 profile → prompt 三段；IControlCatalog → 目標集
    PKG->>HOST: IEvidenceStorage.stage_to_dir(tenant, file_uids, job_dir)
    HOST->>ST: 逐檔 get_file() 落 /job/files/
    PKG->>C: docker run（掛 /job；env 只有 AI 金鑰）
    C->>C: 讀 prompt.json＋catalog.json，逐檔呼叫 AI
    C-->>PKG: _report-original.json（每檔 → [part_id, confidence]）
    PKG->>DB: runs（batch_id／catalog_snapshot／prompt_snapshot）；status → review；心跳停
    U->>FE: 審閱頁：加減 AO、標不適用、儲存
    FE->>PKG: PUT /classification-run/{run_uid}/state
    U->>FE: 按「歸檔進任務」
    FE->>PKG: POST /evidence-batches/{uid}/archive
    PKG->>HOST: ITaskEvidenceSink.resolve_jobs(round_id)
    HOST->>DB: get_jobs_by_round_id → {part_id: job_execution_id}
    loop 每檔每命中 AO
      PKG->>HOST: ITaskEvidenceSink.attach(...)
      HOST->>DB: job_evidences(source=AI_CLASSIFIED) 冪等
    end
    PKG->>DB: 沒任務的標 no_task；status → archived
    PKG-->>FE: {attached_files, evidence_created, evidence_existed, no_task_files}
    FE->>U: 問「剩餘 Z 檔要清掉嗎？」
    U->>FE: 清掉
    FE->>PKG: POST /evidence-batches/{uid}/purge
    PKG->>HOST: IEvidenceStorage.delete(tenant, file_uid)
    HOST->>ST: delete_file()（實刪，D7）
    PKG->>DB: evidence_batch_files.status → removed

6.10 框架去硬編碼——實作面要動的點（.5）

6.11 多供應商 AI（D12）

決策者 2026-09-16 追加：分類要能用 OpenAI 等其他供應商的模型，看系統填了哪幾家的 API 金鑰決定可選哪家、哪個模型。

金鑰存系統設定：system_configs 新 group AI_PROVIDER_CONFIG（租戶級，比照 STORAGE_CONFIG 的形狀——ROOT 給預設、新租戶從 ROOT 複製、值加密不回顯明文）：

AI_PROVIDER_CONFIG/CONFIG = {
  "anthropic": {"api_key": "..."},
  "openai":     {"api_key": "..."},
  "azure_openai": {"api_key": "...", "endpoint": "..."},   # 預留，本案不接
  "ollama":     {"base_url": "..."}                        # 預留，無金鑰
}

環境變數 ANTHROPIC_API_KEY／OPENAI_API_KEY（.env.sample:140-141 已存在）保留為後備：AI_PROVIDER_CONFIG 沒填該供應商的金鑰就退回讀對應環境變數。兩者都沒有＝該供應商不可選。

可用模型動態算：「有填金鑰（或環境變數有值）的供應商」× 「該供應商的型號碼表」。碼表放套件 jedi-evidence-classification 一支 llm_models.py：

@dataclass(frozen=True)
class LlmModelSpec:
    provider: str        # "anthropic" | "openai" | ...
    model_id: str         # API 呼叫用的實際字串
    display_name: str     # 畫面顯示
    supports_vision: bool
    default: bool          # 該供應商的預設選項


LLM_MODELS: list[LlmModelSpec] = [
    LlmModelSpec("anthropic", "claude-sonnet-4-6", "Claude Sonnet 4.6", True, default=True),
    LlmModelSpec("anthropic", "claude-opus-4-8",   "Claude Opus 4.8",   True, default=False),
    LlmModelSpec("openai",    "gpt-5",              "GPT-5",             True, default=True),
    ...
]

加型號只改這支碼表，不改程式邏輯。現有 evidence_classification_service.py:81 的 ALLOWED_MODELS 白名單退場，改由碼表 + 可用供應商聯集動態算。

容器抽 LlmClient 介面（套件 domain/ports.py 或容器模組內）：

class LlmClient(Protocol):
    def classify(self, system_block: str, user_parts: list[dict]) -> dict: ...
    # 回傳格式與現有 classify_with_claude() 一致：(parsed_result, usage) 或含 usage 的 dict

兩個實作：AnthropicClient（現有 container_entrypoint.py:635 起 classify_with_claude() 那段搬進來，改名不改邏輯）、OpenAIClient（走 chat.completions，相容 API 的 Azure OpenAI／Ollama 都走它，endpoint 可配）。容器 image 同時裝兩家 SDK；宿主起容器時只塞「這一批實際要用的那個供應商」的金鑰環境變數，不兩家都塞（§6.4 容器工作目錄契約的「沒有 DB／Drive 環境變數」延伸——現在也只有一家 AI 金鑰進容器）。

視覺支援：碼表 supports_vision=False 的型號，遇到圖片證據要明確標記「此模型不支援圖片，未分類」寫進結果，不可靜默跳過（否則審閱頁看到的是「沒判定」，使用者無法區分是真的判不出來還是模型天生看不了圖）。

前端：「AI 分類設定」分頁（T-5.4 所在頁）多一區「供應商金鑰」——只顯示每家「已設定」／「未設定」，可覆寫，不回顯明文。分類觸發對話框與 profile 編輯頁的模型下拉改打新端點：

GET /api/1.0/classification/available-models
→ [{"provider": "anthropic", "model_id": "...", "display_name": "...", "supports_vision": true}, ...]

只回傳「該租戶目前可用」的模型（金鑰已設定的供應商 × 碼表）。

驗收：切到 OpenAI 跑一次同一批證據，validation／adjudication 兩份評測報表要能正常產出，且與 Claude 那次跑出來的報表可比對（欄位形狀一致，不要求判定結果相同）。

6.12 金鑰解析三層與第一版不開放租戶自填（D13）

D12 定義了 AI_PROVIDER_CONFIG 這張設定表的形狀；D13 把它的寫入來源與誰能填定案。

金鑰解析三層（AI 小幫手／AI Dashboard／證據分類三功能共用同一支解析器）：

resolve(tenant_id, provider):
    租戶自己的 AI_PROVIDER_CONFIG 有填 provider 的金鑰？ → 用它
    否則 ROOT（tenant_id=1）的 AI_PROVIDER_CONFIG 有填？ → 用它（原廠鑰）
    否則環境變數（ANTHROPIC_API_KEY／OPENAI_API_KEY）有值？ → 用它（開發機退路）
    都沒有 → None（該供應商不可用）

三個既有讀法（AI 小幫手 os.getenv("ANTHROPIC_API_KEY")、AI Dashboard _ai_api_keys() 直讀三個環境變數、證據分類 SystemConfigAiProviderAdapter.configured_providers() 只回 bool 未回實際金鑰）改統一走這支解析器，行為對現有兩功能必須零改變——沒設定 ROOT 金鑰時退回 env，與改動前一致。

值的加密：AI_PROVIDER_CONFIG 的金鑰欄位落 DB 前用 Fernet 加密（沿用 infra/cloud_integration/crypto/fernet_crypto.py 既有實作類別），加密鑰走獨立環境變數，不與 DRIVE_TOKEN_ENCRYPTION_KEY 共用——不同用途共用一把鑰匙，其中一邊外洩會牽連另一邊。

第一版不開放客戶自填：租戶層級的 AI 供應商金鑰設定 UI 不開放——T-5.4 那頁的「供應商金鑰」區塊鎖 ROOT 平台管理員可見可寫，租戶管理員看不到這個入口（與 profile 內容編輯不同軸，profile 是租戶管理員可編，見「寫作時發現的事」第 4 點 2026-09-17 修正）。全部客戶第一版共用原廠那把 ROOT 金鑰。未來要開放客戶自填，只改一個守門旗標即可，不必動解析邏輯本身。

風險天花板：這個機制的安全等級與現有 Drive OAuth token 加密同級——防的是不小心的操作與資料庫外洩，不防客戶機上有 root 權限的有心人（因為解密鑰與密文存在同一台機器的 guidant.env 與 DB）。要防到那個等級需要「原廠代理」（金鑰完全不落地客戶機，改由原廠伺服器代打 AI API），那是獨立需求，不在本案範圍。

install.sh 裝機寫入：原廠鑰的來源是 install.conf（裝機人員填寫，比照現有 S3／物件儲存憑證段的處理方式），裝機時寫入 ROOT 租戶的 AI_PROVIDER_CONFIG（走加密）；install.conf.example 只留欄位名與說明，值留空不入版控。--upgrade 模式不覆寫已存在的 ROOT 設定——客戶機上的值可能已經被後續操作改過，升級不該蓋回去。

粒度原則：每張卡單一 session 做得完；動套件的卡標 [套件]，開發走 poetry path dependency、完成不還原 pin（.6 T-6.2 統一還原）。驗收條件全部是 runner 與決策者都能親手做的動作。

FR-107.1 暫存批次＋安全地基 — 依賴：無（子需求卡 CM-1844）

FR-107.2 儲存 port＋容器改取檔 — 依賴：FR-107.1（子需求卡 CM-1845）

FR-107.3 分類跑在批次上 — 依賴：FR-107.2（子需求卡 CM-1846）

FR-107.4 歸檔進任務 — 依賴：FR-107.3（子需求卡 CM-1847）

FR-107.5 框架去硬編碼 — 依賴：FR-107.2（可與 .3／.4 平行）（子需求卡 CM-1848）

FR-107.6 舊線退場＋收口 — 依賴：全部（子需求卡 CM-1849）

環境：DEV（BE 本機、DB localhost:5432、STORAGE_CONFIG 指 local 或 seaweedfs 皆可）。準備：一個有 living SSP（catalog 2.13）且輪次已建任務的專案；manager 帳號 A、auditor 帳號 B、另一租戶 manager 帳號 C；5 份證據檔（其中 1 份已存在某任務證據裡）。

1. 地基：C 登入打 A 專案的批次列表 → 403。DEV SELECT count(*) FROM upload_files WHERE tenant_id IS NULL → 0。
2. 上傳：A 進專案總覽 → 「上傳證據批次」→ 選輪次 → 拖 5 檔 → 列表 5 筆 → 刪 1 → 4 筆 → 完成上傳 → 狀態「就緒」。B 登入看得到列表、沒有上傳按鈕。
3. 防呆（只 DEV）：清掉 tenant 的 STORAGE_CONFIG → A 建新批次 → 畫面明確錯誤；還原設定。
4. 分類：A 按「開始分類」→ 狀態「分類中」、上傳按鈕禁用 → docker ps 看到 evidence-classifier 容器、docker inspect 環境變數只有 AI 金鑰 → 完成進「審閱」。
5. 心跳：另建一批按分類 → 立刻 kill -9 BE → DEV 把該批 job_heartbeat_at 改成 40 分鐘前 → 重啟 BE → 批次「失敗」→ 按重跑 → 不必重傳。
6. 審閱：4 檔各對到檢查點；其中那份已在任務裡的檔有「與任務 X 既有證據內容相同」提示；加一個檢查點、標一個不適用、儲存、重整還在。
7. 歸檔：按「歸檔進任務」→ 摘要「已掛 X 檔／Y 筆證據／Z 檔無對應任務」→ 選清掉 → 狀態「已歸檔」。到「我的任務」對應任務證據頁看到檔帶「AI 分類」標籤。DEV：job_evidences 有 source='AI_CLASSIFIED' 且 classification_run_id 非空；upload_files 沒多列；evidence_batch_files 有 removed 列且 classification 非空；儲存後端上被清的實體檔不存在。
8. 冪等：DEV 手動把批次 status 改回 review 再按歸檔 → 摘要 evidence_created=0、job_evidences 筆數不變。
9. 框架：框架版本 2.13 →「AI 分類設定」→ 新增 profile persona「你是 XYZ 專家」→ 再跑一批 → run prompt_snapshot 開頭是那句；停用 → 再跑 → 通用。套件 resources/ 無 JSON。
10. 後端無關：STORAGE_CONFIG 切 seaweedfs → 步驟 2、4、7 重走一次，零程式改動。
11. 舊線：前端找不到舊「自動分類」按鈕；DEV 既有舊 run 從舊 URL 開仍可看、兩份報表可開。
12. 出貨：pyproject.toml 兩支套件是 pin；安裝包內有 evidence-classifier image（依 §11 裁示）。

• Drive 同步功能本身（cloud_integration）：不動。它負責「任務資料夾 ↔︎ Drive 資料夾」雙向；本案的批次不建 Drive 資料夾。
• 儲存後端切換搬家工具：既有 follow-up，不併本案（風險 3）。
• 全域 /tmp fallback 防呆：D6 只擋批次上傳路徑；套件全域行為另案（follow-up：改成啟動時警告）。
• 通用 job 表：D4 最小版，不在分類線內長通用能力。
• 跨來源去重：D9 只提示不阻擋。
• IUploadFileProvider 介面：不加方法；列目錄與搬移在批次檔表這層做。
• 舊 Drive 分類 route 刪除：D3 並存一版，下一版另開卡刪。

寫作時對照程式碼發現的矛盾與缺口，不在 D1–D11 範圍內，開卡前提交決策者裁定：

1. 現行安裝包沒有帶分類容器 image。scripts/build/ 與 scripts/installer/ 兩處 grep classifier 零命中——落地版客戶裝完就算有 API 也跑不了分類（docker run 找不到 image）。本案 T-2.3 把 image build 搬進套件 repo 後，image 要不要進 installer bundle、由誰 build、放哪個 registry（Harbor？），需要裁；T-6.2 的驗收依裁示調整。 裁示：進安裝包，隨三顆主 image 一起 build（走 FR-065 build 線）；拆分表 .6 新增 T-6.4「分類容器 image 進出貨包」（範圍：scripts/build/build_all.sh 加第四顆 image、build_bundle.sh 打包、installer compose 加 service；驗收：全新裝機後不手動拉 image 能跑完一次分類）。
2. 討論稿把 attach_to_job／remove_from_batch 放在 IEvidenceStorage；D11 後批次檔表在套件內，「掛進任務」屬任務疆界、「移出批次」是套件自己的表操作。本文改成：IEvidenceStorage 只管檔案實體（存／取／stage／刪），ITaskEvidenceSink 管找任務與掛證據，移出批次在套件內做。與討論稿不同，請確認。 裁示：照 design 這個切法——IEvidenceStorage 只管檔案實體，ITaskEvidenceSink 管找任務＋掛證據。
3. classification_profiles 放 compliance schema、framework_version_id 不建 FK（討論稿寫 oscal.classification_profiles 帶 FK）。理由：表由 jedi-evidence-classification 擁有，跨插件不建 FK（插件互不相依）。round_id、file_id 同理。若首腦要 DB 級完整性，要接受套件依賴 jedi-compliance-audit／jedi-oscal-v2／jedi-file-upload 的 model，與 D6 契約衝突。 裁示：不建 FK，一律軟參照，程式層查存在性；與現有插件契約一致。
4. profile CRUD 的守門軸：討論稿沒寫。「AI 分類設定」在框架版本管理頁，該頁是平台管理員軸；套件現有 IProjectRoleGuard 只有專案角色，需要新加一支平台管理員 port（本文 T-5.1 暫寫 IPlatformAdminGuard）。是否改為「租戶管理員可編自己租戶的 profile」需裁。 裁示：只給平台管理員，新加 IPlatformAdminGuard port；租戶層級等需求再開。 2026-09-17 修正：profile 守門放寬到租戶管理員（軸④capability storage-config.update，與 STORAGE_CONFIG 同一顆，理由見 PlatformAdminGuardAdapter docstring）——四層解析鏈裡租戶那兩層本來就只有租戶管理員自己建得出來，只給平台管理員的話那兩層永遠沒人用得到。AI 供應商金鑰設定頁維持鎖 ROOT 平台管理員（D13），兩者是不同守門軸，不要混為一談。
5. job_evidences partial UNIQUE 前的既存重複列：DEV／POC 可能已有同 (job_execution_id, file_id) 未刪的重複列（Drive 同步早期版本）。T-4.1 先查、有就回報，不自動合併；若有，合併規則要裁。 裁示：先查不合併，查出有再裁。
6. 舊 route 與新 route 並存期的 FE api.js 常數：舊十支保留給舊 run，新加約十二支；EvidenceClassificationService.js 會有兩套。可接受（D3 一版），但 .6 刪舊線時要一起清，記進 T-6.1 的 follow-up。 裁示：.6 刪舊線一起清（已在 T-6.1）。