# FR-073 檢測 Agent 安裝形態比照主產品——固定系統路徑＋升級沿用（需求草稿）

- **日期**：2026-09-03（user 於 FR-072 錄影片④實測 agent 包 0.2.31 時提出）
- **狀態**：Phase 0 白話需求；design.md 由分析棒產出（方案對照）
- **鐵證**：CM-1533 出 0.2.32 換版時實際踩到——新目錄首裝＝新 compose project，舊容器佔固定 container_name 導致新版建不出，installer fallback 把失敗讀成成功；新 volume 空 → 憑證消失 → 雲端 409 拒新註冊。runner 手動搬憑證救回。

## 現況（0.2.31，190 實查）
- 客戶解 tar.gz 到家目錄，在解壓目錄內 `sudo ./install.sh`
- **解壓目錄＝安裝目錄**：compose、.env（token＋儲存憑證，600）、certs-in/、content/、factory/、install-*.log 全在裡面；`/usr/local/bin/guidant-agent-compose` 指回該目錄
- 完成畫面要特別印「🔴 請勿刪除」——設計缺陷的訊號
- 對照主產品：`/srv/guidant-ai`（資料）＋`/etc/guidant-ai/install.conf`（設定）＋`/usr/local/bin/guidant`（CLI），解壓目錄用完可刪

## 問題
1. 客戶直覺「解壓目錄＝暫存」，裝完順手刪 → compose/.env/憑證/profile 全沒，CLI 失效
2. 家目錄屬個別使用者：帳號停用/家目錄清理/權限變更都波及服務
3. 升級路徑不清：新版解到另一目錄，舊 .env/憑證怎麼接手？（prev_* 沿用邏輯依賴「舊目錄還在」）；且 CM-1533 證明「新目錄首裝」會撞固定 container_name 靜默失敗

## 期望（user）
- 安裝目錄固定系統路徑（`/srv/guidant-agent` 或 `/opt/guidant-agent`）、設定 `/etc/guidant-agent/`、CLI 指固定路徑
- install.sh 從解壓目錄搬/複製需要的檔，解壓目錄與 tar.gz 用完可刪
- 升級＝解新包 → install.sh 偵測既有安裝 → 沿用 .env/憑證/volume → 換 image
- uninstall 對應調整；FR-072 `reset-190.sh` 探測/清理路徑同步（已預留 `/etc/guidant-agent*` `/opt/guidant-agent` `/var/lib/guidant-agent` `/home/*/guidant-agent-compose-*`）
- 相容：舊形態已裝客戶要能被新 install.sh 偵測並遷移

## 分析棒要產出（design.md）
- 方案選項：目錄落點（/srv vs /opt）、搬遷 vs 就地、升級/遷移策略（含 CM-1533 的 container_name 撞名與 volume 接手）
- 影響範圍：agent 包打包腳本（源碼在 evidence-agent repo `deploy/`；BE repo grep `guidant-agent-compose`）、BE repo
- 文件影響：`docs/user-manual/agent/03-install.md`、`07-upgrade.md`、`onprem/10-optional-features.md §10.5`、FR-072 影片④
- 順帶：CM-1533 runner 建議的兩條——installer ⑥ fallback 補「容器 image tag == 本次要裝 tag」判定；換版正規路徑該是 `upgrade` 子命令而非新目錄首裝（文件是否引導到位）

## 座標
- agent 源碼：`~/Projects/Billows/Audit-Manager/evidence-agent/deploy/`（install.sh／docker-compose.yml／README）
- 190 現有 0.2.32 安裝可實查（`ssh guidantai@192.168.50.190`，唯讀）；0.2.31 舊目錄同在
- 主產品 installer 範本：BE `scripts/installer/install.sh`（資料目錄/etc/CLI 三分離＋沿用模式＋upgrade）