jim800121chen
4d0b870480
把 visionA-backend 6 個 in-memory store 接到資料庫持久化，範圍=完整 （PG 全接 + session 接 Redis + 交易韌性）。interface / handler 不動， 只加 DB 實作 + 換 wiring，config 未設 DB 時保留 in-memory fallback。 - 塊 0 基礎建設：pgx/v5 連線池 + DatabaseConfig/RedisConfig + golang-migrate runner（embed）+ cmd/migrate + testcontainers 測試基礎建設 - 塊 1 model → Postgres：array 映射、upsert 保留 CreatedAt、faa_object_key、 三維 filter（owner/chip/source）、soft-delete partial index - 塊 2 device → Postgres：partial unique（已刪 serial 可重註冊）、雙狀態欄位 - 塊 3 token → Postgres：pairing_tokens + session_tokens 分表、token_hash 當 PK - 塊 4 userSession → Redis：idle + absolute 雙 TTL 取代 cleanup goroutine （tunnel session 維持 in-memory，yamux handle 不可序列化） - 塊 5 交易/韌性：WithTx helper + 刪 device cascade 撤銷 token（同 tx 原子） + /healthz ping PG/Redis（fail-fast 503）+ pgx error 統一映射（不洩漏 raw error） 降級策略（fail-fast）：PG 掉 → 持久資料 API 回 503；Redis 掉 → session 失敗 不自動 fallback in-memory（避免多機 session 不同步）。 DB：PostgreSQL 14.23（gen_random_uuid 內建、無 citext → email 用 lower() unique index）。每塊經 Reviewer 審查 + 真 PG/Redis testcontainers 全量 dbtest 綠燈， in-memory fallback 未受影響。 docs: 同步更新 database.md（schema/config/migration 清單）+ api-spec.md （409/503 錯誤碼、/healthz 新行為、device unpair cascade）。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
433 lines
18 KiB
Markdown
433 lines
18 KiB
Markdown
# visionA-backend
|
||
|
||
> visionA Cloud 的後端服務。由 **`api-server`**（無狀態 REST/WS API）與 **`remote-proxy`**（有狀態 tunnel server）兩個 binary 組成。
|
||
|
||
---
|
||
|
||
## ⚠️ Phase 0 雛形警告
|
||
|
||
**這是雛形（prototype）版本，不是生產交付物。** 主要限制：
|
||
|
||
- 單一 user（永遠回 `demo-user`，無真正認證）
|
||
- 所有狀態 in-memory（重啟即消失，無 DB / Redis）
|
||
- Storage 走 LocalFS（無 S3）
|
||
- WebSocket proxy 尚未實作（所有 `/ws/*` 皆回 501）
|
||
- 單一 instance（無水平擴展）
|
||
|
||
完整限制見下方 [雛形範圍與限制](#雛形範圍與限制)。
|
||
|
||
---
|
||
|
||
## 架構總覽
|
||
|
||
```
|
||
┌─────────────────────┐
|
||
│ Browser / curl │
|
||
└──────────┬──────────┘
|
||
│ REST / WS (3721)
|
||
▼
|
||
┌──────────────────────────────┐
|
||
│ api-server │
|
||
│ (cmd/api-server) │
|
||
│ │
|
||
│ - REST + WS handler │
|
||
│ - Auth middleware（static）│
|
||
│ - ProxyClientStore │
|
||
│ （查詢 session） │
|
||
│ - Forwarder │
|
||
│ （轉發 HTTP 到 tunnel） │
|
||
│ - LocalFS storage (/storage)│
|
||
│ 無狀態，可水平擴展 │
|
||
└──────────┬───────────────────┘
|
||
│ internal HTTP (3801)
|
||
▼
|
||
┌──────────────────────────────┐
|
||
│ remote-proxy │
|
||
│ (cmd/remote-proxy) │
|
||
│ │
|
||
│ - Tunnel server (ws://3800) │
|
||
│ - yamux session store │
|
||
│ - /internal/forward/raw │
|
||
│ - /internal/session/:token │
|
||
│ │
|
||
│ ⚠️ 有狀態（單 instance） │
|
||
└──────────┬───────────────────┘
|
||
│ WebSocket + yamux (3800)
|
||
▼
|
||
┌──────────────────────────────┐
|
||
│ Local Agent │
|
||
│ (在客戶端機器上跑) │
|
||
│ │
|
||
│ 目前 demo 用 POC 的 │
|
||
│ edge-ai-server 當 client │
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
詳細設計見：
|
||
- [`.autoflow/04-architecture/design-doc.md`](../.autoflow/04-architecture/design-doc.md)（§7 部署）
|
||
- [`.autoflow/04-architecture/TDD.md`](../.autoflow/04-architecture/TDD.md)
|
||
- [`.autoflow/04-architecture/api/api-spec.md`](../.autoflow/04-architecture/api/api-spec.md)（前端 REST API）
|
||
- [`.autoflow/04-architecture/api/api-internal.md`](../.autoflow/04-architecture/api/api-internal.md)（api-server ↔ remote-proxy）
|
||
|
||
---
|
||
|
||
## 技術堆疊
|
||
|
||
| 層級 | 技術 | 備註 |
|
||
|------|------|------|
|
||
| 語言 | Go 1.26 | `go.mod` 鎖定 |
|
||
| HTTP framework | [Gin](https://github.com/gin-gonic/gin) + `gin-contrib/cors` | B4 導入 |
|
||
| Tunnel 傳輸 | `gorilla/websocket` + `hashicorp/yamux` | 沿用 POC `edge-ai-platform` |
|
||
| Logging | `log/slog`（stdlib） | JSON handler，結構化輸出 |
|
||
| ID 生成 | `google/uuid` | request-id / demo seed |
|
||
| 單元測試 | `stretchr/testify` | B2 導入 |
|
||
| 配置 | 12-Factor App | 全走 env，不寫死 |
|
||
|
||
---
|
||
|
||
## 快速啟動（10 分鐘起步）
|
||
|
||
### 前置
|
||
|
||
- Go 1.26+（本機 run）或 Docker 27+（容器 run）
|
||
- macOS / Linux（Windows 未測試）
|
||
|
||
### 方式 A：本機 `go run`（最快，適合開發）
|
||
|
||
```bash
|
||
cd visionA-backend
|
||
|
||
# 1) 一鍵跑 remote-proxy + api-server（任一 Ctrl+C 兩個都會停）
|
||
make dev
|
||
|
||
# 另開 terminal 驗證：
|
||
curl http://localhost:3721/healthz
|
||
# {"status":"ok"}
|
||
|
||
curl -X POST http://localhost:3721/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email":"demo@visionA.local","password":"any"}'
|
||
# {"success":true,"data":{"user":{"id":"demo-user",...},"access_token":"demo-access-token",...}}
|
||
```
|
||
|
||
### 方式 B：Docker Compose（接近生產拓撲）
|
||
|
||
```bash
|
||
cd visionA-backend
|
||
|
||
# 1) 複製環境變數範本
|
||
cp .env.example .env
|
||
# （視情況編輯 .env — 通常預設就能跑）
|
||
|
||
# 2) 建 image + 啟動
|
||
make docker-compose-up
|
||
|
||
# 3) 驗證
|
||
curl http://localhost:3721/healthz
|
||
curl -X POST http://localhost:3721/api/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"email":"demo@visionA.local","password":"any"}'
|
||
|
||
# 4) 跟 logs
|
||
make docker-compose-logs
|
||
|
||
# 5) 停
|
||
make docker-compose-down
|
||
```
|
||
|
||
**Ports：**
|
||
- `3721`：api-server REST + WS（對前端）
|
||
- `3800`：remote-proxy tunnel WS（對 local agent）
|
||
- `3801`：remote-proxy internal HTTP（compose 內部，不對外）
|
||
|
||
---
|
||
|
||
## 如何用 POC `edge-ai-server` 驗證 tunnel
|
||
|
||
雛形不包含 local agent（Q3 決策：local agent 模組 Phase 1 才做）。要驗證 tunnel 整條鏈路，用 POC `edge-ai-platform/edge-ai-server` 當 tunnel client。
|
||
|
||
### 步驟
|
||
|
||
```bash
|
||
# Terminal 1 — 起 visionA-backend
|
||
cd visionA-backend
|
||
make dev
|
||
# 或 docker compose up
|
||
|
||
# Terminal 2 — 申請 pairing token（雛形：POST 就會配發一個）
|
||
curl -X POST http://localhost:3721/api/pairing/token \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name":"demo"}'
|
||
# { "success": true, "data": { "token": "vAc_...", "expires_at": "..." } }
|
||
|
||
# Terminal 3 — POC edge-ai-server 當 tunnel client 接上來
|
||
cd /path/to/edge-ai-platform
|
||
./dist/edge-ai-server \
|
||
--relay-url=ws://localhost:3800/tunnel/connect \
|
||
--relay-token=vAc_<貼上上一步的 token>
|
||
|
||
# Terminal 2 — 驗證 tunnel 已連上
|
||
curl -H "Authorization: Bearer demo-access-token" \
|
||
http://localhost:3721/api/pairing/status
|
||
# { "success": true, "data": { "connected": true, ... } }
|
||
|
||
# 打到 local agent（會被 forward 過 tunnel）
|
||
curl -H "Authorization: Bearer demo-access-token" \
|
||
http://localhost:3721/api/devices/scan
|
||
```
|
||
|
||
### 或：用 B3 的 fake tunnel client 寫小 demo
|
||
|
||
若不想起 POC，`cmd/api-server/b5_integration_test.go` 裡的 `startFakeTunnelClient` 是現成的 60 行範例，直接複製到 `cmd/tunnel-demo/main.go` 就能跑。
|
||
|
||
---
|
||
|
||
## 目錄結構
|
||
|
||
```
|
||
visionA-backend/
|
||
├── cmd/
|
||
│ ├── api-server/ # REST/WS API server（無狀態）
|
||
│ │ ├── main.go
|
||
│ │ ├── seed.go # --seed-demo-data 用的示範資料
|
||
│ │ ├── integration_test.go # B4 端到端測試
|
||
│ │ └── b5_integration_test.go # B5 端到端測試（含 tunnel forward + model upload）
|
||
│ ├── migrate/ # 獨立 migration 工具（go run ./cmd/migrate up|down|version）
|
||
│ └── remote-proxy/ # tunnel server（有狀態，持有 session in-memory）
|
||
│ └── main.go
|
||
├── internal/
|
||
│ ├── api/ # API handlers + Gin router + middleware（B4 + B5）
|
||
│ ├── auth/ # AuthService / AuthProvider / PairingStore（雛形 Static + InMemory）
|
||
│ ├── session/ # Store / Handle / Forwarder / ProxyClient
|
||
│ ├── device/ # Device domain + InMemoryRepository
|
||
│ ├── model/ # Model domain + InMemoryRepository
|
||
│ ├── cluster/ # Cluster domain（POC 複製，dispatcher 留 TODO）
|
||
│ ├── relay/ # tunnel server + internal forward API（POC 改造）
|
||
│ ├── wsconn/ # WebSocket ↔ net.Conn adapter（POC 複製）
|
||
│ ├── converter/ # StubClient（Phase 2 才實作）
|
||
│ ├── storage/ # Store interface + LocalFSStore（HMAC presigned URL）
|
||
│ ├── config/ # Config + Load()（12-Factor；含 DatabaseConfig / RedisConfig）
|
||
│ ├── db/ # DB 接入塊 0：pgxpool 連線池 + migration runner（嵌入式）
|
||
│ │ └── testsupport/ # testcontainers 整合測試 helper + fixture factory（-tags=dbtest）
|
||
│ └── logger/ # slog JSON logger wrapper
|
||
├── migrations/ # golang-migrate SQL（NNNN_*.up/down.sql）+ embed.go
|
||
├── docker/
|
||
│ ├── Dockerfile.api-server # multi-stage，non-root，healthcheck
|
||
│ ├── Dockerfile.remote-proxy
|
||
│ └── docker-compose.yml
|
||
├── .env.example # 環境變數範本（commit）
|
||
├── .gitignore # 已排除 .env / bin/ / data/
|
||
├── Makefile # build / dev / test / docker-* 等 targets
|
||
├── go.mod / go.sum
|
||
└── README.md # 本檔
|
||
```
|
||
|
||
---
|
||
|
||
## API 端點摘要
|
||
|
||
完整規格見 [`.autoflow/04-architecture/api/api-spec.md`](../.autoflow/04-architecture/api/api-spec.md)。
|
||
|
||
| 群組 | 端點 | 說明 |
|
||
|------|------|------|
|
||
| System | `GET /healthz` | liveness/readiness（無需認證） |
|
||
| System | `GET /api/system/health` | tunnel / agent 連線狀態 |
|
||
| System | `GET /api/system/info` | 版本 + build 資訊 |
|
||
| Auth | `POST /api/auth/login` | 雛形永遠回 `demo-user` |
|
||
| Auth | `POST /api/auth/register` | 雛形 501 |
|
||
| Auth | `GET /api/auth/me` | 當前 user 資訊 |
|
||
| Pairing | `POST /api/pairing/token` | 申請 pairing token（vAc_ + 32 hex） |
|
||
| Pairing | `GET /api/pairing/status` | 目前 user 的 tunnel 狀態 |
|
||
| Pairing | `GET /api/pairing/tokens` | 列出已簽發的 token |
|
||
| Pairing | `DELETE /api/pairing/tokens/:id` | revoke token |
|
||
| Devices | `GET /api/devices` | 列出裝置 |
|
||
| Devices | `POST /api/devices/scan` | 觸發 local agent 掃 USB（透過 tunnel） |
|
||
| Devices | `DELETE /api/devices/:id` | unpair（同時關 tunnel） |
|
||
| Models | `POST /api/models/init` | 兩階段上傳 step 1（拿 presigned PUT URL） |
|
||
| Models | `PUT /storage/:signed` | 實際上傳檔案（HMAC 驗簽） |
|
||
| Models | `POST /api/models/:id/finalize` | 兩階段上傳 step 2（marked ready） |
|
||
| Models | `GET /api/models` | 列出模型 |
|
||
| Clusters | `GET /api/clusters` | 列出 cluster（骨架） |
|
||
| Storage | `GET /storage/:signed` | presigned download |
|
||
| Camera / Inference | `/api/cameras/*`、`/api/inference/*` | proxy 到 local agent |
|
||
| WebSocket | `/ws/*` | **雛形 501**（B7 之後補） |
|
||
|
||
### 錯誤格式（統一）
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "TUNNEL_DISCONNECTED",
|
||
"message": "local agent 未連線或 tunnel 斷開",
|
||
"request_id": "req_abc123"
|
||
}
|
||
}
|
||
```
|
||
|
||
錯誤碼清單見 [`internal/api/errors.go`](internal/api/errors.go)。
|
||
|
||
---
|
||
|
||
## 環境變數
|
||
|
||
詳見 [`.env.example`](.env.example)。常用：
|
||
|
||
| 變數 | 預設 | 說明 |
|
||
|------|------|------|
|
||
| `VISIONA_API_PORT` | `3721` | api-server listen port |
|
||
| `VISIONA_TUNNEL_PORT` | `3800` | remote-proxy 對 local agent 的 WS port |
|
||
| `VISIONA_PROXY_INTERNAL_PORT` | `3801` | remote-proxy 對 api-server 的內部 HTTP port |
|
||
| `VISIONA_PROXY_INTERNAL_URL` | `http://localhost:3801` | api-server 連 remote-proxy 用（docker compose 會覆為 `http://remote-proxy:3801`） |
|
||
| `VISIONA_SEED_DEMO_DATA` | `false` | 啟動時塞示範資料（device + model + pairing） |
|
||
| `VISIONA_STORAGE_SIGNING_SECRET` | `dev-signing-secret-...` | presigned URL HMAC secret（**生產必改**） |
|
||
| `VISIONA_STATIC_USER_ID` | `demo-user` | 雛形 static auth 的 user id |
|
||
| `VISIONA_MODEL_MAX_SIZE_MB` | `100` | 模型上傳大小上限 |
|
||
| `VISIONA_CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | CORS 白名單（逗號分隔） |
|
||
| `VISIONA_LOG_LEVEL` | `info` | debug / info / warn / error |
|
||
| `VISIONA_DB_HOST` / `_USER` / `_NAME` | （空） | PostgreSQL 連線；三者全非空才啟用（否則維持 in-memory） |
|
||
| `VISIONA_DB_AUTO_MIGRATE` | `true` | 啟動時自動跑 migrate up |
|
||
|
||
---
|
||
|
||
## 資料庫（DB 接入塊 0）
|
||
|
||
> 對齊 [`docs/autoflow/04-architecture/database.md`](../docs/autoflow/04-architecture/database.md) §5、§5.5。
|
||
|
||
塊 0 = **DB 基礎建設**：PostgreSQL 連線池（pgxpool）+ migration runner（golang-migrate，
|
||
嵌入式 SQL）+ testcontainers 整合測試骨架。
|
||
|
||
**啟用模式**：`VISIONA_DB_HOST` / `VISIONA_DB_USER` / `VISIONA_DB_NAME` 三者全非空 → 建池 +
|
||
自動 migrate；任一缺 → **不建池，所有 repository 維持 in-memory**（local dev fallback，雛形行為不變）。
|
||
|
||
> ⚠️ **塊 0 範圍**：即使 DB 啟用，目前 model / device / token repository **仍是 in-memory**。
|
||
> 建池只為驗證基礎建設可用、並讓 schema 先就位。把 repository 切到 Postgres 是塊 1–3。
|
||
|
||
```bash
|
||
# 設好 VISIONA_DB_* 後，手動跑 migration（或交給 api-server 啟動時 auto-migrate）
|
||
make migrate-up
|
||
make migrate-version # 顯示目前 schema 版本
|
||
|
||
# DB 整合測試（testcontainers，需本機 / CI 有 Docker daemon）
|
||
make test-db # = go test -tags=dbtest ./internal/db/...
|
||
```
|
||
|
||
migration 檔在 [`migrations/`](migrations/)（`NNNN_description.up.sql` / `.down.sql`），
|
||
透過 `migrations/embed.go` 的 `//go:embed` 嵌入 binary，部署不需另複製。
|
||
第一份 `0001_create_users_models` 建 `users` + `models`（對齊 database.md §5.1）。
|
||
|
||
---
|
||
|
||
## 測試
|
||
|
||
```bash
|
||
# 所有單元測試 + integration test + race detector（預設 tags，不需 Docker）
|
||
make test-race
|
||
|
||
# DB 整合測試（testcontainers，需 Docker daemon）
|
||
make test-db
|
||
|
||
# 僅 go vet / gofmt check
|
||
make lint
|
||
|
||
# 詳細輸出
|
||
make test
|
||
```
|
||
|
||
覆蓋面：
|
||
- 單元測試：`internal/{auth,session,device,model,config,storage,api,relay,wsconn,logger,converter,db}`
|
||
- `internal/db`：DSN 組裝 / SafeTarget 遮蔽 / Config.Enabled（純函式，預設 tags 即跑）
|
||
- Integration：
|
||
- `cmd/api-server/integration_test.go`（B4：api-server → remote-proxy → fake tunnel）
|
||
- `cmd/api-server/b5_integration_test.go`（B5：完整端到端 — login / scan / model upload / tunnel disconnect）
|
||
- `internal/db/db_integration_test.go`（DB 接入塊 0：pool ping / migrate 冪等 / up-down-up / schema 形狀 / fail-fast；`-tags=dbtest`，需 Docker）
|
||
|
||
---
|
||
|
||
## 開發者指南
|
||
|
||
| 我想做的事 | 看哪裡 |
|
||
|-----------|--------|
|
||
| 新增一個 REST endpoint | `internal/api/` 找類似的 handler 複製；proxy 類用 `newProxyHandler` |
|
||
| 改動 API 規格 | 先改 `.autoflow/04-architecture/api/api-spec.md` 再改 code |
|
||
| 加環境變數 | `internal/config/config.go` + `load.go` + `.env.example` + 本 README |
|
||
| 改 tunnel 協定 | `.autoflow/04-architecture/tunnel.md` + `internal/relay/` + `internal/session/forwarder.go` |
|
||
| 追蹤某個 Review 問題 | `.autoflow/05-implementation/review/` |
|
||
|
||
---
|
||
|
||
## Known Issues
|
||
|
||
### Tunnel client 不在本 repo
|
||
|
||
visionA-backend 只實作 tunnel **server** 端（`internal/relay/` + `internal/wsconn/`）；tunnel **client** 由 visionA Agent 實作（從 POC `edge-ai-platform/server/internal/tunnel/client.go` 複製）。本 repo 過去曾保留一份 `internal/tunnel/` 副本，但因從未被 import 且會造成「兩處需要同步修補」的維護負擔，已於 2026-04-21 刪除（決策見 [`.autoflow/04-architecture/adr/adr-008-tunnel-client-reuse.md`](../.autoflow/04-architecture/adr/adr-008-tunnel-client-reuse.md)）。
|
||
|
||
POC `client.go` 的 `backoff()` 有單位 mix bug（`attempt >= 1` 時永遠回 30 秒），visionA Agent 建立後需在自己的 repo 修復；本 repo 不再追蹤此 issue。
|
||
|
||
### WebSocket proxy 未實作
|
||
|
||
所有 `/ws/*` endpoint 目前回 `501 Not Implemented`。原因：`Forwarder.ForwardWebSocket` 需要 `http.Hijacker` + 雙向 `io.Copy` 架構，B7 範圍外。
|
||
|
||
前端呼叫 `/ws/*` 時會收到 JSON body `{ "success": false, "error": { "code": "NOT_IMPLEMENTED", ... } }`，瀏覽器 WebSocket 會 fail upgrade。
|
||
|
||
---
|
||
|
||
## 雛形範圍與限制
|
||
|
||
### 是什麼
|
||
|
||
- 雙 binary 架構驗證（api-server 無狀態 + remote-proxy in-memory session）
|
||
- REST + Tunnel 完整鏈路：browser → api-server → internal HTTP → remote-proxy → yamux → local agent
|
||
- 兩階段模型上傳（init → PUT presigned → finalize）
|
||
- Docker image + docker-compose 可跑
|
||
|
||
### 不是什麼
|
||
|
||
| 項目 | 雛形 | Phase 1+ |
|
||
|------|------|---------|
|
||
| Auth | static，一律 `demo-user` | OIDC / Clerk |
|
||
| 資料庫 | 無（全 in-memory） | PostgreSQL |
|
||
| Session 存放 | `remote-proxy` 進程內 | Redis（支援水平擴展） |
|
||
| 檔案儲存 | LocalFS（`./data/storage`） | S3 |
|
||
| 支援多 user | ❌ | ✅ |
|
||
| Rate limiting | ❌ | ✅ |
|
||
| Audit log | ❌ | ✅ |
|
||
| WebSocket proxy | 501 stub | ✅ |
|
||
| TLS | ❌（http only） | ✅（ALB / NLB termination） |
|
||
| 水平擴展 | ❌ | ✅（api-server 可；remote-proxy 需加 shared session store） |
|
||
|
||
### 重啟即消失
|
||
|
||
`make docker-compose-down` 或 restart 後：
|
||
- 所有 pairing token 消失
|
||
- 所有 device / model 紀錄消失（除非 `VISIONA_SEED_DEMO_DATA=true`）
|
||
- Storage 檔案保留（`./data/storage` 被 mount 為 volume）
|
||
|
||
---
|
||
|
||
## Phase 1 路線圖
|
||
|
||
- [ ] 真 auth（OIDC via Clerk / Auth0）
|
||
- [ ] PostgreSQL + Redis（參考 `.autoflow/04-architecture/database.md`）
|
||
- [ ] S3 / R2 storage backend（替換 LocalFSStore）
|
||
- [ ] WebSocket proxy（hijack + 雙向 io.Copy）
|
||
- [ ] 多裝置 / 多 cluster 支援
|
||
- [ ] Rate limiting + audit log
|
||
- [ ] K8s / ECS deployment（參考 `.autoflow/04-architecture/build-deploy.md` §7）
|
||
- [ ] CI/CD pipeline（GitHub Actions）
|
||
- [ ] Local agent 模組（獨立 binary，取代 POC edge-ai-server 當 tunnel client）
|
||
|
||
---
|
||
|
||
## 目前實作進度
|
||
|
||
- [x] **B1** 專案初始化（go.mod、目錄骨架、Makefile、.gitignore）
|
||
- [x] **B2** 共用 `internal/` 模組（core interface + in-memory 實作 + 單元測試）
|
||
- [x] **B3** `cmd/remote-proxy` + relay / tunnel / wsconn / cluster
|
||
- [x] **B4** `cmd/api-server` + `internal/api` 骨架 + Forwarder + ProxyClient
|
||
- [x] **B5** API handlers 雛形（20+ endpoint 實作、兩階段上傳、tunnel forward）
|
||
- [x] **B6** Docker image + docker-compose（multi-stage + non-root + healthcheck）
|
||
- [x] **B7** README + `.env.example` + Makefile 補完
|
||
|
||
完整任務紀錄見 [`.autoflow/progress.md`](../.autoflow/progress.md)。
|