Lensnara SCM Project Dashboard

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 처리.

항목	내용
IP Address	192.168.1.90
OS	Ubuntu 24.04.3 LTS (GNU/Linux 6.8.0-49-generic x86_64)
Domain	https://melon.sellingclub.co.kr

항목	내용
User	intma
Password	********* (관리자 문의)
Port	22 (Default)

항목	내용
Remote URL	[email protected]:git/lensnara_scm.git
Path	~/git/lensnara_scm.git

항목	내용
Container Name	melon-nginx
Image	nginx:alpine
Nginx Ver	1.29.3
Internal Port	7783 (Mapped to Host)
Web Root (Guest)	/var/www/html/public
Web Root (Host)	(Docker Volume/Bind Mount 확인 필요)

Category	Target (Plan)	Current Status
Backend	PHP 8.4 / Laravel 12.x	Installed (v12.41.1)
Admin Panel	FilamentPHP v3.2	Installed (Stable)
Frontend Libs	Livewire v3, Alpine.js v3	Installed
Node.js	v20 (LTS)	Installed (v20.19.2)
Database	MariaDB 12.1.2	Installed (Docker)
Web Server	Nginx (Alpine)	Installed (v1.27.x)
OS	Ubuntu 24.04	Installed (24.04.3 LTS)

Lensnara SCM Project Dashboard

Lensnara SCM v1 - 프로젝트 기획서

0. Meta-Prompt (For AI Agent) New

프로젝트 정보

1. 솔루션 개요 (Solution Overview)

1.1 솔루션 목적

1.2 주요 목표

1.3 운영 대원칙 (Grand Principles) New

2. 핵심 기능 (Key Features)

2.1 상품 관리

2.2 재고 관리 핵심

2.3 주문 관리 핵심

2.4 대시보드/통계

2.5 시스템 관리 (System) New

3. 기술 스택 (Tech Stack)

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

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

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

4.2.1 users (사용자 및 권한) System

4.2.2 products (상품 마스터) Master

4.2.3 inventory (재고 - 마스터) Master

4.2.4 sales_channels (판매 채널 관리) New

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

4.2.6 orders (주문 정보) 핵심

4.2.7 order_items (주문 상세)

4.2.8 stock_logs (재고 이력) Log

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

5.1 적정 소요량 산출

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

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

6.1 인증 (Authentication)

6.2 권한 관리 (Authorization)

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

7.1 테스트 전략

7.2 예외 처리 (Exception Handling)

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

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

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

11. 개발 일정

12. 변경 이력 (History)

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

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

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

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

Phase 1: Project Initialization (기반 구축)

1. Server Environment Setup

2. Framework & Project Structure

3. Database & Migration

4. Plan Integration

Phase 2: Authentication & User Management

1. Filament Installation

2. User Setup

Phase 3: System Upgrade (Bleeding Edge)

1. Core Framework Upgrade

2. Frontend & Styling

Phase 4: Product Management (DDD)

1. Domain & Database

2. Filament Resources

Phase 5: Inventory Management (DDD)

1. Core Logic

2. UI & Actions

Phase 6: Order Management

1. Order Processing

2. Admin Features

Phase 7: Dashboard & Analytics

1. Widgets & Charts

Phase 8: Deployment & Handover

1. Verification & Docs

Phase 9: Site Settings & Branding

1. Settings & Branding

Phase 10: Outstanding Features (To-Do)

1. Product & Inventory (상품/재고)

2. Order & CS (주문/CS)

3. Business Logic (비즈니스 로직)

4. System & Security (시스템/보안)

구현 현황 및 상세 계획 (Implementation Status & Plan)

✅ 개발 완료된 기능 (Implemented)

Phase 1: Project Initialization

Phase 3: System Upgrade

Phase 4: Product Management