member-platform/docs/LOCAL_DEV_RUNBOOK.md

Local Dev Runbook（Keycloak）

1) 先重建 DB schema（本次改版必做）

cd backend
psql "$DATABASE_URL" -f scripts/init_schema.sql

• DB schema 檔案：backend/scripts/init_schema.sql

2) 啟動後端

本地開發使用 .env.development：

cd backend
# edit .env.development directly

本機開發固定使用 backend/.env.development。

再啟動：

cd backend
./scripts/start_dev.sh

• 專案路徑：backend
• 啟動腳本：backend/scripts/start_dev.sh

3) 啟動前端

cd frontend
npm install
npm run dev

• 專案路徑：frontend

4) 必要環境變數（backend/.env）

• KEYCLOAK_BASE_URL
• KEYCLOAK_REALM
• KEYCLOAK_CLIENT_ID
• KEYCLOAK_CLIENT_SECRET
• KEYCLOAK_ADMIN_CLIENT_ID
• KEYCLOAK_ADMIN_CLIENT_SECRET
• MEMBER_REQUIRED_REALM_ROLES
• ADMIN_REQUIRED_REALM_ROLES
• CACHE_BACKEND（memory 或 redis）
• CACHE_REDIS_URL
• CACHE_PREFIX
• CACHE_DEFAULT_TTL_SECONDS

Cache 切換範例

• 本地（預設）：
  • CACHE_BACKEND=memory
• 切 Redis：
  • CACHE_BACKEND=redis
  • CACHE_REDIS_URL=redis://127.0.0.1:6379/0

調整後重啟後端生效。

5) 基本檢查

1. GET http://127.0.0.1:8000/healthz 應為 200。
2. 前端按「前往 Keycloak 登入」應可成功導轉與回跳。
3. GET /me 登入後應有資料。
4. 非 admin realm role 帳號打 /admin/* 應為 403。
5. POST /admin/sync/from-provider?force=true 可手動觸發全量補齊同步。
6. 列表 API 不會自動同步 IdP（避免高負載），需手動按同步按鈕或呼叫同步 API。

6) 新模型驗收路徑

1. 新增 Company、Site。
2. 在 Keycloak 建立 System（Client）與 Role（Client Role）。
3. 在後台按「同步 Keycloak」，確認 DB 補齊 System/Role。
4. 對 Site 指派 Role。
5. 新增 User，加入 Site。
6. 驗證 User 的角色是由 Site 推導，不是 direct assign。

7) API 白名單驗收

1. 建立 api_client。
2. 用 X-Client-Key + X-API-Key 呼叫 /internal/*。
3. 驗證未授權 key 會被拒絕。

8) VPS Docker 啟動（Backend）

• Dockerfile: backend/Dockerfile
• 建置與啟動指令：參考 backend/README.md 的 Docker (VPS / Production) 章節。