設計定案：單 binary 兩模式，六步管線，四棒拆分

狀態：設計定案待實作（D1–D11 已拍板）｜建立日期：2026-08-14｜三階段戰線第一棒：FR-063 編譯 → FR-064 防竄改 → FR-065 Installer 討論稿（唯一素材來源，user 已審）：discussion.html｜Notion 母案：CM-1187

產品進入落地版（on-premise）交付階段——客戶主機上不可再出現一行可讀原始碼。本案把 BE 整包用 Nuitka standalone 編成機器碼 binary、包進 Linux Docker image 交付，與 FR-062 既有 license 執法構成雙保險。範圍限定 Linux 容器版；防竄改（FR-064）、Installer 與 Windows 支援（FR-065，傾向 Docker Desktop / WSL2 跑同一 Linux image）是後兩棒。

選型脈絡（前期已定）：比較過 .pyc（compileall）／ Cython ／ PyArmor ／ Nuitka 四條路。Python 3.11 反編譯工具鏈已斷裂（uncompyle6 / decompyle3 停在 3.8 前後），純 .pyc 其實已有基礎保護力，但決策者拍板採 Nuitka standalone 取得最高保護等級，對齊 Grafana / HashiCorp 等 Go binary 陣營的交付形態（源碼可見陣營如 GitLab / Sentry 僅靠 license 執法）。

2026-08-13 夜間實測（STG 機 /opt/guidant_ai，Nuitka 4.1.3 / Python 3.11，4 core / 32GB）：冷 build 1h27m、產物 main_app.dist 808MB、8,613 支 C 檔全編、pymupdf.mupdf.c 單檔 34 分鐘（平行化不可壓縮地板）。試跑 import 期即炸 SystemError: dynamic module 'dependency_injector.providers' not initialized properly from def——根因與修法已定案為 D2。

%%{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
  SRC["原始碼樹<br/>（統一入口＋<br/>resource_path 收斂後）"] --> PIPE["Build 管線六步<br/>（build 機 24c/32GB，<br/>全 script 化）"]
  PIPE --> BIN["Nuitka dist<br/>單 binary 兩模式<br/>＋隨附資料檔"]
  BIN --> IMG["Production image<br/>非 root · gunicorn 內嵌<br/>fc-match 斷言"]
  IMG --> SMOKE["Smoke 七項探針"]
  SMOKE --> CUST["客戶主機<br/>容器內無 .py 業務原始碼<br/>＋FR-062 license 雙保險"]

十一項均已定案（細節與完整理由見討論稿「決策定案 D1–D11」節）：

三路掃描（動態 import／__file__ 路徑／外部依賴）結果總表——完整明細（#4 四處資料檔、#10 volume 清單、#14 jedi- 環境變數清單）見討論稿「現況盤點」節，此處不重複貼*：

掃過確認安全（getattr/registry 字串、inspect.getsource 零命中、BytesIO 串流匯出、__import__("uuid") 常量、runtime listdir）——見討論稿「✅ 掃過確認安全」。

5.1 統一入口（D9 + D7 + D1）

新增統一入口（骨架以 main_app.py 邏輯為主），RUN_MODE 環境變數切換 api（預設）/ socketio；main.py / main_app.py / main_socketio.py 三支全退役。單一 binary、容器 command 只差環境變數。

模式裁剪載入表（現況兩入口幾乎孿生，socketio 背著全部 REST blueprint＋4 個 scheduler job 雙跑）：

• SocketIO namespace 集中註冊（FR-063.4 補）：兩個 namespace（/socket/notification、/socket/fill-survey）原本註冊在各模組 create_module() 內，被本表「socketio 模式不載 REST blueprint」一併裁掉，導致即時功能全失效（api 模式有定義沒端點、socketio 模式有端點沒 namespace）。修法為抽離至 config/socketio_namespaces.py 集中清單，由 create_app(enable_socketio=True) 在 DI wiring 之後統一註冊（handler 走 @inject，早於 wiring 建構會安靜拿到佔位物件）。該清單同時是 Nuitka 顯式 include 的來源，心智模型同 REGISTERED_APPS 與 DI 靜態清單。
• eventlet 條件塊：eventlet.monkey_patch() 收進 if mode == "socketio":，且必須在其他 import 之前——Python import 執行到才發生，Nuitka 保留模組執行順序語意，編譯後行為不變。
• gunicorn 內嵌（D7）：api 模式 production 承載採 gunicorn BaseApplication API——在我們的程式內起 master/worker，入口仍是我們的 binary；worker 數走環境變數。開發模式保留 Flask dev server（開關切換，開發體驗不變）。
• PyCharm debug 保障（歷史脈絡：當初拆兩檔正是 eventlet monkey_patch × pydevd 衝突）：RUN_MODE 不設或 =api 時 import eventlet 那行根本不執行、stdlib 零觸碰，debug 體驗與現行 main_app.py 完全等價；patch 收進條件塊後誤觸面比現狀更小。
• 工程注意：socketio 模式 DI 最小集邊界要實際盤（socket handler 依賴回追），第一版「不載 blueprint、不起 scheduler、DI 照全量」求穩——裁過頭會踩隱性依賴。
• 紅利：socketio 進程瘦身（啟動快／記憶體省／8002 不再暴露整套 REST API）、scheduler 收斂單一持有、eventlet × Nuitka 實測覆蓋面縮小。

5.2 DI 靜態清單機制（盤點#1）

• gen script：從現行 config/di_modules.py 的 rglob 掃描結果 dump 產 config/di_modules_static.py（build 期執行，Step 3）。
• 雙軌：開發模式照舊動態掃（加檔即生效，開發體驗不變）；release 模式吃 build 期凍結的靜態清單。
• 一致性驗證：gen script 是兩軌之間唯一的橋——掃描結果 dump 下來就是靜態清單，不存在第二套手維護名單；同一份程式碼兩模式行為等價。

%%{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 TB
  subgraph DEV["開發模式（現況不變）"]
    D_SRC["原始碼樹 .py"] --> D_SCAN["di_modules.py<br/>rglob 動態掃"]
    D_SRC --> D_RES["resource_path()<br/>回原始碼樹"]
  end
  subgraph REL["release 模式（Nuitka 產物）"]
    R_BIN["統一入口 dist<br/>binary＋隨附資料檔"] --> R_STATIC["di_modules_static.py<br/>build 期產的靜態清單"]
    R_BIN --> R_RES["resource_path()<br/>回 dist 根"]
  end
  D_SCAN -. "gen script<br/>build 期 dump" .-> R_STATIC

5.3 resource_path() 設計（D3，盤點#4/#8/#11）

單一入口：開發模式回原始碼樹、打包模式回 dist 根。全部要收斂的讀取點：

順帶搬遷／清理項（同棒做掉）：

1. catalog seed 搬出 docs/（release 產物不該讀 docs/）
2. 下載範本移出 static/（解盤點#8 雙重身分衝突）
3. 清掉三處指向不存在目錄的 Blueprint static 宣告（盤點#11，含 module_frame_import_route.py:32 現在就壞的下載路徑）
4. 刪 api/__init__.py 死碼 load_routes()

5.4 Build 管線六步（D2 / D5 / D6）

全 script 化——build 機只是算力，搬家零成本（D5）。

5.5 Production image 規格（D8，盤點#5/#7/#9/#10/#13/#14）

• 非 root 固定 uid（如 1000）專用使用者；entrypoint：先 chdir 固定工作目錄（解盤點#7 log 路徑）→ chown volume 目錄（解掛載 uid/gid 不合老問題）→ 起 binary。
• OS 依賴：沿用現行 E2E Dockerfile apt 清單（LibreOffice / WeasyPrint 系統庫 pango·harfbuzz·gobject·fontconfig / fonts-noto-cjk 等）；WeasyPrint 的 .so 走 image apt 裝齊、不打進 binary（盤點#13）。build 期 fc-match 'Noto Sans CJK TC' 斷言——缺字型 PDF 回 200 但中文整段消失（盤點#5）。
• volume 佈局：

• 環境變數注入：正式進入點不載 .env，全靠外部注入；DB_SECRET / JWT_SECRET / REDIS_SECRET import 期就 json.loads——缺了 import 階段直接炸。主專案 60+ 變數以各 Config class 為準、.1 收斂時產完整對照表；jedi- 套件內另有 16 個主專案 grep 不到的變數*（ENABLE_MULTI_TENANT、DB_USERNAME 等，完整清單見討論稿盤點#14），落地版部署文件必列。

5.6 Smoke 驗收清單（七項探針）

「編得出來」≠「功能活著」——本案地雷多為靜默失效型，逐雷探針缺一不可（FR-064/065 復用）：

5.7 Config 三層重整（D11）

分層判準——「誰、多常、需要改它」：

第 1 刀：六套環境 class 塌成一套 Config

• 保留單一 Config（以現 BaseConfig 為底）；DevelopmentPremise / StagingPremise / StagingAwsBillowS / ProductionAwsBillowS / StagingAwsNics / ProductionAwsNics 六套子 class 全刪。
• 差異值 env 化：WEBSITE_URL→刪（死項）、CORS_ALLOWED_ORIGINS→env 逗號分隔（預設 *）、DB_PORT→env（預設 5432）、LOGGING_LOCATION→env LOG_DIR（預設 ./log）、SQLALCHEMY_TRACK_MODIFICATIONS→死項刪、JWT 效期→第 3 刀進 DB。
• config_util.py ENV→class 對照表退役；ENV 變數降級為純顯示標籤（log 印一行，不驅動行為），不破壞現有部署腳本。檔頭死值 AWD_DEFAULT_URL、BaseConfig.DB_NAME="audit_manager" 一併清。
• 遷移配套：產「六 class 差異→env 對照表」，三環境 .env 翻譯是機械操作；STG / POC 實際更新等部署放行（環境鐵律）。

第 2 刀：Secret 拆 JSON 包裝＋啟動期集中驗證

• 新增 config/config_loader.py：新格式平鋪變數（DB_USER / DB_PASSWORD / REDIS_USER / REDIS_PASSWORD / JWT_SECRET_KEY），向後相容舊格式（偵測 DB_SECRET 存在照舊 json.loads，現有 .env 零改動）。
• 開機必填檢查，缺項一次列全（「缺少：DB_HOST, JWT_SECRET_KEY（或 JWT_SECRET）」），取代 import 期 json.loads 直接 traceback；json.loads 移進 loader，由統一入口（D9 / .1c）最早階段呼叫——loader 與統一入口同檔作業。
• 附帶效益：新格式命名與 jedi-* 期待的 DB_USERNAME / DB_PASSWORD 命名分歧一併對齊收斂（盤查發現 jedi 讀的變數名與主專案 .env 是兩套）。

第 3 刀：營運參數遷移 DB system_config（內建預設＋DB 覆寫）

• 第一批（刻意保守）：LOGIN_MAX_LOCK_COUNT / LOGIN_USER_LOCK_TIME、CHANGE_PASSWORD_THRESHOLD_DAYS、LOGIN_INACTIVITY_THRESHOLD_DAYS、JWT_ACCESS/REFRESH_TOKEN_EXPIRES、MFA_REQUIRED。
• 機制：沿用既有 system_config root reader pattern（infra/system_config/system_config_root_reader.py 現成）；編譯內建預設值，DB 有值覆寫，讀不到照預設跑（無啟動依賴）。本期不做 UI（root 管理介面留後續）；migration 一支 seed（ON CONFLICT DO NOTHING），只套 DEV。
• 風險註記：JWT 效期改 DB 後的快取生效時機，與既有 system_config reader 快取行為一致，不另發明。

死項清理（2026-08-14 盤查定案）

「讀寫分離未生效」事實註記：SQLALCHEMY read replica 綁定無人消費，DB_READ_HOST 設了未生效——讀寫分離從未實際運作。落地版單機 PG 無 replica 需求；真要讀寫分離是獨立 feature 不夾帶。DB_READ_HOST 保留 env 定義，文件標註「目前未生效」。jedi-* 套件不讀 Flask app.config（已驗證），只吃 env＋DTO，死項判定無漏掃風險。

影響面：讀 app.config[...] 的呼叫點全不用動（key 名不變，值來源變）；要動：config.py 大改、config_util.py 退役對照表、新增 config_loader.py、統一入口接線、一支 migration、密碼政策 / JWT 讀取點改走 system_config reader（約 3–5 個 service 檔）。

%%{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 P1[".1 程式整理（開發環境即可驗證）"]
    A1["a DI 靜態清單<br/>🔴 編譯硬前置"]
    A2["b resource_path＋搬遷<br/>🔴 編譯硬前置"]
    A3["c 統一入口 RUN_MODE<br/>＋舊入口退役＋裁剪"]
    A4["d gunicorn 內嵌<br/>（與 c 同檔一起做）"]
    A5["e fail-fast＋死碼<br/>＋version bake 接點"]
    A6["f jedi-file-upload D10<br/>（獨立可平行）"]
    A7["g config 三層重整 D11<br/>（.1b 後，與 c 平行；<br/>loader 與 c 同檔）"]
  end
  subgraph P2[".2 Build 管線（等 build 機；script 可先寫）"]
    B1["a build 機環境建置"]
    B2["b wheel rebuild script<br/>⚠️ build 機到位最優先跑<br/>15 分驗 D2 炸點"]
    B3["c Nuitka build script"]
  end
  P3[".3 Production image<br/>Smoke 七項探針"]
  P4[".4 socketio 模式驗證<br/>（驗證棒非開發棒）"]
  A1 --> B3
  A2 --> B3
  A2 --> A7
  A3 --> A4
  B1 --> B2
  B2 --> B3
  B3 --> P3
  P3 --> P4

FR-063.1 程式整理 — 依賴：無（全部可在開發環境完成驗證，不需 build 機）

收口 gate：開發模式行為零變化——既有測試綠、PyCharm debug 不變、RUN_MODE 兩模式開發環境都起得來；grep 全 codebase 無殘留 __file__ 相對資料檔定位；blueprint 缺模組時啟動即炸而非 warning。

FR-063.2 Build 管線 — 依賴：build 機到位（D5，user 準備）；script 撰寫可與 .1 平行

驗收：build 機一鍵跑完 Step 1–4 產出可啟動的統一入口 dist；私房 wheel 快取命中時跳過重編；binary 產出後 api 模式起得來、打得到 API（import 期不炸、DI wire 全量）。

FR-063.3 Production image — 依賴：.2 binary 產出

production Dockerfile：非 root 固定 uid（D8）／volume 佈局（盤點#10）／fc-match 斷言（盤點#5）／entrypoint chdir＋chown（盤點#7/D8）／環境變數文件化（盤點#14 完整對照表）。

驗收：Smoke 七項探針全過（§5.6）；重啟後上傳檔不丟；容器內找不到任何 .py 業務原始碼；process 以非 root uid 執行。

FR-063.4 socketio 模式驗證與裁剪 — 依賴：.3

裁剪程式碼在 .1c 已寫掉；本棒主要是編譯後實測，是驗證棒不是開發棒：eventlet monkey-patch × Nuitka 相容性實測；卡關 → 啟動 D1 保底（換 gevent 等 async_mode，入口薄殼十幾行無祕密，業務模組仍全數受編譯保護）。

驗收：RUN_MODE=socketio 進程可建立連線並收發事件（socketio 通知端到端通）、不載 REST blueprint、scheduler 不雙跑；或保底方案落地且業務模組仍在編譯保護內。

1. Smoke 七項探針全過（§5.6：登入／列表／i18n／SSP docx／PDF 中文／上傳／socketio）。
2. 容器內無 .py 業務原始碼——客戶主機上找不到任何可讀業務原始碼，與 FR-062 license 執法構成雙保險。
3. 開發模式零回歸——既有測試綠、PyCharm debug 體驗與現行 main_app.py 完全等價、動態 DI 掃描與資源定位行為不變（加檔即生效）。
4. Config 向後相容（D11）——三環境用舊 .env 原封不動起服務，行為零差異；新格式 .env 行為相同。
5. 其他逐棒驗收見 §6 各子需求（.1 收口 gate／.2 binary 可啟動／.3 image 規格／.4 socketio 通）。