← 문서 목록
v1.0.0 📅 2025-12-06 📂 기획

Lensnara SCM v1 - 프로젝트 기획서

최초 작성일: 2025-12-06 | 원본 형식: HTML (v1-original.html)

0. Meta-Prompt (For AI Agent)

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

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 등

3. STRICTLY follow the exact Directory Structure defined in 기획서 Section 4

4. IMPLEMENT functionality Phase by Phase exactly as defined in 기획서 Section 5 (6단계)
   → 각 단계가 끝날 때마다 "Phase X 완료"라고 명확히 표시

1. 솔루션 개요 (Solution Overview)

1.1 솔루션 목적

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

1.2 주요 목표

1.3 운영 대원칙 (Grand Principles)

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

2. 핵심 기능 (Key Features)

2.1 상품 관리

2.2 재고 관리 핵심

2.3 주문 관리 핵심

2.4 대시보드/통계

2.5 시스템 관리 (System)

3. 기술 스택 (Tech Stack)

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

4. 시스템 설계 및 데이터베이스

4.1 디렉토리 구조 (Directory Structure)

기획서의 핵심 요구사항을 반영한 도메인 주도 설계(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 데이터베이스 스키마

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 (판매 채널 관리)

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

4.2.5 inventory_allocations (채널별 재고 할당)

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 적정 소요량 산출

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

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

6.1 인증 (Authentication)

6.2 권한 관리 (Authorization)

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

7.1 테스트 전략

7.2 예외 처리 (Exception Handling)

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

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

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

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

{
  "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)

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 최초 기획서 작성 및 주요 정책 수립 (프로젝트명/코드명 확정, 핵심 로직 정의, Tech Stack 확정, 운영 대원칙/시스템 안정성 추가, 보안/테스트/API 사양서 통합)

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

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

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

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

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

개발 태스크 (Development Tasks)

Phase 1: Project Initialization (기반 구축)

1. Server Environment Setup

2. Framework & Project Structure

3. Database & Migration

4. Plan Integration

Phase 2: Authentication & User Management

Phase 3: System Upgrade (Bleeding Edge)

Phase 4: Product Management (DDD)

Phase 5: Inventory Management (DDD)

Phase 6: Order Management

Phase 7: Dashboard & Analytics

Phase 8: Deployment & Handover

Phase 9: Site Settings & Branding

Phase 10: Outstanding Features (To-Do)

Next Steps: 기획서에 명시된 기능 중 현재 미구현된 항목들 (V2 제외)

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

2. Order & CS (주문/CS)

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

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

구현 현황 및 상세 계획

✅ 개발 완료된 기능 (Implemented)

🚧 개발 예정 기능 (Pending)

1. Integration Features (연동 퍼널)

2. System Management (시스템 관리)

3. Advanced Logic (고도화 로직)

서버 세팅 정보

개발 및 유지보수를 위한 서버 접속 정보입니다.

기본 정보

항목 내용
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

SSH 접속 정보

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

Git 리포지토리

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

Docker 컨테이너 정보

항목 내용
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

기술 스택 현황 (설치일 기준)

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)

Nginx & SSL

← 문서 목록으로