hskwon
0c86b390ad
- MNG_CRITICAL_RULES.md: DB 마이그레이션 금지 등 핵심 규칙 - UserController: 사용자 CRUD API 엔드포인트 - StoreUserRequest, UpdateUserRequest: 사용자 검증 - 사용자 관리 뷰: index, create, edit, table - 시스템 관리 메뉴 UI 개선 (테이블 헤더 스타일) - docs/INDEX.md: CRITICAL_RULES 링크 추가
7.7 KiB
7.7 KiB
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
🚀 빠른 시작
개발 명령어
# 서버 실행
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/카테고리 관리
프로젝트 문서
- 🚨 MNG_CRITICAL_RULES.md - 절대 위반 금지 규칙 (필독!)
- CURRENT_WORKS.md - 현재 작업 진행 상황
- MIGRATION_PLAN.md - Admin → MNG 마이그레이션 계획 (Phase 4)
- claudedocs/mng/MNG_PROJECT_PLAN.md - 전체 프로젝트 계획
- claudedocs/mng/DEV_PROCESS.md - 개발 프로세스 (HTMX + API 방식)
- 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 마이그레이션 전략
모델 복사 프로세스
# 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 작성 원칙
{{-- ✅ 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 - SAM 프로젝트 가이드
- docs/INDEX.md - 전체 문서 네비게이션
- docs/reference/architecture.md - SAM 아키텍처
- docs/specs/database-schema.md - DB 스키마
MNG 프로젝트 문서
- claudedocs/mng/MNG_PROJECT_PLAN.md - 프로젝트 전체 계획
- claudedocs/mng/DEV_PROCESS.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 준비 중