SI 클라이언트 요청·운영 통합 포털

흩어진 채널(이메일/카카오/전화/폼)로 들어오던 클라이언트 요청을 하나의 포털로 통합하고, AI 트리아지 + 라이브 요소 피커로 "요청을 잃지 않고 중복 없이" 처리하는 SI 회사용 플랫폼.

기획: ~/.claude/plans/idempotent-zooming-flute.md 상세 설계: ~/.claude/plans/idempotent-zooming-flute-agent-a425c91db1fb8a17c.md

핵심 가치

• 요청 트리: 파생요청(1 → 1-1, 1-2) 추적, 변경이력 append-only → 유실 0
• AI는 제안만: Claude가 분류/요약/중복탐지 제안, PM이 승인 (무결성 보호)
• 라이브 요소 피커: 비개발자가 실제 화면 요소를 클릭 → 셀렉터/스타일/스크린샷 자동 첨부
• 멀티테넌트 준비: 모든 행 tenant_id + DB RLS (단일 조직 우선, 추후 SaaS 전환)

구현 현황

MVP 코어 완성 + 검증 완료 (✅ = 구현·테스트됨, ⏳ = 예정)

영역	상태
모노레포(Turborepo+pnpm)	✅
PostgreSQL 스키마 + RLS + 요청트리(ltree)	✅ (DB 스모크 테스트 통과)
멀티테넌트 격리(RLS, si_app 롤)	✅ (타 테넌트/미설정 차단 검증)
Auth.js v5 로그인(조직·롤)	✅ (E2E 통과)
tRPC + 요청 생성/목록/상세/트리/상태변경/코멘트	✅ (E2E 통과)
포털 UI (로그인·대시보드·요청작성·상세)	✅ (next build 통과)
AI 트리아지 워커(Claude)	⏳ Phase 1 잔여
라이브 요소 피커 위젯	⏳ Phase 2
견적 / 헬스 대시보드 / 채널통합 / SaaS화	⏳ Phase 2~3

모노레포 구조

apps/
  portal/    # ✅ Next.js 15 (대시보드 + 포털 + Auth.js + tRPC)
  workers/   # ⏳ BullMQ 워커 (ai.triage, ai.dedupe, shot.render, health.check)
  widget/    # ⏳ 임베드 위젯 (Vanilla TS + Shadow DOM, IIFE 빌드)
packages/
  db/        # ✅ PostgreSQL (순수 SQL 마이그레이션 + RLS + postgres.js tenant 클라이언트)
  shared/    # ✅ zod 스키마 (폼·위젯·AI 공통 타입)
  ai/        # ⏳ Claude tool-use 스키마 + 프롬프트 + 임베딩
  ui/        # ⏳ shadcn/ui 공유 컴포넌트

빠른 시작 (로컬)

Node 20+ 필요. corepack enable 가 권한오류(Program Files)면 corepack pnpm <cmd> 로 직접 실행. Postgres 호스트 포트는 5440 (docker-compose 매핑, 5432/5433 충돌 회피).

# 1) 의존성 설치
corepack pnpm install

# 2) 환경변수 (루트 = db 스크립트용, portal = Next 앱용)
cp .env.example .env
cp .env.example apps/portal/.env.local

# 3) 로컬 인프라 기동 (Postgres+pgvector, Redis, MinIO)
docker compose up -d postgres        # 또는 전체: docker compose up -d

# 4) DB 스키마 + RLS + 시드 (순수 SQL 마이그레이션)
corepack pnpm db:migrate
corepack pnpm db:seed
corepack pnpm db:smoke               # (선택) RLS·트리 스모크 테스트

# 5) 개발 서버
corepack pnpm --filter @si/portal dev   # http://localhost:3000

데모 로그인 (비밀번호 password123): pm@acme.dev(PM·내부) · client@goodshop.com(클라이언트)

런타임 E2E 검증 (서버 구동 후 별도 셸):

corepack pnpm --filter @si/portal start   # 프로덕션 서버
node apps/portal/scripts/e2e.mjs          # 로그인→요청생성→트리→상태변경 검증

단계

• MVP: 포털·요청접수 / AI 자동정리 / PM 대시보드 / 요청트리 / 상태 투명성
• Phase 2: 라이브 요소 피커 + 견적
• Phase 3: 사이트 헬스 대시보드 + 채널 통합 + SaaS화

주요 명령

명령	설명
pnpm dev	전체 개발 서버
pnpm build	전체 빌드
pnpm typecheck	타입 체크
pnpm db:migrate	SQL 마이그레이션 적용 (sql/*.sql)
pnpm db:seed	데모 데이터 시드
pnpm db:smoke	RLS·트리 스모크 테스트
pnpm db:reset	(개발) public 스키마 초기화

pnpm 이 PATH에 없으면 모든 명령 앞에 corepack 을 붙이세요 (예: corepack pnpm db:migrate).