# 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     # 시도 결과, 에러 기록, 다음 단계
```