Spective 핸드오프

Appearance

3. 개발 환경 셋업 ​

인수자가 처음부터 로컬에서 앱을 띄우는 절차입니다. 루트 README.md와 동일한 기준이며, 여기서는 인계 관점으로 정리합니다.

3.1 사전 요구사항 ​

  • mise (권장 — Node/Bun 버전 자동 고정)
  • Node.js 22.x — 단일 소스는 package.json의 devEngines.runtime
  • Bun 1.3.x — package.json의 packageManager (현재 bun@1.3.13)
  • ⚠️ mise는 Node 버전을 devEngines.runtime에서만 읽음. engines.node/volta.node는 무시 → Node 버전 변경 시 devEngines.runtime 수정.
  • 출처: README.md, mise.toml, package.json

3.2 클론 → 설치 → 실행 ​

bash
mise install      # package.json 기준 Node/Bun 자동 설치
bun install       # 의존성 설치
bun run dev        # 전체 dev 서버 (Turbo)
  • 실제 웹 앱 포트: 3800
  • 단일 앱만: bun run --filter web dev

3.3 환경변수 · 시크릿 복호화 ​

  • dotenvx 암호화 구조: .env(공통) + .env.secrets.{environment}(암호화), .env.keys는 미커밋
  • .env.keys 복호화 키 입수 경로 (상세 §7.2):
    • Bitwarden 공유 볼트 — 인수자가 공유 볼트 멤버로 추가되어 평문 키 입수
    • GCP Secret Manager — 로컬 평문 키 없이 prod 운영하려면 roles/secretmanager.secretAccessor 권한 위임으로 충분 (런타임이 DOTENV_PRIVATE_KEY_SECRETS_PRODUCTION에서 읽음)
    • ⚠️ 이메일/메신저 평문 전달 금지
  • 시크릿 추가: cd apps/web && bunx dotenvx set KEY "value" -f .env.secrets.<환경>
  • 출처: ARCHITECTURE.md §환경 변수

3.4 로컬 DB 셋업 + 시드 ​

bash
cd apps/web            # db:* 스크립트는 apps/web/package.json 에만 있음 (루트 실행 시 "Script not found")
bun run db:migrate     # dev 마이그레이션 실행
bun run db:generate    # Prisma 클라이언트 생성
bun run db:studio      # GUI (dev DB 접속)

환경별 시드 (dev / prod 분리, apps/web에서 실행):

명령어설명
bun run db:seed전체 시드
bun run db:seed:diagnosis진단 문항
bun run db:seed:report-pages리포트 페이지
bun run db:seed:landing랜딩 페이지

각 명령에 :prod 접미사를 붙이면 prod 대상 (예: db:seed:prod). 출처: README.md Database.

로컬 DB 구동 방식: 별도의 로컬 Postgres/Docker를 띄우지 않습니다. DB는 관리형 **Supabase(Postgres, Seoul)**이며, 로컬 개발 시 dotenvx 시크릿의 DATABASE_URL(pooled)·DIRECT_URL(direct)로 dev Supabase에 직접 접속합니다. 따라서 시크릿 복호화(3.3)만 되면 apps/web에서 bun run db:migrate·db:studio가 그대로 동작합니다. (DB 상세는 6.4)

3.5 테스트 · 린트 · 타입체크 ​

bash
bun run test               # 전체 단위 테스트 (Turbo)
bun run test:integration   # 통합 테스트 (web, testcontainers)
bun run lint               # ESLint (@antfu/eslint-config)
bun run lint:fix
bun run typecheck
bun run e2e                # Playwright E2E
  • 커밋 시 husky + lint-staged가 변경 파일에 eslint --fix 자동 적용.
  • 커밋 메시지는 commitlint(conventional commits) 검증.