권혁성
d4e5f62413
- system/overview.md: 전체 아키텍처 개요 - system/api-structure.md: API 구조 (220 모델, 1027 엔드포인트, 18 라우트 도메인) - system/react-structure.md: React 구조 (249 페이지, 612 컴포넌트) - system/mng-structure.md: MNG 구조 (171 컨트롤러, 436 Blade 뷰) - system/docker-setup.md: Docker 7 컨테이너 구성 - system/database/README.md + 9개 도메인 스키마 (270+ 테이블) - core, hr, sales, production, finance, boards, files, system, erp-analysis Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
208 lines
6.7 KiB
Markdown
208 lines
6.7 KiB
Markdown
# 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` |