# Shared Drive File Access 功能規格與 SOP

## 實際程式碼再確認

### 目前已存在、可直接重用的能力
1. **AI_Result 本機快取查詢能力已存在**
   - `ai_result_cache_query.py`
   - `ai_result_nl_query.py`
   - 已可查 local SQLite / SearchIndex / Knowledge / RAG cache
   - 適合先支撐 AI_Result 範圍內的模糊查詢與路徑定位

2. **Hermes 已有受控 public download 能力**
   - `hermes_cli/managed_downloads.py`
   - 已有：
     - staged public downloads
     - persistent signing secret
     - signed token
     - `/downloads/<token>` 形式 public URL
   - 目前預設有效期為 7 天，但可在建立 token 時覆寫秒數；因此 **24 小時有效連結是可行的**

3. **本機可做 zip 加密**
   - 目前主機 `zip` 指令支援 `-e encrypt`
   - 代表第一版可先用密碼保護 zip

4. **共享槽目前在 Hermes 主機可掛載可讀**
   - `/Volumes/Project`
   - `/Volumes/Materials`
   - `/Volumes/media`
   - `/Volumes/AI_Result`

### 目前尚未完整存在、需要補建的能力
1. **共享槽統一索引層尚未存在**
   - 目前 AI_Result 有 local cache / SQLite / SearchIndex
   - 但 `/Volumes/Project`、`/Volumes/Materials`、`/Volumes/media` 尚未看到統一的「快速語意 / 模糊搜尋檔案位置索引」

2. **資料夾 → 候選檔案選取 → 最多 10 檔打包下載** 尚未做成固定流程

3. **敏感檔案判斷 → 自動改走加密壓縮檔** 尚未做成固定規則與執行管線

---

## 目標

建立一套給同事使用的共享槽查找 / 下載能力，讓使用者可以：
- 用自然語言、模糊描述、品牌名、客戶名、檔名片段、內容片段查找公槽檔案
- 由 Hermes 回覆候選檔案 / 資料夾位置
- 必要時產生 **24 小時有效** 的下載連結，供不在辦公室、無法直接掛載公槽的人使用
- 若命中資料夾，先列出候選檔案，讓使用者最多選擇 10 個檔案後打包下載
- 若檔案含個資或財務資料，或無法可靠判定內容，預設走 **加密壓縮檔 + 分通道密碼通知**

## 非目標
- 不把整個共享槽直接暴露成可瀏覽檔案伺服器
- 不預設讓整個資料夾整包外送
- 不在第一版就做 heavyweight vector database / embeddings-first 系統
- 不處理使用者對共享槽權限差異；目前前提是「你看到的資料夾皆屬同事可查閱範圍」

---

## 建議使用模式

### 模式 1：找到後回路徑
適用：同事本來就能進辦公室或可掛共享槽

輸出：
- 檔案或資料夾候選
- Mac / Windows 路徑
- 類型、時間、簡述

### 模式 2：找到後直接給檔案下載
適用：同事不在辦公室、無法掛載共享槽，但已明確知道檔案就是要哪一個

輸出：
- 候選確認
- Hermes 複製到本機 staging
- 產 24 小時 signed link

### 模式 3：先列候選，再讓用戶選擇
**這是預設模式，也是最推薦模式。**

適用：
- 查詢模糊
- 可能有多版本
- 查到的是資料夾
- 同事只記得用途，不記得完整檔名

規則：
- 先列候選清單
- 若是單檔，可直接選定下載
- 若是資料夾，只列檔案，不直接整包提供
- 最多選 10 個檔案後打包下載

---

## 使用流程 SOP

### A. 查找階段
1. 使用自然語言 / 模糊搜尋詞進行搜尋
2. 先查 AI_Result 本機快取層（若問題屬 AI_Result）
3. 再查共享槽檔名 / 路徑 / 摘要索引
4. 回傳候選清單，而不是直接猜單一答案

### B. 候選呈現階段
每個候選至少包含：
- 檔名 / 資料夾名
- 類型
- 所屬共享槽（Project / Materials / media / AI_Result）
- Mac 路徑
- Windows 路徑
- 修改時間
- 簡短說明（若可抽取）
- 是否可下載

### C. 單檔下載階段
1. 使用者選定檔案
2. Hermes 將原始檔**複製到本機 staging**（不可直接拿原公槽路徑發連結）
3. 若需保護，先轉入加密 zip
4. 使用 managed download 產生 tokenized public URL
5. URL 有效期固定 **24 小時**
6. 回傳下載連結

### D. 資料夾下載階段
1. 若查到的是資料夾，先列該資料夾內檔案清單
2. 使用者最多可選擇 **10 個檔案**
3. Hermes 複製所選檔案到本機 staging
4. 打成 zip
5. 若需保護，打成**加密 zip**
6. 產生 24 小時有效下載連結

### E. 密碼通知階段
若壓縮檔為加密 zip：
- 下載連結走原聊天
- 密碼必須走**另一通道**
  - 優先：綁定 email
  - 次選：另一個已綁定訊息通道
- 若無可信第二通道，應先要求確認，不直接自動外送敏感壓縮包

---

## 敏感資料保護規則

### 一律加密的情況
1. 可明確判讀並命中：
   - 個資
   - 財務資料
   - 報價 / 成本 / 營收 / 毛利 / 付款資訊
   - 身分證、手機、地址、信箱、銀行帳號等高敏欄位

2. 無法可靠解析內容：
   - 掃描型 PDF
   - 圖片型文件
   - 未知格式
   - 壓縮包裡再包其他檔案

3. 一個 zip 內只要任一檔命中敏感條件
   - 整包加密

### 可不加密的情況
- 公開素材
- 一般參考圖檔
- 已知為低風險且可清楚辨識內容的簡報 / 文件
- 但若使用者要求，也可手動強制加密

### 注意
這套是「**有信心就判斷，沒信心就保守加密**」策略，避免偽陰性。

---

## 下載規則

### 連結規則
- 下載連結必須來自 Hermes 管理的 staged public download 路徑
- 不可直接暴露 `/Volumes/...` 原始路徑
- tokenized link 有效期固定 24 小時
- 連結失效後需重新產生

### 單次限制
- 資料夾模式最多 10 個檔案
- 建議再加總大小上限（例如 500MB 或 1GB，實作時決定）
- 超限時：
  - 拒絕直接打包
  - 改回候選清單、請使用者縮小範圍

### staging 清理
- staging 檔案與 zip 應在有效期後自動清理
- 即使 token 過期，也不應無限保留本機副本

---

## 語意 / 模糊搜尋能力評估

### 目前夠用的部分
對 AI_Result：
- 目前已有 local cache / SQLite / SearchIndex / Knowledge / NL query wrapper
- 足夠支撐第一版 AI_Result 範圍內的模糊查找與路徑定位

### 目前不足的部分
對整體共享槽：
- `/Volumes/Project`
- `/Volumes/Materials`
- `/Volumes/media`

目前尚未看到統一的「檔名 + 路徑 + 內容摘要」快速索引層。
所以若要讓共享槽查找變好用，**建議另外建立一層快速索引**。

### 是否需要一開始就做 embeddings / 向量搜尋？
**不需要。**

第一版建議先做：
- SQLite/FTS5
- 檔名 / 路徑 / 資料夾名 / 抽取摘要索引
- alias / synonym expansion
- BM25 排序

理由：
- 成本較低
- 更新維護簡單
- 已足夠解掉大多數「同事找檔」問題
- 之後真的不夠，再補 hybrid search（FTS + embeddings）

---

## 推薦方案

## Phase 1（推薦先做）
- AI_Result 繼續使用現有 local cache / SearchIndex / SQLite
- 新增共享槽檔案索引（Project / Materials / media）
- 預設採 **模式 3：先列候選再選擇**
- 單檔可產 24h link
- 資料夾最多選 10 檔後打包
- 敏感 / 不可判讀內容預設加密 zip
- 密碼分通道傳送

## Phase 2
- 增加更完整的內容抽取
  - PDF / docx / xlsx / pptx
- 增加敏感度分類器
- 增加 staging quota / cleanup / audit

## Phase 3
- 若 FTS 效果不夠，再補 embeddings / hybrid semantic retrieval

---

## 需要補充的政策項目
建議在正式實作前明文化：
1. 哪些共享槽 root 允許產生下載連結
2. 總大小上限與單檔上限
3. 失效後 staging 清理時間
4. 若無第二通道，敏感壓縮檔是否禁止外送
5. 是否需要記錄下載稽核（日後可加）
6. 是否允許同一使用者一次請求多個下載包

---

## 最終建議
**最適合也最方便建製的方案是：**

> 先做「共享槽 FTS/摘要索引 + 候選清單互動 + 本機 staging 下載 + 敏感加密」的第一版，
> 不要一開始就上完整向量語意系統。

這樣能最快落地，也最符合你現在的使用場景與 Hermes 現有能力。
