Refine admin login flow and verification harness

docs/ENGINEERING_HARNESS.md

@@ -31,6 +31,7 @@
 - Infrastructure는 Dapper SQL과 외부 시스템 구현을 가진다.
 - Web은 Controller, 공개 Razor Pages SSR, Blazor host, 인증/서빙 설정을 가진다.
 - Web.Client/Admin UI는 클라이언트 사이드 Blazor WebAssembly로 본다. 서버 DI 서비스에 의존하지 않고 API client만 호출한다.
+- 로그인 화면은 정적 SSR 또는 Razor Page form으로 처리하고, 홈/대시보드 같은 상호작용 화면만 Interactive WebAssembly + MudBlazor를 사용한다.
 - 관리자 호스트가 prerender를 사용하더라도 데이터 접근 원칙은 WASM + API-first다. prerender는 초기 마크업용이며 비즈니스 로직의 근거가 아니다.
 - 어드민 기본 렌더는 WASM이다. 다만 초기 흰 화면 방지 목적의 셸 프리렌더와 로그인 화면의 서버 프리렌더는 허용한다. 비즈니스 로직은 여전히 API-first다.
 - 로그인 화면은 예외적으로 “먼저 보여야 하는 화면”이다. JS 바인딩/텔레메트리/하이드레이션이 실패해도 로그인 폼 자체는 화면에 남아 있어야 하며, 실패 시 흰 화면이나 빈 본문을 허용하지 않는다.
@@ -58,6 +59,9 @@
 | 리팩토링 | 동작 보존 테스트를 먼저 추가하고 작은 단위로 이동 |
 | 일관성 | 오류 응답은 ProblemDetails, 페이징은 `{ data, total, page, pageSize }` |
 | 파편화 방지 | 같은 필드/상태/서비스유형 문자열은 enum/상수/공통 코드 중 하나로 단일화 |
+| UI 상태 | Blazor 화면의 폼/목록 상태는 MVVM 스타일의 ViewModel로 분리 |
+| DTO 검증 | DTO에는 `System.ComponentModel.DataAnnotations` 어노테이션을 1차 기준으로 둔다 |
+| 추가 검증 | 어노테이션만으로 표현이 부족할 때만 FluentValidation을 보완으로 쓴다 |
 | 과유불급 | 추상화는 2개 이상 실제 사용처가 생긴 뒤 도입 |
 | 정규화 | 고객, 문의, 상담, 계약, 세금신고는 원천 테이블을 분리 |
 | 역정규화 | 대시보드/검색/운영 요약용 스냅샷만 허용하고 원천 id와 갱신 시점을 저장 |
@@ -71,6 +75,7 @@
 
 - DB 제약 조건이 1차 방어선이다: NOT NULL, UNIQUE, FK, CHECK, index.
 - Application validation은 사용자 메시지와 use case 규칙을 담당한다.
+- DTO validation은 `DataAnnotations`를 1차 기준으로 하고, 표현력이 부족한 경우에만 FluentValidation으로 보완한다.
 - UI validation은 빠른 피드백일 뿐이며 유일한 검증으로 보지 않는다.
 - 관리자 수정 화면에 노출한 필드는 실제 저장되어야 한다. 저장하지 않는 필드는 read-only로 표시한다.
 - 상태 전이는 허용 목록을 둔다. 임의 문자열 저장을 금지한다.
@@ -79,6 +84,7 @@
 - 로그인 화면은 배포 전 브라우저 실증이 필수다. `dotnet build`만으로 로그인 화면 정상 표시를 완료로 선언하지 않는다.
 - 로그인 화면 실증 기준은 최소 1회 실제 브라우저 응답, 로그인 폼 렌더, 입력 포커스 가능 여부 확인이다.
 - 공개 루트와 관리자 루트는 반드시 분리 검증한다. `https://www.taxbaik.com/` 은 공용 홈페이지 제목을 가져야 하고, `https://www.taxbaik.com/taxbaik/admin/login` 은 관리자 제목을 가져야 한다.
+- 최종 완료 검증은 실제 서비스 도메인에서만 수행한다. IP 직결 주소는 로컬/임시 확인용으로만 사용한다.
 - 배포 후 smoke 기준은 `scripts/taxbaik-smoke.sh`를 1차 기준으로 사용한다. CI와 브라우저 E2E는 이 스크립트를 재사용해야 한다.
 - `UsePathBase("/taxbaik")`가 있는 Web 앱에서 `MapGet("/")` 같은 루트 리다이렉트를 추가할 때는, 반드시 루프 여부를 `curl`로 먼저 확인하고 나서만 반영한다. `/`와 `/taxbaik/`가 서로를 다시 가리키면 안 된다.
 - nginx의 `location /`와 `location /taxbaik`를 건드린 뒤에는, 변경 직후 `curl -I https://www.taxbaik.com/`, `curl -I https://www.taxbaik.com/taxbaik/`, `curl -I https://www.taxbaik.com/taxbaik/admin/login` 순서로 확인하고 결과를 기록한다.
@@ -109,7 +115,7 @@
 | Naming | `Create[Entity]Endpoint`, `Get[Entity]Endpoint`, `List[Entity]Endpoint` 등 |
 | Location | `src/TaxBaik.Web/Features/[DomainName]/` |
 | Pattern | Request DTO → Endpoint class → Response DTO |
-| Validation | FluentValidation (FastEndpoints 내장) |
+| Validation | DTO는 `DataAnnotations` 우선, 부족할 때만 FluentValidation 보완 |
 | Registration | `builder.Services.AddFastEndpoints()` + `app.MapFastEndpoints()` |
 | Coexistence | Controllers와 FastEndpoints는 PathBase 내에서 병행 가능 (URL 충돌만 피함) |
 
@@ -143,7 +149,8 @@ public class GetBlogEndpoint : Endpoint<GetBlogRequest, GetBlogResponse>
 
 ## CI Harness
 
-완료는 로컬 성공이 아니라 CI와 배포본 성공이다.
+완료는 단순 로컬 성공이 아니라, 아래 필수 하네스를 모두 통과하고 그 증빙이 남아야 한다.
+실행 순서는 항상 `로컬 1차 검증 -> CI 배포 -> 실제 도메인 최종 검증`이다.
 
 | Gate | Command/Check | Target |
 | --- | --- | --- |
@@ -155,6 +162,42 @@ public class GetBlogEndpoint : Endpoint<GetBlogRequest, GetBlogResponse>
 | Deploy | `.gitea/workflows/deploy.yml` | success |
 | Post Deploy | `.gitea/workflows/browser-e2e.yml` | success |
 
+### Validation Order
+
+1. 로컬에서 `dotnet build`와 필요한 unit/Playwright 시나리오를 먼저 통과시킨다.
+1. 로컬 검증이 끝나야 CI 배포를 진행한다.
+1. CI 배포가 성공해야 실제 도메인에서 브라우저 E2E와 smoke를 수행한다.
+1. 실제 도메인 결과와 증빙이 있어야만 최종 완료로 기록한다.
+
+### Definition Of Done
+
+다음 조건을 모두 만족해야 `완료`로 본다.
+
+1. `dotnet build`가 경고/오류 없이 성공한다.
+1. Playwright가 실제 사용자 시나리오를 직접 호출한다.
+1. 시나리오에서 기대한 데이터가 실제 응답 데이터로 검증된다.
+1. 화면 캡처와 DOM 캡처를 남긴다.
+1. 기대값이 실제 화면 결과와 일치한다는 증빙이 데이터로 남는다.
+1. 위 증빙이 없으면 기능이 동작해 보여도 완료로 선언하지 않는다.
+
+### Mandatory Harness
+
+아래 하네스는 선택 사항이 아니라 필수다.
+
+- 빌드 하네스: `dotnet build src/TaxBaik.sln -c Release --no-restore`
+- 브라우저 하네스: Playwright로 실제 사용자 흐름 실행
+- 데이터 하네스: API 응답, DB 값, 또는 화면 데이터가 기대값과 일치하는지 검증
+- 증빙 하네스: 스크린샷, DOM 스냅샷, 테스트 로그를 함께 보관
+- 판정 하네스: 사람의 육안 판단이 아니라 캡처와 로그로 성공 여부를 판정
+
+### Evidence Rules
+
+- Playwright는 단순 페이지 열기만으로 끝내지 않는다.
+- 사용자 관점에서 버튼 클릭, 입력, 저장, 조회 같은 실제 시나리오를 실행해야 한다.
+- 각 시나리오는 기대값과 실제값을 비교하는 assert를 포함해야 한다.
+- 스크린샷은 결과 화면을 증빙하고, DOM 캡처는 화면이 그렇게 나온 구조적 근거를 제공해야 한다.
+- 수동 확인만 있고 데이터 증빙이 없으면 실패다.
+
 ### Gitea Auth Harness
 
 - Gitea API와 workflow dispatch에는 `GITEA_TOKEN_TAXBAIK`만 사용한다.
@@ -168,6 +211,7 @@ public class GetBlogEndpoint : Endpoint<GetBlogRequest, GetBlogResponse>
 - 동일 개념이 3곳 이상 다른 이름/계약으로 구현되면 기능 추가를 중단하고 정리한다.
 - UI가 저장한다고 보이는 필드를 API/Application이 저장하지 않으면 릴리스하지 않는다.
 - 운영 배포 검증이 CI 밖에서만 가능하면 완료로 보지 않는다.
+- 빌드, Playwright 시나리오, 화면 캡처, DOM 캡처, 데이터 일치 증빙이 없는 상태에서 완료라고 쓰지 않는다.
 - `UsePathBase` 아래에서 루트 기본값을 만들려면 리다이렉트보다 실제 최종 콘텐츠가 나오는지 먼저 확인한다. 루트가 `/taxbaik/`를 다시 반환하면 즉시 중단한다.
 - lint가 필요하면 build보다 먼저, 그리고 배포보다 훨씬 앞단에서 실패시키고, lint가 없는 프로젝트에 억지로 새 lint 체계를 만들지 않는다.
 - 데이터 모델을 추측해서 세무 규칙이나 더존 UX 관습을 왜곡해 구현하지 않는다.