# SAM API 전체 분석 보고서

> **작성일**: 2026-01-29
> **목적**: api/, mng/, react/ 프로젝트 간 API 중복/통합/미사용 분석 및 관계 정리
> **기준 문서**: api/routes/api/v1/*.php, mng/routes/api.php, mng/routes/web.php, react/src/lib/api/*
> **상태**: ✅ 분석 완료

---

## 📍 분석 결과 요약

| 항목 | 수치 |
|------|------|
| **api/ 엔드포인트** | ~710+ |
| **mng/ 엔드포인트** | ~300+ |
| **React 실제 사용** | ~80+ (api/ 전체의 ~15%) |
| **중복 도메인** | 10개 |
| **즉시 정리 가능** | 3건 |
| **통합 가능 그룹** | 6개 |

---

## 1. 개요

### 1.1 배경

SAM 프로젝트는 api/(REST API), mng/(관리자 패널), react/(프론트엔드) 3개 프로젝트로 구성되어 있으며, 각 프로젝트가 독립적으로 발전하면서 동일 도메인에 대한 API가 중복 생성되었다. 본 분석은 전체 API를 파악하고 정리 방안을 제시한다.

### 1.2 분석 범위

| 프로젝트 | 역할 | 분석 대상 |
|---------|------|----------|
| **api/** | REST API 서버 | routes/api/v1/*.php (14개 라우트 파일), 컨트롤러 138개 |
| **mng/** | 관리자 패널 | routes/api.php, routes/web.php, 컨트롤러 90+개 |
| **react/** | 프론트엔드 | src/lib/api/*, src/hooks/*, src/app/api/* |

---

## 2. 프로젝트별 API 구조

### 2.1 API 프로젝트 (api/)

**라우트 파일**: `api/routes/api/v1/`

| 도메인 | 라우트 파일 | 엔드포인트 수 | 소비자 |
|--------|-----------|:----------:|--------|
| 인증 | `auth.php` | 8 | React, MNG |
| 사용자 | `users.php` | 25 | React |
| 테넌트 | `tenants.php` | 18 | React |
| 관리자 | `admin.php` | 22 | React, MNG |
| 공통 | `common.php` | 95+ | React, MNG |
| HR | `hr.php` | 85+ | React |
| 재무 | `finance.php` | 130+ | React |
| 영업 | `sales.php` | 85+ | React |
| 재고 | `inventory.php` | 65+ | React |
| 생산 | `production.php` | 35+ | React |
| 설계 | `design.php` | 55+ | React |
| 파일 | `files.php` | 15 | React |
| 게시판 | `boards.php` | 70+ | React |
| 문서 | `documents.php` | 5+ | React |

### 2.2 MNG 프로젝트 (mng/)

**API 소비 방식**: 자체 모델로 DB 직접 접근 (api/ REST API를 거치지 않음)

| 도메인 | 엔드포인트 수 | 비고 |
|--------|:----------:|------|
| 사용자/역할/권한 | 30+ | api/와 중복 |
| 메뉴/글로벌메뉴 | 25+ | api/와 중복 |
| 게시판/필드 | 20+ | api/와 중복 |
| 카테고리/글로벌 | 15+ | api/와 중복 |
| 바로빌 (전체) | 60+ | MNG 전용 (외부 서비스) |
| 프로젝트 관리 | 25+ | MNG 전용 |
| 견적 공식 | 30+ | MNG 전용 |
| 품목 필드 | 25+ | MNG 전용 |
| 문서/템플릿 | 12+ | api/와 중복 |
| 계좌/자금일정 | 18+ | api/와 중복 |
| 기타 (회의록, 신용, 영업, Lab) | 40+ | MNG 전용 |

### 2.3 React 프론트엔드 (react/)

**API 호출 방식**: Next.js Proxy (`/api/proxy/*`) → Backend (`/api/v1/*`)

| 카테고리 | 주요 엔드포인트 | 사용 빈도 |
|---------|---------------|:--------:|
| 인증 | login, logout, refresh, signup | 높음 |
| 품목 CRUD | items, items/{id}, items/bom | 높음 |
| 품목기준관리 | item-master/* (pages, sections, fields) | 높음 |
| 견적 계산 | quotes/calculate, quotes/calculate/bom | 높음 |
| 공통코드 | settings/common/{group} | 높음 |
| 대시보드 | card-transactions/dashboard, loans/dashboard | 중간 |
| 알림 | today-issues/unread, unread/count | 중간 |
| 거래처 | clients, client-groups | 중간 |
| 재고 | stocks, work-results | 중간 |
| 일괄작업 | bulk-update-account-code | 낮음 |
| 내보내기 | attendances/export, salaries/export | 낮음 |

---

## 3. 중복 API 분석

### 3.1 중복 컨트롤러 목록 (api/ vs mng/)

| # | 도메인 | api/ 컨트롤러 | mng/ 컨트롤러 | 중복 수준 |
|---|--------|-------------|-------------|:--------:|
| 1 | 사용자 관리 | `Api\V1\Admin\AdminController` | `Api\Admin\UserController` | 🔴 높음 |
| 2 | 역할 관리 | `Api\V1\RoleController` | `Api\Admin\RoleController` | 🔴 높음 |
| 3 | 메뉴 관리 | `Api\V1\MenuController` | `Api\Admin\MenuController` | 🔴 높음 |
| 4 | 카테고리 | `Api\V1\CategoryController` | `Api\Admin\CategoryApiController` | 🔴 높음 |
| 5 | 계좌 관리 | `Api\V1\BankAccountController` | `Api\Admin\BankAccountController` | 🔴 높음 |
| 6 | 권한 관리 | `Api\V1\PermissionController` | `Api\Admin\PermissionController` | 🟡 중간 |
| 7 | 부서 관리 | `Api\V1\DepartmentController` | `Api\Admin\DepartmentController` | 🟡 중간 |
| 8 | 게시판 | `Api\V1\BoardController` | `Api\Admin\BoardController` | 🟡 중간 |
| 9 | 문서 | `Api\V1\Documents\DocumentController` | `Api\Admin\DocumentApiController` | 🟡 중간 |
| 10 | 테넌트 | `Api\V1\TenantController` | `Api\Admin\TenantController` | 🟡 중간 |

### 3.2 상세 비교

#### (1) 사용자 관리 🔴

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 기본 CRUD | ✅ | ✅ | 동일 |
| 복구 (restore) | ✅ | ✅ | 동일 |
| 비밀번호 초기화 | ✅ | ✅ | 동일 |
| 활성화/비활성화 | ✅ (PATCH /status) | ❌ | api/만 |
| 역할 부여/해제 | ✅ (POST/DELETE /roles) | ❌ | api/만 |
| 영구삭제 | ❌ | ✅ (DELETE /force) | mng/만 (슈퍼관리자) |
| 개발용 로그인토큰 | ❌ | ✅ (POST /login-token) | mng/만 |
| 모달 데이터 | ❌ | ✅ (GET /modal) | mng/만 |

#### (2) 역할 관리 🔴

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 기본 CRUD | ✅ | ✅ | 동일 |
| 통계 (stats) | ✅ | ❌ | api/만 |
| 활성 목록 (active) | ✅ | ❌ | api/만 |

#### (3) 메뉴 관리 🔴

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 기본 CRUD | ✅ | ✅ | 동일 |
| 순서변경 (reorder) | ✅ | ✅ | 동일 |
| 복구 (restore) | ✅ | ✅ | 동일 |
| 활성화 토글 | ✅ (toggle) | ✅ (toggle-active) | 동일 기능 |
| 동기화 | ✅ (sync, sync-new, sync-updates) | ❌ | api/만 |
| 트리 구조 | ❌ | ✅ (tree) | mng/만 |
| 글로벌 복사 | ❌ | ✅ (copy-from-global) | mng/만 |
| 일괄 작업 | ❌ | ✅ (bulk-delete/restore/force) | mng/만 |
| 숨김 토글 | ❌ | ✅ (toggle-hidden) | mng/만 |
| 영구삭제 | ❌ | ✅ (force) | mng/만 (슈퍼관리자) |

#### (4) 카테고리 🔴

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 기본 CRUD | ✅ | ✅ | 동일 |
| 트리/순서변경/이동 | ✅ | ✅ | 동일 |
| 활성화 토글 | ✅ | ✅ | 동일 |
| 필드 관리 | ✅ (fields CRUD, bulk-upsert) | ❌ | api/만 |
| 템플릿 관리 | ✅ (templates, apply, preview, diff) | ❌ | api/만 |
| 로그 조회 | ✅ (logs) | ❌ | api/만 |
| 글로벌 관리 | ❌ | ✅ (global-categories) | mng/만 |

#### (5) 계좌 관리 🔴

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 기본 CRUD | ✅ | ✅ | 동일 |
| 활성화 토글 | ✅ | ✅ | 동일 |
| 활성 목록 (active) | ✅ | ❌ | api/만 |
| 대표계좌 설정 | ✅ (set-primary) | ❌ | api/만 |
| 전체 조회 (all) | ❌ | ✅ | mng/만 |
| 요약 (summary) | ❌ | ✅ | mng/만 |
| 거래내역 | ❌ | ✅ (transactions) | mng/만 |
| 일괄 작업 | ❌ | ✅ (bulk-*) | mng/만 |
| 영구삭제/복구 | ❌ | ✅ (force/restore) | mng/만 |

#### (6) 권한 관리 🟡

| 기능 | api/ | mng/ | 차이 |
|------|:----:|:----:|------|
| 권한 매트릭스 조회 | ✅ (dept/role/user menu-matrix) | ❌ | api/만 (특화) |
| 기본 CRUD | ❌ | ✅ | mng/만 |

> **분석**: api/는 매트릭스 조회 전용, mng/는 CRUD 전용으로 기능 분리된 상태. 완전 중복은 아님.

---

## 4. 통합 가능 API

### 4.1 통합 대상 그룹

| # | 대상 | 현재 상태 | 통합 방안 | 우선순위 |
|---|------|----------|----------|:--------:|
| 1 | **인증 API** | signup + register 중복 | register 제거 (signup 유지) | 🔴 |
| 2 | **사용자 관리** | api/ + mng/ 각각 CRUD | mng/ → api/ 호출로 전환 | 🔴 |
| 3 | **역할 관리** | api/ + mng/ 각각 CRUD | api/에 통합, mng/는 호출만 | 🟡 |
| 4 | **메뉴 관리** | api/ 동기화 + mng/ 관리 분리 | 관리: mng/, 조회+동기화: api/ | 🟡 |
| 5 | **대시보드 데이터** | 개별 엔드포인트 분산 | 통합 대시보드 API 제공 | 🟢 |
| 6 | **일괄 업데이트** | withdrawals/deposits/sales 각각 | 공통 bulk-update 패턴 | 🟢 |

### 4.2 인증 API 중복 상세

```
현재:
  POST /v1/login              → 로그인
  POST /v1/logout             → 로그아웃
  POST /v1/signup             → 회원가입 (1)
  POST /v1/register           → 회원가입 (2) ← 중복!
  POST /v1/token-login        → 토큰 로그인 (MNG→DEV)
  POST /v1/refresh            → 토큰 갱신
  POST /v1/internal/exchange-token → 내부 서버 토큰 교환
  GET  /v1/debug-apikey       → 디버그용 ← 프로덕션 제거 필요

권장:
  - register 제거 (signup 유지)
  - debug-apikey 프로덕션 비활성화
```

---

## 5. 미사용 API

### 5.1 React에서 호출하지 않는 api/ 도메인

| 도메인 | 엔드포인트 수 | 미사용 이유 |
|--------|:----------:|-----------|
| HR 전체 (employees, attendance, leave, approval) | ~80+ | MNG에서 직접 관리 또는 React 미구현 |
| 생산 대부분 (processes, work-orders, inspections) | ~35+ | work-results만 사용 |
| 설계 전체 (models, versions, bom-templates) | ~55+ | 견적 계산 시 간접 사용만 |
| 재무 대부분 (cards, payroll, bad-debts 등) | ~100+ | CEO 대시보드 일부만 사용 |
| 사용자 초대 (invitations) | ~5 | React 미구현 |
| 알림 설정 (notification-settings) | ~5 | React 미구현 |
| 프로필 관리 (profiles) | ~5 | React 미구현 |
| 팝업 관리 (popups) | ~5 | React 미구현 |
| AI 리포트 (reports/ai) | ~4 | React 미구현 |
| 구독/결제 (subscriptions, payments) | ~20+ | React 미구현 |
| 현장/시공 (sites, construction) | ~30+ | React 미구현 |
| 검사 관리 (inspections) | ~8 | React 미구현 |

> **참고**: "미사용"은 React 프론트엔드 기준. MNG에서 Blade UI로 직접 사용하거나 향후 구현 예정인 경우 포함.

### 5.2 완전 미사용 가능성 높은 API

| 엔드포인트 | 이유 | 조치 권장 |
|-----------|------|----------|
| `GET /v1/debug-apikey` | 디버그 전용 | 프로덕션 비활성화 |
| `POST /v1/register` | signup과 중복 | 제거 |
| `GET /v1/welfare/*` | React/MNG 모두 미호출 확인 필요 | 사용 여부 확인 |
| `GET /v1/entertainment/*` | React/MNG 모두 미호출 확인 필요 | 사용 여부 확인 |
| `GET /v1/calendar/schedules` | React 미호출 | 사용 여부 확인 |
| `GET /v1/comprehensive-analysis` | React 미호출 | 사용 여부 확인 |

### 5.3 MNG 전용 기능 (정상)

| 기능 | 설명 | 상태 |
|------|------|:----:|
| 바로빌 (Barobill) | 전자세금계산서, 카드, 홈택스 연동 | ✅ 정상 |
| 프로젝트 관리 | 프로젝트, 태스크, 이슈 | ✅ 정상 |
| 데일리 로그 | 일일 스크럼 | ✅ 정상 |
| 견적 공식 | 견적 계산 공식 관리 | ✅ 정상 |
| 회의록 | 녹음, AI 요약 (Google Cloud) | ✅ 정상 |
| 신용 평가 | Coocon API 연동 | ✅ 정상 |
| 영업 관리 | 매니저, 전망, 기록 | ✅ 정상 |
| DevTools | API 탐색기, 흐름 테스터 | ✅ 정상 |
| Lab/R&D | AI, 전략 실험 | ✅ 정상 |

---

## 6. 프로젝트 간 API 관계도

### 6.1 시스템 구조

```
┌─────────────────────────────────────────────────────────────┐
│                      사용자 (브라우저)                         │
│                                                              │
│     ┌──────────────┐            ┌──────────────────┐         │
│     │  React App   │            │   MNG Admin      │         │
│     │ (dev.sam.kr) │            │  (mng.sam.kr)    │         │
│     └──────┬───────┘            └──────┬───────────┘         │
│            │                           │                     │
│     Next.js Proxy               자체 모델 직접 사용           │
│   (/api/proxy/*)              + 일부 api/ 호출               │
│            │                           │                     │
│            ▼                           │                     │
│     ┌──────────────┐                   │                     │
│     │   API 서버    │◄─────────────────┘                     │
│     │ (api.sam.kr)  │     token-login,                       │
│     │              │     DevTools API 탐색                    │
│     └──────┬───────┘                                         │
│            │                                                 │
│            ▼                                                 │
│     ┌──────────────┐                                         │
│     │   Database   │◄──── MNG도 동일 DB 직접 접근             │
│     │   (MySQL)    │                                         │
│     └──────────────┘                                         │
└─────────────────────────────────────────────────────────────┘

외부 API:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Google   │ │ Coocon   │ │  FCM     │ │   NTS    │
│ Cloud    │ │ (신용)   │ │ (푸시)   │ │ (홈택스)  │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
     └────────────┴────────────┴─────────────┘
                       │
                   MNG에서 호출
```

### 6.2 데이터 흐름

| 흐름 | 방식 | 설명 |
|------|------|------|
| React → API | HTTP (Proxy) | 모든 비즈니스 로직 API 호출 |
| MNG → DB | 직접 모델 | 관리 기능은 DB 직접 접근 |
| MNG → API | HTTP | token-login, DevTools, 일부 동기화 |
| MNG → 외부 | HTTP | Barobill, Google Cloud, Coocon, NTS |
| API → DB | 직접 모델 | 모든 비즈니스 로직 |

### 6.3 중복 발생 원인

```
문제: MNG가 api/를 호출하지 않고 DB 직접 접근
     → 동일 도메인에 대해 api/, mng/ 각각 독립 컨트롤러 보유
     → 비즈니스 로직 분산, 유지보수 부담 증가

현재:
  React  → api/ (REST API) → DB
  MNG    → DB 직접              ← 여기가 문제

이상적:
  React  → api/ (REST API) → DB
  MNG    → api/ (REST API) → DB  (관리자 전용 엔드포인트 추가)
```

---

## 7. 개선 권장사항

### 7.1 즉시 정리 (Quick Wins) 🔴

| # | 작업 | 영향 | 노력 |
|---|------|------|:----:|
| 1 | `POST /v1/register` 제거 (signup 유지) | 코드 정리 | 소 |
| 2 | `GET /v1/debug-apikey` 프로덕션 비활성화 | 보안 강화 | 소 |
| 3 | 미사용 Swagger 문서 정리 | 문서 정확성 | 소 |

### 7.2 중복 해소 (Medium Term) 🟡

| # | 작업 | 현재 | 목표 |
|---|------|------|------|
| 1 | 사용자 관리 통합 | api/ + mng/ 각각 | api/ 마스터, mng/ 관리자 기능만 추가 |
| 2 | 역할 관리 통합 | api/ + mng/ 각각 | api/ 단일 소스 |
| 3 | 카테고리 통합 | api/ + mng/ 각각 | api/ 마스터, mng/ 글로벌 관리만 유지 |
| 4 | 계좌 관리 통합 | api/ + mng/ 각각 | 하나로 통합 |
| 5 | 메뉴 관리 정리 | api/ 동기화 + mng/ 관리 | 역할 분리 명확화 |

### 7.3 아키텍처 개선 (Long Term) 🟢

| # | 작업 | 설명 |
|---|------|------|
| 1 | MNG → API 호출 전환 | MNG가 DB 직접 접근 대신 api/ REST API 호출 |
| 2 | API Gateway 도입 | 인증/권한/레이트리밋 중앙 관리 |
| 3 | 미사용 API 비활성화 | deprecation 헤더 추가 후 단계적 제거 |
| 4 | API v2 전환 | 중복 정리 포함한 v2 설계 |

---

## 8. 전체 엔드포인트 도메인별 수

### API 프로젝트

| 도메인 | 파일 | 수 |
|--------|------|:--:|
| 인증 | auth.php | 8 |
| 사용자 | users.php | 25 |
| 테넌트 | tenants.php | 18 |
| 관리자 | admin.php | 22 |
| 공통 | common.php | 95+ |
| HR | hr.php | 85+ |
| 재무 | finance.php | 130+ |
| 영업 | sales.php | 85+ |
| 재고 | inventory.php | 65+ |
| 생산 | production.php | 35+ |
| 설계 | design.php | 55+ |
| 파일 | files.php | 15 |
| 게시판 | boards.php | 70+ |
| 문서 | documents.php | 5+ |
| **합계** | | **~710+** |

### MNG 프로젝트

| 그룹 | 수 |
|------|:--:|
| 사용자/역할/권한 | 30+ |
| 메뉴/글로벌메뉴 | 25+ |
| 게시판/필드 | 20+ |
| 카테고리/글로벌 | 15+ |
| 바로빌 | 60+ |
| 프로젝트 관리 | 25+ |
| 견적 공식 | 30+ |
| 품목 필드 | 25+ |
| 문서/템플릿 | 12+ |
| 계좌/자금일정 | 18+ |
| 기타 | 40+ |
| **합계** | **~300+** |

---

## 9. 참고 문서

- `docs/standards/api-rules.md` - API 규칙
- `docs/architecture/system-overview.md` - 시스템 아키텍처
- `docs/specs/database-schema.md` - DB 스키마
- `api/routes/api/v1/*.php` - API 라우트 파일
- `mng/routes/api.php` - MNG API 라우트
- `react/src/lib/api/` - React API 클라이언트

---

## 10. 결론

1. **api/와 mng/의 10개 도메인에서 컨트롤러 중복** 발생 - 동일 DB를 각각 직접 접근하는 구조적 문제
2. **React는 api/ 전체의 약 15%만 사용** - 나머지는 MNG 전용이거나 미구현 기능
3. **인증 API에 signup/register 중복** 존재 - 즉시 정리 가능
4. **장기적으로 MNG → API 호출 전환**이 이상적이나, 현재 아키텍처도 기능적으로 동작
5. **Quick Wins(register 제거, debug-apikey 비활성화)부터 시작** 권장

---

*이 문서는 /sc:plan 스킬로 생성되었습니다.*