chore: visionA Cloud monorepo 根目錄設定（Makefile + README + .gitignore）

- Makefile：top-level convenience targets（呼叫各子專案的 Makefile） - README.md：擴充為 monorepo 索引（local-tool / visionA-backend / visionA-frontend / local-agent 各組件說明 + dev-with-mc / stage 部署 quickstart） - .gitignore： - .env.dev / .env.dev.generated / .env.stage 排除（dev 與 stage 環境檔不進 git） - .autoflow/ 整包 ignore（個人/per-branch 工作目錄；progress.md 與 review 報告皆 ignored；共享產品文件已搬到 docs/ 進 git） - graphify-out/ 排除 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-01 11:22:57 +08:00 · 2026-05-01 11:22:57 +08:00 · d9d8f03fba
commit d9d8f03fba
parent eb66a7287a
3 changed files with 174 additions and 7 deletions
--- a/.gitignore
+++ b/.gitignore
@ -48,6 +48,17 @@ local-tool/visiona-local/payload/
 .env
 .env.local
 .env.*.local
+# dev 環境（docker-compose.dev.yml）
+.env.dev
+.env.dev.generated
+# stage 環境（docker-compose.stage.yml）— 不進 git，由人工放到 stage host
+.env.stage

 # Claude Code 本地 session / memory，不入 git
 .claude/
+
+# Autoflow Agent（由 autoflow-agent init 自動產生）
+# 整包 ignore（progress.md / review 報告 / 個人筆記皆 per-branch）
+# 共享文件（PRD / 設計 / 架構 / 交付）走 docs/ 進 git
+.autoflow/
+graphify-out/
--- a/110
+++ b/110
@ -0,0 +1,110 @@
+# visionA monorepo dev convenience Makefile
+#
+# 對應文件：
+#   - docs/DEV-SETUP.md（完整 dev 環境流程，含 OAuth client 註冊）
+#   - docker-compose.dev.yml（dev all-in-one：postgres + member-center + visiona-backend）
+#   - .autoflow/04-architecture/oidc-tdd.md §12
+#
+# 子專案 Makefile（不在這裡 wrap，請進子目錄使用）：
+#   - visionA-backend/Makefile  — go build / docker-compose prod / 單元測試
+#   - local-agent/Makefile      — wails build（Agent 桌面端）
+#   - local-tool/               — 離線版桌面工具（獨立子專案）
+#
+# 設計原則：
+#   1. dev 環境用 docker compose 一鍵啟動 backend + DB + Member Center（OIDC provider）
+#   2. frontend 仍用 host pnpm dev（HMR 體驗較好，不放 compose）
+#   3. dev-reset 是核選項，會清掉 DB volume，慎用
+#
+# ⚠️ 此 Makefile 僅供 dev 使用，production 走 visionA-backend/docker/docker-compose.yml + IaC。
+
+COMPOSE_FILE   := docker-compose.dev.yml
+COMPOSE        := docker compose -f $(COMPOSE_FILE)
+ENV_FILE       := .env.dev
+ENV_EXAMPLE    := .env.dev.example
+FRONTEND_DIR   := visionA-frontend
+
+.DEFAULT_GOAL := help
+.PHONY: help dev-up dev-down dev-logs dev-status dev-reset dev-rebuild \
+        frontend-dev backend-dev clean check-env
+
+# ---------------------------------------------------------------------------
+# Help
+# ---------------------------------------------------------------------------
+help:
+	@echo "visionA Dev Commands:"
+	@echo ""
+	@echo "  make dev-up         # 起 dev 環境（postgres + member-center + visiona-backend）"
+	@echo "  make dev-down       # 停 dev 環境（保留 DB volume）"
+	@echo "  make dev-reset      # 停 dev 環境並清掉 DB volume（從零重來，慎用）"
+	@echo "  make dev-rebuild    # 重 build images 並重啟（程式碼改動後用）"
+	@echo "  make dev-logs       # 跟蹤 dev 環境 logs（tail=50, follow）"
+	@echo "  make dev-status     # 看 dev 環境 service 狀態"
+	@echo ""
+	@echo "  make frontend-dev   # 起 frontend dev server（pnpm dev，host）"
+	@echo ""
+	@echo "  make clean          # 清掉所有 build artifact（不含 docker volumes）"
+	@echo ""
+	@echo "完整流程（含 OAuth client 手動註冊）見 docs/DEV-SETUP.md"
+
+# ---------------------------------------------------------------------------
+# dev environment（docker compose）
+# ---------------------------------------------------------------------------
+
+# 確保 .env.dev 存在；不存在則從範本複製並提示使用者編輯
+check-env:
+	@if [ ! -f $(ENV_FILE) ]; then \
+		echo ">>> 未找到 $(ENV_FILE)，從 $(ENV_EXAMPLE) 複製一份..."; \
+		cp $(ENV_EXAMPLE) $(ENV_FILE); \
+		echo ""; \
+		echo "    已建立 $(ENV_FILE)（預設 VISIONA_AUTH_TYPE=static，可立刻起來跑）"; \
+		echo "    要切到 OIDC 模式：請依 docs/DEV-SETUP.md §5 註冊 OAuth client，"; \
+		echo "    把 client_id/secret 填入 $(ENV_FILE)，並改 VISIONA_AUTH_TYPE=oidc 後重啟。"; \
+		echo ""; \
+	fi
+
+dev-up: check-env
+	$(COMPOSE) --env-file $(ENV_FILE) up -d
+	@echo ""
+	@echo ">>> 等 service 起動..."
+	@sleep 3
+	@$(COMPOSE) ps
+	@echo ""
+	@echo ">>> 啟動完成。下一步："
+	@echo "    1. 等所有 service healthy：watch -n 2 'docker compose -f $(COMPOSE_FILE) ps'"
+	@echo "    2. 起 frontend：             make frontend-dev"
+	@echo "    3. 開瀏覽器：                http://localhost:3000"
+	@echo "    （首次需手動註冊 OAuth client，見 docs/DEV-SETUP.md §5）"
+
+dev-down:
+	$(COMPOSE) down
+
+dev-reset:
+	@echo "⚠️  將清掉所有 dev DB volume（pgdata + api-storage），無法復原。"
+	@printf "確定？(y/N) "; read ans; if [ "$$ans" != "y" ] && [ "$$ans" != "Y" ]; then echo "取消"; exit 1; fi
+	$(COMPOSE) down -v
+	@echo "✓ Dev 環境已清掉（含 DB volume）"
+
+dev-rebuild: check-env
+	$(COMPOSE) --env-file $(ENV_FILE) up -d --build
+	@$(COMPOSE) ps
+
+dev-logs:
+	$(COMPOSE) logs -f --tail=50
+
+dev-status:
+	$(COMPOSE) ps
+
+# ---------------------------------------------------------------------------
+# frontend（host，不在 compose 內）
+# ---------------------------------------------------------------------------
+frontend-dev:
+	cd $(FRONTEND_DIR) && pnpm install && pnpm dev
+
+# ---------------------------------------------------------------------------
+# clean
+# ---------------------------------------------------------------------------
+clean:
+	-cd visionA-backend && $(MAKE) clean 2>/dev/null || true
+	-cd local-agent && $(MAKE) clean 2>/dev/null || true
+	-cd $(FRONTEND_DIR) && rm -rf .next out node_modules
+	@echo "✓ build artifact 已清除（docker volumes 不受影響，請另用 make dev-reset）"
--- a/README.md
+++ b/README.md
@ -1,15 +1,61 @@
 # visionA

-Innovedus visionA monorepo. Currently contains:
+Innovedus visionA monorepo — Edge AI 開發平台（離線版 + 雲端版）。

-## Subprojects
+## 開發環境快速啟動

-### `local-tool/`
-**visionA-local** — local-first edge AI desktop tool, derived from edge-ai-platform.
-Wails + Go + Next.js, packaged as macOS dmg / Windows exe / Linux AppImage.
+```bash
+make dev-up         # 起 backend + Member Center（OIDC）+ Postgres
+make frontend-dev   # 另開 terminal：起 frontend dev server（pnpm dev）
+# 開瀏覽器 http://localhost:3000
+```

-See [`local-tool/README.md`](./local-tool/README.md) for details.
+完整流程（含 OAuth client 手動註冊、port 對照、疑難排解）見 [`docs/DEV-SETUP.md`](./docs/DEV-SETUP.md)。
+其他 target：`make help`。
+
+## 子專案
+
+| 專案 | 角色 | 狀態 |
+|------|------|------|
+| [`local-tool/`](./local-tool/README.md) | **離線版** 桌面工具（Wails + Go + Next.js） | 穩定維護 |
+| [`visionA-frontend/`](./visionA-frontend/README.md) | 雲端版 web 前端（Next.js） | ✅ Phase 0 雛形 |
+| [`visionA-backend/`](./visionA-backend/README.md) | 雲端版後端（Go，雙 binary：api-server + remote-proxy） | ✅ Phase 0 雛形 |
+| [`local-agent/`](./local-agent/README.md) | **visionA Agent** — 雲端版 local 端代理（Wails + Go + Next.js） | ✅ Phase 0.5 雛形 |
+
+## 架構關係
+
+```
+離線模式（local-tool 單獨）
+  使用者瀏覽器 → localhost:3721 (local-tool server) → Kneron 裝置
+
+雲端模式（visionA 雲端版 + visionA Agent）
+  使用者瀏覽器 → visionA-frontend (CDN) → visionA-backend (api-server)
+                                                ↓ internal HTTP
+                                       visionA-backend (remote-proxy)
+                                                ↓ WebSocket + yamux tunnel
+                                       使用者電腦上的 visionA Agent
+                                                ↓ 本機 HTTP
+                                       Agent 的內部 server → Kneron 裝置
+```
+
+**兩種模式可在同一台電腦共存**（local-tool 和 visionA Agent 獨立安裝、不衝突）。
+
+## 產品線原則
+
+1. **local-tool 不動**，需要時 fork
+2. **雲端 vs 本機差異只在前端部署位置**
+3. **雲端 agent 的 server ≈ local-tool 的 server**（差別在沒本機操作 UI）
+4. **雲端 web UI 先抄 local-tool**，之後再加新功能
+
+## 文件
+
+完整產品文件見 [`.autoflow/`](./.autoflow/README.md)：
+
+- 產品需求：[`.autoflow/02-prd/PRD.md`](./.autoflow/02-prd/PRD.md)
+- 設計規格：[`.autoflow/03-design/design-spec.md`](./.autoflow/03-design/design-spec.md)
+- 架構總覽：[`.autoflow/04-architecture/design-doc.md`](./.autoflow/04-architecture/design-doc.md)
+- 交付總結：[`.autoflow/07-delivery/project-summary.md`](./.autoflow/07-delivery/project-summary.md)

 ## License

-TBD (internal use)
+TBD（內部使用）