Files

김보곤 b717a1cc62 docs: [weather] 기상청 날씨 API 연동 가이드 추가

- 발표시각별 데이터 커버리지 차이 문서화 (06시 vs 18시)
- D+3~D+4 사각지대 문제 및 다중 발표 병합 해결법
- 디버깅 명령어, 트러블슈팅 포함

2026-02-22 19:14:24 +09:00

11 KiB

Raw Permalink Blame History

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

📖 개발 가이드

현재 진행 상황

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

SAM 공통 문서:

📊 ../../docs/specs/database-schema.md - 데이터베이스 스키마 (Phase 4: 8개 테이블 상세)
../../docs/INDEX.md - SAM 전체 문서 네비게이션
../../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 마이그레이션 전략

모델 복사 프로세스

# 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 프로젝트 문서

MNG_PROJECT_PLAN.md - 프로젝트 전체 계획
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)
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 완료, 콘텐츠 관리 확장 중

11 KiB Raw Permalink Blame History

MNG 프로젝트 문서

📋 프로젝트 개요

🚀 빠른 시작

개발 명령어

로그인

📖 개발 가이드

현재 진행 상황

프로젝트 문서

🏗️ 아키텍처

디렉토리 구조

레이아웃 구조

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

모델 복사 프로세스

Blade + HTMX 작성 원칙

API + Blade 구조

📊 데이터베이스

DB 공유 전략

모델 독립 운영

🛡️ 품질 관리

코드 품질 체크리스트

UI 수정 용이성 체크리스트

🔗 관련 문서

SAM 공통 문서

MNG 프로젝트 문서

📝 작업 이력

11 KiB

Raw Permalink Blame History