沒有評估目標的框架，也看得到條文、開得出工作

狀態：設計定案｜日期：2026-10-11｜範圍：第二期 P2-A（平台層 A／B，四卡 A1／B1／B2／B3）｜CRA 層 P2-B～D 見 design-cra.md 討論稿（現況盤點、方案比較、D1～D14 原文）：phase2-discussion.md

🔴 這份是設計決策，不是現況。 內文行號停在 2026-10-11（BE 89aadc59b、FE 9d50d2d1），實作改動後不回頭改寫；上線後的現況看 SPEC 頁。

第〇步拿 CRA 31 條在 DEV 走完一輪，露出兩個跟 CRA 無關、任何框架只要控制項底下沒有評估目標（AO，Assessment Objective，一條控制項要查的幾件具體事）就會踩到的缺口：

1. 規劃頁看不到條文與建議證據：顧問在規劃頁只看得到控制項標題。CMMC 每條都有 AO 文字補上「要查什麼」，所以沒人發現；CRA 沒有 AO，畫面就只剩一個標題。後端其實已把每條控制項的全部段落撈出來，只是只留 AO、把條文（statement）與建議證據（guidance）丟掉。
2. 沒有 AO 時準備期一個工作都開不出來：程式已寫好「沒有 AO 就在控制項層開一筆」，但收證據的流程範本來源全空，於是靜默略過，建專案回 job_count: 0，只在 info log 記一筆 skipped。

為什麼不限 CRA 做：之後的 SEMI E187、ISO 系列、客戶自訂框架多半也不會一條條寫 AO。這兩處修在平台層，CRA 只是第一個用到的框架；CMMC 這類有 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 建專案／發起覆核
  participant ST as 啟動服務
  participant GEN as 準備期產生器
  participant WT as 流程範本表
  API->>ST: start_project（或 launch_reverify）
  ST->>ST: 讀資源庫 template_uid
  Note over ST: 空值 → 退回系統「收證據」範本（新）
  ST->>GEN: generate（fallback_template_uid）
  loop 每條在範圍內的控制項
    alt 有 AO
      loop 每個 AO
        GEN->>GEN: 範本來源＝AO props 的 workflow-template-uid，沒有才用 fallback
      end
    else 沒有 AO
      GEN->>GEN: 控制項層一筆（AO 編號＝控制項編號），範本來源＝fallback
    end
    alt 範本來源仍是空，或讀不到
      Note over GEN: 略過並記 warning，寫出控制項編號（新）
    else 讀得到（SYSTEM 範本所有租戶可讀）
      GEN->>WT: 每條各 clone 一份專案副本（控制項層不再共用，新）
      GEN->>GEN: 建工作、注入工作 uid、寫控制項對應紀錄
    end
  end

覆核輪（launch_reverify）走同一支產生器，差別只在範本來源：有 AO 讀 AO props 現值；控制項層改為從上一輪同一控制項的對應紀錄取上一輪的專案副本再 clone（本期新）。

整案一句話：任何沒有 AO 的框架，規劃頁也看得到條文與建議證據；建專案時每條控制項各開一筆收證據的工作，覆核輪照樣開；有 AO 的框架畫面與行為一點都不變。

依賴：A1 與 B1 平行；B2 等 B1；B3 等 B2（要用到 B2 寫的對應紀錄形狀）。A1 不碰 B 系列任何檔。

決策者已裁（2026-10-11，討論稿 D4／D8／D12）

本文件實作層決定

座標以 BE 89aadc59b、FE 9d50d2d1、jedi-compliance-audit 工作樹為準。

5.1 A1：控制項樹帶條文與建議證據

後端（app/oscal/service/ssp_control_implementation_service.py，1,058 行，已超標——本卡只改既有函式內幾行，不新增函式；挑段落的小工具放新檔）：

1. 新檔 app/oscal/service/control_part_prose.py：兩個純函式 statement_prose(parts)、guidance_prose(parts)，挑法照 framework_version_edit_service.py:266-276（取第一筆 name 相符段落的 prose，沒有回 None）。不把 framework_version_edit_service 那兩個私有方法改成共用——它們是 instance method，改動會牽連框架編輯頁；兩處各自五行，留在 domain-capabilities.md 登記「段落挑法 canonical 在 control_part_prose.py」。
2. _resolve_inscope_catalog（:224-228）：迴圈內 get_by_control 的結果先存變數，AO 照舊進 parts_by_cc，另建 prose_by_cc[cc.id] = (statement, guidance)。回傳從三元組改四元組 (all_groups, controls, parts_by_cc, prose_by_cc)。
3. 兩個呼叫端一起改：build_control_tree_by_ssp_id（:474-477）與 build_classifier_catalog_by_ssp_id（:261-272）。後者刪掉自己重打的那段，改從 prose_by_cc 取 statement；stmt.prose or stmt.title or "" 的兜底保留（statement_prose 回 None 時用空字串）。分類器輸出契約不變（docstring 明訂只可加欄）。
4. _build_control 回傳（:806-817）加 "statement": stmt or None, "guidance": guid or None。
5. 不增 SQL：段落原本就逐條全撈。CMMC L2 110 條合計約 50KB、CRA 31 條約 25KB（探脈量測），直接併進樹不做延遲載入。逐條查詢（N+1）是既有現象，不在本卡處理。

前端（ProjectPlanningView.vue 2,638 行，已超標——只准加引用，邏輯進新元件）：

1. :647 控制項組樹多帶 statement: c.statement ?? ''、guidance: c.guidance ?? ''；description: '' 保留（其他程式可能讀它，待驗後再收）。
2. 新元件 src/components/grc/planning/ControlReferenceText.vue：props statement、guidance；兩塊各自 v-if 有值才渲染，標題用 i18n lang.project_planning.control_statement／control_guidance（zh_Hant_TW／en 兩檔都補）；內文 white-space: pre-wrap，樣式照同頁 :2226 的 text-sm＋var(--text-secondary)。
3. :2201 下方一行 <ControlReferenceText :statement="selectedControl.statement" :guidance="selectedControl.guidance" />。
4. 無 AO 的假節點（後端 :792-804）不另外塞建議證據：控制項面板已經顯示兩塊，點假 AO 節點時面板仍是同一個控制項，重複顯示無意義。這點與討論稿「無 AO 退回分支顯示控制項建議證據」不同，理由是面板層級已涵蓋。

影響面：control-tree 另有 6 頁在用（RoundAuditReview、RoundApAuthoring、ProjectAuditorOverview、EvidenceClassificationReview、AutoClassifyBatch 等），只加欄位、不動既有欄位，不會壞。CMMC 控制項同樣會顯示兩塊（CMMC 條文與建議證據本來就有資料）——這是刻意的：顧問在 CMMC 也需要看到條文；AO 面板不受影響。

5.2 B1：收證據範本系統化＋空值退回系統預設

migration scripts/sql/2026-10-xx-fr135-collect-evidence-template-system.sql，manifest 登記 phase=seed、envs=*：

1. 冪等 UPSERT 這一份範本：INSERT ... ON CONFLICT (uid) DO UPDATE SET scope='SYSTEM', tenant_id=1, updated_at=now(), updated_user='system'。BPMN 內容照 scripts/sql/2026-06-15-fr038-q1-seed-collect-evidence-template.sql 原文（start → userTask collect_evidence → end）。不寫顯式 id（既有客戶庫的 id 已被佔，先例同 fr093-4d）。
2. 翻譯列：workflow_templates_trans 依 workflow_template_id 補一列（language_code 與 xml），冪等用 NOT EXISTS。DEV 現況這份範本沒有翻譯列（2026-10-11 查），_clone_for 走 create_workflow_template 會自己建副本的翻譯列，本份是否必須有翻譯列待驗——runner 先在 DEV 實測 clone 一次確認讀得到 xml，讀得到就不補。
3. 檔頭寫清楚：scope 必須本檔自己給（停在預設 TENANT 時，非 1 號租戶讀不到且 RLS 靜默無錯）；只套 DEV。
4. 收尾 INSERT public.schema_migrations。

程式：

1. prep_job_generation_service.py 加模組常數 SYSTEM_COLLECT_EVIDENCE_TEMPLATE_UID = "f4038001-0000-4000-8000-000000000001"（與 _DEFAULT_PREP_TASK_ID 並列，註解一行：「對外契約，migration 與此同值，不可改」）。
2. generate() 開頭：fallback_template_uid = fallback_template_uid or SYSTEM_COLLECT_EVIDENCE_TEMPLATE_UID——只在首輪模式（reclone_from_props=False）。覆核輪的來源由 B3 處理，B1 不改覆核輪行為。
3. docstring 的 fallback_template_uid 說明改一行：「空值退回系統收證據範本」。

DEV 套用：只套 DEV（環境異動鐵律）。套完確認：SELECT scope, tenant_id FROM compliance.workflow_templates WHERE uid='f4038001-…0001' → SYSTEM|1。

出貨基線：本支是 phase=seed，不進 99-stamp 蓋章，不需重產 02-schema／04-seed；新裝由 init_apply_package_content 套上。runner 仍照 sql-migration skill 回報「已確認不需重產基線」一句。

5.3 B2：控制項層每條各 clone＋可觀測＋規劃頁帶得到流程

1. clone 粒度（prep_job_generation_service.py:142-175）：_clone_for(src_uid, shared=True) 加參數；呼叫處 cloned = _clone_for(src_uid, shared=part is not None)。shared=False 時不讀不寫快取、每次新建副本。來源範本只讀一次：get_workflow_template_by_uid 的結果另用 src_cache 存，避免 31 條各查一次。
2. 為什麼要拆：同來源共用一份副本時，inject_job_execution_uid（:204-210）每條都改寫同一份 xml，最後只留最後一條的工作 uid；流程編輯器開其他 30 條會把它們當「新任務」重複建工作（:139-141 註解已點名這個不變量）。
3. 略過可觀測（:170-175）：兩處 skipped += 1 前加 logger.warning("generate_prep_jobs skip control=%s ao=%s reason=%s src=%s", cid, ao_part_id, "no-template-source"|"template-not-readable", src_uid)。
4. 規劃頁帶得到流程（ssp_control_implementation_service.py:792-804）：有輪次時 key=(cid,cid)，補 "workflow_template_uid": wf_uid_by_key.get(key)、"workflow_execution_uid": we_uid_by_key.get(key)；無輪次時兩欄給 None（P6）。FE 不用改，:647 附近 AO 組裝已讀這兩欄、:1406-1410 有值就能開流程編輯器。

5.4 B3：覆核輪控制項層從上一輪取範本

現況：覆核輪呼叫 generate(..., reclone_from_props=True, fallback_template_uid=None)（套件 audit_round_app_service.py:774-779）。有 AO 時來源是 AO props 現值（首輪回填過的專案副本），控制項層沒有 props 可讀，於是一定略過。

設計：

1. 套件（jedi-compliance-audit）：generate() 多傳 parent_round_id=round_entity.parent_round_id。只改這一處呼叫；round_entity 已在手上（launch_reverify 建輪時寫入 parent_round_id=parent.id，:655）。
2. 主專案產生器：generate() 加 parent_round_id: Optional[int] = None 參數。覆核輪模式且 part is None 時，來源改為「上一輪同一 (cid, cid) 對應紀錄的流程執行所用的範本 uid」，查不到才略過（照 B2 記 warning）。
3. 查詢放哪：新方法 get_round_control_template_uids(round_id) -> {control_id: template_uid}，加在 infra/flow_control/repository/reverify_clone_query.py（176 行，與承襲配對同主題）。一次查整輪，SQL：workflow_execution_control_mapping 以 round_id 與 ao_part_id = control_id 過濾 → workflow_executions.template_id → workflow_templates.uid。flow_control_job_repo_impl.py 1,215 行已超標，不加在那裡。產生器透過 DI 注入（di_containers/flow_control/flow_control_containers.py:289 已有 reverify_clone_query provider 可接）。
4. 承襲不用改：新輪工作建好後，inherit_from_parent 以 (control_id, ao_part_id) IS NOT DISTINCT FROM 配對（reverify_clone_query.py:48），控制項層兩輪都是 (cid,cid)，指派人、部門設備、證據照常承襲。
5. 發版：jedi-compliance-audit 進一版，走套件規範（dev 期 poetry path dependency、發版與推 Nexus 等決策者明示）。舊版套件不傳 parent_round_id 時，產生器參數預設 None，行為與現在相同（控制項層略過）——主專案可以先上、套件後上。

依本專案測試政策（碎片卡預設不寫新 unit test），本期四卡的測試要求如下：

全卡共同：commit 前跑 pytest test/test_module_boundaries.py test/security/code/（幾秒）。

每節可直接轉成 Notion 卡內文。四卡共同鐵則：不切 branch、不 push；只動 DEV；顯式 git add 自己的檔；超過 800 行的檔只准抽出、不准往裡塞；檔內註解只寫為什麼與陷阱，經過寫進 commit message；做完立刻 commit＋Notion 子卡回寫＋狀態改「修正待驗證」。

A1 規劃頁顯示條文與建議證據（BE＋FE 同卡）

• 做什麼：控制項樹多帶 statement／guidance，規劃頁控制項面板顯示「條文」「建議證據」兩塊；分類器順手刪掉重複查詢。設計見 §5.1。
• 改哪些檔：BE 新檔 app/oscal/service/control_part_prose.py；app/oscal/service/ssp_control_implementation_service.py:224-228（解析）、:261-272（分類器刪重複查詢）、:474-477（接四元組）、:806-817（回傳加兩欄）；docs/claude/domain-capabilities.md 補一列。FE 新檔 src/components/grc/planning/ControlReferenceText.vue；src/views/project/ProjectPlanningView.vue:647（組樹）、:2201（引用一行）；i18n 兩語系各兩個 key。
• 驗收（可親手做）：① 開 CRA 第〇步專案規劃頁，點 I.1 → 面板出現「條文」「建議證據」，建議證據的條列分行顯示 ② 開任一 CMMC 專案規劃頁點 AC.L1-3.1.1 → 兩塊出現且 AO 列表與改前一樣 ③ 稽核執行頁、證據分類審閱頁開得起來、控制項樹正常 ④ 證據自動分類跑一批，build_classifier_catalog_by_ssp_id 輸出的 statement 與改前一致（拿同一 SSP 比對改前後 JSON）。
• 依賴：無。可與 B1 平行。
• 規模：S。
• 要帶的鐵則：體積上限（兩支都超標，新邏輯一律新檔）；新增 method 前先查既有能力（挑段落沿用既有挑法，不另發明）；分類器輸出契約只可加欄。

B1 收證據範本系統化＋空值退回系統預設

• 做什麼：一支 phase=seed migration 把「收證據」範本改 SYSTEM、新裝帶上；產生器首輪模式讀到空值退回這份。設計見 §5.2。
• 改哪些檔：新檔 scripts/sql/2026-10-xx-fr135-collect-evidence-template-system.sql；scripts/sql/manifest.tsv 加一列（seed／*）；app/flow_control/service/prep_job_generation_service.py 常數＋generate() 開頭一行＋docstring 一行。不動 scripts/init/04-seed-core.sql 與 gen_seed_sql.sh。
• 驗收（可親手做）：① DEV 套 migration 兩次，第二次無錯無變化 ② SELECT scope, tenant_id FROM compliance.workflow_templates WHERE uid='f4038001-0000-4000-8000-000000000001' 回 SYSTEM|1 ③ 以非 102 租戶帳號用 CRA 公版建專案，log/app.log 的 generate_prep_jobs 彙總行 skipped=0（B2 未做前 jobs 可能是 31 但共用副本，屬預期） ④ 用 CMMC 資源庫建專案，工作數與改前相同。
• 依賴：無。
• 規模：S～M。
• 要帶的鐵則：SQL Migration 鐵則（日期註解、檔頭 -- Date:、收尾登 schema_migrations、--single-transaction -v ON_ERROR_STOP=1、用 cmmgr）；環境異動鐵律（只套 DEV）；改 scripts/sql/ 當次跑 ddd-compliance-reviewer；回報「本支 phase=seed，不需重產出貨基線」。

B2 控制項層每條各 clone＋略過可觀測＋規劃頁帶得到流程

• 做什麼：沒有 AO 的控制項每條 clone 自己的流程副本；略過記 warning；規劃頁控制項層那筆補範本與流程 uid。設計見 §5.3。
• 改哪些檔：app/flow_control/service/prep_job_generation_service.py:142-175；app/oscal/service/ssp_control_implementation_service.py:792-804；新測試 test/test_prep_job_control_level_clone.py。
• 驗收（可親手做）：① 以非 102 租戶用 CRA 公版新建專案 → 準備期 31 筆工作 ② SELECT count(DISTINCT we.template_id) FROM public.workflow_execution_control_mapping m JOIN compliance.workflow_executions we ON we.id=m.workflow_execution_id WHERE m.round_id=<新專案首輪 id> 回 31 ③ 規劃頁任開兩條的流程編輯器，第一條加一個任務存檔，第二條任務數不變 ④ 每條控制項都能開流程編輯器、不再提示「沒有流程」 ⑤ 把資源庫範本暫時指到一個不存在的 uid 再建專案，log/app.log 出現 31 行 generate_prep_jobs skip ... reason=template-not-readable（驗完改回） ⑥ CMMC 專案建立結果與改前一致。
• 依賴：B1。
• 規模：M。
• 要帶的鐵則：體積上限（ssp_control_implementation_service.py 只改既有分支內兩行）；新測試要做突變驗證；DB 寫入只在 DEV。

B3 覆核輪控制項層從上一輪取範本（含 jedi-compliance-audit 發版）

• 做什麼：套件傳 parent_round_id；主專案產生器覆核輪模式下控制項層從上一輪對應紀錄取範本。設計見 §5.4。
• 改哪些檔：套件 jedi-compliance-audit/jedi_compliance_audit/app/service/audit_round_app_service.py:774-779；主專案 infra/flow_control/repository/reverify_clone_query.py（新方法）、app/flow_control/service/prep_job_generation_service.py（參數與分支）、di_containers/flow_control/flow_control_containers.py（注入）。
• 驗收（可親手做）：① CRA 新專案首輪對一條（例 I.1）指派人員、判「不符合」，走到發起覆核 ② 覆核輪規劃頁 I.1 底下有一筆工作，指派人與首輪相同 ③ 該筆工作的流程編輯器開得起來，改它不影響首輪那份 ④ CMMC 專案跑一次覆核輪，工作數與改前相同。
• 依賴：B2。
• 規模：S（套件一行）＋S（主專案查詢）。
• 要帶的鐵則：jedi-* 套件異動規範（開工前在卡上列「動哪支套件、範圍、其他 consumer 風險」等決策者點頭；dev 期走 poetry path dependency，path 改動不 commit；發版與推 Nexus 等決策者明示）；主專案向下相容（舊套件不傳參數時行為不變）。

%%{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
  A1["A1 規劃頁條文"]
  B1["B1 範本系統化"] --> B2["B2 每條各 clone"] --> B3["B3 覆核輪"]
  A1 --> V["P2-A 驗收"]
  B3 --> V

四卡全部「修正待驗證」後，決策者在 DEV 一次跑完（先全部跑完、收集失敗，再一起修）：

1. 新租戶建 CRA 專案：以非 102 的租戶登入，用 CRA 公版（SYSTEM 451，或 D5 重建後的新公版）建專案 → 準備期 31 筆工作；log/app.log 該次 generate_prep_jobs 行 jobs=31 skipped=0。
2. 規劃頁：點任一條看得到「條文」「建議證據」兩塊、段落換行正常；每條都能開流程編輯器。
3. 流程互不干擾：任選兩條，第一條流程加一個任務存檔，第二條不變；重整後第一條仍是新流程。
4. 覆核輪：首輪判一條不符合後發起覆核 → 覆核輪那條有工作、承襲首輪指派人。
5. CMMC 不變：用 CMMC 資源庫建專案，工作數、規劃頁 AO 面板、覆核輪工作數與改前一致（改前數字由 A1／B1 runner 在動工前先記下，寫在 Notion 卡上）。
6. 新裝：等下一次封安裝包時，新裝機查 compliance.workflow_templates 有且僅有這一份 scope=SYSTEM 的「收證據」（本項跟著下次出包驗，不為此單獨出包——驗收打折處見下）。

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