visionA/docs/autoflow/04-architecture/feature-model-sharing-tdd.md

技術設計文件（TDD）— 模型共享（Model Sharing）

狀態：Draft（待 PM / Design 三方互審） 作者：Architect Agent 日期：2026-08-02 範圍：L 級新功能。在既有「模型庫」（owner-only + preset）上，新增「公開對象（visibility）」+「共享模型庫（依身份權限可見）」兩個維度。 對齊：api/api-model-sharing.md（API 規格）、ADR-017 決策 3（model_shares 點對點分享）、database.md §2.3（models schema）。

不動 production code、不寫 migration 實檔——本檔只給設計方向，migration DDL / handler 由 backend agent 落地。

---

1. 系統概述與定位

1.1 功能拆解（對齊使用者截圖）

大項	細項	對應本 TDD
模型公開設定	設定公開對象	§3 資料模型（visibility 欄）+ API §3 PATCH visibility
共享模型庫	依身份權限可見列表 / 分頁 / 排序 filter / 搜尋	§4 權限查詢 + API §1 GET /api/models/library
共享模型庫	模型 profile 頁	§5 + API §2 GET /api/models/:id/profile

1.2 兩個正交維度（核心設計判斷）

現況只有 owner-only（models.owner_user_id + 403 非 owner）+ preset（7 個公用模型、不在 DB）。本功能加兩個正交維度：

維度	語意	資料落點	來源
visibility（廣播）	「對一群人公開」：private / tenant / public	models.visibility 欄（本 TDD 新增）	本功能
model_shares（點對點）	「分享給特定某人」by user	model_shares 表	ADR-017 決策 3 已定義，本功能沿用不重造

兩者是「或」的關係：一個 user 能看到 model ⟺ 是我的 OR visibility 命中我的身份 OR 被 share 給我 OR preset。這是共享模型庫列表的核心 predicate（§4）。

為何不把 visibility 塞進 model_shares：model_shares 是 per-(model, user) 列舉，表達「public/tenant」要對每個 user 塞一列、不可行。visibility 是「對一整群」的廣播屬性，天然是 model 上的 enum 欄，查詢時展開成 OR 條件。兩者資料結構本質不同、故分開。

---

2. 「依身份權限」的基礎：既有 identity 模型盤點

設計前先確認「身份」有什麼可用（避免腦補一套不存在的 RBAC）：

事實	source	對本功能的意義
users.roles TEXT[] NOT NULL DEFAULT '{}'	migration 0001 + user.User.Roles	有 role 欄位，但目前 OIDC provision 只寫最小欄位、role 多為空。本功能第一階段不依賴 role 做可見性（避免建在空資料上），只用 owner / org / share / visibility。role-based 可見性列為後續。[需 PM 確認]
users.org_id UUID（migration 0001 有欄）；但 user.User domain 未含 OrgID、UserContext.OrgID 有欄位但 OIDC 未必填	migration 0001 line、auth.UserContext.OrgID、user.User（無 OrgID）	tenant visibility 依賴 org_id。第一階段需確認 OIDC 是否帶 org claim；若無，tenant 可見性暫時等同「沒有人」（安全預設）。[需 PM 確認] org_id 來源。
UserContext{ UserID, Email, Roles, OrgID } 已是 handler 可信賴身份	auth.auth.go	可見性查詢的 input = UserContext。handler 從它取 userID + orgId。
無 tenant / group / workspace 表	grep migrations	本功能不新增 workspace 表（ADR-017 決策 3 B2 workspace 留後續）。tenant = org_id 直接比對，不建關聯表。

設計結論：第一階段「身份」= userID + org_id。可見性維度 = private / tenant(org) / public + 點對點 share。不建 RBAC engine、不建 workspace 表（effort scaling：與現況落差最小、避免建在空 role 資料上）。

---

3. 資料模型變更（給 migration 設計方向，不寫實檔）

3.1 models 表加 visibility 欄

-- 方向（DDL 由 backend agent 落地 migration 0006 或後續編號）
ALTER TABLE models ADD COLUMN visibility TEXT NOT NULL DEFAULT 'private';
--   'private' | 'tenant' | 'public'
--   既有資料預設 'private'：不破壞現況（既有 model 維持只有 owner 看得到）。★關鍵相容性
ALTER TABLE models ADD CONSTRAINT chk_models_visibility
    CHECK (visibility IN ('private','tenant','public'));

為何用 enum 欄而非獨立 sharing 表：

• 「公開對象」是 model 的單值屬性（一個 model 一個 visibility），不是 1-N 關聯 → enum 欄最自然、查詢無需 join。
• 若未來要「同時公開給多個特定 group」才需要關聯表；第一階段 private/tenant/public 三選一，enum 足夠（YAGNI）。

既有資料預設值（關鍵相容性）：DEFAULT 'private' → 既有所有 model 遷移後維持 owner-only 語意，零行為改變。使用者要主動 PATCH 才會公開。

3.2 model_shares 表（沿用 ADR-017 決策 3，本功能不重造）

ADR-017 決策 3 已定義（此處只引用、確認欄位對齊）：

CREATE TABLE model_shares (
    model_id        UUID NOT NULL REFERENCES models(id),
    grantee_user_id UUID NOT NULL REFERENCES users(id),
    role            TEXT NOT NULL,     -- 'viewer' | 'editor'
    granted_by      UUID NOT NULL REFERENCES users(id),
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (model_id, grantee_user_id)
);
CREATE INDEX ON model_shares (grantee_user_id);

本功能第一階段的寫入 model_shares 的 API（分享給特定人）不在使用者截圖範圍內（截圖是「公開對象」+「共享庫瀏覽」）。model_shares 在本功能中主要作為讀取端（共享庫 predicate 的一部分），確保未來點對點分享上線時共享庫已支援。[需 PM 確認] 本期是否需要「分享給特定人」的寫入 UI，或只做 visibility 廣播。

3.3 index 設計（效能，見 §4）

-- 共享庫「public 全平台可見」列表：high-selectivity 掃描
CREATE INDEX idx_models_public_active ON models (visibility, created_at DESC)
    WHERE deleted_at IS NULL AND visibility = 'public' AND uploaded_at IS NOT NULL;
-- tenant 可見：需 join users 取 owner.org_id，故 index 在 owner_user_id（既有 idx_models_owner_active 已可用）
-- 搜尋 q：見 §5 效能考量（第一階段 ILIKE + trigram，量大再上 FTS）

沿用 ADR-018 慣例：partial index WHERE deleted_at IS NULL（既有 models index 全用此模式）、gen_random_uuid()（PG14 內建）、migration 需有對應 *_test.go 驗 up/down 對稱（130 testcontainers，避免假綠——見 memory「DB 接入 dbtest 陷阱」）。

---

4. 權限可見性查詢設計（核心，效能重點）

4.1 可見性 predicate

「共享模型庫列表」= 一個 query 過濾出當前 user 可見的所有 model：

可見(model, user) =
      model.owner_user_id = :userID                              -- 我的
   OR model.visibility = 'public'                                -- 全平台
   OR (model.visibility = 'tenant'
        AND owner.org_id = :userOrgID AND :userOrgID IS NOT NULL) -- 同租戶
   OR EXISTS (SELECT 1 FROM model_shares s                        -- 分享給我
        WHERE s.model_id = model.id AND s.grantee_user_id = :userID)
-- preset 模型不在 DB，由 handler 層 union（沿用既有 modelsListHandler 做法）

4.2 query 形狀（給 backend，方向非最終 SQL）

第一階段建議 單一 query + LEFT JOIN users（取 owner.org_id / owner.name） ：

SELECT m.*, u.name AS owner_name, u.org_id AS owner_org_id
FROM models m
JOIN users u ON u.id = m.owner_user_id
WHERE m.deleted_at IS NULL
  AND m.uploaded_at IS NOT NULL                    -- 只列 ready
  AND (
        m.owner_user_id = $userID
     OR m.visibility = 'public'
     OR (m.visibility = 'tenant' AND u.org_id = $userOrgID AND $userOrgID <> '')
     OR EXISTS (SELECT 1 FROM model_shares s
                 WHERE s.model_id = m.id AND s.grantee_user_id = $userID)
      )
  -- + filter（target_chip / source / q）+ sort + cursor（見 §5）

4.3 效能考量

考量	對策
OR 條件讓 planner 難用 index	public 是最常見的大集合、用 idx_models_public_active（§3.3）覆蓋。owner 用既有 idx_models_owner_active。PG 對多 OR 可能走 BitmapOr——[需 backend 驗] EXPLAIN，量大時考慮拆 UNION（owner 子查 ∪ public 子查 ∪ shared 子查）避免全表掃。
model_shares EXISTS 子查	idx model_shares (grantee_user_id) 已在 ADR-017 定義，子查走此 index。
tenant join users	owner.org_id 比對需 join；users 主鍵 join 成本低。
N+1 owner name	用 JOIN 一次帶出 owner_name，不在 handler loop 查。
共享庫規模	全平台 public model 數量可能大 → 必須分頁 + index，不可一次撈全部（現況 owner-only list 無此問題）。

---

5. API 規格摘要（詳見 api/api-model-sharing.md）

端點	用途	權限
GET /api/models/library	共享庫列表（分頁 cursor + limit + sort + order + q + filter）	登入即可，回傳依身份裁剪可見範圍
GET /api/models/:id/profile	模型 profile（公開版詳情）	可見性檢查，不命中回 404
PATCH /api/models/:id/visibility	設公開對象	owner-only

5.1 分頁契約（cursor vs offset — 決策）

採 cursor-based（不透明 base64 游標），不用 offset：

• 理由：共享庫是「跨擁有者、可能很大、常按 created_at 排序」的 feed 型列表；offset 在深分頁效能差且有「插入導致跳頁/重複」問題。
• cursor 編碼 (sort_value, id) tie-breaker，base64 不透明（前端當黑箱）。
• has_more + next_cursor 回傳（見 API §1）。
• 與既有 GET /api/models 不一致是可接受的：既有是「我的模型」小列表、無分頁需求；共享庫是新端點、獨立契約。[需 Design 確認] 前端是否用無限捲動（cursor 適合）或頁碼（offng 需 offset，但不建議）。

5.2 既有端點的連帶變更（相容性關鍵）

既有端點	變更	相容性
GET /api/models	不變（維持「我的 + preset」語意，owner dashboard 用）	零改變
GET /api/models/:id（get 詳情）	不變（維持 owner-only 403）	零改變；profile 是新端點、不動這個
GET /api/models/:id/download	owner-only → 共享權限檢查（有可見性 + can_download 才放行）	⚠️ 行為改變、涉及 auth。與 profile 可見性共用同一判斷函式（single source of truth）。[需 security 審]
POST /api/models/init / finalize / DELETE	不變（新 model 預設 private，見 §3.1）	零改變
toModelResponse DTO	加 visibility 欄（omitempty 或固定輸出，[需 Design 確認]）	加欄不破壞既有前端（snake/camel 雙吃 + 未知欄忽略）

---

6. 安全性設計（多處 [需 security 審]）

#	風險	對策	需 security 審
SEC-1	IDOR / enumeration：非 owner 猜 model id 看不該看的 profile/download	可見性檢查在 handler 第一步；不命中回 404 而非 403（不揭露 id 存在性）	✅
SEC-2	下載端點權限繞過：download 從 owner-only 放寬後放行過頭	profile 可見性 + download 授權共用同一 canAccessModel(uc, model) → accessLevel 函式，杜絕兩處邏輯漂移	✅
SEC-3	資訊洩漏：profile 回傳 owner email / storage_key / faa_object_key	DTO 白名單；內部 key json:"-"（沿用 FAAObjectKey 既有做法）；owner 只揭露 id/name	✅
SEC-4	tenant 邊界誤放：org_id 為空時誤判「同租戶」	tenant 命中要求 owner.org_id == user.org_id 且兩者皆非空；空 org 一律不落 tenant 可見	✅
SEC-5	越權改 visibility：非 owner 改他人 model 公開對象	PATCH visibility 強制 owner_user_id == userID；editor 能否改 [需 PM 確認]	✅
SEC-6	公開後可下載即等於檔案外流	visibility=public 的 download 仍走 ADR-017 (a) FAA delegated token（短 TTL + boundary），非直接曝露 storage	併 ADR-017 R4

建議：本功能的權限模型（可見性判斷 + download 放寬 + enumeration 防護）整體送 security agent 審一輪。這是「auth 的複雜點」——放寬既有 owner-only 邊界，任何判斷漏洞都是資料外洩。

---

7. 對既有功能的相容性總結

面向	影響	結論
既有 model 資料	visibility DEFAULT 'private'	零行為改變，既有 model 維持 owner-only
既有 GET /api/models	不動	相容
既有上傳/下載/刪除	上傳/刪除不動；download 加共享權限檢查	download 需回歸測試（既有 owner 下載仍 work）
前端 model-store	DTO 加 visibility 欄；snake/camel 雙吃 + 未知欄忽略	加欄相容；共享庫是新頁面/新 store slice
migration	新增 visibility 欄 + index（+ model_shares 若尚未建）	需 up/down 對稱 test（130 testcontainers，避免假綠）

---

8. 並行化工作流計畫（Parallelization Plan）

L 級、跨 backend + frontend + testing，適用本節。contract-first：§8.1 契約定死後三條 work-stream 可平行。

8.1 模組間契約（single source of truth）

契約項	定義處	鎖定內容
API schema（library / profile / visibility）	api/api-model-sharing.md	request/response 欄位、分頁 cursor 形狀、錯誤碼
visibility enum	本檔 §3.1	private/tenant/public（三方一致，前後端不各自定義字串）
accessLevel enum	本檔 §6 SEC-2	owner/editor/viewer/none（can_download = access != none）
可見性 predicate	本檔 §4.1	唯一真實來源，backend 與 testing 都對這份
DTO 欄位（owner 裁剪、內部 key 不揭露）	api §1/§2	owner{id,name,is_me}、不含 email/storage_key/faa_object_key

8.2 依賴圖 + 關鍵路徑

graph LR
    C[契約定稿 §8.1<br/>critical] --> M[migration: visibility 欄+index<br/>backend, critical]
    C --> FE[前端: 共享庫頁+profile<br/>對 mock schema]
    M --> Q[權限 query + canAccessModel<br/>backend, critical]
    Q --> LIB[library/profile/visibility handler<br/>backend]
    Q --> DL[download 端點權限放寬<br/>backend]
    C --> TS[測試腳本設計<br/>testing 對契約]
    LIB --> INT[整合 join]
    DL --> INT
    FE --> INT
    INT --> SEC[security 審 + E2E join]
    TS --> SEC

關鍵路徑（critical path）：契約定稿 → migration → 權限 query + canAccessModel → handler → 整合 → security審/E2E。這條無法平行、決定總工期。前端可對 mock schema 平行、不在關鍵路徑上。

8.3 work-stream 清單 + 同步點

Work-stream	派給	可與誰平行	阻擋於（前置）	同步點（join）
WS-1 migration + 權限 query + canAccessModel + 三個 handler + download 放寬	backend	WS-2, WS-3	契約定稿	整合 join
WS-2 共享庫列表頁 + profile 頁（對 mock）	frontend	WS-1, WS-3	契約定稿	整合 join
WS-3 測試腳本設計（權限 matrix + 分頁 + enumeration）	testing	WS-1, WS-2	契約定稿	E2E join
WS-4 security 審（權限模型 / IDOR / 邊界）	security	—	WS-1 整合後	security join

backend 的權限 query 與 canAccessModel 在關鍵路徑、內部串行（query → handler → download），不硬拆。coding 本質難平行的部分誠實標串行。

8.4 任務卡（Anthropic 四要素，摘要）

WS-1 backend：

• Objective：落地 visibility 欄 migration + 可見性 query + canAccessModel(uc, model)→accessLevel 單一函式 + library/profile/visibility 三 handler + download 端點改用 canAccessModel。
• Output：可運行 API + 單元測試（權限 matrix）+ migration up/down test（130 testcontainers）。行為符合 §4.1 predicate + api 契約。
• 來源指引：本 TDD §3/§4/§6 + api/api-model-sharing.md + ADR-017 決策 3（model_shares）。
• 邊界：只做 model sharing。不碰前端、不改 model_shares schema（ADR-017 已定）、不動既有 GET /api/models 與 /:id 語意。visibility/accessLevel 字串照契約、不自造。download 放寬必須用 canAccessModel、不得複製一份可見性邏輯。

WS-2 frontend：

• Objective：共享庫列表頁（分頁/排序/filter/搜尋）+ profile 頁 + visibility 設定 UI。
• Output：頁面 + 元件測試，對 §8.1 契約的 mock。
• 邊界：只做 UI + api client。不碰 backend。visibility enum / 錯誤碼 / 分頁 cursor 當黑箱照契約。不揭露/不依賴 storage_key/faa_object_key（DTO 本來就沒有）。

WS-3 testing：

• Objective：權限可見性 matrix（owner/tenant同org/tenant異org/public/shared/無關 × library/profile/download）+ enumeration（猜 id 回 404）+ 分頁 + 既有 owner download 回歸。
• 邊界：對契約與 §4.1 predicate 設計，不改 production code。

---

9. 待三方確認清單（彙整，交互審用）

#	項目	待誰	出處
P1	org_id 來源（OIDC 是否帶 org claim）+ tenant=org 語意是否正確；跨 org 可能性	PM	§2
P2	本期是否要「分享給特定人」寫入 UI，或只做 visibility 廣播	PM	§3.2
P3	editor 能否改 visibility / 未 ready 能否公開 / checksum 對非 owner 是否公開	PM	api §3/§5、§6 SEC-5
P4	第一階段是否需要 role-based 可見性（現況 role 資料多為空）	PM	§2
D1	共享庫 UI 入口（與「我的模型」分頁 or 合併 tab）、無限捲動 vs 頁碼	Design	§5.1、api §0
D2	shared_with_me / visibility badge 標示方式、profile 頁欄位與版面	Design	api §1/§2
SEC1	整體權限模型送審：IDOR/404 策略、download 放寬、tenant 邊界、owner email 不揭露	security	§6 全節

---

10. 一句話總結

在既有 owner-only 模型庫上，加一個 model 上的 visibility enum 欄（private/tenant/public，預設 private 保證零相容性衝擊） 作為「公開對象」廣播維度，與 ADR-017 決策 3 的 model_shares（點對點分享）正交；共享模型庫用單一可見性 predicate（我的 ∪ public ∪ 同 org tenant ∪ share ∪ preset）+ cursor 分頁 + 對應 index 查詢；profile/download 的權限用同一 canAccessModel 函式杜絕邏輯漂移，enumeration 一律回 404——整個放寬 owner-only 邊界的權限模型建議整體送 security 審。