@hamjimin/xplat-back 0.6.3 → 0.7.0

package/README.md

@@ -1,19 +1,11 @@
 # @hamjimin/xplat-back
 
-NestJS + TypeScript 백엔드 스캐폴딩/모듈 패키지 (zium-backend 기반)
+Express + TypeScript 백엔드 프레임워크 & CLI 스캐폴딩 도구
 
-스토어/어드민 API 분리를 기본으로 하는 **NestJS 도메인 모듈 골격**을 제공하고,
-유틸/보안/스토리지/결제/배송 등 공통 기능은 `xplatSystem` 싱글턴을 통해 접근할 수 있습니다.
+커머스 백엔드에 필요한 **인증, 스토리지, 결제, 배송, 쿼리 빌더** 등의 모듈을 `xplatSystem` 싱글턴으로 통합 제공하며,
+CLI를 통해 프로젝트 초기화와 **MySQL DDL 자동 설치**까지 지원합니다.
 
-> 기존 Express 기반 파일 라우팅(createApp/createRouter)은 **레거시 호환용**으로 유지됩니다.
-
-## 특징
-
-- 🧩 **NestJS 모듈 구조**: Store/Admin API 분리, 도메인 모듈 확장 전제
-- 🏷️ **버저닝/Prefix 설계**: `/store/v1`, `/admin/v1` 형태의 라우팅 분리
-- 🔌 **xplatSystem 싱글턴**: 인증/JWT, 스토리지(S3), 결제/배송 등 공통 기능 접근
-- 🛠️ **확장 포인트**: 이벤트/잡/도메인 서비스 등 확장 가능한 구조
-- 🔧 **TypeScript 지원**: 타입 정의 포함
+---
 
 ## 설치
 
@@ -23,138 +15,446 @@ npm install @hamjimin/xplat-back
 yarn add @hamjimin/xplat-back
 ```
 
-## 빠른 시작 (NestJS 권장)
+## 빠른 시작
 
-### 1. NestJS 앱에 도메인 골격 적용
+### 1. 프로젝트 스캐폴딩
 
-`xplat-back`는 커머스 도메인 골격(`store/admin` 분리)을 포함합니다.
-서비스에서는 해당 구조를 기준으로 모듈/컨트롤러를 확장하는 방식을 권장합니다.
+```bash
+npx @hamjimin/xplat-back my-project
+```
 
-예: Store/Admin Health 컨트롤러 구조
+자동 생성되는 파일:
+
+```
+my-project/
+├── src/
+│   ├── app.ts                         # Express 앱 진입점
+│   ├── server.ts                      # 서버 실행 파일
+│   ├── restapi/
+│   │   └── health.ts                  # 예시 API 라우트
+│   ├── const/
+│   │   ├── api_code.ts                # API 응답 코드 상수
+│   │   └── constants.ts               # 공통 상수
+│   └── util/
+│       └── dbconfig/
+│           └── dbConnections.ts       # DB 연결 설정 (TypeORM)
+├── tsconfig.json
+├── package.json
+└── .env
+```
+
+### 2. Express 앱 생성
 
 ```typescript
-import { Controller, Get } from '@nestjs/common';
-
-@Controller()
-export class StoreHealthController {
-  @Get('health')
-  health() {
-    return {
-      ok: true,
-      scope: 'store',
-      timestamp: new Date().toISOString(),
-    };
-  }
-}
+import { createApp } from '@hamjimin/xplat-back';
+import * as path from 'path';
+
+const app = createApp({
+  cors: {
+    origin: ['http://localhost:3000'],
+    credentials: true,
+  },
+  router: {
+    directory: path.join(__dirname, 'restapi'),
+    basePath: '/restapi',
+  },
+  trustProxy: true,
+});
+
+app.listen(4000, () => {
+  console.log('Server running on port 4000');
+});
+```
+
+`createApp` 옵션:
+
+| 옵션 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `cors.origin` | `string[]` | `['*']` | CORS 허용 origin |
+| `cors.credentials` | `boolean` | `true` | 자격 증명 허용 |
+| `json.limit` | `string` | `'1mb'` | JSON body 크기 제한 |
+| `router.directory` | `string` | `'src/restapi'` | 라우트 파일 디렉토리 |
+| `router.basePath` | `string` | `'/restapi'` | 라우터 base path |
+| `trustProxy` | `boolean` | `true` | 프록시 신뢰 |
+| `middleware` | `Function[]` | `[]` | 커스텀 미들웨어 |
+
+### 3. 파일 기반 라우팅
+
+디렉토리 구조가 API endpoint에 자동 매핑됩니다.
+
+```
+src/restapi/
+├── health.ts          → GET /restapi/health
+├── users.ts           → /restapi/users
+└── users/
+    └── profile.ts     → /restapi/users/profile
 ```
 
 ```typescript
-import { Controller, Get } from '@nestjs/common';
-
-@Controller()
-export class AdminHealthController {
-  @Get('health')
-  health() {
-    return {
-      ok: true,
-      scope: 'admin',
-      timestamp: new Date().toISOString(),
-    };
-  }
-}
+import { createRouter } from '@hamjimin/xplat-back';
+
+const router = createRouter(path.join(__dirname, 'restapi'));
+app.use('/restapi', router);
+```
+
+---
+
+## CLI
+
+```bash
+npx @hamjimin/xplat-back [project-name] [options]
+npx @hamjimin/xplat-back db:setup
 ```
 
-### 2. 버저닝/Prefix 참고
+### 프로젝트 생성 옵션
+
+| 옵션 | 단축 | 설명 | 기본값 |
+|------|------|------|--------|
+| `--port <port>` | `-p` | 서버 포트 | `4000` |
+| `--cors <origins>` | `-c` | CORS origins (쉼표 구분) | `http://localhost:3000` |
+| `--router-dir <dir>` | `-r` | 라우터 디렉토리 | `src/restapi` |
+| `--router-path <path>` | | 라우터 base path | `/restapi` |
+
+```bash
+npx @hamjimin/xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+```
+
+### db:setup - MySQL DDL 자동 설치
+
+인터랙티브 UI로 MySQL 접속 정보를 입력하고, 필요한 테이블을 선택하여 바로 생성합니다.
 
-Store/Admin API는 템플릿 기준으로 아래 prefix를 사용합니다.
+```bash
+npx @hamjimin/xplat-back db:setup
+```
+
+**실행 흐름:**
 
 ```
-Store API: /store/v1
-Admin API: /admin/v1
+🗄️  xplat-back 데이터베이스 설정
+
+? DB Host: localhost
+? DB User: root
+? DB Password: ****
+? DB Name: my_shop
+? DB Port: 3306
+
+✅ MySQL 연결 성공!
+
+? 설치할 DDL 모듈을 선택하세요 (스페이스바로 선택):
+ ◉ 사용자 (User / Employee / Partner)
+ ◉ 상품 (Category / Product / Variants / Brand / Side_Product)
+ ◯ 패키지 (Product_Package / Detail / Variant)
+ ◉ 주문 (Orders / Order_Items / Order_Manage)
+ ...
+
+📎 의존성으로 자동 추가된 모듈:
+  → 사용자 (01_user.sql)
+
+📋 실행 대상 DDL (3개 파일):
+  📦 01_user.sql - 사용자
+  📦 02_product.sql - 상품
+  📦 04_order.sql - 주문
+
+? 위 3개 DDL 파일을 실행하시겠습니까? Yes
+
+  ✅ 01_user.sql → user, employee, partner
+  ✅ 02_product.sql → category, product, variants, brand, side_product
+  ✅ 04_order.sql → orders, order_items, order_manage, order_manage_comment
+
+🎉 데이터베이스 설정이 완료되었습니다!
 ```
 
-### 3. 공통 기능 사용 (xplatSystem)
+**제공되는 DDL 모듈 (10개):**
+
+| # | 모듈 | 테이블 |
+|---|------|--------|
+| 1 | 사용자 | `user`, `employee`, `partner` |
+| 2 | 상품 | `category`, `product`, `variants`, `brand`, `side_product` |
+| 3 | 패키지 | `product_package`, `product_package_detail`, `product_package_variant` |
+| 4 | 주문 | `orders`, `order_items`, `order_manage`, `order_manage_comment` |
+| 5 | 결제 | `payment`, `calcurate` |
+| 6 | 배송 | `delivery`, `reservation` |
+| 7 | 장바구니 | `cart`, `cart_items` |
+| 8 | 캠페인 | `campaign`, `promotion_detail`, `event_detail` |
+| 9 | 리뷰 | `product_review`, `review_images`, `package_product_review`, `package_review_images` |
+| 10 | 연결 테이블 | `chain_category_detail`, `chain_product_detail`, `chain_variant_detail` 외 5개 |
+
+- FK 의존성이 자동 해결됩니다 (예: 주문 선택 시 사용자 자동 포함)
+- `IF NOT EXISTS`로 멱등성이 보장되어 중복 실행해도 안전합니다
+- 이미 존재하는 테이블은 체크박스에 상태가 표시됩니다
+
+---
+
+## xplatSystem 싱글턴
+
+모든 모듈은 `xplatSystem` 인스턴스를 통해 접근할 수 있습니다.
 
 ```typescript
 import { xplatSystem } from '@hamjimin/xplat-back';
 
-const { storePrefix, adminPrefix } = xplatSystem.commerce.getVersioning();
-// storePrefix: /store/v1
-// adminPrefix: /admin/v1
+xplatSystem.auth       // 인증/JWT
+xplatSystem.storage    // S3 스토리지
+xplatSystem.payment    // 결제
+xplatSystem.shipping   // 배송
+xplatSystem.orm        // 쿼리 빌더
+xplatSystem.middleware // 미들웨어
+xplatSystem.commerce   // NestJS 커머스 모듈
 ```
 
-## 모듈 구성 (패키지 제공)
+---
 
-- `xplatSystem.app` (레거시 Express 앱 생성)
-- `xplatSystem.router` (레거시 파일 기반 라우팅)
-- `xplatSystem.auth` (JWT/인증 유틸)
-- `xplatSystem.storage` (S3 유틸)
-- `xplatSystem.payment` (Toss/KakaoPay)
-- `xplatSystem.shipping` (CJ/Logen/CVS)
-- `xplatSystem.orm` (쿼리 빌더/ORM 유틸)
+## 모듈 상세
 
-## CLI (레거시 Express 스캐폴딩)
+### Auth - 인증/JWT
 
-> 현재 CLI는 Express 기반 템플릿을 생성합니다.  
-> NestJS 전용 스캐폴딩은 별도 정리 후 제공 예정입니다.
+```typescript
+import { xplatSystem } from '@hamjimin/xplat-back';
 
-```bash
-npx @hamjimin/xplat-back [project-name]
+// 토큰 생성
+const token = xplatSystem.auth.generateToken(
+  { id: 'user-1', role: 'admin' },
+  { secret: process.env.JWT_SECRET!, expiresIn: '1h' }
+);
+
+// Access + Refresh 토큰 쌍 생성
+const tokenPair = xplatSystem.auth.createTokenPair(
+  { id: 'user-1' },
+  { secret: process.env.JWT_SECRET!, expiresIn: '15m' },   // access
+  { secret: process.env.JWT_SECRET!, expiresIn: '7d' }     // refresh
+);
+
+// 인증 미들웨어
+const authMiddleware = xplatSystem.auth.createMiddleware({
+  secret: process.env.JWT_SECRET!,
+  cookieName: 'accessToken',
+  onSuccess: (req, payload) => { req.user = payload; },
+});
+
+app.use('/api/protected', authMiddleware);
 ```
 
-옵션:
+토큰은 **Cookie** 또는 **Authorization: Bearer** 헤더에서 자동 추출됩니다.
 
-```bash
-npx @hamjimin/xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+### Storage - S3 파일 관리
+
+```typescript
+const storage = xplatSystem.storage;
+
+// S3 설정 (환경변수 또는 직접 전달)
+// S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, AWS_REGION
+
+// 업로드
+await storage.upload({
+  key: 'uploads/2025/01/image.png',
+  body: fileBuffer,
+  bucket: 'my-bucket',
+  contentType: 'image/png',
+});
+
+// Presigned 다운로드 URL 생성
+const url = await storage.getDownloadUrl({
+  key: 'uploads/2025/01/image.png',
+  bucket: 'my-bucket',
+  expiresInSec: 3600,
+});
+
+// 삭제
+await storage.delete({ key: 'uploads/2025/01/image.png', bucket: 'my-bucket' });
 ```
 
-사용 가능한 옵션:
-- `-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) 템플릿 추가
+유틸 함수:
+- `buildKey(prefix, fileName, date?)` - 날짜 기반 S3 key 생성 (`prefix/YYYY/MM/DD/fileName`)
+- `extractKey(url)` - S3 URL에서 key 추출
+- `getDatePrefix()` - `YYYY/MM/DD` 형태의 접두사
+
+### Payment - 결제
+
+Toss Payments, KakaoPay를 플러그인 방식으로 지원합니다.
 
-## 레거시 Express API
+```typescript
+import { TossPaymentProvider, KakaoPayProvider } from '@hamjimin/xplat-back';
+
+const payment = xplatSystem.payment;
+
+// 결제 프로바이더 등록
+payment.registerProvider(new TossPaymentProvider({
+  secretKey: process.env.TOSS_SECRET_KEY!,
+  testMode: true,
+}), true);   // true = 기본 프로바이더로 설정
+
+payment.registerProvider(new KakaoPayProvider({
+  adminKey: process.env.KAKAO_ADMIN_KEY!,
+  cid: 'TC0ONETIME',
+}));
+
+// 결제 요청
+const response = await payment.requestPayment({
+  orderId: 'order-123',
+  amount: 15000,
+  customerName: '홍길동',
+});
 
-NestJS 전환 이전 프로젝트를 위한 호환 API입니다.
+// 결제 승인
+const details = await payment.confirmPayment({
+  paymentKey: response.paymentKey,
+  orderId: 'order-123',
+  amount: 15000,
+});
 
-### `createApp(config?)`
+// 결제 취소
+await payment.cancelPayment({
+  paymentKey: response.paymentKey,
+  cancelReason: '고객 요청',
+});
+```
 
-Express 애플리케이션을 생성합니다.
+### Shipping - 배송
+
+CJ대한통운, 로젠, 편의점 택배를 플러그인 방식으로 지원합니다.
 
 ```typescript
-import { createApp } from '@hamjimin/xplat-back';
-import * as path from 'path';
+import { CJLogisticsProvider, LogenProvider } from '@hamjimin/xplat-back';
 
-const app = createApp({
-  router: {
-    directory: path.join(__dirname, 'restapi'),
-    basePath: '/restapi',
-  },
+const shipping = xplatSystem.shipping;
+
+shipping.registerProvider(new CJLogisticsProvider({
+  apiKey: process.env.CJ_API_KEY!,
+  customerCode: 'CUSTOMER-001',
+}), true);
+
+// 배송비 계산
+const fee = await shipping.calculateFee({
+  destinationZip: '06234',
+  weight: 2.5,
+});
+
+// 운송장 생성
+const label = await shipping.createLabel({
+  orderId: 'order-123',
+  toName: '홍길동',
+  toPhone: '010-1234-5678',
+  toAddress: '서울시 강남구 테헤란로 123',
+  toZip: '06234',
 });
+
+// 배송 조회
+const tracking = await shipping.track(label.trackingNumber);
 ```
 
-### `createRouter(directory)`
+### ORM - 쿼리 빌더
 
-디렉토리 구조를 기반으로 Express 라우터를 생성합니다.
+SQL WHERE / ORDER BY 절을 구조화된 데이터로 생성합니다.
 
 ```typescript
-import { createRouter } from '@hamjimin/xplat-back';
-import * as path from 'path';
+import { xplatSystem } from '@hamjimin/xplat-back';
 
-const router = createRouter(path.join(__dirname, 'restapi'));
-app.use('/restapi', router);
+const orm = xplatSystem.orm;
+
+// WHERE 절 생성
+const whereQuery = orm.createWhereQuery({
+  condition: 'AND',
+  searchData: [
+    { column: 'name', operator: 'LIKE', value: '홍' },
+    { column: 'status', operator: 'IN', value: ['active', 'pending'] },
+    { column: 'created_at', operator: 'BETWEEN', value: ['2025-01-01', '2025-12-31'] },
+  ],
+});
+
+// ORDER BY 절 생성
+const sortQuery = orm.createSortQuery([
+  { column: 'created_at', operator: 'DESC' },
+  { column: 'name', operator: 'ASC' },
+]);
+
+// 기존 쿼리에 적용
+let query = 'SELECT * FROM user WHERE 1=1';
+query = orm.appendWhereClause(query, whereQuery);
+query = orm.appendOrderClause(query, sortQuery);
 ```
 
+지원 연산자: `=`, `!=`, `LIKE`, `IN`, `NOTIN`, `BETWEEN`, `ISNULL`, `ISNOTNULL`
+
+### Middleware - 미들웨어
+
+```typescript
+const mw = xplatSystem.middleware;
+
+// 요청 로깅
+app.use(mw.logger());
+
+// 상세 로깅 (body 포함)
+app.use(mw.detailedLogger());
+
+// 필드 검증
+app.post('/users', mw.requireFields(['email', 'password']));
+
+// 커스텀 검증
+app.post('/users', mw.validator({
+  body: {
+    email: (v) => typeof v === 'string' && v.includes('@') || 'Invalid email',
+    age: (v) => typeof v === 'number' && v > 0 || 'Age must be positive',
+  },
+}));
+
+// 에러 핸들러 + 404 (마지막에 등록)
+app.use(mw.notFound());
+app.use(mw.errorHandler());
+```
+
+---
+
+## NestJS 커머스 모듈
+
+Store/Admin API 분리 구조를 제공합니다.
+
+```typescript
+import { Module } from '@nestjs/common';
+import { CommerceModule } from '@hamjimin/xplat-back';
+
+@Module({
+  imports: [CommerceModule],
+})
+export class AppModule {}
+```
+
+```
+Store API: /store/v1/*
+Admin API: /admin/v1/*
+```
+
+```typescript
+const { storePrefix, adminPrefix } = xplatSystem.commerce.getVersioning();
+// storePrefix: /store/v1
+// adminPrefix: /admin/v1
+```
+
+---
+
 ## 환경변수
 
-`.env` 파일에서 설정할 수 있는 환경변수:
+`.env` 파일에서 설정 가능한 환경변수:
 
 ```env
+# 앱
 NODE_ENV=development
 PORT=4000
-CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:5173
+CORS_ALLOW_ORIGINS=http://localhost:3000
+
+# 데이터베이스
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=
+DB_DATABASE=my_database
+
+# AWS S3
+AWS_REGION=ap-northeast-2
+S3_BUCKET=my-bucket
+S3_ACCESS_KEY=
+S3_SECRET_KEY=
+
+# JWT
+JWT_SECRET=your-secret-key
 ```
 
 ## TypeScript 설정
@@ -173,23 +473,46 @@ CORS_ALLOW_ORIGINS=http://localhost:3000,http://localhost:5173
     "moduleResolution": "node",
     "sourceMap": true,
     "baseUrl": "./src",
-    "paths": {
-      "@/*": ["*"]
-    }
+    "paths": { "@/*": ["*"] }
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]
 }
 ```
 
-## 라이센스
-
-ISC
-
-## 기여
+## Export 목록
 
-버그 리포트 및 기능 제안은 이슈로 등록해주세요.
+```typescript
+// 싱글턴
+export { xplatSystem, XplatSystem } from '@hamjimin/xplat-back';
+
+// 앱/라우터
+export { createApp, createRouter } from '@hamjimin/xplat-back';
+
+// 모듈
+export {
+  AppModule, RouterModule, AuthModule,
+  UtilsModule, MiddlewareModule, ConstantsModule,
+  StorageModule, ORMModule, PaymentModule, ShippingModule,
+} from '@hamjimin/xplat-back';
+
+// 결제 프로바이더
+export { TossPaymentProvider, KakaoPayProvider } from '@hamjimin/xplat-back';
+
+// 배송 프로바이더
+export { CJLogisticsProvider, LogenProvider, CvsProvider } from '@hamjimin/xplat-back';
+
+// 타입
+export type {
+  AppConfig, ExtendedRequest, ExtendedResponse, AuthenticatedRequest,
+  TokenPayload, TokenOptions, TokenPair,
+  DetailSearch, SortQueryData, SearchDataItem, ColumnMapper,
+  S3Config,
+  PaymentRequestParams, PaymentResponse, PaymentConfirmParams, PaymentDetails,
+  ShippingFeeParams, ShippingFee, CreateLabelParams, ShippingLabel, TrackingInfo,
+} from '@hamjimin/xplat-back';
+```
 
-## 관련 프로젝트
+## 라이센스
 
-이 패키지는 [zium-backend](https://github.com/your-org/zium-backend) 프로젝트의 구조를 기반으로 만들어졌습니다.
+ISC