kjh2064/taxbaik

Files

T

kjh2064 157df05292 🔧 문서 체계화 + 배포 정책 강화 (2026-07-08)

## 개선 사항

### 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>

2026-07-08 17:51:03 +09:00

4.4 KiB

Raw Blame History

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 자동 배포

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):

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 설정 상세

🆘 긴급 상황

배포 실패 (자동 롤백)

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

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

수동 롤백

# 이전 포트로 복구
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

4.4 KiB Raw Blame History