refactor(infra): first-deploy-only workflow import + versioning guide

- init_n8n.sh: skip import if workflow already exists in n8n volume
- Remove --force-recreate (preserves n8n state + credential links)
- Add workflows/README.md with versioning rules and recovery guide

Workflow lifecycle: n8n UI (edit) → export → commit (version control)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ImTotem

infra/scripts/init_n8n.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# n8n workflow import + owner setup
-# Credentials (Postgres, Google Sheets) must be set up manually in n8n UI
+# n8n init: owner setup + first-time workflow import only
+# Workflows persist in n8n volume — reimport skipped if already exist
+# Credentials set up manually in n8n UI on first deploy
+# Workflow changes: edit in n8n UI, then export to workflows/*.json for versioning
 
 COMPOSE="sudo docker compose -p bcsd-app --env-file .env -f infra/docker/docker-compose.yml"
 MAX_RETRIES=15
@@ -20,6 +22,11 @@ wait_n8n() {
     return 1
 }
 
+workflow_exists() {
+    local id="$1"
+    $COMPOSE exec -T n8n n8n list:workflow 2>&1 | grep -q "$id"
+}
+
 setup_owner() {
     set -a; source .env; set +a
     local port
@@ -46,10 +53,22 @@ print('setup' if d.get('userManagement',{}).get('showSetupOnFirstLoad') else 'do
     echo "  Owner created: ${N8N_AUTH_USER}@bcsdlab.com"
 }
 
+import_if_new() {
+    local file="$1"
+    local id="$2"
+    if workflow_exists "$id"; then
+        echo "  $id — already exists, skipping (edit in n8n UI)"
+        return 0
+    fi
+    echo "  $id — first import"
+    $COMPOSE exec -T n8n n8n import:workflow --input="$file" 2>&1
+    $COMPOSE exec -T n8n n8n publish:workflow --id="$id" 2>&1 || true
+}
+
 echo "=== n8n Init ==="
 
 echo "1. Starting n8n..."
-$COMPOSE up -d --force-recreate n8n
+$COMPOSE up -d n8n
 
 echo "2. Waiting for n8n..."
 if ! wait_n8n; then
@@ -61,13 +80,8 @@ fi
 echo "3. Setting up owner account..."
 setup_owner
 
-echo "4. Importing workflows (overwrites by ID)..."
-$COMPOSE exec -T n8n n8n import:workflow --input="/workflows/pg_sheets_sync.json" 2>&1
-$COMPOSE exec -T n8n n8n import:workflow --input="/workflows/link_auto_expire.json" 2>&1
-
-echo "5. Publishing workflows..."
-$COMPOSE exec -T n8n n8n publish:workflow --id="pg-sheets-sync" 2>&1 || true
-$COMPOSE exec -T n8n n8n publish:workflow --id="link-auto-expire" 2>&1 || true
+echo "4. Importing workflows (first deploy only)..."
+import_if_new "/workflows/pg_sheets_sync.json" "pg-sheets-sync"
+import_if_new "/workflows/link_auto_expire.json" "link-auto-expire"
 
 echo "=== n8n Init complete ==="
-echo "NOTE: Set up Postgres + Google Sheets credentials in n8n UI if first deploy"

workflows/README.md

@@ -0,0 +1,45 @@
+# n8n Workflow 관리 규칙
+
+## 원칙
+
+- **n8n UI가 source of truth** — 실제 실행되는 워크플로우는 n8n 볼륨에 저장
+- **이 디렉토리는 버전 관리용 백업** — Git에서 변경 이력 추적
+- **배포 시 자동 import는 첫 배포만** — 이후에는 n8n 볼륨 상태 유지
+
+## 워크플로우 수정 절차
+
+1. **n8n UI**에서 워크플로우 수정 및 테스트
+2. 동작 확인 후 **n8n UI에서 export** (Workflow → `...` → Download)
+3. 다운받은 JSON으로 `workflows/*.json` 업데이트
+4. **커밋 메시지**에 변경 내용 기록: `docs(workflow): {변경 내용}`
+
+## Export 시 주의사항
+
+- n8n export에 credential 데이터는 포함되지 않음 (ID만 포함)
+- credential ID는 환경마다 다르므로 **커밋 전 ID를 빈 문자열로 교체**:
+  ```json
+  "credentials": {"postgres": {"id": "", "name": "BCSD PostgreSQL"}}
+  ```
+- 이렇게 해야 다른 환경에서 첫 배포 시 credential 수동 연결만 하면 됨
+
+## 파일 목록
+
+| 파일 | 워크플로우 ID | 설명 |
+|------|--------------|------|
+| `pg_sheets_sync.json` | `pg-sheets-sync` | PG → Google Sheets 동기화 (5분) |
+| `link_auto_expire.json` | `link-auto-expire` | 만료 링크 자동 처리 (1분) |
+
+## Credential 관리
+
+- n8n 볼륨(`n8n-data`)에 암호화 저장, `N8N_ENCRYPTION_KEY`로 보호
+- 첫 배포 시 n8n UI에서 수동 생성:
+  - **BCSD PostgreSQL**: host=`postgres`, port=`5432`, .env의 DB 정보
+  - **Google Sheets SA**: Service Account, bcsd-credentials의 SA JSON 사용
+- 이후 배포에서는 볼륨에 보존되므로 재설정 불필요
+
+## 볼륨 유실 시 복구
+
+1. `n8n import:credentials` — bcsd-credentials에서 export한 파일로 복구
+2. `n8n import:workflow` — 이 디렉토리의 JSON 파일로 복구
+3. n8n UI에서 각 워크플로우의 credential 재연결
+4. 워크플로우 Publish