sam-docs/system/api-structure.md

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)

응답 포맷

{
  "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