oscal 逐檔分類

實查日期：2026-09-16 ｜ 當時 HEAD：84b8426a ｜ branch：feature/review

🔴 本表是某一天的快照，引用前先重驗。 每個數字下方都附了產生它的指令，重跑一次比相信這份表安全。

oscal 是主專案最大的一塊自有資產，不是套件的殼：163 支檔案裡， 11,494 行（57.5%）是主專案自己寫的業務（Word／Excel 解析、兩份文件比對、 CMMC 格式轉換、匯入管線），4,757 行（23.8%）是轉接殼（把前端的欄位名翻成 jedi_oscal_v2 套件的形狀、再交給套件存），其餘 3,619 行（18.1%）是序列化器、 DTO、mapper 這類接線與型別。

真業務是殼的 2.4 倍——比 module_frame 那邊的 1.45 倍更懸殊。原因是這個模組 獨佔了整個「把客戶的既有文件吃進系統」那條線：domain/oscal/parser/（2,027 行） 與 app/oscal/service/import_diff/（1,384 行）合計 3,411 行零套件引用， 套件完全不參與。

殼的部分則高度集中在兩處：框架維護四支（framework_*，1,101 行， 主體是 v1 形狀 ↔︎ v2 形狀的來回翻譯）與 SSP 子物件五支（ssp_party ／components ／inventory_items／leveraged／system_characteristic，714 行）。

四層規模

另有 di_containers/oscal/oscal_containers.py（509 行，不在四層內，判 DI 註冊時要看）。

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git rev-parse --short HEAD
for L in api app domain infra; do
  d=$L/oscal
  printf '%-22s %s 檔 / %s 行\n' $d \
    "$(git ls-files $d | grep '\.py$' | wc -l | tr -d ' ')" \
    "$(git ls-files $d | grep '\.py$' | xargs wc -l | tail -1 | awk '{print $1}')"
done

對外 route：61 條

用 AST 數（不是 regex——add_resource( 常換行寫，regex 會漏抓）。 61 條全部在 api/oscal/__init__.py 統一註冊，掛 blueprint oscal、前綴 /api/1.0。 注意：所有 route 註冊都寫在 __init__.py，各 route 檔本身只定義 Resource 類別。

另有 3 條被註解掉不計入（grep -rn "^\s*#.*add_resource" api/oscal/）：

前端四層查的第三層先講清楚

ui_routes 全庫只有 1 列與本模組相關—— id=33, name='compliance-framework-manage', url='/compliance-framework/compliance-framework-manage', enable=1。 它是選單項不是 API，管的是「左側選單看不看得到合規框架管理」這一件事； 61 條 API route 不會逐條出現在 ui_routes 裡。SSP 那批（/ssp/*，佔 61 條的 40 條） 更是完全不經選單——它們掛在專案頁面內的分頁裡（/project/projects/:id/...）， 由專案選單進入。因此下表不設第三層欄位，在此統一交代。

PGPASSWORD=<查 .env> psql -h localhost -p 5432 -U cmmgr -d guidant_ai_dev \
  -c "SELECT id, name, url, enable FROM public.ui_routes
      WHERE name ILIKE '%framework%' OR name ILIKE '%ssp%' OR name ILIKE '%oscal%';"

route 清單與前端查證結果

四層＝① 前端 API 常數表 src/config/api/api.js ② 前端實際呼叫（.vue／service/*.js） ③ DB public.ui_routes（見上段）④ 非瀏覽器呼叫者（scripts/、e2e）。

框架維護（13 條）

資源庫（4 條）

SSP 匯入（8 條）

SSP 子物件維護（14 條）

SSP 程序書池與控制項實作（16 條）

匯出與範本 SSP（3 條）

第 61 列不是 BE 的 route（AST 只數到 60 條掛在 oscal blueprint 上、加上第 59 的 /ssp/<uid>/export 共 61）。列在此是因為前端確實會打這個路徑，而 BE 全 repo 沒有 任何地方註冊它——屬於前端打得到但後端不存在的缺口，詳見 ⑤。

這模組自己持有的表

compliance.framework_parse_jobs、compliance.ssp_docx_parse_jobs、 compliance.ssp_excel_parse_jobs 三張匯入工作表，ORM 在 infra/oscal/model/。 模組所有其他資料——框架、版本、catalog、profile、SSP 本體與所有子物件—— 都不在主專案的表，而是由 jedi_oscal_v2 持有。這是本模組「殼」那一半的由來： 三張 job 表記的是「這份檔案解析到哪、使用者選了什麼」，解析完寫進套件就結束。

四類的判準（依賴方向，不是檔名）

• 真業務：主要邏輯自己寫，jedi_* 引用少或零；刪掉這支功能就消失。
• 轉接殼：主體是「開 @transaction → 呼叫套件 service → 欄位對應」，商業規則在套件。 殼不等於可刪——它是「主專案回答套件問題」的必要接線。要另外標「有沒有帶主專案獨有規則」。
• 共用設施：沒有 route、沒有自己的業務語意，是給別的模組或別的檔用的（DTO、序列化器、 error code、port、mapper、resolver）。
• 死碼：全 repo 零 import、零 route 註冊、零 DI 註冊（四層都要查才算）。
• 還看不準：允許存在，要寫卡在哪。本表 0 支。

api/oscal（67 檔／3,984 行）

routes/ — 20 檔／2,314 行

這模組的守門位置與 module_frame 相反，是刻意的。 module_frame 的 route 幾乎每支 都掛 @require_capability(...)（主體域守門：只看「你是誰」）；oscal 的 SSP 那批 route 一個也沒掛——因為它們是資源域守門：要先把 ssp_uid 反查成專案、才知道 要判這個人在哪個專案裡的角色。route 層表達不了，所以統一落在 app service 的 SspPermissionChecker。這符合 common/authz/ 的雙軌設計（CLAUDE.md 授權守門段）。

serializers/ — 47 檔／1,670 行

除下列四支外，其餘 43 支全是 共用設施（純 marshmallow Schema，零業務、零 DB； oscal_common/ 下 19 支另被 api/project/serializers/project.py 與 api/module_frame/serializers/module_frame.py 借用，是跨模組的欄位契約）。

⚠️ 這五支死 schema 用 grep import 抓不到、也不能只看 grep 命中數。 它們互相用 marshmallow 的字串式 fields.Nested("X") 引用，形成一個封閉的小圈： ssp.py 引 SystemCharacteristic／SystemImplementation，oscal_framework_menu 引 oscal_framework_version_menu，而圈外沒有任何人引用這個圈。守衛測試 test/test_module_boundaries.py:2028-2042 把這幾行列為字串式 Nested 白名單， 理由寫的是「本卡範圍外未動」——那是說明沒清，不是說明它們是活的。

app/oscal（46 檔／10,964 行）

service/ — 直屬 14 支，模組的重心

ssp_control_implementation_service.py 的殼段／業務段拆解

這支 1,004 行、19 個套件引用，是全模組最像「殼」卻最不是殼的一支。按方法區塊估算：

粗分約 業務 611 行／殼 104 行／工具 82 行，其餘是 import 與類別骨架。 這個拆法是按方法區塊估的，不是逐行計數。

import_diff/ — 4 檔／1,384 行，整包零套件引用

grep -rnE '^\s*(from|import) jedi_' app/oscal/service/import_diff/ | wc -l   # → 0

import_adapter/ — 6 檔／1,057 行

excel_parser/ — 7 檔／1,047 行

export/ — 6 檔／883 行

dto/ — 3 檔／29 行

domain/oscal（36 檔／4,549 行）

parser/ — 7 檔／2,027 行，整包零套件引用

grep -rnE '^\s*(from|import) jedi_' domain/oscal/parser/ | wc -l   # → 0

adapter/ — 4 檔／959 行

service/ — 14 檔／1,043 行

entity/ 與 repository/ — 10 檔／520 行

infra/oscal（14 檔／499 行）

分類單位是檔。混住兩種性質的檔（如 ssp_control_implementation_service.py 是業務＋殼、 ssp_document_pool_service.py 是殼＋業務）按主體歸類，另在 ② 表的證據欄註明混住情形。

共用設施佔過半檔數但只佔 18.1% 行數——裡面有 22 支空的或只有一兩行的 __init__.py， 加上 43 支純 marshmallow Schema 與一批 dataclass。看行數比看檔數準。

git ls-files api/oscal app/oscal domain/oscal infra/oscal \
  | grep '\.py$' | while read f; do printf '%s\t%s\n' "$(wc -l < "$f"|tr -d ' ')" "$f"; done

按層分布：

四件事從這張表看得出來：

1. api/ 一支真業務都沒有，全是殼與序列化器。這是乾淨的形狀——route 層不該有業務。 對照 module_frame 那邊 api/ 還有一支 162 行的真業務（route 層自己用 pandas 讀 Excel 比對欄位標題）， oscal 這邊沒有同類問題。
2. domain/ 3,121 行真業務、零殼——這是全模組最值錢的一塊：Word 解析（2,027）、 CMMC 轉換（860）、比對器（202）、匯入還原（208）。套件完全不參與。
3. 殼集中在 app/ 與 api/（4,757 行的 100%），與 module_frame 同形。
4. 六支死碼全在 api/，且全是序列化器與一支被註解掉的 route，沒有一支在 app/ 以下。

對 FR-102 總表 B 該列（README.md:100）逐句核對：

FR-102 對本模組的五句證據沒有一句已失效，兩句需要精確化。

判準是「說得出證據才叫可收」。下面每一項都附了怎麼驗它真的沒人用。 本卡只分析不動程式，列在此處是備妥證據，清不清屬異動、要決策者裁。

4.1 一支被註解掉的 route 檔（39 行）

api/oscal/routes/oscal_export_route.py 整檔（定義 OscalExportRoute）。

四層查證結果：

怎麼驗：

grep -rn "OscalExportRoute" --include='*.py' . | grep -v __pycache__
grep -rn "oscal/export/" ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/
grep -rn "oscal/export/" ~/Projects/Billows/Audit-Manager/compliance-manager-test/site-regression/

⚠️ 但它背後的 OscalExportAppService（47 行）是活的，不能一起收—— api/oscal/routes/framework/oscal_framework_version_route.py:138 用它做框架的 OSCAL 下載 （export('catalog', catalog_uid, fmt='json')），走 flow_control_container 注入。 另外三處註解文字（ssp_export_app_service.py:6,113、oscal_containers.py:406） 寫著「json/yaml/xml 匯出已移至 OscalExportRoute」——那個目的地其實是關著的， 這三行說明與現況不符。

4.2 兩條註冊了但前端零呼叫的資源庫端點

GET /oscal/resource-library/<uid>（詳情）與 POST /oscal/resource-library/<uid>/publish（發布）， 對應 resource_library_route.py 的 ResourceLibraryRoute（67-73 行）與 ResourceLibraryPublishRoute（76-84 行）。

四層查證結果：

怎麼驗：

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
grep -rn "RESOURCE_LIBRARY\b" src/ | grep -v "config/api/api.js"
grep -rn "resource-library/" src/
cd ~/Projects/Billows/Audit-Manager/compliance-manager-test
grep -rn "resource-library/" site-regression/steps/ site-regression/support/ site-regression/pages/

⚠️ 兩支背後的 service 方法不能一起收：

• get_resource_library（resource_library_app_service.py:205）被六處後端內部呼叫 （ssp_excel_import_app_service.py:367,464,817、ssp_docx_import_app_service.py:165,337,454,603）， 是匯入線驗證「這個資源庫存不存在」的手段。
• publish_resource_library（:533）只有這個端點呼叫，收掉端點等於收掉整個發布功能。 「發布」是資源庫從租戶私有變成系統公版的唯一途徑（建立端點刻意不掛平台管理員守門， 就是因為治理靠發布這關擋）。列在此處只是標出「目前對外不可達」，不是建議砍。

4.3 五支互相引用成封閉圈的死序列化器（87 行）

以及 api/oscal/serializers/__init__.py:10-14 對它們的五行 re-export。

四層查證結果：

怎麼驗（必須連字串式 Nested 一起查，只 grep import 會漏）：

for c in SystemSecurityPlanResponseSchema SystemCharacteristicResponseSchema \
         SystemImplementationResponseSchema OscalFrameworkMenuResponseSchema \
         OscalFrameworkVersionMenuResponseSchema; do
  echo "--- $c"
  grep -rn "\b$c\b" --include='*.py' . | grep -v __pycache__ | grep -v '^./docs/'
done

每一支的命中應該只有三種：自己的 class 定義、serializers/__init__.py 的 re-export、 圈內另一支的字串式 Nested。有第四種就表示它是活的。

🔴 兩個清理時會踩的坑：

1. 名字只差三個字母。 活的是 ssp_system_characteristic_inproject.py 的 SspSystemCharacteristicResponseSchema（有 Ssp 前綴，被 ssp_system_characteristic_route.py:14,23,38 用）；死的是 ssp_system_characteristic.py 的 SystemCharacteristicResponseSchema（無前綴）。 同理框架選單：活的是 oscal_framework.py:70 的 OscalFrameworkMenuSchema（無 Response）， 死的是 oscal_framework_menu.py 的 OscalFrameworkMenuResponseSchema（有 Response）。 grep 時不加 \b 邊界會兩邊一起命中，直接誤判。

2. 守衛測試的白名單不是「它是活的」的證明。 test/test_module_boundaries.py:2028-2042 把這幾支的字串式 Nested 行列在白名單，理由寫「本卡範圍外未動」——那是 FR-092 第 18 棒的作業範圍註記。真要清，這幾行白名單也要一起移除，否則守衛會 指向不存在的檔案行號。

4.4 沒有的

以下曾被懷疑、實查後確認不可收，列在此處避免下一個人重查：

• infra/oscal 三張匯入工作表的 repo：三支都有寫入者也有讀取者（各自的 domain service 被對應的 app service 注入），沒有孤兒。
• ssp_scoped_excel_import_route.py 的兩個被註解類別：雖然 route 註冊被註解，但 同檔的 SspScopedExcelImportUploadRoute 仍註冊且前端在用（SspExcelImportService.js:56）， 整檔不可收，只有那兩個類別可議——而它們的 service 方法是共用的，收了也省不到行數。
• app/oscal/service/oscal_export_app_service.py：見 4.1 的警告，框架 OSCAL 下載在用。

5.1 兩支匯入匯出 service 各寫一份 Excel 欄位契約

app/oscal/service/ssp_control_impl_import_service.py（431 行）與 app/module_frame/service/module_frame_template_import_service.py（1,008 行） 各自定義了同一份 Excel 樣板的欄位契約。實查逐項比對結果：

逐字重複的約 25 行（module_frame 那側的檔頭第 3 行明寫「格式對齊 app/oscal/service/ssp_control_impl_import_service.py」）。

為什麼現在動不了：三個候選落點各有代價，且與「這兩個模組誰是誰的上游」這個更大的 疆界問題綁在一起——

• 抽到 common/：兩邊都只是引用者，但「Excel 樣板的欄位契約」不是通用工具， 放 common/ 會讓 common/ 開始長業務知識。
• 留在其中一側讓另一側引用：現有依賴方向是 oscal → module_frame（v2 子物件 的欄位對應表、Excel sheet 定義都在 module_frame 那側定義），照這個方向應該是 module_frame 定義、oscal 引用。但 _P_STATUS／_P_DESC 的方向恰好相反 （module_frame 自己寫一份，oscal 從自己模組內 import）——兩個方向並存。
• 進套件：欄位標題是中文、是主專案的 FE 契約，套件不該知道。

需要什麼前置：先定「module_frame 與 oscal 誰是誰的上游」。目前跨模組 import 共 9 處、方向全是 oscal → module_frame（app/oscal 六支引用 app/module_frame 的 service 與 excel_template/sheet_definitions），反向只有 3 處 （module_frame 的 ssp-resources service、兩支 serializer、一支匯出 route）。 方向已經很清楚是 module_frame 在上游，但這與直覺相反（oscal 比較大、比較底層）， 需要決策者確認這是刻意的還是長歪的。

5.2 五支 SSP 子物件殼與資源庫範本版是共用不是重複

卡片問「五支 ssp_*_app_service 與 module_frame 六支殼是否鏡像」。實查結論： 不是兩份真相，是同一份——五支全都直接 import module_frame 那側的對應表：

五支的檔頭都明寫「欄位 mapping 與資源庫範本版完全相同……故直接共用其純 mapping 靜態方法，確保兩端一致、單一真相。差別只在『ssp_id 從哪來 ＋ 權限』」。 module_frame 那一側的分類表記的也是同一件事，兩邊對得上。

module_frame 那側是六支（多一支 ModuleFrameSspResourcesService）， oscal 這側對應的 SspResourcesAppService 走的是第三支共用 service （ssp_resources_context_service.py，住在 oscal 這側，被兩邊共用）—— 所以嚴格說是 5 ＋ 1 對 5 ＋ 1，不是六對六。

卡在哪：這五支殼繼承了範本版的空值哨兵——套件的資料表有幾個欄位不准留空， 前端允許留空，主專案就塞假值進去（party_uuid 塞全零 UUID、date_authorized 塞今天）， 讀出來時再換回空白。這件事在 module_frame 那一側的分類表也列為待裁。 在 oscal 這一側看，問題更嚴重一級： 範本 SSP 是內部資料，專案 SSP 是租戶的實際稽核資料，全零 UUID 與「今天」這個假日期 會跟著匯出進客戶的系統安全計畫書。目前 _to_dict 有換回 None，但那是讀路徑的補救—— 任何第三個寫入者（例如未來新增的批次匯入）不知道這個看不見的約定，就會把假值寫成真值。

需要什麼前置：與 module_frame 那一側同一題——jedi_oscal_v2 除本專案外還有沒有別的使用者。 有就只能維持現狀；沒有就該把欄位改成可留空。

5.3 殼裡混著業務、拆不拆會影響套件契約的三支

下列三支的「殼」與「業務」纏在同一個方法裡，不是分開的區段，拆解會動到套件契約：

這三支不列在 ④「可以立刻收的」，因為它們不是可收，是可能該搬——而搬的前提是 先決定套件契約要不要變。

5.4 前端打得到、後端不存在的一條路徑

前端 src/service/ModuleFrameTemplateService.js:198 打 GET /oscal/catalog-controls/<control_uid>/assessments，常數定義在 api.js:180。 後端全 repo 沒有註冊這條 route（grep -rn "catalog-controls" --include='*.py' . 零命中， 套件側也零命中）。

呼叫者是 ModuleFrameTemplateEditView.vue:566 的 loadAOsForControl()。 現況不會壞，因為那段程式碼上方註解寫明「AO 已在 buildTreeFromProfile 從 module_frame.oscal_profile 預載，此處 cache 應該總是命中。走 API 只是防呆」， 且整段包在 try/catch 裡、失敗只 console.warn 並回空陣列。

卡在哪：這是個沉默的後備路徑——真的走到（快取沒命中）時會拿到 404， 然後靜默回空陣列，前端的 AO 清單變空白、不報錯。要嘛後端補這條 route， 要嘛前端把這個後備拿掉改成明確報錯。屬前端與後端契約問題，不在本卡的分析範圍內。

另外兩條同型的（都在 ComplianceFrameworkVersionManage.vue）： OSCAL_FRAMEWORK_VERSION_IMPORT（/oscal-framework-version/import/<type>）與 OSCAL_FRAMEWORK_VERSION_SAMPLE_DOWNLOAD（/oscal-framework-version/download/sample） 後端也都不存在。但這兩條的前端入口本身是關著的——開啟該對話框的選單項 onUpdateVersionDocClick 在 :596-599 被整段註解（註解寫「v2 兩階段化後暫時隱藏」）， 所以使用者點不到。三條合起來看是同一件事：框架匯入從舊的「上傳整份文件」 改成新的「解析工作」兩階段流程後，前端留下了指向舊端點的殘骸。

本表遇到「兩種合理判法、不自選」的有三件：

一、module_frame 與 oscal 誰是誰的上游

跨模組 import 的方向已經很清楚是 oscal 依賴 module_frame（9 處對 3 處）， 包括五支 SSP 子物件的欄位對應表、Excel sheet 定義。但這與規模直覺相反 （oscal 兩倍大、概念上更底層）。

• 維持現狀（module_frame 是上游）：零風險，但每個新來的人看到「大模組依賴小模組」 都會想反過來改，而改了會壞。
• 反轉（把共用的欄位對應表搬去 oscal）：符合直覺，但要動五支 SSP 子物件 service ＋六支 module_frame service，且 module_frame 那側的 Excel 樣板產生器（1,656 行） 也在被 oscal 引用，一併反轉範圍會很大。

判斷需要的資訊：這兩個模組未來會不會有一個進套件。若 module_frame（資源庫） 要進套件，現在的方向剛好（套件不能依賴主專案）；若 oscal 要進，方向就是錯的。

二、5.1 那約 25 行 Excel 欄位契約要不要抽、抽去哪

module_frame 那一側的分類表也把這題列為待裁，建議兩個模組的結果一起看。 從 oscal 這一側實測，逐字重複約 25 行，但變數名不一致 （HEADER_LABELS vs EXPECTED_HEADERS）反而是更麻煩的部分——兩邊各改一次時， grep 同一個名字只會找到一半。

三個候選落點與代價見 5.1。這題與第一題綁死，建議一起裁。

三、四類「對外不可達」的東西要不要清

「清」屬異動，本案只分析不動程式。