# CLAUDE.md (핵심 요약)

## 📌 이 파일의 역할

**전체 구조 & 진행 상황만 기록**

상세한 지침은 별도 하네스 문서 참조:
- 배포 정책 → `DEPLOYMENT_HARNESS.md`
- Nginx 설정 → `NGINX_HARNESS.md`
- 빌드 검증 → `BUILD_VALIDATION_HARNESS.md`
- 프로젝트 정보 → `docs/INDEX.md`

---

## 🎯 프로젝트 상태 (2026-07-08)

### ✅ 완료 항목

**Phase 1-9, Phase 13: API-First 마이그레이션 완료**
- ✅ WebAssembly 렌더 모드 적용
- ✅ 16개 Blazor 페이지 마이그레이션
- ✅ FastEndpoints 통일 (PhaseII 13)
- ✅ JWT 토큰 개선 (Access/Refresh 분리)
- ✅ E2E 테스트 20/20 통과

**Phase 8: 무상태 아키텍처**
- ✅ Admin UI WebAssembly CSR 적용
- ✅ 서버 Circuit 메모리 0
- ✅ 동시 접속 무제한 확장성

---

## 🚀 현재 배포 정책

### Green-Blue 배포 (무중단)

**프로세스:**
```
빌드 & 테스트
  ↓
publish (Web + Proxy)
  ↓
deploy_gb.sh 실행
  ↓
사전 검증 (엄격)
  ├─ 헬스 체크 (6단계)
  ├─ API 엔드포인트
  └─ 로그 오류 확인
  ↓
포트 전환 (무중단)
  ↓
E2E 테스트
  ↓
배포 완료
```

**검증 기준:**
- 배포 버전 문제 → 자동 중단 + 롤백
- 모든 검증 통과 → 배포 진행
- 배포 실패 → 이전 버전 자동 복구

---

## 📍 Nginx 설정 (상대경로)

### 포트 매핑

```
공개: https://www.taxbaik.com/
  ↓ (Nginx)
프록시: http://127.0.0.1:5001/
  ↓ (프록시가 읽음)
활성 포트: /home/kjh2064/taxbaik_port
  ↓
실제 앱: http://127.0.0.1:{5003|5004}
```

### 필수 규칙

```
✅ proxy_pass http://127.0.0.1:5001/;  (슬래시 필수)
✅ Nginx 설정은 절대 변경 안 함 (배포마다)
✅ 포트 5001은 프록시 전용 (앱 직접 X)
```

---

## 🔧 개발 핵심 지침

### 입력 검증 (클라이언트 + 서버)

**클라이언트:**
- 실시간 마스킹 + 피드백
- 유효성 검사 후 제출 차단

**서버:**
- DTO DataAnnotations
- 서비스 로직 검증
- 명확한 에러 메시지

### 메시지 길이 표준

```
최소: 10자 (너무 짧은 내용 방지)
최대: 5000자 (DB + 성능)
```

### 한국 전화번호

```
정규식: ^(0(2|3[1-3]|4[1-4]|...|70|50[5-9])\d{7,8}|0\d{9,10})$
고정전화: 02-123-4567 (4-3-4)
휴대폰:   010-1234-5678 (3-4-4)
```

---

## 🔄 배포 절차

### CI/CD 자동 배포

```bash
1. git push master
   ↓
2. Gitea Actions trigger (.gitea/workflows/deploy.yml)
   ↓
3. Build → Test → Publish
   ↓
4. SSH: deploy_gb.sh 실행
   ↓
5. 사전 검증 (DEPLOYMENT_HARNESS.md 참고)
   ↓
6. 성공 → Telegram 알림
   실패 → 자동 롤백 + 알림
```

### 배포 토큰

- **Gitea Token**: `GITEA_TOKEN_TAXBAIK` 환경변수
- **Push 명령**: `git push http://gitea.taxbaik.com/kjh2064/taxbaik.git master`

---

## ⚙️ 환경 변수 (배포)

**필수 설정 (deploy_gb.sh):**
```bash
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://127.0.0.1:${TARGET_PORT}
ConnectionStrings__Default=Host=localhost;Database=taxbaikdb;...
ApiClient__BaseUrl=http://127.0.0.1:${TARGET_PORT}/api/
```

**누락 시 배포 실패:** "Missing connection string" → 자동 롤백

---

## 📊 기술 스택

| 계층 | 기술 |
|------|------|
| **서버** | ASP.NET Core 10 |
| **DB** | PostgreSQL 18 + Dapper |
| **클라이언트** | Blazor WebAssembly |
| **UI** | MudBlazor |
| **배포** | Green-Blue (무중단) |
| **Nginx** | 프록시 (정적 설정) |
| **CI/CD** | Gitea Actions |

---

## 📝 중요 파일

| 파일 | 목적 |
|------|------|
| `deploy_gb.sh` | Green-Blue 배포 |
| `scripts/validate-deploy.sh` | 사전 검증 |
| `/etc/nginx/sites-available/taxbaik-domains.conf` | Nginx 설정 |
| `.gitea/workflows/deploy.yml` | CI/CD 파이프라인 |
| `docs/DEPLOYMENT_HARNESS.md` | 배포 정책 상세 |
| `docs/NGINX_HARNESS.md` | Nginx 설정 상세 |

---

## 🆘 긴급 상황

### 배포 실패 (자동 롤백)

```bash
# 현재 포트 확인
cat /home/kjh2064/taxbaik_port

# 로그 확인
tail -100 /home/kjh2064/deployments/taxbaik_*/web_*.log
```

### 수동 롤백

```bash
# 이전 포트로 복구
echo "5003" > /home/kjh2064/taxbaik_port
sudo systemctl reload nginx
```

---

## 📞 참고 문서

- **배포**: `docs/DEPLOYMENT_HARNESS.md`
- **Nginx**: `docs/NGINX_HARNESS.md`
- **빌드**: `docs/BUILD_VALIDATION_HARNESS.md`
- **프로젝트**: `docs/INDEX.md`
- **엔지니어링**: `docs/ENGINEERING_HARNESS.md`

---

**최종 업데이트: 2026-07-08**