Synoria Base
系統分析與設計規格書
權限管理（IAM）
文件名稱
系統分析與設計規格書_SynoriaBase_權限管
版本
V 1.0
理.docx
設計
—
日期
2026-09-24
系統
Synoria Base（Go 1.26 + Rust + React 18）
狀態
定稿
文件更新記錄
版本
日期
修改人
修改事項
1.0
2026-09-24
—
初版：權限管理功能區 10 支功能頁與共用機制
文件審核記錄
審核角色
姓名
日期
意見
需求方
開發
測試
目錄
文件更新記錄 ...................................................................................................................................................................... 2
文件審核記錄 ...................................................................................................................................................................... 2
目錄 ........................................................................................................................................................................................ 2
1 文件範圍 ........................................................................................................................................................................ 6
2 業務需求摘要 ............................................................................................................................................................... 6
3 功能需求清單 ............................................................................................................................................................... 7
4 系統架構與共用設定 .................................................................................................................................................. 7
4.1 系統架構 ............................................................................................................................................................ 7
4.2 請求管線 ............................................................................................................................................................ 8
4.3 授權決策（PEP／PDP） .............................................................................................................................. 9
4.4 資料權限 ......................................................................................................................................................... 10
4.5 回應格式與分頁............................................................................................................................................ 12
4.6 綁定的樂觀鎖 ................................................................................................................................................ 12
4.7 訊息顯示與錯誤碼 ....................................................................................................................................... 13
4.8 模組擴充契約 ................................................................................................................................................ 14
5 畫面與流程 ................................................................................................................................................................. 15
5.1 登入（Login） ............................................................................................................................................. 15
5.1.1 頁面顯示邏輯 .................................................................................................................................... 15
5.1.2 驗證邏輯............................................................................................................................................. 16
5.1.3 登入處理邏輯 .................................................................................................................................... 16
5.1.4 登出 ..................................................................................................................................................... 17
5.1.5 介面與訊息 ........................................................................................................................................ 17
5.2 個人設定（Me） ......................................................................................................................................... 17
5.2.1 個人資料............................................................................................................................................. 18
5.2.2 偏好設定............................................................................................................................................. 18
5.2.3 變更密碼............................................................................................................................................. 19
5.2.4 強制變更密碼 .................................................................................................................................... 20
5.2.5 介面與訊息 ........................................................................................................................................ 20
5.3 使用者管理（Users） ................................................................................................................................ 20
5.3.1 頁面顯示邏輯 .................................................................................................................................... 21
5.3.2 查詢邏輯............................................................................................................................................. 22
5.3.3 新增使用者 ........................................................................................................................................ 22
5.3.4 編輯使用者 ........................................................................................................................................ 23
5.3.5 指派角色............................................................................................................................................. 24
5.3.6 重設密碼............................................................................................................................................. 25
5.3.7 批次啟用與停用 ............................................................................................................................... 25
5.3.8 刪除使用者 ........................................................................................................................................ 26
5.3.9 匯入與匯出 ........................................................................................................................................ 26
5.3.10 介面清單 .......................................................................................................................................... 27
5.3.11 訊息一覽 .......................................................................................................................................... 27
5.4 部門管理（Depts） .................................................................................................................................... 28
5.4.1 頁面顯示邏輯 .................................................................................................................................... 28
5.4.2 新增部門............................................................................................................................................. 28
5.4.3 編輯部門............................................................................................................................................. 29
5.4.4 刪除部門............................................................................................................................................. 29
5.4.5 介面與訊息 ........................................................................................................................................ 29
5.5 角色管理（Roles） ..................................................................................................................................... 30
5.5.1 頁面顯示邏輯 .................................................................................................................................... 30
5.5.2 新增與編輯 ........................................................................................................................................ 31
5.5.3 設定功能權限 .................................................................................................................................... 32
5.5.4 設定選單可見性 ............................................................................................................................... 33
5.5.5 設定資料範圍 .................................................................................................................................... 34
5.5.6 並行修改............................................................................................................................................. 34
5.5.7 刪除與批次變更狀態....................................................................................................................... 35
5.5.8 介面與訊息 ........................................................................................................................................ 35
5.6 權限管理（Permissions）........................................................................................................................ 36
5.6.1 頁面顯示邏輯 .................................................................................................................................... 36
5.6.2 新增與編輯 ........................................................................................................................................ 36
5.6.3 刪除 ..................................................................................................................................................... 37
5.6.4 權限目錄的來源 ............................................................................................................................... 37
5.6.5 介面與訊息 ........................................................................................................................................ 37
5.7 選單管理（Menus） .................................................................................................................................. 38
5.7.1 頁面顯示邏輯 .................................................................................................................................... 38
5.7.2 新增與編輯 ........................................................................................................................................ 39
5.7.3 刪除 ..................................................................................................................................................... 40
5.7.4 側欄選單的產生 ............................................................................................................................... 40
5.7.5 介面與訊息 ........................................................................................................................................ 41
5.8 線上使用者（Online Sessions） ........................................................................................................... 41
5.8.1 頁面顯示邏輯與查詢....................................................................................................................... 41
5.8.2 強制下線............................................................................................................................................. 42
5.8.3 介面與訊息 ........................................................................................................................................ 42
5.9 稽核紀錄（Audit Logs） .......................................................................................................................... 42
5.9.1 事件類型............................................................................................................................................. 43
5.9.2 頁面顯示邏輯與查詢....................................................................................................................... 43
5.9.3 變更明細............................................................................................................................................. 44
5.9.4 匯出與刪除 ........................................................................................................................................ 44
5.9.5 介面與訊息 ........................................................................................................................................ 45
5.10 登入日誌（Login Log） ......................................................................................................................... 45
6 資料存取對象 ............................................................................................................................................................ 46
7 業務規則與驗證 ........................................................................................................................................................ 47
8 例外處理 ..................................................................................................................................................................... 49
9 使用者與權限 ............................................................................................................................................................ 49
9.1 典型角色 ......................................................................................................................................................... 49
9.2 權限鍵目錄 .................................................................................................................................................... 49
10 非功能需求 .............................................................................................................................................................. 51
1
文件範圍
本文件描述 Synoria Base 後台「權限管理」功能區的系統分析與設計，供開發、測試與驗收使用。內
容以畫面為單位展開：每個功能頁先呈現畫面，再依序說明頁面顯示邏輯、查詢邏輯、驗證邏輯與資
料寫入邏輯，並標明所涉及的 API、權限鍵、資料表與對使用者顯示的訊息。
項目
內容
涵蓋
權限管理功能區的 10 支功能頁：登入、個人設定、使用者、部門、角色、權限、選單、線上
使用者、稽核紀錄、登入日誌
涵蓋
上述頁面共用的機制：請求管線、授權決策（PEP／PDP）、資料權限、回應格式、樂觀鎖、
訊息與錯誤碼、模組擴充契約
不涵蓋
系統維運功能區（參數設置、字典、行政區、檔案管理、通知公告、定時任務、背景任務、
服務監控、前端錯誤、登入 IP 名單），另行撰寫
不涵蓋
外部身分整合（LDAP／AD／SAML／OIDC／MFA）與多租戶
不涵蓋
部署與基礎設施（高可用、WAF、監控告警）
文件中的畫面均為示意圖，依實際頁面版型與欄位重製，資料皆為虛構，用於標示欄位位置與狀態。
2
業務需求摘要
Synoria Base 是一套可重複使用的後台底座：任何業務系統（CRM、ERP 等）都能以它為基礎，直接
取得身分驗證、授權、資料權限與稽核能力，把開發心力放在業務功能上。權限管理功能區是底座的
核心，目標是讓「誰能做什麼、能看到哪些資料、做過什麼」都有明確且可驗證的答案。
需求
說明
對應功能
身分驗證
帳密登入、驗證碼、登入失敗鎖定、可撤銷的 session、
登入、個人設定
強制變更密碼
帳號管理
建立與維護帳號、批次匯入匯出、重設密碼、指派角色與
使用者
部門
組織與資料權限
維護部門樹；以角色設定資料可見範圍（全部／自訂／本
部門、角色
部門／本部門及以下／僅本人）
功能權限
以權限鍵定義每一個 API 動作，角色綁定權限鍵後，成員
角色、權限
才能執行該動作
導覽治理
維護選單樹與頁面路由；選單可見性與功能權限分開設定
選單、角色
會話控管
檢視目前在線的連線，必要時強制下線
線上使用者
稽核
登入、授權拒絕與管理異動皆留紀錄，可依 request_id
稽核紀錄、登入日誌
追查整串請求並檢視欄位變更
整個功能區遵循四項設計原則：
• 後端是唯一的安全邊界。前端依權限隱藏按鈕只是為了使用體驗，每一支 API 仍由後端重新判定。
• 預設拒絕（fail-closed）。未登記的路由、決策服務故障或逾時、授權資料不一致，一律拒絕。
• 功能權限與資料權限分開。權限鍵決定「能不能做」，資料範圍決定「能看到哪些資料列」。
• 可稽核。拒絕與異動都留下紀錄，並能區分「策略拒絕」與「系統故障造成的拒絕」。
3
功能需求清單
權限管理功能區的功能頁一覽。詳細規格見第 5 章對應小節。
編號
功能頁
路由
說明
章節
IAM-01
登入
/login
帳密登入，含驗證碼、失敗鎖定與 IP 限
5.1
流
IAM-02
個人設定
IAM-03
使用者
/me/profile
/me/preferences
/system/users
個人資料、偏好設定與變更密碼
5.2
帳號維護、匯入匯出、重設密碼、指派
5.3
角色
IAM-04
IAM-05
部門
/system/depts
維護部門樹
5.4
角色
/system/roles
維護角色，設定功能權限、選單可見性
5.5
與資料範圍
IAM-06
權限
/system/permissions
維護權限目錄
5.6
IAM-07
選單
/system/menus
維護選單樹、路由與所需權限
5.7
IAM-08
線上使用者
檢視在線連線並強制下線
5.8
IAM-09
稽核紀錄
/system/onlinesessions
/system/audit
查詢、匯出稽核紀錄與檢視欄位變更
5.9
IAM-10
登入日誌
/system/login-log
檢視登入、登出與變更密碼事件
5.10
4
系統架構與共用設定
4.1
系統架構
圖 4.1-1
系統架構與元件職責
元件
技術
職責
前端 SPA
React 18、Vite、Refine、shadcn/ui、
畫面、動態選單、表單驗證、UX 權限守門
TanStack Table、react-hook-form +
zod、i18next
API（PEP）
Go 1.26、Gin、GORM
HTTP 契約、身分驗證、授權執行、資料存
取、稽核
Policy Core
Rust、tonic gRPC
無狀態的授權決策，只回答允許或拒絕與原因
資料庫
PostgreSQL／MySQL／SQL Server
同一套 schema，以各方言的 migration 維護
KV Store
記憶體或 Redis
登入限流、失敗次數、驗證碼、防重送
（PDP）
決策（PDP）與執行（PEP）分成兩個服務。PDP 只做決策，不連資料庫，也不自行 fail-closed；逾
時、無法連線等錯誤由 Go 端轉成型別化錯誤，再統一轉為拒絕。這樣的切分讓決策邏輯可以獨立測
試與替換，也確保系統故障永遠不會被誤判為允許。
圖 4.1-2
後台外殼：側欄選單、頁籤列與內容區
登入後的頁面共用同一個外殼。側欄選單由後端依使用者的角色產生（見 5.7.4），頂部提供選單搜尋、
通知與個人選單（個人資料、變更密碼、設定、登出），頁籤列保留已開啟的頁面。
4.2
請求管線
受保護的 API 依序通過下列中介層，任一層拒絕即回傳統一格式的錯誤，不會進入功能程式：
順序
中介層
職責
拒絕時
1
RequestID
沿用或產生 X-Request-Id，寫入回應與稽核，用於
—
串起整次請求
2
Authn
驗證 Bearer token 對應的 session 未撤銷、未過
401 AUTH-003（session
期；每次請求都自資料庫重新載入使用者狀態、角
無效）
色、權限與自訂部門
401 AUTH-002（帳號非
啟用）
3
4
MustChangePassw
帳號被標記須變更密碼時，只放行變更密碼、取得
ord
身分與登出三支 API
RateLimit
寫入類請求（POST／PUT／PATCH／DELETE）依
403 AUTHZ-003
429
使用者與路由限流，可由系統參數開關
5
AntiResubmit
3 秒內內容相同的請求視為重複送出，可由系統參
409 DATA-003
數開關
6
Authz（PEP）
依路由的權限政策向 PDP 取得決策，並計算本次的
403／500／503，見
資料範圍
4.3
由於每次請求都重新載入使用者資料，角色、權限或帳號狀態一經變更，下一次請求就會生效，不需
要另外設計令牌版本或快取失效機制。強制變更密碼刻意回傳 403 而非 401，讓前端引導使用者變更
密碼，而不是把人登出。
回應標頭：登入、建立使用者、匯入使用者、重設密碼、變更密碼等回應可能含憑證的路由，一律加
上 Cache-Control: no-store，避免瀏覽器或代理伺服器快取。
4.3
授權決策（PEP／PDP）
每一條路由在啟動時登記三種政策之一：公開、僅需登入、需權限鍵。啟動時系統會檢查所有路由都
已分類，且每個權限鍵都存在於 sys_permission；任一不符即拒絕啟動，讓「忘了掛權限」在上線前
就被擋下。
圖 4.3-1
授權決策流程
decision_source
情境
HTTP
原因碼
PolicyEvaluated
策略判定拒絕
403
AUTHZ-001
FailClosedUnavailable
PDP 無法連線
503
PDP-002
FailClosedTimeout
PDP 逾時（預設 5 秒）
503
PDP-001
FailClosedInternalError
PDP 內部錯誤
500
