多租戶 SaaS 後端目前已實現、可直接串接的 API 能力,依 9 個模組盤點,標明每個模組解決的問題與可用端點。
內部工程與 PM,做為前端串接、能力對齊與範圍溝通的單一「能力地圖」,補足 schema 契約看不出的全貌。
API 契約已達 75 路徑 / 112 操作、三條使用線成形;能力散落在 schema 中,需一頁對齊已交付範圍與尚未涵蓋的邊界。
後端能力真相集中在 openapi.json(CI 強制與程式碼同步),但那是逐端點的 request/response schema——看得到「有哪些欄位」,看不出「這個模組解決什麼問題、屬於哪條使用線、邊界在哪」。前端串接與 PM 排範圍時,得在數十條路徑之間反覆拼圖,常誤判某能力「還沒做」或「應該有」。本文以功能視角把 9 個模組、三條使用線與 6 項橫切能力壓成一頁,並明確標出尚未涵蓋的面向(合約寫入、LINE 訊息推播、寄信),讓串接與範圍討論有共同基準。
“我每次串新功能都要先開 Scalar 翻半天,才確定這條線到底做完了沒。給我一頁能力地圖,比 100 條 schema 有用。
— 前端工程師(LIFF / 租戶後台)
openapi.json 逐欄位契約(schema 仍以其為準)。frontend/ 三份導覽)。任何狀態碼皆回 {data, messages, status_code},錯誤帶穩定機器碼。ADR-0054 / 0045。
每端點有 gating permission,伺服器端即時解析(60 秒快取,撤銷即時失效)。
租戶未啟用模組整組回 403;租戶停權全站封鎖(entitlement)。
所有寫入方法支援 Idempotency-Key header,重試安全。
長時作業(如 ERP 同步)回 202 + job_id,以 GET /jobs/{id} 輪詢。
GET /health/live、GET /health/ready。
使用者如何登入、如何被邀請進租戶、租戶內成員如何管理。
租戶如何自訂角色組合權限;平台如何維護全域角色目錄。
inactive_permissions,不報錯(ADR-0048)。平台如何開租戶、控制可用模組、處理停權與刪除。
誰能當平台管理員;問題帳號如何全域封鎖;權限如何稽核。
公司 / 業主 / 員工 / 廠商主資料,以及現場人員如何拿到登入帳號。
code 不可改、支援 ?view=options;協力廠商人員資料範圍固定 own(ADR-0051)。工程專案建檔與空間分區(區域樹),供合約與回報掛載。
合約由 ERP 單向同步(唯讀),現場人員回報工作量,系統管控上限與追加減。
租戶自帶物件儲存(R2 / S3 / MinIO),使用者上傳回報照片等附件。
LLM 供應商設定與對話代理(本次未聚焦,列此備查) — 租戶自帶 LLM 金鑰(BYO key),
/llm/profiles 管理 profile 與金鑰輪替(只寫不讀、遮罩 last 4);
POST /llm/{name}/v1/chat/completions 為 OpenAI 相容、恆 SSE 串流,是系統中唯一不走回應信封的端點。
| 指標 | 現況值 | 量測方式 |
|---|---|---|
| API 契約規模 | 75 路徑 · 112 操作 | 以 openapi.json 逐路徑 / operation 計數(CI 強制同步)。 |
| 模組覆蓋 | 9 模組 | identity · permission · tenant · directory · project · contract · llm · storage(+ 平台治理)。 |
| 使用線覆蓋 | 3 條 | 超管後台 /admin/*、租戶後台 /<module>/*、LIFF(租戶線子集)。 |
| 橫切保證 | 6 項全模組 | 回應信封、RBAC、entitlement 閘門、冪等、背景工作、健康檢查逐端點適用。 |
| 寫入冪等覆蓋 | 100% 寫入方法 | 所有寫入端點支援 Idempotency-Key,重試安全。 |
| 權限撤銷延遲 | 即時(≤ 60s 快取) | RBAC 伺服器端解析,權限快取 60 秒,撤銷即時失效。 |
我想要一次交易開通租戶並種核心模組授權、必要時以代入身分排查,以便快速上線客戶且全程稽核可追、不會升權。
我想要邀請成員與協力廠商人員、自訂角色權限、維護名錄與專案區域,以便把現場組織搬進系統並控管誰能看哪些資料。
我想要接受邀請直接入戶、對可回報項目批次提交工作量並附照片,以便在工地用手機完成報工,且只看得到自己所屬廠商的合約。
登入 / 邀請 / 多租戶切換、RBAC 角色目錄、平台帳號治理與租戶生命週期。
四種名錄主檔 + 帳號開通、協力廠商人員入戶、專案與階層區域樹。
ERP 單向同步 + 現場批次回報 + 追加減對帳、BYO 儲存兩段式上傳、BYO LLM 對話代理。
合約寫入面(僅 ERP 同步、API 無建立 / 修改)、專案硬刪除(以 status 取代)、邀請寄信(僅回一次性 token)、LINE webhook / 訊息推播端點。