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 설정 추가` |

### 커밋 예시

```bash
# 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:새 스킬 추가` |

```bash
# 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 사용**:

```html
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 부분 로드 시 스크립트가 실행되지 않으므로 전체 페이지 리로드 필요:

```php
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 컨테이너
```bash
sam-mng-1      # Laravel MNG 앱
sam-api-1      # Laravel API 앱
sam-mysql-1    # MySQL 데이터베이스
sam-nginx-1    # Nginx 웹서버
sam-phpmyadmin-1  # phpMyAdmin
```

### Artisan 명령어 실행
```bash
# 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. **절대 시더를 만들어 실행하지 않음**

### 안내 예시

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