# 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