Initial commit

This commit is contained in:
2026-10-28 15:30:05 +09:00
commit 696e34f403
269 changed files with 33654 additions and 0 deletions
+10
View File
@@ -0,0 +1,10 @@
<script setup lang="ts">
// 최상위 레이아웃 — 라우터 뷰만 마운트, 도메인 별 레이아웃은 라우트 단위로 분리
import { RouterView } from 'vue-router'
</script>
<template>
<RouterView />
</template>
<style scoped></style>
+76
View File
@@ -0,0 +1,76 @@
<script setup lang="ts">
// 공통 버튼 컴포넌트 — 모든 재사용 컴포넌트의 기준 패턴
// (타입 지정 Props/Emits, scoped 스타일, rem 단위, 기본 접근성 속성)
// 사용 예: <BaseButton label="저장" variant="primary" @click="onSave" />
// Props 정의
interface Props {
// 버튼 라벨 (접근성 aria-label 로도 사용)
label: string
// 시각 변형
variant?: 'primary' | 'secondary'
// 비활성화 여부
disabled?: boolean
// 네이티브 button type
type?: 'button' | 'submit'
}
const props = withDefaults(defineProps<Props>(), {
variant: 'primary',
disabled: false,
type: 'button',
})
// Emits 정의
interface Emits {
// 클릭 이벤트
(e: 'click', event: MouseEvent): void
}
const emit = defineEmits<Emits>()
// 클릭 핸들러 — 비활성화 상태에서는 이벤트를 전파하지 않음
function handleClick(event: MouseEvent) {
if (props.disabled) return
emit('click', event)
}
</script>
<template>
<button
:type="type"
:class="['base-button', `base-button--${variant}`]"
:disabled="disabled"
:aria-label="label"
:aria-disabled="disabled"
@click="handleClick"
>
{{ label }}
</button>
</template>
<style scoped>
/* 모든 치수는 rem 기준 (16px = 1rem) */
.base-button {
padding: 0.5rem 1rem;
font-size: 1rem;
border: none;
border-radius: 0.375rem;
cursor: pointer;
}
.base-button:disabled {
opacity: 0.5;
cursor: not-allowed;
}
.base-button--primary {
background-color: #4f46e5;
color: #ffffff;
}
.base-button--secondary {
background-color: #e5e7eb;
color: #111827;
}
</style>
+50
View File
@@ -0,0 +1,50 @@
import { describe, expect, it } from 'vitest'
import {
ERROR_CODE_MESSAGES,
FALLBACK_ERROR_CODE,
} from '@/shared/constants/error-codes.generated'
import { getErrorMessage } from './useApi'
describe('에러 코드 사전', () => {
it('등록된 코드는 해당 한국어 메시지를 반환한다', () => {
expect(getErrorMessage('AUTH_001')).toBe(
'로그인이 필요한 서비스입니다. 로그인 후 이용해 주세요.',
)
})
it('미등록 코드는 SYS_001 폴백 메시지를 반환한다', () => {
expect(getErrorMessage('UNKNOWN_999')).toBe(
ERROR_CODE_MESSAGES[FALLBACK_ERROR_CODE],
)
})
it('클라이언트 로직이 참조하는 코드가 사전에 존재한다', () => {
// useApi 의 상태코드 역매핑과 세션 만료 승격이 이 코드들을 직접 사용한다.
// 사전에서 빠지면 폴백 메시지가 나가므로 반드시 존재해야 한다.
//
// ⚠️ 전체 목록을 비교하지 않는 이유: 세 플랫폼의 사전은 backend 레지스트리에서
// 생성되므로 목록 일치는 구조적으로 보장되고, CI 가 드리프트를 검사한다.
// 여기서 전수 비교를 하면 도메인 코드를 추가할 때마다 무의미하게 깨진다.
const usedByClient = [
'SYS_001',
'REQ_001',
'AUTH_001',
'AUTH_002',
'AUTH_003',
'VAL_001',
'RES_001',
'BIZ_001',
]
for (const code of usedByClient) {
expect(ERROR_CODE_MESSAGES).toHaveProperty(code)
}
})
it('모든 코드는 DOMAIN_NNN 네이밍 규약을 따른다', () => {
for (const code of Object.keys(ERROR_CODE_MESSAGES)) {
expect(code).toMatch(/^[A-Z]+_\d{3}$/)
}
})
})
+148
View File
@@ -0,0 +1,148 @@
import axios, {
type AxiosInstance,
type AxiosResponse,
type InternalAxiosRequestConfig,
} from 'axios'
import {
ERROR_CODE_MESSAGES,
FALLBACK_ERROR_CODE,
type ErrorCode,
} from '@/shared/constants/error-codes.generated'
import { useAuthStore } from '@/stores/auth.store'
// 표준 응답 포맷 타입 (Global Response Wrapper) — 백엔드 TransformInterceptor 와 동일 구조
export interface StandardResponse<T = unknown> {
success: boolean
data?: T
error?: {
code: string
message: string
/** 서버 요청 추적 ID — 문의 대응 시 로그 검색 키 */
traceId?: string
}
}
/** 인터셉터가 reject 할 때 넘기는 정규화된 에러 — 호출부는 code 로 분기한다. */
export interface ApiError {
code: ErrorCode
message: string
traceId?: string
status?: number
}
const API_TIMEOUT_MS = 10000
/** 동일 코드의 알림이 짧은 시간에 중복 노출되는 것을 막는 간격 */
const DUPLICATE_ALERT_WINDOW_MS = 3000
function isErrorCode(code: string): code is ErrorCode {
return code in ERROR_CODE_MESSAGES
}
/** 에러 코드 → 사용자 노출 문구. 사용자 문구는 이 사전에만 존재한다. */
export function getErrorMessage(code: string): string {
return isErrorCode(code)
? ERROR_CODE_MESSAGES[code]
: ERROR_CODE_MESSAGES[FALLBACK_ERROR_CODE]
}
// 사용자 노출용 알림 — Toast 라이브러리 도입 시 이 함수 하나만 교체한다.
let lastAlert: { code: string; at: number } | null = null
const showErrorUI = (code: ErrorCode, message: string) => {
const now = Date.now()
if (lastAlert && lastAlert.code === code && now - lastAlert.at < DUPLICATE_ALERT_WINDOW_MS) {
return
}
lastAlert = { code, at: now }
window.alert(message)
}
// 중앙 Axios 인스턴스
const api: AxiosInstance = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
timeout: API_TIMEOUT_MS,
// HttpOnly/Secure 쿠키 인증 시 자격 증명을 함께 전송
withCredentials: true,
})
// 요청 인터셉터 — CSRF, 추가 헤더 등 필요 시 확장
api.interceptors.request.use(
(config: InternalAxiosRequestConfig) => config,
(error: unknown) => Promise.reject(error),
)
/** HTTP 상태 코드 → 에러 코드 폴백 (서버가 표준 에러 본문을 주지 못한 경우) */
function resolveCodeByStatus(status: number): ErrorCode {
if (status === 401) return 'AUTH_001'
if (status === 403) return 'AUTH_003'
if (status === 400 || status === 422) return 'VAL_001'
if (status === 404) return 'RES_001'
if (status === 429) return 'REQ_001'
return FALLBACK_ERROR_CODE
}
/**
* 인증 세션이 있는 상태에서 401 을 받으면 "세션 만료"로 간주한다.
* AUTH_002 는 서버가 내려주지 않는 클라이언트 전용 코드다.
*/
function toAuthCode(code: ErrorCode): ErrorCode {
if (code !== 'AUTH_001') return code
const authStore = useAuthStore()
if (authStore.isLoggedIn) {
authStore.clearAuth()
return 'AUTH_002'
}
return 'AUTH_001'
}
/** 에러 코드를 확정하고 알림까지 처리한 뒤 정규화된 에러를 만든다. */
function handle(rawCode: string, traceId?: string, status?: number): ApiError {
const code = toAuthCode(isErrorCode(rawCode) ? rawCode : FALLBACK_ERROR_CODE)
const message = getErrorMessage(code)
showErrorUI(code, message)
return { code, message, traceId, status }
}
// 응답 인터셉터 — 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 이지만 비즈니스 로직상 실패인 경우 (백엔드는 4xx 로 내리지만 방어적으로 처리)
return Promise.reject(
handle(payload.error?.code ?? 'BIZ_001', payload.error?.traceId, response.status),
)
}
return payload as never
},
(error) => {
if (!error?.response) {
// 네트워크 단절·타임아웃 — 서버 응답 자체가 없는 경우
return Promise.reject(handle(FALLBACK_ERROR_CODE))
}
const status: number = error.response.status
const payload = error.response.data as StandardResponse | undefined
const code = payload?.error?.code ?? resolveCodeByStatus(status)
return Promise.reject(handle(code, payload?.error?.traceId, status))
},
)
/**
* useApi — 컴포넌트에서 axios 인스턴스를 가져올 때 사용하는 composable
* 직접 import 대신 useApi() 사용을 권장 (테스트 시 모킹 용이)
*/
export function useApi() {
return api
}
export default api
+43
View File
@@ -0,0 +1,43 @@
import { ref } from 'vue'
import { useApi } from './useApi'
import { useAuthStore } from '@/stores/auth.store'
// 인증 도메인 API Composable 샘플 — 로그인/로그아웃 흐름의 시작점
// 실제 인증 엔드포인트가 추가되면 이 패턴을 그대로 사용/확장한다.
export interface LoginPayload {
email: string
password: string
}
export function useAuth() {
const api = useApi()
const authStore = useAuthStore()
const loading = ref<boolean>(false)
async function login(payload: LoginPayload): Promise<boolean> {
loading.value = true
try {
// 서버는 인증 성공 시 HttpOnly 쿠키로 토큰을 내려준다 (응답 바디에 토큰 없음)
await api.post('/auth/login', payload)
authStore.markAuthenticated()
return true
} catch {
// 에러 메시지/알림은 useApi 인터셉터에서 전역 처리됨
return false
} finally {
loading.value = false
}
}
async function logout(): Promise<void> {
loading.value = true
try {
await api.post('/auth/logout')
} finally {
authStore.clearAuth()
loading.value = false
}
}
return { loading, login, logout }
}
+31
View File
@@ -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 }
}
+12
View File
@@ -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')
+27
View File
@@ -0,0 +1,27 @@
<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>
+23
View File
@@ -0,0 +1,23 @@
<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>
+35
View File
@@ -0,0 +1,35 @@
import { createRouter, createWebHistory, type RouteRecordRaw } from 'vue-router'
import { useAuthStore } from '@/stores/auth.store'
// 코드 스플리팅 — 모든 페이지 컴포넌트는 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,
})
// 네비게이션 가드 — 보호 라우트(requiresAuth) 접근 시 인증 여부 검사
router.beforeEach((to) => {
const authStore = useAuthStore()
if (to.meta.requiresAuth && !authStore.isLoggedIn) {
// 미인증 시 홈으로 리다이렉트
// (실제 로그인 페이지 추가 시 { name: 'login' } 으로 변경)
return { name: 'home' }
}
return true
})
export default router
@@ -0,0 +1,19 @@
// backend/src/common/errors/error-codes.ts 에서 자동 생성된 파일입니다. 직접 수정하지 마세요.
export const ERROR_CODE_MESSAGES = {
SYS_001: '일시적인 시스템 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.',
REQ_001: '요청이 너무 많습니다. 잠시 후 다시 시도해 주세요.',
AUTH_001: '로그인이 필요한 서비스입니다. 로그인 후 이용해 주세요.',
AUTH_002: '안전을 위해 로그아웃 되었습니다. 다시 로그인해 주세요.',
AUTH_003: '해당 메뉴나 기능에 접근할 수 있는 권한이 없습니다.',
VAL_001: '입력하신 정보를 다시 확인해 주세요. (필수값 누락 또는 형식 오류)',
RES_001: '요청하신 정보나 페이지를 찾을 수 없습니다.',
BIZ_001: '요청하신 작업을 완료하지 못했습니다. 다시 시도해 주세요.',
FILE_001: '허용되지 않는 파일 형식입니다. 파일을 확인해 주세요.',
FILE_002: '파일 크기가 허용 범위를 초과했습니다.',
} as const
export type ErrorCode = keyof typeof ERROR_CODE_MESSAGES
/** 매핑 실패 시 사용하는 폴백 코드 */
export const FALLBACK_ERROR_CODE: ErrorCode = 'SYS_001'
+25
View File
@@ -0,0 +1,25 @@
// 목록 응답 공유 계약 — 백엔드 PaginatedResult 와 동일 구조
// (백엔드: backend/src/common/dto/pagination.dto.ts)
export interface PageInfo {
/** 다음 페이지 존재 여부 */
hasNext: boolean
/** 다음 요청에 넘길 커서. 마지막 페이지면 null */
nextCursor: string | null
/** 전체 개수. 계산 비용이 큰 경우 null 일 수 있다. */
total: number | null
}
export interface PaginatedResult<T> {
items: T[]
pageInfo: PageInfo
}
/** 커서 기반 목록 조회 쿼리 파라미터 */
export interface CursorPaginationQuery {
cursor?: string
limit?: number
}
/** 목록 API 기본 조회 개수 — 백엔드 PAGINATION_DEFAULT_LIMIT 와 동일 */
export const DEFAULT_PAGE_SIZE = 20
+20
View File
@@ -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}`
}
+24
View File
@@ -0,0 +1,24 @@
import { computed, ref } from 'vue'
import { defineStore } from 'pinia'
// 인증 세션 상태 스토어
// 웹은 JWT 를 HttpOnly·Secure 쿠키로 보관하므로(보안 규칙), JS 에서 토큰을 직접
// 저장/조회하지 않는다. 여기서는 "현재 인증된 세션인지" 여부만 관리한다.
// (사용자 프로필 데이터는 user.store.ts 에서 별도 관리)
export const useAuthStore = defineStore('auth', () => {
// 로그인 성공 또는 세션 확인 API 응답으로 갱신되는 인증 여부
const authenticated = ref<boolean>(false)
const isLoggedIn = computed<boolean>(() => authenticated.value)
// 로그인 성공 시 호출 (실제 로그인 API 연동 시 useAuth 에서 사용)
function markAuthenticated() {
authenticated.value = true
}
// 로그아웃/세션 만료 시 호출
function clearAuth() {
authenticated.value = false
}
return { isLoggedIn, markAuthenticated, clearAuth }
})
+19
View File
@@ -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 }
})