module_frame 逐檔分類

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

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

module_frame 不是「真業務與轉接殼各半」，真業務比殼多：81 支檔案裡， 5,563 行（50.8%）是主專案自己寫的業務（Excel 範本產生器、YAML／Excel 匯入、BPMN 流程編排）， 3,831 行（35.0%）是薄薄一層的欄位對應殼（把前端的欄位名翻成 OSCAL 的形狀、再交給 jedi_oscal_v2 套件存）， 其餘 1,548 行（14.1%）是序列化器、DTO、mapper 這類接線與型別。

而那六支被懷疑「與 oscal 那邊各寫一份」的殼，實查後發現沒有兩份真相—— oscal 那五支是直接 import 這邊的對應表來用，這邊才是唯一的定義處。

四層規模

另有 di_containers/module_frame/module_frame_containers.py（不在四層內，判 DI 註冊時要看）。

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git rev-parse --short HEAD
for L in api app domain infra; do
  d=$L/module_frame
  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：45 條

用 AST 數（不是 regex——add_resource( 常換行寫，regex 會漏抓）。 45 條全部掛在 blueprint module-frame、前綴 /api/1.0。

⚠️ 與派工卡上的「43 條」不符——實際是 45 條。 這不是新增的 route： FR-102 總表 A 該列（README.md:58）寫的就是 45，卡片轉述時誤植為 43。 45 是本棒 AST 實跑的結果。

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

route 清單與前端四層查結果

四層＝① FE src/config/api/api.js 常數 ② FE 路由 src/config/router/index.js ③ DB public.ui_routes（DEV localhost:5432/guidant_ai_dev）④ 非瀏覽器呼叫者（scripts/、e2e）。

第三層先講清楚：ui_routes 全庫只有 1 列與本模組相關—— id=24, name='module-frame', url='/module-frame/module-frame', enable=1。 它是選單項不是 API，管的是「左側選單看不看得到資源庫」這一件事； 45 條 API route 不會逐條出現在 ui_routes 裡。因此下表第三層對所有 route 都是同一個答案 （該選單開著＝整組頁面可達），逐條列會變成 45 個一樣的格子，故不設欄，在此統一交代。

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

FE 路由第二層共 9 條 /module-frame/*（router/index.js:412-491）： module-frame／module-frame-items／:uid/template-edit／import-docx／:uid/import-docx／ import-excel／:uid/import-excel／import-excel/preview/:parseUid。

表列 43 列是把成對的 list／item route 併列顯示，展開後即 45 條路徑。

這模組自己持有的表

compliance.module_frames + compliance.module_frames_trans（多語系翻譯表）兩張， ORM 在 infra/module_frame/models/。模組所有其他資料——控制項預設值、AO 預設值、 程序書池、元件、資產清冊、外部授權、系統特性、參與方——都不在這兩張表， 而是存在該 module_frame 的樣板 SSP（module_frames.template_ssp_id → oscal.ssps）底下， 由 jedi_oscal_v2 的 SspService 負責讀寫。這是本模組「殼」那一半的由來。

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

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

api/module_frame（25 檔／2,763 行）

app/module_frame（31 檔／7,416 行）

service/ — 13 支，模組的重心

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

卡片問「一支檔混了多少種事」。按方法區塊估算：

粗分約 殼 355 行／業務 975 行／工具 170 行。這個拆法是按方法區塊估的，不是逐行計數。

excel_template/ — 7 檔／1,656 行，整包零 jedi 引用

grep -rnE '^\s*(from|import) jedi_' app/module_frame/excel_template/ | wc -l → 0。 卡片要求實查確認，已確認。

dto/ 與 code/ — 8 檔／240 行

domain/module_frame（12 檔／348 行）

infra/module_frame（13 檔／415 行）

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

共用設施佔過半檔數但只佔 14.1% 行數——因為裡面有 16 支空的或只有一兩行的 __init__.py，加上一批純 dataclass 的 DTO 與 mapper。看行數比看檔數準。

# 逐檔行數（分類請照 ② 表）
git ls-files api/module_frame app/module_frame domain/module_frame infra/module_frame \
  | grep '\.py$' | while read f; do printf '%s\t%s\n' "$(wc -l < "$f"|tr -d ' ')" "$f"; done

按層分布：

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

1. 殼全部集中在 api/ 與 app/ 兩層，domain/ 與 infra/ 零殼—— 代表這模組的「自持資料那一半」（兩張表的 entity／repo／model）是乾淨的主專案資產， 混住只發生在對外那兩層。
2. app/ 一層就佔了真業務的 88%（4,891／5,563 行），其中光三支大檔 （ssp_import_template 1,500、template_import 1,008、import_service 415）就 2,923 行。
3. api/ 的 14 支殼共 1,813 行是典型的 route 轉呼叫層，每支 56～281 行，沒有異常肥大的。

對 FR-102 那句「真業務與 v2 轉接殼約各半」的回答：以行數算是 真業務 5,563 ／ 轉接殼 3,831 ＝ 1.45 : 1，真業務明顯多於殼，不是各半。 FR-102 該句是模組層級的粗估，方向（兩種都有、混住）對，比例要修正。

判準是「說得出證據才叫可收」。下面每一項都附了怎麼驗它真的沒人用。

4.1 兩個已無 route 註冊的 Resource 類別

api/module_frame/routes/module_frame_route.py 裡的 ModuleFramesRoute（第 44-62 行） 與 ModuleFrameStartRoute（第 113-131 行），以及 __init__.py:14 對它們的 import。

四層查證結果：

怎麼驗：

grep -rn "ModuleFramesRoute\|ModuleFrameStartRoute" --include='*.py' . | grep -v __pycache__
grep -rn "/module-frames\b\|/module-frame/start" ~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/

⚠️ 但它們背後的 service 方法不能一起收：

• ModuleFramesRoute 吃的 get_module_frames_and_pager 是 ModuleFrameDomainService 也有的同名方法，而 domain 那支被 repo 層用著。
• ModuleFrameStartRoute 吃的 start_project_from_module_frame（module_frame_service.py:226-265） 確實只有這個被註解的 route 在呼叫——但它裡面編排的「啟動專案 → 建摘要報告」是完整功能， 砍掉等於砍功能。列在此處只是標出「目前對外不可達」，不是建議砍。

4.2 兩支只在被註解的前端程式碼中出現的下載端點

GET /module-frame/download/template 與 GET /module-frame/download/yaml-template （module_frame_import_route.py 的 ModuleFrameTemplateDownloadRoute／ModuleFrameYamlTemplateDownloadRoute）。

四層查證結果：

同組還有 POST /module-frame/import/template（ModuleFrameImportTemplateRoute）， FE 的 importFromExcel() 整支被註解（ModuleFrame.vue:737）。 注意這三支是同一組：下載 Excel 範本 → 填 → 上傳匯入，前端把整條流程註解掉了。 但同檔的 import/verify／import／import/yaml 三支仍在用（:1019／:1050／:847）， 所以 ModuleFrameImportService 這支 service 不可整支收。

怎麼驗：

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
grep -rn "MODULE_FRAME_TEMPLATE_DOWNLOAD\|MODULE_FRAME_YAML_TEMPLATE_DOWNLOAD\|MODULE_FRAME_IMPORT_TEMPLATE\b" src/
# 三處命中全部前綴 "//"

⚠️ 這兩支 route 讀的是 GLOBAL_DOWNLOAD_DIR 下的 audit_frame_template_v1.xlsx／.yaml 兩個隨版檔案；收 route 時要一併確認那兩個檔還有沒有別的用途。

4.3 沒有找到的東西（如實記錄）

卡片點名的兩個「可以立刻收」候選，實查後都不成立：

(a) 六支 v2 殼與 oscal 五支「兩份真相」——不成立。 oscal 那五支直接 import module_frame 這邊的對應表，不是各寫一份：

五支的檔頭都明寫「與資源庫範本版完全相同……故直接共用其純 mapping 靜態方法， 確保兩端一致、單一真相。差別只在 ssp_id 從哪來 + 權限」。 module_frame 這邊是定義處，oscal 那邊是引用者，收不掉也不該收。

第六支 module_frame_ssp_resources_service.py 方向相反——它 import app/oscal/service/ssp_resources_context_service.py，共用的實作在 oscal 那邊。

另外 app/flow_control/service/assessment_plan_app_service.py:57 也 import module_frame_party_service 的 _build_props 與 _to_email_list——三個模組共用同一份對應表。

(b) module_frame_template_import_service.py（1,008 行）與 app/oscal/service/ssp_control_impl_import_service.py（431 行）是不是重複實作——部分重複，但不是可立刻收的。

實查逐項對照：

結論：可抽出共用的是「Excel 欄位契約與樣式」那約 40 行常數（三組逐字相同）， 不是整支 service。而那 40 行要抽到哪裡、抽了會不會又變成 module_frame 與 oscal 互相 import 的第三條線，屬設計問題——列進 ⑤。

(c) 沒有死碼。 81 支全部通過四層查（模組內 import／模組外 import／DI 註冊／route 註冊）。 最接近的是 4.1 那兩個 Resource 類別，但它們在 __init__.py 有 import， 不符「四層全零」的死碼定義，故歸「疑似死碼」記錄而非死碼。

只說「為什麼現在動不了、需要什麼前置」，不給完整方案。

5.1 Excel 欄位契約散在三處，抽出來會製造新的跨模組依賴

現況：SSP 控制項現況說明的 Excel 格式（9 欄標題、6 個狀態值、配色邊框） 在 module_frame_template_import_service.py（資源庫範本端）與 app/oscal/service/ssp_control_impl_import_service.py（專案端）各寫一份逐字相同的常數。 第三處是 app/module_frame/excel_template/sheet_definitions.py——它定義的是另一套 （SSP 匯入的九張表），被 app/oscal/service/excel_parser/sheet_handlers.py import。

為什麼現在動不了：抽到哪裡沒有現成答案。抽進 common/ 要問「Excel 欄位標題算不算跨模組共用型別」； 留在 module_frame 讓 oscal import，會讓 oscal → module_frame 的依賴再多一條 （目前已有六條：五支 service mapping ＋ sheet_definitions）； 抽進 jedi_oscal_v2 套件則要問「中文欄位標題是不是套件該知道的事」—— CLAUDE.md 對套件的判準是「屬套件 domain 的才進套件」，中文標題像是產品知識。

需要的前置：先確定 module_frame 與 oscal 這兩個模組的最終疆界（誰是誰的上游）， 再決定共用常數往哪邊放。這件事等 oscal 的逐檔分類結果（FR-105 另一支產出）。

5.2 六支 v2 殼「殼裡混著業務」，拆不拆會影響套件契約 → 需要決策者裁

現況：六支殼每一支都不是純轉呼叫，都帶了主專案獨有的規則（見 ② 表的「殼帶主專案規則」欄）。 以 module_frame_leveraged_service.py 為例，它做三件事：

1. 欄位對應（FE 名 ↔︎ OSCAL props）— 這是殼該做的
2. NN 欄空值哨兵（party_uuid 空落 NIL-UUID、date_authorized 空落 date.today()）— 這是在繞套件 schema 的 NOT NULL 約束
3. 同名去重、暱稱 enrich — 這是產品規則

第 2 項是關鍵：檔內註解寫「套件 import_ssp 用 party-uuid or "" 對 uuid 欄是 latent bug （無 party-uuid 的 SSP 匯入會 500），但屬 import 路徑、本期非 scope」。 也就是說主專案這一側在替套件的設計缺口補位。

兩種合理判法，後果不同：

這題不自選，列出來問決策者。 判斷需要的資訊：jedi_oscal_v2 除了本專案還有沒有別的 consumer、以及決策者對「主專案替套件補位」的容忍度。

5.3 module_frame_service.py 是模組內依賴最雜的一支，拆之前要先決定 BPMN 歸誰

現況：304 行、jedi=11／host=9。它同時碰四個外部套件 （jedi_flow_engine 的 workflow template 與 execution、jedi_task_platform 的 participant、 jedi_common 的分頁與 session）與三個主專案模組 （app/flow_engine、app/project_summary_report、domain/module_frame）。

裡面 96 行的 clone_module_frame 是自寫的 BPMN 深拷貝 （複製主流程 → 逐個複製子流程 → 把主流程 XML 裡的 called_element_id 全換成新 id）。 module_frame_item_service.py 的 219 行也幾乎全是 BPMN 增刪改。

為什麼現在動不了：「資源庫範本要不要綁一條 BPMN 流程」這件事本身 正在 FR-104（流程疆界重新分析）被重新檢視。 在那邊有結論之前，動這兩支 BPMN 邏輯等於押注一個還沒定的方向。

需要的前置：FR-104 的結論。

5.4 di_containers/oscal/oscal_containers.py 註冊了六支 module_frame 的 service

oscal_containers.py:57,60,63,66,69,88 註冊了 module_frame_system_characteristic_service、 components、inventory、leveraged、party、ssp_resources 六支， 而它們的 route（在 api/module_frame/）也是從 Containers.oscal_container 取注入。

這不是錯——這六支殼的資料落點在 oscal.ssp_* 表，DI 依落點分組有其道理。 但它造成「module_frame 的 route 從 oscal 的 container 取 service」這個反直覺的接線， 新人照 module_frame_containers.py 找會找不到。

為什麼現在動不了：移動 DI 註冊會同時改到 oscal 那側的 wiring， 而 DI 簽章漂移是靜默的（Factory 是 lazy，對不上只在該端點被打時才炸）。 要動需要把六支的端點逐一實打驗過。

需要的前置：oscal 的逐檔分類，確認 oscal 那側對這六支的依賴全貌。

FR-102 README.md:101 對 module_frame 的證據欄共 5 句。逐句核對結果：

沒有任何一句已失效；兩句需要精確化（「全自寫」與「約各半」），一句需要補充（同型是六支）。

1. 六支 v2 殼裡的「NN 欄空值哨兵」要不要退回套件解（§5.2 的 A／B 兩案）。 關鍵未知：jedi_oscal_v2 除本專案外還有沒有別的 consumer。

2. Excel 欄位契約那約 40 行逐字重複的常數要抽到哪裡（§5.1）。 三個候選落點各有代價，且與「module_frame 和 oscal 誰是誰的上游」這個更大的疆界問題綁在一起。

3. §4.1 與 §4.2 那五個對外不可達的端點要不要清（兩個被註解的 Resource ＋ 三個前端只在註解中呼叫的下載／匯入端點）。 證據已備齊（四層查證結果見該節），但「清」屬異動、本棒只分析不動程式。