create-m2m-bo-template-vue 1.0.2 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m2m-bo-template-vue",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Scaffolding CLI for the M2M back-office vue template.",
   "type": "module",
   "bin": {

package/template/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md — bo-template-vue / template
+
+이 문서는 `/template` 디렉토리에서 작업할 때 항상 참고해야 하는 규칙입니다.
+
+## 프로젝트 목적
+
+- 참고 디렉토리 `C:\@project\bo-template-react\template` (React + TypeScript + react-router-dom + `m2m-uiux-react`)를
+  본 디렉토리 `C:\@project\bo-template-vue\template` (Vue 3 + TypeScript + vue-router + `m2m-uiux-vue`)로 포팅합니다.
+- React 참고 디렉토리에 존재하는 **모든 페이지, 컴포넌트, 라우트, 기능**을 Vue 버전에도 빠짐없이 동일하게 구현합니다.
+- `m2m-uiux-react`와 `m2m-uiux-vue`는 동일한 제작사(m2m)가 배포하는 컴포넌트 라이브러리로, props·상수명·디자인 토큰(`--m2m-*` CSS 변수)이
+  100% 동일합니다. 즉 시각적 결과물은 프레임워크와 무관하게 동일해야 합니다.
+
+## 절대 규칙
+
+1. **React 기반의 참고 디렉토리(`bo-template-react/template`)를 원본으로 삼아 Vue 형태로 새로 작성한다.**
+   - React 소스를 그대로 두고, Vue 관용 문법(SFC `<script setup lang="ts">`, `<template>`, Composition API,
+     `ref`/`reactive`/`computed`/`watch`, `vue-router`)으로 다시 작성합니다.
+   - 로직/데이터/문구/도메인 규칙은 그대로 유지하고, JSX → Vue 템플릿, React hooks → Vue Composition API로만 변환합니다.
+2. **`/template` 상위 폴더 영역은 절대 건드리지 않는다.**
+   - `/template` 상위(예: 리포지토리 루트의 배포 설정, CI/CD, `.gitlab-ci.yml`, 루트 `package.json` 등)는 배포 및 테스트 영역이므로 수정 금지.
+   - 모든 작업은 `/template` 디렉토리 내부에서만 수행합니다.
+3. **React와 Vue는 언어(프레임워크) 차원에서는 다르지만, 화면에 보이는 결과(레이아웃/스타일/인터랙션)는 항상 동일해야 한다.**
+   - CSS Modules(`*.module.css`)는 Vue에서도 동일 파일명·동일 클래스 구조로 그대로 포팅합니다 (`<style module>` 또는 CSS Modules 그대로 사용).
+   - 페이지 타이틀, 문구(한국어 텍스트), 표/컬럼 구성, 필터, 뱃지, 상태값 등은 1:1로 동일해야 합니다.
+   - 아이콘은 `lucide-react` → `lucide-vue-next`로 대응합니다 (아이콘 이름 동일).
+   - UI 컴포넌트는 `m2m-uiux-react/<Component>` → `m2m-uiux-vue/<Component>` 서브패스 import로 대응합니다.
+
+## ⚠️ 컴포넌트 사용 규칙 (매우 중요 — 반드시 준수)
+
+React 참고 코드는 `m2m-uiux-react`를 직접 각 페이지에서 import해서 사용합니다. Vue 쪽도 동일하게 해야 합니다.
+
+1. **`m2m-uiux-vue`를 다시 감싼 래퍼 컴포넌트를 `components/common`에 새로 만들지 않는다.**
+   - 예: `Button`, `Input`, `Select`, `Checkbox`, `Radio`, `Switch`, `Textarea`, `Divider`, `Badge`, `Tooltip`, `Loading`, `ProgressBar`, `Tabs`, `Segmented`, `Accordion`(라이브러리 것 그대로 쓸 수 있는 경우), `Steps`, `DatePicker`, `TimePicker`, `Header` 등 **`m2m-uiux-vue`가 이미 제공하는 컴포넌트는 페이지(`.vue`)에서 `import { Button } from 'm2m-uiux-vue/Button'` 처럼 직접 import해서 템플릿에 바로 쓴다.** React 참고 코드가 `m2m-uiux-react/Button`을 직접 쓰듯이 그대로 대응시킨다.
+   - `components/common`에는 **`m2m-uiux-vue`에 존재하지 않는, 이 프로젝트 고유의 합성 컴포넌트**만 둔다 (예: 통계 카드 그리드, 커스텀 테이블 레이아웃, 상세 드로어의 공통 레이아웃, 엑셀 다운로드 버튼, 페이지 사이즈 셀렉트, 토스트 프로바이더/헬퍼 등 React 원본의 `CommonXxx.tsx` 중 실제로 라이브러리에 없는 로직/마크업을 담고 있는 것).
+2. **파일명/컴포넌트명에서 `Common` 접두사를 붙이지 않는다.**
+   - React 쪽 파일명이 `CommonCard.tsx`, `CommonControls.tsx` 등이었어도, Vue 쪽 개별 컴포넌트 파일/이름은 접두사 없이 의미 그대로 짓는다 (예: `StatCard.vue`, `StatGrid.vue`, `SplitPaneLayout.vue`, `ExcelDownloadButton.vue`, `PageSizeSelect.vue`, `ToastProvider.vue`, `ConfirmDialog.vue` 등). React 원본 파일 하나가 여러 컴포넌트를 export하던 것은 각각 의미에 맞는 이름의 개별 `.vue` 파일로 쪼갠다.
+3. **React 방식의 콜백 prop(`:value`, `:onClick`, `:onChange`, `:onFocus` 등)을 Vue 컴포넌트 API로 그대로 옮기지 않는다.**
+   - Vue스럽게(MVVM) 작성한다: 클릭은 `@click`, 포커스는 `@focus`, 값 바인딩은 `v-model`(또는 `v-model:xxx`), 상태는 `ref`/`reactive`/`computed`로 관리한다.
+   - 즉 "무엇이 보이고 어떻게 동작하는가(시각적 결과·기능)"는 React와 100% 동일해야 하지만, "어떻게 구현하는가(이벤트 바인딩 문법, prop 네이밍 컨벤션, 상태 관리 방식)"는 Vue 관용 방식을 따른다. React의 구현 로직/문법을 그대로 베끼지 않는다.
+4. 위 규칙은 이미 만들어진 `components/common/Common*.vue` 다수와 그것을 사용한 일부 페이지에도 소급 적용되어 현재 정리 중이다. 새로 작업하는 에이전트/세션은 반드시 이 규칙에 맞게 작성하고, 기존에 `Common` 접두사 래퍼나 `:onClick` 스타일 코드를 보면 이 규칙에 맞게 고친다.
+
+## 포팅 매핑 규칙
+
+| React | Vue |
+|---|---|
+| `react-router-dom` (`Routes`/`Route`/`useNavigate`/`useLocation`/`Link`) | `vue-router` (`createRouter`/`RouterView`/`useRouter`/`useRoute`/`RouterLink`) |
+| `useState` | `ref` / `reactive` |
+| `useEffect` | `watch` / `watchEffect` / `onMounted` / `onUnmounted` |
+| `useMemo` / `useCallback` | `computed` / 일반 함수 (Vue는 별도 메모이제이션이 대부분 불필요) |
+| custom hooks (`useXxx.ts`) | composables (`useXxx.ts`, 동일 파일명 유지, Composition API로 재작성) |
+| `.tsx` 컴포넌트 | `.vue` SFC (`<script setup lang="ts">`) |
+| `*.module.css` | 동일 파일명의 CSS Modules 그대로 유지 |
+| `lucide-react` | `lucide-vue-next` |
+| `m2m-uiux-react/*` | `m2m-uiux-vue/*` |
+| 순수 데이터/유틸 `*.ts` (`data/*.ts`, `lib/business.ts`, `lib/theme.ts`, `lib/nav.ts` 등 프레임워크 비의존 로직) | 대부분 그대로 복사 (React 의존 부분만 Vue로 치환) |
+
+## 폴더 구조
+
+React의 `src/pages/**`, `src/components/**`, `src/lib/**`, `src/data/**` 디렉토리 구조와 파일명을 최대한 그대로 유지합니다
+(`.tsx` → `.vue`, 나머지 `.ts` 파일은 파일명 유지). 라우트 경로(URL)도 React `App.tsx`의 라우트 테이블과 완전히 동일하게 구성합니다.
+
+## 작업 시 체크리스트
+
+- [ ] 새 페이지/컴포넌트를 만들 때는 반드시 React 원본 파일을 먼저 읽고 동일한 마크업 구조·클래스·문구로 작성했는지 확인
+- [ ] 라우트 경로, 리다이렉트(구 URL 호환)도 React `App.tsx`와 동일하게 등록했는지 확인
+- [ ] CSS Module 클래스명이 React 쪽과 동일한지 확인 (그대로 복사 후 필요한 문법만 조정)
+- [ ] `m2m-uiux-vue` 컴포넌트 API(props)가 `m2m-uiux-react`와 동일한지 확인 (다르면 실제 배포된 패키지의 타입 정의를 기준으로 조정)
+- [ ] 완료 후 `npm run build` (vue-tsc + vite build)로 타입 에러 없는지 확인

package/template/index.html

@@ -1,10 +1,11 @@
 <!doctype html>
-<html lang="en">
+<html lang="ko" data-theme="light">
   <head>
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>template</title>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/static/pretendard.min.css">
+    <title>회원 관리 · 백오피스</title>
   </head>
   <body>
     <div id="app"></div>