[Docs] 프로젝트 README 및 Compose-React 비교 정리

[ksubin-dev]

작업 내용

기존 Vite 기본 README를 제거하고,
현재까지 구현한 React Web POC 내용을 기준으로 프로젝트 전용 README를 작성했습니다.

이번 README에서는 프로젝트의 구현 범위를 과장하지 않고,
기존 Android 금융 테스트와 React POC의 관계,
상태 및 데이터 흐름,
테스트와 CI,
Compose와 React의 구현 방식 차이를 중심으로 정리했습니다.

---

주요 변경 사항

프로젝트 소개

기존 Android 유형 테스트 전체를 React로 마이그레이션한 것이 아니라,
기존 금융 테스트 1개를 React + TypeScript로 다시 구현한 Web POC임을 명확히 작성했습니다.

기존 프로젝트의 흐름도 다음 정도로만 짧게 정리했습니다.

V1  Java + XML + Activity
V2  Host Activity + Fragment
V3  Kotlin + Jetpack Compose 금융 테스트
React POC  V3 금융 테스트를 React + TypeScript로 재구현

---

주요 화면

기존 반응형 UI 검증 과정에서 사용한 실제 화면 이미지를 README에 재사용했습니다.

포함한 화면:

Mobile StartScreen
Mobile QuizScreen
Mobile ResultScreen
Desktop QuizScreen

모바일 3개 화면은 한 번에 흐름을 확인할 수 있도록 가로로 배치했습니다.

---

구현 범위 & Tech Stack

실제 React POC에서 구현한 범위만 작성했습니다.

금융 테스트 1개
질문 6개
결과 3개
Start → Quiz → Result → Restart
모바일 / 데스크톱 반응형 UI
Vitest 결과 계산 단위 테스트
GitHub Actions PR CI

실제로 사용한 기술만 Tech Stack에 포함했습니다.

React
TypeScript
Vite
CSS
ESLint
Prettier
Vitest
GitHub Actions

---

프로젝트 구조

전체 Vite 기본 파일을 나열하지 않고,
이번 구현에서 역할이 있는 주요 구조만 정리했습니다.

src/
├─ components/
│  ├─ StartScreen/
│  ├─ QuizScreen/
│  └─ ResultScreen/
├─ data/
│  └─ financeTest.ts
├─ types/
│  └─ financeTest.ts
├─ utils/
│  ├─ resultCalculator.ts
│  └─ resultCalculator.test.ts
└─ App.tsx

.github/
└─ workflows/
   └─ ci.yml

각 영역의 역할도 다음과 같이 구분했습니다.

data
→ 금융 테스트 데이터

types
→ 데이터 구조 정의

components
→ 화면 UI 및 사용자 이벤트

utils
→ 결과 계산 로직 및 단위 테스트

App
→ 화면 흐름 및 State 관리

별도의 Architecture 이름은 붙이지 않았습니다.

---

State 및 데이터 흐름

App.tsx에서 관리하는 핵심 State를 정리했습니다.

screen
currentQuestionIndex
selectedAnswers

데이터 흐름도 함께 작성했습니다.

financeTest
    ↓
   App
    ↓ Props
QuizScreen
    ↓ Callback
   App
    ↓
selectedAnswers
    ↓
calculateResult()
    ↓
ResultScreen

부모에서 Props로 데이터를 전달하고,
자식의 이벤트는 Callback을 통해 다시 부모로 전달하는 흐름을 설명했습니다.

---

주요 구현 포인트

README에 다음 구현 판단을 정리했습니다.

Props / Callback 흐름
최소 State 사용
Derived Value 분리
데이터 / UI / 계산 로직 역할 분리
마지막 Answer 누락 방지 처리

currentQuestion, totalQuestions, progressPercent, result처럼
기존 State에서 계산 가능한 값은 별도 State로 저장하지 않고
Derived Value로 처리한 점도 포함했습니다.

---

결과 계산 및 테스트

기존 Kotlin 금융 테스트의 결과 계산 규칙을 React 버전에서도 유지했습니다.

1. 선택 Answer의 scores를 Result ID별로 누적
2. 가장 높은 점수의 Result 선택
3. 동점이면 results 배열에서 먼저 정의된 Result 선택
4. 선택 답변 없음 / 유효 점수 없음 / 전체 점수 0이면 Result ID 3

결과 계산 로직은 UI와 분리된 Pure Function으로 구성했고,
Vitest 단위 테스트 내용을 README에 정리했습니다.

Test Files : 1 passed
Tests      : 8 passed

주요 검증 범위:

Result 1 / 2 / 3 반환
점수 누적
동점 처리
선택 답변 없음
유효 점수 없음
전체 점수 0

---

GitHub Actions CI

Issue #10에서 구성한 실제 CI 흐름을 README에 정리했습니다.

Pull Request to develop / main
      ↓
Checkout
      ↓
Node.js 24 + npm cache
      ↓
npm ci
      ↓
ESLint
      ↓
Vitest
      ↓
Production Build

Workflow YAML 전체를 복사하지 않고,
현재 프로젝트에서 실제 사용하는 검증 흐름만 설명했습니다.

---

Compose ↔ React 비교

Android Compose와 React가 완전히 동일한 개념이라는 의미가 아니라,
이번 POC에서 맡은 역할과 데이터 흐름을 기준으로 비교했습니다.

주요 비교 항목:

Composable ↔ Component
Parameter ↔ Props
Lambda Callback ↔ Callback Props
Compose State ↔ useState
Recomposition ↔ Re-render
Kotlin data class ↔ TypeScript type
계산 함수 분리 ↔ Pure Function

실제 구현 경험을 기준으로 설명하고,
React 실무 프로젝트나 Android 전체 마이그레이션처럼 표현하지 않았습니다.

---

실행 방법

Node.js 24 기준으로 실행 방법을 작성했습니다.

npm install
npm run dev

검증 명령:

npm run lint
npm run test:run
npm run build

---

README 작성 원칙

이번 README에서는 다음 내용을 의도적으로 제외했습니다.

Android 전체 앱 React 마이그레이션 표현
React 실무 프로젝트 표현
MVVM / Clean Architecture 적용 주장
Coverage 수치
배포
E2E 테스트
사용자 수 / 성능 개선 수치
사용하지 않은 기술
근거 없는 확장성 / 유지보수성 표현

실제 구현한 범위와 코드에서 확인 가능한 내용만 작성했습니다.

---

변경 파일

README.md

README 외 production code, test code, CI workflow, dependency 파일은 수정하지 않았습니다.

---

검증

README 작성 후 기존 프로젝트가 정상적으로 유지되는지 확인했습니다.

npm.cmd run lint
npm.cmd run test:run
npm.cmd run build
npx.cmd prettier --check .

결과:

ESLint   passed
Vitest   1 file / 8 tests passed
Build    passed
Prettier passed

---

확인 사항

• Vite 기본 README 제거
• 프로젝트 소개 작성
• Android 금융 테스트와 React POC 관계 설명
• 주요 화면 이미지 추가
• 구현 범위 작성
• 실제 Tech Stack 작성
• 프로젝트 구조 작성
• State / Props / Callback 흐름 작성
• Derived Value 설명
• 데이터 / UI / 계산 역할 분리 설명
• 마지막 Answer 처리 설명
• 결과 계산 규칙 작성
• Vitest 1 file / 8 tests 작성
• GitHub Actions CI 흐름 작성
• Compose ↔ React 역할 기준 비교 작성
• 실행 방법 작성
• 구현 범위를 벗어난 내용 제외
• lint 통과
• Vitest 통과
• build 통과
• Prettier 통과
• GitHub README 렌더링 최종 확인
• GitHub Actions quality-check 성공 확인

---

Related Issue: #11