시스템 아키텍처 가이드

1. 전체 구조

                    ┌────────────────────────┐
                    │    Filament Admin      │  ← UI 계층
                    │  (Resources / Pages)   │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │    Laravel Routes      │  ← 라우팅
                    │   (web.php / api.php)  │
                    └───────────┬────────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          │                     │                       │
┌─────────▼──────────┐  ┌──────▼───────┐  ┌───────────▼──────────┐
│  Filament Resource │  │  API Controller│  │  PlanController     │
│  (Admin CRUD)      │  │  (REST API)    │  │  (문서 허브)         │
└─────────┬──────────┘  └──────┬───────┘  └──────────────────────┘
          │                     │
          └─────────┬───────────┘
                    │
          ┌─────────▼──────────┐
          │   Domain Services  │  ← 비즈니스 로직
          │  (InventoryService │
          │   OrderService     │
          │   PurchaseService) │
          └─────────┬──────────┘
                    │
          ┌─────────▼──────────┐
          │   Domain Models    │  ← 데이터 계층
          │   (Eloquent ORM)   │
          └─────────┬──────────┘
                    │
          ┌─────────▼──────────┐
          │     MariaDB        │  ← 저장소
          └────────────────────┘

2. 디렉토리 구조

app/
├── Domains/                    ← DDD 도메인 계층
│   ├── Product/
│   │   ├── Models/             (Product, ProductMapping)
│   │   ├── Imports/            (ProductImport)
│   │   └── Policies/          (ProductPolicy)
│   ├── Inventory/
│   │   ├── Enums/              (StockLogType, StockTakeStatus)
│   │   ├── Models/             (Inventory, InventoryAllocation, StockLog, StockTake*)
│   │   ├── Services/           (InventoryService, InventoryAnalysisService, SafetyStockService)
│   │   ├── Imports/            (InventoryImport)
│   │   └── Policies/          (InventoryPolicy, InventoryAllocationPolicy, StockTakePolicy)
│   ├── Order/
│   │   ├── Enums/              (OrderStatus, ReturnRequestStatus)
│   │   ├── Models/             (Order, OrderItem, ReturnRequest)
│   │   ├── Services/           (OrderService)
│   │   ├── Imports/            (OrderImport, OrderInvoiceImport, ShipmentImport)
│   │   └── Policies/          (OrderPolicy, ReturnRequestPolicy)
│   ├── Purchasing/
│   │   ├── Enums/              (PurchaseOrderStatus)
│   │   ├── Models/             (PurchaseOrder, PurchaseOrderItem, Supplier)
│   │   ├── Services/           (PurchaseService)
│   │   └── Policies/          (PurchaseOrderPolicy, SupplierPolicy)
│   └── SalesChannel/
│       ├── Models/             (SalesChannel)
│       └── Policies/          (SalesChannelPolicy)
│
├── Exports/                    ← 엑셀 내보내기 (Sample Templates)
├── Filament/                   ← Filament Admin Panel
│   └── Resources/              (15개 Resource — 아래 참조)
├── Http/
│   ├── Controllers/
│   │   ├── Api/V1/             (InventoryController, OrderController)
│   │   └── PlanController.php  (문서 허브)
│   ├── Middleware/              (AuthenticateApiKey)
│   ├── Requests/               (StoreOrderRequest 등)
│   └── Resources/              (API Resource 변환기)
├── Jobs/                       ← Queue 작업
├── Models/                     ← 공통 모델 (CommonCode, Setting, User)
├── Policies/                   ← 공통 정책
└── Providers/                  ← 서비스 프로바이더

3. Filament Resources (Admin 화면)

Resource	도메인	핵심 기능
ProductResource	Product	상품 CRUD + 공통코드 연결 + SKU 매핑
SalesChannelResource	SalesChannel	채널 관리 + API Key
InventoryResource	Inventory	재고 조회 + 입/출/조정 액션
AllocationResource	Inventory	채널별 재고 할당
InboundResource	Inventory	입고 관리
StockLogResource	Inventory	입출고 이력 조회
StockTakeResource	Inventory	재고 실사
AssetValueResource	Inventory	재고 자산 가치
MovementSummaryResource	Inventory	입출고 요약
OrderResource	Order	주문 관리 + 상태 탭 + Excel Import
ReturnRequestResource	Order	반품 관리
PurchaseOrderResource	Purchasing	구매 발주 관리
SupplierResource	Purchasing	공급업체 관리
CommonCodeResource	System	공통코드 (브랜드/카테고리/색상/단위)
UserResource	System	사용자 관리

4. 핵심 서비스 로직

4.1 InventoryService

재고 변동의 중심 서비스. 모든 재고 관련 작업은 DB 트랜잭션 + Stock Log 기록.

inbound() — 입고 처리 (quantity 증가 + IN 로그)
outbound() — 출고 처리 (quantity 감소 + OUT 로그)
adjust() — 수량 조정 (ADJUST 로그)
allocate() — 채널 할당 (ALLOCATE 로그)

4.2 OrderService

주문 상태 전이를 관리. OrderStatus Enum 사용:

Unpaid (0): 입금전
Paid (1): 입금완료
Preparing (2): 상품준비
ReadyToShip (9): 발송준비
Shipped (3): 발송완료
Cancelled (88): 취소

모든 상태값은 App\Domains\Order\Enums\OrderStatus Enum으로 관리됩니다.

4.3 PurchaseService

구매 발주 라이프사이클 관리.

Status: Draft → Ordered → Received → (또는 Cancelled)
입고 시 received_qty 업데이트 + Inventory 연동

4.4 SafetyStockService

안전재고 자동 계산 + 발주점 알림.

calculateAndApply() — Z-Score 기반 안전재고 자동 계산
checkReorderPoints() — 부족 재고 → Filament 알림 전송
스케줄러: UpdateSafetyStockJob → 매일 02:00 자동 실행

4.5 Activity Log

spatie/laravel-activitylog 기반 변경 이력 자동 추적.

적용 모델: Order, Product, Inventory, PurchaseOrder
설정: logAll(), logOnlyDirty() — 변경된 필드만 기록

5. API 계층

routes/api.php
  └── prefix('v1') + middleware(AuthenticateApiKey)
        ├── GET  /inventory        → InventoryController@index
        ├── GET  /inventory/{sku}  → InventoryController@show
        └── POST /orders           → OrderController@store

인증 흐름:

X-Api-Key 헤더 확인
sales_channels 테이블에서 api_key 매칭
매칭된 SalesChannel 객체를 $request->attributes에 주입
컨트롤러에서 채널 기반 데이터 필터링

6. 코드 규칙

PHP: 8.5 modern features (typed properties, match, enums)
모델: Eloquent relationship + return type hints
DB 접근: Model::query() 사용 (DB:: 금지)
캐스팅: casts() 메서드 사용
미들웨어: bootstrap/app.php에서 선언적 등록
테스트: PHPUnit (Pest 아님)
포매팅: Laravel Pint (--dirty 옵션)
프론트엔드: Tailwind CSS v4 (CSS-first @theme config)