jim800121chen
c54f16fca0
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
Wails IPC raise endpoint, stale process cleanup
.autoflow/: full PRD / Design Spec / Architecture / Testing docs
(4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
146 lines
7.2 KiB
Markdown
146 lines
7.2 KiB
Markdown
# 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。
|