SamProject/sam-manage
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f50e98b802be95d7c30c1c2824c04c39c386ba89
sam-manage/CLAUDE.md
김보곤 f50e98b802 docs: [CLAUDE.md] Tailwind CSS 레이아웃 규칙 추가 
- 반응형 클래스 대신 inline style 사용 규칙
- flex 레이아웃 패턴 정리
- w-full 금지 규칙 (flex 컨테이너 자식)
2026-02-21 12:50:31 +09:00

8.6 KiB
Raw Blame History

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"

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

경고: 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 기반) - 수동 관리 필수!

경고: 메뉴 시더(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)와 컨트롤러도 함께 추가해야 함
  • 새 메뉴 추가 후 부서별 권한 설정이 필요하면 사용자에게 안내