# M1-1 Review Report — repo 骨架初始化

**審查者**：Reviewer Agent
**審查時間**：2026-04-10
**審查範圍**：M1-1 產出（`.gitignore` / `Makefile` / `README.md` / 目錄骨架 / `.gitkeep`）
**參考文件**：
- `.autoflow/04-architecture/architecture-overview.md` §4.1
- `.autoflow/04-architecture/build-pipeline.md` §1、§2、§3
- `.autoflow/progress.md`（第三輪 Q-D 決策：vendor/ 不進 git）

---

## 結論：✅ 通過（含 3 項 🟢 建議，不阻斷 M1-2）

整體品質良好，目錄結構、.gitignore 的 vendor/ 排除策略、Makefile target 覆蓋度、README 平台版本標註都符合規格。沒有誤建 `go.mod` / `package.json` / `wails.json`，也沒有 `git init`。以下列出 3 項建議項目，可在 M1-2 前順手補上，或延到後續任務處理。

---

## 檢查清單

### 1. 目錄結構對齊 architecture-overview.md §4.1
- [x] `server/` 存在（含 `.gitkeep`） — M1-2 會複製 edge-ai-platform 的 Go 後端
- [x] `frontend/` 存在（含 `.gitkeep`） — M1-4 會複製 Next.js 業務前端
- [x] `visiona-local/` 存在（含 `.gitkeep`） — M1-9 會從 installer/ 複製 Wails shell
- [x] `payload/` 存在（含 `.gitkeep`）
- [x] `vendor/` 存在（含 `.gitkeep`） — 雖 architecture-overview §4.1 原圖沒畫出 top-level vendor/，但 build-pipeline.md §2 明確定義 `/Users/jimchen/visionA/local-tool/vendor/` 為依賴快取根目錄，建立是正確的
- [x] `dist/` 存在 — 用於最終發行物
- [x] `scripts/` 存在（含 `.gitkeep`） — build-pipeline.md §3.1 有 `scripts/vendor-sync.sh`、§1 `installer-linux` 有 `scripts/build-appimage.sh`，合理
- [x] `Makefile` 與 `README.md` 在 repo root

### 2. .gitignore 正確性（對照 build-pipeline.md §2.4）
- [x] `/vendor/**` 被排除（R4-Q-D 決策 D2：vendor 不進 git）
- [x] `!/vendor/.gitkeep` 白名單保留
- [x] `!/vendor/README.md` 白名單保留（但實際 README.md 尚未建立 — 見 🟢-1）
- [x] `/dist/` 排除
- [x] `/visiona-local/build/` 排除（Wails build 輸出）
- [x] `/visiona-local/payload/` 排除（build 暫存），`!/visiona-local/payload/.gitkeep` 白名單
- [x] `/payload/*.tar.gz`、`/payload/*.zip` 排除
- [x] Go 常見忽略齊全（`*.exe` / `*.dylib` / `*.so` / `*.test` / `go.work.sum`）
- [x] Node/Next.js 常見忽略齊全（`node_modules/` / `.next/` / `out/` / `*.tsbuildinfo` / `.pnpm-store/`）
- [x] Python venv、cache 齊全
- [x] OS 忽略齊全（`.DS_Store` / `Thumbs.db` / `desktop.ini` / `._*`）
- [x] Editor（`.vscode/` / `.idea/` / `*.swp`）
- [x] Secrets（`.env*` / `*.pem` / `*.key`）
- [x] 保留既有的 `.claude/` 與 `.autoflow/.backups/` 規則

### 3. Makefile target 命名對齊 build-pipeline.md §1
| build-pipeline.md 規格 | M1-1 實作 | 狀態 |
|---|---|---|
| `help` | `help` | ✅ |
| `dev` / `dev-mock` | `dev` / `dev-mock` | ✅ |
| `build-server` | `build-server`（+ alias `server`） | ✅ |
| `build-frontend` | `build-frontend`（+ alias `frontend`） | ✅ |
| `build-embed` | `build-embed` | ✅ |
| `payload` / `payload-macos/windows/linux` | 同名 | ✅ |
| `installer-macos` | **拆成 `wails-macos` + `dmg`** | ⚠️ 見下 |
| `installer-windows` | **拆成 `wails-windows` + `exe`** | ⚠️ 見下 |
| `installer-linux` | **拆成 `wails-linux` + `appimage`** | ⚠️ 見下 |
| `vendor-sync` | `vendor-sync`（新增，build-pipeline.md §3.1 有腳本） | ✅ |
| `test` / `lint` / `fmt` / `clean` | 同名 | ✅ |

**命名差異說明：** Backend 把 `installer-{os}` 拆成兩段（`wails-{os}` 負責 wails build、`dmg`/`exe`/`appimage` 負責打包成發行檔）。**這個拆分可接受**，理由：
1. 單一職責更清晰，debug 時可只跑 wails build 不打包
2. CI 可以分開 cache wails build 產物
3. 未來要換打包工具（例如 dmgbuild → create-dmg）只影響後半段
4. 可以加一個 `installer-macos: wails-macos dmg` 的聚合 target 保持對 spec 的向下相容（見 🟢-2）

### 4. README.md 平台版本標註
- [x] macOS 14 (Sonoma) / 15 (Sequoia)，x86_64（Apple Silicon 走 Rosetta 2）✅
- [x] Windows 10 / 11，x86_64 ✅
- [x] Ubuntu 22.04 / 24.04，x86_64 ✅
- [x] 明確標註「不支援 ARM native（使用者決策 Q4）」
- [x] 有目錄結構說明、文件索引、狀態（M1 開發中）
- [x] 開發者快速開始有提醒「M1-1 所有 target 都是 placeholder，不會真的 build」，避免誤解

### 5. 禁區檢查
- [x] 沒有誤建 `go.mod`（root / server/ 都沒有） — M1-2、M1-3 會處理
- [x] 沒有誤建 `package.json`（frontend/） — M1-4 會處理
- [x] 沒有誤建 `wails.json`（visiona-local/） — M1-9 會處理
- [x] 沒有 `.git/` 目錄 — 未執行 `git init`，正確
- [x] 沒有 `go.work` — architecture-overview §4.1 有列出，但屬 M1-3 範圍，M1-1 跳過是對的

---

## 問題列表

### 🔴 阻斷
（無）

### 🟡 需修
（無）

### 🟢 建議（不阻斷 M1-2，可順手補）

#### 🟢-1：建立 `vendor/README.md` 說明依賴取得方式
`.gitignore` 已經把 `!/vendor/README.md` 列為白名單，但實際檔案尚未建立。建議補一份最小版本，說明：
- vendor/ 的用途（離線依賴快取）
- 為什麼不進 git（R4-Q-D 決策，避免 binary bloat）
- 如何取得（`make vendor-sync`）
- 子目錄結構（`python/` / `wheels/` / `ffmpeg/` / `yt-dlp/` / `drivers/`）

這樣新開發者 clone 之後看到空的 vendor/ 不會疑惑。

**優先級：** 低，可在 M1-2 前順手加，或延到 M3（首次真的用到 vendor/ 時）再補。

#### 🟢-2：加一個 `installer-{os}` 聚合 target 保持向下相容
為了跟 build-pipeline.md §1 原本的命名一致，建議在 Makefile 加：

```makefile
installer: installer-$(OS)
installer-macos: wails-macos dmg
installer-windows: wails-windows exe
installer-linux: wails-linux appimage
```

這樣 build-pipeline.md 原本提到的 `make installer-macos` 依然能用，又保留 Backend 拆分後的細粒度 target。**目前 M1-1 先不做也可以**，M1-12（dmg 完成時）再補即可。

**優先級：** 低，可延到 M1-12。

#### 🟢-3：`dist/` 目錄沒有 `.gitkeep`
目前 `dist/` 是空目錄，git 不會追蹤空目錄，下次 clone 後 `dist/` 會消失，雖然 Makefile 的 `build-server` 會 `mkdir -p $(DIST)`，但建議補一個 `.gitkeep` 保持一致性（其他五個目錄都有）。注意 `.gitignore` 的 `/dist/` 規則會讓 `.gitkeep` 也被忽略，需要改成：

```
/dist/*
!/dist/.gitkeep
```

或乾脆不保留空 `dist/` 目錄，改在第一次 build 時才建立（Makefile `clean` 已經會 `mkdir -p $(DIST)`，其實不需要在 repo 中預留目錄）。

**建議：** 採後者，**刪掉目前空的 `dist/` 目錄**，由 Makefile 負責建立即可，`.gitignore` 維持 `/dist/` 不變。這樣更乾淨。

**優先級：** 低。

---

## 通過後可以進入 M1-2 嗎？

**可以，立刻進入 M1-2（複製 server core from edge-ai-platform）。**

M1-1 的品質已達標，3 項建議都是錦上添花，不影響後續任務：
- 🟢-1（vendor/README.md）可延到 M3
- 🟢-2（installer 聚合 target）可延到 M1-12
- 🟢-3（dist/ 空目錄）可隨時順手處理

Orchestrator 可直接呼叫 Backend Agent 開始 M1-2。