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

---

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

경고: MNG 프로젝트에서는 마이그레이션 파일을 생성하지 않습니다!

핵심 원칙

작업	올바른 위치	MNG에서
마이그레이션 생성	/home/aweso/sam/api/database/migrations/	❌ 금지
마이그레이션 실행	docker exec sam-api-1 php artisan migrate	❌ 금지
테이블 생성/수정	API 프로젝트에서만	❌ 금지

MNG database 폴더 상태

/home/aweso/sam/mng/database/
├── migrations/     ← 비어있음 (파일 생성 금지!)
├── seeders/        ← MNG 전용 시더만 허용 (예: MngMenuSeeder)
└── factories/      ← 사용 안 함

MNG에서 허용되는 것

• ✅ 컨트롤러, 뷰, 라우트 작성
• ✅ 모델 작성 (API의 테이블 사용)
• ✅ MNG 전용 시더 (MngMenuSeeder 등)

MNG에서 금지되는 것

• ❌ database/migrations/ 에 파일 생성
• ❌ docker exec sam-mng-1 php artisan migrate 실행
• ❌ 테이블 구조 변경 관련 작업

새 테이블이 필요할 때

1. API 프로젝트에서 마이그레이션 생성
2. docker exec sam-api-1 php artisan migrate 실행
3. MNG에서 해당 테이블의 모델만 작성

---

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 기반)

메뉴 구조

사이드바 메뉴는 DB에 저장되어 있으며 MngMenuSeeder로 관리합니다.

메뉴 추가/수정 절차 (필수!)

1. 시더 파일 수정

   database/seeders/MngMenuSeeder.php
   

2. 시더 실행 (Docker)

   docker exec sam-mng-1 php artisan db:seed --class=MngMenuSeeder
   

3. 브라우저 새로고침으로 확인

주의사항

• 시더 실행 시 기존 메뉴(tenant_id=1)가 삭제 후 재생성됨
• 메뉴 코드 수정만으로는 적용 안 됨 → 반드시 시더 실행 필요
• 라우트(routes/web.php)와 컨트롤러도 함께 추가해야 함