sam-manage/CLAUDE.md

Claude Code 프로젝트 설정

Git 커밋 규칙 (최우선 필수 규칙)

경고: 이 규칙은 절대 누락되어서는 안 됩니다!

적용 범위

/home/aweso/sam/ 하위의 모든 폴더에 적용:

• /home/aweso/sam/mng - 관리자 웹 (Laravel)
• /home/aweso/sam/api - API 서버 (Laravel)
• 기타 sam 하위 폴더

각 폴더는 독립적인 Git 저장소입니다. 해당 폴더에서 git 명령을 실행해야 합니다.

필수 수행 절차

모든 코드 작업 완료 후 반드시 다음을 수행:

1. 변경된 파일이 있는 폴더로 이동
2. git status로 변경사항 확인
3. git add <파일들> 로 스테이징
4. git commit -m "type:메시지" 로 커밋

커밋 메시지 형식 (필수)

Prefix	사용 시점	예시
feat:	새로운 파일/기능 생성	feat:재무 대시보드 추가
fix:	버그 수정, 코드 수정	fix:HTMX 리다이렉트 오류 수정
refactor:	코드 리팩토링	refactor:서비스 클래스 구조 개선
docs:	문서 수정	docs:README 업데이트
chore:	설정, 빌드 관련	chore:CLAUDE.md 설정 추가

커밋 예시

# mng 폴더 작업 후
cd /home/aweso/sam/mng
git add app/Http/Controllers/SomeController.php
git add resources/views/some-view.blade.php
git commit -m "feat:새로운 기능 추가"

# api 폴더 작업 후
cd /home/aweso/sam/api
git add app/Http/Controllers/Api/SomeApiController.php
git commit -m "fix:API 응답 오류 수정"

Claude Code 설정 파일도 커밋 대상

다음 파일들이 변경되면 반드시 커밋:

파일/폴더	설명	커밋 예시
CLAUDE.md	프로젝트 설정	docs:CLAUDE.md 규칙 업데이트
claudedocs/	Claude 관련 문서	docs:기능 분석 문서 추가
.claude/settings.json	Claude 설정	chore:Claude 설정 변경
agents/, skills/	커스텀 에이전트/스킬	feat:새 스킬 추가

# CLAUDE.md 변경 시
git add CLAUDE.md
git commit -m "docs:CLAUDE.md 규칙 업데이트"

# claudedocs 문서 추가 시
git add claudedocs/new-feature.md
git commit -m "docs:새 기능 분석 문서 추가"

체크리스트 (작업 완료 시 확인)

• mng 폴더 변경사항 확인 → git add → git commit
• api 폴더 변경사항 확인 → git add → git commit
• CLAUDE.md, claudedocs/, agents/, skills/ 변경 확인 → git commit
• 커밋 메시지에 적절한 prefix 사용 (feat:/fix:/refactor:/docs:/chore:)
• 한글로 명확한 커밋 메시지 작성

---

프로젝트 기술 스택

• Backend: Laravel 11 (PHP 8.3)
• Frontend: Blade + HTMX + Tailwind CSS
• React 페이지: React 18 + Babel (브라우저 트랜스파일링)
• Database: MySQL 8

---

Tailwind CSS 레이아웃 규칙 (필수)

경고: 이 프로젝트는 Tailwind CSS 빌드 시점에 포함되지 않은 유틸리티 클래스가 런타임에 적용되지 않습니다.

반응형 클래스 대신 inline style 사용

Tailwind 반응형 클래스(sm:, md:, lg:)가 빌드에 누락될 수 있으므로, 레이아웃 관련 속성은 inline style을 사용한다.

❌ class="w-full sm:w-1/3 sm:flex-nowrap"
✅ style="flex: 1 1 250px; max-width: 400px;"

flex 레이아웃 패턴

항목 유형	사용 방법	예시
가변 너비	inline style flex	style="flex: 1 1 250px; max-width: 400px;"
고정 너비	shrink-0 + inline width	class="shrink-0" style="width: 140px;"
줄바꿈 방지	whitespace-nowrap	class="whitespace-nowrap"

flex 컨테이너 직계 자식에서 w-full 금지

flex-wrap 컨테이너에서 w-full은 항목이 한 줄 전체를 차지하여 줄바꿈을 유발한다. flex 자식 요소의 너비는 flex 속성이나 inline style로 제어한다.

❌ <div class="w-full sm:w-1/3">  ← w-full이 줄바꿈 유발
✅ <div style="flex: 1 1 250px; max-width: 400px;">  ← inline flex로 제어

Tailwind 기본 클래스는 그대로 사용

색상, 패딩, 마진, 보더, 라운드 등 비-반응형 클래스는 Tailwind 사용:

class="px-4 py-2 border border-gray-300 rounded-lg bg-white text-gray-800"

---

데이터베이스 아키텍처 (필수 규칙)

2026-02-27 정책 변경: API/React 운영 배포 중지 기간 동안 MNG에서 마이그레이션 생성 및 실행을 허용한다.

핵심 원칙

작업	MNG에서	비고
마이그레이션 생성	✅ 허용	운영 배포에 필요한 테이블
마이그레이션 실행	✅ 허용	php artisan migrate
모델 작성	✅ 허용
시더	⚠️ MNG 전용만	MngMenuSeeder 등
팩토리	❌ 금지

MNG 마이그레이션 작성 규칙

1. API develop에 동일 마이그레이션이 있으면 파일명을 동일하게 유지
2. Schema::hasTable() 가드 필수 — 중복 실행 방지

public function up(): void
{
    if (Schema::hasTable('table_name')) {
        return;
    }
    Schema::create('table_name', function (Blueprint $table) {
        // ...
    });
}

마이그레이션 실행

# 로컬 (Docker)
docker exec sam-mng-1 php artisan migrate

# 개발 서버
cd /home/webservice/mng && php artisan migrate

# 운영 서버 (--force 필수)
cd /home/webservice/mng && php artisan migrate --force

향후 정리

• API 운영 배포 재개 시 MNG 마이그레이션을 API로 통합 정리
• 동일 파일명 + Schema::hasTable() 가드로 충돌 없음

---

HTMX 네비게이션 규칙

HX-Redirect가 필요한 페이지

복잡한 JavaScript가 @push('scripts')에 있는 페이지는 HTMX 부분 로드 시 스크립트가 실행되지 않으므로 전체 페이지 리로드 필요:

public function index(Request $request): View|Response
{
    if ($request->header('HX-Request')) {
        return response('', 200)->header('HX-Redirect', route('...'));
    }
    // ...
}

적용 대상:

• React 컴포넌트 사용 페이지 (VAT, 미수금, 미지급금 등)
• API Explorer, Flow Tester
• Daily Logs (toggleAttentionItem 등 함수 사용)

HX-Redirect가 불필요한 페이지

단순 Blade 템플릿 (JavaScript 없음):

• 재무 대시보드
• 계좌관리 (accounts/*)
• FCM 관리
• API Logs

Docker 환경 명령어

기본 Docker 컨테이너

sam-mng-1      # Laravel MNG 앱
sam-api-1      # Laravel API 앱
sam-mysql-1    # MySQL 데이터베이스
sam-nginx-1    # Nginx 웹서버
sam-phpmyadmin-1  # phpMyAdmin

Artisan 명령어 실행

# MNG 앱에서 artisan 명령 실행
docker exec sam-mng-1 php artisan <명령어>

# API 앱에서 artisan 명령 실행
docker exec sam-api-1 php artisan <명령어>

메뉴 관리 (DB 기반) - 수동 관리 필수!

경고: 메뉴 시더(Seeder)를 절대 실행하지 마세요!

배경

사이드바 메뉴는 DB의 menus 테이블에 저장됩니다. 메뉴 시더 실행 시 부서별 권한 설정(permission_overrides)이 초기화되므로 시더 사용을 금지합니다.

금지 사항

❌ php artisan db:seed --class=MngMenuSeeder 실행 금지
❌ php artisan db:seed --class=*MenuSeeder 실행 금지
❌ 메뉴 시더 파일 생성 금지
❌ 메뉴 데이터를 일괄 삭제 후 재생성하는 방식 금지

메뉴 변경 시 올바른 절차

메뉴 추가/수정/삭제/이동이 필요할 때는 사용자에게 수동 실행 안내를 제공합니다:

1. tinker 명령어를 안내 (사용자가 직접 실행)
2. 또는 SQL 쿼리를 안내 (사용자가 phpMyAdmin 등에서 직접 실행)
3. 절대 시더를 만들어 실행하지 않음

안내 예시

# 메뉴 추가
ssh sam-server "cd /home/webservice/mng && php artisan tinker --execute=\"
App\\\\Models\\\\Commons\\\\Menu::create([
    'tenant_id' => 1,
    'parent_id' => <부모ID>,
    'name' => '새 메뉴',
    'url' => '/new-menu',
    'icon' => 'icon-name',
    'sort_order' => 1,
    'is_active' => true,
]);
\""

# 메뉴 이름 변경
ssh sam-server "cd /home/webservice/mng && php artisan tinker --execute=\"
App\\\\Models\\\\Commons\\\\Menu::withoutGlobalScopes()->find(<ID>)->update(['name' => '새이름']);
\""

# 메뉴 비활성화 (삭제 대신)
ssh sam-server "cd /home/webservice/mng && php artisan tinker --execute=\"
App\\\\Models\\\\Commons\\\\Menu::withoutGlobalScopes()->find(<ID>)->update(['is_active' => false]);
\""

주의사항

• 메뉴 변경 시 라우트(routes/web.php)와 컨트롤러도 함께 추가해야 함
• 새 메뉴 추가 후 부서별 권한 설정이 필요하면 사용자에게 안내