@xfilecom/xframe 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "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`
+- API: `http://localhost:3000` — `GET /health` (`AppService`: DB 로드·연결 여부만; 쿼리 패턴은 `docs/DATABASE.md`)
 - Client: `http://localhost:3001` — `CommonResponse` 형태로 `/health` 표시
 - Admin: `http://localhost:3002`
 
@@ -28,6 +28,10 @@ Nest API (`@xfilecom/backend-core`) + Vite/React client·admin (`@xfilecom/front
 
 자세한 설명은 `shared/README.md` 참고.
 
+## Database (MySQL + Drizzle)
+
+설정 흐름, `DatabaseService` / `DatabaseQuery` 주입, Drizzle Kit 스크립트는 **[docs/DATABASE.md](./docs/DATABASE.md)** 를 보면 됩니다.
+
 ## GitLab `~/.npmrc` 와 충돌 시
 
 프로젝트 루트 `.npmrc`의 `@xfilecom:registry`가 npm 공개 레지스트리를 가리키므로, `@xfilecom/*` 설치는 여기서 우선합니다.

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

@@ -1,11 +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,
+    private readonly controllerHelpers: ControllerHelpers,
+  ) {}
+
   @Public()
   @Get('health')
   health() {
-    return { ok: true, service: '__SERVICE_LABEL__' };
+    return this.controllerHelpers.success(this.appService.getHealth());
   }
 }

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

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { CoreModule, type CoreModuleOptions } from '@xfilecom/backend-core';
 import { appConfig } from './config.loader';
 import { AppController } from './app.controller';
+import { AppService } from './app.service';
 import { schema } from '../../../shared/schema';
 
 function coreOptionsFromYaml(): CoreModuleOptions {
@@ -20,5 +21,6 @@ function coreOptionsFromYaml(): CoreModuleOptions {
 @Module({
   imports: [CoreModule.forHttpApi(coreOptionsFromYaml())],
   controllers: [AppController],
+  providers: [AppService],
 })
 export class AppModule {}

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

@@ -0,0 +1,38 @@
+import { Injectable, Optional } from '@nestjs/common';
+import { DatabaseService } from '@xfilecom/backend-core';
+
+/**
+ * DB 사용은 backend-core 에서 두 가지가 있습니다.
+ *
+ * 1. **DatabaseService** — `this.database.db` 로 Drizzle API 직접.
+ * 2. **DatabaseQuery** — `findOne` / `count` / `select` 등 헬퍼.
+ *
+ * `GET /health` 는 특정 테이블을 가정하지 않음 (`db:pull` 등으로 스키마가 바뀌어도 깨지지 않게).
+ * 도메인 쿼리는 별도 서비스에서 스키마 심볼·`DatabaseQuery` 로 작성하면 됨. → `docs/DATABASE.md` §3.
+ */
+@Injectable()
+export class AppService {
+  constructor(@Optional() private readonly database?: DatabaseService) {}
+
+  serviceLabel(): string {
+    return '__SERVICE_LABEL__';
+  }
+
+  /**
+   * `GET /health`. `core.database.auto: false` 이면 DB 모듈 미로드 → optional 미주입.
+   */
+  getHealth(): {
+    ok: true;
+    service: string;
+    database: { moduleLoaded: boolean; connected: boolean };
+  } {
+    const service = this.serviceLabel();
+    const moduleLoaded = this.database !== undefined;
+    const connected = moduleLoaded && this.database.isConnected();
+    return {
+      ok: true,
+      service,
+      database: { moduleLoaded, connected },
+    };
+  }
+}

package/template/docs/DATABASE.md

@@ -0,0 +1,122 @@
+# Database (MySQL + Drizzle)
+
+xframe 프로젝트는 **`@xfilecom/backend-core`** 가 MySQL 풀과 Drizzle 인스턴스를 붙이고, **`shared/schema`** 의 테이블 정의를 넘깁니다.
+
+## 1. 설정
+
+| 단계 | 위치 |
+|------|------|
+| 연결 정보 | `shared/config/api/application.yml` 의 `database.*` |
+| 로드 | `apps/api/src/config.loader.ts` → `loadApplicationYamlSync` + `syncEnvKeys` 로 `DB_*` 동기화 |
+| 켜기/끄기 | 같은 YAML 의 `core.database.auto` (`true` 이면 부팅 시 연결 시도) |
+
+`CONFIG_SOURCE` 기본값은 `yaml` 입니다. 배포에서 프로세스 환경변수로 YAML 을 덮어쓰려면 `yamlWithEnvOverrides` 를 쓰면 됩니다.
+
+## 2. 스키마
+
+- 테이블은 `shared/schema/schema.ts` (등)에 `drizzle-orm/mysql-core` 로 정의합니다.
+- `shared/schema/index.ts` 에서 `export const schema = …` 로 **객체 하나**로 묶어 `app.module.ts` 의 `CoreModule` 에 넘깁니다.
+- Nest 빌드는 `apps/api/tsconfig.build.json` 에 `../../shared/schema/**/*.ts` 가 포함되어 있습니다.
+
+`DatabaseQuery` 에 넘기는 **테이블 이름 문자열**은 DB 테이블명이 아니라, **`schema` 객체의 프로퍼티 이름**과 같아야 합니다.  
+예: `export const appMeta = mysqlTable('app_meta', …)` 이면 문자열은 `'appMeta'` 입니다.
+
+## 3. Nest 에서 쓰는 두 가지 방식
+
+`CoreModule` 이 DB 를 켠 상태면 **`DatabaseService`** 와 **`DatabaseQuery`** 를 어디서든 주입할 수 있습니다 (`@Global()`). 둘 중 하나만 써도 되고, 같이 주입해도 됩니다.
+
+| | **`DatabaseService`** | **`DatabaseQuery`** |
+|---|------------------------|---------------------|
+| **역할** | 풀 + Drizzle 인스턴스 (`get db()`) | 문자열 테이블 키 기준 CRUD 헬퍼 |
+| **쿼리** | `drizzle-orm` API 직접 (`select`, `eq`, `sql` …) | `findOne`, `select`, `insert`, `count` … |
+| **타입** | 스키마 심볼 import (`appMeta` 등) — 권장 | 테이블 키는 문자열 (`'appMeta'`) |
+| **언제** | 복잡한 조인·raw·Drizzle 문서 그대로 | 단순 CRUD·페이지네이션·object `where` |
+
+스캐폴드 **`apps/api/src/app.service.ts`** 의 `GET /health` 는 **DB 모듈 로드 여부·연결 여부**만 돌려주며, 어떤 테이블도 가정하지 않습니다. 실제 쿼리는 아래 패턴으로 별도 서비스를 두면 됩니다.
+
+### A. Drizzle API 직접 (`DatabaseService.db`)
+
+타입 안전하게 쓰려면 스키마에서 테이블을 import 합니다.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { eq } from 'drizzle-orm';
+import { DatabaseService } from '@xfilecom/backend-core';
+import { appMeta } from '../../../shared/schema';
+
+@Injectable()
+export class MetaService {
+  constructor(private readonly database: DatabaseService) {}
+
+  async getValue(key: string) {
+    const db = this.database.db;
+    const [row] = await db
+      .select()
+      .from(appMeta)
+      .where(eq(appMeta.key, key))
+      .limit(1);
+    return row?.value ?? null;
+  }
+}
+```
+
+연결이 안 된 상태에서 `this.database.db` 를 쓰면 예외가 납니다. 필요하면 `this.database.isConnected()` 로 확인하세요.
+
+### B. 헬퍼 CRUD (`DatabaseQuery`)
+
+문자열 테이블 키·plain object `where`·페이지네이션 등을 쓰기 쉽게 한 래퍼입니다.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { DatabaseQuery } from '@xfilecom/backend-core';
+
+@Injectable()
+export class MetaService {
+  constructor(private readonly dbQuery: DatabaseQuery) {}
+
+  findByKey(key: string) {
+    return this.dbQuery.findOne('appMeta', {
+      where: { key },
+      fields: ['id', 'key', 'value'],
+    });
+  }
+}
+```
+
+`select` / `insert` / `update` / `delete` / `count` / `exists` / `findById` 등은 **`DatabaseQuery` 타입 정의·구현**(`@xfilecom/backend-core`)을 보면 됩니다.
+
+## 4. 모듈에 서비스 등록
+
+```typescript
+@Module({
+  imports: [CoreModule.forHttpApi(coreOptionsFromYaml())],
+  controllers: [AppController],
+  providers: [MetaService],
+})
+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 을 찾습니다).
+
+| 스크립트 | 설명 |
+|----------|------|
+| `npm run db:generate` | 스키마 diff → SQL 마이그레이션 생성 |
+| `npm run db:push` | 스키마를 DB 에 맞춤 (개발용) |
+| `npm run db:migrate` | 마이그레이션 적용 |
+| `npm run db:studio` | Drizzle Studio |
+| `npm run db:pull` | DB 역추출 (introspect) |
+
+원시 SQL·시드는 `shared/sql/` 에 두는 패턴을 권장합니다.
+
+## 6. 연결 실패 시
+
+`DatabaseService` 는 연결에 실패해도 **애플리케이션 기동은 계속**하고 경고만 남깁니다. DB 가 필요한 핸들러에서는 `isConnected()` 확인 또는 try/catch 로 처리하세요.

package/template/shared/README.md

@@ -6,7 +6,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 하는 식으로 맞추면 됩니다. |
+| **`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`, 수동 스크립트 등) |
 | **`endpoint/`** | HTTP 계약(OpenAPI yaml, 공유 DTO 타입, 라우트 메타) — 제품에 맞게 확장 |
 

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

@@ -10,8 +10,8 @@ http:
 # • 기본 CONFIG_SOURCE=yaml (`apps/api/src/config.loader.ts`) → 이 파일이 DB 근거, 셸의 DB_* 로 덮이지 않음.
 #   배포에서 env 우선이면 CONFIG_SOURCE=yamlWithEnvOverrides
 # • 호스트: Docker MySQL 을 맥/윈에서 포트 포워딩으로 쓸 때는 `127.0.0.1` 권장 (`localhost` 는 소켓/해석 차이).
-# • DB 이름·비밀번호는 DB 클라이언트(GUI)와 글자 하나까지 동일해야 함 (예: my_db vs my-db, milk1209 vs milk!209).
-# • 비밀번호에 ! @ # 등 YAML 특수문자, DB 이름에 하이픈이 있으면 반드시 따옴표: password: 'a!b' , name: 'my-db'
+# • DB 이름·비밀번호는 MySQL/GUI 와 동일해야 함 (언더스코어 vs 하이픈 등 이름 혼동 주의).
+# • YAML 은 보통 따옴표 없이 써도 됨. ! : @ 등으로 파싱이 꼬일 때만 작은따옴표로 감싸면 됨.
 # • 로그에 Access denied … user'@'172.x.x.x 면 컨테이너가 보는 클라이언트 주소입니다. MySQL 에서 GRANT 대상 호스트(% 등) 확인.
 #
 database:

package/template/shared/schema/README.md

@@ -3,3 +3,10 @@
 - 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를 정리하세요.
 - Nest 기본 빌드는 `apps/api/src`만 컴파일하므로, `shared/schema`에 TS를 두면 **`apps/api/tsconfig.build.json`의 `include`** 에 `../../shared/schema/**/*.ts` 를 추가하거나, 스키마를 `apps/api/src/database/schema`에 두고 이 폴더는 문서·SQL 덤프용으로만 써도 됩니다.
+
+## `DatabaseQuery` 와 테이블 이름
+
+`@xfilecom/backend-core` 의 `DatabaseQuery` 는 첫 인자로 **문자열 테이블 키**를 받습니다. 이 값은 MySQL 의 물리 테이블명이 아니라 **`schema` 객체의 키**와 같아야 합니다.  
+예: `export const appMeta = mysqlTable('app_meta', …)` → `findOne('appMeta', …)`.
+
+Drizzle 을 직접 쓸 때는 `DatabaseService.db` 와 함께 `appMeta` 심볼을 import 하면 됩니다. 전체 흐름은 **[docs/DATABASE.md](../../docs/DATABASE.md)** 를 참고하세요.

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

@@ -9,4 +9,8 @@ export type CommonEnvelope<T> = {
 export type HealthData = {
   ok?: boolean;
   service?: string;
+  database?: {
+    moduleLoaded: boolean;
+    connected: boolean;
+  };
 };

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 에 맞출 것.