跳至主要内容

ADR-022: auth-admin 降級為業務層參考實作

ADR 編號: 022 狀態: 已接受 (Accepted) 決策日期: 2026-07-22 決策者: Development Team 取代: ADR-020 被取代: 無

摘要​

撤銷 ADR-020 的 auth-admin optional feature：帳號／角色管理端點面整域降級為業務層參考實作（{controller|service|security}/authadmin/，@reference-surface 生命週期——消費端依自己的帳號管理模式 retarget，或整域 prune）。feature catalog 移除 auth-admin 條目；程式碼原樣搬遷、wire 契約不變。

背景 (Context)​

ADR-020 的前提被 adoption 後的 fleet 回饋推翻​

ADR-020 的收編判斷基於兩家下游的端點面重合（帳號 CRUD＋生命週期＋角色指派高度一致）。但 adoption 後的實作回饋顯示，重合的只是表層動詞；帳號的來源與可管理性才是分歧的主軸，且差異持續擴大：

  • 帳號來源異質：部分帳號經本地管理面建立，部分來自特殊管道（外部 provision、匯入、聯邦身分等），後者不宜、甚至不可經本地 CRUD 管理。
  • 「哪些帳號可管理、可管理到什麼程度」隨專案的身分治理模式而異——canonical service 的統一模型（所有帳號走同一組 CRUD＋生命週期操作）無法涵蓋，而這層分歧無法用 ADR-020 D-B 的 customizer hook（欄位級）或 D-C 的政策 SPI（租戶邊界級）表達：它是操作語意本身的分歧。

判準回歸紀律四​

21-feature-surface.md 紀律四：「feature 出能力與接點，資源的實作歸消費端」。帳號管理面被證實屬「資源實作」——每個消費端的形狀不同、無穩定的 canonical 核心可同步。繼續以 feature 出貨，sync 會對著各家已分歧的實作嘮叨；這正是把 MailSetting CRUD 放業務層的同一判準。

與 ADR-020 仍然成立的部分​

  • 權限貢獻機制不受影響：AuthorityContributor SPI 已上收框架 jar（io.leandev.appfuse.security），本域的權限宣告（account:*／role:*）隨參考實作走。
  • D-B 的 command＋customizer、D-C 的政策 SPI 作為參考實作內部的設計原樣保留——它們仍是好的起點形狀，只是不再是同步契約。
  • ADR-018 的 Account 空體紀律、@Version opt-in 不受影響（屬 auth feature）。

決策 (Decision)​

  1. 整域搬遷至業務層（layer-first 佈局）：
    • controller/authadmin/：AccountController、RoleController
    • service/authadmin/：AccountAdminService、RoleAdminService、RoleMembershipPolicy、AccountAdminPolicy、PrincipalTenantAccountAdminPolicy、AuthAdminAuthorityContributor
    • security/authadmin/：AuthAdminAuthority
    • wire 契約（/api/v1/accounts、/api/v1/roles）與行為零變化。
  2. feature catalog 移除 auth-admin；本域此後由業務殘餘推導機制涵蓋（scaffold stamp @reference-surface、可 prune、非 base variant 不出貨）。
  3. 下游已 adopt 者：其副本自本決策起即為下游自有碼（不再受 /feature sync 管理）——這與 fleet 現況一致：各家的帳號管理本就已依自身治理模式分歧。

後果 (Consequences)​

正面​

  • 消費端取得帳號管理面的完整所有權：端點形狀、操作語意（哪些帳號可管理）、持久化與治理模式全域自訂，不再有「canonical service 同步 vs 在地分歧」的拉扯。
  • feature catalog 不再承載一個「controller 列 seam、實質各家已 fork」的條目（紀律四的反模式）。

負面（誠實列出）​

  • 失去 canonical service 的同步管道：404 不洩漏存在性、租戶邊界政策、樂觀鎖往返等安全相關預設，日後的框架修正不再自動下行——由參考實作的 retarget 起點品質承擔。
  • 非 base variant（ownership）scaffold 不再帶帳號管理起點（業務殘餘不下行），需要者自行 retarget 本域或另行作者化。
  • ADR-020 預期的「終結 fleet 重造」目標放棄——fleet 回饋顯示該目標對此域不可達。

相關​

  • ADR-020（被本 ADR 取代）
  • 21-feature-surface.md 紀律四（feature 出能力與接點，資源實作歸消費端）
  • m-reference-code.md（@reference-surface 生命週期）、m-reference-prune.md（整域剝離）