@hamjimin/xplat-back 0.6.2 → 0.6.3

package/README.md

@@ -1,16 +1,19 @@
 # @hamjimin/xplat-back
 
-Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)
+NestJS + TypeScript 백엔드 스캐폴딩/모듈 패키지 (zium-backend 기반)
 
-파일명과 API endpoint가 자동으로 일치하는 라우팅 시스템을 제공합니다. 디렉토리 구조를 기반으로 자동으로 Express 라우터를 생성하여, 파일명만으로 API endpoint를 매핑할 수 있습니다.
+스토어/어드민 API 분리를 기본으로 하는 **NestJS 도메인 모듈 골격**을 제공하고,
+유틸/보안/스토리지/결제/배송 등 공통 기능은 `xplatSystem` 싱글턴을 통해 접근할 수 있습니다.
+
+> 기존 Express 기반 파일 라우팅(createApp/createRouter)은 **레거시 호환용**으로 유지됩니다.
 
 ## 특징
 
-- 🚀 **파일 기반 라우팅**: 파일명과 디렉토리 구조가 API endpoint로 자동 매핑
-- 📁 **자동 라우터 생성**: 디렉토리 구조를 재귀적으로 탐색하여 라우터 자동 생성
-- ⚡ **빠른 프로젝트 설정**: CLI를 통한 프로젝트 초기화
-- 🔧 **TypeScript 지원**: 완전한 TypeScript 타입 정의 포함
-- 🎯 **zium-backend 기반**: 검증된 프로젝트 구조 기반
+- 🧩 **NestJS 모듈 구조**: Store/Admin API 분리, 도메인 모듈 확장 전제
+- 🏷️ **버저닝/Prefix 설계**: `/store/v1`, `/admin/v1` 형태의 라우팅 분리
+- 🔌 **xplatSystem 싱글턴**: 인증/JWT, 스토리지(S3), 결제/배송 등 공통 기능 접근
+- 🛠️ **확장 포인트**: 이벤트/잡/도메인 서비스 등 확장 가능한 구조
+- 🔧 **TypeScript 지원**: 타입 정의 포함
 
 ## 설치
 
@@ -20,145 +23,115 @@ npm install @hamjimin/xplat-back
 yarn add @hamjimin/xplat-back
 ```
 
-## 빠른 시작
+## 빠른 시작 (NestJS 권장)
 
-### CLI를 통한 프로젝트 초기화
-```bash
-npx @hamjimin/xplat-back [project-name]
-```
+### 1. NestJS 앱에 도메인 골격 적용
 
-옵션:
+`xplat-back`는 커머스 도메인 골격(`store/admin` 분리)을 포함합니다.
+서비스에서는 해당 구조를 기준으로 모듈/컨트롤러를 확장하는 방식을 권장합니다.
 
-```bash
-npx @hamjimin/xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+예: Store/Admin Health 컨트롤러 구조
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+
+@Controller()
+export class StoreHealthController {
+  @Get('health')
+  health() {
+    return {
+      ok: true,
+      scope: 'store',
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
 ```
 
-사용 가능한 옵션:
-- `-p, --port <port>`: 서버 포트 (기본값: 4000)
-- `-c, --cors <origins>`: CORS 허용 origins (쉼표로 구분)
-- `-r, --router-dir <directory>`: 라우터 디렉토리 (기본값: src/restapi)
-- `--router-path <path>`: 라우터 base path (기본값: /restapi)
-- `--with-next`: Next.js 프론트엔드(web) 템플릿 추가
+```typescript
+import { Controller, Get } from '@nestjs/common';
+
+@Controller()
+export class AdminHealthController {
+  @Get('health')
+  health() {
+    return {
+      ok: true,
+      scope: 'admin',
+      timestamp: new Date().toISOString(),
+    };
+  }
+}
+```
 
-### 수동 설정
+### 2. 버저닝/Prefix 참고
 
-#### 1. 패키지 설치
+Store/Admin API는 템플릿 기준으로 아래 prefix를 사용합니다.
 
-```bash
-npm install express @hamjimin/xplat-back
-npm install -D typescript @types/express @types/node ts-node tsconfig-paths
+```
+Store API: /store/v1
+Admin API: /admin/v1
 ```
 
-#### 2. Express 앱 생성
-
-`src/app.ts`:
+### 3. 공통 기능 사용 (xplatSystem)
 
 ```typescript
-import express, { Application } from 'express';
-import * as path from 'path';
-import { createApp } from '@hamjimin/xplat-back';
-
-const app: Application = createApp({
-  cors: {
-    origin: ['http://localhost:3000'],
-    credentials: true,
-  },
-  router: {
-    directory: path.join(__dirname, 'restapi'),
-    basePath: '/restapi',
-  },
-  trustProxy: true,
-});
-
-const port = parseInt(process.env.PORT || '4000', 10);
+import { xplatSystem } from '@hamjimin/xplat-back';
 
-app.listen(port, () => {
-  console.log(`🚀 Server is running on port ${port}`);
-});
-
-export default app;
+const { storePrefix, adminPrefix } = xplatSystem.commerce.getVersioning();
+// storePrefix: /store/v1
+// adminPrefix: /admin/v1
 ```
 
-#### 3. 라우트 파일 생성
+## 모듈 구성 (패키지 제공)
 
-`src/restapi/health.ts`:
+- `xplatSystem.app` (레거시 Express 앱 생성)
+- `xplatSystem.router` (레거시 파일 기반 라우팅)
+- `xplatSystem.auth` (JWT/인증 유틸)
+- `xplatSystem.storage` (S3 유틸)
+- `xplatSystem.payment` (Toss/KakaoPay)
+- `xplatSystem.shipping` (CJ/Logen/CVS)
+- `xplatSystem.orm` (쿼리 빌더/ORM 유틸)
 
-```typescript
-import express, { Request, Response } from 'express';
+## CLI (레거시 Express 스캐폴딩)
 
-const router = express.Router();
-
-router.get('/', (req: Request, res: Response) => {
-  res.json({
-    success: true,
-    message: 'Server is healthy',
-    timestamp: new Date().toISOString(),
-  });
-});
+> 현재 CLI는 Express 기반 템플릿을 생성합니다.  
+> NestJS 전용 스캐폴딩은 별도 정리 후 제공 예정입니다.
 
-export = router;
+```bash
+npx @hamjimin/xplat-back [project-name]
 ```
 
-이제 `GET /restapi/health` 엔드포인트가 자동으로 생성됩니다!
-
-#### 4. 서버 실행
+옵션:
 
 ```bash
-npm run dev
-# 또는
-ts-node -r tsconfig-paths/register src/app.ts
+npx @hamjimin/xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
 ```
 
-## API 문서
-
-### `createApp(config?)`
+사용 가능한 옵션:
+- `-p, --port <port>`: 서버 포트 (기본값: 4000)
+- `-c, --cors <origins>`: CORS 허용 origins (쉼표로 구분)
+- `-r, --router-dir <directory>`: 라우터 디렉토리 (기본값: src/restapi)
+- `--router-path <path>`: 라우터 base path (기본값: /restapi)
+- `--with-next`: Next.js 프론트엔드(web) 템플릿 추가
 
-Express 애플리케이션을 생성합니다.
+## 레거시 Express API
 
-#### Parameters
+NestJS 전환 이전 프로젝트를 위한 호환 API입니다.
 
-```typescript
-interface AppConfig {
-  cors?: {
-    origin?: string[] | ((origin: string | undefined, callback: (err: Error | null, allow?: boolean) => void) => void);
-    credentials?: boolean;
-  };
-  json?: {
-    limit?: string;
-  };
-  urlencoded?: {
-    extended?: boolean;
-  };
-  router?: {
-    directory?: string;
-    basePath?: string;
-  };
-  trustProxy?: boolean;
-  middleware?: Array<(req: Request, res: Response, next: NextFunction) => void>;
-}
-```
+### `createApp(config?)`
 
-#### 예제
+Express 애플리케이션을 생성합니다.
 
 ```typescript
 import { createApp } from '@hamjimin/xplat-back';
+import * as path from 'path';
 
 const app = createApp({
-  cors: {
-    origin: process.env.CORS_ALLOW_ORIGINS?.split(',') ?? ['*'],
-    credentials: true,
-  },
   router: {
     directory: path.join(__dirname, 'restapi'),
     basePath: '/restapi',
   },
-  middleware: [
-    // 커스텀 미들웨어
-    (req, res, next) => {
-      console.log(`${req.method} ${req.path}`);
-      next();
-    },
-  ],
 });
 ```
 
@@ -166,12 +139,6 @@ const app = createApp({
 
 디렉토리 구조를 기반으로 Express 라우터를 생성합니다.
 
-#### Parameters
-
-- `directory` (string): 라우트 파일들이 위치한 디렉토리 경로
-
-#### 예제
-
 ```typescript
 import { createRouter } from '@hamjimin/xplat-back';
 import * as path from 'path';
@@ -180,67 +147,6 @@ const router = createRouter(path.join(__dirname, 'restapi'));
 app.use('/restapi', router);
 ```
 
-#### 라우팅 규칙
-
-디렉토리 구조가 다음과 같을 때:
-
-```
-restapi/
-├── health.ts          → GET /restapi/health
-├── user/
-│   ├── profile.ts     → GET /restapi/user/profile
-│   └── settings.ts    → GET /restapi/user/settings
-└── admin/
-    └── users.ts       → GET /restapi/admin/users
-```
-
-- 파일명이 endpoint로 변환됩니다 (`.ts`, `.js` 확장자 제거)
-- 디렉토리는 경로의 일부가 됩니다
-- 각 파일은 Express Router를 export해야 합니다
-
-## 라우트 파일 작성법
-
-각 라우트 파일은 Express Router를 export해야 합니다:
-
-```typescript
-import express, { Request, Response } from 'express';
-
-const router = express.Router();
-
-// GET /restapi/example
-router.get('/', (req: Request, res: Response) => {
-  res.json({ message: 'Hello World' });
-});
-
-// POST /restapi/example
-router.post('/', (req: Request, res: Response) => {
-  res.json({ message: 'Created' });
-});
-
-export = router;
-// 또는
-export default router;
-```
-
-## 프로젝트 구조 예시
-
-```
-my-backend-project/
-├── src/
-│   ├── app.ts              # Express 앱 설정
-│   ├── server.ts           # 서버 시작 (선택적)
-│   └── restapi/            # API 라우트 파일들
-│       ├── health.ts       # GET /restapi/health
-│       ├── user/
-│       │   └── profile.ts  # GET /restapi/user/profile
-│       └── admin/
-│           └── users.ts    # GET /restapi/admin/users
-├── dist/                   # TypeScript 컴파일 결과
-├── tsconfig.json
-├── package.json
-└── .env
-```
-
 ## 환경변수
 
 `.env` 파일에서 설정할 수 있는 환경변수:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamjimin/xplat-back",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",