sam-manage/docs/INDEX.md

# 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 4**: 시스템 관리 메뉴 완성 (2025-11-24)
  - ✅ Phase 4-1: 테넌트 관리 (CRUD, 복구/영구삭제)
  - ✅ Phase 4-2: 역할 관리 (CRUD, 권한 할당, Spatie Permission)
  - ✅ Phase 4-3: 부서 관리 (CRUD, 계층 구조)
  - ✅ Phase 4-4: 사용자 관리 (CRUD, 복구/영구삭제)
  - ✅ Phase 4-5: 메뉴 관리 (CRUD, 트리 구조, 토글)

**다음 Phase:**
- 🎯 **Phase 5**: 제품/자재 관리
  - [ ] 제품 관리 (Products)
  - [ ] 자재 관리 (Materials)
  - [ ] 카테고리 관리 (Categories)
- ⏳ **Phase 6**: BOM 관리
  - [ ] BOM 구조 (Bill of Materials)
  - [ ] BOM 버전 관리
- ⏳ **Phase 7**: 시스템 관리
  - [ ] 감사 로그 (Audit Logs)
  - [ ] 시스템 설정 (Settings)

### 프로젝트 문서

**MNG 프로젝트:**
- **[🚨 MNG_CRITICAL_RULES.md](./MNG_CRITICAL_RULES.md)** - 절대 위반 금지 규칙 (필독!)
- **[📋 TABLE_LAYOUT_STANDARD.md](./TABLE_LAYOUT_STANDARD.md)** - 테이블 페이지 레이아웃 표준 (권한 관리 페이지 기반)
- **[CURRENT_WORKS.md](../CURRENT_WORKS.md)** - 현재 작업 진행 상황
- **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - 트러블슈팅 가이드
- **[MIGRATION_PLAN.md](./MIGRATION_PLAN.md)** - Admin → MNG 마이그레이션 계획 (Phase 4)
- **[MNG_PROJECT_PLAN.md](./MNG_PROJECT_PLAN.md)** - 전체 프로젝트 계획
- **[DEV_PROCESS.md](./DEV_PROCESS.md)** - 개발 프로세스 (HTMX + API 방식)
- **[SETUP_GUIDE.md](./SETUP_GUIDE.md)** - 초기 설정 가이드
- **[HTMX_API_PATTERN.md](./HTMX_API_PATTERN.md)** - HTMX + API 패턴 가이드
- **[LAYOUT_PATTERN.md](./LAYOUT_PATTERN.md)** - 레이아웃 패턴 가이드
- **[kma-weather-api.md](./kma-weather-api.md)** - 기상청 날씨 API 연동 가이드 (발표시각별 데이터 범위 주의)

**SAM 공통 문서:**
- **[📊 ../../docs/specs/database-schema.md](../../docs/specs/database-schema.md)** - 데이터베이스 스키마 (Phase 4: 8개 테이블 상세)
- **[../../docs/INDEX.md](../../docs/INDEX.md)** - SAM 전체 문서 네비게이션
- **[../../docs/reference/architecture.md](../../docs/reference/architecture.md)** - SAM 아키텍처

---

## 🏗️ 아키텍처

### 디렉토리 구조
```
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 프로젝트 문서
- **[MNG_PROJECT_PLAN.md](./MNG_PROJECT_PLAN.md)** - 프로젝트 전체 계획
- **[DEV_PROCESS.md](./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)
- Phase 4-1: 테넌트 관리 백엔드/프론트엔드 구현

**2025-11-24 (일)**
- Phase 4-2: 역할 관리 시스템 구현 (Spatie Permission 통합)
- Phase 4-3: 부서 관리 시스템 구현 (계층 구조)
- Phase 4-4: 사용자 관리 기능 추가 (복구/영구삭제)
- Phase 4-5: 메뉴 관리 기능 개선 (트리 구조, 토글)
- 공통 컴포넌트: 페이지네이션, 테넌트 선택기
- 문서: MNG_CRITICAL_RULES.md, TROUBLESHOOTING.md 추가
- **Phase 4 완료**: 시스템 관리 메뉴 5개 완성 (60+ 파일, 5,000+ 줄)

**2025-12-01 (일)**
- 사용자 관리 비밀번호 기능 개선
  - 사용자 생성: 비밀번호 입력 제거 → 자동 생성 후 이메일 발송
  - 사용자 수정: 비밀번호 변경 → 비밀번호 초기화 버튼으로 대체
  - 사용자 모달: 비밀번호 초기화 버튼 추가
- Gmail SMTP 이메일 설정 (Google Groups 발신자)
- 프로필 이미지 없을 때 이름 첫 글자 표시 (한글 지원: mb_* 함수)
- 문서: SETUP_GUIDE.md 이메일 설정 섹션 추가

**2025-12-02 (월)**
- 메뉴 관리 드래그 앤 드롭 기능 구현
  - 같은 레벨 내 순서 변경 (SortableJS)
  - 계층 이동: Notion 스타일 좌우 드래그
    - → 오른쪽: 하위로 이동 (인덴트)
    - ← 왼쪽: 상위로 이동 (아웃덴트)
  - 시각적 피드백: 펄스 애니메이션, 인디케이터 툴팁
- 테넌트 관리 UI 개선
  - 목록/모달 UI 개선
  - 모달 하단 버튼 플로팅 고정
- 프로필 설정 페이지 추가
  - 기본 정보 수정
  - 비밀번호 변경
- 최초 로그인 시 비밀번호 변경 강제 기능
  - EnsurePasswordChanged 미들웨어
  - must_change_password 필드 활용
- 게시판 관리 기능 확장
  - 템플릿 기반 게시판 생성 (공지사항, FAQ, 자료실 등)
  - SVG 아이콘 적용
  - 게시글 파일 첨부 기능 완료
- 일일 스크럼(Daily Logs) 기능 구현
  - 스크럼 목록/상세/작성
  - 날짜별 엔트리 관리

---

**최종 업데이트**: 2025-12-02
**버전**: 2.1
**상태**: Phase 4 완료, 콘텐츠 관리 확장 중