first commit

2026-05-18 11:25:51 +09:00
commit 4d70b1428a
197 changed files with 28388 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+*.tsbuildinfo
+
+.eslintcache
+
+# Cypress
+/cypress/videos/
+/cypress/screenshots/
+
+# Vitest
+__screenshots__/
+
+# Vite
+*.timestamp-*-*.mjs
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+.env.development
+.env.production
@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "semi": false,
+  "singleQuote": true
+}
@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "Vue.volar",
+    "vitest.explorer",
+    "oxc.oxc-vscode"
+  ]
+}
@@ -0,0 +1,26 @@
+FROM node:20-alpine AS build-stage
+WORKDIR /app
+
+# 호스트의 npm 11 이 작성한 package-lock.json 형식과 호환되도록 npm 을 11 로 업그레이드
+RUN npm install -g npm@11
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+
+ARG BUILD_MODE=production
+ARG VITE_API_BASE_URL
+ENV VITE_API_BASE_URL=$VITE_API_BASE_URL
+
+RUN npm run build-only -- --mode ${BUILD_MODE}
+
+FROM nginx:stable-alpine AS production-stage
+
+# 보안 헤더 포함된 nginx 설정 적용
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+COPY --from=build-stage /app/dist /usr/share/nginx/html
+
+# 비-root 실행은 nginx-unprivileged 이미지 도입 시 활성화 (현재는 80 포트 바인드 필요)
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
@@ -0,0 +1,48 @@
+# frontend
+
+This template should help get you started developing with Vue 3 in Vite.
+
+## Recommended IDE Setup
+
+[VS Code](https://code.visualstudio.com/) + [Vue (Official)](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
+
+## Recommended Browser Setup
+
+- Chromium-based browsers (Chrome, Edge, Brave, etc.):
+  - [Vue.js devtools](https://chromewebstore.google.com/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd)
+  - [Turn on Custom Object Formatter in Chrome DevTools](http://bit.ly/object-formatters)
+- Firefox:
+  - [Vue.js devtools](https://addons.mozilla.org/en-US/firefox/addon/vue-js-devtools/)
+  - [Turn on Custom Object Formatter in Firefox DevTools](https://fxdx.dev/firefox-devtools-custom-object-formatters/)
+
+## Type Support for `.vue` Imports in TS
+
+TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.
+
+## Customize configuration
+
+See [Vite Configuration Reference](https://vite.dev/config/).
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Type-Check, Compile and Minify for Production
+
+```sh
+npm run build
+```
+
+### Run Unit Tests with [Vitest](https://vitest.dev/)
+
+```sh
+npm run test:unit
+```
@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+// Vite 환경변수 타입 정의 — VITE_ prefix 만 클라이언트 번들에 포함됨
+interface ImportMetaEnv {
+  readonly VITE_API_BASE_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}
@@ -0,0 +1,17 @@
+import pluginVue from 'eslint-plugin-vue'
+import vueTsEslintConfig from '@vue/eslint-config-typescript'
+
+// Flat config — Vue 3 + TypeScript 표준 권장 룰
+export default [
+  ...pluginVue.configs['flat/recommended'],
+  ...vueTsEslintConfig(),
+  {
+    rules: {
+      // 컴포넌트 단어 수 강제 해제 (HomePage 등 단일 컴포넌트도 허용)
+      'vue/multi-word-component-names': 'off',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
+  },
+]
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="ko">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="프로젝트 베이스 템플릿" />
+    <title>Project Base</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
@@ -0,0 +1,48 @@
+server {
+    listen       80;
+    server_name  localhost;
+
+    # ----------------------------------------
+    # 보안 헤더
+    # ----------------------------------------
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;
+
+    # ----------------------------------------
+    # 압축 (Gzip)
+    # ----------------------------------------
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/javascript application/javascript application/json application/xml image/svg+xml;
+
+    # ----------------------------------------
+    # SPA 라우팅
+    # ----------------------------------------
+    location / {
+        root   /usr/share/nginx/html;
+        index  index.html index.htm;
+        try_files $uri $uri/ /index.html;
+
+        # 정적 자원 캐싱 (SPA 빌드 산출물은 해시 파일명이라 장기 캐싱 가능)
+        location ~* \.(?:js|css|woff2?|ttf|svg|png|jpg|jpeg|gif|ico)$ {
+            expires 30d;
+            add_header Cache-Control "public, immutable";
+        }
+    }
+
+    error_page   500 502 503 504  /50x.html;
+    location = /50x.html {
+        root   /usr/share/nginx/html;
+    }
+
+    # 숨김 파일 접근 차단
+    location ~ /\. {
+        deny all;
+        access_log off;
+        log_not_found off;
+    }
+}
@@ -0,0 +1,45 @@
+{
+  "name": "frontend",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "run-p type-check \"build-only {@}\" --",
+    "preview": "vite preview",
+    "test:unit": "vitest",
+    "build-only": "vite build",
+    "type-check": "vue-tsc --build",
+    "lint": "eslint . --fix",
+    "format": "oxfmt src/"
+  },
+  "dependencies": {
+    "axios": "^1.14.0",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.31",
+    "vue-router": "^4.4.5"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.4",
+    "@types/jsdom": "^28.0.1",
+    "@types/node": "^24.12.0",
+    "@vitejs/plugin-vue": "^6.0.5",
+    "@vitejs/plugin-vue-jsx": "^5.1.5",
+    "@vue/eslint-config-typescript": "^14.2.0",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.9.1",
+    "eslint": "^9.18.0",
+    "eslint-plugin-vue": "^9.32.0",
+    "jsdom": "^29.0.1",
+    "npm-run-all2": "^8.0.4",
+    "oxfmt": "^0.42.0",
+    "typescript": "~6.0.0",
+    "vite": "^8.0.3",
+    "vite-plugin-vue-devtools": "^8.1.1",
+    "vitest": "^4.1.2",
+    "vue-tsc": "^3.2.6"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}
@@ -0,0 +1,10 @@
+<script setup lang="ts">
+// 최상위 레이아웃 — 라우터 뷰만 마운트, 도메인 별 레이아웃은 라우트 단위로 분리
+import { RouterView } from 'vue-router'
+</script>
+
+<template>
+  <RouterView />
+</template>
+
+<style scoped></style>
@@ -0,0 +1,93 @@
+import axios, {
+  type AxiosInstance,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios'
+
+// 표준 응답 포맷 타입 (Global Response Wrapper) — 백엔드 TransformInterceptor와 동일 구조
+export interface StandardResponse<T = unknown> {
+  success: boolean
+  data?: T
+  error?: {
+    code: string
+    message: string
+  }
+}
+
+// 에러 코드 사전 — CLAUDE.md / 백엔드 HttpExceptionFilter 와 1:1 매핑
+const ErrorCodeLexicon: Record<string, string> = {
+  SYS_001: '일시적인 시스템 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.',
+  AUTH_001: '로그인이 필요한 서비스입니다. 로그인 후 이용해 주세요.',
+  AUTH_002: '안전을 위해 로그아웃 되었습니다. 다시 로그인해 주세요.',
+  AUTH_003: '해당 메뉴나 기능에 접근할 수 있는 권한이 없습니다.',
+  VAL_001: '입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)',
+  RES_001: '요청하신 정보나 페이지를 찾을 수 없습니다.',
+  BIZ_001: '요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요.',
+}
+
+// 사용자 노출용 알림 — Toast 라이브러리 도입 시 이 함수만 교체하면 됨
+const showErrorUI = (message: string) => {
+  // eslint-disable-next-line no-alert
+  window.alert(message)
+}
+
+// 중앙 Axios 인스턴스
+const api: AxiosInstance = axios.create({
+  baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
+  timeout: 10000,
+  // HttpOnly/Secure 쿠키 인증 시 자격 증명을 함께 전송
+  withCredentials: true,
+})
+
+// 요청 인터셉터 — CSRF, 추가 헤더 등 필요 시 확장
+api.interceptors.request.use(
+  (config: InternalAxiosRequestConfig) => config,
+  (error: unknown) => Promise.reject(error),
+)
+
+// 응답 인터셉터 — Global Response Wrapper 언래핑 + 에러코드 → 메시지 매핑
+api.interceptors.response.use(
+  (response: AxiosResponse<StandardResponse>) => {
+    const payload = response.data
+
+    if (payload && typeof payload.success === 'boolean') {
+      if (payload.success) {
+        // 성공 시 data 만 언래핑하여 반환
+        return payload.data as never
+      }
+      // HTTP 200 이지만 비즈니스 로직상 실패인 경우
+      const errCode = payload.error?.code || 'BIZ_001'
+      showErrorUI(ErrorCodeLexicon[errCode] || ErrorCodeLexicon.SYS_001)
+      return Promise.reject(payload.error)
+    }
+    return payload as never
+  },
+  (error) => {
+    let errCode = 'SYS_001'
+
+    if (error?.response) {
+      const status: number = error.response.status
+      const payload = error.response.data as StandardResponse | undefined
+
+      if (payload?.error?.code) {
+        errCode = payload.error.code
+      } else if (status === 401) errCode = 'AUTH_001'
+      else if (status === 403) errCode = 'AUTH_003'
+      else if (status === 400 || status === 422) errCode = 'VAL_001'
+      else if (status === 404) errCode = 'RES_001'
+    }
+
+    showErrorUI(ErrorCodeLexicon[errCode] || ErrorCodeLexicon.SYS_001)
+    return Promise.reject(error)
+  },
+)
+
+/**
+ * useApi — 컴포넌트에서 axios 인스턴스를 가져올 때 사용하는 composable
+ * 직접 import 대신 useApi() 사용을 권장 (테스트 시 모킹 용이)
+ */
+export function useApi() {
+  return api
+}
+
+export default api
@@ -0,0 +1,31 @@
+import { ref } from 'vue'
+import { useApi } from './useApi'
+
+// 도메인별 API Composable 샘플 — 실제 도메인이 추가되면 이 패턴을 복제
+export interface User {
+  id: number
+  email: string
+  name: string
+}
+
+export function useUser() {
+  const api = useApi()
+  const loading = ref<boolean>(false)
+  const error = ref<string | null>(null)
+
+  async function getUser(id: number): Promise<User | null> {
+    loading.value = true
+    error.value = null
+    try {
+      // 인터셉터에서 success/data 언래핑 후 데이터만 반환
+      return (await api.get<User>(`/users/${id}`)) as unknown as User
+    } catch (e) {
+      error.value = (e as Error)?.message ?? 'unknown error'
+      return null
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { loading, error, getUser }
+}
@@ -0,0 +1,12 @@
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+
+app.use(createPinia())
+app.use(router)
+
+app.mount('#app')
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+// 홈 페이지 — 템플릿 기본 진입점
+import { ref } from 'vue'
+
+const message = ref<string>('You did it!')
+</script>
+
+<template>
+  <main class="home">
+    <h1>{{ message }}</h1>
+    <p>
+      Visit
+      <a href="https://vuejs.org/" target="_blank" rel="noopener">vuejs.org</a>
+      to read the documentation
+    </p>
+  </main>
+</template>
+
+<style scoped>
+.home {
+  padding: 2rem;
+}
+</style>
@@ -0,0 +1,18 @@
+<script setup lang="ts">
+// 404 페이지 — 라우팅 매칭 실패 시 노출
+</script>
+
+<template>
+  <main class="not-found" role="alert">
+    <h1>404</h1>
+    <p>요청하신 정보나 페이지를 찾을 수 없습니다.</p>
+    <RouterLink to="/">홈으로 돌아가기</RouterLink>
+  </main>
+</template>
+
+<style scoped>
+.not-found {
+  padding: 2rem;
+  text-align: center;
+}
+</style>
@@ -0,0 +1,31 @@
+import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'
+
+// 코드 스플리팅 — 모든 페이지 컴포넌트는 lazy import 처리
+const routes: RouteRecordRaw[] = [
+  {
+    path: '/',
+    name: 'home',
+    component: () => import('@/pages/HomePage.vue'),
+    meta: { requiresAuth: false },
+  },
+  {
+    path: '/:pathMatch(.*)*',
+    name: 'not-found',
+    component: () => import('@/pages/NotFoundPage.vue'),
+  },
+]
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes,
+})
+
+// 네비게이션 가드 — 인증 분기 (스토어 도입 후 useAuthStore로 교체)
+router.beforeEach((to) => {
+  if (to.meta.requiresAuth) {
+    // TODO: useAuthStore().isLoggedIn 검사 후 '/login' 으로 리다이렉트
+  }
+  return true
+})
+
+export default router
@@ -0,0 +1,20 @@
+// 공통 포맷터 — 부수효과 없는 순수 함수만 작성
+
+/**
+ * 숫자를 한국 통화 표기 (예: 12345 → "12,345원")
+ */
+export function formatCurrency(value: number): string {
+  return `${value.toLocaleString('ko-KR')}원`
+}
+
+/**
+ * Date 또는 ISO 문자열을 'YYYY-MM-DD' 형식으로 변환
+ */
+export function formatDate(input: Date | string): string {
+  const date = typeof input === 'string' ? new Date(input) : input
+  if (Number.isNaN(date.getTime())) return ''
+  const yyyy = date.getFullYear()
+  const mm = String(date.getMonth() + 1).padStart(2, '0')
+  const dd = String(date.getDate()).padStart(2, '0')
+  return `${yyyy}-${mm}-${dd}`
+}
@@ -0,0 +1,19 @@
+import { computed, ref } from 'vue'
+import { defineStore } from 'pinia'
+import type { User } from '@/composables/useUser'
+
+// 사용자 도메인 Pinia 스토어 샘플 — 도메인 단위로 파일을 분리하여 관리
+export const useUserStore = defineStore('user', () => {
+  const user = ref<User | null>(null)
+  const isLoggedIn = computed<boolean>(() => user.value !== null)
+
+  function setUser(payload: User | null) {
+    user.value = payload
+  }
+
+  function clear() {
+    user.value = null
+  }
+
+  return { user, isLoggedIn, setUser, clear }
+})
@@ -0,0 +1,18 @@
+{
+  "extends": "@vue/tsconfig/tsconfig.dom.json",
+  "include": ["env.d.ts", "src/**/*", "src/**/*.vue"],
+  "exclude": ["src/**/__tests__/*"],
+  "compilerOptions": {
+    // Extra safety for array and object lookups, but may have false positives.
+    "noUncheckedIndexedAccess": true,
+
+    // Path mapping for cleaner imports.
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    // `vue-tsc --build` produces a .tsbuildinfo file for incremental type-checking.
+    // Specified here to keep it out of the root directory.
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo"
+  }
+}
@@ -0,0 +1,14 @@
+{
+  "files": [],
+  "references": [
+    {
+      "path": "./tsconfig.node.json"
+    },
+    {
+      "path": "./tsconfig.app.json"
+    },
+    {
+      "path": "./tsconfig.vitest.json"
+    }
+  ]
+}
@@ -0,0 +1,27 @@
+// TSConfig for modules that run in Node.js environment via either transpilation or type-stripping.
+{
+  "extends": "@tsconfig/node24/tsconfig.json",
+  "include": [
+    "vite.config.*",
+    "vitest.config.*",
+    "cypress.config.*",
+    "playwright.config.*",
+    "eslint.config.*"
+  ],
+  "compilerOptions": {
+    // Most tools use transpilation instead of Node.js's native type-stripping.
+    // Bundler mode provides a smoother developer experience.
+    "module": "preserve",
+    "moduleResolution": "bundler",
+
+    // Include Node.js types and avoid accidentally including other `@types/*` packages.
+    "types": ["node"],
+
+    // Disable emitting output during `vue-tsc --build`, which is used for type-checking only.
+    "noEmit": true,
+
+    // `vue-tsc --build` produces a .tsbuildinfo file for incremental type-checking.
+    // Specified here to keep it out of the root directory.
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo"
+  }
+}
@@ -0,0 +1,19 @@
+{
+  "extends": "./tsconfig.app.json",
+
+  // Override to include only test files and clear exclusions.
+  // Application code imported in tests is automatically included via module resolution.
+  "include": ["src/**/__tests__/*", "env.d.ts"],
+  "exclude": [],
+
+  "compilerOptions": {
+    // Vitest runs in a different environment than the application code.
+    // Adjust lib and types accordingly.
+    "lib": [],
+    "types": ["node", "jsdom"],
+
+    // `vue-tsc --build` produces a .tsbuildinfo file for incremental type-checking.
+    // Specified here to keep it out of the root directory.
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.vitest.tsbuildinfo"
+  }
+}
@@ -0,0 +1,28 @@
+import { fileURLToPath, URL } from 'node:url'
+
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+import vueDevTools from 'vite-plugin-vue-devtools'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [
+    vue(),
+    vueJsx(),
+    vueDevTools(),
+  ],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url))
+    },
+  },
+  server: {
+    // ngrok 등 외부 도메인 접근 허용 (DNS Rebinding 보호 비활성화)
+    allowedHosts: true,
+    // 도커/윈도우 환경 파일 핫 리로딩 강제 활성화
+    watch: {
+      usePolling: true,
+    }
+  }
+})
@@ -0,0 +1,14 @@
+import { fileURLToPath } from 'node:url'
+import { mergeConfig, defineConfig, configDefaults } from 'vitest/config'
+import viteConfig from './vite.config'
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      environment: 'jsdom',
+      exclude: [...configDefaults.exclude, 'e2e/**'],
+      root: fileURLToPath(new URL('./', import.meta.url)),
+    },
+  }),
+)