팀원 로컬 세팅용 setup 스크립트

클론 후 npm run setup 한 줄로 끝나게 했다.
docker/node 버전 사전 점검 → .env 생성 → 컨테이너 → 마이그레이션 →
시드 → 키워드 7,093건 적재까지.

- scripts/setup.sh
- scripts/requirements.txt — 엑셀 스크립트용 openpyxl (누락돼 있었다)
- README 빠른 시작을 클론부터 시작하도록 수정, 포트/모델 다운로드 안내 추가

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

README.md

@@ -9,17 +9,41 @@ o2o-site-AEO 가 발행한 사이트에 **업체별 SEO/AEO 키워드**를 제
 
 ## 빠른 시작 (로컬)
 
+**필요한 것:** Docker Desktop 실행 중 · Node 20+
+
 ```bash
+git clone https://gitea.o2o.kr/Web4ai/o2o-site-ontology.git
+cd o2o-site-ontology
 npm install
-cp .env.example .env          # 기본값은 LLM_PROVIDER=mock — API 키 불필요
-npm run db:up                 # postgres(pgvector) + redis
-npm run db:migrate
-npm run db:seed               # 업종/지역 계층 + 데모 업체 3곳
-npm run dataset:build         # 1,000건 데이터셋 생성 → data/
-npm run dataset:ingest        # 임베딩 + pgvector 적재 (최초 1회 모델 다운로드)
-npm start                     # http://localhost:3100
+npm run setup      # .env 생성 → 컨테이너 → 마이그레이션 → 시드 → 키워드 7,093건 적재
+npm start          # http://localhost:3100
 ```
 
+`npm run setup` 이 전부 한다. API 키는 필요 없다 (LLM=mock, 임베딩=로컬 모델).
+최초 1회 임베딩 모델을 내려받는다 — 약 120MB, 1~2분. 그 뒤로는 오프라인으로 동작한다.
+
+포트는 기존 개발환경과 겹치지 않게 잡아 두었다 — postgres `55432`, redis `56379`, 앱 `3100`.
+
+확인: **http://localhost:3100/demo** 입력창에 `스테이 머뭄`
+
+엑셀 산출 스크립트를 쓸 때만 파이썬 의존성이 필요하다.
+
+```bash
+pip3 install -r scripts/requirements.txt
+```
+
+<details><summary>수동으로 단계별 실행</summary>
+
+```bash
+cp .env.example .env
+npm run db:up                    # postgres(pgvector) + redis
+npm run db:migrate
+npm run db:seed                  # 업종/지역 계층 + 데모 업체
+npm run dataset:ingest           # 군산 상세 974건
+npm run dataset:ingest-nationwide # 전국 54개 지역
+```
+</details>
+
 브라우저에서 **http://localhost:3100/demo** 를 열면 매칭 콘솔이 뜬다.
 입력창에 `스테이 머뭄` 을 넣으면 (띄어쓰기가 달라도) 업체를 해석하고
 적재된 971건 사전에서 잘 맞는 키워드를 순위대로 보여준다.

package.json

@@ -4,6 +4,7 @@
   "description": "SEO/AEO keyword ontology service for o2o-site-AEO",
   "private": true,
   "scripts": {
+    "setup": "bash scripts/setup.sh",
     "build": "nest build",
     "start": "nest start",
     "start:dev": "nest start --watch",

scripts/requirements.txt

@@ -0,0 +1,3 @@
+# 엑셀 산출 스크립트용 (scripts/export-xlsx.py, export-db-xlsx.py)
+#   pip3 install -r scripts/requirements.txt
+openpyxl>=3.1

scripts/setup.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# 클론 직후 로컬 세팅 한 번에.
+#   npm run setup
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+step() { printf '\n\033[1m▶ %s\033[0m\n' "$1"; }
+
+step "사전 점검"
+command -v docker >/dev/null || { echo "❌ docker 가 필요합니다"; exit 1; }
+docker info >/dev/null 2>&1 || { echo "❌ Docker Desktop 을 실행해 주세요"; exit 1; }
+node -e 'process.exit(+process.versions.node.split(".")[0] >= 20 ? 0 : 1)' \
+  || { echo "❌ Node 20 이상이 필요합니다 (현재 $(node -v))"; exit 1; }
+echo "  docker ok · node $(node -v)"
+
+step ".env 준비"
+if [ -f .env ]; then echo "  이미 있음 — 건너뜀"; else cp .env.example .env; echo "  .env.example → .env"; fi
+
+step "컨테이너 기동 (postgres+pgvector, redis)"
+docker compose up -d --wait
+
+step "스키마 마이그레이션"
+npm run --silent db:migrate
+
+step "기준 데이터 시드 (업종·지역·데모 업체)"
+npm run --silent db:seed
+
+step "키워드 적재 — 군산 상세"
+echo "  최초 1회 임베딩 모델을 내려받습니다 (약 120MB, 1~2분)"
+npm run --silent dataset:ingest 2>&1 | grep -vE '^\s*적재 [0-9]+/' || true
+
+step "키워드 적재 — 전국 54개 지역"
+npm run --silent dataset:ingest-nationwide 2>&1 | grep -vE '^\s*적재 [0-9]+/' || true
+
+step "완료"
+cat <<'MSG'
+  npm start                → http://localhost:3100
+  http://localhost:3100/demo  매칭 콘솔 (입력창에 "스테이 머뭄")
+
+  엑셀 산출이 필요하면: pip3 install -r scripts/requirements.txt
+MSG