factoryOps-v2/CLAUDE.md

FactoryOps v2 개발 가이드

IMPORTANT: 스킬 우선 확인

YOU MUST 서버 실행, 테스트, 커밋, 빌드 등 반복 작업 수행 전 반드시 아래 스킬을 먼저 확인하세요. 스킬에 정의된 방법을 따르지 않고 임의로 명령어를 실행하지 마세요.

사용 가능한 스킬

스킬	설명	사용 시점
/serve	개발 서버 시작 (Podman)	서버 실행 필요 시
/test	pytest 테스트 실행	테스트 실행 시
/commit	Git 커밋 생성	코드 변경 후 커밋 시
/review	코드 리뷰	변경사항 검토 시
/ui-test	브라우저 UI 테스트 (Playwright MCP)	코드 작성/수정 후
/frontend-design	프론트엔드 디자인	UI 개발 시

사용자 선호사항

• 커밋 후 항상 푸시: /commit 완료 후 자동으로 git push 실행

---

기술 스택

• Backend: FastAPI (Python 3.11+)
• Frontend: Next.js 16 (App Router, React 19)
• Database: PostgreSQL 전용 (asyncpg + SQLAlchemy async) — SQLite 미사용
• Data Fetching: SWR 2.x
• Styling: 커스텀 CSS (Material Design 3 스타일)
• Auth: JWT (HS256, 24h 만료) + bcrypt

프로젝트 구조

factoryOps/
├── main.py                    # FastAPI 앱 엔트리포인트 (60~80줄)
├── requirements.txt           # Python 의존성
├── alembic.ini                # DB 마이그레이션 설정
├── alembic/                   # 마이그레이션 파일
├── src/
│   ├── auth/                  # 인증 시스템 (JWT)
│   ├── database/              # DB 설정 + 모델 (PostgreSQL async)
│   ├── tenant/                # 멀티테넌트 관리
│   ├── api/                   # API 라우터
│   └── services/              # 비즈니스 로직
├── tests/                     # pytest 테스트
├── dashboard/                 # Next.js 프론트엔드
│   ├── app/                   # App Router 페이지
│   ├── components/            # 공유 컴포넌트
│   └── lib/                   # API, 훅, 유틸리티
├── planning/                  # 작업 메모리
└── scripts/                   # 유틸리티 스크립트

핵심 설계 원칙

"TYPE 필드로 분기하고, 테넌트 ID로는 절대 분기하지 않는다."

• 업체별 차이는 lifecycle_type, data_type, inspection_mode, alarm_type 등 엔티티 TYPE 필드에서 결정
• 코어 앱에 if tenant == "spifox" 같은 분기 = 0개
• 3개 고객사: 스피폭스(프레스), 엔키드(다이캐스팅), 알펫(라미네이팅)

데이터베이스

• PostgreSQL 전용 (asyncpg 드라이버)
• JSONB, UUID, TIMESTAMPTZ 등 PostgreSQL 네이티브 타입 사용
• 마이그레이션: Alembic
• 테스트: PostgreSQL 테스트 DB (트랜잭션 롤백 격리)

Vercel React Best Practices 적용

적용된 패턴

• server-parallel-fetching - 서버 컴포넌트 병렬 페칭
• bundle-dynamic-imports - 클라이언트 컴포넌트 동적 로드
• rendering-hoist-jsx - 정적 객체 모듈 레벨 호이스팅
• rerender-memo - 메모이즈된 컴포넌트
• client-swr-dedup - SWR 자동 요청 중복 제거

Planning with Files (작업 메모리 시스템)

복잡한 작업 시 planning/ 디렉토리 파일들을 작업 메모리로 활용합니다.

planning/
├── task_plan.md    # 작업 단계별 체크박스 관리
├── findings.md     # 발견한 정보, 코드 참조, 결정 사항
└── progress.md     # 시도 결과, 에러 기록, 다음 단계