sam-docs/history/roadmaps/december-2025.md

# SAM 12월 완료 로드맵

**작성일**: 2025-11-18
**목표**: 2025년 12월 31일까지 SAM 백엔드 핵심 기능 개발 완료
**기간**: 6주 (2025-11-18 ~ 2025-12-31)

---

## 📊 현재 진행 상황 (2025-11-18 기준)

### ✅ 완료된 항목 (약 70%)

#### 1. API 공통 기반 ✅
- [x] Exception Handler (Handler.php)
- [x] Swagger 설정 (l5-swagger v1)
- [x] API Key 인증 (ApiKeyMiddleware)
- [x] Rate Limit (ApiRateLimiter)
- [x] CORS 처리 (CorsMiddleware)
- [x] 권한 체크 (CheckPermission)

#### 2. 인증/보안 ✅
- [x] API Key 모델 및 인증
- [x] Role-Permission 시스템
- [x] 멀티테넌트 권한 구조
- [x] 권한 오버라이드 시스템

#### 3. 테넌트 관리 ✅
- [x] BelongsToTenant 글로벌 스코프
- [x] TenantBootstrap 서비스
- [x] 테넌트 컨텍스트 주입
- [x] 테넌트 옵션/설정 관리

#### 4. 기준정보/코드 관리 ✅
- [x] Category (3단계 트리)
- [x] CategoryField (동적 필드)
- [x] CategoryTemplate (템플릿)
- [x] Classification (공통 코드)
- [x] CommonCode 관리

#### 5. 제품/부품/자재 도메인 ✅
- [x] Product 모델 (67개 모델)
- [x] Part 관리
- [x] Material 관리
- [x] ProductComponent (BOM 연결)
- [x] PriceHistory (단가 이력)

#### 6. BOM (Bill of Materials) ✅
- [x] BomTemplate 관리
- [x] BomTemplateItem CRUD
- [x] BomCalculationService (가격 계산)
- [x] ModelVersion (버전 관리)
- [x] 재귀 BOM 구조

#### 7. 영업 흐름 ✅
- [x] Estimate (견적) - 기본 CRUD
- [x] EstimateItem (견적 라인)
- [x] Order (수주) - 5개 모델
- [x] OrderItem, OrderHistory
- [x] OrderItemComponent

#### 8. 자재입고/수입검사 ✅
- [x] MaterialReceipt (자재입고)
- [x] MaterialInspection (수입검사)
- [x] MaterialInspectionItem (검사 항목)

#### 9. 파일/로그 시스템 ✅
- [x] FileService, FileStorageService
- [x] AuditLogger, AuditLogService
- [x] File 모델 (Polymorphic)

#### 10. Admin 패널 (Filament) ✅
- [x] 27개 Resources 구현
- [x] Product, BOM, Material
- [x] Category, Role, Permission
- [x] Department, User, Tenant
- [x] Client, File 관리

#### 11. Services 계층 ✅
- [x] 56개 Service 클래스
- [x] Service-First 아키텍처
- [x] Design, Estimate, Pricing
- [x] Authz, Audit, Calculation

#### 12. Controllers ✅
- [x] 42개 API Controllers
- [x] RESTful 구조
- [x] FormRequest 검증
- [x] ApiResponse 표준 응답

---

## ❌ 미완료 항목 (약 30%)

### 1. 공정/생산 계획 (Priority: HIGH)
- [ ] Process Routing (공정 라우팅)
- [ ] Work Order (작업지시)
- [ ] Production Record (생산실적)
- [ ] Process Checksheet (공정 체크시트)

### 2. 단가/원가 체계 (Priority: HIGH)
- [ ] 단가 정책 로직 (공장별/중량/치수 기반)
- [ ] 원가 계산 서비스 (제품별, BOM 기반)
- [ ] 견적-수주 단가 연결 테이블
- [ ] PricingEngine 고도화

### 3. 견적서 출력 (Priority: MEDIUM)
- [ ] 견적서 HTML 템플릿
- [ ] PDF 생성 (DomPDF/Snappy)
- [ ] 견적서 미리보기 API
- [ ] 견적서 다운로드

### 4. 재고/자재 관리 (Priority: HIGH)
- [ ] 입출고 트랜잭션 설계
- [ ] 재고 집계 API (제품/부품/자재별)
- [ ] LOT 관리 확장
- [ ] 시리얼 관리

### 5. 창고/위치 관리 (Priority: MEDIUM)
- [ ] Warehouse (창고) 모델
- [ ] Location (위치) 모델
- [ ] 창고-위치 계층 구조
- [ ] 재고-위치 연결

### 6. 파일 시스템 완성 (Priority: MEDIUM)
- [ ] 파일 Upload API 개발
- [ ] 썸네일/리사이징 서비스
- [ ] 파일 접근 권한 (Security Layer)
- [ ] 파일 삭제 정책 구현

### 7. 알림 시스템 (Priority: LOW)
- [ ] 이메일 발송 서비스
- [ ] 카카오 메시지 연동
- [ ] 시스템 이벤트 기반 알림 규칙
- [ ] 알림 템플릿 관리

### 8. 테넌트 초기화 (Priority: MEDIUM)
- [ ] 테넌트 초기 데이터 생성 API
- [ ] 샘플 데이터 생성 스크립트
- [ ] 온보딩 자동화

### 9. 배포/운영 (Priority: HIGH)
- [ ] 배포 스크립트 (Docker Compose)
- [ ] staging/production 서버 구성
- [ ] 백업 정책
- [ ] 로그/모니터링 대시보드

### 10. 프론트엔드 (React) (Priority: MEDIUM)
- [ ] Admin 공통 레이아웃 최종 정리
- [ ] 기준정보 관리 UI
- [ ] 제품/부품/BOM 트리 UI
- [ ] 견적/수주 화면
- [ ] 재고관리 UI

---

## 📅 주차별 로드맵

### Week 1: 2025-11-18 ~ 2025-11-24 (공정/단가 체계)

**목표**: 공정 관리 및 단가 계산 로직 완성

#### API 개발
- [ ] Process Routing 모델 및 마이그레이션
- [ ] WorkOrder 모델 및 마이그레이션
- [ ] ProductionRecord 모델
- [ ] ProcessRoutingService 구현
- [ ] WorkOrderService 구현
- [ ] 단가 정책 로직 구현 (PricingEngine)
- [ ] 원가 계산 서비스 (CostCalculationService)

#### Admin 패널
- [ ] ProcessRoutingResource
- [ ] WorkOrderResource
- [ ] ProductionRecordResource

#### Swagger
- [ ] Process API 문서
- [ ] WorkOrder API 문서
- [ ] Pricing API 문서

**완료 기준**:
- 공정 라우팅 CRUD 완료
- 작업지시 생성/조회 완료
- 단가 계산 로직 테스트 통과

---

### Week 2: 2025-11-25 ~ 2025-12-01 (견적서 출력 + 재고)

**목표**: 견적서 PDF 생성 및 재고 트랜잭션 구현

#### API 개발
- [ ] EstimateTemplate 모델
- [ ] EstimatePrintService (PDF 생성)
- [ ] InventoryTransaction 모델
- [ ] StockMovement 모델
- [ ] InventoryService 구현
- [ ] 재고 집계 API

#### Admin 패널
- [ ] 견적서 미리보기 UI
- [ ] 견적서 PDF 다운로드
- [ ] 재고 현황 대시보드

#### Swagger
- [ ] Estimate Print API 문서
- [ ] Inventory API 문서

**완료 기준**:
- 견적서 PDF 생성 성공
- 입출고 트랜잭션 기록 완료
- 재고 집계 조회 API 완료

---

### Week 3: 2025-12-02 ~ 2025-12-08 (창고/파일/알림)

**목표**: 창고 관리, 파일 시스템, 알림 시스템 완성

#### API 개발
- [ ] Warehouse 모델
- [ ] Location 모델
- [ ] WarehouseService 구현
- [ ] FileUploadService 고도화
- [ ] FileThumbnailService (이미지 리사이징)
- [ ] NotificationService 구현
- [ ] EmailService 구현
- [ ] KakaoMessageService 연동

#### Admin 패널
- [ ] WarehouseResource
- [ ] LocationResource
- [ ] 파일 업로드 UI 개선
- [ ] 알림 설정 UI

#### Swagger
- [ ] Warehouse API 문서
- [ ] File Upload API 문서
- [ ] Notification API 문서

**완료 기준**:
- 창고/위치 CRUD 완료
- 파일 업로드 및 썸네일 생성 완료
- 이메일/카카오 알림 발송 성공

---

### Week 4: 2025-12-09 ~ 2025-12-15 (Admin UI + 테스트)

**목표**: Admin 패널 UI 완성 및 API 테스트

#### Admin 패널
- [ ] 공통 레이아웃 최종 정리
- [ ] 대시보드 위젯 구현
- [ ] 제품/BOM 트리 뷰 개선
- [ ] 견적/수주 화면 완성
- [ ] 재고관리 UI 완성
- [ ] 작업지시 UI 완성

#### 테스트
- [ ] PHPUnit 테스트 케이스 작성
- [ ] API 통합 테스트
- [ ] Postman 컬렉션 업데이트
- [ ] Swagger 문서 최종 검토

#### 품질 체크
- [ ] Pint 코드 포맷팅 전체 적용
- [ ] 코드 리뷰 (Service-First, FormRequest)
- [ ] i18n 메시지 키 정리

**완료 기준**:
- Admin 패널 모든 화면 완성
- 핵심 API 테스트 통과율 80% 이상
- Swagger 문서 100% 완성

---

### Week 5: 2025-12-16 ~ 2025-12-22 (통합 테스트 + 버그 수정)

**목표**: 전체 시스템 통합 테스트 및 버그 수정

#### 통합 테스트
- [ ] 견적 → 수주 → 생산 → 재고 흐름 테스트
- [ ] 멀티테넌트 격리 검증
- [ ] 권한 시스템 전체 테스트
- [ ] 파일 업로드/다운로드 테스트
- [ ] 알림 발송 테스트

#### 버그 수정
- [ ] Critical 버그 0건
- [ ] High 버그 수정
- [ ] Medium 버그 트리아지

#### 성능 최적화
- [ ] 느린 쿼리 최적화 (N+1 문제)
- [ ] API 응답 속도 개선
- [ ] 인덱스 최적화

**완료 기준**:
- 전체 시나리오 테스트 통과
- Critical/High 버그 0건
- API 평균 응답 속도 < 500ms

---

### Week 6: 2025-12-23 ~ 2025-12-31 (배포 준비 + 문서화)

**목표**: 프로덕션 배포 준비 및 문서화 완성

#### 배포 준비
- [ ] Docker Compose 최종 검증
- [ ] 환경변수 설정 가이드
- [ ] 데이터베이스 마이그레이션 순서 확정
- [ ] 백업/복구 절차 수립
- [ ] 로그/모니터링 대시보드 구축

#### 문서화
- [ ] API 문서 최종 검토 (Swagger)
- [ ] 관리자 매뉴얼 작성
- [ ] 개발자 가이드 업데이트
- [ ] 배포 가이드 작성
- [ ] 트러블슈팅 가이드

#### 보안 점검
- [ ] OWASP Top 10 체크
- [ ] API Key 보안 검토
- [ ] SQL Injection 방어 확인
- [ ] XSS 방어 확인
- [ ] CSRF 토큰 검증

#### 런칭 준비
- [ ] 테넌트 온보딩 자동화
- [ ] 샘플 데이터 생성 스크립트
- [ ] 데모 시나리오 (PPT + 녹화)
- [ ] SLA/장애 대응 문서

**완료 기준**:
- 프로덕션 배포 체크리스트 100% 완료
- 모든 문서 작성 완료
- 보안 점검 통과

---

## 🎯 핵심 성공 지표 (KPI)

### 기술 지표
- [ ] API 엔드포인트 100개 이상
- [ ] Swagger 문서 100% 완성
- [ ] 테스트 커버리지 60% 이상
- [ ] API 평균 응답 속도 < 500ms
- [ ] Critical/High 버그 0건

### 기능 지표
- [ ] 견적 → 수주 → 생산 → 재고 흐름 완성
- [ ] Admin 패널 30개 이상 Resources
- [ ] 멀티테넌트 격리 100% 검증
- [ ] 파일 업로드/다운로드 안정성 99%
- [ ] 알림 발송 성공률 95% 이상

### 품질 지표
- [ ] Service-First 아키텍처 100% 준수
- [ ] FormRequest 검증 100% 적용
- [ ] i18n 메시지 키 100% 적용
- [ ] BelongsToTenant 스코프 100% 적용
- [ ] Pint 코드 포맷팅 100% 통과

---

## ⚠️ 리스크 관리

### High Risk
| 리스크 | 영향도 | 완화 방안 |
|--------|--------|-----------|
| 단가 계산 로직 복잡도 | High | Week 1에 집중, 전문가 리뷰 |
| 재고 트랜잭션 동시성 | High | Lock 전략 수립, 테스트 강화 |
| PDF 생성 성능 | Medium | 비동기 큐 처리, 캐싱 |

### Medium Risk
| 리스크 | 영향도 | 완화 방안 |
|--------|--------|-----------|
| Admin UI 완성도 | Medium | Week 4 전담, 우선순위 선정 |
| 알림 시스템 안정성 | Medium | 외부 API 장애 처리 |
| 통합 테스트 시간 부족 | Medium | 자동화 테스트 확대 |

### Low Risk
| 리스크 | 영향도 | 완화 방안 |
|--------|--------|-----------|
| 문서화 누락 | Low | 주차별 문서 작성 병행 |
| 코드 품질 저하 | Low | Pint + Code Review |

---

## 🚀 다음 단계 (2026년 1월~)

### Phase 2: 프론트엔드 고도화
- React Admin 패널 완전 재구축
- 사용자 포털 (고객 견적 요청)
- 모바일 대응
- 실시간 대시보드

### Phase 3: 고급 기능
- 실시간 생산 모니터링
- IoT 센서 연동
- AI 기반 수요 예측
- 재고 최적화 알고리즘

### Phase 4: 확장
- 다국어 지원 확대
- 글로벌 테넌트 지원
- API 버전 2.0
- 마이크로서비스 전환 검토

---

## 📝 작업 추적

### 진행 상황 업데이트
- **매일**: CURRENT_WORKS.md 업데이트
- **매주**: 주차별 로드맵 진행률 체크
- **매 2주**: 전체 로드맵 리뷰 및 조정

### 커밋 규칙
- `feat`: 새로운 기능 추가
- `fix`: 버그 수정
- `chore`: 빌드, 설정 변경
- `refactor`: 코드 리팩토링
- `docs`: 문서 업데이트
- `test`: 테스트 추가/수정

---

## 📞 담당자 및 연락처

| 역할 | 담당자 | 비고 |
|------|--------|------|
| 프로젝트 리드 | - | - |
| 백엔드 개발 | Claude Code | API/Admin |
| 프론트엔드 개발 | - | React |
| QA | - | 테스트 |
| DevOps | - | 배포/운영 |

---

**작성**: Claude Code
**최종 업데이트**: 2025-11-18
**다음 리뷰**: 2025-11-25 (Week 2 시작 전)