fix(tunnel): Named Tunnel 타임아웃 버그 수정 및 README 현행화

SOIV · claude · SOIV · commit 78f78e661543 · 2026-04-26T19:36:50.000+09:00
- Named Tunnel은 url 이벤트를 발생시키지 않아 60초 타임아웃 발생하던 문제 수정
- Named 모드에서 2초 대기 후 프로세스 생존 확인으로 성공 처리
- AdminView에서 named 터널 URL을 의미 있는 안내 문구로 표시
- README(ko/en)를 로드맵 문서 기준으로 현행화 (Phase 2.2 진행 중)

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -1,127 +1,134 @@
-# Fieldstack
-
-> Personal modular productivity framework
-
-[![한국어](https://img.shields.io/badge/README-한국어-blue)](README_ko.md)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub Org](https://img.shields.io/badge/GitHub-fieldstack--project-181717?logo=github)](https://github.com/fieldstack-project)
-
----
-
-## About
-
-Fieldstack is an open-source, self-hosted modular framework for personal productivity and finance management.
-
-**Developed and maintained by** [PSquare DIVISION](https://github.com/psquare-division)
-
-### Core Values
-- ✅ **Completely Free** - No feature restrictions
-- ✅ **Self-hosted** - Your data, your control
-- ✅ **Modular** - Install only what you need
-- ✅ **Open Source** - MIT License
-- ✅ **Community-driven** - Built together
-
----
-
-## Development Status
-
-Current phase: **Development in progress (Roadmap Phase 1.5)**
-
-- ✅ Planning and documentation are complete
-- ✅ Roadmap Phase 1 (Core foundation) is complete
-- ✅ Roadmap Phase 1.9 (API server, DB, auth backend, shared links) is complete
-- 🚧 Roadmap Phase 1.5 (Core Control Plane UI/UX) is nearing completion
-- 🎯 Target timeline remains **2026-2027**
-
-### Phase Progress
-
-| Phase | Scope (Roadmap) | Status | Progress |
-| ------- | ----------- | ------- | ------- |
-| Phase 1 | Core foundation setup | Completed ✅ | 100% |
-| Phase 1.5 | Core Control Plane UI/UX | In progress ⏳ | 90% |
-| Phase 1.9 | API server · DB · auth backend · shared links | Completed ✅ | 100% |
-| Phase 1.95 | Setup install wizard (mode switch · backend API · UI) | In progress ⏳ | 0% |
-| Phase 2 | Core module development (Ledger, Subscription) | Not started 🚧 | 0% |
-| Phase 3 | Marketplace and website | Not started 🚧 | 0% |
-| Phase 4 | Deployment optimization | Not started 🚧 | 0% |
-| Phase 5 | Expansion and ecosystem | Not started 🚧 | 0% |
-| Phase 6 | Community growth (continuous) | Not started 🚧 | 0% |
-
-#### Phase 1.5 Snapshot (2026-04-15)
-
-| Sub-phase | Scope | Status |
-| --------- | ----- | ------ |
-| 1.5.1 | Control UI components (P0/P0.5 implemented, `ready: true`) | Done ✅ |
-| 1.5.2 | Install wizard dev bypass (`dev:bypass`) | Done ✅ |
-| 1.5.3 | Login UX (failure/lock/session expiry, password recovery, mock accounts) | Done ✅ |
-| 1.5.4 | Main Home (sidebar, deep link routing, mobile drawer, onboarding banner) | Done ✅ |
-| 1.5.5 | Admin dashboard / general settings (PIN step-up, audit log, dirty-state save) | Done ✅ |
-| 1.5.6 | UX quality baseline (responsive breakpoints, QA checklist, a11y, tone guide) | Done ✅ |
-| Gate | Accessibility / responsive / E2E pass · UI contract freeze | Pending ⏳ |
-
-> Note: This phase table follows `docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md` and is updated as implementation progresses.
-
----
-
-## Tech Stack
-
-| Layer | Technology |
-| ----- | ---------- |
-| Frontend | React 19, Vite, TypeScript (strict) |
-| Backend | Node.js, Express 5, tsx |
-| Database | PostgreSQL (primary) · SQLite (planned) |
-| Auth | JWT, TOTP 2FA, Argon2id |
-| Monorepo | pnpm workspaces |
-| Testing | Vitest |
-| UI Components | `@fieldstack/controls` (internal), Storybook |
-| Styling | CSS custom properties (design token system) |
-
----
-
-## Getting Started
-
-> **Production deployment guide will be published when the Setup install wizard (Phase 1.95) is complete.**<br>
-> Until then, you can run the project locally in development mode.
-
-### Local Development
-
-```bash
-git clone https://github.com/fieldstack-project/fieldstack.git
-cd fieldstack
-pnpm install
-
-# Start PostgreSQL (Docker required)
-docker-compose up -d
-
-# Run dev server (web + api in parallel)
-pnpm dev:bypass       # skip install wizard
-# → Web:  http://localhost:5173
-# → API:  http://localhost:3000
-
-# Storybook (UI components)
-pnpm storybook        # http://localhost:6007
-```
-
-**Dev mock accounts**
-
-| Role | Email | Password |
-| ---- | ----- | -------- |
-| Admin | `admin@fieldstack.dev` | `Admin1234!` |
-| User | `user@fieldstack.dev` | `User1234!` |
-
----
-
-## Documentation
-
-📚 [Official Documentation](https://docs.fieldstack.dev)<br>
-🏪 [Marketplace](https://marketplace.fieldstack.dev)<br>
-💬 [Community Discord](https://discord.gg/5m4aHKmWgg)
-
----
-
-## License
-
-MIT License - see [LICENSE](LICENSE) for details
-
-**Copyright © 2026 Fieldstack Project Contributors**<br>
-**Developed and maintained by PSquare DIVISION**
+# Fieldstack
+
+> Personal modular productivity framework
+
+[![한국어](https://img.shields.io/badge/README-한국어-blue)](README_ko.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub Org](https://img.shields.io/badge/GitHub-fieldstack--project-181717?logo=github)](https://github.com/fieldstack-project)
+
+---
+
+## About
+
+Fieldstack is an open-source, self-hosted modular framework for personal productivity and finance management.
+
+**Developed and maintained by** [PSquare DIVISION](https://github.com/psquare-division)
+
+### Core Values
+- ✅ **Completely Free** - No feature restrictions
+- ✅ **Self-hosted** - Your data, your control
+- ✅ **Modular** - Install only what you need
+- ✅ **Open Source** - MIT License
+- ✅ **Community-driven** - Built together
+
+---
+
+## Development Status
+
+Current phase: **Phase 2.2 — Subscription module in progress**
+
+- Phase 1 · 1.5 · 1.9 · 1.95 — all complete
+- Phase 2 pre-work (ModuleRegistry, module management API, per-user activation) — complete
+- Phase 2.1 Ledger (backend + frontend, CSV import/export, budgets, receipt attachments) — complete
+- Phase 2.x core infrastructure (i18n, Event Bus, Core Scheduler, exchange rates) — mostly complete
+- Phase 2.2 Subscription — core features complete, remaining: Google Calendar, calendar view, timezone strategy
+- Target timeline: **2026–2027**
+
+### Phase Progress
+
+| Phase | Scope | Status | Progress |
+| ----- | ----- | ------ | -------- |
+| Phase 1 | Core foundation setup | Completed ✅ | 100% |
+| Phase 1.5 | Core Control Plane UI/UX | Completed ✅ | 100% |
+| Phase 1.9 | API server · DB · auth backend · shared links | Completed ✅ | 100% |
+| Phase 1.95 | Setup install wizard (mode switch · backend API · UI · reset) | Completed ✅ | 100% |
+| Phase 2 Pre | ModuleRegistry · module management API · per-user activation | Completed ✅ | 100% |
+| Phase 2.1 | Ledger module (backend + frontend) | Completed ✅ | 100% |
+| Phase 2.x | Core systems (i18n · Event Bus · Scheduler · exchange rates) | Mostly complete ⏳ | ~80% |
+| Phase 2.2 | Subscription module | In progress ⏳ | ~70% |
+| Phase 3 | Marketplace and website | Not started 🚧 | 0% |
+| Phase 4 | Deployment optimization | Not started 🚧 | 0% |
+| Phase 5 | Expansion and ecosystem | Not started 🚧 | 0% |
+| Phase 6 | Community growth (continuous) | Not started 🚧 | 0% |
+
+#### Phase 2.2 Subscription — Remaining
+
+| Item | Status |
+| ---- | ------ |
+| Core features (CRUD · price history · stats · notes · scheduler · Event Bus) | Done ✅ |
+| Cumulative stats with status history (pause/resume periods excluded) | Done ✅ |
+| Payment calendar view | Pending ⏳ |
+| Ledger auto-sync (`subscription:payment` event receiver) | Pending ⏳ |
+| Timezone strategy (display vs. billing calculation separation) | Pending ⏳ |
+| Google Calendar integration | Pending ⏳ |
+
+> Note: This table follows `docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md` and is updated as implementation progresses.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+| ----- | ---------- |
+| Frontend | React 19, Vite, TypeScript (strict) |
+| Backend | Node.js, Express 5, tsx |
+| Database | PostgreSQL (primary) · SQLite via `better-sqlite3` |
+| Auth | JWT, TOTP 2FA, Argon2id |
+| i18n | i18next · react-i18next (ko / en) |
+| Scheduler | node-cron (Core Scheduler with DB logging) |
+| Exchange rates | Frankfurter API (DB-cached) |
+| Monorepo | pnpm workspaces |
+| Testing | Vitest |
+| UI Components | `@fieldstack/controls` (internal), Storybook |
+| Styling | CSS custom properties (design token system) |
+| Tunneling | Cloudflare Tunnel (Quick / Named) |
+
+---
+
+## Getting Started
+
+> **Production deployment guide will be published when Phase 2 is complete.**<br>
+> Until then, you can run the project locally in development mode.
+
+### Local Development
+
+```bash
+git clone https://github.com/fieldstack-project/fieldstack.git
+cd fieldstack
+pnpm install
+
+# Start PostgreSQL (Docker required)
+docker-compose up -d
+
+# Run dev server (web + api in parallel)
+pnpm dev:bypass       # skip install wizard
+# → Web:  http://localhost:5173
+# → API:  http://localhost:3000
+
+# Storybook (UI components)
+pnpm storybook        # http://localhost:6007
+```
+
+**Dev mock accounts**
+
+| Role | Email | Password |
+| ---- | ----- | -------- |
+| Admin | `admin@fieldstack.dev` | `Admin1234!` |
+| User | `user@fieldstack.dev` | `User1234!` |
+
+---
+
+## Documentation
+
+📚 [Official Documentation](https://docs.fieldstack.dev)<br>
+🏪 [Marketplace](https://marketplace.fieldstack.dev)<br>
+💬 [Community Discord](https://discord.gg/5m4aHKmWgg)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details
+
+**Copyright © 2026 Fieldstack Project Contributors**<br>
+**Developed and maintained by PSquare DIVISION**
diff --git a/README_ko.md b/README_ko.md
@@ -25,39 +25,42 @@ Fieldstack은 개인 생산성과 재무 관리를 위한 오픈소스 기반의
 
 ## 개발 현황
 
-현재 단계: **개발 진행 중 (로드맵 Phase 1.5)**
+현재 단계: **Phase 2.2 — Subscription 모듈 진행 중**
 
-- ✅ 기획 및 문서화 단계 완료
-- ✅ 로드맵 Phase 1(Core 기반 구축) 완료
-- ✅ 로드맵 Phase 1.9(API 서버 · DB · 인증 백엔드 · 공유 링크) 완료
-- 🚧 로드맵 Phase 1.5(Core Control Plane UI/UX) 마무리 단계
-- 🎯 전체 목표 타임라인은 **2026-2027** 유지
+- Phase 1 · 1.5 · 1.9 · 1.95 — 전 항목 완료
+- Phase 2 사전 작업 (ModuleRegistry · 모듈 관리 API · 유저별 활성화) — 완료
+- Phase 2.1 Ledger (백엔드 + 프론트, CSV import/export, 예산, 영수증 첨부) — 완료
+- Phase 2.x 코어 인프라 (i18n · Event Bus · Core Scheduler · 환율 시스템) — 대부분 완료
+- Phase 2.2 Subscription — 핵심 기능 완료, 잔여: Google Calendar · 캘린더 뷰 · 시간대 전략
+- 전체 목표 타임라인: **2026–2027**
 
 ### Phase 진행 현황
 
 | 단계(Phase) | 범위(로드맵) | 상태 | 진행률 |
-| ----------- | ----------- | --- | ----- |
+| ----------- | ----------- | ---- | ----- |
 | Phase 1 | Core 기반 구축 | 완료 ✅ | 100% |
-| Phase 1.5 | Core Control Plane UI/UX | 진행 중 ⏳ | 90% |
+| Phase 1.5 | Core Control Plane UI/UX | 완료 ✅ | 100% |
 | Phase 1.9 | API 서버 · DB · 인증 백엔드 · 공유 링크 | 완료 ✅ | 100% |
-| Phase 1.95 | Setup 설치 마법사 (모드 전환 · 백엔드 API · UI) | 진행 중 ⏳ | 0% |
-| Phase 2 | 기본 모듈 개발(Ledger, Subscription) | 시작 전 🚧 | 0% |
+| Phase 1.95 | Setup 설치 마법사 (모드 전환 · 백엔드 API · UI · 초기화) | 완료 ✅ | 100% |
+| Phase 2 Pre | ModuleRegistry · 모듈 관리 API · 유저별 활성화 | 완료 ✅ | 100% |
+| Phase 2.1 | Ledger 모듈 (백엔드 + 프론트엔드) | 완료 ✅ | 100% |
+| Phase 2.x | 코어 시스템 보완 (i18n · Event Bus · Scheduler · 환율) | 대부분 완료 ⏳ | ~80% |
+| Phase 2.2 | Subscription 모듈 | 진행 중 ⏳ | ~70% |
 | Phase 3 | 마켓플레이스 및 웹사이트 | 시작 전 🚧 | 0% |
 | Phase 4 | 배포 최적화 | 시작 전 🚧 | 0% |
 | Phase 5 | 확장 및 생태계 | 시작 전 🚧 | 0% |
 | Phase 6 | 커뮤니티 성장(지속) | 시작 전 🚧 | 0% |
 
-#### Phase 1.5 스냅샷 (2026-04-15)
+#### Phase 2.2 Subscription — 잔여 항목
 
-| 서브 페이즈 | 범위 | 상태 |
-| ----------- | ---- | ---- |
-| 1.5.1 | Control UI 컴포넌트 (P0/P0.5 구현 완료, `ready: true`) | 완료 ✅ |
-| 1.5.2 | 설치 마법사 개발용 bypass (`dev:bypass`) | 완료 ✅ |
-| 1.5.3 | 로그인 UX (실패/잠금/세션 만료, 비밀번호 복구, mock 계정 시스템) | 완료 ✅ |
-| 1.5.4 | 메인 홈 (사이드바, 딥 링크, 모바일 Drawer, 온보딩 배너) | 완료 ✅ |
-| 1.5.5 | 관리자 대시보드 / 일반 설정 (PIN step-up, 감사 로그, dirty-state 저장) | 완료 ✅ |
-| 1.5.6 | UX 품질 기준 (반응형 브레이크포인트, QA 체크리스트, 접근성, 톤 가이드) | 완료 ✅ |
-| 게이트 | 접근성/반응형/E2E 통과 · UI 계약 동결 | 진행 중 ⏳ |
+| 항목 | 상태 |
+| ---- | ---- |
+| 핵심 기능 (CRUD · 가격 히스토리 · 통계 · 메모 · Scheduler · Event Bus) | 완료 ✅ |
+| 구독 상태 이력 기반 누적 통계 (해지 기간 제외 계산) | 완료 ✅ |
+| 결제일 캘린더 뷰 | 예정 ⏳ |
+| Ledger 자동 연동 (`subscription:payment` 이벤트 수신) | 예정 ⏳ |
+| 시간대 전략 (표시 시간대 / 결제 계산 시간대 분리) | 예정 ⏳ |
+| Google Calendar 연동 | 예정 ⏳ |
 
 > 참고: 본 Phase 표는 `docs/v2_FINANCIAL-LEDGER/roadmap/01-development-plan.md` 기준이며, 구현 진행에 따라 갱신됩니다.
 
@@ -69,18 +72,22 @@ Fieldstack은 개인 생산성과 재무 관리를 위한 오픈소스 기반의
 | ------ | ---- |
 | 프론트엔드 | React 19, Vite, TypeScript (strict) |
 | 백엔드 | Node.js, Express 5, tsx |
-| 데이터베이스 | PostgreSQL (1순위) · SQLite (예정) |
+| 데이터베이스 | PostgreSQL (1순위) · SQLite (`better-sqlite3`) |
 | 인증 | JWT, TOTP 2FA, Argon2id |
+| 국제화 | i18next · react-i18next (ko / en) |
+| 스케줄러 | node-cron (DB 로그 포함 Core Scheduler) |
+| 환율 | Frankfurter API (DB 캐시) |
 | 모노레포 | pnpm workspaces |
 | 테스트 | Vitest |
 | UI 컴포넌트 | `@fieldstack/controls` (내부 패키지), Storybook |
 | 스타일링 | CSS 커스텀 프로퍼티 (디자인 토큰 시스템) |
+| 터널링 | Cloudflare Tunnel (Quick / Named) |
 
 ---
 
 ## 시작하기
 
-> **프로덕션 배포 가이드는 Setup 설치 마법사(Phase 1.95) 완료 시점에 공개됩니다.**<br>
+> **프로덕션 배포 가이드는 Phase 2 완료 시점에 공개됩니다.**<br>
 > 그 전까지는 아래 방법으로 로컬 개발 환경에서 실행할 수 있습니다.
 
 ### 로컬 개발 환경
diff --git a/apps/api/src/tunnel/cloudflare-tunnel.ts b/apps/api/src/tunnel/cloudflare-tunnel.ts
@@ -109,6 +109,23 @@ class CloudflareTunnelManager {
       });
 
       const url = await new Promise<string>((resolve, reject) => {
+        // Named Tunnel은 url 이벤트를 발생시키지 않으므로 즉시 반환
+        if (cfg.mode === 'named') {
+          tunnelInstance.once('error', (err: Error) => {
+            log.error('tunnel', `tunnel error: ${err.message}`);
+            reject(err);
+          });
+          tunnelInstance.once('exit', (code: number | null) => {
+            reject(new Error(`cloudflared 프로세스가 예상치 못하게 종료되었습니다 (code: ${code}).`));
+          });
+          // 잠시 대기 후 프로세스가 살아있으면 성공으로 간주
+          setTimeout(() => {
+            log.success('tunnel', 'named tunnel active (URL is configured in Cloudflare dashboard)');
+            resolve('named');
+          }, 2_000);
+          return;
+        }
+
         const timeout = setTimeout(() => {
           reject(new Error('터널 URL을 가져오는 데 시간이 초과되었습니다 (60초).'));
         }, 60_000);
diff --git a/apps/web/src/views/AdminView.tsx b/apps/web/src/views/AdminView.tsx
