ZENITH_LMS (SNTL 통합 물류 플랫폼)
항공·해운·통관·택배를 아우르는 차세대 지능형 통합 물류 관리 플랫폼, ZENITH_LMS 프로젝트입니다.
🚀 1. 프로젝트 개요
ZENITH_LMS는 복잡한 글로벌 물류 프로세스를 단일 플랫폼에서 관리하기 위해 설계되었습니다. 화주(Shipper), 운송사(Carrier), 관리자(Admin) 간의 실시간 데이터 동기화와 AI 기반의 자동화된 의사결정을 지원합니다.
- 프로젝트 명: ZENITH_LMS
- 주요 목표: 물류 전 구간(End-to-End) 가시성 확보 및 운영 자동화
- 현재 상태: Phase 5 (Sprint 14) 완료 - E2E 테스트 및 안정화 종료
🛠️ 2. 기술 스택
- Frontend:
Next.js 16 (App Router), React 19, TypeScript, Vanilla CSS (Modern Layout)
- Backend/DB:
Supabase (PostgreSQL), Auth, Storage, Edge Functions
- UI/Design:
Glassmorphism UX, Framer Motion, Lucide React
- PDF/문서:
@react-pdf/renderer (청구서·운송장 동적 생성)
- 모니터링:
Sentry (@sentry/nextjs) (에러 추적 및 관리자 알림)
- 이메일:
Resend (회원 승인 알림 등)
- Testing:
Playwright (E2E), Vitest v4 (Unit/Integration)
- Methodology:
ZEN_A4 (Hybrid), rtk (Token-optimized CLI proxy)
📚 3. 문서 상세 인덱스 (Documentation)
모든 문서는 /docs 폴더 내에 체계적으로 관리되고 있습니다.
📋 [00] 가이드 및 거버넌스 (Guides & Governance)
프로젝트 운영 표준과 개발 원칙을 정의합니다.
📅 [01] 공정 및 일정 관리 (WBS)
프로젝트 진행 상황과 남은 과업을 추적합니다.
🔍 [02] 요구사항 및 기능 분석 (Requirements)
비즈니스 요구사항을 기술적 기능으로 구체화한 문서입니다.
🎨 [03] 시스템 설계 및 API 명세 (Design)
구현을 위한 기술 설계와 API 규격서입니다.
✅ [08] 자가 감사 및 검증 (Audit & QA)
품질 확보를 위한 테스트 결과와 오류 대응 기록입니다.
⚙️ 4. 테스트 및 개발 환경 설정 (Environment Setup)
ZENITH_LMS는 보안 및 방법론 준수를 위해 로컬 Supabase 환경에서의 테스트를 원칙으로 합니다.
rtk란? 프로젝트 전용 CLI 프록시 도구입니다. rtk <command> 형태로 npm, supabase 등 모든 명령어를 실행하면 토큰 최적화 및 로깅이 자동 적용됩니다. 미설치 시 rtk 대신 원래 명령어를 직접 사용하세요.
1단계: 필수 도구 설치
- Node.js (v18+), npm
- Supabase CLI 설치 필수
- Docker (Supabase Local 구동용)
2단계: 환경 변수 설정
cp .env.example .env.local
.env.local에 아래 값을 채워 넣습니다.
| 변수명 | 설명 | 필수 |
|---|
NEXT_PUBLIC_SUPABASE_URL | Supabase 프로젝트 URL | ✅ |
NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabase Anon Key | ✅ |
DATABASE_URL | Supabase DB 직접 연결 URL | ✅ |
SUPABASE_SERVICE_ROLE_KEY | 서버 사이드 전용 Service Role Key | ✅ |
RESEND_API_KEY | 이메일 발송 API Key (Resend) | ✅ |
NEXT_PUBLIC_SENTRY_DSN | Sentry 에러 모니터링 DSN | 선택 |
3단계: 프로젝트 초기화
# 1. 저장소 클론 (이미 완료된 경우 생략)
# 2. 의존성 설치
rtk npm install
# 3. 로컬 Supabase 구동
rtk supabase start
# 4. DB 스키마 및 테스트 계정 시딩
rtk supabase db reset
rtk npm run db:seed
4단계: 애플리케이션 실행
# 로컬 개발 서버 실행
rtk npm run dev
- 접속 주소:
http://localhost:3000
5단계: 테스트 실행 (Playwright)
# 전체 E2E 테스트 실행
npx playwright test
# 특정 시나리오만 실행 (예: 오더 관리)
npx playwright test tests/e2e/e2e-03-master-order.spec.ts
☁️ 5. 배포 (Deployment)
ZENITH_LMS는 Vercel 플랫폼에 배포됩니다.
# Vercel CLI를 통한 프로덕션 배포
vercel --prod
- Vercel 프로젝트 환경 변수에
.env.local의 모든 값을 동일하게 설정해야 합니다.
main 브랜치 푸시 시 Vercel CI/CD가 자동으로 프로덕션 배포를 트리거합니다.- DB 스키마 변경 시 반드시 원격 Supabase에 마이그레이션을 먼저 적용하세요:
rtk supabase db push
📁 6. 폴더 구조 (Folder Structure)
ZENITH_LMS_001/
├── .agent/ # 에이전트 작업 상태 및 TASK_BOARD 관리
├── .planning/ # 프로젝트 ROADMAP 및 CONTEXT 데이터
├── docs/ # 프로젝트 문서 저장소 (가이드, 분석, 설계, 감사)
├── messages/ # 다국어(i18n) 번역 데이터 (ko, en, zh)
├── public/ # 정적 자원 (이미지, 폰트, 리소스)
├── scripts/ # 데이터 시딩 및 유틸리티 스크립트
├── src/ # Next.js 애플리케이션 소스 코드
│ ├── app/ # App Router 기반 페이지 및 API Route
│ ├── components/ # UI 컴포넌트 (Glassmorphism 적용)
│ ├── lib/ # API 유틸리티 및 Supabase 클라이언트
│ └── types/ # 전역 TypeScript 타입 정의
├── supabase/ # DB 마이그레이션, 시드 데이터, RLS 설정
└── tests/ # Playwright E2E 및 Vitest 단위 테스트
🔐 7. 테스트 계정 정보
모든 계정의 비밀번호는 password1234로 동일하게 설정되어 있습니다.
📄 8. 거버넌스 및 준수 사항
- 모든 작업은
ZEN_A4 방법론에 따라 계획-실행-검증 단계를 거칩니다.
- 코드 수정 시 반드시
npm run test:regression을 통과해야 합니다.
- 상세한 운영 규정은 GEMINI.md를 참조하십시오.
© 2026 ZENITH_LMS Team. All rights reserved.
