Yun Chan 0e568f1f0a feat(ads/seo/release): v1.2.0 with live Google Ads, isolated ad profile, ads.txt, and SEO/AEO/GEO optimization

2026-09-14 00:39:44 +09:00

17 KiB

Raw Blame History

Paca E2E TDD & 초고강도 디자인 감사 이론 체계 (SSOT)

문서 상태: 단일 진실 공급원 (Single Source of Truth)
기준 시점: 2026년 9월
적용 대상: Paca 솔루션 전체 (Paca.Core, Paca.App, Paca.Browser, Paca.Server, Paca.Mobile, site/, tests/)
철학: "테스트가 증명하지 않은 코드는 존재하지 않는다. 기계적으로 검증되지 않은 디자인은 결함이다."

제1장. TDD의 근본 헌법 (Canonical Laws of TDD)

1.1 Kent Beck의 원형 사이클 (Test-Driven Development: By Example)

테스트 주도 개발(TDD)의 창시자 Kent Beck이 규정한 핵심 원리는 **"두 가지 단순한 규칙"**에서 출발한다:

결함이 있는 자동화 테스트가 실패하기 전에는 새로운 코드를 작성하지 않는다.
중복을 제거한다(Eliminate Duplication - Refactoring).

이 두 규칙은 리듬감 있는 Red-Green-Refactor 나노 사이클을 형성한다:

🔴 RED: 존재하지 않거나 기대와 다르게 동작하는 기능에 대한 작고 명확한 테스트를 작성하고, 실패를 직접 목격한다.
🟢 GREEN: 오직 실패한 테스트를 통과시킬 목적의 최소한의 코드만을 신속하게 작성한다(가장 단순한 가짜 구현, 상수 반환, 직관적 구현 허용).
🔵 REFACTOR: 테스트가 녹색(GREEN)인 상태를 유지하면서 코드의 악취(Smell), 결합도, 중복을 제거하고 클린 아키텍처로 정제한다.

stateDiagram-v2
    [*] --> RED: 1. 실패하는 최소 테스트 작성
    RED --> GREEN: 2. 테스트를 통과시키는 최소 구현
    GREEN --> REFACTOR: 3. 중복 제거 & 구조 개선 (Green 유지)
    REFACTOR --> RED: 4. 다음 기능 사양 정의

1.2 Robert C. Martin (Uncle Bob)의 TDD 3대 법칙 (The Three Laws of TDD)

Robert C. Martin은 Clean Craftsmanship에서 나노 사이클의 엄격한 규율을 3대 법칙으로 공식화했다:

제1법칙: 실패하는 단위 테스트를 작성하기 전에는 어떠한 프로덕션 코드도 작성할 수 없다.
제2법칙: 컴파일 실패를 포함하여, 실패를 나타내기에 충분한 정도를 넘어서는 단위 테스트를 작성할 수 없다.
제3법칙: 현재 실패하고 있는 단위 테스트 하나를 통과시키기에 충분한 양을 넘어서는 프로덕션 코드를 작성할 수 없다.

이 3대 법칙은 AI 에이전트가 "추측 기반으로 대량의 코드를 쏟아내는 환각(Hallucination)"을 원천적으로 차단하는 절대적 가드레일이다.

1.3 Gerard Meszaros의 xUnit Test Patterns & Anti-Patterns 방어

테스트 스위트가 커질수록 테스트 자체가 기술 부채가 되는 현상을 막기 위해, Meszaros의 패턴과 악취(Smell) 방어 원칙을 준수한다:

Assertion Roulette 방지: 하나의 테스트 메서드 안에 맥락 없는 수십 개의 Assert를 나열하지 않는다. 각 실패 원인을 식별할 수 있도록 명확한 메시지와 독립적인 계약을 부여한다.
Fragile Test 방지: 구현 세부사항(내부 private 변수, 임의의 호출 순서)에 결합하지 않고, **공개 계약(Public Contract)**과 **관찰 가능한 상태(Observable State)**에 결합한다.
Eager Test 방지: 하나의 테스트가 시스템의 너무 많은 기능이나 단계를 한꺼번에 검증하려 하지 않도록 분리한다.

제2장. 현대적 E2E & 피하(Subcutaneous) 테스트 전략

2.1 Martin Fowler의 테스트 피라미드와 실용주의 (The Practical Test Pyramid)

Martin Fowler는 마이크로서비스 및 GUI 애플리케이션의 테스트 전략에서 피라미드 구조를 강조했다:

피라미드 기단 (Unit Tests): 빠르고 결정론적인 격리 테스트. 수천 개 단위로 수 초 내 실행.
피라미드 중단 (Subcutaneous / Integration Tests): UI 직하단(Subcutaneous)에서 전체 비즈니스 로직, 뷰모델, 통신, 저장소를 엮어 검증.
피라미드 상단 (End-to-End GUI Tests): 실제 사용자 화면을 기동하여 전체 여정을 검증. 취약성을 피하기 위해 소수정예의 핵심 여정으로 제한.

          / \
         /   \      E2E GUI Tests (WMI / Live Window) — 고비용, 핵심 여정
        /-----\
       /       \    Subcutaneous Tests (ViewModel, Contracts, Tokens) — 고속, 견고
      /---------\
     /           \  Unit Tests (Core, Alg, Decryption, HLS/DASH) — 초고속, 방대
    /-------------\

2.2 피하 테스트(Subcutaneous Testing)의 핵심 가치

GUI 브라우저 자동화(Selenium, 순수 WinAppDriver)는 렌더링 딜레이, OS 포커스 탈취, 타이밍 이슈로 인해 쉽게 깨진다.
Paca의 E2E TDD는 **피하 테스트 기법(Subcutaneous Testing)**을 극대화한다:

UI 표면 바로 아래 레이어(XAML 파서, Computed Style Engine, Visual Tree Contract, ViewModel 커맨드/상태 머신, HTTP API)를 직접 두드려, 렌더링 타이밍 취약성을 제거하고 100% 결정론적(Deterministic)으로 동작을 보증한다.

2.3 2026 최신 동향: Executable Design Specification & Token-Driven TDD

2026년 현재 생성형 AI 에이전트와 대규모 디자인 시스템의 결합에서 대세가 된 패러다임은 **"실행 가능한 디자인 사양(Executable Design Specification)"**이다:

디자인 토큰(색상, 타이포그래피, 패딩, 여백, 고대비 규격)은 단순한 CSS/XAML 파일이 아니라 **"단위 테스트로 검증되는 불변 계약"**이다.
AI가 코드를 수정할 때 발생하는 보이지 않는 시각적 퇴행(Invisible Visual Regression)을 방지하기 위해, 기계적 테스트 게이트가 토큰의 누락, 불일치, 명도 대비 위반을 실시간으로 차단한다.

제3장. 초고강도 UI/UX 디자인 감사 RED 체계 (Strict Design Gate)

우리는 사용자 경험을 해치는 모든 시각적 결함을 버그로 규정하며, 이를 RED 테스트로 사전에 포착하여 자가 수정한다.

3.1 25대 시각/인터랙션/접근성 감사 규칙 (The 25 Grand Interaction & Design Commandments)

중앙 정렬 및 대칭성 무결성 (Center Alignment & Visual Balance):
- 툴바, 헤더, 모달 다이얼로그의 중앙 정렬 요소가 좌우 비대칭 마진이나 플렉스 오차로 인해 한쪽으로 쏠리는 시각적 치우침(Off-axis tilt)을 영(0)으로 만든다.
컨테이너 오버플로우 방지 (Zero Container Overflow):
- 가로 스크롤 버그(scrollWidth > clientWidth)를 전면 금지한다.
- 긴 텍스트(URL, 파일명, 비디오 제목)는 반드시 TextTrimming="CharacterEllipsis" 또는 반응형 text-wrap: pretty로 감싼다.
WCAG 2.1/2.2 AA/AAA 상대 휘도 & APCA 지각 대비 (Perceptual Contrast):
- 본문 텍스트(TextPrimary, TextSecondary)는 배경 대비 최소 4.5:1 (WCAG AA 기준)을 충족해야 하며, 고대비 모드에서는 7.0:1 (AAA 기준)을 만족해야 한다.
- 비활성/보조 텍스트(TextMuted)도 3.0:1 미만으로 떨어져 "안 보이는 폰트"가 되는 것을 차단한다.
- APCA(Accessible Perceptual Contrast Algorithm)의 공간 주파수 및 다크모드 극성(Polarity) 기준(Lc >= 60~75)을 병행 준수한다.
인풋 필드 규격 및 내부 패딩 (Input Ergonomics):
- 텍스트 박스, URL 입력창 내부의 텍스트가 경계선에 달라붙지 않도록 최소 Padding="8,6" 이상을 보장한다.
- 인풋 높이는 최소 36px~44px를 유지하여 터치/마우스 클릭 실패를 방지한다.
- 포커스 상태에서 눈에 띄는 포커스 링(FocusVisualStyle, BorderBrush)이 반드시 렌더링되어야 한다.
아이콘-텍스트 수직 정렬 정합성 (Icon & Text Vertical Alignment):
- 버튼이나 리스트 아이템 내에서 아이콘(FontIcon, SVG Path)과 레이블 텍스트의 VerticalAlignment="Center" 또는 CSS align-items: center가 100% 일치해야 한다.
- 텍스트 베이스라인과 아이콘 중심선의 불일치로 인한 어색함을 차단한다.
타이포그래피 계층구조 (Typography Hierarchy):
- 제목(H1: 24~~32px, Bold) → 섹션(H2: 18~~22px, SemiBold) → 본문(Body: 13~~15px, Regular) → 캡션(Caption: 11~~12px, Light/Muted)의 일관된 스케일을 유지한다.
- 임의의 매직 넘버 폰트 크기 사용을 금지하고 토큰(FontSize.X)에 바인딩한다.
Flexbox / Grid 레이아웃 왜곡 방지:
- WPF Grid의 컬럼 비율(*, Auto)과 HTML Flexbox의 flex-shrink, flex-grow 오류로 인해 특정 컨트롤이 찌그러지거나 0픽셀로 축소되는 현상을 방지한다.
클릭 타깃 최소 면적 (Hit Target 32px~44px+):
- 닫기 버튼, 탭 전환 버튼, 아이콘 액션 버튼이 너무 작아 클릭하기 힘든 UX 결함을 차단한다. 기본 인터랙션 영역은 32x32px 이상이어야 한다.
디자인 철학 준수 (Designpaca / Swiss Typography / Modern Minimalist):
- 촌스러운 다중 그라데이션, 과도한 드롭 섀도우, 둥근 모서리 남용을 지양한다.
- 차분한 모노크롬 서피스, 정교한 1px 보더(BorderSubtle), 기능적 액센트 컬러 시스템을 엄수한다.
모달 오버레이 무결성 및 시각적 안전성:
- 대화 상자나 팝업 표시 시 뒤쪽 배경의 DimOverlayBrush가 적절히 적용되어 시각적 초점이 흐트러지지 않아야 한다.
WCAG 2.2 타깃 크기 최소 규격 (SC 2.5.8 & 2.5.5 Target Size):
- 24x24 CSS px (WCAG 2.2 Level AA 2.5.8) 절대 최소 면적 강제. 타깃 간 간격 원(24px diameter circle) 중첩 방지.
- 주요 터치 및 클릭 액션(다운로드 시작, 일시정지, 삭제, 탭 닫기)은 44x44 CSS px (Level AAA 2.5.5)를 적극 적용한다.
WCAG 2.2 포커스 외형 및 시인성 (SC 2.4.11 & 2.4.13 Focus Appearance):
- 포커스 링은 최소 2px 이상의 둘레(Perimeter Thickness)와 3:1 이상의 대비비를 유지해야 하며, 다른 플로팅 요소나 모달에 의해 가려지지 않아야 한다(Focus Not Obscured).
다크모드 광륜/난시 생리학적 보호 (Dark Mode Halation & Astigmatism Shield):
- 전체 인구의 30~50%에 달하는 난시 사용자를 위해 완전 검정(#000000) 배경 위에 순백(#FFFFFF) 텍스트의 직접 배치를 차단한다 (고대비 모드 제외).
- 다크모드 표면 표고(Surface Elevation: #121212 -> #1E1E1E -> #2D2D2D) 및 오프화이트 본문(#E2E8F0, #EDEDED)을 적용하여 빛 번짐(Halation Bloom)을 방지한다.
스위스 8pt/4pt 베이스라인 그리드 불변식 (Swiss 8pt/4pt Baseline Invariant):
- 모든 마진, 패딩, 컴포넌트 간격은 Josef Müller-Brockmann과 Karl Gerstner의 그리드 이론에 기반하여 4의 배수(4, 8, 12, 16, 24, 32, 48px)를 엄수한다.
- 홀수나 분수 픽셀(7px, 9px, 13px)의 마진/패딩 누수를 기계적으로 차단한다.
마이크로 타이포그래피 및 고정폭 숫자 안티지터 (Tabular Numerals Anti-Jitter - tnum):
- 다운로드 전송 속도(12.4 MB/s), 남은 시간(00:04:12), 진행률(89.4%) 등 실시간으로 숫자가 갱신되는 텍스트 블록에는 OpenType tnum(Typography.NumeralAlignment="Tabular")을 강제한다.
- 가변폭 숫자(Proportional Figures)로 인한 수평 텍스트 지터(Jitter/Wobble) 현상을 원천 차단한다.
피츠의 법칙 가장자리 무한 타깃 및 캡션 단추 정렬 (Fitts's Law Infinite Boundary):
- 최상단/우측 모서리 창 조작 버튼(Close/Maximize/Minimize)은 여백(Margin)으로 떨어뜨리지 않고 경계에 밀착시켜 마우스 포인터의 난이도 지수 $ID \to 0$을 보장한다.
- 주요 CTA 버튼의 너비와 높이는 충분한 히트 면적(36~44px+)을 유지한다.
힉-하이먼 & 밀러의 법칙 선택지 인지 부하 최적화 (Hick-Hyman & Miller Chunking):
- 툴바 및 최상위 메뉴의 단일 계층 선택지 개수는 $7 \pm 2$개를 초과하지 않도록 세부 서랍(Drawer)과 컨텍스트 메뉴로 계층화한다.
- 다운로드 정보는 [제목/배지] - [진행률/수치] - [조작 버튼]의 3단 청크로 그룹화한다.
WCAG 2.2 드래그 조작 단일 클릭/키보드 대안 보증 (SC 2.5.7 Dragging Movements):
- 탭 순서 이동, 다운로드 큐 우선순위 변경 등 드래그 인터랙션에 대해 반드시 단일 클릭 컨텍스트 메뉴나 키보드 단축키(Ctrl+PageUp/Down, '위로/아래로 이동') 대안을 완비한다.
WCAG 2.2 중복 입력 방지 및 자동 채움 (SC 3.3.7 Redundant Entry):
- 사용자가 이전에 입력한 다운로드 URL, 로그인 자격증명은 브라우저 히스토리, 클립보드 감지, CredentialVault(Windows DPAPI)를 통해 자동 완성 및 재선택 가능해야 한다.
Microsoft UIA FastPass 스크린 리더 계약 (Accessibility Insights for Windows):
- 모든 대화형 컨트롤에 AutomationProperties.Name을 필수로 매핑하고, 순수 시각 장식 요소는 스크린 리더 탐색에서 배제하여 음성 접근성을 보장한다.
윈도우 고대비 모드(WHCM / Forced Colors) WCAG AAA 7.0:1:
- 모든 시맨틱 브러시(TextPrimary, AccentBrush, SuccessBrush, ErrorBrush, SelectionBrush)는 배경에 대해 7.0:1 이상의 초고대비를 엄수한다.
전정기관 보호 움직임 감소(Reduced Motion SC 2.3.3):
- 모든 UI 전환 애니메이션은 최대 300ms 이하로 상한을 두며, 무한 바운스/펄스 모션을 차단한다.
포커스 비가림(Focus Not Obscured SC 2.4.11/2.4.12):
- 스크롤 뷰포트 내부에서 키보드 포커스 탐색 시 항목이 고정 헤더나 툴바에 가려지지 않도록 BringIntoView 가시성을 보장한다.
모달 포커스 트랩 및 Esc 안전 복원:
- 팝업/모달 열람 시 탭 탐색이 외부로 탈출하지 않도록 포커스를 순환시키고, Esc 키 입력 시 즉시 닫고 원래 트리거 요소로 포커스를 복원한다.
게슈탈트 근접성 및 최적 행폭(CPL 50~75) 독서 인체공학:
- 본문 텍스트는 안구 도약 피로를 방지하기 위해 최대 80자 이하의 MaxWidth와 1.5배 이상의 행간을 유지한다.

상세 수학적 정의 및 참고문헌: docs/references/DESIGN_AUDIT_METHODOLOGIES.md

제4장. RED 체계의 수명주기 및 유즈케이스 통폐합 원칙

4.1 맹목적 RED 양산(Red Inflation)의 위험성

테스트 주도 개발에서 흔히 범하는 실수는 "아무런 비즈니스 가치 없는 사소한 속성 하나마다 RED 테스트를 무한 생성하여 테스트 스위트를 비대하게 만드는 것"이다.

테스트 수가 늘어난다고 품질이 비례하지 않는다.
컴파일 에러 유발용 일회성 RED나 사소한 공백 검사는 개발 리듬을 저해하고 유지보수 비용을 폭증시킨다.

4.2 RED 통폐합 및 사용자 유즈케이스 시나리오화

우리는 다음과 같은 기준으로 RED 테스트를 지속적으로 선별·통폐합한다:

단편적 단위 검증 → 복합 시나리오(End-to-End User Journey)로 통합:
- "URL 입력창이 존재한다" + "버튼이 존재한다" + "진행률이 존재한다" 식의 3개 테스트를 분립시키지 않고,
  **"사용자가 비디오 URL을 입력창에 붙여넣고 다운로드 버튼을 클릭하면 다운로드 작업이 등록되고 진행 상태가 업데이트된다"**는 1개의 완전한 복합 유즈케이스 테스트로 통합한다.
의미 없는 RED 추리기:
- 실질적인 사용자 가치(User Value)나 회귀 방지(Regression Guard)에 기여하지 않는 중복 단정문은 제거한다.
진화하는 테스트 스위트:
- 새로운 기능 요구사항이 생기면 기존의 기초 테스트를 깨뜨리지 않고 확장하거나, 보다 높은 수준의 사용자 스토리 계약으로 흡수 통합한다.

제5장. 무중단 자율 완주 루프 (Autonomous Completion Loop)

5.1 자율 루프 4대 게이트 (4 Automated Gates)

모든 에이전트는 아래 4개 게이트를 통과할 때까지 자율적으로 루프를 반복한다:

Gate 1 (Build): 솔루션 전체 빌드 에러 0건, 새로운 컴파일러 경고 0건.
Gate 2 (TDD Suite): dotnet test tests/Paca.Tests 실패 0건, 건너뜀(Skip) 0건, 전체 통과.
Gate 3 (Design Audit Gate): VisualDesignGateTests 및 디자인 시스템 계약 100% 통과.
Gate 4 (Smoke Verification): WMI 분리 런처(agy-gui-launch.ps1)를 통한 실제 데스크톱 윈도우 생성 및 핸들 획득 검증.

5.2 완료의 정의 (Definition of Done)

이론 SSOT 수립 및 아카이빙 완료
에이전트 지침서(AGENTS.md) 동기화 완료
취약한 테스트(Fragile Tests) 무결성 회복 (외부 네트워크 의존 제거)
초고강도 시각/디자인 감사 테스트 확장 및 전수 통과
프로덕션 빌드 성공 및 실창 렌더링 확인
감사 문서(docs/IMPLEMENTATION_AUDIT.md, docs/BACKLOG.md) 최신화 완료

17 KiB Raw Blame History