Lensnara SCM Project Dashboard

Lensnara SCM v1 - 프로젝트 기획서

0. Meta-Prompt (For AI Agent) New

You are now acting as:
Senior Backend Architect & Laravel Expert (10+ years of experience)

TASK:
Build the complete "Lensnara SCM v1" project from scratch, 100% based on the specification document at  

STRICT CONSTRAINTS (절대 위반 불가):

1. NO deviations from the "SCM Master" policy
   → 모든 기능, 테이블 구조, 비즈니스 로직, 기술 스택, 개발 일정은 기획서와 100% 일치해야 함
   → 기획서에 없는 기능은 절대 추가하지 말 것

2. MUST use PHP 8.4 modern features
   → Typed properties, readonly classes, readonly properties, enums, attributes, match expressions, first-class callable syntax 등 적극 활용
   → 모든 클래스, DTO, Value Object는 PHP 8.4 스타일로 작성

3. STRICTLY follow the exact Directory Structure defined in 기획서 Section 4
   → app/Domains/, app/Adapters/, app/DTOs/, app/Services/ 등 기획서에 명시된 구조 그대로 사용
   → 네임스페이스도 동일하게

4. IMPLEMENT functionality Phase by Phase exactly as defined in 기획서 Section 5 (6단계)
   → 1단계 → 2단계 → 3단계 → 4단계 → 5단계 → 6단계 순서로만 진행
   → 이전 단계가 100% 완료되고 검증된 후에만 다음 단계로 넘어감
   → 각 단계가 끝날 때마다 "Phase X 완료"라고 명확히 표시하고, 다음 단계를 시작

추가 기술 요구사항:
- 모든 비즈니스 로직은 Service 클래스 + Event/Listener + Queue Job 형태로 구현
- 재고 관련 모든 로직은 DB 트랜잭션 + Lock(forUpdate) 필수
- FIFO 출고는 입고일시 기준 오름차순 정확히 보장

시작 명령어:
"Phase 1 시작해줘" 라고 말하면 바로 1단계부터 차례대로 완성해 주세요.
각 단계마다 코드, 마이그레이션, 설정 파일까지 전부 포함해서 출력하고,
마크다운 코드 블록 + 파일 경로를 정확히 표시해 주세요.

프로젝트 정보

  • 프로젝트명: 렌즈나라 SCM
  • 코드명: Melon

1. 솔루션 개요 (Solution Overview)

1.1 솔루션 목적

Lensnara SCM은 다채널 주문 및 재고를 중앙에서 통합 관리하여 효율성을 극대화하는 것을 목적으로 합니다.

1.2 주요 목표

  • 전사적 자원 관리: 입고, 출고, 재고의 통합 관리
  • 자동화된 주문 처리: 여러 판매 채널의 주문 수집 및 자동 처리
  • 실시간 재고 동기화: 온/오프라인 채널 간 재고 불일치 최소화
  • 데이터 기반 의사결정: 판매 데이터 분석을 통한 발주 예측

1.3 운영 대원칙 (Grand Principles) New

"SCM은 쇼핑몰의 주문서만 수집하고, 재고의 기준은 SCM을 따른다."
(쇼핑몰 재고는 SCM에서 계산된 수량을 단방향으로 동기화함)

2. 핵심 기능 (Key Features)

2.1 상품 관리

  • 상품 마스터 관리 (등록/수정/삭제)
  • 바코드 및 SKU 관리 (자사몰/오픈마켓 매핑)
  • 안전 재고 설정 및 관리

2.2 재고 관리 핵심

  • 실시간 재고 현황 (창고별/위치별)
  • 입/출고 이력 추적 (Audit Log)
  • 재고 실사(Physical Count) 기능
  • 채널별 재고 할당(Allocation) 기능

2.3 주문 관리 핵심

  • 주문 수집 (API 연동/엑셀 업로드)
  • 주문 상태 관리 (결제완료 → 배송준비 → 배송중)
  • 송장 번호 자동 회신 및 동기화
  • CS 및 반품/교환 처리

2.4 대시보드/통계

  • 일별/월별 주문 현황
  • 재고 부족 알림
  • 판매량 분석 및 리포트
  • 기간별/상품별 매출 통계
  • 적정 발주량 추천 시스템

2.5 시스템 관리 (System) New

  • 사용자 계정 및 권한 관리 (ACL)
  • 공통 코드 및 기초 데이터 관리
  • 시스템 로그 및 접속 이력 모니터링

3. 기술 스택 (Tech Stack)

구분 기술 상세/버전
Styling Tailwind CSS v4.1.17 (Bleeding Edge) Installed
Backend PHP / Laravel PHP 8.4, Laravel 12.41.1 (Bleeding Edge) Installed
Admin Panel FilamentPHP v3.2.x Stable Downgraded
DB MariaDB 12.1.2 stable (트랜잭션 강화) Update
OS / Infra Linux / Docker Ubuntu 24.04, Docker Compose v5.0.x Update

4. 시스템 설계 및 데이터베이스 (System Design & DB)

4.1 디렉토리 구조 (Directory Structure) New

기획서의 핵심 요구사항을 반영한 도메인 주도 설계(DDD) 기반 디렉토리 구조입니다.

app/
├── Domains/
│   ├── Inventory/  <-- [SCM Master의 핵심 (재고 권한 100%)]
│   │   ├── Models/
│   │   │   ├── Inventory.php
│   │   │   ├── InventoryAllocation.php
│   │   │   └── SalesChannel.php
│   │   ├── DTOs/
│   │   │   ├── InboundRequestDto.php
│   │   │   ├── AllocationResultDto.php
│   │   │   └── OutboundRequestDto.php
│   │   ├── Services/
│   │   │   ├── AllocationService.php      (자동 분배 로직)
│   │   │   ├── FifoReleaseService.php     (FIFO 예약 출고)
│   │   │   └── PhysicalCountService.php   (실사 로직)
│   │   ├── Observers/
│   │   │   └── InventoryObserver.php      (입고 감지 및 분배 트리거)
│   │   └── Events/
│   │       ├── InventoryReceived.php
│   │       └── AllocationCompleted.php
│   └── Order/
│       ├── Models/
│       │   └── Order.php
│       ├── DTOs/
│       └── Services/
│           └── OrderSyncService.php       (주문 동기화 및 로컬모드 처리)
├── Adapters/  <-- [외부몰 연동 격리]
│   ├── Contracts/
│   │   └── ChannelAdapterInterface.php    (표준 규격 정의)
│   ├── mitunolens
│   │   └── mitunolensAdapter.php
│   ├── sensmania
│   │   └── sensmaniaAdapter.php
│   └── geeenie
│       └── geeenieAdapter.php
└── Http/
    └── Controllers/
        └── Api/
            └── WebhookController.php      (모든 쇼핑몰 공통 진입점)

4.2 데이터베이스 스키마 (Database Schema)

SCM의 핵심 데이터 모델 정의

4.2.1 users (사용자 및 권한) System

Field Type Description
id INT PK
username VARCHAR 아이디 (Unique)
password VARCHAR 비밀번호 (Hash)
role ENUM 권한 (ADMIN, MANUFACTURER, STAFF)

4.2.2 products (상품 마스터) Master

Field Type Description
id INT PK
code VARCHAR 상품코드 (Unique)
name VARCHAR 상품명
price_in/out DECIMAL 입고가/출고가
safety_stock INT 안전재고

4.2.3 inventory (재고 - 마스터) Master

Field Type Description
id BIGINT PK
product_id INT 상품 ID (FK)
quantity INT 실제 물리 재고 (Total)
location VARCHAR 물류 위치

4.2.4 sales_channels (판매 채널 관리) New

Field Type Note
id INT PK
name VARCHAR 채널명 (예: 미츠노, 렌즈나라)
code VARCHAR 시스템 코드
api_key TEXT API 연동 키

4.2.5 inventory_allocations (채널별 재고 할당) New

Field Type Note
inventory_id BIGINT 재고 ID
channel_id INT 채널 ID
allocated_qty INT 채널 할당 수량 (판매 가능)
reserved_qty INT 주문 예약 수량 (출고 대기)

4.2.6 orders (주문 정보) 핵심

Field Type Note
id BIGINT PK
order_number VARCHAR 주문 번호 (Unique)
site_name VARCHAR 주문 채널명
status ENUM 주문 상태 (0:입금전, 1:입금완료, 9:발송준비, 2:상품준비, 3:발송완료, 88:취소)
total_amount DECIMAL 결제 금액

4.2.7 order_items (주문 상세)

Field Type Note
id INT PK
order_id INT 주문 ID (FK)
product_id INT 상품 ID (FK)
quantity INT 주문 수량
price DECIMAL 단가

4.2.8 stock_logs (재고 이력) Log

Field Type Note
id INT PK
product_id INT 상품 ID
type ENUM 유형 (IN/OUT/ADJUST)
quantity INT 변동 수량
reason VARCHAR 사유

5. 핵심 비즈니스 로직 (상세)

5.1 적정 소요량 산출

  • 최근 3개월 평균 판매량 기반 안전 재고(Safety Stock) 자동 산출
  • Lead Time(입고 소요 시간)을 고려한 발주 시점(Reorder Point) 알림
  • 계절성 지수(Seasonality) 반영 옵션

5.2 데이터 동기화 정책 (Data Sync Policy) New

  • 주문 수집: 매 10분 주기 실행 (Cron Batch)
  • 재고 전송: 변동 발생 즉시 (Event Driven) 실시간 전송
  • 송장 전송: 매 1시간 주기 실행 (API Push)
  • 강제 동기화: 관리자 수동 Trigger 지원 (Full Sync)

6. 보안 및 인증 (Security & Auth) New

6.1 인증 (Authentication)

  • 시스템: Laravel Sanctum + Filament 기본 로그인
  • 구현: API 요청(Bearer Token), 관리자 패널(Filament Guard)

6.2 권한 관리 (Authorization)

  • 방식: Filament Shield 또는 Policy 사용
  • 권한 단계: 관리자(Admin), 창고담당자(Manager), 뷰어(Viewer)

7. 테스트 및 예외 처리 (Testing) New

7.1 테스트 전략

  • 프레임워크: PHPUnit 기반 Pest (가독성/유지보수)
  • 목표 커버리지: 핵심 로직 100% (재고, 주문), 전체 90% 이상

7.2 예외 처리 (Exception Handling)

  • Global Handler: App\Exceptions\Handler에서 표준화된 JSON 변환
  • Business Exception: InsufficientStockException 등 커스텀 예외 정의

8. 시스템 다이어그램 (System Diagram) New

[Products] ||--o{ [Inventory]
[Inventory] ||--o{ [Allocations]
[SalesChannels] ||--o{ [Allocations]

상세 ERD는 PlantUML로 관리되며 자동 생성됩니다.

9. [부록] 주문 수집 API 규격 (API Contract) New

{
  "channel_code": "mituno",
  "orders": [
    {
      "order_no": "ORD-20251206-001",
      "items": [
        { "product_code": "LENS-RED-01", "qty": 2 }
      ],
      "is_offline": true,
      "occurred_at": "2025-12-06 14:30:00"
    }
  ]
}

10. [부록] 에러 코드 (Error Codes) New

Code Description
400 Bad Request (잘못된 요청)
401 Unauthorized (인증 실패/키 없음)
404 Not Found (리소스 없음)
500 Internal Server Error (서버 오류)

11. 개발 일정

단계 내용 기간
1 요구사항 분석 및 DB 설계 (완료) 2025.12.01 ~ 12.05
2 핵심 재고/주문 기능 구현 2주 (Sprint 1)
3 채널 API 연동 (미츠노, 렌즈) 2주 (Sprint 2)
4 관리자 대시보드 및 통계 1주 (Sprint 3)
5 통합 테스트 및 배포 1주
6 안정화 및 유지보수 지속

12. 변경 이력 (History)

Date Ver Change Description
2025.12.06 v1.0.0 최초 기획서 작성 및 주요 정책 수립
  • 프로젝트명/코드명 확정 (Melon)
  • 핵심 로직 (재고 분배, 예약 출고) 정의
  • Tech Stack 확정 (Tailwind v4, MariaDB 12, Filament v4)
  • 1.3 운영 대원칙, 5.5 시스템 안정성 (Circuit Breaker) 추가
  • 보안/테스트/API 사양서 등 기술 문서 통합

13. [V2 Future Scope] 향후 고도화 계획 (개발 보류)

[CRITICAL] 이 섹션의 기능은 V1(MVP) 단계에서 구현하지 않습니다.
AI는 이 로직을 참조하여 확장성 있는 구조(Interface/Empty Class)만 잡아두고, 실제 코드는 작성하지 마십시오.

13.1 자동 재고 분배 (Auto-Allocation Strategy)

  • 로직: 입고 발생 시 sales_channels.allocation_ratio를 조회하여 mituno(40%), sense(60%) 등으로 즉시 자동 분할.
  • 구현: AllocationService::autoDistribute() 메서드.

13.2 서킷 브레이커 (Circuit Breaker State Machine)

  • 로직: Redis를 사용하여 실패 횟수(Failure Count)를 카운팅.
  • 상태 전이: CLOSED(정상) → 3회 실패 → OPEN(차단/5분) → HALF-OPEN(1회 시도).
  • 구현: CircuitBreakerMiddleware 및 Redis 상태 관리 로직.

13.3 예약 주문 선입선출 (FIFO Pre-order Release)

  • 로직: 재고 입고 시 BACKORDER 상태인 주문을 주문일시(Ordered At) 오름차순으로 조회하여 재고 할당.
  • 구현: FifoReleaseService 및 복잡한 Queue 처리.