From d9d8f03fba99795674fb55c671e8fbc1e28b29d9 Mon Sep 17 00:00:00 2001 From: jim800121chen Date: Fri, 1 May 2026 11:22:57 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20visionA=20Cloud=20monorepo=20=E6=A0=B9?= =?UTF-8?q?=E7=9B=AE=E9=8C=84=E8=A8=AD=E5=AE=9A=EF=BC=88Makefile=20+=20REA?= =?UTF-8?q?DME=20+=20.gitignore=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- .gitignore | 11 ++++++ Makefile | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 60 +++++++++++++++++++++++++---- 3 files changed, 174 insertions(+), 7 deletions(-) create mode 100644 Makefile diff --git a/.gitignore b/.gitignore index aff6b44..5623b76 100644 --- 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/ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1d1fd09 --- /dev/null +++ b/Makefile @@ -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）" diff --git a/README.md b/README.md index 7d7f929..b9bd48f 100644 --- 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（內部使用）