129 lines
2.7 KiB
Markdown
129 lines
2.7 KiB
Markdown
# Data Model
|
||
|
||
本文件定義 File Access Agent 的「可選」持久化模型，不是預設必備。
|
||
|
||
## 1. 設計前提
|
||
|
||
- 預設模式為無 DB，metadata 由 bucket provider 提供。
|
||
- 部署採 single-tenant instance：同一個 instance 只處理一個 tenant 的資料。
|
||
- 若啟用持久化，`tenant_id` 仍保存在資料中，作為稽核與跨環境遷移邊界欄位。
|
||
|
||
## 2. 何時才需要持久化
|
||
|
||
只有在下列需求出現時，才建議加 DB：
|
||
|
||
- 審計落地（合規或追蹤）
|
||
- token `jti` replay 防護
|
||
- 額外索引需求（例如 `file_id` 到 `object_key` 快取映射）
|
||
|
||
## 3. 最小可選資料表
|
||
|
||
建議最小可選表：`file_object_refs`
|
||
|
||
用途：
|
||
|
||
- 保存 `file_id` 到 `object_key` 的輕量映射（若上游要求）
|
||
|
||
欄位：
|
||
|
||
- `id`：UUID 或 ULID，internal id
|
||
- `tenant_id`：UUID，應等於 instance 固定 tenant
|
||
- `file_id`：string，唯一
|
||
- `object_key`：string，唯一
|
||
- `created_at`：timestamp
|
||
- `updated_at`：timestamp
|
||
|
||
索引：
|
||
|
||
- unique(`file_id`)
|
||
- unique(`object_key`)
|
||
- index(`updated_at`)
|
||
|
||
## 4. 其他可選資料表
|
||
|
||
### 3.1 `file_access_audit_logs`
|
||
|
||
用途：追蹤 upload/download/metadata/delete 操作
|
||
|
||
欄位：
|
||
|
||
- `id`
|
||
- `tenant_id`
|
||
- `object_key`
|
||
- `action` (`upload|download|metadata|delete`)
|
||
- `actor_type` (`service|client`)
|
||
- `actor_id` nullable
|
||
- `result` (`allow|deny`)
|
||
- `reason_code` nullable
|
||
- `created_at`
|
||
|
||
### 3.2 `token_jti_registry`
|
||
|
||
用途：若之後要做 delegated token replay 防護
|
||
|
||
欄位：
|
||
|
||
- `jti`
|
||
- `tenant_id`
|
||
- `expires_at`
|
||
- `consumed_at` nullable
|
||
|
||
## 5. 儲存技術建議
|
||
|
||
### 4.1 SQLite（建議起步）
|
||
|
||
適用（啟用持久化時）：
|
||
|
||
- 單 instance
|
||
- 中低流量
|
||
- 結構固定、查詢簡單
|
||
|
||
優點：
|
||
|
||
- 部署成本最低
|
||
- C# 生態成熟（EF Core + SQLite）
|
||
|
||
風險：
|
||
|
||
- 高併發寫入能力有限
|
||
- 多副本部署需額外設計一致性
|
||
|
||
### 4.2 文件型 NoSQL
|
||
|
||
適用（啟用持久化時）：
|
||
|
||
- 主要是 key lookup，關聯少
|
||
- 僅存映射或審計文件，不做複雜 join
|
||
|
||
優點：
|
||
|
||
- schema 彈性高
|
||
- `metadata_json` 可原生存取
|
||
|
||
風險：
|
||
|
||
- 交易與一致性語意通常較弱
|
||
- 後續做複雜查詢或審計統計可能要補額外索引設計
|
||
|
||
### 4.3 PostgreSQL
|
||
|
||
適用（啟用持久化時）：
|
||
|
||
- 需要高併發與穩定維運
|
||
- 需要更完整審計與分析查詢
|
||
|
||
優點：
|
||
|
||
- 可靠、可擴展、與 Member Center 堆疊一致
|
||
- `jsonb` 可兼顧結構化與彈性欄位
|
||
|
||
風險：
|
||
|
||
- 維運成本高於 SQLite
|
||
|
||
## 6. 建議路線
|
||
|
||
1. `v1`：無 DB（預設）
|
||
2. `v1.5`：若需要映射或審計，先上 SQLite + `file_object_refs`（必要時加 `file_access_audit_logs`）
|
||
3. `v2`：若流量或治理需求提升，再評估 PostgreSQL 或 NoSQL
|