From 87b1ed08d78f10be8ebaa7fa2de4ee2d52062e1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Sat, 14 Mar 2026 08:37:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[system]=20API=20=EA=B5=AC=EC=A1=B0=20?= =?UTF-8?q?=EB=B6=84=EC=84=9D=20=EB=B0=8F=20=EA=B0=9C=EC=84=A0=20=EB=A1=9C?= =?UTF-8?q?=EB=93=9C=EB=A7=B5=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 프로젝트 규모 정량 분석 (1,400 EP, 261 모델, 202 서비스) - 아키텍처 3대 원칙, 요청 처리 흐름, 표준 테이블 구조 - 기술 부채 8건 식별 (D1~D8) - P1~P3 우선순위별 개선 로드맵 수립 - INDEX.md에 문서 등록 --- INDEX.md | 2 + system/api-analysis-report.md | 289 ++++++++++++++++++++++++++++++++++ 2 files changed, 291 insertions(+) create mode 100644 system/api-analysis-report.md diff --git a/INDEX.md b/INDEX.md index bbbaa23..b25b163 100644 --- a/INDEX.md +++ b/INDEX.md @@ -30,6 +30,7 @@ | 서버 운영 | `dev/deploys/ops-manual/README.md` | 서버 운영 매뉴얼 | | 서버 접근/백업 | `system/server-access-management.md` | 계정, 권한, 백업, 리플리케이션 | | 이관 작업 | `system/migration-status.md` | MNG→API+React 이관 현황, 우선순위, 로드맵 | +| API 개선 로드맵 | `system/api-analysis-report.md` | API 구조 분석, 기술 부채 8건, P1~P3 개선 계획 | | MES | `projects/mes/README.md` | MES 프로젝트 | --- @@ -90,6 +91,7 @@ docs/ | [project-scale.md](system/project-scale.md) | 프로젝트 규모 현황 (코드 행 수, 파일 수) | | [item-master-integration.md](system/item-master-integration.md) | 품목 마스터 통합 설계 | | [erp-analysis/](system/erp-analysis/) | ERP 스토리보드 분석 | +| [api-analysis-report.md](system/api-analysis-report.md) | API 구조 분석 및 개선 로드맵 (기술 부채 8건, P1~P3) | DB 도메인별: diff --git a/system/api-analysis-report.md b/system/api-analysis-report.md new file mode 100644 index 0000000..30c50b3 --- /dev/null +++ b/system/api-analysis-report.md @@ -0,0 +1,289 @@ +# 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 표준 테이블 구조 + +```sql +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 동적화 + +--- + +## 관련 문서 + +- [시스템 아키텍처](overview.md) +- [API 서버 구조](api-structure.md) +- [API 개발 규칙](../dev/standards/api-rules.md) +- [이관 현황](migration-status.md) +- [DB 스키마](database/README.md) +- [보안 정책](security-policy.md) +- [품질 체크리스트](../dev/standards/quality-checklist.md) + +--- + +**최종 업데이트**: 2026-03-14