file_access_agent/docs/DATA_MODEL.md

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