Refresh documentation and supporting scripts

.github/workflows/GCE_DEPLOY.md

@@ -187,8 +187,9 @@ cd ~
 git clone https://github.com/YOUR_USERNAME/auto-refactor-agent.git
 cd auto-refactor-agent
 
-# 建立 .env.prod 檔案
-cat > .env.prod << 'EOF'
+# 建立 backend/.env 檔案（API 容器會讀取）
+mkdir -p backend
+cat > backend/.env << 'EOF'
 # MongoDB
 MONGODB_URL=mongodb://mongodb:27017
 MONGODB_DATABASE=refactor_agent
@@ -207,7 +208,8 @@ ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY_HERE
 # Docker
 DOCKER_BASE_IMAGE=refactor-base:latest
 DOCKER_NETWORK=refactor-network
-DOCKER_VOLUME_PREFIX=/var/refactor-workspaces
+# 專案 workspace 在 API 容器內的根目錄（host 端目錄由 compose 的 WORKSPACE_HOST_DIR 控制）
+DOCKER_VOLUME_PREFIX=/tmp/refactor-workspaces
 
 # Container resources
 CONTAINER_CPU_LIMIT=2.0
@@ -222,10 +224,10 @@ LOG_LEVEL=INFO
 EOF
 
 # 設定權限
-chmod 600 .env.prod
+chmod 600 backend/.env
 ```
 
-⚠️ **重要**：請修改 `.env.prod` 中的以下變數：
+⚠️ **重要**：請修改 `backend/.env` 中的以下變數：
 - `JWT_SECRET_KEY` - 生產環境務必使用安全的隨機字串
 - `ANTHROPIC_API_KEY` - 填入你的 Anthropic API Key
 
@@ -238,17 +240,17 @@ docker network create refactor-network
 #### 4.6 測試部署
 
 ```bash
-# 手動拉取映像測試
-docker pull us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-base:latest
-
-# 啟動服務
-docker-compose -f devops/docker-compose.prod.yml up -d
+# 設定部署必要環境變數（用於組成 image name）
+export REGISTRY_HOST="us-central1-docker.pkg.dev"
+export GCP_PROJECT_ID="$PROJECT_ID"
+export GAR_REPOSITORY="images"
+export IMAGE_TAG="latest"
 
-# 檢查狀態
-docker-compose -f devops/docker-compose.prod.yml ps
+# (可選) host 端 workspace 目錄
+export WORKSPACE_HOST_DIR="/var/lib/refactor-workspaces"
 
-# 查看日誌
-docker-compose -f devops/docker-compose.prod.yml logs -f api
+# 一鍵拉取並啟動服務
+./scripts/deploy-prod.sh
 ```
 
 ---
@@ -333,7 +335,7 @@ EXTERNAL_IP=$(gcloud compute instances describe refactor-agent-prod \
 echo "Instance IP: $EXTERNAL_IP"
 
 # 測試 API health endpoint
-curl http://$EXTERNAL_IP:8000/health
+curl http://$EXTERNAL_IP:8000/api/v1/health
 
 # 測試 Frontend
 curl -I http://$EXTERNAL_IP:80
@@ -420,7 +422,7 @@ docker ps -a
 docker logs refactor-api --tail 50
 
 # 檢查網路連接
-docker exec refactor-api curl -f http://localhost:8000/health
+docker exec refactor-api curl -f http://localhost:8000/api/v1/health
 
 # 檢查防火牆
 sudo iptables -L -n
@@ -438,15 +440,15 @@ ValueError: PostgreSQL URL is required
 # SSH 到 GCE
 gcloud compute ssh refactor-agent-prod --zone=us-central1-a
 
-# 檢查 .env.prod
-cat ~/auto-refactor-agent/.env.prod | grep POSTGRES_URL
+# 檢查 backend/.env
+cat ~/auto-refactor-agent/backend/.env | grep POSTGRES_URL
 
 # 確保 PostgreSQL 容器正在運行
 docker ps | grep postgres
 
 # 重啟服務
 cd ~/auto-refactor-agent
-docker-compose -f devops/docker-compose.prod.yml restart api
+docker compose -f devops/docker-compose.prod.yml restart api
 ```
 
 ---
@@ -469,17 +471,16 @@ docker pull us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-base:$OLD_TAG
 docker pull us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-api:$OLD_TAG
 docker pull us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-frontend:$OLD_TAG
 
-# Tag 為 latest
-docker tag us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-base:$OLD_TAG refactor-base:latest
-docker tag us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-api:$OLD_TAG refactor-api:latest
-docker tag us-central1-docker.pkg.dev/$PROJECT_ID/images/refactor-frontend:$OLD_TAG refactor-frontend:latest
+# 使用舊 tag 重新啟動（確保 docker compose 變數對應）
+export REGISTRY_HOST="us-central1-docker.pkg.dev"
+export GCP_PROJECT_ID="$PROJECT_ID"
+export GAR_REPOSITORY="images"
+export IMAGE_TAG="$OLD_TAG"
 
-# 重啟服務
-docker-compose -f devops/docker-compose.prod.yml down
-docker-compose -f devops/docker-compose.prod.yml up -d
+./scripts/deploy-prod.sh
 
 # 驗證
-docker-compose -f devops/docker-compose.prod.yml ps
+docker compose -f devops/docker-compose.prod.yml ps
 ```
 
 ---

.github/workflows/README.md

@@ -169,7 +169,7 @@ Actions > CI/CD Pipeline > Run workflow
 
 ```bash
 # 啟動服務
-docker-compose -f devops/docker-compose.yml up -d postgres mongodb
+docker compose -f devops/docker-compose.yml up -d postgres mongodb
 
 # 設定環境變數
 export MONGODB_URL="mongodb://localhost:27017"
@@ -312,9 +312,9 @@ gh pr create --base main
 - [Docker Compose 配置](../../devops/docker-compose.yml)
 - [Backend 測試指南](../../backend/tests/QUICK_START.md)
 - [Frontend 測試配置](../../frontend/vitest.config.ts)
-- [環境變數配置](../../ENV_UPDATE_SUMMARY.md)
+- [環境變數配置](../../docs/CONFIGURATION.md)
 
 ---
 
-**最後更新**: 2026-02-06
+**最後更新**: 2026-02-08
 **維護者**: Development Team

CLAUDE.md

@@ -37,7 +37,7 @@ AI 舊程式碼智能重構系統 - 一個前後端分離的大型專案，提
 
 ### 資料模型設計
 
-- **Project** - 專案基本資訊 (repo_url, branch, init_prompt, status, container_id, owner_id)
+- **Project** - 專案基本資訊 (repo_url, branch, spec, status, container_id, owner_id)
 - **AgentRun** - Agent 執行記錄 (project_id, iteration_index, phase, status, artifacts_path)
 - **User** - 使用者帳號 (email, hashed_password, JWT 認證)
 
@@ -68,19 +68,19 @@ docker build -t refactor-base:latest -f devops/base-image/Dockerfile .
 docker run --rm refactor-base:latest ls -la /workspace/agent/
 
 # 啟動所有服務 (MongoDB + API + Frontend)
-docker-compose -f devops/docker-compose.yml up -d
+docker compose -f devops/docker-compose.yml up -d
 
 # 查看服務狀態
-docker-compose -f devops/docker-compose.yml ps
+docker compose -f devops/docker-compose.yml ps
 
 # 查看 API 日誌
-docker-compose -f devops/docker-compose.yml logs -f api
+docker compose -f devops/docker-compose.yml logs -f api
 
 # 停止服務
-docker-compose -f devops/docker-compose.yml down
+docker compose -f devops/docker-compose.yml down
 
 # 停止並清除資料
-docker-compose -f devops/docker-compose.yml down -v
+docker compose -f devops/docker-compose.yml down -v
 ```
 
 **API 層級控制**：

README.md

@@ -10,7 +10,7 @@ AI Refactoring. Measured. Continuous.
 
 - Docker & Docker Compose
 - Git
-- (開發環境) Python 3.11+, Node.js 18+
+- (開發環境) Python 3.11+, Node.js 20+
 
 ### 環境設定
 
@@ -25,10 +25,11 @@ cp .env.example .env
 必要配置項：
 - `JWT_SECRET_KEY` - JWT 簽名金鑰（生產環境務必更換）
 - `MONGODB_URL` - MongoDB 連接字串
+- `POSTGRES_URL` - PostgreSQL 連接字串（必填，Agent 會話持久化）
 - `DOCKER_BASE_IMAGE` - Base Docker Image 名稱
 - `DOCKER_NETWORK` - Docker 網路名稱
 
-**注意**: LLM API Key（如 `ANTHROPIC_API_KEY`）由容器內的 AI Server 自行管理，不需要在後端 `.env` 中設定
+**注意**: `ANTHROPIC_API_KEY` 會由後端讀取後注入到每個專案的 Project Container 中使用；未設定時，Project Container 將無法使用 Anthropic/Claude。
 
 2. **建立 Base Image**
 
@@ -47,16 +48,16 @@ Dockerfile 位置：
 
 ```bash
 # 啟動所有服務（PostgreSQL + MongoDB + Backend API + Frontend）
-docker-compose -f devops/docker-compose.yml up -d
+docker compose -f devops/docker-compose.yml up -d --build
 
 # 查看服務狀態
-docker-compose -f devops/docker-compose.yml ps
+docker compose -f devops/docker-compose.yml ps
 
 # 查看日誌
-docker-compose -f devops/docker-compose.yml logs -f api
+docker compose -f devops/docker-compose.yml logs -f api
 
 # 停止服務
-docker-compose -f devops/docker-compose.yml down
+docker compose -f devops/docker-compose.yml down
 ```
 
 **GCE 單機（正式環境）**
@@ -73,8 +74,8 @@ docker-compose -f devops/docker-compose.yml down
 **本地開發模式**
 
 ```bash
-# 1. 啟動 MongoDB
-docker run -d --name mongodb -p 27017:27017 mongo:7
+# 1. 啟動 PostgreSQL + MongoDB（推薦直接用 compose）
+docker compose -f devops/docker-compose.yml up -d postgres mongodb
 
 # 2. 啟動 Backend
 cd backend
@@ -99,10 +100,10 @@ curl -X POST http://localhost:8000/api/v1/auth/register \
   -H "Content-Type: application/json" \
   -d '{"email":"user@example.com","username":"testuser","password":"password123"}'
 
-# 登入
+# 登入（使用 username）
 curl -X POST http://localhost:8000/api/v1/auth/login \
   -H "Content-Type: application/json" \
-  -d '{"email":"user@example.com","password":"password123"}'
+  -d '{"username":"testuser","password":"password123"}'
 ```
 
 ### 2. 建立專案
@@ -112,9 +113,10 @@ curl -X POST http://localhost:8000/api/v1/projects \
   -H "Authorization: Bearer YOUR_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-    "repo_url": "https://github.com/yourusername/your-repo.git",
+    "project_type": "REFACTOR",
+    "repo_url": "https://github.com/your-org/your-repo.git",
     "branch": "main",
-    "init_prompt": "分析此專案並生成重構計劃"
+    "spec": "分析此專案並生成可量化的重構計劃"
   }'
 ```
 
@@ -144,12 +146,14 @@ curl -N http://localhost:8000/api/v1/projects/{project_id}/agent/runs/{run_id}/s
 ## 測試
 
 ```bash
-# 執行完整 E2E 測試
-./test_cloud_run_e2e_v2.sh
+# Backend
+cd backend
+python -m pytest tests/ -v
 
-# 測試 base image 建置
-export ANTHROPIC_API_KEY=your-api-key
-./test_base_image.sh
+# Frontend
+cd frontend
+npm ci
+npm run test -- --run
 ```
 
 ## 系統架構
@@ -191,6 +195,9 @@ export ANTHROPIC_API_KEY=your-api-key
 
 - **[docs/API.md](./docs/API.md)** - REST API 完整規格
 - **[docs/BACKEND.md](./docs/BACKEND.md)** - 後端技術文件
+- **[docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md)** - 啟動與開發入門
+- **[docs/USAGE.md](./docs/USAGE.md)** - 使用流程（UI/API）
+- **[docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)** - 部署說明
 - **[docs/guides/](./docs/guides/)** - 使用指南
 - **[docs/testing/](./docs/testing/)** - 測試文件
 - **[CLAUDE.md](./CLAUDE.md)** - Claude Code 專案指引
@@ -208,13 +215,13 @@ docker images | grep refactor-base
 
 1. 檢查容器內 AI Server 的 LLM API Key 設定
 2. 查看容器日誌：`docker logs refactor-project-{project_id}`
-3. 檢查 API 日誌：`docker-compose -f devops/docker-compose.yml logs -f api`
+3. 檢查 API 日誌：`docker compose -f devops/docker-compose.yml logs -f api`
 
 ### 如何清理測試資料？
 
 ```bash
 # 停止並移除所有容器和資料
-docker-compose -f devops/docker-compose.yml down -v
+docker compose -f devops/docker-compose.yml down -v
 
 # 清理專案容器
 docker ps -a | grep refactor-project | awk '{print $1}' | xargs docker rm -f