sam-docs/system/api-analysis-report.md

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 표준 테이블 구조

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 동적화

---

관련 문서

• 시스템 아키텍처
• API 서버 구조
• API 개발 규칙
• 이관 현황
• DB 스키마
• 보안 정책
• 품질 체크리스트

---

최종 업데이트: 2026-03-14