ab2a3e35b2
Multi-tenant factory inspection system (SpiFox, Enkid, Alpet): - FastAPI backend with JWT auth, PostgreSQL (asyncpg) - Next.js 16 frontend with App Router, SWR data fetching - Machines CRUD with equipment parts management - Part lifecycle tracking (hours/count/date) with counters - Partial unique index for soft-delete support - 24 pytest tests passing, E2E verified Co-Authored-By: Claude Opus 4 <noreply@anthropic.com>
87 lines
3.6 KiB
Markdown
87 lines
3.6 KiB
Markdown
# 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 # 시도 결과, 에러 기록, 다음 단계
|
|
```
|