跳轉到

工程開工放行與後續補件指引

發布日期：2026-04-21；v1.3.2 補充：2026-04-28（採 工程主導規格補齊模式，避免因未 full frozen 阻斷工程進度）
性質：規格端對 SL-Portal／LIC 相關工程 之 分段開工放行（conditional go）；不宣告 LIC internal 主冊整體最終凍結（full frozen），與 docs/規格端待凍結清單_20260424.md §七（v1.5；若該檔不存在則併讀 規格端待凍結清單_20260421.md）、TRK/03_Solution/2B/LIC/contracts-index.md P0／rolling 口徑一致。待凍結清單若主檔未及升版，併讀 規格端待凍結清單_20260423_增量.md。

2026-04-27 治理裁定：LIC 不以「全模組 full frozen」作為工程開工前提；工程端可依現有交付包與 rolling OpenAPI 先完成一版可驗證實作，並交付 規格回寫包（OpenAPI 匯出、SHA-256、差異摘要、驗收 ID 對照、待裁決清單），由需求倉採納／修正／拒絕後更新 SSOT。

0. 追溯與輸入（工程已交）

項目 連結／路徑
GitHub Issue Issue #19 — 工程端請求規格端凍結
工程回覆合併 PR PR #18 → 99_Archives/20260514_Inbox_spec-freeze-tracking/規格凍結追蹤_工程端回覆表_20260421.md
待凍結盤點（正式 v1.5） docs/規格端待凍結清單_20260424.md（併讀 規格端待凍結清單_20260421.md 若需同日檔名追溯）
LIC internal 主冊（rolling） LIC/02_Analysis/openapi_lic_internal.yaml（info.version 以檔內為準；v1.2 基線：0.3.9-draft，見 §六）
#2/#3 SSOT 合併 PR PR #21（Refs #19）
LIC-NAV／ML LIC/02_Analysis/openapi_lic_ai_navigate_magiclink.yaml v1.2.2
Wave4 CR（Final） LIC/02_Analysis/20260417_CR_LIC_Wave4_AI導覽_MagicLink_規格凍結.md
A2 部署放行 CR LIC/02_Analysis/20260425_CR_LIC110_子集凍結與工程部署放行_A2.md
A3 部署放行 CR LIC/02_Analysis/20260425_CR_LIC100_DashboardStats_凍結與工程部署放行_A3.md
工程主導規格補齊模式 本檔 §3.1；回寫規範見 internal_docs/工程變更回寫與需求Repo同步規範.md §4、§9
2026-04-28 工程第二輪回填（已合併） Issue #23 第二輪回填、工程端合併回填、Issue #19 全面回覆總結：SL-Portal PR #11 已合併（merge 8c0756d6f9238c2d6cd76e02e65800c48e934d37），主線驗證 commit cb0f970fc2e8ae891ec525f570ef9fdd7037c565，CI run 25036638298（validate／deploy-staging／e2e PASS）。需求倉維持 無新增 hard blocker 且不宣告全冊 frozen。

一、放行範圍 — 可優先／持續開工

以下範圍在現行需求倉契約與已合併工程回覆下，規格端准予工程繼續實作（含修 bug、測試、與契約已列路徑對齊之重構），並應以 OpenAPI 為 codegen／契約測試 依據：

區域 依據 工程注意
LIC P0 收口子集 GET /authz/menu、GET /companies（company context）— 見 contracts-index 與主冊註記 僅在此子集內變更時，仍須 PR 回寫需求倉 yaml／fixtures 與 Errors 同捆。
LIC-NAV POST /navigate/resolve、Magic Link POST /auth/magic-link/redeem OpenAPI v1.2.2 與 Wave4 CR Final A1／#4 已裁決：本階段 不在 APIM 強制 validate-jwt／required scope；維持匿名與已登入雙模式，由 BFF session／後端 authz 授權。lic.navigate.resolve、lic.auth.magiclink.redeem 僅作未來 External API reserved scope；若外部化再開 CR。
LIC110 /110/groups* 子集 A2 CR、OpenAPI 0.3.11-draft、Errors §2.4、R10 fixtures 解除本階段部署阻斷：可做嚴格契約測試與部署放行；但不得宣稱 LIC110 整包 full frozen。
LIC100 GET /100/dashboard/stats A3 CR、OpenAPI、Errors §2.3、R9 fixtures 解除本階段部署阻斷：可做嚴格契約測試與部署放行；但不得宣稱 LIC internal 主冊 full frozen。
LIC120／130 等主冊內 已定義且非 #1～#3 阻斷項 之路徑 主冊現況＋工程回覆表 若契約與實作不一致，走 §三 差異流程。
LIC310 主冊內 已定義 之路徑與 schema 主冊＋ External Draft SSOT #5 casing、#13 鍵名、#14 risk_level 仍待規格 CR／裁決；工程可先做不依賴該裁決之分支，或依回覆表自報 TODO／feature flag。

二、暫緩／高返工風險 — 開工但須標示 rolling／待契約

以下項目 主冊契約仍 rolling 或未定義，工程可在既有實作線上續修，但 不得宣稱「已與凍結契約完全一致」；前端 codegen 嚴格校驗建議待 §四 補件後再當 gate：

追蹤 # 說明 工程建議作法
#1／A2 LIC110 /110/groups* 子集 A2 CR 已解除本階段部署阻斷；工程可依 OpenAPI 0.3.11-draft、Errors §2.4、R10 fixtures 做嚴格契約測試。限制：不宣稱 LIC110 整包 full frozen。
#2 POST /110/groups/bulk-assign — 主冊 v0.3.9 已補 path／typed body（company_id＋group_id＋user_logins），段落仍 rolling 可依主冊續作並 Refs #19；若要提升為 current-phase freeze，可併 A2 或另開 CR。
#3／A3 GET /100/dashboard/stats — 主冊 v0.3.9 已補 response schema；company_id（query）必填 已與工程對帳 A3 CR 已解除本階段部署阻斷；工程可依 OpenAPI、Errors §2.3、R9 fixtures 做嚴格契約測試。限制：不宣稱 LIC internal 主冊 full frozen。
#6～#7、#17～#19 IAM 與跨模組 BIL 等 依各交付包 SSOT；需 新 CR 者勿自行定義為唯一真相。

三、工程實作守則（與本放行一併遵守）

  1. 契約來源：需求倉 LIC/02_Analysis/openapi_*.yaml 與 Errors SSOT；工程匯出物回寫依 工程變更回寫與需求Repo同步規範。
  2. 差異／breaking：於 MR 描述標 api_impact（none／additive／breaking）與 change_level（L1／L2／L3）；breaking 須併 CR 或 Issue 連結。
  3. 與本指引不一致時：以 較嚴格者為準（不以口頭覆寫已發布 docs/）。
  4. 多 Repo：Portal／BFF 另依 多Repo_OpenAPI實作契約回寫與Web銜接_治理規範 與 portal-openapi-fe-be-sync 流程。

3.1 工程主導規格補齊模式（Implementation-led Spec Closure）

適用情境：規格尚未 full frozen，但工程若等待全冊凍結會造成進度停滯；LIC 目前依本模式推進。

規則 說明
工程可先做 工程可依交付包、雛型、rolling OpenAPI 與已凍結子集先完成一版可驗證實作；不得把 rolling 項宣稱為 full frozen。
工程可補規格 工程 Repo 內可先補 OpenAPI、DTO／schema、錯誤碼與 fixtures，作為 implementation proposal（實作提案）。
需求倉仍是 SSOT 工程提案收斂後，需求方依回寫包採納／修正／拒絕，並更新 LIC/02_Analysis/、contracts-index、交付包摘要與驗收對照。
breaking 必走 CR 若有欄位刪除、語意變更、錯誤碼策略改變或客戶可見行為改變，須走 CR，不得僅以工程 PR 取代。

工程完成一版後，請提供下列 規格回寫包：

## LIC 規格回寫包

- **工程 Repo／PR／Commit／Tag**：
- **對應需求倉基線**：`<path 或 main@SHA>`
- **OpenAPI 匯出檔或連結**：
- **SHA-256（小寫）**：
- **api_impact**：none／additive／breaking
- **change_level**：L1／L2／L3
- **差異摘要**：與 `LIC/02_Analysis/openapi_lic_internal.yaml` 或對應 SSOT 的差異
- **驗收 ID 對照**：受影響 AC／GWT／測試 ID
- **fixtures／seed 狀態**：已補／待補／不適用
- **待 PM／SA 裁決**：欄位命名、enum、權限、錯誤碼或範圍排除

需求方收到後的處理原則：

類型 處理方式
L1 交付包或 README 註記即可，不必重產整包。
L2 更新 02_Analysis OpenAPI／Errors／fixtures，必要時補 03_附錄/API_規範.md 與 05_驗收對照。
L3 先做 CR 影響分析，再決定採納、修正或退回工程調整。

四、後續規格端補件 — 關閉 #19 checklist 與降低返工

以下由 PM／SA／治理 主導；完成後更新 OpenAPI／CR／contracts-index 並於 Issue #19 勾選或留言 PR 連結。

PR 關聯慣例（強制）：凡 補齊／凍結 與本放行對應之 #1、#2、#3（LIC110 群組 schema、bulk-assign、LIC100 Dashboard stat）之 需求倉 PR，描述須含 Refs #19（必要時併寫 Refs #20），合併後於 Issue #19 留言 PR 連結 + merge commit SHA，以便工程對帳與關閉待校驗項。

優先序 追蹤項 應補產物（SSOT） 建議下游 Skill／動作
P0 #1 openapi_lic_internal.yaml（或核准之分冊）— LIC110 完整 path／schema／operationId spec-close-loop-sa-sd → spec-and-ssot-writer
P0 #2 同上 — bulk-assign 或 CR 排除本輪 同上
P0 #3 同上 — LIC100 stat endpoints schema 同上
P1 #4 已完成本階段裁決：NAV OpenAPI v1.2.2 與 API 規範 §1.3 已標示不強制 APIM validate-jwt／required scope；scope 保留未來 External API 後續若要啟用 APIM 強制 OAuth2 scope，另開 CR
P1 #5 LIC310 status wire format 裁決與主冊／External 一致 CR 小條＋ yaml
P1 #6、#7 IAM120 CR（欄位收斂、Email 流程） prd-writer／spec-close-loop
P1 #15 contracts-index.md 逐列 frozen／rolling／excluded_from_freeze`＋版次；不假凍結全冊 對齊 LIC_契約收口_裁決紀錄
P2 #8～#14、#16～#19 依 docs/規格端待凍結清單_20260424.md §六 錨點逐項收斂 cr-impact-analyst（面大時）

工程端可併行：收到上述 PR 合併通知後，用 engineering-change-sync 輸入做需求倉對帳；測試與型別更新跟 PR #18 同一節奏即可。

五、建議在 Issue #19 的留言範本（規格端貼上即生效敘述）

規格端已發布 **分段開工放行** 與 **工程主導規格補齊模式**：`docs/工程開工放行與後續補件指引_20260421.md`。  
請工程依 **§一** 續作；**§二** 項請標 rolling／待契約，勿當凍結驗收。  
工程完成一版後，請依 **§3.1** 提供「規格回寫包」（OpenAPI 匯出、SHA-256、差異摘要、驗收 ID 對照、待裁決清單）。  
後續補件追蹤：**§四**；規格端合併 **#1～#3** 相關 PR 時 **描述必含 `Refs #19`**；合併後請於 Issue #19 更新 checklist 或留言 SHA。

六、工程對帳基線與驗證節流（2026-04-23）

目的：讓工程端（含自動化／AI）在 SSOT 已補 後能 持續開發，避免因反覆「全 OpenAPI operations 校驗報告」造成 Issue #19 無限回合；缺口補足仍依 §四 分批合併。

6.1 當前對帳基線（需求倉 main）

項目 值
LIC internal 主冊 LIC/02_Analysis/openapi_lic_internal.yaml
info.version 0.3.9-draft（以檔內為準）
合併追溯 PR #21（Refs #19）；merge commit 請以 GitHub 顯示為準（工程端已對帳 577807d）。
本版已收斂之 §四 關聯項 #2 bulk-assign body 欄位與 company_id；#3 stats 之 company_id query 必填；user_logins 欄名維持（見主冊 description 版本說明）。

6.2 驗證節流規則（工程端建議遵守）

  1. 在需求倉 openapi_lic_internal.yaml 的 info.version 未遞增前：不要求、不產出「跨 全部 internal／IAM／PCM／NAV 規格檔之全 operations 反覆 spec-vs-impl 報告」。改以 既有 CI／契約測試、或 針對本次 MR 變更 path／schema 的 diff 驗收 為主。
  2. info.version 遞增且已合併至 main：於 Issue #19 留言一次 Refs #19 + PR 連結 + merge SHA + 主檔路徑，再進行該版所需之 對帳／嚴格校驗。
  3. rolling 與凍結：v0.3.9 仍 不代表 LIC internal full frozen；#1 與其餘 §二 項仍可能變更，工程續作時保留 [§二 rolling] 等註記直至 §四 明確收口。

6.3 與 規格端待凍結清單 對齊

  • 2026-04-28 回寫口徑：工程端第二輪回填包已完成合併對帳（SL-Portal PR #11：merge 8c0756d6f9238c2d6cd76e02e65800c48e934d37；main 驗證 cb0f970fc2e8ae891ec525f570ef9fdd7037c565；CI run 25036638298 PASS），持續確認 A2／A3 current-phase freeze 與 IAM120 #33 收斂可作為工程續作依據；剩餘 BIL bil_order_id、PCM dispute_meeting_ref、PCM sub-program codes、LIC APIM scope、contracts-index 後續遞版列後續裁決，不作為目前工程 hard blocker。
  • 正式版（v1.5）：規格端待凍結清單_20260424.md（高優先 #2/#3 對齊主冊 0.3.9-draft／PR #21、#1 仍列阻斷凍結驗收）。
  • 若需同日檔名 20260421：於取得寫入權限後可將 v1.5 敘事合併回該檔；在此之前以 20260424 為準。併讀 規格端待凍結清單_20260423_增量.md 理解差異。

開發包索引（請與本節併讀）：LIC 開發準備 README、API_規範_跨模組索引、LIC_UI與API契約_工程接續開發指引。

版本紀錄

版本 日期 修改者 說明
v1.3.3 2026-05-14 AI 將 §0 工程回覆表路徑改指向 99_Archives/20260514_Inbox_spec-freeze-tracking/，避免 _inbox 與正式放行文件雙源
v1.3.2 2026-04-28 AI 補登 SL-Portal PR #11 已合併（merge SHA＋main CI 證據），將 §0／§6.3 從 pending merge 更新為已完成對帳
v1.3.1 2026-04-28 AI 補登工程端第二輪回填包與 Issue #19 4/28 全面回覆：目前無新增 hard blocker，PR #11 尚 pending merge，維持工程主導規格補齊模式
v1.3.0 2026-04-27 AI 新增 工程主導規格補齊模式：工程可先完成一版並提交規格回寫包，需求倉再採納／修正／拒絕並更新 SSOT
v1.2.3 2026-04-25 SystemLead A2／A3 已開 CR：LIC110 子集與 Dashboard stats current-phase freeze，解除本階段工程部署阻斷
v1.2.2 2026-04-25 SystemLead A1／#4 LIC-NAV APIM／OAuth2 scope 裁決：本階段不強制 APIM validate-jwt／required scope；OpenAPI v1.2.2
v1.2.1 2026-04-24 SystemLead 待凍結清單 v1.5 改指向 規格端待凍結清單_20260424.md；§0／§四 P2／§6.3 連結同步
v1.2 2026-04-23 SystemLead 新增 §六 對帳基線 v0.3.9／PR #21、驗證節流；§二 #2/#3 改為「已入主冊仍 rolling」
v1.1 2026-04-21 SystemLead §四 增 #1～#3 PR 強制 Refs #19；§五 範本同步
v1.0 2026-04-21 SystemLead 初版：分段放行、§二 風險、§四 補件與 Skill 指引