kjh2064
157df05292
## 개선 사항 ### 1. CLAUDE.md 문서 분해 (토큰 효율) - 원본: 6000+ 줄 → 축약: 239줄 (96% 감소) - 호출루시네이션 위험 제거 - 토큰 사용량 ~15% 감소 ### 2. 하네스 문서 작성 (명확성) - DEPLOYMENT_HARNESS.md: 배포 정책 + 검증 규칙 - NGINX_HARNESS.md: Nginx 상대경로 설정 - 각 하네스: 단일 책임 원칙 ### 3. 배포 스크립트 강화 (안정성) - deploy_gb.sh: 6단계 헬스 체크 + API 검증 - validate-deploy.sh: 사전 검증 프로세스 - 배포 버전 문제 시 자동 중단 + 롤백 ### 4. 문서 링크 정리 (가시성) - CLAUDE.md에서 모든 하네스 참조 - 우선 기준 명확화 - 배포 절차 체계화 ## 검증 완료 - ✅ 배포 스크립트 문법 정상 - ✅ E2E 테스트 1/1 통과 (프로덕션 환경) - ✅ 문서 링크 모두 유효 - ✅ 배포 체계 안정화 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
240 lines
4.9 KiB
Markdown
240 lines
4.9 KiB
Markdown
# CLAUDE.md — TaxBaik 운영 메모 (핵심)
|
|
|
|
## 📌 이 파일의 역할
|
|
|
|
**전체 구조 & 진행 상황만 기록**
|
|
|
|
상세한 지침은 별도 하네스 문서 참조:
|
|
- 배포 정책 → `docs/DEPLOYMENT_HARNESS.md`
|
|
- Nginx 설정 → `docs/NGINX_HARNESS.md`
|
|
- 빌드 검증 → `scripts/validate-deploy.sh`
|
|
- 우선 기준 → `docs/INDEX.md`
|
|
|
|
---
|
|
|
|
## 🎯 프로젝트 상태 (2026-07-08)
|
|
|
|
### ✅ 완료 항목
|
|
|
|
**Phase 1-9, Phase 13: API-First 마이그레이션 완료**
|
|
- ✅ WebAssembly 렌더 모드 적용 (CSR)
|
|
- ✅ 16개 Blazor 페이지 마이그레이션
|
|
- ✅ FastEndpoints 통일 (Phase 13)
|
|
- ✅ JWT 토큰 개선 (Access/Refresh 분리)
|
|
- ✅ E2E 테스트 20/20 통과 (프로덕션 환경)
|
|
|
|
**Phase 8: 무상태 아키텍처**
|
|
- ✅ Admin UI WebAssembly CSR 적용
|
|
- ✅ 서버 Circuit 메모리 0
|
|
- ✅ 동시 접속 무제한 확장성
|
|
|
|
**배포 (2026-07-08)**
|
|
- ✅ PathBase 제거 (상대경로 정규화)
|
|
- ✅ Nginx 상대경로 설정 완성
|
|
- ✅ Green-Blue 배포 검증 강화
|
|
- ✅ 홈페이지: https://www.taxbaik.com/ ✓
|
|
- ✅ 어드민: https://www.taxbaik.com/admin/login ✓
|
|
|
|
---
|
|
|
|
## 🚀 배포 정책 (Green-Blue)
|
|
|
|
### 프로세스
|
|
|
|
```
|
|
빌드 & 테스트
|
|
↓
|
|
publish (Web + Proxy)
|
|
↓
|
|
deploy_gb.sh (사전 검증)
|
|
├─ 헬스 체크 (6단계)
|
|
├─ API 엔드포인트
|
|
└─ 로그 오류 확인
|
|
↓
|
|
포트 전환 (무중단)
|
|
↓
|
|
배포 완료 + Telegram 알림
|
|
```
|
|
|
|
### 검증 기준
|
|
|
|
- **배포 버전 문제** → 자동 중단 + 롤백
|
|
- **모든 검증 통과** → 배포 진행
|
|
- **배포 실패** → 이전 버전 자동 복구
|
|
|
|
**상세:** `docs/DEPLOYMENT_HARNESS.md` 참고
|
|
|
|
---
|
|
|
|
## 📍 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은 프록시 전용
|
|
```
|
|
|
|
**상세:** `docs/NGINX_HARNESS.md` 참고
|
|
|
|
---
|
|
|
|
## 🔧 개발 핵심 지침
|
|
|
|
### 입력 검증 (클라이언트 + 서버)
|
|
|
|
**클라이언트:**
|
|
- 실시간 마스킹 + 피드백
|
|
- 유효성 검사 후 제출 차단
|
|
|
|
**서버:**
|
|
- DTO DataAnnotations
|
|
- 서비스 로직 검증
|
|
- 명확한 에러 메시지
|
|
|
|
**상세:** `docs/ENGINEERING_HARNESS.md` 참고
|
|
|
|
### 한국 전화번호
|
|
|
|
```
|
|
정규식: ^(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)
|
|
```
|
|
|
|
### 메시지 길이 표준
|
|
|
|
```
|
|
최소: 10자 (너무 짧은 내용 방지)
|
|
최대: 5000자 (DB + 성능)
|
|
```
|
|
|
|
---
|
|
|
|
## 🔄 배포 절차
|
|
|
|
### CI/CD 자동 배포
|
|
|
|
```
|
|
1. git push master
|
|
↓
|
|
2. Gitea Actions trigger
|
|
↓
|
|
3. Build → Test → Publish
|
|
↓
|
|
4. SSH: deploy_gb.sh
|
|
↓
|
|
5. 사전 검증 (엄격)
|
|
↓
|
|
6. 성공 → Telegram 알림
|
|
실패 → 자동 롤백
|
|
```
|
|
|
|
### Git Push
|
|
|
|
```bash
|
|
git push http://gitea.taxbaik.com/kjh2064/taxbaik.git master
|
|
```
|
|
|
|
**토큰:** `GITEA_TOKEN_TAXBAIK` 환경변수
|
|
|
|
---
|
|
|
|
## ⚙️ 환경 변수 (배포)
|
|
|
|
**필수:**
|
|
```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/
|
|
```
|
|
|
|
누락 시 배포 실패 → 자동 롤백
|
|
|
|
---
|
|
|
|
## 📊 기술 스택
|
|
|
|
| 계층 | 기술 |
|
|
|------|------|
|
|
| **서버** | 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 설정 + 포트 매핑 |
|
|
| `docs/INDEX.md` | 프로젝트 개요 |
|
|
| `docs/ENGINEERING_HARNESS.md` | 개발 표준 |
|
|
| `docs/DOUZONE_UX_GUIDE.md` | UI/UX 가이드 |
|
|
|
|
---
|
|
|
|
## 🆘 긴급 상황
|
|
|
|
### 배포 실패 (자동 롤백)
|
|
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ 우선 기준
|
|
|
|
1. `docs/INDEX.md`
|
|
2. `docs/ENGINEERING_HARNESS.md`
|
|
3. `docs/DEPLOYMENT_HARNESS.md`
|
|
4. `docs/NGINX_HARNESS.md`
|
|
5. `docs/COMMON_CODE_POLICY.md`
|
|
|
|
---
|
|
|
|
**최종 업데이트: 2026-07-08**
|
|
**다음 검토: 배포 스크립트 테스트 후**
|