# Shared Drive v2 驗收模板（完整版）

> 用途：每次 **shared drive index v2 調整 / 排程變更 / workflow 改動 / Hermes update 後**，直接複製這份，填 `PASS / FAIL / PARTIAL / NOT RUN`。適合內部留完整驗收紀錄。
>
> 搭配文件：
> - `shared-drive-index-v2-maintenance.md`
> - `shared-drive-file-access-validation-matrix.md`
> - `shared-drive-file-access-reply-formats.md`
> - `README.md`

---

## 基本資訊
- 日期：
- 執行者：
- 驗收者：
- 類型：`restart / update / merge / hotfix / refactor / cron-change`
- 版本 / commit / 變更摘要：
- 是否有改 code：`是 / 否`
- 是否有改排程：`是 / 否`
- 是否有改 shared drive roots / 掛載：`是 / 否`

---

## 一、這次改到哪裡
- [ ] `~/.hermes/scripts/shared_drive_common.py`
- [ ] `~/.hermes/scripts/shared_drive_index_build.py`
- [ ] `~/.hermes/scripts/shared_drive_index_v2.py`
- [ ] `~/.hermes/scripts/shared_drive_index_v2_daily.py`
- [ ] `~/.hermes/scripts/shared_drive_index_query.py`
- [ ] `~/.hermes/scripts/shared_drive_lookup.py`
- [ ] `~/.hermes/scripts/shared_drive_chat_workflow.py`
- [ ] `~/.hermes/scripts/shared_drive_delivery_bundle.py`
- [ ] `~/.hermes/scripts/shared_drive_cleanup.py`
- [ ] cron job：`shared-drive-index-v2-daily`
- [ ] 其他：

---

## 二、快速健康檢查（2～5 分鐘）
- [ ] `shared_drive_index_v2.py status` 可讀
- [ ] `shared_drive_index_v2_daily.py` 可執行
- [ ] `shared-drive-index-v2-daily` 排程存在
- [ ] 共享槽根目錄可掛載 / 可讀
- [ ] 沒有明顯 restart loop / 排程異常通知洗版

### 結果
- 狀態：`PASS / FAIL / PARTIAL`
- 備註：

---

## 三、靜態檢查

### 3.1 py_compile
```bash
python3 -m py_compile \
  ~/.hermes/scripts/shared_drive_common.py \
  ~/.hermes/scripts/shared_drive_index_build.py \
  ~/.hermes/scripts/shared_drive_index_v2.py \
  ~/.hermes/scripts/shared_drive_index_v2_daily.py \
  ~/.hermes/scripts/shared_drive_index_query.py \
  ~/.hermes/scripts/shared_drive_lookup.py \
  ~/.hermes/scripts/shared_drive_chat_workflow.py \
  ~/.hermes/scripts/shared_drive_delivery_bundle.py \
  ~/.hermes/scripts/shared_drive_cleanup.py
```
- 結果：`PASS / FAIL / NOT RUN`
- 備註：

---

## 四、索引器 v2 smoke

### 4.1 status
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py status
```
- [ ] 可輸出 JSON
- [ ] 有 `roots`
- [ ] 有 `files` / `fts_rows`
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.2 時窗外行為
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py tick
```
- [ ] 在 `01:00~02:00` 外時回 `outside_window`
- [ ] 不會偷開新 cycle
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.3 忽略時窗手動補跑
```bash
python3 ~/.hermes/scripts/shared_drive_index_v2.py tick --ignore-window
```
- [ ] 可正常跑完或至少推進 queue
- [ ] `processed_dirs` / `indexed_entries` 有合理變化
- [ ] `last_error` 沒有持續惡化
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 4.4 續掃 / 隔日接力邏輯
- [ ] 沒掃完時保留 `active_cycle_id`
- [ ] 再跑時繼續同一個 cycle
- [ ] 掃完後轉 `idle` / `cycle_completed`
- [ ] 不會每天從頭全掃前半段
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 五、shared drive workflow smoke

### 5.1 search
```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py search <query>
```
- [ ] 有候選清單
- [ ] 每個候選有 `file_id`
- [ ] 文案可直接貼聊天
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 5.2 children
```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py children <folder_file_id>
```
- [ ] 可展開資料夾
- [ ] 子檔有 `file_id`
- [ ] 有「最多 10 檔」提示
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 5.3 bundle（索引候選）
```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py bundle \
  --file-ids <file_id_1> ... \
  --requester dk96@bremen.com.tw
```
- [ ] 產出 `download_url`
- [ ] 有 `expires_at`
- [ ] `verification.ok = true`
- [ ] `download_url` 優先為短碼型網址（例如 `/downloads/s-<short_id>`）
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 5.3a Telegram generic document 完成訊息
- [ ] `pptx/pdf/docx/xlsx/zip` 完成訊息預設提供 **24h 短下載連結**
- [ ] 不得只有原生附件而沒有短下載連結
- [ ] 訊息內不得出現 `...` / `…` 截斷 token
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 5.3b email generic document 完成訊息
- [ ] email 內對 `pptx/pdf/docx/xlsx/zip` 預設提供 **24h 短下載連結**
- [ ] 不得只靠附件，避免 24h 時效規則失效
- [ ] 信內連結使用正式網域且可點開
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 5.4 索引未命中 fallback
```bash
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py search <query>
python3 ~/.hermes/scripts/shared_drive_chat_workflow.py search <query> --scope <path>
```
- [ ] 索引未命中時會要求更明確位置 / 範圍
- [ ] `--scope` 可做實地搜尋
- [ ] 實地搜尋候選可用 `--paths` 交付
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 六、敏感與交付規則

### 6.1 敏感檔
- [ ] 含個資 / 財務資料時自動加密 zip
- [ ] `password_channel` 正確
- [ ] 不會把敏感檔裸送
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 6.2 一般檔
- [ ] 單一非敏感檔可直接原檔交付
- [ ] 不會無故強制加密
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 6.3 下載驗證
- [ ] 驗證以 **GET** 為準
- [ ] 不把 `HEAD` / `urllib` / Cloudflare 1010 誤判成最終失敗
- [ ] 下載連結網域正確
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 七、維護與清理

### 7.1 cleanup
```bash
python3 ~/.hermes/scripts/shared_drive_cleanup.py
```
- [ ] 可清理過期 bundle / staging
- [ ] 不會誤刪未過期項目
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

### 7.2 cron / watchdog
- [ ] `shared-drive-index-v2-daily` 存在
- [ ] 正常時靜默
- [ ] 異常時才告警
- 結果：`PASS / FAIL / PARTIAL / NOT RUN`
- 備註：

---

## 八、若失敗，先定位到哪一層
- [ ] 掛載 / 路徑層
- [ ] 索引器 queue / cycle 層
- [ ] 查詢 / FTS 層
- [ ] workflow / reply formatting 層
- [ ] bundle / managed download 層
- [ ] cleanup / cron 層

### 對應要翻的文件
- [ ] `shared-drive-index-v2-maintenance.md`
- [ ] `shared-drive-file-access-validation-matrix.md`
- [ ] `shared-drive-file-access-reply-formats.md`
- [ ] `README.md`

---

## 九、最終結論
- 狀態：`PASS / FAIL / PARTIAL`
- blocker：
- 需追修：
- 是否可交付 / 上線：`可 / 不可 / 有條件`

---

## 十、可直接貼回報版
```md
shared drive v2 驗收結果：
- 狀態：
- 版本/變更：
- 快速健康檢查：
- py_compile：
- index v2 smoke：
- workflow search/children/bundle：
- 索引未命中 fallback：
- 敏感加密 / 下載驗證：
- cleanup / cron：
- blocker：
- 需追修：
- 是否可交付 / 上線：
```