@xfilecom/xframe 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Scaffold full-stack app: Nest + @xfilecom/backend-core, Vite/React + @xfilecom/front-core",
   "license": "UNLICENSED",
   "bin": {

package/template/README.md

@@ -16,7 +16,7 @@ Nest API (`@xfilecom/backend-core`) + Vite/React client·admin (`@xfilecom/front
 
 ## URLs
 
-- API: `http://localhost:3000` — `GET /health` (`AppService`: Drizzle 직접 카운트; `DatabaseQuery` 는 `docs/DATABASE.md`)
+- API: `http://localhost:3000` — `GET /health` (`AppService`: DB 로드·연결 여부만; 쿼리 패턴은 `docs/DATABASE.md`)
 - Client: `http://localhost:3001` — `CommonResponse` 형태로 `/health` 표시
 - Admin: `http://localhost:3002`
 

package/template/apps/api/src/app.controller.ts

@@ -1,14 +1,17 @@
 import { Controller, Get } from '@nestjs/common';
-import { Public } from '@xfilecom/backend-core';
+import { ControllerHelpers, Public } from '@xfilecom/backend-core';
 import { AppService } from './app.service';
 
 @Controller()
 export class AppController {
-  constructor(private readonly appService: AppService) {}
+  constructor(
+    private readonly appService: AppService,
+    private readonly controllerHelpers: ControllerHelpers,
+  ) {}
 
   @Public()
   @Get('health')
   health() {
-    return this.appService.getHealth();
+    return this.controllerHelpers.success(this.appService.getHealth());
   }
 }

package/template/apps/api/src/app.module.ts

@@ -3,6 +3,8 @@ import { CoreModule, type CoreModuleOptions } from '@xfilecom/backend-core';
 import { appConfig } from './config.loader';
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
+import { SqlQueryController } from './sql-query/sql-query.controller';
+import { SqlQueryService } from './sql-query/sql-query.service';
 import { schema } from '../../../shared/schema';
 
 function coreOptionsFromYaml(): CoreModuleOptions {
@@ -20,7 +22,7 @@ function coreOptionsFromYaml(): CoreModuleOptions {
 
 @Module({
   imports: [CoreModule.forHttpApi(coreOptionsFromYaml())],
-  controllers: [AppController],
-  providers: [AppService],
+  controllers: [AppController, SqlQueryController],
+  providers: [AppService, SqlQueryService],
 })
 export class AppModule {}

package/template/apps/api/src/app.service.ts

@@ -1,15 +1,14 @@
 import { Injectable, Optional } from '@nestjs/common';
-import { sql } from 'drizzle-orm';
 import { DatabaseService } from '@xfilecom/backend-core';
-import { appMeta } from '../../../shared/schema';
 
 /**
  * DB 사용은 backend-core 에서 두 가지가 있습니다.
  *
- * 1. **DatabaseService** — `this.database.db` 로 Drizzle API 직접 (아래 `getHealth` 가 이 방식).
- * 2. **DatabaseQuery** — `findOne` / `count` / `select` 등 헬퍼. 예: `await dbQuery.count('appMeta')`.
+ * 1. **DatabaseService** — `this.database.db` 로 Drizzle API 직접.
+ * 2. **DatabaseQuery** — `findOne` / `count` / `select` 등 헬퍼.
  *
- * `docs/DATABASE.md` §3 참고.
+ * `GET /health` 는 특정 테이블을 가정하지 않음 (`db:pull` 등으로 스키마가 바뀌어도 깨지지 않게).
+ * 도메인 쿼리는 별도 서비스에서 스키마 심볼·`DatabaseQuery` 로 작성하면 됨. → `docs/DATABASE.md` §3.
  */
 @Injectable()
 export class AppService {
@@ -20,48 +19,20 @@ export class AppService {
   }
 
   /**
-   * `GET /health` 용. `core.database.auto: false` 이면 DB 프로바이더가 없고 optional 로 비어 있음.
+   * `GET /health`. `core.database.auto: false` 이면 DB 모듈 미로드 → optional 미주입.
    */
-  async getHealth(): Promise<{
+  getHealth(): {
     ok: true;
     service: string;
-    database: {
-      moduleLoaded: boolean;
-      connected: boolean;
-      /** Drizzle 직접 `count(*)` — 동일 결과: `DatabaseQuery.count('appMeta')` */
-      rowCount?: number;
-      sampleTable?: string;
-    };
-  }> {
-    const sampleTable = 'appMeta';
+    database: { moduleLoaded: boolean; connected: boolean };
+  } {
     const service = this.serviceLabel();
     const moduleLoaded = this.database !== undefined;
-    if (!moduleLoaded || !this.database.isConnected()) {
-      return {
-        ok: true,
-        service,
-        database: { moduleLoaded, connected: false, sampleTable },
-      };
-    }
-    let rowCount: number | undefined;
-    try {
-      const db = this.database.db;
-      const [row] = await db
-        .select({ c: sql<number>`count(*)` })
-        .from(appMeta);
-      rowCount = Number(row?.c ?? 0);
-    } catch {
-      rowCount = undefined;
-    }
+    const connected = moduleLoaded && this.database.isConnected();
     return {
       ok: true,
       service,
-      database: {
-        moduleLoaded,
-        connected: true,
-        rowCount,
-        sampleTable,
-      },
+      database: { moduleLoaded, connected },
     };
   }
 }

package/template/apps/api/src/config.loader.ts

@@ -70,5 +70,7 @@ export type AppConfigShape = {
     filters?: { exception?: boolean | Record<string, unknown> };
     guards?: { jwt?: boolean };
     jwt?: { secret?: string; expiresIn?: string };
+    /** true: GET/POST sql-query 라우트 (endpointSqlQueries·pageable·/api/database) — 운영 비권장 */
+    sqlEndpoint?: { enabled?: boolean };
   };
 };

package/template/apps/api/src/sql-query/sql-query.controller.ts

@@ -0,0 +1,62 @@
+import {
+  Body,
+  Controller,
+  Get,
+  NotFoundException,
+  Param,
+  Post,
+} from '@nestjs/common';
+import { ControllerHelpers, Public } from '@xfilecom/backend-core';
+import { appConfig } from '../config.loader';
+import type { SqlDatabaseListPostBody, SqlListPostBody } from '../../../../shared/sql/sql';
+import { SqlQueryService } from './sql-query.service';
+
+/**
+ * - GET `/api/:resource/:action` → `endpointSqlQueries` 정적 SQL
+ * - POST `/api/database` + `{ table, action?, page?, sort?, search? }` → MySQL 테이블명 기준 목록
+ * - POST `/api/:resource/list` + JSON 본문 → 스키마 export 이름 기준 목록
+ */
+@Controller('api')
+export class SqlQueryController {
+  constructor(
+    private readonly sqlQuery: SqlQueryService,
+    private readonly controllerHelpers: ControllerHelpers,
+  ) {}
+
+  @Public()
+  @Post('database')
+  async runDatabase(@Body() body: SqlDatabaseListPostBody) {
+    if (!appConfig.core?.sqlEndpoint?.enabled) {
+      throw new NotFoundException();
+    }
+    const result = await this.sqlQuery.runDatabaseList(body);
+    return this.controllerHelpers.success(result);
+  }
+
+  @Public()
+  @Get(':resource/:action')
+  async runGet(
+    @Param('resource') resource: string,
+    @Param('action') action: string,
+  ) {
+    if (!appConfig.core?.sqlEndpoint?.enabled) {
+      throw new NotFoundException();
+    }
+    const rows = await this.sqlQuery.run(resource, action);
+    return this.controllerHelpers.success(rows);
+  }
+
+  @Public()
+  @Post(':resource/:action')
+  async runPost(
+    @Param('resource') resource: string,
+    @Param('action') action: string,
+    @Body() body: SqlListPostBody,
+  ) {
+    if (!appConfig.core?.sqlEndpoint?.enabled) {
+      throw new NotFoundException();
+    }
+    const result = await this.sqlQuery.runDynamic(resource, action, body ?? {});
+    return this.controllerHelpers.success(result);
+  }
+}

package/template/apps/api/src/sql-query/sql-query.service.ts

@@ -0,0 +1,236 @@
+import {
+  BadRequestException,
+  Injectable,
+  Optional,
+  ServiceUnavailableException,
+} from '@nestjs/common';
+import { DatabaseService } from '@xfilecom/backend-core';
+import type { MySqlTable } from 'drizzle-orm/mysql-core';
+import type { RowDataPacket } from 'mysql2';
+import {
+  listPageableColumnNames,
+  pageableFromClause,
+  pickDefaultSortColumn,
+} from '../../../../shared/sql/pageable-drizzle';
+import {
+  getPageableResourceKeyByMysqlTableName,
+  getPageableTable,
+  getPageableTableByMysqlTableName,
+  PAGEABLE_RESOURCE_OPTIONS,
+} from '../../../../shared/sql/pageable-tables';
+import {
+  escapeLikePattern,
+  isSafeSqlIdentifier,
+  PAGEABLE_LIST_DEFAULTS,
+  resolveEndpointSqlQuery,
+  type SqlDatabaseListPostBody,
+  type SqlListPostBody,
+} from '../../../../shared/sql/sql';
+
+@Injectable()
+export class SqlQueryService {
+  constructor(@Optional() private readonly database?: DatabaseService) {}
+
+  private pool() {
+    if (!this.database?.isConnected() || !this.database.mysql) {
+      throw new ServiceUnavailableException(
+        '데이터베이스에 연결되어 있지 않습니다. core.database.auto 와 application.yml database.* 를 확인하세요.',
+      );
+    }
+    return this.database.mysql;
+  }
+
+  async run(resource: string, action: string): Promise<unknown> {
+    const resolved = resolveEndpointSqlQuery(resource, action);
+    if ('missing' in resolved) {
+      throw new BadRequestException(
+        `SQL 이 등록되어 있지 않습니다. shared/sql/sql.ts 의 endpointSqlQueries 에 ` +
+          `'${resource}.${action}' 에 해당하는 문자열 쿼리를 추가하세요. ` +
+          `(예: endpointSqlQueries.${resource} = { ${action}: 'SELECT ...' })`,
+      );
+    }
+
+    const [rows] = await this.pool().query(resolved.sql);
+    return rows;
+  }
+
+  /**
+   * `POST /api/database` — 본문 `table` 은 MySQL 실제 테이블명 (`app_meta`, `users` 등).
+   */
+  async runDatabaseList(body: SqlDatabaseListPostBody): Promise<{
+    rows: unknown;
+    pagination: {
+      total: number;
+      page: number;
+      limit: number;
+      totalPages: number;
+      pageRequested?: number;
+    };
+  }> {
+    const action = String(body.action ?? 'list').trim();
+    if (action !== 'list') {
+      throw new BadRequestException(
+        `동적 POST 는 action=list 만 지원합니다. (본문 action 생략 시 list)`,
+      );
+    }
+
+    const raw = String(body.table ?? '').trim();
+    if (!raw || !isSafeSqlIdentifier(raw)) {
+      throw new BadRequestException(
+        `유효한 table 이 필요합니다. MySQL 테이블명(식별자)만 허용합니다. 예: { "table": "users", "action": "list" }`,
+      );
+    }
+
+    const table = getPageableTableByMysqlTableName(raw);
+    if (!table) {
+      throw new BadRequestException(
+        `table '${raw}' 은 pageable 스키마에 없거나 허용되지 않습니다. Drizzle 스키마·PAGEABLE_SCHEMA_EXPORT_DENYLIST 를 확인하세요.`,
+      );
+    }
+
+    const resourceKey = getPageableResourceKeyByMysqlTableName(raw);
+    if (!resourceKey) {
+      throw new BadRequestException(`table '${raw}' 에 대한 리소스 키를 찾을 수 없습니다.`);
+    }
+
+    return this.runListForPageableTable(table, resourceKey, body);
+  }
+
+  /**
+   * `POST .../:resource/list` — `resource` 는 스키마 export 이름.
+   */
+  async runDynamic(
+    resource: string,
+    action: string,
+    body: SqlListPostBody,
+  ): Promise<{
+    rows: unknown;
+    pagination: {
+      total: number;
+      page: number;
+      limit: number;
+      totalPages: number;
+      pageRequested?: number;
+    };
+  }> {
+    if (action !== 'list') {
+      throw new BadRequestException(
+        `동적 POST 는 action=list 만 지원합니다. resource 는 shared/schema 의 Drizzle 테이블 export 이름과 같아야 합니다.`,
+      );
+    }
+
+    const table = getPageableTable(resource);
+    if (!table) {
+      throw new BadRequestException(
+        `resource '${resource}' 에 해당하는 Drizzle 테이블 export 가 없습니다. shared/schema/schema.ts 에 ` +
+          `\`export const ${resource} = mysqlTable(...)\` 가 있는지, PAGEABLE_SCHEMA_EXPORT_DENYLIST 에 막혀 있지 않은지 확인하세요.`,
+      );
+    }
+
+    return this.runListForPageableTable(table, resource, body);
+  }
+
+  private async runListForPageableTable(
+    table: MySqlTable,
+    resourceKeyForOptions: string,
+    body: SqlListPostBody,
+  ): Promise<{
+    rows: unknown;
+    pagination: {
+      total: number;
+      page: number;
+      limit: number;
+      totalPages: number;
+      pageRequested?: number;
+    };
+  }> {
+    const allowed = listPageableColumnNames(table);
+    if (allowed.length === 0) {
+      throw new BadRequestException(
+        `테이블에 사용 가능한 컬럼이 없습니다. 스키마·블록리스트를 확인하세요.`,
+      );
+    }
+
+    const ro = PAGEABLE_RESOURCE_OPTIONS[resourceKeyForOptions] ?? {};
+    const maxLimit = ro.maxLimit ?? PAGEABLE_LIST_DEFAULTS.maxLimit;
+    const defaultLimit = ro.defaultLimit ?? PAGEABLE_LIST_DEFAULTS.defaultLimit;
+    const defaultSortOrder = ro.defaultSortOrder ?? PAGEABLE_LIST_DEFAULTS.defaultSortOrder;
+
+    const pageRequested = Math.max(1, Math.floor(Number(body.page?.page) || 1));
+    const limitRaw = Math.floor(Number(body.page?.limit) || defaultLimit);
+    const limit = Math.min(maxLimit, Math.max(1, limitRaw));
+
+    const defaultSortField = pickDefaultSortColumn(allowed);
+    const sortFieldRaw = body.sort?.field?.trim();
+    const sortField =
+      sortFieldRaw &&
+      allowed.includes(sortFieldRaw) &&
+      isSafeSqlIdentifier(sortFieldRaw)
+        ? sortFieldRaw
+        : defaultSortField;
+    if (!isSafeSqlIdentifier(sortField) || !allowed.includes(sortField)) {
+      throw new BadRequestException(`유효하지 않은 기본 정렬 컬럼: ${defaultSortField}`);
+    }
+
+    const orderRaw = body.sort?.order?.toLowerCase();
+    const sortDir =
+      orderRaw === 'asc' || orderRaw === 'desc' ? orderRaw : defaultSortOrder;
+
+    const term = String(body.search?.term ?? '').trim();
+    const requestedFields = Array.isArray(body.search?.fields) ? body.search!.fields! : [];
+    const searchFields = requestedFields.filter(
+      (f) => typeof f === 'string' && isSafeSqlIdentifier(f) && allowed.includes(f),
+    );
+
+    const fromClause = pageableFromClause(table);
+    const whereParts: string[] = ['1=1'];
+    const params: unknown[] = [];
+
+    if (term.length > 0 && searchFields.length > 0) {
+      const likes = searchFields.map((f) => `\`${f}\` LIKE ?`);
+      whereParts.push(`(${likes.join(' OR ')})`);
+      const likeVal = `%${escapeLikePattern(term)}%`;
+      searchFields.forEach(() => params.push(likeVal));
+    }
+
+    const whereSql = `WHERE ${whereParts.join(' AND ')}`;
+    const countSql = `SELECT COUNT(*) AS __cnt ${fromClause} ${whereSql}`;
+    const dataSql =
+      `SELECT * ${fromClause} ${whereSql} ` +
+      `ORDER BY \`${sortField}\` ${sortDir.toUpperCase()} LIMIT ? OFFSET ?`;
+
+    const pool = this.pool();
+    const [countRows] = await pool.query<RowDataPacket[]>(countSql, params);
+    const total = Number((countRows[0] as { __cnt?: number })?.__cnt ?? 0);
+
+    const totalPages = limit > 0 ? Math.ceil(total / limit) : 0;
+    let page = pageRequested;
+    if (totalPages > 0) {
+      page = Math.max(1, Math.min(pageRequested, totalPages));
+    } else {
+      page = 1;
+    }
+    const offset = (page - 1) * limit;
+
+    const dataParams = [...params, limit, offset];
+    const [rows] = await pool.query(dataSql, dataParams);
+
+    const pagination: {
+      total: number;
+      page: number;
+      limit: number;
+      totalPages: number;
+      pageRequested?: number;
+    } = {
+      total,
+      page,
+      limit,
+      totalPages,
+    };
+    if (page !== pageRequested) {
+      pagination.pageRequested = pageRequested;
+    }
+
+    return { rows, pagination };
+  }
+}

package/template/apps/api/tsconfig.build.json

@@ -3,6 +3,10 @@
   "compilerOptions": {
     "rootDir": "../../"
   },
-  "include": ["src/**/*", "../../shared/schema/**/*.ts"],
+  "include": [
+    "src/**/*",
+    "../../shared/schema/**/*.ts",
+    "../../shared/sql/**/*.ts"
+  ],
   "exclude": ["node_modules", "dist", "**/*spec.ts"]
 }

package/template/docs/DATABASE.md

@@ -32,7 +32,7 @@ xframe 프로젝트는 **`@xfilecom/backend-core`** 가 MySQL 풀과 Drizzle 인
 | **타입** | 스키마 심볼 import (`appMeta` 등) — 권장 | 테이블 키는 문자열 (`'appMeta'`) |
 | **언제** | 복잡한 조인·raw·Drizzle 문서 그대로 | 단순 CRUD·페이지네이션·object `where` |
 
-스캐폴드 **`apps/api/src/app.service.ts`** 는 `GET /health` 에 **`DatabaseService.db` + Drizzle** 로 `app_meta` 행 수를 구합니다. 같은 값은 **`DatabaseQuery.count('appMeta')`** 로도 얻을 수 있습니다 (`@Optional()` 로 DB 꺼짐 대응은 동일).
+스캐폴드 **`apps/api/src/app.service.ts`** 의 `GET /health` 는 **DB 모듈 로드 여부·연결 여부**만 돌려주며, 어떤 테이블도 가정하지 않습니다. 실제 쿼리는 아래 패턴으로 별도 서비스를 두면 됩니다.
 
 ### A. Drizzle API 직접 (`DatabaseService.db`)
 
@@ -98,6 +98,11 @@ export class AppModule {}
 
 `DatabaseModule` 을 다시 import 할 필요는 없습니다.
 
+## 공통 응답 (`CommonResponseDto`)
+
+`CoreModule.forHttpApi` 는 기본으로 **`ResponseTransformInterceptor`** 를 켜서, 컨트롤러가 객체만 반환해도 `{ code, data, meta?, error }` 형태로 감쌉니다.  
+그래도 **`ControllerHelpers.success(payload)`** 로 `CommonResponseDto` 를 직접 반환하는 편이 의도가 분명합니다. `CoreModule` 이 `@Global()` 이라 **`ControllerHelpers` 는 주입만 하면 됩니다** — `apps/api/src/app.controller.ts` 의 `GET /health` 가 그 패턴입니다.
+
 ## 5. Drizzle Kit (루트에서 실행)
 
 프로젝트 **루트**에서 스크립트를 실행합니다 (`process.cwd()` 가 루트여야 `drizzle.env.ts` 가 YAML 을 찾습니다).
@@ -115,3 +120,19 @@ export class AppModule {}
 ## 6. 연결 실패 시
 
 `DatabaseService` 는 연결에 실패해도 **애플리케이션 기동은 계속**하고 경고만 남깁니다. DB 가 필요한 핸들러에서는 `isConnected()` 확인 또는 try/catch 로 처리하세요.
+
+## 7. HTTP 로 정적·동적 조회 (`core.sqlEndpoint.enabled`)
+
+`apps/api/src/sql-query/` — **`core.sqlEndpoint.enabled: true`** 이고 **`core.database.auto: true`** 일 때만 라우트가 살아 있습니다.
+
+| 메서드·경로 | 출처 | 설명 |
+|-------------|------|------|
+| `GET /api/:resource/:action` | `shared/sql/sql.ts` 의 `endpointSqlQueries` | 등록된 SQL 문자열만 실행 |
+| `POST /api/:resource/list` | `pageable-tables.ts` + Drizzle | URL `resource` = 스키마 **export 이름**. 스키마의 테이블 `export` 를 `isTable` 로 모아 자동 허용 |
+| `POST /api/database` | 동일 | 본문 `table` = MySQL **물리 테이블명** (`mysqlTable('app_meta', …)` 첫 인자) |
+
+- 컬럼 정렬·LIKE 검색 허용 범위: `shared/sql/pageable-drizzle.ts` + `PAGEABLE_COLUMN_BLOCKLIST_SUBSTRINGS` (`sql.ts`).
+- 테이블 노출 제외: `PAGEABLE_SCHEMA_EXPORT_DENYLIST` (`pageable-tables.ts`).
+- 페이지 한도 등: `PAGEABLE_RESOURCE_OPTIONS` / `PAGEABLE_LIST_DEFAULTS`.
+
+자세한 curl·주의사항은 **`shared/sql/README.md`** 를 참고하세요.

package/template/shared/README.md

@@ -7,7 +7,7 @@
 | **`config/api`** | Nest API YAML (`application.yml`, `application-<env>.yml`) |
 | **`config/web/client`**, **`config/web/admin`** | 각 Vite 앱별 YAML (`VITE_API_BASE_URL`, `VITE_APP_TITLE` 등 주입) |
 | **`schema/`** | Drizzle 등 DB 스키마(TS). `apps/api`의 `tsconfig.build.json`에 경로를 포함하거나, 스키마만 `apps/api/src/database`에 두고 여기서 re-export 하는 식으로 맞추면 됩니다. Nest 에서의 주입·쿼리 패턴은 루트 **[docs/DATABASE.md](../docs/DATABASE.md)** 참고. |
-| **`sql/`** | 마이그레이션·시드·원시 SQL (`drizzle-kit`, 수동 스크립트 등) |
+| **`sql/`** | 마이그레이션·시드·원시 SQL; **`sql/sql.ts`** (`databaseSqlManifest`) 로 경로·절차 메타 정리 |
 | **`endpoint/`** | HTTP 계약(OpenAPI yaml, 공유 DTO 타입, 라우트 메타) — 제품에 맞게 확장 |
 
 `apps/api/src/config.loader.ts`는 **`shared/config/api`** 를 읽습니다.  

package/template/shared/config/api/application.yml

@@ -31,8 +31,13 @@ cors:
   origin: true
 
 core:
+  # true: GET /api/:resource/:action → sql.ts 의 endpointSqlQueries
+  #      POST /api/:resource/list, POST /api/database → pageable 목록 (Drizzle 스키마·컬럼 화이트리스트)
+  # 운영·공개망에서는 false 권장 (임의 SQL·대량 조회 노출 방지). 로컬 개발만 true.
+  sqlEndpoint:
+    enabled: false
   database:
-    # true 시 부팅 시 MySQL 연결 시도, DatabaseService 가 성공/실패 로그 출력
+    # true 시 부팅 시 MySQL 연결 시도, DatabaseService 가 성공/실패 로그 출력 (위 엔드포인트에 필요)
     auto: true
   interceptors:
     logging: true

package/template/shared/schema/README.md

@@ -1,7 +1,7 @@
 # Schema
 
 - Drizzle `schema.ts` / 테이블 정의를 여기 두고, `apps/api`에서 import 해 `CoreModule`의 `database: { auto: true, schema }`에 넘깁니다.
-- `index.ts`는 `export const schema` 로 테이블을 묶습니다. `npm run db:pull`(역추출) 후 `relations.ts`가 생기면 Drizzle 문서에 맞게 `schema` export를 정리하세요.
+- `index.ts`는 `export const schema` 로 테이블을 묶고 `export * from './schema'` 로 re-export 합니다. `shared/sql/pageable-tables.ts` 가 **`import * from '../schema'`** 로 이 엔트리를 읽어 `POST /api/.../list`·`POST /api/database` 허용 테이블을 자동 수집합니다. `npm run db:pull` 후 `relations.ts`가 생기면 Drizzle 문서에 맞게 `index.ts`를 정리하세요.
 - Nest 기본 빌드는 `apps/api/src`만 컴파일하므로, `shared/schema`에 TS를 두면 **`apps/api/tsconfig.build.json`의 `include`** 에 `../../shared/schema/**/*.ts` 를 추가하거나, 스키마를 `apps/api/src/database/schema`에 두고 이 폴더는 문서·SQL 덤프용으로만 써도 됩니다.
 
 ## `DatabaseQuery` 와 테이블 이름

package/template/shared/sql/README.md

@@ -1,6 +1,48 @@
 # SQL
 
-- Drizzle Kit 마이그레이션 출력(`drizzle.config.ts` 의 `out`)은 `migrations/` 아래입니다.
-- **처음에는 `migrations/` 를 만들지 않아도 됩니다.** 첫 `npm run db:generate` 가 `migrations/`·`meta/_journal.json`·snapshot·`.sql` 을 한꺼번에 만듭니다.
-- 주의: **빈 `meta/` 만 두고 `_journal.json` 만 없애면** Kit이 저널을 다시 쓰지 않아 `generate` 가 깨질 수 있으니, 깔끔히 비울 때는 `migrations/` 전체를 지우세요.
-- 시드·리포트용 `.sql`도 이 트리에 둘 수 있습니다.
+- **`sql.ts`** — 마이그레이션 경로·npm 스크립트 이름·시드 순서·운영 체크리스트 등을 JSON에 가깝게 모아 둔 메타.
+
+## `sql.ts` 사용법
+
+1. **역할**  
+   `databaseSqlManifest` 등은 Nest가 자동으로 읽지 **않습니다**. 스크립트·CI·문서용입니다. **SQL HTTP 엔드포인트**는 `endpointSqlQueries`·`SqlQueryService` 가 런타임에 사용합니다.
+
+2. **TypeScript에서 import**
+
+   ```ts
+   import { databaseSqlManifest, type DatabaseSqlManifest } from './shared/sql/sql';
+   ```
+
+3. **JSON 덤프**
+
+   ```bash
+   npx tsx -e "import { databaseSqlManifest } from './shared/sql/sql.ts'; console.log(JSON.stringify(databaseSqlManifest, null, 2))"
+   ```
+
+4. **시드** — `shared/sql/seeds/` 와 `databaseSqlManifest.seeds.order` 를 팀 스크립트가 읽어 실행.
+
+5. **`drizzle.config.ts`** 변경 시 `sql.ts` 의 `drizzleKit` 도 동기화.
+
+## REST `GET /api/:resource/:action` (`endpointSqlQueries`)
+
+- `core.sqlEndpoint.enabled: true` 일 때만 동작. **템플릿 기본은 `false`** (운영·공개망에서는 끄는 것을 권장). 로컬에서 동적 조회를 쓰려면 `true` 로 켜고 `core.database.auto: true` 와 `database.*` 를 맞춥니다.
+
+## REST `POST /api/:resource/list` — Drizzle 스키마 자동 연동
+
+- URL `resource` = **`shared/schema` 의 테이블 `export` 이름** (`export const appMeta` → `/api/appMeta/list`).
+- `pageable-tables.ts` 가 `import *` 로 **`../schema`(index)** 를 읽고 `isTable` 로 테이블만 수집합니다. `npm run db:pull` 로 테이블이 늘어도 맵을 수동 편집할 필요 없습니다.
+- 내부 전용 테이블은 `PAGEABLE_SCHEMA_EXPORT_DENYLIST` 에 export 이름 추가.
+- 컬럼·페이지·검색 규칙은 example 의 `shared/sql/README.md` 와 동일합니다.
+
+## REST `POST /api/database`
+
+- 본문에 **`table`** (MySQL 물리 테이블명, 예: `app_meta`, `users`), 선택 **`action`** (생략 시 `list`).
+- 허용 테이블은 Drizzle 스키마에 있고 denylist 가 아닌 것만.
+
+```bash
+curl -sS -X POST 'http://localhost:3000/api/database' \
+  -H 'Content-Type: application/json' \
+  -d '{"table":"app_meta","page":{"limit":10}}'
+```
+
+- 마이그레이션 산출물은 `shared/sql/migrations/` 아래입니다.

package/template/shared/sql/pageable-drizzle.ts

@@ -0,0 +1,28 @@
+import { getTableConfig } from 'drizzle-orm/mysql-core';
+import type { MySqlTable } from 'drizzle-orm/mysql-core';
+import { isSafeSqlIdentifier, PAGEABLE_COLUMN_BLOCKLIST_SUBSTRINGS } from './sql';
+
+/** Drizzle 테이블에서 정렬·검색 허용 컬럼(DB 이름). 블록리스트·식별자 안전 규칙 적용. */
+export function listPageableColumnNames(table: MySqlTable): string[] {
+  const cfg = getTableConfig(table);
+  return cfg.columns
+    .map((c) => c.name)
+    .filter((n) => isSafeSqlIdentifier(n))
+    .filter(
+      (n) =>
+        !PAGEABLE_COLUMN_BLOCKLIST_SUBSTRINGS.some((s) =>
+          n.toLowerCase().includes(s),
+        ),
+    );
+}
+
+export function pickDefaultSortColumn(allowed: string[]): string {
+  if (allowed.includes('id')) return 'id';
+  return allowed[0] ?? 'id';
+}
+
+/** `FROM \`table_name\`` — 스키마 접두사는 Drizzle 설정 따름 */
+export function pageableFromClause(table: MySqlTable): string {
+  const name = getTableConfig(table).name.replace(/`/g, '');
+  return `FROM \`${name}\``;
+}

package/template/shared/sql/pageable-tables.ts

@@ -0,0 +1,74 @@
+import { isTable } from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/mysql-core';
+import type { MySqlTable } from 'drizzle-orm/mysql-core';
+/** `db:pull` 후에도 `index.ts` 가 스키마를 모아 re-export 하므로 엔트리는 여기서 통일 */
+import * as schemaModule from '../schema';
+import { isSafeSqlIdentifier } from './sql';
+
+/**
+ * `shared/schema/index.ts` → `./schema` 의 **export 이름**이 API `resource` 가 됩니다.
+ * 예: `export const users` → `POST /api/users/list`
+ *
+ * `npm run db:pull` 후에도 `index.ts` 가 테이블을 re-export 하면 **맵 수동 편집 없이** 반영됩니다.
+ * 노출 금지 테이블은 `PAGEABLE_SCHEMA_EXPORT_DENYLIST` 에 export 이름을 넣으세요.
+ */
+export const PAGEABLE_SCHEMA_EXPORT_DENYLIST: ReadonlySet<string> = new Set([
+  // 예: 'internalAuditLog',
+]);
+
+function collectTablesFromSchema(): Record<string, MySqlTable> {
+  const out: Record<string, MySqlTable> = {};
+  for (const [name, value] of Object.entries(schemaModule)) {
+    if (PAGEABLE_SCHEMA_EXPORT_DENYLIST.has(name)) continue;
+    if (isTable(value)) {
+      out[name] = value as MySqlTable;
+    }
+  }
+  return out;
+}
+
+/** 런타임에 스키마 모듈에서 한 번 수집 */
+export const PAGEABLE_TABLE_BY_RESOURCE: Record<string, MySqlTable> =
+  collectTablesFromSchema();
+
+/** 리소스별 옵션 (선택, 키 = 스키마 export 이름) */
+export const PAGEABLE_RESOURCE_OPTIONS: Record<
+  string,
+  {
+    maxLimit?: number;
+    defaultLimit?: number;
+    defaultSortOrder?: 'asc' | 'desc';
+  }
+> = {
+  appMeta: { defaultLimit: 20 },
+};
+
+export function getPageableTable(resource: string): MySqlTable | undefined {
+  return PAGEABLE_TABLE_BY_RESOURCE[resource];
+}
+
+function mysqlNameOf(table: MySqlTable): string {
+  return getTableConfig(table).name.replace(/`/g, '');
+}
+
+export function getPageableTableByMysqlTableName(
+  mysqlTableName: string,
+): MySqlTable | undefined {
+  const normalized = mysqlTableName.replace(/`/g, '').trim();
+  if (!isSafeSqlIdentifier(normalized)) return undefined;
+  for (const table of Object.values(PAGEABLE_TABLE_BY_RESOURCE)) {
+    if (mysqlNameOf(table) === normalized) return table;
+  }
+  return undefined;
+}
+
+export function getPageableResourceKeyByMysqlTableName(
+  mysqlTableName: string,
+): string | undefined {
+  const normalized = mysqlTableName.replace(/`/g, '').trim();
+  if (!isSafeSqlIdentifier(normalized)) return undefined;
+  for (const [resourceKey, table] of Object.entries(PAGEABLE_TABLE_BY_RESOURCE)) {
+    if (mysqlNameOf(table) === normalized) return resourceKey;
+  }
+  return undefined;
+}

package/template/shared/sql/sql.ts

@@ -0,0 +1,140 @@
+/**
+ * DB·SQL 작업을 정리한 머신이 읽기 쉬운 JSON 형태 설정.
+ * 런타임 Nest와 직접 연결하지 않아도 되고, 스크립트·CI·문서 생성 시 참조용으로 쓸 수 있습니다.
+ *
+ * `JSON.stringify(databaseSqlManifest, null, 2)` 로 그대로 덤프 가능합니다.
+ */
+export const databaseSqlManifest = {
+  meta: {
+    kind: 'xframe.database.sql',
+    version: 1,
+    description:
+      'Drizzle Kit 마이그레이션·시드·운영 절차 메타. drizzle.config.ts 의 out/schema 경로와 맞출 것.',
+  },
+
+  drizzleKit: {
+    dialect: 'mysql',
+    schemaGlobs: ['./shared/schema/**/*.ts'],
+    migrationsDirectory: './shared/sql/migrations',
+    kitConfigFile: './drizzle.config.ts',
+    introspectConfigFile: './drizzle.introspect.config.ts',
+    journalRelativePath: './shared/sql/migrations/meta/_journal.json',
+  },
+
+  npmScripts: {
+    generate: 'db:generate',
+    push: 'db:push',
+    migrate: 'db:migrate',
+    studio: 'db:studio',
+    pull: 'db:pull',
+  },
+
+  /** 시드 SQL 실행 순서 (위에서 아래). 파일이 없으면 항목만 두고 enabled: false */
+  seeds: {
+    directory: './shared/sql/seeds',
+    order: [] as {
+      id: string;
+      file: string;
+      enabled: boolean;
+      note?: string;
+    }[],
+  },
+
+  /** 운영·로컬에서 DB 다룰 때 체크리스트 (자동 실행 아님) */
+  workflows: {
+    localDev: [
+      'application.yml database.* 와 실제 MySQL 일치 확인',
+      '스키마 변경 후 루트에서 npm run db:generate → 마이그레이션 검토',
+      '필요 시 npm run db:migrate 또는 개발 전용 db:push',
+    ],
+    deploy: [
+      '백업 후 npm run db:migrate',
+      '마이그레이션 실패 시 롤백·저널(shared/sql/migrations/meta) 상태 확인',
+    ],
+  },
+
+  safety: {
+    avoidPartialMigrationCleanup:
+      'migrations/meta/_journal.json 만 지우지 말 것 — migrations 폴더 단위로 정리',
+    production: {
+      preferMigrateOverPush: true,
+      neverRunPushOnProduction: true,
+    },
+  },
+} as const;
+
+export type DatabaseSqlManifest = typeof databaseSqlManifest;
+
+/**
+ * REST `GET /api/:resource/:action` 가 여기서 SQL 문자열을 찾아 실행합니다.
+ * 키는 객체 경로로 `resource` + `action` (예: users + findOne → users.findOne).
+ * 등록되지 않은 조합이면 API 는 `shared/sql/sql.ts` 에 추가하라는 오류를 돌려줍니다.
+ *
+ * 보안: 운영에서는 `core.sqlEndpoint.enabled: false` 로 끄세요. 임의 SQL 노출입니다.
+ */
+export const endpointSqlQueries = {
+  users: {
+    findOne: 'SELECT * FROM users LIMIT 1',
+  },
+  appMeta: {
+    findOne: 'SELECT * FROM app_meta LIMIT 1',
+  },
+} as const;
+
+export type EndpointSqlQueries = typeof endpointSqlQueries;
+
+export function resolveEndpointSqlQuery(
+  resource: string,
+  action: string,
+): { sql: string } | { missing: true } {
+  const root = endpointSqlQueries as Record<string, Record<string, string>>;
+  const bucket = root[resource];
+  if (!bucket) return { missing: true };
+  const sql = bucket[action];
+  if (typeof sql !== 'string' || !sql.trim()) return { missing: true };
+  return { sql: sql.trim() };
+}
+
+/**
+ * 프론트 POST 본문 — `POST /api/:resource/list`.
+ * 정렬·검색 컬럼은 Drizzle 스키마 + 블록리스트로 허용 범위가 정해짐 (`pageable-drizzle.ts`).
+ */
+export interface SqlListPostBody {
+  page?: { limit?: number; page?: number };
+  sort?: { field?: string; order?: 'asc' | 'desc' };
+  search?: { fields?: string[]; term?: string };
+}
+
+/**
+ * `POST /api/database` — MySQL 실제 테이블명(`mysqlTable('users', …)` 의 첫 인자).
+ * 스키마에 없거나 denylist 면 거절됨.
+ */
+export interface SqlDatabaseListPostBody extends SqlListPostBody {
+  table: string;
+  /** 생략 시 `list` */
+  action?: string;
+}
+
+/** 컬럼명(소문자)에 부분 일치하면 정렬·LIKE 검색 제외 */
+export const PAGEABLE_COLUMN_BLOCKLIST_SUBSTRINGS = [
+  'password',
+  'secret',
+  'token',
+  'hash',
+] as const;
+
+export const PAGEABLE_LIST_DEFAULTS = {
+  maxLimit: 100,
+  defaultLimit: 10,
+  defaultSortOrder: 'desc' as const,
+};
+
+/** SQL 식별자(컬럼명) — 화이트리스트 통과 후에도 한 번 더 검증 */
+export function isSafeSqlIdentifier(name: string): boolean {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name);
+}
+
+/** LIKE 패턴용: % _ \ 이스케이프 */
+export function escapeLikePattern(term: string): string {
+  return term.replace(/[\\%_]/g, '\\$&');
+}

package/template/web/shared/src/types/api.ts

@@ -12,7 +12,5 @@ export type HealthData = {
   database?: {
     moduleLoaded: boolean;
     connected: boolean;
-    rowCount?: number;
-    sampleTable?: string;
   };
 };

package/template/.env.example

@@ -1,6 +0,0 @@
-# Nest API·Drizzle 부트스트랩은 루트 .env 를 읽지 않음. DB 등은 `shared/config/api/application*.yml` 기준.
-# 기본 CONFIG_SOURCE=yaml → 셸에서 export 한 DB_* 로 YAML 이 바뀌지 않음. 덮어쓰기: CONFIG_SOURCE=yamlWithEnvOverrides
-#
-# (선택) 로컬 도구용으로만 .env 를 쓸 경우 — 앱/ drizzle-kit 은 자동 로드하지 않음.
-#
-# 접속 오류 시: GUI 와 동일한 host·user·password·database 이름을 YAML 에 맞출 것.