讓 CRA 專案開得出工作、填得齊資料

狀態：討論稿（待裁 14 項）　｜　日期：2026-10-11　｜　輸入：step-zero-gap-list.md 第四節、cra-implementation-plan.md「第二期」

整案一句話：先讓任何沒有評估目標的框架也能在規劃頁看到條文、開得出收證據的工作；再讓 CRA 專案有地方填產品版本、支援期、通報窗口這些法規要的資料，而 CMMC 專案的畫面一點都不變。

給非工程讀者的背景：每本框架（CMMC、CRA）在系統裡是一棵「控制項樹」；控制項底下可以再分「評估目標」（AO，一條控制項要查的幾件具體事情）。CMMC 每條都有 AO，CRA 第一期刻意不建，結果暴露出系統有兩處只在「有 AO」時才會動。

依賴：平台層 A、B 互不相依，最先做。CRA 1 是 CRA 4 與風險評估頁籤的前提。CRA 3 與 CRA 4 的預設文字都要「重建 CRA 公版」才生效（D5），所以 CRA 層內容一次灌完再重建一次。決策者功課：請顧問確認 ① 7 條 AO 怎麼拆（D6）② 4～5 份文件範本內容（D10）③ Annex II 預設說明文字。

來源是 step-zero-gap-list.md 第四節，括號內是第〇步實測時受影響的條數。第 8 項「定期執行的證明」（1 條，II.3）四份探脈都沒查，本期不處理，列入範圍外。

平台層（任何沒有 AO 的框架都會踩到）

① 規劃頁看不到條文原文與建議證據（31 條）

• 白話問題：顧問在規劃頁只看得到「資料最小化」這種標題，法條原文與建議證據只在框架管理頁看得到。CMMC 有 AO 文字補上「要查什麼」，CRA 沒有就整個空掉。
• 現況：後端其實已把每條控制項的全部段落撈出來（app/oscal/service/ssp_control_implementation_service.py:224-227），卻只留下 AO、把條文（statement）與建議證據（guidance）丟掉（:226）。回傳的控制項物件沒有這兩欄（:820-832）；前端組樹時說明欄寫死空字串（FE ProjectPlanningView.vue:647）。沒 AO 時後端塞一個與控制項同名的假 AO（:792-803），畫面上是控制項底下一個同名節點、面板沒有任何「要查什麼」。

② 沒有 AO 時準備期一個工作都開不出來（31 條）

• 白話問題：建專案回 job_count: 0，準備期空轉，沒有工作能派給客戶收證據。
• 現況：程式其實已寫好「沒 AO 就在控制項層開一筆」（app/flow_control/service/prep_job_generation_service.py:165-166），但要找收證據的流程範本，來源只有兩個：AO 上掛的範本，或資源庫的 template_uid 退路（:168-169）。兩個都空時靜默略過（:170-172），只在 info log 記一筆 skipped（:220-225）。新建資源庫的寫入不寫 template_uid（app/oscal/service/resource_library_app_service.py:545-553），DEV 上 CRA 兩個資源庫 AO 數都是 0。

CRA 層（只影響 CRA）

③ 流程與文件類證據沒有材料（13 條）：CVD 政策、通報窗口、安全通告、支援期聲明，產品本身沒有、系統也沒幫客戶產出的地方。現況：SSP 匯出用寫死的 CMMC 範本（app/oscal/service/ssp_docx_generator.py:1-29），程序書池只能上傳掛載、不能渲染，系統沒有通用的「範本→產出」機制。

④ 證據只能掛整份檔（11 條）：FR-126 矩陣一份要掛 12 條，每條依據的 SR 只能寫在說明欄。現況：掛載對應表 oscal.ssp_reference_document_mappings 只有文件 id 與掛載對象，沒有章節欄（scripts/sql/2026-06-15-fr038-b3-ssp-reference-documents.sql:26-34）；說明欄在池本體，整份共用。另有一套舊掛法並存（見 §4「CRA 2」）。

⑤ 一條包多件事要拆 AO（7 條）：I.1、I.2.b、I.2.d、I.2.h、I.2.l、II.2、A2.8 的證據混在一起。現況：系統沒有手動新增 AO 的路徑——框架編輯端點只有改與刪（framework_version_edit_route.py:112-133），且只有草稿版可改，CRA 已發布。

⑥ Annex II 的「資訊本身」要結構化（6 條）：支援期結束日、通報窗口網址現在只能截圖或寫說明。現況：受評標的表已有擴充屬性（props，OSCAL 標準的自訂鍵值欄）oscal.ssp_system_characteristics.props（jedi-oscal-v2 oscal_ssp_system_characteristics.py:104），已存 target-type／owner-uid 兩鍵（app/module_frame/service/module_frame_system_characteristic_service.py:34-36），加鍵即可。

整體架構

%%{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 RL["資源庫（module_frames）"]
    P["① 控制項選集<br/>oscal_profile_uid"]
    S["② SSP 範本<br/>template_ssp_id"]
    F["③ 稽核流程範本<br/>audit_flow_template_uid"]
    T["收證據退路<br/>template_uid"]
    FS["④ 表單設定<br/>（新）"]
  end
  SYS["系統「收證據」範本<br/>（改 SYSTEM 層級）"]
  subgraph PJ["專案"]
    SSP["專案 SSP<br/>受評標的 props"]
    TREE["控制項樹<br/>＋條文／建議證據"]
    JOB["準備期工作"]
  end
  P -->|建專案複製| TREE
  S -->|深拷貝帶 props| SSP
  F -->|建首輪預設| JOB
  FS -.->|決定顯示哪些欄位| SSP
  SYS -.->|補值或讀時退回| T
  T -->|無 AO 時| JOB
  TREE -->|每 AO 或每控制項| JOB

平台層 A：控制項樹加條文與建議證據兩欄

• 做法：_resolve_inscope_catalog（ssp_control_implementation_service.py:165）本來就對每條控制項撈全部段落（:224-227），改成順手留下 statement 與 guidance；_build_control（:820）加 statement、guidance 兩欄。挑段落的邏輯沿用 framework_version_edit_service.py:266（_statement_prose）與 :272（_guidance_prose）。
• 不增 SQL：段落原本就全撈。CMMC L2 110 條合計約 50KB、CRA 31 條約 25KB，直接併進樹，不做延遲載入。每控制項各查一次的既有問題不是本案造成，不在本期處理。
• 順手收掉的重複查詢：分類器用的 build_classifier_catalog_by_ssp_id（:266-272）為了拿 statement 重打一次，改形狀後兩邊共用。
• 前端：ProjectPlanningView.vue:647 改接新欄位；控制項面板加「條文」「建議證據」兩塊，換行樣式照同頁 :2226；沒 AO 的退回分支（後端 :792）顯示控制項的建議證據。
• 命名：新欄位直接叫 statement／guidance，不沿用 description——框架管理頁的 description 是條文、規劃頁的 description 是空佔位，同字兩義。
• 影響面：control-tree 另有 6 頁在用（RoundAuditReview、RoundApAuthoring、ProjectAuditorOverview、EvidenceClassificationReview、AutoClassifyBatch 等），只加欄位不動既有欄位就不會壞。稽核執行頁 AuditControlRef.vue:65-66 已有欄位但 RoundAuditReviewView.vue:337-338 寫死空字串，要不要一併接起來在 design-platform.md 定。

平台層 B：沒有 AO 也開得出準備期工作

%%{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 API as 建專案 API
  participant ST as 啟動服務
  participant GEN as 準備期產生器
  participant WT as 流程範本表
  API->>ST: start_project
  ST->>ST: 讀資源庫 template_uid（可能是空）
  ST->>GEN: generate（fallback_template_uid）
  loop 每條在範圍內的控制項
    alt 控制項有 AO
      GEN->>GEN: 每個 AO 取 props 上的範本 uid
    else 沒有 AO
      GEN->>GEN: 控制項層一筆，取 fallback
    end
    alt 範本 uid 是空
      Note over GEN: 靜默略過 skipped+1（:170-172）
    else 有 uid
      GEN->>WT: 依 uid 取範本
      alt 本租戶讀不到（TENANT 範本跨租戶）
        Note over GEN: 一樣靜默略過（:173-175）
      else 讀得到
        GEN->>WT: clone 專案副本（同來源只 clone 一次）
        GEN->>GEN: 寫一筆準備期工作
      end
    end
  end

四處要改，缺一個都還是 0 工作或工作打架：

1. 系統「收證據」範本改成所有租戶讀得到：系統只有一份 compliance.workflow_templates uid f4038001-…0001「收證據」，DEV 上是租戶 102 的 TENANT 層級，其他租戶因 RLS（資料庫依租戶隔離）讀不到，get_workflow_template_by_uid 回空照樣略過。要改 SYSTEM 層級，並帶進出貨基線——但基線 scripts/init/04-seed-core.sql:824,868 目前強制 workflow_templates 必須為空（D4）。
2. 範本來源補上：兩條路擇一或併用（D12）——建資源庫的 INSERT 帶上系統範本 uid（resource_library_app_service.py:545-553），或啟動時讀到空值退回系統預設（project_start_app_service.py:146）。前者要回頭補 DEV 既有資源庫；後者既有資源庫自動生效。
3. 每條控制項各 clone 一份：現在 _clone_for 快取同來源只 clone 一次（prep_job_generation_service.py:142-156），31 筆工作共用一份副本，inject_job_execution_uid 覆蓋寫入只留最後一筆，流程編輯器存檔還會重複建工作（:139-141,194-203）。控制項層退回時改成每條各 clone。
4. 規劃頁控制項層那筆補範本 uid：ssp_control_implementation_service.py:796-803 有輪次時帶得到工作，但沒帶 workflow_template_uid／workflow_execution_uid，FE ProjectPlanningView.vue:1407 會提示「沒有流程」；無輪次的舊路徑（:488-494）依 AO props 找工作，控制項層工作看不到。

下游不用改（探脈逐一查過）：工作紀錄寫 (control_id=cid, ao_part_id=cid)（prep_job_generation_service.py:214-216）；指派綁工作 id（flow_control_job_repo_impl.py:548-552）；覆核輪沿用指派用 ao_part_id IS NOT DISTINCT FROM 配得上（reverify_clone_query.py:48）；稽核判定 ao_derivation.py:38-41 無 AO 同樣退回 (cid,cid)。

唯一例外在套件：覆核輪 jedi-compliance-audit audit_round_app_service.py:774-779 傳 fallback=None，控制項層一定略過（D8）。

CRA 1：資源庫第四件「表單設定」

• 落點取捨（D2）：

• 值存哪：使用者填的值存專案 SSP 受評標的 props，鍵加 ext: 前綴（例 ext:cra-support-end-date），避免撞到既有 target-type／owner-uid。寫入用既有非破壞合併工具（module_frame_system_characteristic_service.py:94-115），建專案深拷貝自然帶過去（ssp_clone_service.py:147-153）。
• 專案怎麼拿到設定（D3）：專案已記得資源庫（projects.module_frame_id，建專案寫於 project_start_app_service.py:374），但規劃頁拿的 GET /grc/project/<uid> 回應裡資源庫只有 id／name／group／version／frequency（jedi-compliance-audit api/serializers/project.py:203-212、project_dto.py:72-76）。兩條路：改套件 DTO 加欄，或主專案另開端點。
• 畫面：受評標的固定 8 欄（SspTabPanel.vue:339-342 → SspBasicSection.vue，useSspSystemCharacteristic.js:34），設定有值時在下方多渲染一段動態欄位；風險評估頁籤照雲端頁籤 v-if 先例（ProjectPlanningView.vue:416-429）。
• CMMC 不受影響的條件：設定為空就照現在固定頁籤與 8 欄；CMMC 公版不寫設定。
• CRA 公版怎麼帶設定：public_library_seed_cli.py 的 PublicLibrary dataclass（:18-23）加 form_settings，在 _seed_one 建庫之後（:79）、改名升 SYSTEM 之前（:80-83）同一個交易寫入。
• 建議結構（草案，design-cra.md 定稿）：{ "sections": {"risk_assessment": true}, "fields": [{"key": "ext:cra-support-end-date", "label": "...", "type": "date", "required": true, "options": null}] }，type 限 text／date／select／boolean。

CRA 2：證據指到檔內某一節（locator）

• 對應表 oscal.ssp_reference_document_mappings 加一個文字欄 locator，內容自由寫（「§4.2；SR 1.1, 2.3」），不做結構化——各家文件的章節格式不一。
• 連動五處：新增對應的請求、列出對應的回傳（jedi_compliance_audit SspDocumentPoolQuery）、FE 掛載對話框（ProjectPlanningView.vue:2509 DocumentLinkDialog）加輸入框、建專案複製（project_start_app_service.py:270,292）、快照還原（ssp_document_pool_service.py:216,249）。
• 舊套掛法：context_type=control_implementation|objective 直接寫在 ssp_reference_documents（寫 ssp_control_implementation_service.py:887,974-992、讀 :1010-1012），FE 上傳函式 handleUploadRefDoc（ProjectPlanningView.vue:1511-1533）沒有模板呼叫＝沒有入口，這就是「控制項詳情回空陣列」的原因；建專案也只複製新套。只在新套加 locator，舊套 API 繼續回空（D7）。

CRA 3：拆評估目標（AO seed 004）與重建公版

• 仿套件 003 的冪等寫法（以 part_id 判斷不存在才寫），新增 jedi_oscal_v2/migrations/004，7 條各寫 2～3 個 AO，key 用 {control_id}_obj.N。CMMC 的 AO 來自 PDF 解析器（cmmc2_lv2_parser_adapter.py:610-620），CRA 002 明寫不建 AO（:9），所以只能走 seed。
• 只對之後新建的資源庫與專案有效：建資源庫時整份複製 catalog（resource_library_app_service.py:500-501），AO 的流程範本也只在那時建（_init_ao_workflows，:236-278）。既有 CRA 公版與第〇步測資吃不到（D5）；本期稍早灌的 guidance 同理。
• 生效後：拆了 AO 的 7 條準備期自動變每 AO 一筆（prep_job_generation_service.py:160-172），稽核計畫的查核項（assessment_plan_app_service.py:401）跟著 AO 走。其餘 24 條仍靠平台層 B 的退路開工——拆 AO 不能取代平台層 B。

CRA 4：Annex II 結構化欄位與預設文字

• 結構化值：受評標的 props 加 6 個鍵（例 ext:cra-support-end-date、ext:cra-vuln-contact-url），由 CRA 1 的表單設定宣告、受評標的頁渲染。不開新表、不加新欄。
• 預設說明文字：放「適用控制項預設值」——資源庫範本 SSP 的實作需求 props（implementation-description 等，module_frame_control_default_service.py:1-16,36-41,187-201），建專案隨範本 SSP 複製。A2.x 的預設說明文字是純資料，寫進 CRA 公版 seed。
• 與規劃稿的落點差異：規劃稿把「漏洞揭露政策、通報窗口、通報人員」放組織層資訊系統盤點，探脈建議放受評標的 props（D13）。

資訊系統版本子表

• compliance.information_systems（scripts/sql/packages/jedi_asset/001-asset-tables.sql:97-118）沒有版本欄。建議 jedi-asset 新子表 information_system_versions（資訊系統 FK、版號、上市日、支援期結束日、理由）＋CRUD 端點＋FE InformationSystemManage.vue 子清單。
• SSP 端軟關聯不動：受評標的 inventory_items.props 存 ref-type=information_system＋ref-id（module_frame_inventory_service.py:43-46）。專案要不要「選到某個版本」（規劃稿樹狀圖寫「專案（選系統與版本）」）探脈未查、待驗，design-cra.md 定。

風險評估頁籤（最小雛形）

• 現況：專案頂層頁籤固定六個（ProjectPlanningView.vue:405-413），SSP 子頁籤固定四個（SspTabPanel.vue:336-386），SSP 層完全沒有風險表；風險只存在稽核結果層 oscal.assessment_risks（oscal_ar_risk.py:25，characterizations JSONB :59）與 POA&M 畫面（RoundPoamView.vue:533-633）。
• 已裁第一版是手填登錄表，預留「威脅來源」「元件連結」兩欄。存放處 D9。頁籤顯示由表單設定的 sections.risk_assessment 控制。
• 規劃稿寫「風險資料掛在系統主檔、由專案頁籤寫入」，若照此做就要掛到資訊系統而非 SSP；D9 一併裁。

文件範本進程序書池

• 系統沒有通用的範本產出機制（SSP 匯出寫死 CMMC docx，摘要報告是 Jinja HTML→PDF，common/util/html_pdf.py:26）。
• 最小做法：CVD 政策、通報窗口、安全通告、支援期聲明等 4～5 份 docx 放 CRA 公版的資源庫程序書池（/module-frame/<uid>/reference-documents），預掛到 13 條控制項；建專案整池複製（project_start_app_service.py:229-297）。客戶下載填寫、再上傳成證據。屬純資料（S），範本內容是顧問功課（D10）。
• 「填欄位自動產出」（docxtpl＋Annex II props）是 M～L，屬第三期「三份文件範本」範圍，本期不做。

自家 SBOM：可匯，但不會變成證據

• build 產 CycloneDX JSON（scripts/build/sbom.sh:60,70），安裝包收進 sbom/（build_bundle.sh:30,359-361）；源碼掃描對象端點收 CycloneDX 1.2–1.6、SPDX 2.1–2.3（target_route.py:130-145）——現在就能匯。
• 但掃描模組與控制項證據沒有連結，要當 I.2.a／II.1 證據只能下載報告再手動上傳（D14）。

• P2-A 四張卡互不碰 CRA 內容，可立刻派；A1 與 B1 平行。
• P2-D 的 C4 是收口卡：所有要進 catalog 或公版的資料灌完後只重建一次。
• 合計約 14 張卡；design-platform.md 管 P2-A，design-cra.md 管 P2-B～D。

沿革見 handoff/FR-135-LOG.md 與 git log。