Guidant AI 功能 SPEC 手冊¶
給誰看：新到職的全端工程師，以及需要查「某個功能怎麼運作」的維護者。
怎麼用：從下面的功能群找到你要改的頁面，開該頁的 spec——13 節固定結構，含前後端檔案地圖、API、DB、頁面邏輯與已知坑。
結構：一個頁面 spec = 一條 FE route；頁內 dialog / tab 都寫在該頁 spec 內。
先讀這些（新人第一天）¶
- BE 開發環境：
docs/user-manual/developer-setup-guide.md（或docs/system-design/的 Setup Guide docx） - 系統全貌（技術）：
docs/交付文件/v1.8.0/GAI-SD-01 系統架構 - 系統全貌（業務）：GAI-SD-07 功能規格總覽（稽核生命週期 + UC）
- 然後回來這裡，按你被指派的功能開頁面 spec
兩種查法¶
- 知道功能領域（要改稽核流程 / 證據 / 合規框架…）→ 用下面的「功能群 → 頁面 索引」，或直接看左側選單（按領域分組，與 repo 目錄一致）。
- 只知道在產品畫面哪個選單（照著 UI 找）→ 用「產品選單 → spec 對照表」。
產品選單 → spec 對照表（照畫面找）¶
對齊系統實際的左側選單。同一份 spec 可能對應多個選單入口。
| 產品選單位置 | 對應頁面 spec |
|---|---|
| 專案任務 › 專案儀表板 | 專案儀表板 |
| 專案任務 › 我的任務 | 我的任務 |
| 專案任務 › 專案列表 | 專案列表頁 |
| 專案任務 › 稽核管理 | 我的稽核 |
| 專案任務 › 專案摘要報表 | 專案摘要報表 |
| 合規稽核 › 範本管理 | 範本管理 / 合規資源庫 |
| 合規稽核 › 合規框架管理 | 合規框架管理 |
| 合規稽核 › 稽核流程範本 | BPMN 稽核範本管理 |
| 合規稽核 › 檢測工具管理 | 檢測工具管理 |
| 溝通協作 › 公告檢視 | 公告檢視 |
| 溝通協作 › 公告管理 | 公告管理 |
| 溝通協作 › 問卷管理 | 問卷管理頁 |
| 溝通協作 › 回饋管理 / 回饋檢視 | 回饋管理 |
| 租戶組織 › 租戶管理 | 租戶管理 |
| 租戶組織 › 部門管理 | 部門管理 |
| 租戶組織 › 使用者管理 | 使用者管理 |
| 租戶組織 › 角色權限管理 | 角色權限管理 |
| 系統管理 › 選單管理 | 選單管理 |
| 系統管理 › 資訊系統盤點 | 資訊系統盤點 |
| 系統管理 › 設備管理 | 設備管理 |
| 系統管理 › 操作日誌 | 操作日誌 |
| 系統設定 › 通知頻道設定 | 通知頻道設定（Telegram / Discord） |
| 系統設定 › SMTP 設定 | SMTP 伺服器設定 |
| 系統設定 › LDAP 設定 | LDAP 設定 |
| 系統設定 › 儲存設定 | 儲存設定 |
| 系統設定 › 檔案 Agent 管理 | 檔案 Agent 管理 |
| 系統設定 › 雲端整合 | 雲端整合 |
| 系統設定 › 議題整合設定 | 議題整合設定 |
| AI 分析 › AI 儀表板 | AI 儀表板 |
| 授權管理 › License 授權管理 | License 授權管理 |
| 授權管理 › 我的授權狀態 | 我的授權狀態 |
| （登入前，非選單） | 登入、忘記 / 重設密碼 |
選單裡沒有獨立入口的流程子頁（專案規劃 / 建立 / 設定、稽核計畫填寫 / AR 判定 / POA&M、各匯入精靈、問卷設計器 / 填寫、證據分類覆核 / 報表、個人資料、背景服務）從父流程進入 — 查它們用左側「功能群 → 頁面 索引」。
全站行為（不屬於單一頁面）¶
各頁 spec 只寫頁面自己的差異，下列規則每頁都適用：
| 規則 | 行為 | 出處 |
|---|---|---|
| 專案資源的非成員 | 同租戶、但不是該專案成員的人打任何專案資源（專案、輪次、任務、證據、報告…），一律回 404，與資源不存在逐字相同（以專案定位的端點回 GRC_PROJECT_NOT_FOUND＝GRC_404001，以其他資源定位的回該資源的「不存在」碼）；回 403 等於確認這個編號是真的。是成員但角色不夠仍回 403（他本來就看得到這個專案） |
common/authz/project.py::raise_not_found_if_not_member；守衛測試 test_non_member_returns_not_found |
| 資料庫錯誤 | 只回固定碼 COMMON_400003（格式／長度超限）、COMMON_409001（衝突／仍被引用）、COMMON_408001（忙碌逾時）、COMMON_500001，訊息為固定文字；資料庫原文只進 log |
jedi-common 錯誤處理 |
| 前門 CSP（落地版） | 頁面與 API 回應都帶正式 Content-Security-Policy，不含 unsafe-inline 與 *；違規回報送 /api/1.0/csp-report。後端自帶 CSP 的 Google Drive 授權回呼頁例外，前門不疊加 |
FE nginx.onprem.conf |
| 富文字顯示 | 公告、報告等存成 HTML 的內容，解析前先把行內 style 改名，消毒時只把 text-align 轉成對齊 class（text-left/center/right/justify），字色、字級等其餘行內樣式捨棄；內容本身不改，只影響顯示。富文字編輯器貼上的 HTML 同樣處理 |
FE src/utils/dompurifyStyleToClass.js |
| 前門限速（落地版） | 每 IP：登入類端點（/login、/otp-verify、/otp-resend、忘記／重設密碼）每分鐘 60 次；webhook、agent 註冊、開通與 Drive 回呼每分鐘 30 次；CSP／前端錯誤回報每分鐘 120 次。超過回 429 |
FE nginx.onprem.conf limit_req_zone |
功能群 → 頁面 索引¶
各群先讀
_overview（頁面地圖 / 共用狀態機 / 核心資料模型）再進各頁。完整頁面清單見左側選單（按領域分組、與 repo 目錄一致）；下表為各群總覽入口。
| 功能群 | 總覽入口 |
|---|---|
| 專案管理 | 專案管理 |
| 稽核執行 | 稽核執行 |
| 合規框架與 SSP | 合規框架與 SSP |
| 證據管理 | 證據管理 |
| 問卷 | 問卷 |
| 報表與儀表板 | 報表與儀表板 |
| 協作（無總覽） | 公告管理 / 公告檢視 / 回饋管理 |
| 系統管理 | 系統管理 |
| 認證（登入前） | 認證 |
| Release Notes（查某次上版改了什麼） | Release Notes 總覽 |
| 1.21.0 行為變更尚未寫進頁面的 | 1.21.0 待補 spec 清單 |