GOV-007　BEAM PMO 裁定清單（待裁定項之裁定與執行）

項目	內容
文件編號	GOV-007
版本	1.2
日期	2026-10-01
裁定者	BEAM PMO
記錄者	WorkBuddy AI（開發團隊）
緣起	#A-113 後 BEAM PMO 指示「清掉幾項待我裁定的卡點」。本清單逐項列議題／選項／建議／BEAM PMO 裁定／依裁定之執行，備查
狀態	裁定已收；執行狀態見各節

⚠️ 本清單為「裁定之紀錄」，非規格。各項之規格變更仍依 GOV-003（先規格後程式）於對應文件為之。

---

裁定總表

#	議題	BEAM PMO 裁定	執行狀態
1	SSO 是否改 fail-closed	同意（有條件）：若會影響開發測試則先不改	✅ 已釐清：機制早已實作；依條件「先不改」（見 §1）
2	CorrelationIdFilter 註冊或退役	註冊	✅ 早已實作（CorrelationIdAutoConfiguration；見 §2）
3	日誌 total-size-cap	限制 5GB	✅ 已執行（19 檔＋產生器模板；見 §3）
4	報表下載 409 語意	另立 CC-PLT-3003	✅ 已執行（SDD-006 1.10／SCS-017 1.6；見 §4）
5	statement 帳單 PDF 產生器	必做（現行系統有，微服務不能少）	✅ 已執行（PDFBox 3.0.8；真機驗證通過；見 §5）

---

1. SSO 是否改 fail-closed

議題：cardcore.security.enabled 是否改為 fail-closed（預設要求認證）。

現況（2026-10-01 實測）：

層次	現值	來源
Java 預設	true（fail-closed）	SecurityProperties.enabled（common-spring）
本地 profile	${CARDCORE_SECURITY_ENABLED:false}（預設關閉）	application-local.yml（17/17 服務皆已宣告）
本地 env	true	ops/local/sso.env（sso.sh 產生，env.sh 載入）

★ 重要更正（誠實揭露）：SecurityProperties.enabled 之 fail-closed 預設早已於 2026-09-20（SCS-022 v1.7，§10 #12）由 BEAM PMO 核定並實作。
HANDOVER 之 C-34／W-3 註記「預設仍 false…是否改 fail-closed 待 BEAM PMO 定奪」係過期記載（該註記早於 v1.7 之變更）→ 應予更正。

選項：

選項	內容
(a) 維持現狀	Java 預設 true（正式環境 fail-closed）＋ 本地 application-local.yml 顯式 false
(b) 本地亦 fail-closed	移除本地之 :false（改依 Java 預設 true）→ 本地未設環境變數即要求認證

影響評估（回應 BEAM PMO 之關切「開發測試階段會不會無法繼續」）：

• 採 (b) 後，本地預設為要求認證。惟：
  • 走 ops/local/env.sh 時，sso.env 已載入 true → 現況即為開啟，服務可正常啟動（#A-36 已 17/17 實測）。
  • 未帶 token 之 curl 驗證（#A-111／#A-113／#A-114 之作法）需顯式覆寫 CARDCORE_SECURITY_ENABLED=false——此為既有慣例，非新增障礙。
• ⚠️ 但確有一處會「影響開發」：若開發者不經 env.sh（如 IDE 直接啟動）且未提供 m2m.env，服務將因「入站啟用＋出站憑證未設定」而啟動失敗（SCS-022 §7.6 之刻意 fail-closed）。

建議：採 (a) 維持現狀——理由：fail-closed 之實質目的（正式環境不靜默放行）已達成（Java 預設 true）；而本地之顯式停用係 SCS-022 §10 #12 之既定設計，強改為 (b) 只會讓「不經 env.sh 之開發」啟動失敗，屬「影響開發」。

BEAM PMO 裁定：同意（有條件）——「是，但若會影響開發測試則先不改」。

依裁定之執行：因 (b) 確會影響（不經 env.sh 之開發將啟動失敗）→ 先不改（維持 (a)）；並更正 HANDOVER 之過期註記（載明 fail-closed 已於 v1.7 實作）。

---

2. CorrelationIdFilter 註冊或退役

議題：CorrelationIdFilter（common-spring）從未被註冊為 bean（#A-59 之根因），致 MDC 恆空、TraceContext.currentTraceId() 每次現產亂數——回應看似帶合法追蹤碼，實則與日誌對不上（「靜默不做」型缺陷）。現由 TraceContext 改以 OTel traceId 為權威（#A-59）緩解，但該 filter 本身之去留未定。

選項：

選項	內容	影響
(a) 註冊	將 filter 註冊為 bean（@Component 或 FilterRegistrationBean），於無 OTel 情境提供 correlationId（如 X-Correlation-Id 入站沿用）	補齊「無 OTel 時之追蹤」；⚠️ 須避免與 OTel 之 trace_id 產生兩套值（#A-59 之顧慮）
(b) 退役	刪除 filter，追蹤一律以 OTel 為準	簡化；但無 OTel 情境（如未接 collector 之單元／本機）將無入站關聯碼

建議：採 (a) 註冊，但明確分工——correlationId 僅在無 OTel span 時作為降級值（TraceContext 之既有優先序：OTel traceId → MDC → 臨時值）；且沿用入站 X-Correlation-Id（若帶）以支援跨系統追蹤。

BEAM PMO 裁定：註冊。

依裁定之執行：✅ 早已實作（2026-09-21／22）——CorrelationIdAutoConfiguration（@ConditionalOnWebApplication(SERVLET)）以 FilterRegistrationBean 註冊 filter，顯式指定 ORDER（LOWEST_PRECEDENCE - 100）確保晚於 OTel 觀測範圍；已登錄於 AutoConfiguration.imports；測試 CorrelationIdFilterTest／TraceContextTest 齊備；啟動日誌可見 Filter 'correlationIdFilter' configured for use。
⚠️ 本輪僅更正：CorrelationIdFilter 之 javadoc 原仍寫「🔴 未被註冊」（過時且與實作矛盾）→ 已更正為「已註冊並生效（附歷史）」；SCS-020 §9.5 #3 之「待裁定／未擅自註冊」亦已更正。

---

3. 日誌 total-size-cap

議題：結構化日誌（ECS JSON）之輪轉中，max-file-size（預設 10MB）與 max-history（預設 7）皆已生效，惟 total-size-cap 預設 0B＝無上限 → 日誌總量不受總額約束（C-30 之真實殘留顧慮）。

現況（實測）：Spring Boot 4.1.1 提供 logging.logback.rollingpolicy.*；total-size-cap 預設 0B（無上限）。

選項：

選項	內容
(a) 不設	維持無上限（僅受單檔／份數約束）
(b) 設上限	logging.logback.rollingpolicy.total-size-cap: 5GB

建議：採 (b)——設 5GB，避免長期運行時日誌佔滿磁碟（尤以本機 SSD 為然）。

BEAM PMO 裁定：限制在 5GB SSD 空間。

依裁定之執行：✅ 已執行——19 個 application.yml 均設 logging.logback.rollingpolicy.total-size-cap: 5GB；產生器模板（gen_service_skeleton.py 之 T_APP_YML／T_APP_YML_CORE）同步；SCS-020 → 1.10（§9.5 #5，併更正原建議之錯誤屬性名 logging.file.total-size-cap → logging.logback.rollingpolicy.total-size-cap）。19 檔 YAML 解析驗證通過（0 錯誤）。

---

4. 報表下載 409 語意

議題：報表下載端點（#A-109 之代理端點）於「作業未完成／失敗」時回 409，但暫用 CC-PLT-3001（非法狀態轉換，SDD-006 §3.4）——語意不完全吻合（該碼係為 SDD-005 之狀態機轉換設計）。SDD-006 §3.4 現有 409 平台碼僅 CC-PLT-2002（狀態版本衝突）／CC-PLT-3001（非法狀態轉換）／CC-PLT-3002（終態不可轉換）。

選項：

選項	內容
(a) 沿用 CC-PLT-3001	不改碼表；語意以訊息補充
(b) 另立 CC-PLT-3003	新增「資源尚未就緒」語意之 409 平台碼

建議：採 (b)——「檔案尚未就緒（QUEUED／RUNNING／FAILED）」與「狀態機非法轉換」語意不同；混用會使錯誤處理與告警失準。

BEAM PMO 裁定：是（另立 CC-PLT-3003）。

依裁定之執行：✅ 已執行——SDD-006 §3.4 新增 CC-PLT-3003（409 資源尚未就緒）→ SDD-006 → 1.10；gen_error_codes.py --force 重生 ErrorCodes.java（錯誤碼 123 → 124）；SCS-017 → 1.6（§6.2 改用 CC-PLT-3003）；ReportJobService.download 與 ReportJobServiceTest 同步；:services:report-service:test BUILD SUCCESSFUL。

---

5. statement 帳單 PDF 產生器

議題：帳單 PDF（PDF_REF）之儲存媒體已定（S3 API／本地 Garage，SAD-006 §3.2，#A-106／#A-107），惟 PDF 產生器本身尚未實作（需額外函式庫，SCS-011 §10）→ 帳單尚無法產生 PDF。

現況：report-service 之物件儲存接線已完成（#A-107）；statement-service 之帳單 PDF 產生器未實作（SCS-011 §10 明載）。

選項（產生器之技術路徑）：

選項	內容	授權	備註
(a) Apache PDFBox	純 Java、Apache 2.0	✅ 寬鬆	低階、需自行排版
(b) OpenPDF	com.github.librepdf:openpdf，LGPL/MPL	✅ 可用	iText 分支、API 較高階
(c) iText 7	功能強	⚠️ AGPL／商業	銀行案授權風險
(d) HTML→PDF	以範本轉檔	視引擎	需額外引擎／字型

建議：採 (a) Apache PDFBox（或 (b) OpenPDF）——授權寬鬆、無 AGPL 風險；先出「帳單摘要 PDF」（客戶基本資料、帳期、應繳金額、繳費期限、明細條列），字型須內嵌中文（否則中文變方框）。依 version-compat-verification 先查證版本與 Spring Boot 4.1.1 之相容性再鎖版。

BEAM PMO 裁定：必做——「現有的系統有，微服務的不能少」。

依裁定之執行：✅ 已完成（#A-116）——規格先行：SCS-011 → 1.8（新增 §8.2 帳單 PDF 產生與物件儲存）→ 依賴查證（version-compat-verification；Maven Central 實查採 Apache PDFBox 3.0.8，Apache 2.0，避 iText AGPL）→ 加依賴（libs.versions.toml ＋ statement-service）→ 實作（StatementPdfPort＋PdfBoxStatementPdfAdapter；ObjectStoragePort＋S3StorageConfig＋S3ObjectStorageAdapter；Statement.withPdfRef；接線 StatementGenerationService）→ 真機驗證（產生 35,471 bytes PDF → 上傳真實 Garage → 取回逐位元組一致、含中文）。
併載：PDF 為衍生物——失敗不擋帳單（fail-soft 但不靜默，§8.2.2）。
未竟：電子帳單寄送通道仍為真阻塞（供應商未定）。

---

附註：後續

• 本清單之 #2／#3／#4 為小而明確之變更，可逐項執行（規格 → 程式 → 測試 → 真機 → 文件 → commit）。
• #5 工作量較大，建議另立交付單元（比照 #A-101／#A-107 模式：規格先行 → 依賴查證 → 實作 → 真機驗證）。
• #1 依裁定先不改，惟須更正 HANDOVER 之過期註記。

修訂記錄

版本	日期	說明
1.2	2026-10-01	#5 執行完成——statement 帳單 PDF 產生器：SCS-011 → 1.8（§8.2）；依賴實查採 Apache PDFBox 3.0.8（避 iText AGPL）；實作 StatementPdfPort／PdfBoxStatementPdfAdapter ＋ ObjectStoragePort／S3StorageConfig／S3ObjectStorageAdapter；真機驗證（產生 35,471 bytes → 上傳 Garage → 取回逐位元組一致、含中文）。5 項裁定全數執行完畢。
1.1	2026-10-01	#2／#3／#4 執行完成：②CorrelationIdFilter 早已實作（僅更正過時 javadoc）；③19 檔 application.yml 設 total-size-cap: 5GB（＋產生器模板；SCS-020 1.10）；④CC-PLT-3003 立碼（SDD-006 1.10／SCS-017 1.6；錯誤碼 124）。
1.0	2026-10-01	初版：BEAM PMO 5 項裁定之紀錄（含選項、建議、影響評估、執行狀態）；併更正 HANDOVER「fail-closed 待定奪」之過期記載