프로젝트 'NHCX' 종합 실행 계획서 (Project 'NHCX' Master Plan) - corollazer0/nhcx2025 GitHub Wiki

프로젝트 'NHCX' 종합 실행 계획서 (Project 'NHCX' Master Plan)

문서 버전: 1.0 작성일: 2025년 7월 17일

이 문서는 Figma와 Vue.js 기반의 컴포넌트 주도 개발(CDD) 도입을 통해 개발 효율성, 품질, 비즈니스 연속성을 증명하기 위한 '피닉스(NHCX)' 프로젝트의 종합 실행 계획을 담고 있습니다.

목차

  1. PRD (Product Requirements Document)
  2. TRD (Technical Requirements Document)
  3. GitHub Issue Task 목록
  4. 개선 제안

Part 1: PRD (Product Requirements Document)

1.1. 제품명

NHCX Design System & Showcase MVP (기존의 개발 방식(JSP)에서 벗어나 새롭게 태어나는 개발 문화의 부활을 상징)

1.2. 프로젝트 목표 (The "Why")

본 프로젝트는 Figma와 Vue.js 기반의 컴포넌트 주도 개발(CDD) 방식이 기존 개발 프로세스 대비 얼마나 효율적이고 우수한 결과물을 만들어내는지 증명하는 것을 목표로 한다. 이를 통해 다음의 가치를 입증하고, 디자인 시스템 전담 팀 신설의 필요성을 설파한다.

  • 효율성 증명: 재사용 가능한 컴포넌트를 통해 개발 속도를 단축하고 중복 작업을 제거한다.
  • 품질 및 일관성 확보: Figma로 설계된 UX/UI를 코드 레벨에서 1:1로 구현하여, 모든 제품에서 일관된 사용자 경험과 브랜드 정체성을 유지한다.
  • 비즈니스 연속성: 신규 인력도 빠르게 적응할 수 있는 표준화된 개발 환경을 제공하고, 신속한 프로토타이핑과 MVP 개발을 통해 시장 변화에 민첩하게 대응한다.
  • 문화 혁신: 개발자와 디자이너 간의 협업을 강화하고, JSP 기반의 레거시 시스템에서 벗어나 현대적인 프론트엔드 개발 문화로의 전환을 주도한다.

1.3. 주요 기능 및 범위 (The "What")

  • Core-UI Component Library (Vue.js 3 + TypeScript)
    • Figma 디자인 시스템의 Foundation(Color, Typography 등)과 완벽하게 동기화
    • 총 7개 그룹, 32종의 UI 컴포넌트 개발
    • 각 컴포넌트에 대한 시각적 테스트 및 문서화를 위한 Storybook 제공
    • 컴포넌트 안정성 보장을 위한 Vitest 단위 테스트 코드
  • Showcase MVP Application
    • 개발된 Core-UI 컴포넌트만을 사용하여 제작된 샘플 웹 애플리케이션
    • Figma로 설계된 UserFlow 및 화면 디자인 기반으로 개발
    • CDD의 개발 효율성과 결과물의 품질을 시각적으로 증명
  • Cross-Platform PoC (Android)
    • 디자인 시스템의 스타일 자원을 Kotlin 코드로 변환
    • 핵심 UI 컴포넌트 1~2종을 Jetpack Compose로 개발하여, 디자인 시스템이 웹을 넘어 네이티브 앱까지 확장 가능함을 증명

1.4. 성공 지표

  • 정량적 지표: MVP 개발 시, 유사 규모의 기존 프로젝트 대비 개발 공수 30% 이상 단축, 컴포넌트 재사용률 80% 이상, Storybook에 등록된 컴포넌트별 테스트 커버리지 70% 이상
  • 정성적 지표: 프로젝트 결과물 리뷰 시, 경영진 및 유관 부서의 긍정적 피드백, 참여 개발자 및 디자이너의 CDD 프로세스 만족도 조사

Part 2: TRD (Technical Requirements Document)

2.1. 개발 환경 및 도구

  • IDE: Visual Studio Code (Cursor 등 AI Agent 활용)
  • Package Manager: pnpm
  • Framework: Vue.js 3 (Composition API)
  • Language: TypeScript
  • Styling:
    • CSS Preprocessor: Sass(SCSS)
    • Token Management: Style Dictionary (Figma Tokens -> Multi-platform)
    • CSS Reset: Modern-normalize 또는 A modern CSS reset
  • Bundler / Dev Server: Vite
  • Linting & Formatting: ESLint + Prettier
  • Design Tool: Figma

2.2. 아키텍처

  • UI 라이브러리: 독립적인 NPM 패키지로 관리 (추후 Monorepo 전환 고려)
  • CSS 계층 구조: Reset CSS -> Base CSS (Tokens) -> Component-specific CSS
  • 디렉토리 구조 (예시: Button 컴포넌트):
src/components/Button/
├── Button.vue         # 템플릿, 로직, 스타일 모두 포함
├── Button.types.ts    # 타입 정의
├── Button.stories.ts  # Storybook 스토리
├── Button.spec.ts     # Vitest 테스트 코드
└── README.md          # 컴포넌트 가이드 문서
  • SingleFileCompoent(SFC) 구조 (예시: 간단한 Button 컴포넌트):
<!-- Button.vue -->
<template>
  <button class="button">
    <slot></slot>
  </button>
</template>

<script setup lang="ts">
// ... 스크립트 로직
</script>

<style scoped>
/* Style 영역 */
.button {
  background-color: var(--color-primary);
  color: white;
  padding: 10px 15px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  transition: background-color 0.2s;
}

.button:hover {
  background-color: var(--color-primary-dark);
}
</style>

2.3. 테스트 및 품질 보증

  • Component Testing: Vitest + Vue Testing Library
  • Visual Regression Testing: Storybook을 통한 시각적 테스트 및 수동 검증
  • CI/CD: GitHub Actions를 통해 Pull Request 시 자동 Lint, Test, Build 실행

2.4. 문서화 및 협업

  • Component Documentation: Storybook
  • Project Policy & Guide: GitHub Wiki
  • Task Management: GitHub Issues
  • Version Control: Git (Git-flow 또는 유사한 브랜칭 전략 사용)

Part 3: GitHub Issue Task 목록

  • 각 TASK는 Github Issue의 이름으로 등록한다.
  • Issue에 등록된 Task명을 기반으로 Branch를 feature/[Issue명]으로 생성하고 작업 후 MR한다.

Phase 1: 프로젝트 환경 설정 및 기반 구축 (Epic: Project-Setup)

  • SETUP-001-select-figma-project: PoC에 사용할 오픈소스 Figma 디자인 시스템 선정 및 분석 ✅
  • SETUP-002-initialize-vue-project: Vite 기반 Vue 3 + TypeScript 프로젝트 생성 ✅
  • SETUP-003-configure-linting-rules: Prettier, ESLint 규칙 확정 및 설정 ✅
  • SETUP-004-install-testing-tools: Vitest, Vue Testing Library 설정
  • SETUP-005-install-storybook: Storybook 초기 설정 및 연동 ✅
  • SETUP-006-integrate-style-dictionary: Figma Tokens 연동 및 Style Dictionary 빌드 스크립트 작성 ✅
  • SETUP-007-apply-base-css: CSS Reset 적용 및 생성된 base.css 전역 주입 ✅
  • SETUP-008-define-directory-structure: 컴포넌트 디렉토리 구조 확정 및 README 작성

Phase 2: Core-UI 컴포넌트 개발 (Epic: Component-Development)

  • TASK-CMP-NAV-009-main-menu: Navigation - Main Menu 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-NAV-010-breadcrumb: Navigation - BreadCrumb 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-NAV-011-side-navigation: Navigation - Side Navigation 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-NAV-012-pagination: Navigation - Pagination 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-NAV-013-tab-bars: Navigation - Tab Bars 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-014-structured-list: Layout - Structured list 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-015-critical-alerts: Layout - Critical alerts 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-016-calendar: Layout - Calendar 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-017-disclosure: Layout - Disclosure 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-018-modal: Layout - Modal 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-019-badge: Layout - Badge 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-020-accordion: Layout - Accordion 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-021-carousel: Layout - Carousel 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-022-tab: Layout - Tab 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-023-table: Layout - Table 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-024-splash-screen: Layout - SplashScreen 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-LAYOUT-025-textlist: Layout - Textlist 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-ACTION-026-button: Action - Button 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-ACTION-027-link: Action - link 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-SELECT-028-radio-button: Select - Radio button 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-SELECT-029-checkbox: Select - Checkbox 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-SELECT-030-select-combobox: Select - Select(Combobox) 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-SELECT-031-tag: Select - Tag 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-SELECT-032-toggle-switch: Select - ToggleSwitch 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-FEEDBACK-033-step-indicator: Feedback - Step indicator 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-FEEDBACK-034-spinner: Feedback - Spinner 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-HELP-035-tooltip: Help - Tooltip 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-HELP-036-coach-mark: Help - Coach Mark 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-HELP-037-contextual-help: Help - Contextual help 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-INPUT-038-date-input: Input - Date Input 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-INPUT-039-textarea: Input - TextArea 컴포넌트 개발 (구현, 테스트, 문서화)
  • TASK-CMP-INPUT-040-text-input: Input - Text Input 컴포넌트 개발 (구현, 테스트, 문서화)

Phase 3: MVP 개발 (Epic: MVP-Development)

  • TASK-MVP-041-define-user-flow: MVP UserFlow 및 와이어프레임 Figma 작성
  • TASK-MVP-042-design-mvp-screens: Figma 기반 MVP 화면 상세 디자인
  • TASK-MVP-043-bootstrap-mvp-application: MVP 개발을 위한 신규 Vue 프로젝트 생성 및 UI 라이브러리 연동
  • TASK-MVP-044-implement-mvp-layout: 공통 레이아웃 및 라우팅 구현
  • TASK-MVP-045-develop-feature-A: MVP 핵심 기능 A 개발 (컴포넌트 조립)
  • TASK-MVP-046-develop-feature-B: MVP 핵심 기능 B 개발 (컴포넌트 조립)
  • TASK-MVP-047-write-project-wiki: MVP 개발 정책 GitHub Wiki 문서화

Phase 4: PoC 증명 및 발표 (Epic: Proof-of-Concept)

  • TASK-POC-048-create-presentation-story: PoC 증명을 위한 발표 스토리라인 구성
  • TASK-POC-049-design-presentation-deck: Figma 또는 PPT를 이용한 발표 자료 제작
  • TASK-POC-050-integrate-tokens-android: Style Dictionary 토큰 Android 프로젝트(Kotlin) 연동
  • TASK-POC-051-develop-compose-component: Jetpack Compose로 Button 컴포넌트 재구현
  • TASK-POC-052-develop-compose-screen: Compose 컴포넌트로 1개 화면 개발

Part 4: 개선 사항

제시해주신 계획은 이미 훌륭하지만, 장기적인 확장성과 자동화를 위해 다음 사항들을 고려해볼 수 있습니다.

  1. Monorepo 도입:

    • 내용: Turborepo나 Nx 같은 도구를 사용하여 Vue.js UI 라이브러리, MVP 앱, Android 관련 코드, 공유 로직(ts-utils) 등을 하나의 Git 저장소에서 관리합니다.
    • 장점: 일관성, 효율성, 가시성 증대.

  2. 디자인 토큰 배포 자동화 (CI/CD):

    • 내용: Style Dictionary 빌드 프로세스를 GitHub Actions 같은 CI/CD 파이프라인에 통합합니다. Figma Tokens에 변경이 생기면 자동으로 base.css(웹용)와 Theme.kt(안드로이드용) 파일을 생성하고, 각 플랫폼이 참조하는 내부 패키지(NPM, Maven 등)로 배포합니다.
    • 장점: 수동 작업을 제거하여 휴먼 에러를 방지하고, 디자이너의 변경 사항이 코드에 즉시 반영되어 싱크를 유지합니다.

  3. AI Agent 프롬프트 템플릿 구체화:

    • 정형화된 프롬프트를 통해 컴포넌트 보일러플레이트 코드 생성의 효율과 일관성을 극대화합니다.
⚠️ **GitHub.com Fallback** ⚠️