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

---

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

> **경고: 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 기반)

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

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

1. **시더 파일 수정**
   ```
   database/seeders/MngMenuSeeder.php
   ```

2. **시더 실행 (Docker)**
   ```bash
   docker exec sam-mng-1 php artisan db:seed --class=MngMenuSeeder
   ```

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

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