@axyl-tcb/create-template 1.0.15 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axyl-tcb/create-template",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Axyl TCB Cloud Function 프로젝트 스캐폴딩 CLI (npm create @axyl-tcb/template)",
   "bin": {
     "create-template": "bin/index.js"

package/template/MYSQL.md

@@ -12,6 +12,7 @@ TCB Cloud Function 에서 `mysql2` 를 통해 MySQL 을 사용하는 방법을
 - [트랜잭션](#트랜잭션)
 - [에러 처리](#에러-처리)
 - [baseHandler 통합 예시](#basehandler-통합-예시)
+- [테스트](#테스트)
 - [활용편 — 멱등성 키로 중복 요청 차단하기](#활용편--멱등성-키로-중복-요청-차단하기)
 
 ---
@@ -115,6 +116,8 @@ const [rows] = await pool.query<RowDataPacket[]>(
 );
 ```
 
+> `LIMIT` · `OFFSET` 에도 `?` 플레이스홀더를 쓸 수 있습니다. 단 이 템플릿처럼 `pool.query` 를 사용하세요 — `pool.execute`(prepared statement)는 일부 mysql2 버전에서 LIMIT 바인딩을 거부합니다.
+
 ### IN 조건
 
 ```ts
@@ -280,7 +283,7 @@ try {
 } catch (err: unknown) {
     const mysqlErr = err as { code?: string };
     if (mysqlErr.code === 'ER_DUP_ENTRY') {
-        throw new AxylMiddlewareError(ERROR_CODES.CONFLICT, '이미 존재하는 항목입니다.');
+        throw new AxylMiddlewareError(ERROR_CODES.INVALID_PARAMETER, '이미 존재하는 항목입니다.');
     }
     throw err; // 나머지는 INTERNAL_ERROR 로 처리
 }
@@ -351,6 +354,73 @@ export const main = createAxylHandler(baseHandler, {
 
 ---
 
+## 테스트
+
+핸들러는 실제 DB 연결 없이 테스트합니다. `@axyl-tcb/middleware/db` 를 `vi.mock` 으로 대체하면 됩니다. mock 객체는 `vi.hoisted` 로 먼저 만들어야 hoisting 문제가 없습니다.
+
+> mock 반환 형태는 mysql2 와 동일한 `[rows, fields]` 튜플입니다. SELECT 는 `[[...rows], []]`, INSERT/UPDATE 는 `[{ insertId, affectedRows }, []]` 처럼 첫 요소만 맞추면 됩니다.
+
+### pool.query 기반 (SELECT / INSERT / UPDATE / DELETE)
+
+```ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const { mockPool } = vi.hoisted(() => ({
+    mockPool: { query: vi.fn() },
+}));
+
+vi.mock('@axyl-tcb/middleware/db', () => ({ pool: mockPool }));
+
+import { main } from '../../src/functions/mysql/getInventory';
+
+describe('getInventory handler', () => {
+    const event = { headers: { 'X-Hive-Player-Id': 'p1', 'X-Hive-Aud': '10-1001-5' } };
+    beforeEach(() => vi.clearAllMocks());
+
+    it('보상 목록을 조회한다', async () => {
+        mockPool.query.mockResolvedValueOnce([[{ id: 1, item_id: 10, quantity: 3 }]]);
+
+        const result = await main(event, {});
+
+        expect(result.success).toBe(true);
+        if (!result.success) return;
+        expect(result.data.rewards).toHaveLength(1);
+
+        const [sql, params] = mockPool.query.mock.calls[0]!;
+        expect(sql).toContain('FROM rewards');
+        expect(params).toEqual(['p1', 1001, 20]);   // playerId, aud.gameIndex, limit
+    });
+});
+```
+
+### transaction 기반
+
+`transaction` 헬퍼를 mock 해 콜백에 가짜 커넥션(`conn`)을 넘깁니다. 단계별 쿼리 결과는 `mockConn.query.mockResolvedValueOnce(...)` 로 순서대로 지정합니다.
+
+```ts
+const { mockConn, mockTransaction } = vi.hoisted(() => ({
+    mockConn:        { query: vi.fn() },
+    mockTransaction: vi.fn(),
+}));
+
+vi.mock('@axyl-tcb/middleware/db', () => ({
+    pool:        { query: vi.fn() },
+    transaction: mockTransaction,
+}));
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    // transaction(fn) 이 fn(conn) 을 그대로 실행하도록 연결
+    mockTransaction.mockImplementation(
+        (fn: (conn: typeof mockConn) => Promise<unknown>) => fn(mockConn)
+    );
+});
+```
+
+실제 예시는 생성된 프로젝트의 `test/mysql/grantItem.test.ts`(transaction) 와 `test/mysql/drawGacha.test.ts`(pool + transaction) 를 참고하세요.
+
+---
+
 ## 활용편 — 멱등성 키로 중복 요청 차단하기
 
 ### 왜 필요한가
@@ -488,7 +558,7 @@ const baseHandler: AxylBaseHandler<RewardReqDto, RewardResDto> = async (
 
 ### 실제 예제 — drawGacha (확률성 작업 = 결과 캐싱 필수)
 
-`src/functions/drawGacha.ts` 는 패턴 1(결과 캐싱)을 가챠 뽑기에 적용한 예제입니다.
+`src/functions/mysql/drawGacha.ts` 는 패턴 1(결과 캐싱)을 가챠 뽑기에 적용한 예제입니다.
 
 가챠처럼 **결과가 확률로 정해지는 작업**은 재시도 시 재실행하면 결과가 달라지므로, 단순 중복 차단(패턴 2)으론 부족하고 **원래 뽑힌 결과를 저장했다가 그대로 재반환**해야 합니다.
 

package/template/README.md

@@ -361,12 +361,24 @@ export const main = createAxylHandler(baseHandler);
   "TCB_DOCDB_INSTANCE": "",
   "TCB_DOCDB_DATABASE": ""
 }
+
+// Cloud Storage + MySQL 을 함께 쓰는 경우 (예: uploadFile, deleteFile — 파일 저장 + files 테이블 기록)
+"envVariables": {
+  "TCB_ENV_ID": "",
+  "DB_HOST": "",
+  "DB_PORT": "",
+  "DB_USER": "",
+  "DB_PASSWORD": "",
+  "DB_NAME": ""
+}
 ```
 
 ### 3. 테스트 작성
 
-`test/<테마>/myFunction.test.ts` 를 작성합니다.  
-DB를 사용하는 경우 `test/mysql/grantItem.test.ts` 를 참고하세요.
+`test/<테마>/myFunction.test.ts` 를 작성합니다. 실제 DB/TCB 연결 없이 미들웨어 서브패스를 `vi.mock` 으로 대체합니다.
+
+- 단순 쿼리(`pool.query`) → `test/mysql/drawGacha.test.ts` 또는 [MYSQL.md 테스트](./MYSQL.md#테스트) 의 *pool.query 기반* 예시
+- 트랜잭션(`transaction`) → `test/mysql/grantItem.test.ts` 또는 [MYSQL.md 테스트](./MYSQL.md#테스트) 의 *transaction 기반* 예시
 
 ---