docs: Update architecture guidelines for Razor Pages + Cookie Auth (2026-07-09)
TaxBaik CI/CD / build-and-deploy (push) Successful in 58s

- Add architecture change notice in CLAUDE.md (Blazor WASM → Razor Pages)
- Mark Phase 8/9/13 as [레거시] (no longer current standard)
- Update priority guidelines: add ADMIN_RAZORPAGES_ROADMAP.md and ADMIN_LEGACY_BLAZOR.md
- Fix STACK_TEMPLATE_WBS.md Target Template table: Admin CRUD now uses Razor Pages + Cookie Authentication
- Add legacy references for previous WebAssembly/MudBlazor approach

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-07-09 21:23:53 +09:00
parent 0cf881c652
commit 81b2b1ebdf
2 changed files with 29 additions and 12 deletions
+24 -7
View File
@@ -1,12 +1,29 @@
# CLAUDE.md — TaxBaik 운영 메모
## ⚠️ **중요: 2026-07-09 아키텍처 변경**
**현재 기준 (2026-07-09~):**
- 관리자 UI: **Razor Pages + Cookie Authentication** (서버 렌더링)
- UI 프레임워크: **Tabler** (Bootstrap 5 기반)
- 인증: **Cookie Authentication** (브라우저), JWT (외부 API)
- **자세한 기준은 아래 우선 기준의 문서들을 참고해주세요.**
**이전 기준 (2026-07-03 이전):**
- 관리자 UI: Blazor WebAssembly + MudBlazor (Phase 8/9 참고, 이제 레거시)
- 해당 섹션은 과거 이력으로만 참고 (기준이 아님)
---
## 우선 기준
1. [docs/INDEX.md](./docs/INDEX.md)
2. [docs/ENGINEERING_HARNESS.md](./docs/ENGINEERING_HARNESS.md)
3. [docs/DOUZONE_UX_GUIDE.md](./docs/DOUZONE_UX_GUIDE.md)
4. [docs/COMMON_CODE_POLICY.md](./docs/COMMON_CODE_POLICY.md)
5. [docs/COMBO_POLICY.md](./docs/COMBO_POLICY.md)
2. [docs/ADMIN_RAZORPAGES_ROADMAP.md](./docs/ADMIN_RAZORPAGES_ROADMAP.md) ⭐ **신규 어드민 표준**
3. [docs/ADMIN_LEGACY_BLAZOR.md](./docs/ADMIN_LEGACY_BLAZOR.md) (레거시 Blazor 관리)
4. [docs/ENGINEERING_HARNESS.md](./docs/ENGINEERING_HARNESS.md)
5. [docs/STACK_TEMPLATE_WBS.md](./docs/STACK_TEMPLATE_WBS.md) (갱신됨)
6. [docs/DOUZONE_UX_GUIDE.md](./docs/DOUZONE_UX_GUIDE.md)
7. [docs/COMMON_CODE_POLICY.md](./docs/COMMON_CODE_POLICY.md)
8. [docs/COMBO_POLICY.md](./docs/COMBO_POLICY.md)
이 파일은 실행 절차, 서버 메모, 과거 이력만 둔다. 아키텍처/UX/콤보 기준은 위 문서를 따른다.
@@ -315,7 +332,7 @@ _refreshTokenExpirationMinutes = 10080;
**완료**: 2026-06-28 / 모든 도메인 API-First 마이그레이션 완료
#### Phase 8: WebAssembly 렌더 모드 전환 ✅ (2026-07-03)
#### Phase 8: [레거시] WebAssembly 렌더 모드 전환 ✅ (2026-07-03)
- [x] InteractiveWebAssemblyRenderMode 적용 (Blazor Server → WebAssembly)
- [x] Admin 컴포넌트 WebAssembly 클라이언트 전환
- [x] 서버 상태 관리 제거 (Circuit 불필요)
@@ -362,7 +379,7 @@ export DOTNET_PRINT_TELEMETRY_MESSAGE=false
**⚠️ Phase 8 알려진 한계 (Phase 9에서 수정됨)**:
Phase 8에서는 `<Routes>`(App.razor)와 `<Router>`(Routes.razor)에 전역 `@rendermode`를 지정해 `prerender: false`로 고정했다. 그 결과 로그인 화면을 포함한 모든 어드민 페이지가 WASM 다운로드 완료 전까지 빈 화면/스피너만 보여주는 문제가 있었다(`scripts/validate_admin_render.sh`에 이 트레이드오프가 "기능 우선, 흰 화면 0.5~2초 감수"로 기록되어 있었음). 이는 `docs/ENGINEERING_HARNESS.md`의 "로그인 화면은 예외적으로 서버 프리렌더 허용" 규칙을 충족하지 못한 상태였다. Phase 9에서 페이지별 개별 렌더모드 지정으로 교체했다.
#### Phase 9: 어드민 페이지별 렌더모드 정상화 ✅ (2026-07-03)
#### Phase 9: [레거시] 어드민 페이지별 렌더모드 정상화 ✅ (2026-07-03)
- [x] `App.razor`/`Routes.razor`에서 전역 `@rendermode` 제거 (Router/Routes 자체는 렌더모드를 강제하지 않음)
- [x] `Login.razor``@rendermode @(new InteractiveWebAssemblyRenderMode(prerender: true))`로 명시 → 로그인 폼이 최초 HTML 응답에 정적으로 포함되어 WASM 다운로드 중에도 즉시 표시됨
- [x] 나머지 `[Authorize]` 어드민 페이지는 `@rendermode @(new InteractiveWebAssemblyRenderMode(prerender: false))`로 명시 유지 → 인증 컨텍스트 없이 prerender될 때 `AuthorizeRouteView`가 빈 화면을 그리는 문제(Phase 8 초기에 겪었던 문제) 재발 방지
@@ -372,7 +389,7 @@ Phase 8에서는 `<Routes>`(App.razor)와 `<Router>`(Routes.razor)에 전역 `@r
**완료**: 2026-07-03 / 로그인 흰 화면 제거 + 인증 페이지 안정성 유지
#### Phase 13: FastEndpoints 마이그레이션 ✅ (2026-07-03)
#### Phase 13: [레거시] FastEndpoints 마이그레이션 ✅ (2026-07-03)
- [x] AdminDashboardController → FastEndpoints 마이그레이션
- GetSummaryEndpoint.cs (GET /api/admin-dashboard/summary)
- GetUpcomingFilingsEndpoint.cs (GET /api/admin-dashboard/upcoming-filings)
+5 -5
View File
@@ -18,12 +18,12 @@
| 영역 | 권장 방식 | 비고 |
| --- | --- | --- |
| Public Home | Static SSR + 필요한 부분만 Interactive WebAssembly | 초기 로딩과 SEO 우선 |
| Login | Static SSR 또는 Razor Page form | MudBlazor 의존 금지 |
| Home/Dashboard | Interactive WebAssembly + MudBlazor | 사용자 인터랙션 중심 |
| Admin CRUD | Interactive WebAssembly + API-first | BrowserClient 경유 |
| API | Minimal API 또는 Controller + OpenAPI | 계약 우선 |
| Login | Razor Pages form + Cookie Authentication | MudBlazor 의존 금지 (레거시: Interactive WebAssembly 참고) |
| Home/Dashboard | Razor Pages + Cookie Authentication | 서버 렌더링 우선 (레거시: Interactive WebAssembly + MudBlazor 참고) |
| Admin CRUD | Razor Pages + Repository Pattern + Tabler UI | Cookie Authentication 기준 (레거시: Interactive WebAssembly + API-first 참고) |
| API | Controller + OpenAPI (외부 클라이언트) | 계약 우선, JWT 기반 |
| Persistence | Dapper + `NpgsqlDataSource` singleton | connection pool 직접 관리 금지 |
| Auth | 브라우저는 HttpOnly Secure Cookie 우선, 외부 클라이언트만 JWT | localStorage 저장 금지 |
| Auth | 브라우저는 Cookie Authentication, 외부 클라이언트만 JWT | localStorage 저장 금지 |
현재 저장소 기준 예외: