@hamjimin/xplat-back 0.6.2 → 0.7.0

package/README.md

@@ -1,16 +1,11 @@
 # @hamjimin/xplat-back
 
-Express + TypeScript 백엔드 스캐폴딩 도구 (zium-backend 기반)
+Express + TypeScript 백엔드 프레임워크 & CLI 스캐폴딩 도구
 
-파일명과 API endpoint가 자동으로 일치하는 라우팅 시스템을 제공합니다. 디렉토리 구조를 기반으로 자동으로 Express 라우터를 생성하여, 파일명만으로 API endpoint를 매핑할 수 있습니다.
+커머스 백엔드에 필요한 **인증, 스토리지, 결제, 배송, 쿼리 빌더** 등의 모듈을 `xplatSystem` 싱글턴으로 통합 제공하며,
+CLI를 통해 프로젝트 초기화와 **MySQL DDL 자동 설치**까지 지원합니다.
 
-## 특징
-
-- 🚀 **파일 기반 라우팅**: 파일명과 디렉토리 구조가 API endpoint로 자동 매핑
-- 📁 **자동 라우터 생성**: 디렉토리 구조를 재귀적으로 탐색하여 라우터 자동 생성
-- ⚡ **빠른 프로젝트 설정**: CLI를 통한 프로젝트 초기화
-- 🔧 **TypeScript 지원**: 완전한 TypeScript 타입 정의 포함
-- 🎯 **zium-backend 기반**: 검증된 프로젝트 구조 기반
+---
 
 ## 설치
 
@@ -22,43 +17,39 @@ yarn add @hamjimin/xplat-back
 
 ## 빠른 시작
 
-### CLI를 통한 프로젝트 초기화
-```bash
-npx @hamjimin/xplat-back [project-name]
-```
-
-옵션:
+### 1. 프로젝트 스캐폴딩
 
 ```bash
-npx @hamjimin/xplat-back my-project --port 3000 --cors "http://localhost:3000,http://localhost:5173"
+npx @hamjimin/xplat-back my-project
 ```
 
-사용 가능한 옵션:
-- `-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) 템플릿 추가
+자동 생성되는 파일:
 
-### 수동 설정
-
-#### 1. 패키지 설치
-
-```bash
-npm install express @hamjimin/xplat-back
-npm install -D typescript @types/express @types/node ts-node tsconfig-paths
+```
+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 앱 생성
-
-`src/app.ts`:
+### 2. Express 앱 생성
 
 ```typescript
-import express, { Application } from 'express';
-import * as path from 'path';
 import { createApp } from '@hamjimin/xplat-back';
+import * as path from 'path';
 
-const app: Application = createApp({
+const app = createApp({
   cors: {
     origin: ['http://localhost:3000'],
     credentials: true,
@@ -70,185 +61,400 @@ const app: Application = createApp({
   trustProxy: true,
 });
 
-const port = parseInt(process.env.PORT || '4000', 10);
-
-app.listen(port, () => {
-  console.log(`🚀 Server is running on port ${port}`);
+app.listen(4000, () => {
+  console.log('Server running on port 4000');
 });
-
-export default app;
 ```
 
-#### 3. 라우트 파일 생성
+`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. 파일 기반 라우팅
 
-`src/restapi/health.ts`:
+디렉토리 구조가 API endpoint에 자동 매핑됩니다.
+
+```
+src/restapi/
+├── health.ts          → GET /restapi/health
+├── users.ts           → /restapi/users
+└── users/
+    └── profile.ts     → /restapi/users/profile
+```
 
 ```typescript
-import express, { Request, Response } from 'express';
+import { createRouter } from '@hamjimin/xplat-back';
+
+const router = createRouter(path.join(__dirname, 'restapi'));
+app.use('/restapi', router);
+```
 
-const router = express.Router();
+---
 
-router.get('/', (req: Request, res: Response) => {
-  res.json({
-    success: true,
-    message: 'Server is healthy',
-    timestamp: new Date().toISOString(),
-  });
-});
+## CLI
 
-export = router;
+```bash
+npx @hamjimin/xplat-back [project-name] [options]
+npx @hamjimin/xplat-back db:setup
 ```
 
-이제 `GET /restapi/health` 엔드포인트가 자동으로 생성됩니다!
+### 프로젝트 생성 옵션
 
-#### 4. 서버 실행
+| 옵션 | 단축 | 설명 | 기본값 |
+|------|------|------|--------|
+| `--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
-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 문서
+### db:setup - MySQL DDL 자동 설치
 
-### `createApp(config?)`
+인터랙티브 UI로 MySQL 접속 정보를 입력하고, 필요한 테이블을 선택하여 바로 생성합니다.
 
-Express 애플리케이션을 생성합니다.
+```bash
+npx @hamjimin/xplat-back db:setup
+```
 
-#### Parameters
+**실행 흐름:**
 
-```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>;
-}
 ```
+🗄️  xplat-back 데이터베이스 설정
 
-#### 예제
+? DB Host: localhost
+? DB User: root
+? DB Password: ****
+? DB Name: my_shop
+? DB Port: 3306
 
-```typescript
-import { createApp } from '@hamjimin/xplat-back';
+✅ MySQL 연결 성공!
 
-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();
-    },
-  ],
-});
+? 설치할 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
+
+🎉 데이터베이스 설정이 완료되었습니다!
 ```
 
-### `createRouter(directory)`
+**제공되는 DDL 모듈 (10개):**
 
-디렉토리 구조를 기반으로 Express 라우터를 생성합니다.
+| # | 모듈 | 테이블 |
+|---|------|--------|
+| 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개 |
 
-#### Parameters
+- FK 의존성이 자동 해결됩니다 (예: 주문 선택 시 사용자 자동 포함)
+- `IF NOT EXISTS`로 멱등성이 보장되어 중복 실행해도 안전합니다
+- 이미 존재하는 테이블은 체크박스에 상태가 표시됩니다
 
-- `directory` (string): 라우트 파일들이 위치한 디렉토리 경로
+---
 
-#### 예제
+## xplatSystem 싱글턴
 
-```typescript
-import { createRouter } from '@hamjimin/xplat-back';
-import * as path from 'path';
+모든 모듈은 `xplatSystem` 인스턴스를 통해 접근할 수 있습니다.
 
-const router = createRouter(path.join(__dirname, 'restapi'));
-app.use('/restapi', router);
+```typescript
+import { xplatSystem } from '@hamjimin/xplat-back';
+
+xplatSystem.auth       // 인증/JWT
+xplatSystem.storage    // S3 스토리지
+xplatSystem.payment    // 결제
+xplatSystem.shipping   // 배송
+xplatSystem.orm        // 쿼리 빌더
+xplatSystem.middleware // 미들웨어
+xplatSystem.commerce   // NestJS 커머스 모듈
 ```
 
-#### 라우팅 규칙
+---
+
+## 모듈 상세
 
-디렉토리 구조가 다음과 같을 때:
+### Auth - 인증/JWT
 
+```typescript
+import { xplatSystem } from '@hamjimin/xplat-back';
+
+// 토큰 생성
+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);
 ```
-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
+
+토큰은 **Cookie** 또는 **Authorization: Bearer** 헤더에서 자동 추출됩니다.
+
+### 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' });
 ```
 
-- 파일명이 endpoint로 변환됩니다 (`.ts`, `.js` 확장자 제거)
-- 디렉토리는 경로의 일부가 됩니다
-- 각 파일은 Express Router를 export해야 합니다
+유틸 함수:
+- `buildKey(prefix, fileName, date?)` - 날짜 기반 S3 key 생성 (`prefix/YYYY/MM/DD/fileName`)
+- `extractKey(url)` - S3 URL에서 key 추출
+- `getDatePrefix()` - `YYYY/MM/DD` 형태의 접두사
 
-## 라우트 파일 작성법
+### Payment - 결제
 
-각 라우트 파일은 Express Router를 export해야 합니다:
+Toss Payments, KakaoPay를 플러그인 방식으로 지원합니다.
 
 ```typescript
-import express, { Request, Response } from 'express';
+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: '홍길동',
+});
 
-const router = express.Router();
+// 결제 승인
+const details = await payment.confirmPayment({
+  paymentKey: response.paymentKey,
+  orderId: 'order-123',
+  amount: 15000,
+});
 
-// GET /restapi/example
-router.get('/', (req: Request, res: Response) => {
-  res.json({ message: 'Hello World' });
+// 결제 취소
+await payment.cancelPayment({
+  paymentKey: response.paymentKey,
+  cancelReason: '고객 요청',
 });
+```
+
+### Shipping - 배송
+
+CJ대한통운, 로젠, 편의점 택배를 플러그인 방식으로 지원합니다.
+
+```typescript
+import { CJLogisticsProvider, LogenProvider } from '@hamjimin/xplat-back';
 
-// POST /restapi/example
-router.post('/', (req: Request, res: Response) => {
-  res.json({ message: 'Created' });
+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',
 });
 
-export = router;
-// 또는
-export default router;
+// 배송 조회
+const tracking = await shipping.track(label.trackingNumber);
 ```
 
-## 프로젝트 구조 예시
+### ORM - 쿼리 빌더
+
+SQL WHERE / ORDER BY 절을 구조화된 데이터로 생성합니다.
+
+```typescript
+import { xplatSystem } from '@hamjimin/xplat-back';
+
+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);
 ```
-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
+
+지원 연산자: `=`, `!=`, `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 설정
@@ -267,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