# API 서버 구조 현황

> **최종 갱신**: 2026-02-27
> **기술 스택**: Laravel 12 + PHP 8.4 + Sanctum + Spatie Permission + L5-Swagger

---

## 1. 프로젝트 규모

| 항목 | 수량 |
|------|------|
| API 엔드포인트 | ~1,027 |
| 컨트롤러 | 131 |
| 모델 | 220 |
| 서비스 | 180 |
| FormRequest | 271 |
| 미들웨어 | 9 |
| Swagger 문서 | 110 |
| 마이그레이션 | 459 |
| 설정 파일 | 22 |

---

## 2. 디렉토리 구조

```
app/
├── Http/
│   ├── Controllers/Api/
│   │   ├── Admin/              글로벌 메뉴 관리
│   │   └── V1/                 메인 API (131개)
│   │       ├── Admin/          FCM 관리
│   │       ├── Audit/          감사 로그
│   │       ├── Construction/   시공 (작업지시, 결과, 설정)
│   │       ├── Design/         설계 (모델, 버전, BOM 템플릿)
│   │       ├── Documents/      문서 (템플릿, 생성)
│   │       ├── ESign/          전자서명
│   │       ├── ItemMaster/     품목 마스터 (9개)
│   │       └── [104 Root Controllers]
│   ├── Middleware/              9개
│   └── Requests/               271개 (FormRequest)
├── Models/                     220개 (32개 도메인)
├── Services/                   180개
├── Swagger/v1/                 110개 (OpenAPI 문서)
├── Helpers/                    4개
├── Observers/                  5개
├── Traits/                     모델/감사 트레이트
└── Exceptions/                 2개
```

---

## 3. 라우트 도메인별 엔드포인트

| 라우트 파일 | 엔드포인트 | 주요 기능 |
|------------|-----------|----------|
| finance.php | 180 | 재무 (결제, 청구서, 세금계산서, 급여) |
| hr.php | 141 | 인사 (급여, 근태, 휴가, 대출) |
| common.php | 128 | 공통 (코드, 분류, 카테고리, 필드) |
| sales.php | 122 | 영업 (수주, 견적, 거래처, 출하) |
| boards.php | 84 | 게시판 (동적 필드 지원) |
| inventory.php | 79 | 재고 (자재, 입고, 창고) |
| production.php | 67 | 생산 (작업지시, 작업실적, 공정) |
| design.php | 61 | 설계 (모델, 버전, BOM 템플릿) |
| users.php | 34 | 사용자 (프로필, 역할, 초대) |
| admin.php | 29 | 관리자 (테넌트, 메뉴, FCM) |
| tenants.php | 23 | 테넌트 (전환, 프로필) |
| files.php | 20 | 파일 (업로드, 저장, 조회) |
| esign.php | 18 | 전자서명 워크플로우 |
| documents.php | 17 | 문서 (템플릿, 생성) |
| auth.php | 9 | 인증 (로그인, 로그아웃, 등록) |
| audit.php | 7 | 감사 (로그, 이력) |
| stats.php | 5 | 통계/리포트 |
| app.php | 3 | 앱 버전, 상태 체크 |
| **합계** | **~1,027** | |

```
routes/
├── api.php              메인 API 진입점
└── api/v1/
    ├── admin.php
    ├── app.php
    ├── audit.php
    ├── auth.php
    ├── boards.php
    ├── common.php
    ├── design.php
    ├── documents.php
    ├── esign.php
    ├── files.php
    ├── finance.php
    ├── hr.php
    ├── inventory.php
    ├── production.php
    ├── sales.php
    ├── stats.php
    ├── tenants.php
    └── users.php
```

---

## 4. 미들웨어

| 미들웨어 | 역할 |
|---------|------|
| ApiKeyMiddleware | API 키 인증 + Sanctum 토큰 검증 |
| ApiRateLimiter | API 속도 제한 |
| ApiVersionMiddleware | API 버전 라우팅 |
| CheckPermission | 권한 기반 접근 제어 |
| CheckSwaggerAuth | Swagger UI 인증 |
| CorsMiddleware | CORS 정책 |
| LogApiRequest | API 요청/응답 로깅 |
| PermMapper | 권한 매핑 변환 |
| SetAuditSessionVariables | 감사 세션 컨텍스트 |

---

## 5. 아키텍처 패턴

### 인증 체계
- **글로벌**: API Key (모든 요청)
- **사용자**: Sanctum Bearer Token (Access 120분, Refresh 7일)
- **내부**: HMAC (`INTERNAL_EXCHANGE_SECRET`, mng ↔ api)

### 응답 포맷
```json
{
  "success": true,
  "message": "message.key.from.lang",
  "data": { ... }
}
```
- `ApiResponse::handle()` 헬퍼로 통일

### 핵심 패턴
- **Service-First**: 비즈니스 로직 → Service 클래스
- **FormRequest 필수**: Controller에서 직접 검증 금지
- **BelongsToTenant**: 모든 비즈니스 모델에 tenant_id 격리
- **Auditable**: created_by, updated_by, deleted_by 자동 기록
- **SoftDeletes**: 대부분의 엔티티 논리 삭제

### 헬퍼

| 헬퍼 | 역할 |
|------|------|
| ApiResponse | JSON 응답 포맷 통일 |
| ItemTypeHelper | 품목 분류 로직 |
| Legacy5130Calculator | 레거시 5130 연동 계산 |
| TenantCodeGenerator | 테넌트별 코드 생성 |

---

## 6. 주요 의존성

| 패키지 | 버전 | 용도 |
|--------|------|------|
| laravel/framework | ^12.0 | 코어 프레임워크 |
| laravel/sanctum | ^4.0 | API 토큰 인증 |
| spatie/laravel-permission | ^6.21 | RBAC 권한 관리 |
| darkaonline/l5-swagger | ^9.0 | Swagger/OpenAPI 문서 |
| maatwebsite/excel | ^3.1 | Excel 가져오기/내보내기 |
| google/auth | ^1.49 | Google 인증 |
| doctrine/dbal | ^4.3 | DB 추상화 |

---

## 7. 설정

```
config/
├── app.php              앱 메타데이터
├── audit.php            감사 로깅 (13개월 보존)
├── auth.php             인증 (Sanctum, API 키)
├── authz.php            인가 + 권한
├── cors.php             CORS 정책
├── custom.php           커스텀 앱 설정
├── database.php         DB 연결 (samdb, sam_stat)
├── fcm.php              Firebase Cloud Messaging
├── l5-swagger.php       Swagger 설정
├── pagination.php       페이지네이션 기본값
├── permission.php       Spatie Permission
├── products.php         제품별 설정
├── sanctum.php          Sanctum 토큰 설정
└── [기타 8개]
```

---

## 8. api ↔ mng ↔ react 관계

```
react (dev.sam.kr)  ──Server Actions──→  api (api.sam.kr)  ←──DB 공유──→  mng (mng.sam.kr)
                                              │
                                         MySQL (samdb)
```

- **api**: DB 마이그레이션 유일 관리자 (459개). 모든 테이블 정의
- **mng**: 자체 모델 (185개), 마이그레이션 없음. 동일 DB 직접 접근
- **react**: Server Actions로 api 호출. DB 직접 접근 없음
- **내부 통신**: HMAC 기반 `INTERNAL_EXCHANGE_SECRET` (mng → api)
- **파일 공유**: mng가 api의 `storage/app/tenants` 마운트

### Swagger 문서
- 110개 OpenAPI 문서 파일
- 도메인별 태그 구성
- 보안 스키마: ApiKeyAuth + BearerAuth (Sanctum)
- URL: `api.sam.kr/api/documentation`