docs: README 전면 재작성 + ARCHITECTURE.md 신규 생성

- README: 프로젝트 설명, 기능, 기술 스택, 빌드, 구조, 라이선스 - ARCHITECTURE: 계층 다이어그램, 데이터 흐름, DI, 수익화, 저장, 테스트
2026-03-30 22:03:15 +09:00
parent 4c502df573
commit b0568480f6
2 changed files with 330 additions and 13 deletions
--- a/README.md
+++ b/README.md
@@ -1,25 +1,103 @@
 # Ascii Never Die

-Offline Flutter rebuild of **Progress Quest 6.4** (single-player only). Network features are stripped; all game data and saves live locally.
+Progress Quest 6.4의 핵심 메커니즘을 기반으로, "디지털 판타지" 세계관과 확장된 시스템으로 재구성한 오프라인 싱글플레이어 방치형 RPG.

-## Layout
- `lib/src/features/front/` – temporary front screen shell to hang the upcoming flow on.
- `doc/progress-quest-flutter-plan.md` – working plan/notes for the port.
- `example/pq/` – original Delphi source/assets (reference only, not built).
+## 스크린샷
+
+<!-- TODO: 스크린샷 추가 -->
+| 타이틀 | 캐릭터 생성 | 게임 진행 |
+|--------|-------------|-----------|
+| ![타이틀](docs/screenshots/front.png) | ![생성](docs/screenshots/new_character.png) | ![게임](docs/screenshots/game.png) |
+
+| 아레나 | 명예의 전당 | 설정 |
+|--------|-------------|------|
+| ![아레나](docs/screenshots/arena.png) | ![명예의 전당](docs/screenshots/hall_of_fame.png) | ![설정](docs/screenshots/settings.png) |
+
+## 주요 기능
+
+- **6개 화면** -- 타이틀/세이브 선택, 캐릭터 생성(3d6 스탯 롤), 게임 진행(장비/인벤토리/퀘스트/스킬/전투로그/스토리), 아레나 PvP, 명예의 전당, 설정
+- **완전 오프라인** -- 네트워크 불필요. 모든 게임 데이터와 세이브가 로컬에 저장
+- **수익화** -- AdMob 리워드/인터스티셜 광고 + IAP 광고 제거/프리미엄
+- **다국어 지원** -- 한국어, 영어, 일본어 (앱 UI + 게임 데이터)
+- **ASCII 아트 애니메이션** -- Canvas 기반 전투/탐험/마을 씬, 종족별 캐릭터 프레임
+- **보안** -- 세이브 파일 HMAC-SHA256 무결성 검증, IAP 영수증 RSA 서명 검증
+
+## 기술 스택
+
+| 구분 | 기술 |
+|------|------|
+| 프레임워크 | Flutter 3.x / Dart ^3.9.2 |
+| 상태 관리 | Stream + 직접 관리 |
+| 코드 생성 | freezed + json_serializable |
+| DI | GetIt (서비스 로케이터) |
+| 광고 | google_mobile_ads 7.x |
+| 인앱결제 | in_app_purchase 3.x |
+| 보안 저장 | flutter_secure_storage, crypto (HMAC), pointycastle (RSA) |
+| 오디오 | just_audio |
+| 폰트 | JetBrainsMono (ASCII), PressStart2P (레트로 UI) |
+
+## 빌드 및 실행

-## Run
 ```bash
+# 의존성 설치
 flutter pub get
+
+# 코드 생성 (freezed/json_serializable)
+dart run build_runner build --delete-conflicting-outputs
+
+# 실행 (-d macos, -d chrome, -d android 등)
 flutter run
-```

-Use any supported platform (`-d macos`, `-d chrome`, etc.); multi-platform scaffolding is enabled.
-
-## Checks
-Run from repo root before handoff:
-
-```bash
+# 검증
 dart format --set-exit-if-changed .
 flutter analyze
 flutter test
 ```
+
+## 프로젝트 구조
+
+```
+lib/
+├── main.dart                 # 앱 진입점
+├── data/                     # 정적 게임 데이터 (종족, 직업, 스킬, 포션, 스토리)
+├── l10n/                     # 앱 UI 다국어 리소스 (arb)
+└── src/
+    ├── app.dart              # MaterialApp 설정
+    ├── core/
+    │   ├── engine/           # 게임 루프, 전투, 보상, 스킬 등 30개 서비스
+    │   ├── model/            # GameState, 장비, 스킬, 전투 등 데이터 모델
+    │   ├── infrastructure/   # AdMob, IAP 외부 서비스 구현
+    │   ├── di/               # GetIt 서비스 로케이터 + 인터페이스
+    │   ├── audio/            # BGM/SFX 오디오 서비스
+    │   ├── storage/          # 세이브/설정/통계 저장소
+    │   └── util/             # RNG, 밸런스 상수, PQ 로직 헬퍼
+    ├── features/
+    │   ├── front/            # 타이틀/세이브 선택
+    │   ├── new_character/    # 캐릭터 생성
+    │   ├── game/             # 메인 게임 (탭별 페이지 + 위젯)
+    │   ├── arena/            # 아레나 PvP
+    │   ├── hall_of_fame/     # 명예의 전당
+    │   └── settings/         # 설정
+    └── shared/               # 테마, 레트로 위젯, ASCII 애니메이션
+
+example/pq/                   # Delphi 원본 소스 (참조용)
+test/                         # 단위/위젯/회귀 테스트 (25개 파일)
+```
+
+아키텍처 상세는 [ARCHITECTURE.md](ARCHITECTURE.md) 참조.
+
+## 릴리즈 이력
+
+| 버전 | 날짜 | 주요 내용 |
+|------|------|-----------|
+| 1.1.0 | 2026-03-30 | IAP RSA 검증, HMAC 세이브, CI, 테스트 105개 추가 |
+| 1.0.1 | 2026-03-19 | 초기 릴리즈 (Google Play 내부 테스트) |
+
+전체 변경 이력은 [CHANGELOG.md](CHANGELOG.md) 참조.
+
+## 라이선스
+
+비공개 프로젝트. 무단 배포 금지.
+
+Progress Quest 원본 소스(`example/pq/`)는 참조용으로만 포함되어 있습니다.
+폰트 라이선스: JetBrains Mono (SIL OFL 1.1), Press Start 2P (SIL OFL 1.1).