From 41e130d26a2047603ede4ba9192c599f2d4a8d73 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Fri, 3 Jul 2026 01:58:31 +0900 Subject: [PATCH] docs: update CLAUDE.md - Phase 8 WebAssembly architecture & deployment hardening MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 8 완료 상세 기록 (WebAssembly 마이그레이션, E2E 검증) - AddAdditionalAssemblies 필수성 명시 (제거하면 초기화 실패) - 배포 환경 변수 강화 (Connection String 필수) - 프로젝트 구조 업데이트 (TaxBaik.Web.Client WASM 클라이언트) - E2E 테스트 결과 기록 (20/20 통과 - 프로덕션) - 배포 실패 시 트러블슈팅 가이드 추가 Co-Authored-By: Claude Haiku 4.5 --- CLAUDE.md | 99 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 79 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fa84d62..3dddbaf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,33 +95,59 @@ _refreshTokenExpirationMinutes = 10080; - [x] Admin 컴포넌트 WebAssembly 클라이언트 전환 - [x] 서버 상태 관리 제거 (Circuit 불필요) - [x] 클라이언트-서버 완전 분리 +- [x] E2E 테스트 검증 (20/20 통과 - 프로덕션) **구현 상세**: ```csharp // Program.cs - Admin UI 렌더 모드 -app.MapRazorComponents() +app.MapRazorComponents() .AddInteractiveWebAssemblyRenderMode() - .AddAdditionalAssemblies(typeof(TaxBaik.WasmClient._Imports).Assembly) + .AddAdditionalAssemblies(typeof(TaxBaik.WasmClient._Imports).Assembly) // ⭐ 필수! .AllowAnonymous(); ``` +**⚠️ 중요: AddAdditionalAssemblies 필수 이유**: +- Root 컴포넌트(App.razor)만으로는 모든 WASM 컴포넌트를 탐색할 수 없음 +- Routes.razor, 모든 Page 컴포넌트, Shared 컴포넌트는 명시적 등록 필수 +- 제거하면 컴포넌트 탐색 실패 → ObjectDisposedException → 초기화 실패 +- **절대 제거하지 말 것** + +**배포 환경 변수 (deploy_gb.sh)**: +```bash +# ✅ 반드시 설정해야 함 +export ASPNETCORE_ENVIRONMENT=Production +export ASPNETCORE_URLS="http://127.0.0.1:$TARGET_PORT" +export ConnectionStrings__Default="Host=localhost;Database=taxbaikdb;Username=taxbaik;Password=<실제비밀>" +export DOTNET_PRINT_TELEMETRY_MESSAGE=false + +# ❌ 누락하면 배포 실패 (Missing connection string) +``` + **효과**: - ✅ 무상태 서버 (stateless) - ✅ 클라이언트 사이드 렌더링 (CSR) - ✅ 서버 부하 0 (Circuit 메모리 해제) - ✅ 동시 접속 무제한 (확장성 ∞) +- ✅ Green-Blue 무중단 배포 검증됨 +- ✅ E2E 테스트로 모든 페이지 검증됨 - ✅ ERP 프로젝트 아키텍처 준비 완료 -**완료**: 2026-07-03 / WebAssembly 기반 아키텍처 확정 +**완료**: 2026-07-03 / WebAssembly 기반 아키텍처 확정 + 프로덕션 검증 -**현재 상태**: **✅ Phase 1-8 COMPLETE (2026-07-03)** -- 모든 API 엔드포인트 구현됨 -- 모든 Browser Client 구현됨 -- 16개 Blazor 페이지 API-First 마이그레이션 완료 -- MudDataGrid 더존 세무회계프로그램 UX 수준 적용 -- MudDialog 모달 패턴 (흰 화면 플래시 제거) -- ConfirmDialog 삭제 확인 컴포넌트 -- **WebAssembly 렌더 모드 적용** (Admin UI 클라이언트 사이드) +**현재 상태**: **✅ Phase 1-8 COMPLETE & VERIFIED (2026-07-03)** +- ✅ 모든 API 엔드포인트 구현됨 +- ✅ 모든 Browser Client 구현됨 +- ✅ 16개 Blazor 페이지 API-First 마이그레이션 완료 +- ✅ MudDataGrid 더존 세무회계프로그램 UX 수준 적용 +- ✅ MudDialog 모달 패턴 (흰 화면 플래시 제거) +- ✅ ConfirmDialog 삭제 확인 컴포넌트 +- ✅ **WebAssembly 렌더 모드 완전 적용** (Admin UI 클라이언트 사이드) +- ✅ **E2E 테스트 검증 완료** (20/20 테스트 통과 - 프로덕션 환경) + - Desktop Chrome: 5/5 + - iPhone 12: 5/5 + - iPad Pro: 5/5 + - Galaxy S9+: 5/5 +- ✅ 배포 스크립트 환경 변수 강화 --- @@ -310,22 +336,33 @@ Repositories (데이터 계층) TaxBaik.Domain 클래스 라이브러리 (엔티티, 인터페이스, enum) TaxBaik.Infrastructure 클래스 라이브러리 (Dapper repository, DB 마이그레이션) TaxBaik.Application 클래스 라이브러리 (서비스, DTO, 비즈니스 로직) -TaxBaik.Web ASP.NET Core 앱 (포트 5001) +TaxBaik.Web ASP.NET Core 앱 (포트 5001 - 서버는 순수 API) ├─ Pages/ Razor Pages (공개 홈페이지, 블로그, 문의폼) ├─ Components/ │ ├─ (Web pages) - │ └─ Admin/ Blazor Server (관리자 백오피스) - │ ├─ Pages/ - │ ├─ Layout/ - │ └─ App.razor - └─ Services/ 인증, 블로그, 문의 등 + │ └─ App.razor Blazor Root (WebAssembly 렌더링) + └─ Services/ 인증, 블로그, 문의 등 (API만 제공) + +TaxBaik.Web.Client (NEW) Blazor WebAssembly WASM 클라이언트 + ├─ _Imports.razor 네임스페이스 임포트 + └─ Components/ + └─ Admin/ 관리자 페이지 (클라이언트 사이드) + ├─ Pages/ (모든 페이지) + ├─ Layout/ (레이아웃) + ├─ Shared/ (공유 컴포넌트) + ├─ App.razor Root 컴포넌트 + └─ Routes.razor 라우팅 정의 ``` **경로:** - 홈페이지: `/taxbaik` (Razor Pages) -- 관리자: `/taxbaik/admin` (Blazor Server) +- 관리자: `/taxbaik/admin` (Blazor WebAssembly - CSR) - 로그인: `/taxbaik/admin/login` +**렌더링 방식**: +- 공개 사이트: SSR (Razor Pages) - SEO 최적화 +- 관리자 페이지: CSR (Blazor WebAssembly) - 클라이언트 사이드 + **운영 원칙:** - 단일 앱, 단일 서비스, 단일 배포 경로를 유지한다. - 운영 변경은 코드 또는 CI에서만 반영한다. @@ -641,13 +678,35 @@ ssh kjh2064@178.104.200.7 - 기존 포트에서 동작하던 구버전 .NET 프로세스를 종료(`kill -15`)합니다. - 만약 헬스 체크 실패 시 새 프로세스만 강제 종료하고 배포를 롤백하여 실서비스 다운타임을 방지합니다. +**배포 환경 변수 (deploy_gb.sh에서 반드시 설정)**: +```bash +export ASPNETCORE_ENVIRONMENT=Production +export ASPNETCORE_URLS="http://127.0.0.1:$TARGET_PORT" +export ConnectionStrings__Default="Host=localhost;Database=taxbaikdb;Username=taxbaik;Password=taxbaik123" +export DOTNET_PRINT_TELEMETRY_MESSAGE=false +``` + +⚠️ **필수 주의사항**: +- `ConnectionStrings__Default` 누락 시 배포 실패 (Missing connection string) +- 환경 변수는 dotnet 프로세스 시작 전에 export되어야 함 +- deploy_gb.sh의 "Starting New App on Port" 섹션에서 설정 필수 + **운영 규칙**: - 로컬 또는 서버에서 수동 `dotnet publish`로 운영 배포하지 않는다. - 배포 실패 시 Gitea Actions CI/CD 로그 및 `~/deployments/taxbaik_timestamp/web_*.log`를 먼저 확인한다. -- 배포 후 최종 검증은 프록시 포트를 경유하는 메인 홈페이지, 관리자 로그인 페이지, 로그인 API를 모두 포함한다. + - `Missing connection string` → deploy_gb.sh 환경 변수 확인 + - `core dumped` + `Health check failed` → Program.cs 초기화 에러 확인 +- 배포 후 최종 검증: + - ✅ E2E 테스트 (20/20 통과 기준) + - ✅ 프록시 포트 경유 (www.taxbaik.com) + - ✅ 메인 홈페이지 HTTP 200 + - ✅ 관리자 로그인 페이지 로드 + - ✅ 로그인 API 응답 **롤백**: -- 이전 정상 커밋을 `master`에 revert 또는 hotfix로 되돌려 다시 배포를 수행하거나, 비상시 서버의 `taxbaik_port` 파일의 포트 번호를 수동 수정하여 이전 버전 포트로 즉시 원상복구한다. +- 배포 실패 시 자동 롤백 (이전 포트로 즉시 복구) +- 수동 롤백: 이전 정상 커밋을 `master`에 revert 후 다시 배포 +- 긴급 복구: 서버의 `taxbaik_port` 파일 수동 수정 ### 3.4 서비스 파일 위치 ```