規格端待凍結清單 (Spec Freeze Action Items) — 正式發布版
發布日期: 2026-04-21
產出方: 工程端 (ENG) 盤點；本檔由需求倉補登 SSOT 錨點（單一真相來源連結） 與 LIC 契約索引口徑對齊，供 PM／SA／治理直接引用。
前版軌跡:_inbox/規格端待凍結清單_20260419.md（初版）、99_Archives/20260514_Inbox_spec-freeze-tracking/規格端待凍結清單_20260421.md（工程原文入口封存，正文以本docs/檔為準）。
目的: 以下為工程端盤點後，仍尚未凍結或存在歧義的規格項目。需要規格端（PM／SA／治理倉）接手處理並凍結，工程端才能進行後續開發。工程端結構化回覆（歷史封存）：
99_Archives/20260514_Inbox_spec-freeze-tracking/規格凍結追蹤_工程端回覆表_20260421.md
分段開工放行（規格端）：docs/工程開工放行與後續補件指引_20260421.md（對齊 GitHub Issue #19）
更新摘要
- ✅ LIC-NAV（AI 導覽）／Magic Link API：已完成合約對齊（OpenAPI v1.2.1），原 #4
nav_resolve_base_url工程端已自行實作（見 §六 表列 #13）。 - ✅ LIC310 Draft：新增
NavResolveBaseUrl欄位支持（待契約主冊欄位名 裁決確認，見 §六 表列 #13）。 - ⬇️ 原 Inbox 版之 LIC-NAV
nav_resolve_base_url議題降為 🟢 Low（工程端已決議實作鍵名）。 - 其餘項目狀態不變。
一、LIC 模組（授權管理）
🔴 高優先 (High Priority — 阻斷開發)
PR 關聯：規格端針對 #1～#3 開立之 OpenAPI／CR 需求倉 PR，描述請含
Refs #19（凍結追蹤 Issue #19），合併後於該 Issue 留言 PR + SHA。詳見工程開工放行與後續補件指引_20260421.md§四。
| # | 交付包 | 缺件項目 | 現狀說明 | 規格端需要的動作 | 影響範圍 |
|---|---|---|---|---|---|
| 1 | LIC110 | 群組 CRUD + Membership + 授權指派 OpenAPI 凍結分冊 | API 路徑/Schema 仍 rolling，無凍結版 operationId | 產出凍結版 OpenAPI 分冊，定義完整 request/response schema | 群組管理前端合約校驗 |
| 2 | LIC110 | bulk-assign 批次指派 API |
完全未定義 path 與 body schema | 定義批次指派 API 並凍結（或正式排除本輪） | 批次授權功能 |
| 3 | LIC100 | Dashboard 4 張統計卡片 stat API 端點 | 全部 pending，無任何 endpoint 定義 | 定義 stat card API endpoint + response schema 並凍結 | Dashboard 統計區塊 |
🟡 中優先 (Medium Priority — 影響功能完整度)
| # | 交付包 | 缺件項目 | 現狀說明 | 規格端需要的動作 | 影響範圍 |
|---|---|---|---|---|---|
| 4 | LIC-NAV | APIM/OAuth scopes 正式字串 | 建議 scope 為 rolling 狀態（OpenAPI x-oauth2-apim-proposed-scopes） |
與 IAM/資安凍結 audience + scope 字串 | 生產環境 APIM 授權 |
| 5 | LIC310 | Draft ↔ InReview status 字面值 casing | 工程端 enum draft/inreview；契約可能用 draft/in_review |
統一 casing 並於契約中宣告 | API 互通測試 |
| 6 | IAM120 | display_name vs nickname 收斂 |
CR 尚未裁決兩者合一或保留兩欄 | 出 CR 裁決 | 個人資料頁欄位映射 |
| 7 | IAM120 | Email 變更流程 | 完整驗證流程（驗證、通知、舊信箱確認）未定稿 | 定義完整流程並凍結 | 個人資料修改功能 |
🟢 低優先 (Low Priority — 不阻斷核心流程)
| # | 交付包 | 缺件項目 | 現狀說明 | 規格端需要的動作 | 影響範圍 |
|---|---|---|---|---|---|
| 8 | LIC310 | LIC320/330 Dictionary API | 尚未出 OpenAPI | 納入下一版或正式排除 | Catalog 進階查詢 |
| 9 | IAM120 | Anti-merge / 敏感資料遮罩策略 | 規則已敘述但未凍結 | 凍結遮罩規則 | 安全合規 |
| 10 | PCM120 | 匯出功能 | 明確標記為「next slice」不在本輪 | 確認排除或納入 | 報表匯出 |
| 11 | PCM110 | dispute_meeting_ref 是否必填 |
產品端待決 | 出裁決 | 核准表單驗證 |
| 12 | PCM130 | Sub-program codes 枚舉 | 待定 | 定義枚舉值 | 歷程篩選 |
| 13 | LIC310 | nav_resolve_base_url 正式 key 名稱確認 |
工程端已實作為 NavResolveBaseUrl，等待契約確認命名 |
確認正式 key name | Draft DTO 命名 |
| 14 | LIC310 | risk_level 欄位 |
雛型有此欄位但契約無對應 | 決定是否納入契約或移除 | Catalog Review UI |
二、跨模組缺件
| # | 項目 | 現狀 | 需要的動作 |
|---|---|---|---|
| 15 | LIC 全模組 OpenAPI 凍結 | contracts-index 仍有多項 draft/TODO |
將 contracts-index 每列改為 frozen 或 excluded_from_freeze |
| 16 | LIC DDL/Schema | 群組、AuditEvent、Catalog schema 未凍結 | 凍結邏輯實體與欄位語意 |
| 17 | IAM420 | 駁回 platform_reject_reason 是否補欄 |
待產品確認 |
| 18 | IAM220 | status enum SSOT、rejected 原因揭露政策 | 待定 |
| 19 | IAM300 | BIL 繳費介面 bil_order_id |
待 OpenAPI 凍結 BIL 介接 schema |
三、建議處理優先順序
- 立即處理 (#1, #2, #3): LIC110 全 API + LIC100 Dashboard — 阻斷前端合約校驗與新功能開發
- 本週處理 (#4-#7): APIM scope、LIC310 casing、IAM120 欄位收斂 — 影響上線品質
- 下輪處理 (#8-#19): 低優先或已明確排除的項目
四、工程端已自行完成的項目（本輪新增）
以下為本輪工程端自行完成的合約對齊修正，不需規格端動作：
| 項目 | 修正內容 | 對齊目標 |
|---|---|---|
| ✅ LIC-NAV Navigate/Resolve Request DTO | 新增 intent_text/intent_key/action_key/locale |
OpenAPI v1.2.1 |
| ✅ LIC-NAV Navigate/Resolve Response | 新增 authz_allowed(required)/message(required)/reason_code/email_dispatched/candidate.score |
OpenAPI v1.2.1 |
| ✅ LIC-ML MagicLink Redeem Response | 移除 token/memberId/displayName；新增 target_program_code/consumption |
OpenAPI v1.2.1（安全：response 不含 access token） |
| ✅ LIC-ML HTTP Status Code | 所有錯誤統一 403（原為 401） | OpenAPI v1.2.1 Wave 4 規定 |
| ✅ LIC Error Envelope | 改為 { code, message, request_id, trace_id } 格式 |
OpenAPI v1.2.1 ErrorResponse schema |
| ✅ X-Request-Id Header | 讀取並回傳 request_id | OpenAPI v1.2.1 required header |
| ✅ LIC310 ProgramDraft | 新增 NavResolveBaseUrl 欄位 |
LIC310-F01 規格要求 |
| ✅ MagicLink Session | 改為 HttpOnly Cookie（BFF pattern） | OpenAPI v1.2.1 安全規範 |
| ✅ Frontend 合約對齊 | 更新 TypeScript types + API hooks + pages | 與後端 DTO 一致 |
五、對整體產品的影響評估
| 風險等級 | 影響描述 |
|---|---|
| 🔴 高 | 群組管理 (LIC110) 是最大缺口 — 群組 CRUD、成員管理、授權批次指派雖已實作後端，但無凍結合約可供前端校驗。佔 LIC 模組 ~30% 功能面積。 |
| 🔴 高 | Dashboard 統計 (LIC100) — 4 張卡片均無 API 定義，首頁數據區塊空白。 |
| 🟡 中 | APIM scope 未凍結會阻斷生產環境部署前的 API 管理設定。 |
| 🟢 低 | 其餘項目不阻斷核心流程，可排入下一輪。 |
結論: 所有已凍結規格均已完整對齊實作（含本輪 OpenAPI v1.2.1 合約修正），無工程端遺漏。
六、SSOT 錨點補件
用途：將上表每一項對到「應改哪裡」之既有路徑；不取代 PM／SA 之裁決與 OpenAPI 正文撰寫。
| # | 建議主責 SSOT／交付物（相對 repo 根目錄） | 補充 |
|---|---|---|
| 1, 2 | LIC/02_Analysis/openapi_lic_internal.yaml（LIC110 區段）；LIC/99_Delivery/交付開發包_LIC110_群組與授權建檔目錄/；LIC/02_Analysis/20260320_Rules_LIC_授權異動稽核事件_AuditEvent.md |
與 AuditEvent 寫入語意一致；#2 若納入需新 operationId 與 Errors 對照 |
| 3 | LIC/99_Delivery/交付開發包_LIC100_程式授權中樞目錄/；LIC/02_Analysis/ 內 LIC100 分析稿；openapi_lic_internal.yaml（待增路徑） |
建議併入 internal 主冊或宣告 excluded 之獨立分冊策略 |
| 4 | LIC/02_Analysis/openapi_lic_ai_navigate_magiclink.yaml（v1.2.1；§1.3 x-oauth2-apim-proposed-scopes）；LIC/02_Analysis/20260324_API_LIC_AI導覽與深連結.md |
與 IAM／資安 audience 字串聯合凍結 |
| 5 | LIC/02_Analysis/openapi_lic_internal.yaml（LIC310 Program Draft schema 註解／enum）；LIC/02_Analysis/20260323_API_LIC_Program_Catalog_External_Draft.md |
主冊註解已示例 wire：draft、in_review（snake_case）；若工程 DTO 為 inreview 需 CR 選邊或 deprecated 別名 |
| 6, 7, 9 | IAM/99_Delivery/交付開發包_IAM120_會員主檔與登入綁定維護/（含 01_規格/、03_附錄/待決策事項清單_IAM120.md） |
#6/#7 建議開 IAM120 專屬 CR 收斂 |
| 8 | TRK/03_Solution/2B/LIC/contracts-index.md §1.2；LIC/02_Analysis/20260419_補登_Inbox規格端待凍結清單_LIC低優先與索引_R2.md |
R2 已敘述 320／330 唯讀納主冊、寫入排除 |
| 10 | PCM/99_Delivery/交付開發包_PCM120_平台自申請待審與裁定/README.md |
確認 next slice 是否本輪排除 |
| 11 | PCM/99_Delivery/交付開發包_PCM110_*（核准表單相關交付包）之 01_規格/ |
以產品裁決更新驗收條件 |
| 12 | PCM/99_Delivery/交付開發包_PCM130_審核歷程與歸檔查詢/01_規格/ |
枚舉納 SSOT 字典或 OpenAPI |
| 13 | LIC/99_Delivery/交付開發包_LIC310_ProgramCatalog草稿與審核目錄/03_附錄/工程師開工指引.md；openapi_lic_internal.yaml（待補 ProgramDraft 欄位） |
工程已用 NavResolveBaseUrl；需 主冊／External Draft 對齊命名 |
| 14 | LIC/99_Delivery/交付開發包_LIC310_* 雛型與欄位對照；20260323_API_LIC_Program_Catalog_External_Draft.md |
擇一：納契約 或 刪雛型欄位 |
| 15 | TRK/03_Solution/2B/LIC/contracts-index.md；LIC/02_Analysis/20260403_CR_LIC_全模組契約凍結_單一internal_OpenAPI策略.md；LIC/99_Delivery/LIC_契約收口_裁決紀錄.md |
詳 §七 |
| 16 | LIC/02_Analysis/20260320_Rules_LIC_授權異動稽核事件_AuditEvent.md；LIC/99_Delivery/交付開發包_LIC110_*/03_附錄/schema_參考.md |
contracts-index §1.2 已標 DDL 本輪 excluded |
| 17 | IAM/99_Delivery/交付開發包_IAM420_關閉公司帳號申請/ |
產品確認後更新 OpenAPI／欄位表 |
| 18 | IAM/99_Delivery/交付開發包_IAM220_我的加入申請/01_規格/雛型欄位與OpenAPI對照表_IAM220.md |
status enum 與 PCM 對齊單一 SSOT |
| 19 | IAM/99_Delivery/交付開發包_IAM300_*（若路徑不同請以 IAM SSOT Map 為準）；BIL 契約倉路徑（跨模組） |
依 多 Repo OpenAPI 治理 登錄 BIL 介接版次 |
LIC-NAV／ML v1.2.1 機器可讀契約（工程已對齊）：
LIC/02_Analysis/openapi_lic_ai_navigate_magiclink.yaml- 人讀敘述：
LIC/02_Analysis/20260324_API_LIC_AI導覽與深連結.md - CR：
LIC/02_Analysis/20260417_CR_LIC_Wave4_AI導覽_MagicLink_規格凍結.md
七、contracts-index 與 P0 裁決口徑
| 議題 | 說明 |
|---|---|
| #15 與「全列 frozen」 | 工程盤點期望 contracts-index 每列標示 frozen 或 excluded_from_freeze。需求倉現行上位裁決為：在 freeze window 完成前，不得以 frozen 宣告「LIC internal 主冊整體最終凍結」，且 P0 收口子集僅含 LIC100 之 GET /authz/menu、GET /companies（company context）；LIC110～310 等列為 rolling 或 excluded_from_freeze（見 TRK/03_Solution/2B/LIC/contracts-index.md 開頭註記與 §1.2）。 |
| 規格端實務動作 | 將 #15 落實為：逐列標示 frozen／rolling／excluded_from_freeze 之一並附 CR／版次；不得把「索引表上出現 frozen 字樣」等同「全模組契約已最終凍結」。若需擴張 P0 子集，必須走 LIC_契約收口_裁決紀錄 與新 CR。 |
| 與本清單 #1～#3 的關係 | #1～#3 為工程端 功能面 阻塞（缺 operationId／schema）；contracts-index 為 治理面 登錄。兩者並行：先補 OpenAPI 正文與 CR（相關 PR 請 Refs #19），再回寫索引列狀態。 |
本文件由工程端盤點起稿，2026-04-21 於 docs/ 補登錨點後發布；請規格端逐項確認後回覆處理結果。補登追溯：LIC/02_Analysis/20260421_補登_Inbox規格端待凍結清單_發布版與SSOT錨點.md。
v1.2：增連結至工程端結構化回覆表 99_Archives/20260514_Inbox_spec-freeze-tracking/規格凍結追蹤_工程端回覆表_20260421.md。
v1.3：增連結至分段開工放行 docs/工程開工放行與後續補件指引_20260421.md（Issue #19）。
v1.4：高優先 #1～#3 增 PR 須 Refs #19 與 Issue 留言慣例。
v1.5：將 2026-04-21 _inbox 原文與工程回覆表改連至 99_Archives/20260514_Inbox_spec-freeze-tracking/，避免 _inbox 與正式文件雙源。