# MNG 프로젝트 문서

> 📌 **MNG 관리자 패널 문서 (Laravel + Blade + Tailwind)**

---

## 📋 프로젝트 개요

**MNG**는 Filament 의존성 없이 AI 없이도 수정 가능한 Plain Laravel 관리자 패널입니다.

**핵심 철학:**
- **단순함 > 복잡함** - 복잡한 추상화 제거
- **수정 용이성** - AI 없이도 Blade 템플릿 수정 가능
- **코드 재사용** - admin/ 모델/서비스 복사 후 간소화

**기술 스택:**
- Laravel 12 + PHP 8.4
- Blade + Tailwind CSS 3.x + HTMX
- Sanctum 인증 (세션 + 토큰)
- MySQL 8.0 (admin/api와 DB 공유)

**도메인:** `mng.sam.kr`

---

## 🚀 빠른 시작

### 개발 명령어
```bash
# 서버 실행
php artisan serve

# Vite (Tailwind CSS)
npm run dev

# 마이그레이션
php artisan migrate

# 코드 스타일
./vendor/bin/pint
```

### 로그인
- URL: `http://mng.sam.kr/login`
- 계정: admin/ 또는 api/와 동일한 users 테이블 사용

---

## 📖 개발 가이드

### 현재 진행 상황

**완료된 Phase:**
- ✅ **Phase 1**: 인증 시스템 (AuthService, LoginController, User 모델)
- ✅ **Phase 2**: 레이아웃 구조 (sidebar + header, Pure Tailwind)
- ✅ **Phase 3**: 테넌트 선택 기능 (TenantController, ViewServiceProvider)

**진행 중 Phase:**
- 🔄 **Phase 4**: 시스템 관리 메뉴 (admin/ Filament 기능 이식)
  - 테넌트 관리
  - 사용자 관리
  - 메뉴 관리
  - 역할/부서/권한 관리

**계획된 Phase:**
- ⏳ **Phase 5**: 제품/자재 관리
- ⏳ **Phase 6**: BOM/카테고리 관리

### 프로젝트 문서
- **[CURRENT_WORKS.md](../CURRENT_WORKS.md)** - 현재 작업 진행 상황
- **[MIGRATION_PLAN.md](./MIGRATION_PLAN.md)** - Admin → MNG 마이그레이션 계획 (Phase 4)
- **[claudedocs/mng/MNG_PROJECT_PLAN.md](../../claudedocs/mng/MNG_PROJECT_PLAN.md)** - 전체 프로젝트 계획
- **[claudedocs/mng/DEV_PROCESS.md](../../claudedocs/mng/DEV_PROCESS.md)** - 개발 프로세스 (HTMX + API 방식)
- **[claudedocs/mng/SETUP_GUIDE.md](../../claudedocs/mng/SETUP_GUIDE.md)** - 초기 설정 가이드

---

## 🏗️ 아키텍처

### 디렉토리 구조
```
mng/
├── app/
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Auth/           # 인증 컨트롤러
│   │   │   └── TenantController.php
│   │   ├── Requests/           # FormRequest (검증)
│   │   └── Middleware/
│   ├── Services/               # 비즈니스 로직 (Service-First)
│   ├── Models/                 # Eloquent 모델 (독립 운영)
│   │   ├── User.php
│   │   └── Tenant.php
│   └── Providers/
│       └── ViewServiceProvider.php
├── routes/
│   ├── web.php                 # Blade 라우트
│   └── api.php                 # Admin API (향후)
├── resources/
│   └── views/
│       ├── layouts/
│       │   └── app.blade.php   # 마스터 레이아웃
│       ├── partials/
│       │   ├── sidebar.blade.php
│       │   ├── header.blade.php
│       │   └── tenant-selector.blade.php
│       ├── auth/               # 로그인 화면
│       └── dashboard/          # 대시보드
├── database/
│   └── migrations/
└── docs/                       # 프로젝트 문서
    └── INDEX.md                # 이 문서
```

### 레이아웃 구조
```
┌─────────────────────────────────────┐
│ ┌──────┐ ┌─────────────────────┐   │
│ │      │ │   Header (64px)     │   │
│ │ Side │ ├─────────────────────┤   │
│ │ bar  │ │                     │   │
│ │(256) │ │   Main Content      │   │
│ │      │ │                     │   │
│ └──────┘ └─────────────────────┘   │
└─────────────────────────────────────┘
```

**특징:**
- 좌측 사이드바: 256px 고정
- 상단 헤더: 64px 고정
- Pure Tailwind CSS (DaisyUI 제거됨 - oklch() 호환성 문제)
- HTMX 기반 인터랙션 (Alpine.js 제거)
- 반응형: 추후 모바일 대응 예정

---

## 🔄 Admin → MNG 마이그레이션 전략

### 모델 복사 프로세스
```bash
# 1. admin/ 모델 복사
cp -r admin/app/Models/* mng/app/Models/

# 2. Filament 코드 제거
# - form(), table(), getNavigationLabel() 등 제거
# - 순수 Eloquent 관계만 유지

# 3. Traits 복사
cp admin/app/Traits/BelongsToTenant.php mng/app/Traits/
cp admin/app/Traits/HasAuditLog.php mng/app/Traits/
```

### Blade + HTMX 작성 원칙
```blade
{{-- ✅ GOOD: HTMX로 API 호출 --}}
<form hx-post="/api/admin/users"
      hx-target="#user-list"
      hx-swap="beforeend">
    <input type="text" name="name" class="input input-bordered" />
    <button class="btn btn-primary">저장</button>
</form>

{{-- ❌ BAD: 과도한 추상화 --}}
<x-custom-card :config="$complexConfig" />

{{-- ❌ BAD: Alpine.js 사용 (제거됨) --}}
<div x-data="{ open: false }">...</div>
```

### API + Blade 구조
```
1. Blade 화면 (Web Routes)
   └─ HTMX 호출 → /api/admin/users

2. API Controller
   └─ HTMX 요청? → Blade 부분 HTML 반환
   └─ 일반 요청? → JSON 반환

3. Service → Model → Database
```

---

## 📊 데이터베이스

### DB 공유 전략
- **기존 테이블 재사용**: users, roles, departments, products 등
- **관리자 전용 테이블**: `admin_*` 접두사
- **통계 테이블**: `stat_*` 접두사

### 모델 독립 운영
- admin/, api/, mng/ 각각 독립된 모델 사용
- 동일한 DB 테이블을 참조하지만 모델은 독립
- Filament 의존성 제거

---

## 🛡️ 품질 관리

### 코드 품질 체크리스트
```
□ Service-First (비즈니스 로직 → Service)
□ FormRequest (컨트롤러 검증 금지)
□ BelongsToTenant (multi-tenant 스코프)
□ i18n 키 (하드코딩 금지)
□ Soft Delete (deleted_at)
□ 감사 로그 (HasAuditLog trait)
□ Feature Test
□ Pint (코드 스타일)
```

### UI 수정 용이성 체크리스트
```
□ Tailwind 유틸리티 클래스 직접 사용 (추상화 최소)
□ Alpine.js 단순 인터랙션만
□ Blade 템플릿 2레벨 이하
□ 인라인 Tailwind 허용
□ AI 없이 수정 가능
```

---

## 🔗 관련 문서

### SAM 공통 문서
- **[CLAUDE.md](../../CLAUDE.md)** - SAM 프로젝트 가이드
- **[docs/INDEX.md](../../docs/INDEX.md)** - 전체 문서 네비게이션
- **[docs/reference/architecture.md](../../docs/reference/architecture.md)** - SAM 아키텍처
- **[docs/specs/database-schema.md](../../docs/specs/database-schema.md)** - DB 스키마

### MNG 프로젝트 문서
- **[claudedocs/mng/MNG_PROJECT_PLAN.md](../../claudedocs/mng/MNG_PROJECT_PLAN.md)** - 프로젝트 전체 계획
- **[claudedocs/mng/DEV_PROCESS.md](../../claudedocs/mng/DEV_PROCESS.md)** - 개발 프로세스
- **[CURRENT_WORKS.md](../CURRENT_WORKS.md)** - 작업 진행 상황

---

## 📝 작업 이력

**2025-11-20 (수)**
- Phase 1: 인증 시스템 구현 (AuthService, LoginController)
- Phase 2: 레이아웃 구조화 (sidebar + header, Pure Tailwind)
- Phase 3: 테넌트 선택 기능 구현 (TenantController)

**2025-11-21 (목)**
- 문서 체계화 (INDEX.md 작성)
- 공통 문서 업데이트 (CLAUDE.md, docs/INDEX.md, architecture.md)

---

**최종 업데이트**: 2025-11-21
**버전**: 1.0
**상태**: Phase 3 완료, Phase 4 준비 중