# 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