SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: [bending] 절곡품 전용 테이블 분리 완료 문서

Browse Source 
- README: bending_items 266건 + bending_models 62건 DB 검증 완료
- README: 하장바 검색 문제 해결 (10건 정상)
- README: bending_data JSON 통합, bending_item_mappings DROP
- README: LOT 코드 체계, 테이블 관계도, 레거시 대응표 갱신
- step1: 데이터분석 업데이트
- step5: canvas 그리기 추가
- .gitattributes CRLF→LF 정규화
This commit is contained in:
강영보
2026-03-19 20:03:46 +09:00
parent 6484e73976
commit 220ab78041
41 changed files with 16081 additions and 14435 deletions
Download Patch File Download Diff File Expand all files Collapse all files

578
system/api-analysis-report.md
View File

@@ -1,289 +1,289 @@
# SAM API 구조 분석 및 개선 로드맵
> **작성일**: 2026-03-14
> **상태**: 분석 완료, 개선 진행중
> **작성자**: R&D 개발실장
> **대상**: `/home/aweso/sam/api` (Laravel 12 REST API)
---
## 1. 개요
### 1.1 목적
SAM API의 현재 구조를 정량적으로 분석하고, 기술 부채를 식별하여 우선순위별 개선 로드맵을 수립한다. R&D 개발실장이 백엔드 전반을 파악하고 체계적으로 품질을 끌어올리기 위한 기준 문서이다.
### 1.2 분석 기준일
- 코드베이스: 2026-03-14 기준 develop 브랜치
- Claude Code v2.1.75 (Opus 4.6)로 자동 분석
---
## 2. 프로젝트 규모
### 2.1 전체 수치
| 항목 | 수량 | 비고 |
|------|------|------|
| **엔드포인트** | ~1,400개 | 19개 도메인 라우트 파일 |
| **컨트롤러** | 152개 | V1 144개 + Admin 1개 + Equipment 7개 |
| **서비스** | 202개 | 22개 도메인 폴더 + 루트 98개 |
| **모델** | 261개 | 32개 도메인 폴더 |
| **FormRequest** | 305개 | 42개 도메인 폴더 |
| **마이그레이션** | 545개 | 메인 523 + 통계 22 |
| **미들웨어** | 10개 | |
| **아티산 커맨드** | 39개 | |
| **옵저버** | 15개 | 감사/이벤트 처리 |
| **Swagger 문서** | 110개 | OpenAPI 스펙 |
| **테스트** | 14개 | Feature 11 + Unit 3 |
| **PHP 코드** | 179,010줄 | |
### 2.2 도메인별 엔드포인트 분포
| 도메인 | 엔드포인트 | 비중 | 핵심 기능 |
|--------|:---------:|:----:|----------|
| Finance | 271 | 19% | 카드, 계좌, 입출금, 급여, 세금계산서, 바로빌 |
| HR | 153 | 11% | 부서, 직원, 근태, 휴가, 전자결재, 시공관리 |
| Sales | 135 | 10% | 거래처, 견적, 입찰, 수주, 단가, 데모테넌트 |
| Common | 134 | 10% | 메뉴, 권한, 카테고리, 대시보드, 알림 |
| Inventory | 85 | 6% | 품목, BOM, 자재, 입고, 배차 |
| Boards | 84 | 6% | 게시판, 품목기준관리(ItemMaster) |
| Production | 73 | 5% | 공정, 작업지시, 작업실적, 검사 |
| Design | 61 | 4% | 모델, 버전, BOM 템플릿, 계산 엔진 |
| Quality | 36 | 3% | 품질관리, 검사, 인증 |
| Users | 34 | 2% | 프로필, 역할, 테넌트 전환 |
| Admin | 29 | 2% | 테넌트, 메뉴, FCM, API Key |
| Equipment | 27 | 2% | 설비, 정비 |
| Tenants | 23 | 2% | 테넌트 설정, 구독 |
| Files | 21 | 2% | 업로드, 저장 |
| Documents | 18 | 1% | 템플릿, 생성 |
| ESign | 18 | 1% | 전자서명 워크플로우 |
| Auth | 9 | 1% | 로그인, 토큰 |
| Stats | 9 | 1% | 통계/리포트 |
| Audit | 7 | 0.5% | 감사 로그 |
---
## 3. 아키텍처 분석
### 3.1 3대 설계 원칙
```
┌─────────────────────────────────────────────────────┐
│ 1. Service-First 패턴 │
│ Controller (라우팅만) → Service (로직) → Model │
│ Controller에 비즈니스 로직 작성 금지 │
├─────────────────────────────────────────────────────┤
│ 2. Multi-Tenant (tenant_id 기반) │
│ BelongsToTenant 트레이트 → 자동 WHERE 필터링 │
│ 1명 사용자가 여러 테넌트 접근 가능 │
├─────────────────────────────────────────────────────┤
│ 3. 5계층 보안 │
│ Nginx → Rate Limit → API Key → Sanctum → 권한 │
│ 메뉴 기반 RBAC (7가지 권한 타입) │
└─────────────────────────────────────────────────────┘
```
### 3.2 요청 처리 흐름
```
HTTP Request
↓
Nginx (악성 경로 차단, Rate Limit)
↓
Middleware Stack
├─ ApiKeyMiddleware (X-API-KEY 검증)
├─ ApiVersionMiddleware (v1/v2 폴백)
├─ auth:sanctum (Bearer 토큰)
├─ PermMapper (메뉴→권한 매핑)
├─ CheckPermission (RBAC 체크)
└─ SetAuditSessionVariables (감사 추적)
↓
Controller (FormRequest 타입힌팅 → 자동 검증)
↓
Service (비즈니스 로직)
├─ tenantId() / apiUserId() 자동 제공
└─ Model (BelongsToTenant 자동 필터링)
↓
ApiResponse::handle() → JSON { success, message, data }
```
### 3.3 표준 테이블 구조
```sql
id BIGINT PK
tenant_id BIGINT FK -- 멀티테넌트 격리
-- 비즈니스 컬럼 (FK, WHERE/ORDER BY 대상만)
options JSON NULL -- 유연한 확장 속성
created_by BIGINT FK -- 감사 추적
updated_by BIGINT FK
deleted_by BIGINT FK
created_at TIMESTAMP
updated_at TIMESTAMP
deleted_at TIMESTAMP -- SoftDeletes
```
### 3.4 핵심 트레이트
| 트레이트 | 역할 | 적용 범위 |
|---------|------|----------|
| `BelongsToTenant` | tenant_id 자동 필터링 (Global Scope) | 모든 테넌트 모델 |
| `Auditable` | created_by, updated_by, deleted_by 자동 기록 | 모든 비즈니스 모델 |
| `ModelTrait` | is_active 스코프, 날짜 처리 | 모든 모델 |
| `SoftDeletes` | 논리 삭제 (물리 삭제 금지) | 모든 모델 |
### 3.5 주요 파일 위치
```
/home/aweso/sam/api/
├── app/
│ ├── Http/Controllers/Api/V1/ ← 컨트롤러 (144개)
│ ├── Http/Middleware/ ← 미들웨어 (10개)
│ ├── Http/Requests/ ← FormRequest (305개)
│ ├── Models/ ← 모델 (261개, 32개 폴더)
│ ├── Services/ ← 서비스 (202개, 22개 폴더)
│ ├── Traits/ ← 공용 트레이트 (6개)
│ ├── Observers/ ← 옵저버 (15개)
│ ├── Console/Commands/ ← 아티산 커맨드 (39개)
│ └── Swagger/v1/ ← API 문서 (110개)
├── routes/api/v1/ ← 도메인별 라우트 (19개)
├── database/migrations/ ← 마이그레이션 (545개)
├── config/ ← 설정 (24개)
└── tests/ ← 테스트 (14개)
```
---
## 4. 이관 현황
### 4.1 전체 현황
| 상태 | 수량 | 설명 |
|------|:----:|------|
| 이관 완료 | 24개 | API + React 모두 구현됨 |
| 이관 대상 (P1) | 15개 | 자금일정, 정산, VAT, 채번, 전자서명 등 |
| React UI만 필요 | 8개 | API 완료, UI 미구현 (QMS, 설비 등) |
| MNG 유지 | 11개 | PMIS, 신용평가, Dev Tools 등 |
### 4.2 이관 대상 우선순위
| Phase | 대상 | 우선순위 |
|-------|------|:-------:|
| Phase 1 | 자금일정, 일일자금, 정산, VAT, 채번, 전자서명 | 🔴 P1 |
| Phase 2 | 견적수식, 판매수수료, 전자서명 고도화 | 🟡 P2 |
| Phase 3 | QMS UI, 설비 UI, 요금제 UI | 🟡 P2 |
| Phase 4 | 휴가정책 자동부여, 통합근태 | 🟢 P3 |
---
## 5. 기술 부채 및 개선 로드맵
### 5.1 식별된 기술 부채
| ID | 영역 | 현황 | 영향도 | 우선순위 |
|:--:|------|------|:------:|:-------:|
| D1 | **테스트 부재** | 14개 (1,400 EP 대비 1%) | 🔴 높음 | P1 |
| D2 | **N+1 쿼리** | 일부 Service에서 반복 쿼리 | 🔴 높음 | P1 |
| D3 | **마이그레이션 정리** | 545개, 순서/네이밍 혼재 | 🟡 중간 | P2 |
| D4 | **i18n 미완** | 일부 에러에 직접 문자열 잔존 | 🟡 중간 | P2 |
| D5 | **FK 제약 과다** | Production 도메인 중심 | 🟡 중간 | P2 |
| D6 | **통계 DB 동기화** | sam_stat 수동/불완전 | 🟢 낮음 | P3 |
| D7 | **API 문서 최신화** | 110개 중 일부 outdated | 🟢 낮음 | P3 |
| D8 | **Rate Limiting** | 10회/분 고정, 도메인별 미세분화 | 🟢 낮음 | P3 |
### 5.2 개선 로드맵
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 P1 즉시 착수 (품질 기반 확보)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D1] 테스트 커버리지 확충
→ 핵심 도메인(Finance, Sales, HR) Feature 테스트 우선
→ 목표: 주요 CRUD + 비즈니스 로직 커버
[D2] N+1 쿼리 최적화
→ 대형 컨트롤러 5개 우선 점검
(ItemsBomController, WorkOrderController,
BarobillCardTransactionController,
ApprovalController, QuoteController)
→ Service에서 with() eager load 적용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟡 P2 단기 개선 (안정성 강화)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D3] 마이그레이션 정리
→ squash 또는 네이밍 표준화
→ MNG 전용 마이그레이션 분리 확인
[D4] i18n 완성
→ 직접 문자열 → message key 전환
→ grep으로 잔존 문자열 스캔
[D5] FK 제약 최적화
→ Production 도메인 FK 관계 정리
→ 삭제 순서 복잡도 감소
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟢 P3 중장기 (확장성)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D6] 통계 DB 실시간화
→ Event Sourcing 또는 CDC 검토
[D7] Swagger 문서 최신화
→ 자동 생성 파이프라인 개선
[D8] Rate Limiting 동적화
→ 테넌트/도메인별 차등 적용
```
### 5.3 강점 (유지해야 할 것)
```
✅ Service-First 패턴 — 일관된 비즈니스 로직 분리
✅ 5계층 보안 — Nginx ~ Permission까지 다층 방어
✅ BelongsToTenant — 멀티테넌트 자동 격리, 데이터 누출 방지
✅ Auditable — 모든 변경사항 자동 추적
✅ options JSON — 스키마 변경 없이 유연한 확장
✅ FormRequest 분리 — 305개 검증 클래스, 입력 검증 표준화
✅ ApiResponse::handle() — 통일된 응답 포맷
```
---
## 6. 진행 추적
> 아래 체크리스트로 개선 작업 진행 상황을 추적한다.
### P1 (즉시)
- [ ] [D1] 테스트 커버리지 확충 — 핵심 도메인 Feature 테스트
- [ ] [D2] N+1 쿼리 최적화 — 대형 컨트롤러 5개 점검
### P2 (단기)
- [ ] [D3] 마이그레이션 정리
- [ ] [D4] i18n 직접 문자열 제거
- [ ] [D5] FK 제약 최적화
### P3 (중장기)
- [ ] [D6] 통계 DB 실시간화
- [ ] [D7] Swagger 문서 최신화
- [ ] [D8] Rate Limiting 동적화
---
## 관련 문서
- [시스템 아키텍처](overview.md)
- [API 서버 구조](api-structure.md)
- [API 개발 규칙](../dev/standards/api-rules.md)
- [이관 현황](migration-status.md)
- [DB 스키마](database/README.md)
- [보안 정책](security-policy.md)
- [품질 체크리스트](../dev/standards/quality-checklist.md)
---
**최종 업데이트**: 2026-03-14
# SAM API 구조 분석 및 개선 로드맵
> **작성일**: 2026-03-14
> **상태**: 분석 완료, 개선 진행중
> **작성자**: R&D 개발실장
> **대상**: `/home/aweso/sam/api` (Laravel 12 REST API)
---
## 1. 개요
### 1.1 목적
SAM API의 현재 구조를 정량적으로 분석하고, 기술 부채를 식별하여 우선순위별 개선 로드맵을 수립한다. R&D 개발실장이 백엔드 전반을 파악하고 체계적으로 품질을 끌어올리기 위한 기준 문서이다.
### 1.2 분석 기준일
- 코드베이스: 2026-03-14 기준 develop 브랜치
- Claude Code v2.1.75 (Opus 4.6)로 자동 분석
---
## 2. 프로젝트 규모
### 2.1 전체 수치
| 항목 | 수량 | 비고 |
|------|------|------|
| **엔드포인트** | ~1,400개 | 19개 도메인 라우트 파일 |
| **컨트롤러** | 152개 | V1 144개 + Admin 1개 + Equipment 7개 |
| **서비스** | 202개 | 22개 도메인 폴더 + 루트 98개 |
| **모델** | 261개 | 32개 도메인 폴더 |
| **FormRequest** | 305개 | 42개 도메인 폴더 |
| **마이그레이션** | 545개 | 메인 523 + 통계 22 |
| **미들웨어** | 10개 | |
| **아티산 커맨드** | 39개 | |
| **옵저버** | 15개 | 감사/이벤트 처리 |
| **Swagger 문서** | 110개 | OpenAPI 스펙 |
| **테스트** | 14개 | Feature 11 + Unit 3 |
| **PHP 코드** | 179,010줄 | |
### 2.2 도메인별 엔드포인트 분포
| 도메인 | 엔드포인트 | 비중 | 핵심 기능 |
|--------|:---------:|:----:|----------|
| Finance | 271 | 19% | 카드, 계좌, 입출금, 급여, 세금계산서, 바로빌 |
| HR | 153 | 11% | 부서, 직원, 근태, 휴가, 전자결재, 시공관리 |
| Sales | 135 | 10% | 거래처, 견적, 입찰, 수주, 단가, 데모테넌트 |
| Common | 134 | 10% | 메뉴, 권한, 카테고리, 대시보드, 알림 |
| Inventory | 85 | 6% | 품목, BOM, 자재, 입고, 배차 |
| Boards | 84 | 6% | 게시판, 품목기준관리(ItemMaster) |
| Production | 73 | 5% | 공정, 작업지시, 작업실적, 검사 |
| Design | 61 | 4% | 모델, 버전, BOM 템플릿, 계산 엔진 |
| Quality | 36 | 3% | 품질관리, 검사, 인증 |
| Users | 34 | 2% | 프로필, 역할, 테넌트 전환 |
| Admin | 29 | 2% | 테넌트, 메뉴, FCM, API Key |
| Equipment | 27 | 2% | 설비, 정비 |
| Tenants | 23 | 2% | 테넌트 설정, 구독 |
| Files | 21 | 2% | 업로드, 저장 |
| Documents | 18 | 1% | 템플릿, 생성 |
| ESign | 18 | 1% | 전자서명 워크플로우 |
| Auth | 9 | 1% | 로그인, 토큰 |
| Stats | 9 | 1% | 통계/리포트 |
| Audit | 7 | 0.5% | 감사 로그 |
---
## 3. 아키텍처 분석
### 3.1 3대 설계 원칙
```
┌─────────────────────────────────────────────────────┐
│ 1. Service-First 패턴 │
│ Controller (라우팅만) → Service (로직) → Model │
│ Controller에 비즈니스 로직 작성 금지 │
├─────────────────────────────────────────────────────┤
│ 2. Multi-Tenant (tenant_id 기반) │
│ BelongsToTenant 트레이트 → 자동 WHERE 필터링 │
│ 1명 사용자가 여러 테넌트 접근 가능 │
├─────────────────────────────────────────────────────┤
│ 3. 5계층 보안 │
│ Nginx → Rate Limit → API Key → Sanctum → 권한 │
│ 메뉴 기반 RBAC (7가지 권한 타입) │
└─────────────────────────────────────────────────────┘
```
### 3.2 요청 처리 흐름
```
HTTP Request
↓
Nginx (악성 경로 차단, Rate Limit)
↓
Middleware Stack
├─ ApiKeyMiddleware (X-API-KEY 검증)
├─ ApiVersionMiddleware (v1/v2 폴백)
├─ auth:sanctum (Bearer 토큰)
├─ PermMapper (메뉴→권한 매핑)
├─ CheckPermission (RBAC 체크)
└─ SetAuditSessionVariables (감사 추적)
↓
Controller (FormRequest 타입힌팅 → 자동 검증)
↓
Service (비즈니스 로직)
├─ tenantId() / apiUserId() 자동 제공
└─ Model (BelongsToTenant 자동 필터링)
↓
ApiResponse::handle() → JSON { success, message, data }
```
### 3.3 표준 테이블 구조
```sql
id BIGINT PK
tenant_id BIGINT FK -- 멀티테넌트 격리
-- 비즈니스 컬럼 (FK, WHERE/ORDER BY 대상만)
options JSON NULL -- 유연한 확장 속성
created_by BIGINT FK -- 감사 추적
updated_by BIGINT FK
deleted_by BIGINT FK
created_at TIMESTAMP
updated_at TIMESTAMP
deleted_at TIMESTAMP -- SoftDeletes
```
### 3.4 핵심 트레이트
| 트레이트 | 역할 | 적용 범위 |
|---------|------|----------|
| `BelongsToTenant` | tenant_id 자동 필터링 (Global Scope) | 모든 테넌트 모델 |
| `Auditable` | created_by, updated_by, deleted_by 자동 기록 | 모든 비즈니스 모델 |
| `ModelTrait` | is_active 스코프, 날짜 처리 | 모든 모델 |
| `SoftDeletes` | 논리 삭제 (물리 삭제 금지) | 모든 모델 |
### 3.5 주요 파일 위치
```
/home/aweso/sam/api/
├── app/
│ ├── Http/Controllers/Api/V1/ ← 컨트롤러 (144개)
│ ├── Http/Middleware/ ← 미들웨어 (10개)
│ ├── Http/Requests/ ← FormRequest (305개)
│ ├── Models/ ← 모델 (261개, 32개 폴더)
│ ├── Services/ ← 서비스 (202개, 22개 폴더)
│ ├── Traits/ ← 공용 트레이트 (6개)
│ ├── Observers/ ← 옵저버 (15개)
│ ├── Console/Commands/ ← 아티산 커맨드 (39개)
│ └── Swagger/v1/ ← API 문서 (110개)
├── routes/api/v1/ ← 도메인별 라우트 (19개)
├── database/migrations/ ← 마이그레이션 (545개)
├── config/ ← 설정 (24개)
└── tests/ ← 테스트 (14개)
```
---
## 4. 이관 현황
### 4.1 전체 현황
| 상태 | 수량 | 설명 |
|------|:----:|------|
| 이관 완료 | 24개 | API + React 모두 구현됨 |
| 이관 대상 (P1) | 15개 | 자금일정, 정산, VAT, 채번, 전자서명 등 |
| React UI만 필요 | 8개 | API 완료, UI 미구현 (QMS, 설비 등) |
| MNG 유지 | 11개 | PMIS, 신용평가, Dev Tools 등 |
### 4.2 이관 대상 우선순위
| Phase | 대상 | 우선순위 |
|-------|------|:-------:|
| Phase 1 | 자금일정, 일일자금, 정산, VAT, 채번, 전자서명 | 🔴 P1 |
| Phase 2 | 견적수식, 판매수수료, 전자서명 고도화 | 🟡 P2 |
| Phase 3 | QMS UI, 설비 UI, 요금제 UI | 🟡 P2 |
| Phase 4 | 휴가정책 자동부여, 통합근태 | 🟢 P3 |
---
## 5. 기술 부채 및 개선 로드맵
### 5.1 식별된 기술 부채
| ID | 영역 | 현황 | 영향도 | 우선순위 |
|:--:|------|------|:------:|:-------:|
| D1 | **테스트 부재** | 14개 (1,400 EP 대비 1%) | 🔴 높음 | P1 |
| D2 | **N+1 쿼리** | 일부 Service에서 반복 쿼리 | 🔴 높음 | P1 |
| D3 | **마이그레이션 정리** | 545개, 순서/네이밍 혼재 | 🟡 중간 | P2 |
| D4 | **i18n 미완** | 일부 에러에 직접 문자열 잔존 | 🟡 중간 | P2 |
| D5 | **FK 제약 과다** | Production 도메인 중심 | 🟡 중간 | P2 |
| D6 | **통계 DB 동기화** | sam_stat 수동/불완전 | 🟢 낮음 | P3 |
| D7 | **API 문서 최신화** | 110개 중 일부 outdated | 🟢 낮음 | P3 |
| D8 | **Rate Limiting** | 10회/분 고정, 도메인별 미세분화 | 🟢 낮음 | P3 |
### 5.2 개선 로드맵
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 P1 즉시 착수 (품질 기반 확보)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D1] 테스트 커버리지 확충
→ 핵심 도메인(Finance, Sales, HR) Feature 테스트 우선
→ 목표: 주요 CRUD + 비즈니스 로직 커버
[D2] N+1 쿼리 최적화
→ 대형 컨트롤러 5개 우선 점검
(ItemsBomController, WorkOrderController,
BarobillCardTransactionController,
ApprovalController, QuoteController)
→ Service에서 with() eager load 적용
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟡 P2 단기 개선 (안정성 강화)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D3] 마이그레이션 정리
→ squash 또는 네이밍 표준화
→ MNG 전용 마이그레이션 분리 확인
[D4] i18n 완성
→ 직접 문자열 → message key 전환
→ grep으로 잔존 문자열 스캔
[D5] FK 제약 최적화
→ Production 도메인 FK 관계 정리
→ 삭제 순서 복잡도 감소
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🟢 P3 중장기 (확장성)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[D6] 통계 DB 실시간화
→ Event Sourcing 또는 CDC 검토
[D7] Swagger 문서 최신화
→ 자동 생성 파이프라인 개선
[D8] Rate Limiting 동적화
→ 테넌트/도메인별 차등 적용
```
### 5.3 강점 (유지해야 할 것)
```
✅ Service-First 패턴 — 일관된 비즈니스 로직 분리
✅ 5계층 보안 — Nginx ~ Permission까지 다층 방어
✅ BelongsToTenant — 멀티테넌트 자동 격리, 데이터 누출 방지
✅ Auditable — 모든 변경사항 자동 추적
✅ options JSON — 스키마 변경 없이 유연한 확장
✅ FormRequest 분리 — 305개 검증 클래스, 입력 검증 표준화
✅ ApiResponse::handle() — 통일된 응답 포맷
```
---
## 6. 진행 추적
> 아래 체크리스트로 개선 작업 진행 상황을 추적한다.
### P1 (즉시)
- [ ] [D1] 테스트 커버리지 확충 — 핵심 도메인 Feature 테스트
- [ ] [D2] N+1 쿼리 최적화 — 대형 컨트롤러 5개 점검
### P2 (단기)
- [ ] [D3] 마이그레이션 정리
- [ ] [D4] i18n 직접 문자열 제거
- [ ] [D5] FK 제약 최적화
### P3 (중장기)
- [ ] [D6] 통계 DB 실시간화
- [ ] [D7] Swagger 문서 최신화
- [ ] [D8] Rate Limiting 동적화
---
## 관련 문서
- [시스템 아키텍처](overview.md)
- [API 서버 구조](api-structure.md)
- [API 개발 규칙](../dev/standards/api-rules.md)
- [이관 현황](migration-status.md)
- [DB 스키마](database/README.md)
- [보안 정책](security-policy.md)
- [품질 체크리스트](../dev/standards/quality-checklist.md)
---
**최종 업데이트**: 2026-03-14

452
system/migration-status.md
View File

@@ -1,226 +1,226 @@
# MNG → API+React 이관 현황 및 로드맵
> **작성일**: 2026-03-12
> **상태**: 분석 완료, 로드맵 수립
> **담당**: R&D실
---
## 1. 개요
### 1.1 목적
MNG(관리자 웹)에서 API+React로 이관할 남은 항목을 식별하고, 멀티테넌시 적합도를 기준으로 실전 서비스 개발 우선순위를 수립한다.
### 1.2 현재 규모
| 프로젝트 | 규모 |
|----------|------|
| **MNG** | 컨트롤러 212개, 모델 227개, 서비스 113개 |
| **API** | 컨트롤러 100+, 모델 120+, 마이그레이션 130+ |
| **React** | 페이지 253개, 컴포넌트 36개 도메인 |
### 1.3 멀티테넌시 판단 기준
| 기준 | 이관 대상 | 이관 불필요 |
|------|----------|-----------|
| 2개+ 테넌트가 사용하는가? | 재무, 영업, 인사, 견적 | PMIS(특정 테넌트 전용) |
| `tenant_id` 격리가 의미 있는가? | 자금일정, 채번규칙, 수수료 | 신용평가, 개발도구 |
| SaaS 고객에게 제공 가치가 있는가? | 전자서명, 정산, VAT | 로드맵, R&D, 스크럼 |
| 관리자만 사용하는가? | 사용자도 씀 → 이관 | Dev Tools, 감사 추적 |
---
## 2. 이관 완료 도메인
API + React 모두 구현 완료된 기능이다.
| 도메인 | 완성도 | 비고 |
|--------|:------:|------|
| 인증/계정 | 100% | 로그인, 토큰, 회원가입 |
| 사용자/테넌트/부서 | 100% | 조직 관리 전체 |
| 역할/권한 | 100% | 3단계 권한 체계 |
| 메뉴 관리 | 100% | 글로벌/테넌트 메뉴 |
| 품목 관리 (Item) | 95% | BOM, 동적 필드 |
| 카테고리/공통코드 | 100% | 트리 구조, 동기화 |
| 거래처 (Client) | 95% | 그룹, OCR |
| 견적/수주/매출 | 90% | 견적서 PDF, 발송 |
| 입찰 (Bidding) | 90% | 상태 관리 |
| 단가 관리 (Pricing) | 90% | 일괄 등록 |
| 카드/계좌/입출금 | 90% | 바로빌 부분 연동 |
| 급여 (Payroll) | 85% | 계산, 확정, 지급 |
| 채권/거래처원장 | 85% | 조회, 메모 |
| 세금계산서 | 85% | 발행, 홈택스 |
| 근태/휴가/직원 | 85% | 출퇴근, 연차 |
| 전자결재 | 80% | 양식, 결재선, 위임 |
| 게시판 | 80% | 커스텀 필드, 댓글 |
| 파일/문서 관리 | 80% | 업로드, 공유, 버전 |
| 생산 (공정/작업지시) | 80% | 작업일지, 자재 투입 |
| 재고 (구매/입고/출하) | 80% | 배차, Lot 추적 |
| 설계/BOM | 75% | 모델 버전, 계산 엔진 |
| 대시보드 | 90% | CEO 포함 5가지 타입 |
| 현장관리 (Site) | 75% | 현장설명회, 계약 |
| 바로빌 (기본) | 70% | 카드/계좌 연동 |
---
## 3. 미이관 항목 분석
### 3.1 멀티테넌트 이관 대상 (P1~P2)
실전 서비스에서 복수 테넌트가 사용할 핵심 기능이다.
| # | 기능 | MNG 컨트롤러 | 적합도 | 우선순위 |
|---|------|-------------|:------:|:--------:|
| 1 | 자금일정 (Fund Schedule) | `FundScheduleController` | 높음 | P1 |
| 2 | 일일자금 (Daily Fund) | `DailyFundController` | 높음 | P1 |
| 3 | 미지급금 (Payable) | `PayableController` | 높음 | P1 |
| 4 | 부가세 (VAT) | `VatRecordController` | 높음 | P1 |
| 5 | 정산 (Settlement) | `SettlementController` | 높음 | P1 |
| 6 | 환불 (Refund) | `RefundController` | 높음 | P1 |
| 7 | 채번규칙 (Numbering Rule) | `NumberingRuleController` | 높음 | P1 |
| 8 | 견적수식 (Quote Formula) | `QuoteFormulaController` | 높음 | P1 |
| 9 | 전자서명 (eSign) | `EsignController` 외 2개 | 높음 | P1 |
| 10 | 분개기록 (Journal Entry) | `JournalEntryController` | 중간 | P2 |
| 11 | 구독관리 (Subscription) | `SubscriptionController` | 중간 | P2 |
| 12 | 판매수수료 | `SalesCommissionController` | 중간 | P2 |
| 13 | 휴가정책 (Leave Promotion) | `LeavePromotionController` | 중간 | P2 |
| 14 | 통합근태 | `AttendanceIntegratedController` | 중간 | P2 |
| 15 | 사업소득자 | `BusinessIncomeEarnerController` | 중간 | P2 |
> **참고**: API에 `ExpectedExpense`(미지급비용), `GeneralJournalEntry`(일반전표)가 이미 존재한다. MNG 버전과 기능 범위가 다르므로 비교 후 보강한다.
### 3.2 MNG 전용 (이관 불필요)
관리자 전용이거나 특정 테넌트에 국한되어 멀티테넌트 이관 가치가 낮은 기능이다.
| # | 기능 | MNG 컨트롤러 수 | 사유 |
|---|------|:--------------:|------|
| 1 | PMIS 시공관리 | 12개 | 특정 테넌트 건설 전용, `Juil/` 네임스페이스 |
| 2 | 신용평가 (Credit) | 1개 | 외부 API 연동, 관리자 전용 |
| 3 | Dev Tools | 2개 | API Explorer, Flow Tester (개발자 전용) |
| 4 | 추가 기능 | 5개 | Kiosk, Notion, RAG, Docx, Pptx (유틸리티) |
| 5 | 튜토리얼 비디오 | 1개 | 관리자 콘텐츠 관리 |
| 6 | 로드맵/R&D | 2개 | 내부 기획 도구 |
| 7 | 일일 스크럼 | 1개 | 내부 개발팀 도구 |
| 8 | 감사 로그/트리거 추적 | 3개 | 관리자 감사 도구 (API 읽기전용 API만 검토) |
**후순위** (규모별 차이가 커서 범용성 낮음):
| # | 기능 | 비고 |
|---|------|------|
| 9 | 경조사비/회사차량/차량일지 | 회사 규모별 차이 큼 |
| 10 | 명함 요청 | 마이너 기능 |
| 11 | 면접 시나리오 | 영업 내부 도구 |
### 3.3 React UI 보강 대상
API는 완료되었으나 React 화면이 미구현 또는 부분 구현된 기능이다.
| # | 기능 | API | React | 우선순위 |
|---|------|:---:|:-----:|:--------:|
| 1 | 품질관리 (QMS) | 완료 | 개발중 | P1 |
| 2 | 설비/장비 (Equipment) | 완료 | 개발중 | P1 |
| 3 | 어음 관리 (Bill) | 완료 | 미구현 | P2 |
| 4 | 가지급금 (Loan) | 완료 | 미구현 | P2 |
| 5 | 요금제/결제 | 완료 | 부분 | P1 |
| 6 | 캘린더 일정 | 완료 | 부분 | P2 |
| 7 | AI 보고서 | 완료 | 부분 | P2 |
| 8 | 팝업 관리 | 완료 | 부분 | P3 |
---
## 4. 실전 서비스 이관 로드맵
### Phase 1: 핵심 재무 (즉시 착수)
테넌트가 실제 업무에 필수적으로 사용하는 재무 기능이다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 1-1 | 자금일정 + 일일자금 | API 신규 + React 신규 | 높음 |
| 1-2 | 정산 (Settlement) | API 신규 + React 신규 | 높음 |
| 1-3 | 환불 (Refund) | API 신규 + React 신규 | 중간 |
| 1-4 | 부가세 (VAT) | API 신규 + React 신규 | 높음 |
| 1-5 | 채번규칙 | API 신규 + React 설정화면 | 중간 |
### Phase 2: 영업/견적 고도화
견적 자동화와 수수료 체계를 구축한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 2-1 | 견적수식 (Quote Formula) | API 신규 + React 신규 | 매우 높음 |
| 2-2 | 판매수수료 | API 신규 + React 신규 | 높음 |
| 2-3 | 전자서명 (eSign) | API 신규 + React 신규 | 매우 높음 |
### Phase 3: React UI 보강
API는 완료되어 있으므로 React 화면만 구현한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 3-1 | 품질관리 (QMS) | React 신규 | 높음 |
| 3-2 | 설비/장비 | React 신규 | 중간 |
| 3-3 | 어음/가지급금 | React 신규 | 중간 |
| 3-4 | 요금제/결제 화면 | React 보강 | 중간 |
### Phase 4: 인사 고도화
기본 HR은 완료되어 있으며, 정책/통합 기능을 추가한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 4-1 | 휴가정책 자동부여 | API 보강 + React | 중간 |
| 4-2 | 통합근태 | API 신규 + React | 높음 |
| 4-3 | 사업소득자/지급 | API 신규 + React | 중간 |
---
## 5. 이관 작업 시 공통 체크리스트
### API 이관 시
- [ ] `tenant_id` 기반 멀티테넌트 격리 적용
- [ ] MNG HTMX 코드 → REST API로 분리
- [ ] 마이그레이션 소유 기준 확인 (API 전용/공용 → API, MNG 전용 → MNG)
- [ ] `options` JSON 컬럼 정책 준수
- [ ] Service-First 아키텍처 (Controller → Service → Model)
- [ ] FormRequest 검증 적용
- [ ] Swagger 문서 작성
### React 이관 시
- [ ] Server Actions 패턴 사용 (`executePaginatedAction`, `executeServerAction`)
- [ ] `createCrudService` 팩토리 활용 (반복 코드 제거)
- [ ] Zod 스키마 검증 적용
- [ ] `FormField` molecule 사용
- [ ] 기존 `UniversalListPage` 템플릿 활용
- [ ] 모바일 반응형 고려 (`MobileCard`)
---
## 6. 수량 요약
| 분류 | 항목 수 | 비고 |
|------|:-------:|------|
| 이관 완료 | 24개 도메인 | API + React 모두 존재 |
| 이관 대상 (P1) | 9개 기능 | Phase 1~2 |
| 이관 대상 (P2) | 6개 기능 | Phase 2~4 |
| MNG 유지 | 11개 기능 | 관리자/특정 테넌트 전용 |
| React UI 보강 | 8개 기능 | API 완료, UI 미구현 |
---
## 관련 문서
- [system/overview.md](overview.md) — 전체 시스템 아키텍처
- [system/api-structure.md](api-structure.md) — API 서버 구조
- [system/react-structure.md](react-structure.md) — React 프론트엔드 구조
- [system/mng-structure.md](mng-structure.md) — MNG 관리자 패널 구조
- [dev/standards/api-rules.md](../dev/standards/api-rules.md) — API 개발 규칙
- [dev/standards/options-column-policy.md](../dev/standards/options-column-policy.md) — options JSON 정책
---
**최종 업데이트**: 2026-03-12
# MNG → API+React 이관 현황 및 로드맵
> **작성일**: 2026-03-12
> **상태**: 분석 완료, 로드맵 수립
> **담당**: R&D실
---
## 1. 개요
### 1.1 목적
MNG(관리자 웹)에서 API+React로 이관할 남은 항목을 식별하고, 멀티테넌시 적합도를 기준으로 실전 서비스 개발 우선순위를 수립한다.
### 1.2 현재 규모
| 프로젝트 | 규모 |
|----------|------|
| **MNG** | 컨트롤러 212개, 모델 227개, 서비스 113개 |
| **API** | 컨트롤러 100+, 모델 120+, 마이그레이션 130+ |
| **React** | 페이지 253개, 컴포넌트 36개 도메인 |
### 1.3 멀티테넌시 판단 기준
| 기준 | 이관 대상 | 이관 불필요 |
|------|----------|-----------|
| 2개+ 테넌트가 사용하는가? | 재무, 영업, 인사, 견적 | PMIS(특정 테넌트 전용) |
| `tenant_id` 격리가 의미 있는가? | 자금일정, 채번규칙, 수수료 | 신용평가, 개발도구 |
| SaaS 고객에게 제공 가치가 있는가? | 전자서명, 정산, VAT | 로드맵, R&D, 스크럼 |
| 관리자만 사용하는가? | 사용자도 씀 → 이관 | Dev Tools, 감사 추적 |
---
## 2. 이관 완료 도메인
API + React 모두 구현 완료된 기능이다.
| 도메인 | 완성도 | 비고 |
|--------|:------:|------|
| 인증/계정 | 100% | 로그인, 토큰, 회원가입 |
| 사용자/테넌트/부서 | 100% | 조직 관리 전체 |
| 역할/권한 | 100% | 3단계 권한 체계 |
| 메뉴 관리 | 100% | 글로벌/테넌트 메뉴 |
| 품목 관리 (Item) | 95% | BOM, 동적 필드 |
| 카테고리/공통코드 | 100% | 트리 구조, 동기화 |
| 거래처 (Client) | 95% | 그룹, OCR |
| 견적/수주/매출 | 90% | 견적서 PDF, 발송 |
| 입찰 (Bidding) | 90% | 상태 관리 |
| 단가 관리 (Pricing) | 90% | 일괄 등록 |
| 카드/계좌/입출금 | 90% | 바로빌 부분 연동 |
| 급여 (Payroll) | 85% | 계산, 확정, 지급 |
| 채권/거래처원장 | 85% | 조회, 메모 |
| 세금계산서 | 85% | 발행, 홈택스 |
| 근태/휴가/직원 | 85% | 출퇴근, 연차 |
| 전자결재 | 80% | 양식, 결재선, 위임 |
| 게시판 | 80% | 커스텀 필드, 댓글 |
| 파일/문서 관리 | 80% | 업로드, 공유, 버전 |
| 생산 (공정/작업지시) | 80% | 작업일지, 자재 투입 |
| 재고 (구매/입고/출하) | 80% | 배차, Lot 추적 |
| 설계/BOM | 75% | 모델 버전, 계산 엔진 |
| 대시보드 | 90% | CEO 포함 5가지 타입 |
| 현장관리 (Site) | 75% | 현장설명회, 계약 |
| 바로빌 (기본) | 70% | 카드/계좌 연동 |
---
## 3. 미이관 항목 분석
### 3.1 멀티테넌트 이관 대상 (P1~P2)
실전 서비스에서 복수 테넌트가 사용할 핵심 기능이다.
| # | 기능 | MNG 컨트롤러 | 적합도 | 우선순위 |
|---|------|-------------|:------:|:--------:|
| 1 | 자금일정 (Fund Schedule) | `FundScheduleController` | 높음 | P1 |
| 2 | 일일자금 (Daily Fund) | `DailyFundController` | 높음 | P1 |
| 3 | 미지급금 (Payable) | `PayableController` | 높음 | P1 |
| 4 | 부가세 (VAT) | `VatRecordController` | 높음 | P1 |
| 5 | 정산 (Settlement) | `SettlementController` | 높음 | P1 |
| 6 | 환불 (Refund) | `RefundController` | 높음 | P1 |
| 7 | 채번규칙 (Numbering Rule) | `NumberingRuleController` | 높음 | P1 |
| 8 | 견적수식 (Quote Formula) | `QuoteFormulaController` | 높음 | P1 |
| 9 | 전자서명 (eSign) | `EsignController` 외 2개 | 높음 | P1 |
| 10 | 분개기록 (Journal Entry) | `JournalEntryController` | 중간 | P2 |
| 11 | 구독관리 (Subscription) | `SubscriptionController` | 중간 | P2 |
| 12 | 판매수수료 | `SalesCommissionController` | 중간 | P2 |
| 13 | 휴가정책 (Leave Promotion) | `LeavePromotionController` | 중간 | P2 |
| 14 | 통합근태 | `AttendanceIntegratedController` | 중간 | P2 |
| 15 | 사업소득자 | `BusinessIncomeEarnerController` | 중간 | P2 |
> **참고**: API에 `ExpectedExpense`(미지급비용), `GeneralJournalEntry`(일반전표)가 이미 존재한다. MNG 버전과 기능 범위가 다르므로 비교 후 보강한다.
### 3.2 MNG 전용 (이관 불필요)
관리자 전용이거나 특정 테넌트에 국한되어 멀티테넌트 이관 가치가 낮은 기능이다.
| # | 기능 | MNG 컨트롤러 수 | 사유 |
|---|------|:--------------:|------|
| 1 | PMIS 시공관리 | 12개 | 특정 테넌트 건설 전용, `Juil/` 네임스페이스 |
| 2 | 신용평가 (Credit) | 1개 | 외부 API 연동, 관리자 전용 |
| 3 | Dev Tools | 2개 | API Explorer, Flow Tester (개발자 전용) |
| 4 | 추가 기능 | 5개 | Kiosk, Notion, RAG, Docx, Pptx (유틸리티) |
| 5 | 튜토리얼 비디오 | 1개 | 관리자 콘텐츠 관리 |
| 6 | 로드맵/R&D | 2개 | 내부 기획 도구 |
| 7 | 일일 스크럼 | 1개 | 내부 개발팀 도구 |
| 8 | 감사 로그/트리거 추적 | 3개 | 관리자 감사 도구 (API 읽기전용 API만 검토) |
**후순위** (규모별 차이가 커서 범용성 낮음):
| # | 기능 | 비고 |
|---|------|------|
| 9 | 경조사비/회사차량/차량일지 | 회사 규모별 차이 큼 |
| 10 | 명함 요청 | 마이너 기능 |
| 11 | 면접 시나리오 | 영업 내부 도구 |
### 3.3 React UI 보강 대상
API는 완료되었으나 React 화면이 미구현 또는 부분 구현된 기능이다.
| # | 기능 | API | React | 우선순위 |
|---|------|:---:|:-----:|:--------:|
| 1 | 품질관리 (QMS) | 완료 | 개발중 | P1 |
| 2 | 설비/장비 (Equipment) | 완료 | 개발중 | P1 |
| 3 | 어음 관리 (Bill) | 완료 | 미구현 | P2 |
| 4 | 가지급금 (Loan) | 완료 | 미구현 | P2 |
| 5 | 요금제/결제 | 완료 | 부분 | P1 |
| 6 | 캘린더 일정 | 완료 | 부분 | P2 |
| 7 | AI 보고서 | 완료 | 부분 | P2 |
| 8 | 팝업 관리 | 완료 | 부분 | P3 |
---
## 4. 실전 서비스 이관 로드맵
### Phase 1: 핵심 재무 (즉시 착수)
테넌트가 실제 업무에 필수적으로 사용하는 재무 기능이다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 1-1 | 자금일정 + 일일자금 | API 신규 + React 신규 | 높음 |
| 1-2 | 정산 (Settlement) | API 신규 + React 신규 | 높음 |
| 1-3 | 환불 (Refund) | API 신규 + React 신규 | 중간 |
| 1-4 | 부가세 (VAT) | API 신규 + React 신규 | 높음 |
| 1-5 | 채번규칙 | API 신규 + React 설정화면 | 중간 |
### Phase 2: 영업/견적 고도화
견적 자동화와 수수료 체계를 구축한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 2-1 | 견적수식 (Quote Formula) | API 신규 + React 신규 | 매우 높음 |
| 2-2 | 판매수수료 | API 신규 + React 신규 | 높음 |
| 2-3 | 전자서명 (eSign) | API 신규 + React 신규 | 매우 높음 |
### Phase 3: React UI 보강
API는 완료되어 있으므로 React 화면만 구현한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 3-1 | 품질관리 (QMS) | React 신규 | 높음 |
| 3-2 | 설비/장비 | React 신규 | 중간 |
| 3-3 | 어음/가지급금 | React 신규 | 중간 |
| 3-4 | 요금제/결제 화면 | React 보강 | 중간 |
### Phase 4: 인사 고도화
기본 HR은 완료되어 있으며, 정책/통합 기능을 추가한다.
| 순서 | 기능 | 작업 범위 | 복잡도 |
|:----:|------|----------|:------:|
| 4-1 | 휴가정책 자동부여 | API 보강 + React | 중간 |
| 4-2 | 통합근태 | API 신규 + React | 높음 |
| 4-3 | 사업소득자/지급 | API 신규 + React | 중간 |
---
## 5. 이관 작업 시 공통 체크리스트
### API 이관 시
- [ ] `tenant_id` 기반 멀티테넌트 격리 적용
- [ ] MNG HTMX 코드 → REST API로 분리
- [ ] 마이그레이션 소유 기준 확인 (API 전용/공용 → API, MNG 전용 → MNG)
- [ ] `options` JSON 컬럼 정책 준수
- [ ] Service-First 아키텍처 (Controller → Service → Model)
- [ ] FormRequest 검증 적용
- [ ] Swagger 문서 작성
### React 이관 시
- [ ] Server Actions 패턴 사용 (`executePaginatedAction`, `executeServerAction`)
- [ ] `createCrudService` 팩토리 활용 (반복 코드 제거)
- [ ] Zod 스키마 검증 적용
- [ ] `FormField` molecule 사용
- [ ] 기존 `UniversalListPage` 템플릿 활용
- [ ] 모바일 반응형 고려 (`MobileCard`)
---
## 6. 수량 요약
| 분류 | 항목 수 | 비고 |
|------|:-------:|------|
| 이관 완료 | 24개 도메인 | API + React 모두 존재 |
| 이관 대상 (P1) | 9개 기능 | Phase 1~2 |
| 이관 대상 (P2) | 6개 기능 | Phase 2~4 |
| MNG 유지 | 11개 기능 | 관리자/특정 테넌트 전용 |
| React UI 보강 | 8개 기능 | API 완료, UI 미구현 |
---
## 관련 문서
- [system/overview.md](overview.md) — 전체 시스템 아키텍처
- [system/api-structure.md](api-structure.md) — API 서버 구조
- [system/react-structure.md](react-structure.md) — React 프론트엔드 구조
- [system/mng-structure.md](mng-structure.md) — MNG 관리자 패널 구조
- [dev/standards/api-rules.md](../dev/standards/api-rules.md) — API 개발 규칙
- [dev/standards/options-column-policy.md](../dev/standards/options-column-policy.md) — options JSON 정책
---
**최종 업데이트**: 2026-03-12

962
system/react-component-architecture.md
View File

@@ -1,481 +1,481 @@
# React 컴포넌트 아키텍처 현황
> **작성일**: 2026-03-12
> **상태**: 현황 분석 완료
> **관련 문서**: [react-structure.md](react-structure.md) — 전체 프로젝트 구조
---
## 1. 개요
### 1.1 목적
SAM React 프로젝트의 컴포넌트 아키텍처 현황을 기록한다. Atomic Design 폴더 구조를 채택했으나 **실제 계층적 의존성은 부분적으로만 작동**하고 있으며, 이 문서는 현실과 이상의 차이를 정리하여 신규 화면 개발 시 올바른 패턴을 참고하도록 한다.
### 1.2 기술 스택
| 계층 | 기술 | 설명 |
|------|------|------|
| UI 프리미티브 | Radix UI (13개 패키지) | 접근성 기반 헤드리스 컴포넌트 |
| 스타일 | shadcn/ui + Tailwind CSS v4 + CVA | 프로젝트 맞춤 커스터마이징 |
| 폼 | React Hook Form + Zod | 타입 안전한 검증 |
| 상태 | Zustand 5 + Immer | 전역 상태 (persist) |
| 아이콘 | Lucide React (550+) | |
| 차트 | Recharts v3 | |
| 에디터 | Tiptap | 리치텍스트 |
| 테마 | CSS 변수 + Zustand | light / dark / senior 3종 |
---
## 2. 폴더 구조
```
src/components/
├── ui/ ← shadcn/ui 프리미티브 (60개)
│ Button, Input, Select, Dialog, DatePicker,
│ CurrencyInput, PhoneInput, FileDropzone 등
│
├── atoms/ ← Atomic Design 원자 (3개)
│ BadgeSm, TabChip, ScrollableButtonGroup
│
├── molecules/ ← Atomic Design 분자 (13개)
│ FormField, StatusBadge, MobileCard,
│ DateRangeSelector, StandardDialog 등
│
├── organisms/ ← Atomic Design 유기체 (14개)
│ PageLayout, PageHeader, DataTable,
│ StatCards, EmptyState, SearchFilter 등
│
├── templates/ ← 페이지 템플릿 (5개, 2개 미사용)
│ UniversalListPage, IntegratedDetailTemplate,
│ IntegratedListTemplateV2
│
├── layout/ ← 전역 레이아웃
│ Sidebar, CommandMenuSearch, HeaderFavoritesBar
│
├── business/ ← 대시보드
├── accounting/ ← 회계 도메인
├── hr/ ← 인사 도메인
├── approval/ ← 전자결재 도메인
├── items/ ← 품목 도메인
├── production/ ← 생산 도메인
├── ... (도메인별 ~600개)
│
└── common/ ← 공통 (DataTable 독립 구현)
```
---
## 3. 실제 의존성 분석
### 3.1 이상 vs 현실
```
[이상적 Atomic Design]
Page → Templates → Organisms → Molecules → Atoms → ui/
[실제 구조]
Page ──→ Templates ──────────────────────→ ui/ (직접)
├─→ Organisms ──────────────────────→ ui/ (직접)
├─→ Molecules ──────────────────────→ ui/ (직접)
└─→ ui/ ────────────────────────────→ ui/ (직접)
계층 간 연결:
atoms → molecules: 2/13만 사용 (17%)
molecules → organisms: 0회 (완전 단절)
organisms → templates: 2회만 (PageLayout, PageHeader)
```
### 3.2 Import 비율 (전체 2,186회)
| 대상 | 횟수 | 비율 | 평가 |
|------|------|------|------|
| **ui/ 직접** | 1,831회 | **83.7%** | 압도적 |
| templates | 192회 | 8.8% | 핵심 2개 템플릿 |
| organisms | 148회 | 6.8% | PageLayout/MobileCard 중심 |
| molecules | 45회 | 2.1% | FormField/StatusBadge 중심 |
| atoms | 15회 | 0.7% | 거의 미사용 |
### 3.3 계층별 ui/ 의존
| 계층 | ui/ import 횟수 | atoms/molecules/organisms import | 비고 |
|------|----------------|--------------------------------|------|
| templates | 25회+ | 4회 | ui/ 직접 의존 |
| organisms | 25회+ | 0회 | molecules 완전 미사용 |
| molecules | 28회+ | 2회 (atoms) | 대부분 ui/ 직접 |
| 도메인 코드 | 1,700회+ | ~300회 | 83% ui/ 직접 |
---
## 4. 핵심 컴포넌트 사용 현황
### 4.1 고빈도 컴포넌트 (TOP 10)
| 순위 | 컴포넌트 | 계층 | 사용 횟수 | 역할 |
|------|---------|------|---------|------|
| 1 | `FormField` | molecules | 216회 | Label + Input 통합 |
| 2 | `UniversalListPage` | templates | 214회 | 목록 페이지 전체 |
| 3 | `IntegratedDetailTemplate` | templates | 182회 | 상세/폼 페이지 전체 |
| 4 | `MobileCard` | molecules+organisms | 172+129회 | 모바일 카드 |
| 5 | `StatusBadge` | molecules | 125회 | 상태 뱃지 |
| 6 | `PageLayout` | organisms | 67회 | 페이지 래퍼 |
| 7 | `BadgeSm` | atoms | 63회 | 소형 뱃지 |
| 8 | `PageHeader` | organisms | 56회 | 페이지 헤더 |
| 9 | `ListMobileCard` | organisms | 50회 | 모바일 목록 카드 |
| 10 | `DateRangeSelector` | molecules | 45회 | 날짜 범위 필터 |
### 4.2 미사용 컴포넌트
| 컴포넌트 | 계층 | 비고 |
|---------|------|------|
| `ListPageTemplate` | templates | 0회 — `UniversalListPage`로 대체됨 |
| `ResponsiveFormTemplate` | templates | 0회 — `IntegratedDetailTemplate`로 대체됨 |
### 4.3 저사용 컴포넌트 (5회 미만)
| 컴포넌트 | 계층 | 사용 횟수 |
|---------|------|---------|
| `FormActions` | organisms | 4회 |
| `ScreenVersionHistory` | organisms | 4회 |
---
## 5. 실제 페이지 개발 패턴
### 5.1 목록 페이지 (90%+ 사용 패턴)
```tsx
// 실제 도메인 코드 패턴
import { UniversalListPage } from '@/components/templates/UniversalListPage';
import { StatusBadge } from '@/components/molecules';
import { MobileCard } from '@/components/organisms/MobileCard';
import { Button } from '@/components/ui/button';
import { Dialog } from '@/components/ui/dialog';
```
`UniversalListPage`가 내부적으로 테이블, 페이지네이션, 검색 필터, 모바일 대응을 모두 포함한다.
### 5.2 상세/폼 페이지 (90%+ 사용 패턴)
```tsx
import { IntegratedDetailTemplate } from '@/components/templates/IntegratedDetailTemplate';
import { FormField } from '@/components/molecules/FormField';
import { Input } from '@/components/ui/input';
import { Select } from '@/components/ui/select';
```
`IntegratedDetailTemplate`이 내부적으로 DetailField, DetailSection, DetailGrid, DetailActions 등 9개 하위 컴포넌트를 자체 포함한다.
### 5.3 도메인 폴더 내부 구조
```
src/components/accounting/BillManagement/
├── BillManagementClient.tsx ← 메인 컴포넌트
├── actions.ts ← Server Action (API 호출)
├── types.ts ← TypeScript 타입
├── billConfig.ts ← 설정, 필터 옵션
└── modals/ ← 하위 모달 컴포넌트
```
---
## 6. ui/ 컴포넌트 목록 (shadcn/ui 기반, 60개)
### 6.1 기본 UI
| 컴포넌트 | 설명 |
|---------|------|
| `button` | 6개 variant (default/destructive/outline/secondary/ghost/link), 4개 size |
| `input` | HTML input 래퍼, aria-invalid 지원 |
| `label` | HTML label 래퍼 |
| `card` | Card/CardHeader/CardTitle/CardContent/CardFooter |
| `badge` | 5개 variant |
| `alert` | Alert/AlertTitle/AlertDescription |
| `skeleton` | 로딩 스켈레톤 |
### 6.2 폼 입력
| 컴포넌트 | 설명 |
|---------|------|
| `checkbox` | Radix UI Checkbox |
| `radio-group` | Radix UI RadioGroup |
| `select` | Radix UI Select (검색 없음) |
| `switch` | Radix UI Switch |
| `slider` | Radix UI Slider |
| `date-picker` | 날짜 선택 |
| `date-range-picker` | 날짜 범위 |
| `date-time-picker` | 날짜+시간 |
| `file-input` | 파일 선택 |
| `file-dropzone` | 드래그앤드롭 파일 |
| `image-upload` | 이미지 업로드 |
| `multi-select-combobox` | 다중 선택 콤보박스 |
| `searchable-select` | 검색 가능 셀렉트 |
### 6.3 한국형 입력 (자동 포맷팅)
| 컴포넌트 | 포맷 | 용도 |
|---------|------|------|
| `phone-input` | `010-1234-5678` | 전화번호 |
| `business-number-input` | `123-45-67890` | 사업자등록번호 |
| `personal-number-input` | `123456-7890123` | 주민번호 |
| `account-number-input` | 은행별 포맷 | 계좌번호 |
| `card-number-input` | `1234 5678 9012 3456` | 카드번호 |
| `currency-input` | `1,234,567` | 금액 (천단위) |
| `quantity-input` | 정수 | 수량 |
| `number-input` | 소수점 | 숫자 |
### 6.4 오버레이/피드백
| 컴포넌트 | 설명 |
|---------|------|
| `dialog` | Radix UI Dialog |
| `alert-dialog` | 확인/취소 다이얼로그 |
| `drawer` | Vaul 드로어 |
| `sheet` | 사이드 패널 |
| `popover` | Radix UI Popover |
| `tooltip` | Radix UI Tooltip |
| `dropdown-menu` | Radix UI DropdownMenu |
| `confirm-dialog` | 커스텀 확인 다이얼로그 |
| `command` | cmdk 커맨드 팔레트 |
| `loading-spinner` | 스피너 |
| `progress` | Radix UI Progress |
| `sonner` | 토스트 알림 |
### 6.5 레이아웃/데이터
| 컴포넌트 | 설명 |
|---------|------|
| `table` | HTML table 래퍼 |
| `tabs` | Radix UI Tabs |
| `accordion` | Radix UI Accordion |
| `collapsible` | Radix UI Collapsible |
| `scroll-area` | Radix UI ScrollArea |
---
## 7. 테마 시스템
### 7.1 3가지 테마
| 테마 | 클래스 | 특징 |
|------|--------|------|
| Light | `:root` (기본) | 밝은 배경, 표준 글자 크기 |
| Dark | `.dark` | 어두운 배경, 밝은 글자 |
| Senior | `.senior` | 큰 글자(18px), 높은 대비, 굵은 폰트 |
### 7.2 CSS 변수 체계
```css
:root {
--primary: #3B82F6; /* 주 색상 */
--destructive: #EF4444; /* 위험/삭제 */
--background: #FAFAFA; /* 배경 */
--card: #FFFFFF; /* 카드 배경 */
--border: #E2E8F0; /* 테두리 */
/* 60+ 색상 변수 */
}
.dark { --background: #0F172A; --primary: #60A5FA; ... }
.senior { --font-size: 18px; --font-weight-medium: 600; ... }
```
### 7.3 Tailwind variant
```css
@variant dark (&:is(.dark *));
@variant senior (&:is(.senior *));
```
코드에서 `dark:bg-slate-800 senior:text-lg` 형태로 사용한다.
### 7.4 상태 관리
```
Zustand (themeStore) → document.documentElement.className 변경
→ localStorage persist (새로고침 유지)
```
---
## 8. 모바일 반응형 전략
### 8.1 자동 전환
| 뷰포트 | 표시 방식 |
|--------|----------|
| 768px 이상 (md:) | `DataTable` (테이블) |
| 768px 미만 | `MobileCard` / `ListMobileCard` (카드 목록) |
### 8.2 핵심 모바일 컴포넌트
| 컴포넌트 | 용도 | 사용 횟수 |
|---------|------|---------|
| `MobileCard` (molecules) | 필터/정보 카드 | 172회 |
| `MobileCard` (organisms) | 상세 조회 카드 | 129회 |
| `ListMobileCard` | 목록 카드 | 50회 |
| `MobileFilter` | 모바일 필터 | 14회 |
### 8.3 iOS Safe Area
```css
:root {
--safe-area-inset-top: env(safe-area-inset-top, 0px);
--safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
}
```
Capacitor 기반 모바일 앱 대응이 포함되어 있다.
---
## 9. 폼 패턴
### 9.1 신규 폼 (권장 패턴)
```tsx
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
const schema = z.object({
name: z.string().min(1, '필수'),
amount: z.number().min(0),
status: z.enum(['active', 'inactive']),
});
type FormData = z.infer<typeof schema>;
export function MyForm() {
const form = useForm<FormData>({
resolver: zodResolver(schema),
defaultValues: { name: '', amount: 0, status: 'active' },
});
return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
}
```
### 9.2 CVA 기반 variant 시스템
```tsx
import { cva } from 'class-variance-authority';
const buttonVariants = cva(
'inline-flex items-center justify-center gap-2 rounded-md',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground',
destructive: 'bg-destructive text-white',
outline: 'border bg-background',
ghost: 'hover:bg-accent',
},
size: {
default: 'h-9 px-4 py-2',
sm: 'h-8 px-3',
lg: 'h-10 px-6',
icon: 'size-9',
},
},
}
);
```
---
## 10. 신규 화면 개발 가이드
### 10.1 목록 페이지 작성 시
```
1. UniversalListPage 사용 (목록 90%+ 커버)
2. 도메인 폴더에 actions.ts, types.ts, config.ts 분리
3. StatusBadge로 상태 표시
4. MobileCard 렌더 함수 정의 (모바일 대응)
5. 추가 UI는 ui/ 에서 직접 import
```
### 10.2 상세/폼 페이지 작성 시
```
1. IntegratedDetailTemplate 사용 (상세/폼 90%+ 커버)
2. FormField로 Label + Input 조합 (일관성)
3. Zod 스키마 정의 (검증)
4. 추가 UI는 ui/ 에서 직접 import
```
### 10.3 Import 우선순위
```
1순위: templates (UniversalListPage, IntegratedDetailTemplate)
2순위: molecules (FormField, StatusBadge, DateRangeSelector)
3순위: organisms (PageLayout, PageHeader, EmptyState)
4순위: ui/ (Button, Dialog, Input 등 프리미티브)
```
> atoms는 현재 3개뿐이므로 필요 시 ui/에서 직접 사용한다.
### 10.4 하지 말 것
```
❌ ListPageTemplate 사용 (dead code — UniversalListPage 사용)
❌ ResponsiveFormTemplate 사용 (dead code — IntegratedDetailTemplate 사용)
❌ 새 atoms 만들기 (ui/ 컴포넌트로 충분)
❌ 도메인 코드에서 다른 도메인 컴포넌트 import
```
---
## 11. 현황 평가 요약
### 11.1 잘 작동하는 부분
| 항목 | 설명 |
|------|------|
| **2개 핵심 템플릿** | `UniversalListPage`(214회) + `IntegratedDetailTemplate`(182회)가 전체 페이지의 90%+ 커버 |
| **shadcn/ui 기반 ui/** | 60개 프리미티브가 일관된 디자인 시스템 제공 |
| **고빈도 molecules** | `FormField`(216회), `StatusBadge`(125회)가 폼/상태 표시 표준화 |
| **모바일 대응** | MobileCard 기반 자동 전환 |
| **테마 시스템** | light/dark/senior 3종 CSS 변수 기반 |
| **한국형 입력** | 전화번호, 사업자번호, 계좌번호 등 자동 포맷팅 |
### 11.2 개선이 필요한 부분
| 항목 | 현상 | 영향 |
|------|------|------|
| **계층 간 의존성 붕괴** | organisms가 molecules를 0회 사용 | Atomic Design 의미 퇴색 |
| **atoms 유명무실** | 3개만 존재, ui/ 60개에 비해 극소 | 계층 존재 이유 불분명 |
| **ui/ 과의존** | 전체 import의 83.7% | 추상화 효과 없음 |
| **Dead code** | ListPageTemplate, ResponsiveFormTemplate 미사용 | 혼란 유발 |
| **index.ts 비일관** | atoms/templates는 index.ts 미사용 | import 패턴 불통일 |
### 11.3 결론
**실제 아키텍처는 "Templates + UI Components" 2계층 구조**이다.
```
실제 작동 구조:
Layer 1 — 페이지 템플릿 (2개가 전체 지배)
├── UniversalListPage ← 목록 페이지
└── IntegratedDetailTemplate ← 상세/폼 페이지
Layer 2 — UI 프리미티브 (shadcn/ui)
└── ui/ 60개 컴포넌트 ← 모든 곳에서 직접 사용
보조 — molecules (FormField, StatusBadge 등 고빈도 유틸)
보조 — organisms (PageLayout, PageHeader, MobileCard)
```
Atomic Design 폴더명(atoms/molecules/organisms/templates)은 유지되어 있으나, 실제 개발 시에는 **templates → ui/ 직접 사용** 패턴을 따르는 것이 현실적이다.
---
## 관련 문서
- [React 프론트엔드 구조](react-structure.md) — 프로젝트 규모, 도메인, 아키텍처 패턴
- [API 서버 구조](api-structure.md) — API 서버 구조
- [MNG 관리자 패널 구조](mng-structure.md) — MNG 구조
---
**최종 업데이트**: 2026-03-12
# React 컴포넌트 아키텍처 현황
> **작성일**: 2026-03-12
> **상태**: 현황 분석 완료
> **관련 문서**: [react-structure.md](react-structure.md) — 전체 프로젝트 구조
---
## 1. 개요
### 1.1 목적
SAM React 프로젝트의 컴포넌트 아키텍처 현황을 기록한다. Atomic Design 폴더 구조를 채택했으나 **실제 계층적 의존성은 부분적으로만 작동**하고 있으며, 이 문서는 현실과 이상의 차이를 정리하여 신규 화면 개발 시 올바른 패턴을 참고하도록 한다.
### 1.2 기술 스택
| 계층 | 기술 | 설명 |
|------|------|------|
| UI 프리미티브 | Radix UI (13개 패키지) | 접근성 기반 헤드리스 컴포넌트 |
| 스타일 | shadcn/ui + Tailwind CSS v4 + CVA | 프로젝트 맞춤 커스터마이징 |
| 폼 | React Hook Form + Zod | 타입 안전한 검증 |
| 상태 | Zustand 5 + Immer | 전역 상태 (persist) |
| 아이콘 | Lucide React (550+) | |
| 차트 | Recharts v3 | |
| 에디터 | Tiptap | 리치텍스트 |
| 테마 | CSS 변수 + Zustand | light / dark / senior 3종 |
---
## 2. 폴더 구조
```
src/components/
├── ui/ ← shadcn/ui 프리미티브 (60개)
│ Button, Input, Select, Dialog, DatePicker,
│ CurrencyInput, PhoneInput, FileDropzone 등
│
├── atoms/ ← Atomic Design 원자 (3개)
│ BadgeSm, TabChip, ScrollableButtonGroup
│
├── molecules/ ← Atomic Design 분자 (13개)
│ FormField, StatusBadge, MobileCard,
│ DateRangeSelector, StandardDialog 등
│
├── organisms/ ← Atomic Design 유기체 (14개)
│ PageLayout, PageHeader, DataTable,
│ StatCards, EmptyState, SearchFilter 등
│
├── templates/ ← 페이지 템플릿 (5개, 2개 미사용)
│ UniversalListPage, IntegratedDetailTemplate,
│ IntegratedListTemplateV2
│
├── layout/ ← 전역 레이아웃
│ Sidebar, CommandMenuSearch, HeaderFavoritesBar
│
├── business/ ← 대시보드
├── accounting/ ← 회계 도메인
├── hr/ ← 인사 도메인
├── approval/ ← 전자결재 도메인
├── items/ ← 품목 도메인
├── production/ ← 생산 도메인
├── ... (도메인별 ~600개)
│
└── common/ ← 공통 (DataTable 독립 구현)
```
---
## 3. 실제 의존성 분석
### 3.1 이상 vs 현실
```
[이상적 Atomic Design]
Page → Templates → Organisms → Molecules → Atoms → ui/
[실제 구조]
Page ──→ Templates ──────────────────────→ ui/ (직접)
├─→ Organisms ──────────────────────→ ui/ (직접)
├─→ Molecules ──────────────────────→ ui/ (직접)
└─→ ui/ ────────────────────────────→ ui/ (직접)
계층 간 연결:
atoms → molecules: 2/13만 사용 (17%)
molecules → organisms: 0회 (완전 단절)
organisms → templates: 2회만 (PageLayout, PageHeader)
```
### 3.2 Import 비율 (전체 2,186회)
| 대상 | 횟수 | 비율 | 평가 |
|------|------|------|------|
| **ui/ 직접** | 1,831회 | **83.7%** | 압도적 |
| templates | 192회 | 8.8% | 핵심 2개 템플릿 |
| organisms | 148회 | 6.8% | PageLayout/MobileCard 중심 |
| molecules | 45회 | 2.1% | FormField/StatusBadge 중심 |
| atoms | 15회 | 0.7% | 거의 미사용 |
### 3.3 계층별 ui/ 의존
| 계층 | ui/ import 횟수 | atoms/molecules/organisms import | 비고 |
|------|----------------|--------------------------------|------|
| templates | 25회+ | 4회 | ui/ 직접 의존 |
| organisms | 25회+ | 0회 | molecules 완전 미사용 |
| molecules | 28회+ | 2회 (atoms) | 대부분 ui/ 직접 |
| 도메인 코드 | 1,700회+ | ~300회 | 83% ui/ 직접 |
---
## 4. 핵심 컴포넌트 사용 현황
### 4.1 고빈도 컴포넌트 (TOP 10)
| 순위 | 컴포넌트 | 계층 | 사용 횟수 | 역할 |
|------|---------|------|---------|------|
| 1 | `FormField` | molecules | 216회 | Label + Input 통합 |
| 2 | `UniversalListPage` | templates | 214회 | 목록 페이지 전체 |
| 3 | `IntegratedDetailTemplate` | templates | 182회 | 상세/폼 페이지 전체 |
| 4 | `MobileCard` | molecules+organisms | 172+129회 | 모바일 카드 |
| 5 | `StatusBadge` | molecules | 125회 | 상태 뱃지 |
| 6 | `PageLayout` | organisms | 67회 | 페이지 래퍼 |
| 7 | `BadgeSm` | atoms | 63회 | 소형 뱃지 |
| 8 | `PageHeader` | organisms | 56회 | 페이지 헤더 |
| 9 | `ListMobileCard` | organisms | 50회 | 모바일 목록 카드 |
| 10 | `DateRangeSelector` | molecules | 45회 | 날짜 범위 필터 |
### 4.2 미사용 컴포넌트
| 컴포넌트 | 계층 | 비고 |
|---------|------|------|
| `ListPageTemplate` | templates | 0회 — `UniversalListPage`로 대체됨 |
| `ResponsiveFormTemplate` | templates | 0회 — `IntegratedDetailTemplate`로 대체됨 |
### 4.3 저사용 컴포넌트 (5회 미만)
| 컴포넌트 | 계층 | 사용 횟수 |
|---------|------|---------|
| `FormActions` | organisms | 4회 |
| `ScreenVersionHistory` | organisms | 4회 |
---
## 5. 실제 페이지 개발 패턴
### 5.1 목록 페이지 (90%+ 사용 패턴)
```tsx
// 실제 도메인 코드 패턴
import { UniversalListPage } from '@/components/templates/UniversalListPage';
import { StatusBadge } from '@/components/molecules';
import { MobileCard } from '@/components/organisms/MobileCard';
import { Button } from '@/components/ui/button';
import { Dialog } from '@/components/ui/dialog';
```
`UniversalListPage`가 내부적으로 테이블, 페이지네이션, 검색 필터, 모바일 대응을 모두 포함한다.
### 5.2 상세/폼 페이지 (90%+ 사용 패턴)
```tsx
import { IntegratedDetailTemplate } from '@/components/templates/IntegratedDetailTemplate';
import { FormField } from '@/components/molecules/FormField';
import { Input } from '@/components/ui/input';
import { Select } from '@/components/ui/select';
```
`IntegratedDetailTemplate`이 내부적으로 DetailField, DetailSection, DetailGrid, DetailActions 등 9개 하위 컴포넌트를 자체 포함한다.
### 5.3 도메인 폴더 내부 구조
```
src/components/accounting/BillManagement/
├── BillManagementClient.tsx ← 메인 컴포넌트
├── actions.ts ← Server Action (API 호출)
├── types.ts ← TypeScript 타입
├── billConfig.ts ← 설정, 필터 옵션
└── modals/ ← 하위 모달 컴포넌트
```
---
## 6. ui/ 컴포넌트 목록 (shadcn/ui 기반, 60개)
### 6.1 기본 UI
| 컴포넌트 | 설명 |
|---------|------|
| `button` | 6개 variant (default/destructive/outline/secondary/ghost/link), 4개 size |
| `input` | HTML input 래퍼, aria-invalid 지원 |
| `label` | HTML label 래퍼 |
| `card` | Card/CardHeader/CardTitle/CardContent/CardFooter |
| `badge` | 5개 variant |
| `alert` | Alert/AlertTitle/AlertDescription |
| `skeleton` | 로딩 스켈레톤 |
### 6.2 폼 입력
| 컴포넌트 | 설명 |
|---------|------|
| `checkbox` | Radix UI Checkbox |
| `radio-group` | Radix UI RadioGroup |
| `select` | Radix UI Select (검색 없음) |
| `switch` | Radix UI Switch |
| `slider` | Radix UI Slider |
| `date-picker` | 날짜 선택 |
| `date-range-picker` | 날짜 범위 |
| `date-time-picker` | 날짜+시간 |
| `file-input` | 파일 선택 |
| `file-dropzone` | 드래그앤드롭 파일 |
| `image-upload` | 이미지 업로드 |
| `multi-select-combobox` | 다중 선택 콤보박스 |
| `searchable-select` | 검색 가능 셀렉트 |
### 6.3 한국형 입력 (자동 포맷팅)
| 컴포넌트 | 포맷 | 용도 |
|---------|------|------|
| `phone-input` | `010-1234-5678` | 전화번호 |
| `business-number-input` | `123-45-67890` | 사업자등록번호 |
| `personal-number-input` | `123456-7890123` | 주민번호 |
| `account-number-input` | 은행별 포맷 | 계좌번호 |
| `card-number-input` | `1234 5678 9012 3456` | 카드번호 |
| `currency-input` | `1,234,567` | 금액 (천단위) |
| `quantity-input` | 정수 | 수량 |
| `number-input` | 소수점 | 숫자 |
### 6.4 오버레이/피드백
| 컴포넌트 | 설명 |
|---------|------|
| `dialog` | Radix UI Dialog |
| `alert-dialog` | 확인/취소 다이얼로그 |
| `drawer` | Vaul 드로어 |
| `sheet` | 사이드 패널 |
| `popover` | Radix UI Popover |
| `tooltip` | Radix UI Tooltip |
| `dropdown-menu` | Radix UI DropdownMenu |
| `confirm-dialog` | 커스텀 확인 다이얼로그 |
| `command` | cmdk 커맨드 팔레트 |
| `loading-spinner` | 스피너 |
| `progress` | Radix UI Progress |
| `sonner` | 토스트 알림 |
### 6.5 레이아웃/데이터
| 컴포넌트 | 설명 |
|---------|------|
| `table` | HTML table 래퍼 |
| `tabs` | Radix UI Tabs |
| `accordion` | Radix UI Accordion |
| `collapsible` | Radix UI Collapsible |
| `scroll-area` | Radix UI ScrollArea |
---
## 7. 테마 시스템
### 7.1 3가지 테마
| 테마 | 클래스 | 특징 |
|------|--------|------|
| Light | `:root` (기본) | 밝은 배경, 표준 글자 크기 |
| Dark | `.dark` | 어두운 배경, 밝은 글자 |
| Senior | `.senior` | 큰 글자(18px), 높은 대비, 굵은 폰트 |
### 7.2 CSS 변수 체계
```css
:root {
--primary: #3B82F6; /* 주 색상 */
--destructive: #EF4444; /* 위험/삭제 */
--background: #FAFAFA; /* 배경 */
--card: #FFFFFF; /* 카드 배경 */
--border: #E2E8F0; /* 테두리 */
/* 60+ 색상 변수 */
}
.dark { --background: #0F172A; --primary: #60A5FA; ... }
.senior { --font-size: 18px; --font-weight-medium: 600; ... }
```
### 7.3 Tailwind variant
```css
@variant dark (&:is(.dark *));
@variant senior (&:is(.senior *));
```
코드에서 `dark:bg-slate-800 senior:text-lg` 형태로 사용한다.
### 7.4 상태 관리
```
Zustand (themeStore) → document.documentElement.className 변경
→ localStorage persist (새로고침 유지)
```
---
## 8. 모바일 반응형 전략
### 8.1 자동 전환
| 뷰포트 | 표시 방식 |
|--------|----------|
| 768px 이상 (md:) | `DataTable` (테이블) |
| 768px 미만 | `MobileCard` / `ListMobileCard` (카드 목록) |
### 8.2 핵심 모바일 컴포넌트
| 컴포넌트 | 용도 | 사용 횟수 |
|---------|------|---------|
| `MobileCard` (molecules) | 필터/정보 카드 | 172회 |
| `MobileCard` (organisms) | 상세 조회 카드 | 129회 |
| `ListMobileCard` | 목록 카드 | 50회 |
| `MobileFilter` | 모바일 필터 | 14회 |
### 8.3 iOS Safe Area
```css
:root {
--safe-area-inset-top: env(safe-area-inset-top, 0px);
--safe-area-inset-bottom: env(safe-area-inset-bottom, 0px);
}
```
Capacitor 기반 모바일 앱 대응이 포함되어 있다.
---
## 9. 폼 패턴
### 9.1 신규 폼 (권장 패턴)
```tsx
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
const schema = z.object({
name: z.string().min(1, '필수'),
amount: z.number().min(0),
status: z.enum(['active', 'inactive']),
});
type FormData = z.infer<typeof schema>;
export function MyForm() {
const form = useForm<FormData>({
resolver: zodResolver(schema),
defaultValues: { name: '', amount: 0, status: 'active' },
});
return <form onSubmit={form.handleSubmit(onSubmit)}>...</form>;
}
```
### 9.2 CVA 기반 variant 시스템
```tsx
import { cva } from 'class-variance-authority';
const buttonVariants = cva(
'inline-flex items-center justify-center gap-2 rounded-md',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground',
destructive: 'bg-destructive text-white',
outline: 'border bg-background',
ghost: 'hover:bg-accent',
},
size: {
default: 'h-9 px-4 py-2',
sm: 'h-8 px-3',
lg: 'h-10 px-6',
icon: 'size-9',
},
},
}
);
```
---
## 10. 신규 화면 개발 가이드
### 10.1 목록 페이지 작성 시
```
1. UniversalListPage 사용 (목록 90%+ 커버)
2. 도메인 폴더에 actions.ts, types.ts, config.ts 분리
3. StatusBadge로 상태 표시
4. MobileCard 렌더 함수 정의 (모바일 대응)
5. 추가 UI는 ui/ 에서 직접 import
```
### 10.2 상세/폼 페이지 작성 시
```
1. IntegratedDetailTemplate 사용 (상세/폼 90%+ 커버)
2. FormField로 Label + Input 조합 (일관성)
3. Zod 스키마 정의 (검증)
4. 추가 UI는 ui/ 에서 직접 import
```
### 10.3 Import 우선순위
```
1순위: templates (UniversalListPage, IntegratedDetailTemplate)
2순위: molecules (FormField, StatusBadge, DateRangeSelector)
3순위: organisms (PageLayout, PageHeader, EmptyState)
4순위: ui/ (Button, Dialog, Input 등 프리미티브)
```
> atoms는 현재 3개뿐이므로 필요 시 ui/에서 직접 사용한다.
### 10.4 하지 말 것
```
❌ ListPageTemplate 사용 (dead code — UniversalListPage 사용)
❌ ResponsiveFormTemplate 사용 (dead code — IntegratedDetailTemplate 사용)
❌ 새 atoms 만들기 (ui/ 컴포넌트로 충분)
❌ 도메인 코드에서 다른 도메인 컴포넌트 import
```
---
## 11. 현황 평가 요약
### 11.1 잘 작동하는 부분
| 항목 | 설명 |
|------|------|
| **2개 핵심 템플릿** | `UniversalListPage`(214회) + `IntegratedDetailTemplate`(182회)가 전체 페이지의 90%+ 커버 |
| **shadcn/ui 기반 ui/** | 60개 프리미티브가 일관된 디자인 시스템 제공 |
| **고빈도 molecules** | `FormField`(216회), `StatusBadge`(125회)가 폼/상태 표시 표준화 |
| **모바일 대응** | MobileCard 기반 자동 전환 |
| **테마 시스템** | light/dark/senior 3종 CSS 변수 기반 |
| **한국형 입력** | 전화번호, 사업자번호, 계좌번호 등 자동 포맷팅 |
### 11.2 개선이 필요한 부분
| 항목 | 현상 | 영향 |
|------|------|------|
| **계층 간 의존성 붕괴** | organisms가 molecules를 0회 사용 | Atomic Design 의미 퇴색 |
| **atoms 유명무실** | 3개만 존재, ui/ 60개에 비해 극소 | 계층 존재 이유 불분명 |
| **ui/ 과의존** | 전체 import의 83.7% | 추상화 효과 없음 |
| **Dead code** | ListPageTemplate, ResponsiveFormTemplate 미사용 | 혼란 유발 |
| **index.ts 비일관** | atoms/templates는 index.ts 미사용 | import 패턴 불통일 |
### 11.3 결론
**실제 아키텍처는 "Templates + UI Components" 2계층 구조**이다.
```
실제 작동 구조:
Layer 1 — 페이지 템플릿 (2개가 전체 지배)
├── UniversalListPage ← 목록 페이지
└── IntegratedDetailTemplate ← 상세/폼 페이지
Layer 2 — UI 프리미티브 (shadcn/ui)
└── ui/ 60개 컴포넌트 ← 모든 곳에서 직접 사용
보조 — molecules (FormField, StatusBadge 등 고빈도 유틸)
보조 — organisms (PageLayout, PageHeader, MobileCard)
```
Atomic Design 폴더명(atoms/molecules/organisms/templates)은 유지되어 있으나, 실제 개발 시에는 **templates → ui/ 직접 사용** 패턴을 따르는 것이 현실적이다.
---
## 관련 문서
- [React 프론트엔드 구조](react-structure.md) — 프로젝트 규모, 도메인, 아키텍처 패턴
- [API 서버 구조](api-structure.md) — API 서버 구조
- [MNG 관리자 패널 구조](mng-structure.md) — MNG 구조
---
**최종 업데이트**: 2026-03-12

332
system/untitled-ui-evaluation.md
View File

@@ -1,166 +1,166 @@
# Untitled UI 도입 검토
> **작성일**: 2026-03-12
> **상태**: 검토 중
> **작성자**: 개발팀장
---
## 1. 개요
### 1.1 목적
외부 UI 컴포넌트 라이브러리 **Untitled UI** 도입 여부를 검토한다. SAM 프로젝트의 현재 디자인 시스템(shadcn/ui + Tailwind CSS)과의 호환성, 비용 대비 효과, 도입 방안을 분석한다.
### 1.2 배경
SAM React 프론트엔드는 현재 shadcn/ui 60개 컴포넌트 + Atomic Design 구조로 운영 중이다. 디자인 품질 향상과 개발 속도 개선을 위해 상용 UI Kit 도입을 검토한다.
---
## 2. Untitled UI 소개
### 2.1 제품 개요
Untitled UI는 세계 최대 규모의 Figma UI Kit + React 컴포넌트 라이브러리이다. Atomic Design 시스템으로 유명하며, 디자이너와 개발자 모두를 위한 도구를 제공한다.
- **공식 사이트**: https://www.untitledui.com
- **핵심 특징**: Atomic Design 기반, 접근성(Accessibility) 준수, 반응형 지원
### 2.2 제품 구성 및 가격
| 제품 | 설명 | Free | Solo (1인) | Team (5인) |
|------|------|------|-----------|-----------|
| **Figma** | UI Kit / 디자인 시스템 | $0 | $129 | $359 |
| **React** | React + Tailwind CSS + React Aria 컴포넌트 | $0 | $349 | $699 |
| **Icons** | 4,600+ 아이콘 (다중 스타일) | $0 | $59 | $109 |
> **결제 방식**: 1회 결제 (one-time payment), 평생 업데이트 포함, 무제한 프로젝트 사용 가능
### 2.3 라이선스 구조
- **Solo**: 1명 사용, 무제한 프로젝트
- **Team**: 5명 사용, 무제한 프로젝트
- 디자이너와 개발자가 **다른 제품**을 각각 Solo로 구매하면 Team 불필요
---
## 3. SAM 현재 디자인 시스템과 비교
### 3.1 SAM 현재 스택
| 항목 | 현재 (SAM) | Untitled UI React |
|------|-----------|-------------------|
| UI 프리미티브 | shadcn/ui (60개) | Untitled UI 컴포넌트 |
| 스타일링 | Tailwind CSS v4 | Tailwind CSS |
| 접근성 | Radix UI | React Aria |
| 폼 | React Hook Form + Zod | (별도) |
| 아이콘 | Lucide React (550+) | 4,600+ (유료) |
| 테마 | CSS 변수 (light/dark/senior) | CSS 변수 기반 |
### 3.2 SAM 프론트엔드 현황 (참고)
- **페이지**: 249개
- **컴포넌트**: 612개 (shadcn/ui 기반)
- **핵심 템플릿**: `UniversalListPage` (214회), `IntegratedDetailTemplate` (182회)
- **고빈도 molecules**: `FormField` (216회), `StatusBadge` (125회)
- **프레임워크**: Next.js 15 + React 19
> 상세 현황: `docs/system/react-component-architecture.md` 참조
### 3.3 기술 호환성
| 항목 | 호환 여부 | 비고 |
|------|----------|------|
| Tailwind CSS | ✅ 호환 | 동일 스타일링 프레임워크 |
| React 19 | ✅ 호환 | React 기반 |
| Next.js 15 | ✅ 호환 | React 프레임워크이므로 문제 없음 |
| Radix UI ↔ React Aria | ⚠️ 공존 가능 | 접근성 라이브러리가 다름, 혼용 시 번들 증가 |
| shadcn/ui 기존 코드 | ⚠️ 점진적 교체 필요 | 612개 컴포넌트가 이미 구축됨 |
---
## 4. 도입 시 장단점 분석
### 4.1 장점
| 항목 | 설명 |
|------|------|
| 디자인 품질 | 전문 디자이너가 설계한 고품질 UI 패턴 |
| 디자인-개발 일관성 | Figma 시안 → React 코드 변환이 1:1 대응 |
| 시간 절약 | 새 화면 개발 시 프리셋 활용으로 속도 향상 |
| 접근성 | React Aria 기반의 체계적 접근성 지원 |
| 아이콘 | 4,600+ 다양한 스타일의 아이콘 |
| 업데이트 | 1회 결제로 평생 업데이트 |
### 4.2 단점
| 항목 | 설명 |
|------|------|
| 기존 코드 충돌 | shadcn/ui 612개 컴포넌트와 역할 중복 |
| 학습 비용 | 새 컴포넌트 API 학습 필요 |
| 번들 크기 | Radix UI + React Aria 공존 시 증가 |
| 마이그레이션 부담 | 전면 교체 시 비용 큼 |
| 커스텀 한계 | SAM 특화 컴포넌트(한국형 입력 등)는 자체 유지 필요 |
---
## 5. 추천 방안
### 5.1 방안 A: Figma만 구매 ($129) — 추천
```
디자이너 → Figma Solo ($129) 구매 → 시안 제작
개발자 → 기존 shadcn/ui 컴포넌트로 구현 (변경 없음)
```
**적합한 경우**:
- 디자이너가 합류하여 체계적 시안이 필요할 때
- 현재 React 코드를 유지하면서 디자인 품질만 높이고 싶을 때
- 가장 저렴하고 리스크 없는 방법
### 5.2 방안 B: Figma + React 모두 구매 ($478)
```
디자이너 → Figma Solo ($129) → 시안 제작
개발자 → React Solo ($349) → 새 화면에 Untitled UI 컴포넌트 사용
```
**적합한 경우**:
- 신규 프로젝트(MES 등)를 처음부터 Untitled UI로 시작할 때
- 기존 SAM 코드는 shadcn/ui 유지, 신규 코드만 Untitled UI 적용
### 5.3 방안 C: React만 구매 ($349)
```
개발자 → React Solo ($349) → 참고용 + 부분 적용
디자이너 → Figma Free 버전으로 참고
```
**적합한 경우**:
- 디자이너 없이 개발자가 직접 UI를 구현할 때
- 고급 컴포넌트 패턴을 참고 자료로 활용할 때
### 5.4 권장 결론
> **현재 상황**: 디자이너 부재, 612개 컴포넌트 이미 구축, SAM 기능 개발 진행 중
**단기 (현재)**: 도입 보류 — 기존 shadcn/ui 시스템이 잘 작동 중이며, 249 페이지가 이미 구축됨
**중기 (디자이너 합류 시)**: 방안 A (Figma $129) — 디자인 시안 품질 향상
**장기 (MES 등 신규 프로젝트)**: 방안 B ($478) — 신규 코드에 Untitled UI 적용 검토
---
## 6. SAM 내 디자인 관련 기존 자료
| 문서 | 경로 | 내용 |
|------|------|------|
| React 컴포넌트 아키텍처 | `system/react-component-architecture.md` | Atomic Design, shadcn/ui 60개, 의존성 분석 |
| React 프로젝트 구조 | `system/react-structure.md` | 249페이지, 612 컴포넌트 현황 |
| MES Atomic Design | `projects/mes/00_baseline/docs_breakdown/react_atomic_design_summary.md` | 100종 UI 패턴, 4단계 마이그레이션 |
| 디자인 인사이트 | `features/rd/design-insight.md` | UI/UX 패턴 수집, 100종 CSS 와이어프레임 |
| 기획디자인 에디터 | `projects/planning-design/README.md` | Figma 대체 목적 자체 스토리보드 에디터 |
---
**최종 업데이트**: 2026-03-12
# Untitled UI 도입 검토
> **작성일**: 2026-03-12
> **상태**: 검토 중
> **작성자**: 개발팀장
---
## 1. 개요
### 1.1 목적
외부 UI 컴포넌트 라이브러리 **Untitled UI** 도입 여부를 검토한다. SAM 프로젝트의 현재 디자인 시스템(shadcn/ui + Tailwind CSS)과의 호환성, 비용 대비 효과, 도입 방안을 분석한다.
### 1.2 배경
SAM React 프론트엔드는 현재 shadcn/ui 60개 컴포넌트 + Atomic Design 구조로 운영 중이다. 디자인 품질 향상과 개발 속도 개선을 위해 상용 UI Kit 도입을 검토한다.
---
## 2. Untitled UI 소개
### 2.1 제품 개요
Untitled UI는 세계 최대 규모의 Figma UI Kit + React 컴포넌트 라이브러리이다. Atomic Design 시스템으로 유명하며, 디자이너와 개발자 모두를 위한 도구를 제공한다.
- **공식 사이트**: https://www.untitledui.com
- **핵심 특징**: Atomic Design 기반, 접근성(Accessibility) 준수, 반응형 지원
### 2.2 제품 구성 및 가격
| 제품 | 설명 | Free | Solo (1인) | Team (5인) |
|------|------|------|-----------|-----------|
| **Figma** | UI Kit / 디자인 시스템 | $0 | $129 | $359 |
| **React** | React + Tailwind CSS + React Aria 컴포넌트 | $0 | $349 | $699 |
| **Icons** | 4,600+ 아이콘 (다중 스타일) | $0 | $59 | $109 |
> **결제 방식**: 1회 결제 (one-time payment), 평생 업데이트 포함, 무제한 프로젝트 사용 가능
### 2.3 라이선스 구조
- **Solo**: 1명 사용, 무제한 프로젝트
- **Team**: 5명 사용, 무제한 프로젝트
- 디자이너와 개발자가 **다른 제품**을 각각 Solo로 구매하면 Team 불필요
---
## 3. SAM 현재 디자인 시스템과 비교
### 3.1 SAM 현재 스택
| 항목 | 현재 (SAM) | Untitled UI React |
|------|-----------|-------------------|
| UI 프리미티브 | shadcn/ui (60개) | Untitled UI 컴포넌트 |
| 스타일링 | Tailwind CSS v4 | Tailwind CSS |
| 접근성 | Radix UI | React Aria |
| 폼 | React Hook Form + Zod | (별도) |
| 아이콘 | Lucide React (550+) | 4,600+ (유료) |
| 테마 | CSS 변수 (light/dark/senior) | CSS 변수 기반 |
### 3.2 SAM 프론트엔드 현황 (참고)
- **페이지**: 249개
- **컴포넌트**: 612개 (shadcn/ui 기반)
- **핵심 템플릿**: `UniversalListPage` (214회), `IntegratedDetailTemplate` (182회)
- **고빈도 molecules**: `FormField` (216회), `StatusBadge` (125회)
- **프레임워크**: Next.js 15 + React 19
> 상세 현황: `docs/system/react-component-architecture.md` 참조
### 3.3 기술 호환성
| 항목 | 호환 여부 | 비고 |
|------|----------|------|
| Tailwind CSS | ✅ 호환 | 동일 스타일링 프레임워크 |
| React 19 | ✅ 호환 | React 기반 |
| Next.js 15 | ✅ 호환 | React 프레임워크이므로 문제 없음 |
| Radix UI ↔ React Aria | ⚠️ 공존 가능 | 접근성 라이브러리가 다름, 혼용 시 번들 증가 |
| shadcn/ui 기존 코드 | ⚠️ 점진적 교체 필요 | 612개 컴포넌트가 이미 구축됨 |
---
## 4. 도입 시 장단점 분석
### 4.1 장점
| 항목 | 설명 |
|------|------|
| 디자인 품질 | 전문 디자이너가 설계한 고품질 UI 패턴 |
| 디자인-개발 일관성 | Figma 시안 → React 코드 변환이 1:1 대응 |
| 시간 절약 | 새 화면 개발 시 프리셋 활용으로 속도 향상 |
| 접근성 | React Aria 기반의 체계적 접근성 지원 |
| 아이콘 | 4,600+ 다양한 스타일의 아이콘 |
| 업데이트 | 1회 결제로 평생 업데이트 |
### 4.2 단점
| 항목 | 설명 |
|------|------|
| 기존 코드 충돌 | shadcn/ui 612개 컴포넌트와 역할 중복 |
| 학습 비용 | 새 컴포넌트 API 학습 필요 |
| 번들 크기 | Radix UI + React Aria 공존 시 증가 |
| 마이그레이션 부담 | 전면 교체 시 비용 큼 |
| 커스텀 한계 | SAM 특화 컴포넌트(한국형 입력 등)는 자체 유지 필요 |
---
## 5. 추천 방안
### 5.1 방안 A: Figma만 구매 ($129) — 추천
```
디자이너 → Figma Solo ($129) 구매 → 시안 제작
개발자 → 기존 shadcn/ui 컴포넌트로 구현 (변경 없음)
```
**적합한 경우**:
- 디자이너가 합류하여 체계적 시안이 필요할 때
- 현재 React 코드를 유지하면서 디자인 품질만 높이고 싶을 때
- 가장 저렴하고 리스크 없는 방법
### 5.2 방안 B: Figma + React 모두 구매 ($478)
```
디자이너 → Figma Solo ($129) → 시안 제작
개발자 → React Solo ($349) → 새 화면에 Untitled UI 컴포넌트 사용
```
**적합한 경우**:
- 신규 프로젝트(MES 등)를 처음부터 Untitled UI로 시작할 때
- 기존 SAM 코드는 shadcn/ui 유지, 신규 코드만 Untitled UI 적용
### 5.3 방안 C: React만 구매 ($349)
```
개발자 → React Solo ($349) → 참고용 + 부분 적용
디자이너 → Figma Free 버전으로 참고
```
**적합한 경우**:
- 디자이너 없이 개발자가 직접 UI를 구현할 때
- 고급 컴포넌트 패턴을 참고 자료로 활용할 때
### 5.4 권장 결론
> **현재 상황**: 디자이너 부재, 612개 컴포넌트 이미 구축, SAM 기능 개발 진행 중
**단기 (현재)**: 도입 보류 — 기존 shadcn/ui 시스템이 잘 작동 중이며, 249 페이지가 이미 구축됨
**중기 (디자이너 합류 시)**: 방안 A (Figma $129) — 디자인 시안 품질 향상
**장기 (MES 등 신규 프로젝트)**: 방안 B ($478) — 신규 코드에 Untitled UI 적용 검토
---
## 6. SAM 내 디자인 관련 기존 자료
| 문서 | 경로 | 내용 |
|------|------|------|
| React 컴포넌트 아키텍처 | `system/react-component-architecture.md` | Atomic Design, shadcn/ui 60개, 의존성 분석 |
| React 프로젝트 구조 | `system/react-structure.md` | 249페이지, 612 컴포넌트 현황 |
| MES Atomic Design | `projects/mes/00_baseline/docs_breakdown/react_atomic_design_summary.md` | 100종 UI 패턴, 4단계 마이그레이션 |
| 디자인 인사이트 | `features/rd/design-insight.md` | UI/UX 패턴 수집, 100종 CSS 와이어프레임 |
| 기획디자인 에디터 | `projects/planning-design/README.md` | Figma 대체 목적 자체 스토리보드 에디터 |
---
**최종 업데이트**: 2026-03-12