create-sonamu 0.1.4 → 0.1.6

package/README.md

@@ -114,19 +114,17 @@ pnpm create sonamu my_app \
 cd my_app/packages/api
 pnpm docker:up
 
-# 2. API 서버 시작 (Sonamu UI 포함)
-pnpm dev
-
-# 3. Web 서버 시작 (새 터미널)
-cd my_app/packages/web
+# 2. 개발 서버 시작 (API + Web 통합 모드)
 pnpm dev
 ```
 
 🎉 **완료!**
 
-- API: http://localhost:34900
+- API + Web: http://localhost:34900 (통합 모드)
 - Sonamu UI: http://localhost:34900/sonamu-ui (엔티티 관리)
-- Web: http://localhost:3028
+
+> **참고**: `pnpm dev`는 `sonamu dev`를 실행하며, 기본적으로 API와 Web을 하나의 포트로 통합 서빙합니다.
+> Web만 별도로 실행하려면 `sonamu dev web`을 사용하세요.
 
 ---
 
@@ -167,14 +165,14 @@ pnpm dev
 
 | 서비스         | 포트               | URL                              |
 | -------------- | ------------------ | -------------------------------- |
-| **API 서버**   | `BASE_PORT` (34900) | http://localhost:34900            |
+| **API + Web (통합)** | `BASE_PORT` (34900) | http://localhost:34900     |
 | **Sonamu UI**  | -                  | http://localhost:34900/sonamu-ui  |
-| **Web 개발**   | `BASE_PORT + 2000` (3028) | http://localhost:3028     |
 | **PostgreSQL** | 5432               | -                                |
 
 **참고**:
+- `sonamu dev` (= `sonamu dev all`)은 API와 Web을 하나의 포트(one-port)로 통합 서빙합니다
 - Sonamu UI는 API 서버에 통합되어 있어 별도 실행이 필요 없습니다
-- Web은 개발 중에는 Vite dev 서버(3028)로, 프로덕션에서는 빌드 후 API 서버에서 서빙됩니다
+- Web만 별도로 실행하려면 `sonamu dev web`을 사용하세요
 
 ---
 
@@ -184,8 +182,10 @@ pnpm dev
 
 | 명령어           | 설명                                      |
 | ---------------- | ----------------------------------------- |
-| `pnpm dev`       | 개발 서버 시작 (HMR, Sonamu UI 포함)      |
-| `pnpm build`     | 프로덕션 빌드                             |
+| `pnpm dev`       | 통합 개발 서버 시작 (= `sonamu dev all`)  |
+| `pnpm build`     | 전체 프로덕션 빌드 (= `sonamu build all`) |
+| `pnpm build api` | API만 빌드 (= `sonamu build api`)         |
+| `pnpm build web` | Web만 빌드 (= `sonamu build web`)         |
 | `pnpm start`     | 프로덕션 서버 실행                        |
 | `pnpm test`      | 테스트 실행                               |
 | `pnpm docker:up`     | Docker 데이터베이스 시작                  |
@@ -196,15 +196,26 @@ pnpm dev
 | `pnpm sonamu skills sync` | 공식 Skills 동기화                   |
 | `pnpm sonamu skills create <name>` | 커스텀 Skill 생성             |
 
-### Web (`web/`)
+### 개발 서버 모드
+
+| 명령어                          | 설명                                     |
+| ------------------------------- | ---------------------------------------- |
+| `sonamu dev`                    | 통합 모드 (= `sonamu dev all`)           |
+| `sonamu dev all`                | 통합 모드 (one-port: API + Web)          |
+| `sonamu dev api`                | API-only 모드 (Vite 통합 비활성)         |
+| `sonamu dev web`                | Vite 단독 실행                           |
+| `sonamu dev web -- --port 3028` | Vite 옵션 전달                           |
+
+### 빌드
 
-| 명령어         | 설명                          |
-| -------------- | ----------------------------- |
-| `pnpm dev`     | 개발 서버 시작 (Vite)         |
-| `pnpm build`   | 프로덕션 빌드 (Client + SSR)  |
-| `pnpm preview` | 빌드 결과 미리보기            |
+| 명령어             | 설명                                      |
+| ------------------ | ----------------------------------------- |
+| `sonamu build`     | 전체 빌드 (= `sonamu build all`)          |
+| `sonamu build all` | 전체 빌드 (API + Web)                     |
+| `sonamu build api` | API만 빌드                                |
+| `sonamu build web` | Web만 빌드                                |
 
-**참고**: `pnpm build`는 클라이언트와 SSR 서버를 모두 빌드합니다. 빌드 결과는 `api/public/web`과 `api/dist/ssr`에 복사됩니다.
+**참고**: `sonamu build web`은 클라이언트와 SSR 서버를 모두 빌드합니다. 빌드 결과는 `web/dist/`에 생성되고, `api/web-dist/`로 복사됩니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sonamu",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Create a new Sonamu project",
   "keywords": [
     "sonamu",

package/template/src/README.md

@@ -48,17 +48,19 @@ cd packages/api
 pnpm docker:up
 ```
 
-### 3. API 서버 시작
+### 3. 개발 서버 시작
 
 ```bash
 cd packages/api
 pnpm dev
 ```
 
-API 서버가 시작되면 다음 주소로 접속할 수 있습니다:
-- **API 서버**: http://localhost:34900
+개발 서버가 시작되면 다음 주소로 접속할 수 있습니다:
+- **API + Web (통합)**: http://localhost:34900
 - **Sonamu UI**: http://localhost:34900/sonamu-ui (엔티티 관리)
 
+> `pnpm dev`는 `sonamu dev`를 실행하며, 기본적으로 API와 Web을 하나의 포트로 통합 서빙합니다 (`sonamu dev all`과 동일).
+
 ### 4. 첫 번째 엔티티 생성
 
 1. Sonamu UI 열기: http://localhost:34900/sonamu-ui
@@ -66,14 +68,11 @@ API 서버가 시작되면 다음 주소로 접속할 수 있습니다:
 3. 엔티티 정의 (예: `User`, `Post`)
 4. `api/src/application/`과 `web/src/services/`에 파일이 자동으로 생성됩니다
 
-### 5. Web 서버 시작 (새 터미널에서)
+### 5. 앱 확인
 
-```bash
-cd packages/web
-pnpm dev
-```
+http://localhost:34900 을 열어서 앱을 확인하세요!
 
-http://localhost:3028 을 열어서 앱을 확인하세요!
+> Web만 별도로 실행하고 싶다면 `sonamu dev web`을 사용할 수 있습니다 (`--` 뒤에 Vite 옵션 전달 가능).
 
 ---
 
@@ -105,12 +104,11 @@ web/src/services/
 
 ## 🌐 포트 구성
 
-| 서비스      | 포트                    | URL                             |
-| ----------- | ----------------------- | ------------------------------- |
-| API 서버    | `BASE_PORT` (기본 34900) | http://localhost:34900           |
-| Sonamu UI   | -                       | http://localhost:34900/sonamu-ui |
-| Web 클라이언트 | `BASE_PORT + 2000`      | http://localhost:3028           |
-| PostgreSQL  | 5432                    | -                               |
+| 서비스             | 포트                     | URL                             |
+| ------------------ | ------------------------ | ------------------------------- |
+| API + Web (통합)   | `BASE_PORT` (기본 34900) | http://localhost:34900           |
+| Sonamu UI          | -                        | http://localhost:34900/sonamu-ui |
+| PostgreSQL         | 5432                     | -                               |
 
 ## 📜 주요 스크립트
 
@@ -124,27 +122,30 @@ web/src/services/
 
 ### API (`packages/api/`)
 
-| 명령어              | 설명                                   |
-| ------------------- | -------------------------------------- |
-| `pnpm dev`          | 개발 서버 시작 (HMR, Sonamu UI 포함)   |
-| `pnpm build`        | 프로덕션 빌드                          |
-| `pnpm start`        | 프로덕션 서버 시작                     |
-| `pnpm test`         | 테스트 실행                            |
-| `pnpm docker:up`    | Docker DB 시작                         |
-| `pnpm docker:down`  | Docker DB 중지                         |
-| `pnpm docker:reset` | Docker DB 초기화 (볼륨 삭제 후 재시작) |
-| `pnpm dump`         | 테스트 DB 덤프 생성                    |
-| `pnpm seed`         | 덤프를 fixture DB에 적용               |
+| 명령어              | 설명                                       |
+| ------------------- | ------------------------------------------ |
+| `pnpm dev`          | 통합 개발 서버 시작 (= `sonamu dev all`)   |
+| `pnpm build`        | 전체 프로덕션 빌드 (= `sonamu build all`)  |
+| `pnpm build api`    | API만 빌드 (= `sonamu build api`)          |
+| `pnpm build web`    | Web만 빌드 (= `sonamu build web`)          |
+| `pnpm start`        | 프로덕션 서버 시작                         |
+| `pnpm test`         | 테스트 실행                                |
+| `pnpm docker:up`    | Docker DB 시작                             |
+| `pnpm docker:down`  | Docker DB 중지                             |
+| `pnpm docker:reset` | Docker DB 초기화 (볼륨 삭제 후 재시작)     |
+| `pnpm dump`         | 테스트 DB 덤프 생성                        |
+| `pnpm seed`         | 덤프를 fixture DB에 적용                   |
 | `pnpm sonamu skills sync` | 공식 Skills 동기화                   |
 | `pnpm sonamu skills create <name>` | 커스텀 Skill 생성             |
 
-### Web (`packages/web/`)
+### 개발 서버 모드
 
-| 명령어         | 설명               |
-| -------------- | ------------------ |
-| `pnpm dev`     | 개발 서버 시작     |
-| `pnpm build`   | 프로덕션 빌드      |
-| `pnpm preview` | 빌드 결과 미리보기 |
+| 명령어                                 | 설명                           |
+| -------------------------------------- | ------------------------------ |
+| `sonamu dev` / `sonamu dev all`        | 통합 모드 (one-port: API + Web) |
+| `sonamu dev api`                       | API-only 모드                  |
+| `sonamu dev web`                       | Vite 단독 실행                 |
+| `sonamu dev web -- --port 3028 --host 0.0.0.0` | Vite 옵션 전달         |
 
 ## 🛠️ 개발 워크플로우
 

package/template/src/gitignore

@@ -3,7 +3,7 @@ node_modules/
 
 # Production builds
 dist/
-dist-ssr/
+web-dist/
 
 # Environment variables
 .env

package/template/src/packages/api/package.json

@@ -39,7 +39,7 @@
     "knex": "^3.1.0",
     "pg": "^8.16.3",
     "radashi": "^12.2.0",
-    "sonamu": "^0.7.51",
+    "sonamu": "^0.8.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/template/src/packages/api/src/sonamu.config.ts

@@ -49,8 +49,8 @@ export default defineConfig({
         // nothing yet
       },
     },
-    
-    auth:{
+
+    auth: {
       emailAndPassword: { enabled: true },
       baseURL: process.env.BETTER_AUTH_URL ?? `http://${host}:${port}`,
       secret: process.env.BETTER_AUTH_SECRET ?? "miomock-secret-key-change-this-in-production",

package/template/src/packages/api/src/testing/setup-mocks.ts

@@ -1,44 +1,44 @@
 import type { MakeDirectoryOptions, Mode, PathLike, RmOptions } from "fs";
 import type { FileHandle } from "fs/promises";
-import { Naite } from "sonamu";
+// import { Naite } from "sonamu";
 import { vi } from "vitest";
 
-// GlobalMock: fs/promises
+// GlobalMock: fs/promises (사용 예시 - 필요시 활성화)
 vi.mock("fs/promises", async (importOriginal) => {
   const actual = (await importOriginal()) as typeof import("fs/promises");
   return {
     ...actual,
     access: vi.fn((path: PathLike, mode?: number) => {
-      const vfs = Naite.get("mock:fs/promises:virtualFileSystem").result();
-      if (vfs.some((v) => v === path)) {
-        return Promise.resolve();
-      }
+      // const vfs = Naite.get("mock:fs/promises:virtualFileSystem").result();
+      // if (vfs.some((v) => v === path)) {
+      //   return Promise.resolve();
+      // }
 
       return actual.access(path, mode);
     }),
-    mkdir: vi.fn(
-      async (
-        path: PathLike,
-        options?: MakeDirectoryOptions | Mode | null,
-      ): Promise<string | undefined> => {
-        Naite.t("fs:mkdir", { path, options });
-        if (typeof options === "object" && options?.recursive) {
-          return typeof path === "string" ? path : path.toString();
-        }
-        return undefined;
-      },
-    ),
-    writeFile: vi.fn((path: PathLike | FileHandle, data: string | Buffer | Uint8Array) => {
-      const filePath = typeof path === "string" ? path : path.toString();
+    // mkdir: vi.fn(
+    //   async (
+    //     path: PathLike,
+    //     options?: MakeDirectoryOptions | Mode | null,
+    //   ): Promise<string | undefined> => {
+    //     // Naite.t("fs:mkdir", { path, options });
+    //     if (typeof options === "object" && options?.recursive) {
+    //       return typeof path === "string" ? path : path.toString();
+    //     }
+    //     return undefined;
+    //   },
+    // ),
+    // writeFile: vi.fn((path: PathLike | FileHandle, data: string | Buffer | Uint8Array) => {
+    //   const filePath = typeof path === "string" ? path : path.toString();
 
-      Naite.t(`fs/promises:writeFile`, { path: filePath, data });
-    }),
-    rm: vi.fn(async (path: PathLike, options?: RmOptions) => {
-      const filePath = typeof path === "string" ? path : path.toString();
+    //   // Naite.t(`fs/promises:writeFile`, { path: filePath, data });
+    // }),
+    // rm: vi.fn(async (path: PathLike, options?: RmOptions) => {
+    //   const filePath = typeof path === "string" ? path : path.toString();
 
-      Naite.t(`fs/promises:rm`, { path: filePath, options });
-      // 실제 삭제하지 않고 기록만 함
-      return Promise.resolve();
-    }),
+    //   // Naite.t(`fs/promises:rm`, { path: filePath, options });
+    //   // 실제 삭제하지 않고 기록만 함
+    //   return Promise.resolve();
+    // }),
   };
 });

package/template/src/packages/web/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@sonamu-kit/react-components": "^0.1.8",
+    "@sonamu-kit/react-components": "^0.2.2",
     "@tanstack/react-query": "^5.90.12",
     "@tanstack/react-router": "1.143.11",
     "axios": "^1.13.2",

package/template/src/packages/web/src/App.tsx

@@ -3,7 +3,7 @@ import { useRouterState } from "@tanstack/react-router";
 import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
 import { type ReactNode, Suspense, useEffect } from "react";
 import Sidebar from "./components/Sidebar";
-import { setLocale } from "./i18n/sd.generated";
+import { SUPPORTED_LOCALES, setLocale } from "./i18n/sd.generated";
 
 interface AppProps {
   children?: ReactNode;
@@ -17,8 +17,8 @@ function App({ children }: AppProps) {
   useEffect(() => {
     // 브라우저 locale 감지
     const browserLocale = navigator.language.split("-")[0];
-    if (["ko", "en"].includes(browserLocale)) {
-      setLocale(browserLocale as "ko" | "en");
+    if (SUPPORTED_LOCALES.includes(browserLocale as typeof SUPPORTED_LOCALES[number])) {
+      setLocale(browserLocale as typeof SUPPORTED_LOCALES[number]);
     }
   }, []);
 

package/template/src/packages/web/src/i18n/sd.generated.ts

@@ -2,7 +2,7 @@
 // 초기 빈 상태 - sonamu dev 실행 시 실제 내용으로 대체됩니다.
 
 const DEFAULT_LOCALE = "ko" as const;
-const SUPPORTED_LOCALES = ["ko", "en"] as const;
+export const SUPPORTED_LOCALES = ["ko", "en"] as const;
 let _currentLocale: (typeof SUPPORTED_LOCALES)[number] = DEFAULT_LOCALE;
 
 export function setLocale(locale: (typeof SUPPORTED_LOCALES)[number]) {

package/template/src/packages/web/src/lib/auth-client.ts

@@ -0,0 +1,3 @@
+import { createAuthClient } from "better-auth/react";
+
+export const { signIn, signUp, useSession, signOut } = createAuthClient();

package/template/src/packages/web/src/services/sonamu.shared.ts

@@ -1,13 +1,27 @@
-// 자동 생성 파일 - sonamu sync로 갱신됨
-// 초기 빈 상태 - sonamu dev 실행 시 실제 내용으로 대체됩니다.
-
 /**
- * ISO 8601 및 타임존 포맷의 날짜 문자열을 Date 객체로 변환하는 reviver
+ * @generated
+ * 최초 1회 생성되며, 이후에는 덮어쓰지 않습니다.
+ * 필요시 직접 수정할 수 있습니다.
  */
+/** biome-ignore-all lint/correctness/useExhaustiveDependencies: shared */
+/** biome-ignore-all lint/suspicious/noExplicitAny: shared */
+
+/*
+  fetch
+*/
+import type { AxiosRequestConfig } from "axios";
+import axios from "axios";
+import qs from "qs";
+import { type core, z } from "zod";
+import { EventSource } from "eventsource";
+import { getCurrentLocale } from "../i18n/sd.generated";
+
+// ISO 8601 및 타임존 포맷의 날짜 문자열을 Date 객체로 변환하는 reviver
 export function dateReviver(_key: string, value: any): any {
   if (typeof value === "string") {
     // ISO 8601 형식: 2024-01-15T09:30:00.000Z 또는 2024-01-15T09:30:00+09:00
     const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})?$/;
+
     // Timezone 포맷: 2024-01-15 09:30:00+09:00
     const timezoneRegex = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}$/;
 
@@ -20,3 +34,546 @@ export function dateReviver(_key: string, value: any): any {
   }
   return value;
 }
+
+axios.defaults.transformResponse = [
+  (data) => {
+    if (typeof data === "string") {
+      try {
+        return JSON.parse(data, dateReviver);
+      } catch {
+        return data;
+      }
+    }
+    return data;
+  },
+];
+
+export async function fetch(options: AxiosRequestConfig) {
+  try {
+    const res = await axios({
+      ...options,
+    });
+    return res.data;
+  } catch (e: unknown) {
+    if (axios.isAxiosError(e) && e.response && e.response.data) {
+      const d = e.response.data as {
+        message: string;
+        issues: core.$ZodIssue[];
+      };
+      throw new SonamuError(e.response.status, d.message, d.issues);
+    }
+    throw e;
+  }
+}
+
+export function toFormData(
+  obj: Record<string, unknown>,
+  formData = new FormData(),
+  prefix = "",
+): FormData {
+  for (const [key, value] of Object.entries(obj)) {
+    const formKey = prefix ? `${prefix}[${key}]` : key;
+
+    if (value instanceof File || value instanceof Blob) {
+      formData.append(formKey, value);
+    } else if (Array.isArray(value)) {
+      value.forEach((item, index) => {
+        toFormData({ [index]: item }, formData, formKey);
+      });
+    } else if (value !== null && value !== undefined && typeof value === "object") {
+      toFormData(value as Record<string, unknown>, formData, formKey); // 재귀로 펼치기
+    } else if (value !== null && value !== undefined) {
+      formData.append(formKey, String(value));
+    }
+  }
+
+  return formData;
+}
+
+export class SonamuError extends Error {
+  isSonamuError: boolean;
+
+  constructor(
+    public code: number,
+    public message: string,
+    public issues: z.ZodIssue[],
+  ) {
+    super(message);
+    this.isSonamuError = true;
+  }
+}
+export function isSonamuError(e: any): e is SonamuError {
+  return e && e.isSonamuError === true;
+}
+
+export function defaultCatch(e: any) {
+  if (isSonamuError(e)) {
+    alert(e.message);
+  } else {
+    alert("에러 발생");
+  }
+}
+
+/*
+  Isomorphic Types
+*/
+// semanticQuery가 있으면 similarity를 추가하는 조건부 타입
+type WithSimilarity<LP, T> = LP extends { semanticQuery: Record<string, unknown> }
+  ? T & { similarity: number }
+  : T;
+
+export type ListResult<
+  LP extends { queryMode?: SonamuQueryMode },
+  T,
+> = LP["queryMode"] extends "list"
+  ? { rows: WithSimilarity<LP, T>[] }
+  : LP["queryMode"] extends "count"
+    ? { total: number }
+    : { rows: WithSimilarity<LP, T>[]; total: number };
+
+export const SonamuQueryMode = z.enum(["both", "list", "count"]);
+export type SonamuQueryMode = z.infer<typeof SonamuQueryMode>;
+
+/* Filter Types */
+// Prop 타입별 허용 연산자
+export const operatorsByPropType = {
+  string: ["eq", "ne", "contains", "startsWith", "endsWith", "in", "notIn", "isNull", "isNotNull"],
+  integer: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "between", "isNull", "isNotNull"],
+  numeric: ["eq", "ne", "gt", "gte", "lt", "lte", "in", "notIn", "between", "isNull", "isNotNull"],
+  boolean: ["eq", "ne", "isNull", "isNotNull"],
+  date: ["eq", "ne", "before", "after", "between", "isNull", "isNotNull"],
+  datetime: ["eq", "ne", "before", "after", "between", "isNull", "isNotNull"],
+  enum: ["eq", "ne", "in", "notIn", "isNull", "isNotNull"],
+  json: ["isNull", "isNotNull"],
+} as const;
+
+// Prop 타입별 기본 연산자
+export const defaultOperatorByPropType = {
+  string: "contains",
+  integer: "eq",
+  numeric: "eq",
+  boolean: "eq",
+  date: "eq",
+  datetime: "eq",
+  enum: "eq",
+  json: "isNull",
+} as const;
+
+// operatorsByPropType에서 파생되는 타입들
+export type FilterPropType = keyof typeof operatorsByPropType;
+export type FilterOperator = (typeof operatorsByPropType)[keyof typeof operatorsByPropType][number];
+
+// 특정 prop 타입에 허용되는 연산자 유니온
+type OperatorForPropType<TPropType extends FilterPropType> =
+  (typeof operatorsByPropType)[TPropType][number];
+
+// 연산자별 기대 값 타입
+type OperatorValue<T, K extends FilterOperator> = K extends "in" | "notIn"
+  ? T[]
+  : K extends "between"
+    ? [T, T]
+    : K extends "isNull" | "isNotNull"
+      ? boolean
+      : T;
+
+// 특정 연산자 집합에 대한 필터 조건 타입
+type ConditionForOperators<T, TOps extends FilterOperator> =
+  | T
+  | { [K in TOps]?: OperatorValue<T, K> };
+
+/**
+ * 필터 조건 - 타입에 따라 사용 가능한 연산자가 제한
+ */
+export type FilterCondition<T> =
+  NonNullable<T> extends number
+    ? ConditionForOperators<NonNullable<T>, OperatorForPropType<"integer">>
+    : NonNullable<T> extends string
+      ? ConditionForOperators<NonNullable<T>, OperatorForPropType<"string">>
+      : NonNullable<T> extends Date
+        ? ConditionForOperators<NonNullable<T>, OperatorForPropType<"date">>
+        : NonNullable<T> extends boolean
+          ? ConditionForOperators<NonNullable<T>, OperatorForPropType<"boolean">>
+          : // Fallback: 비원시 타입은 null 체크만 허용
+            ConditionForOperators<NonNullable<T>, OperatorForPropType<"json">>;
+
+/**
+ * 필터 쿼리
+ * 엔티티의 각 필드에 대한 필터 조건 정의
+ */
+export type FilterQuery<TEntity, TNumericKeys extends keyof TEntity = never> = {
+  [K in keyof TEntity]?: K extends TNumericKeys
+    ? ConditionForOperators<NonNullable<TEntity[K]>, OperatorForPropType<"numeric">>
+    : FilterCondition<TEntity[K]>;
+};
+
+/**
+ * Sonamu 필터 적용 타입
+ * Entity에서 제외할 필드와 numeric 필드를 받아서 최종 FilterQuery 타입을 생성
+ */
+export type ApplySonamuFilter<
+  TEntity,
+  TOmitKeys extends keyof TEntity = never,
+  TNumericKeys extends Exclude<keyof TEntity, TOmitKeys> = never,
+> = FilterQuery<Omit<TEntity, TOmitKeys>, TNumericKeys>;
+
+
+/**
+ * 필드명과 값을 기반으로 FilterPropType을 추론
+ */
+export function getFieldPropType(
+  fieldName: string,
+  value: any,
+  numericColumns: readonly string[]
+): FilterPropType {
+  // numeric 타입 체크 (명시적으로 지정된 컬럼)
+  if (numericColumns.includes(fieldName)) {
+    return "numeric";
+  }
+
+  // 값 기반 타입 추론
+  if (value instanceof Date) {
+    // Date 객체의 시간 정보 확인
+    const hasTime = value.getHours() !== 0 || value.getMinutes() !== 0 || value.getSeconds() !== 0;
+    return hasTime ? "datetime" : "date";
+  }
+
+  if (typeof value === "number") {
+    return "integer";
+  }
+
+  if (typeof value === "boolean") {
+    return "boolean";
+  }
+
+  // JSON 타입 (객체/배열)
+  if (value !== null && typeof value === "object") {
+    return "json";
+  }
+
+  // 기본값: string
+  return "string";
+}
+
+/* Semantic Query */
+export const SonamuSemanticParams = z.object({
+  semanticQuery: z.object({
+    embedding: z.array(z.number()).min(1024).max(1024),
+    threshold: z.number().optional(),
+    method: z.enum(["cosine", "l2", "inner_product"]).optional(),
+  }),
+});
+export type SonamuSemanticParams = z.infer<typeof SonamuSemanticParams>;
+
+/*
+  Utils
+*/
+export function zArrayable<T extends z.ZodTypeAny>(
+  shape: T,
+): z.ZodUnion<readonly [T, z.ZodArray<T>]> {
+  return z.union([shape, shape.array()]);
+}
+
+/*
+  Custom Scalars
+*/
+export const SQLDateTimeString = z
+  .string()
+  .regex(/([0-9]{4}-[0-9]{2}-[0-9]{2}( [0-9]{2}:[0-9]{2}:[0-9]{2})*)$/, {
+    message: "잘못된 SQLDate 타입",
+  })
+  .min(10)
+  .max(19)
+  .describe("SQLDateTimeString");
+export type SQLDateTimeString = z.infer<typeof SQLDateTimeString>;
+
+/**
+ * SonamuFile Types
+ */
+export interface SonamuFile {
+  name: string;
+  url: string;
+  mime_type: string;
+  size: number;
+}
+
+export const SonamuFileSchema = z.object({
+  name: z.string(),
+  url: z.string(),
+  mime_type: z.string(),
+  size: z.number(),
+});
+
+export const SonamuFileArraySchema = z.array(SonamuFileSchema);
+
+/*
+  Stream
+*/
+export type SSEStreamOptions = {
+  enabled?: boolean;
+  retry?: number;
+  retryInterval?: number;
+};
+export type SSEStreamState = {
+  isConnected: boolean;
+  error: string | null;
+  retryCount: number;
+  isEnded: boolean;
+};
+export type EventHandlers<T> = {
+  [K in keyof T]: (data: T[K]) => void;
+};
+
+import { useEffect, useRef, useState } from "react";
+
+export function useSSEStream<T extends Record<string, any>>(
+  url: string,
+  params: Record<string, any>,
+  handlers: {
+    [K in keyof T]?: (data: T[K]) => void;
+  },
+  options: SSEStreamOptions = {},
+): SSEStreamState {
+  const { enabled = true, retry = 3, retryInterval = 3000 } = options;
+
+  const [state, setState] = useState<SSEStreamState>({
+    isConnected: false,
+    error: null,
+    retryCount: 0,
+    isEnded: false,
+  });
+
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const retryTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handlersRef = useRef(handlers);
+
+  // handlers를 ref로 관리해서 재연결 없이 업데이트
+  useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+
+  // 연결 함수
+  const connect = () => {
+    if (!enabled) return;
+
+    try {
+      // 기존 연결이 있으면 정리
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close();
+        eventSourceRef.current = null;
+      }
+
+      // 재시도 타이머 정리
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current);
+        retryTimeoutRef.current = null;
+      }
+
+      // URL에 파라미터 추가
+      const queryString = qs.stringify(params);
+      const fullUrl = queryString ? `${url}?${queryString}` : url;
+
+      const eventSource = new EventSource(fullUrl, {
+        fetch: (url, init) =>
+          globalThis.fetch(url, {
+            ...init,
+            headers: {
+              ...init?.headers,
+              "Accept-Language": getCurrentLocale(),
+            },
+          }),
+      });
+      eventSourceRef.current = eventSource;
+
+      // 연결 시도 중 상태 표시
+      setState((prev) => ({
+        ...prev,
+        isConnected: false,
+        error: null,
+        isEnded: false,
+      }));
+
+      eventSource.onopen = () => {
+        setState((prev) => ({
+          ...prev,
+          isConnected: true,
+          error: null,
+          retryCount: 0,
+          isEnded: false,
+        }));
+      };
+
+      eventSource.onerror = (_event) => {
+        // 이미 다른 연결로 교체되었는지 확인
+        if (eventSourceRef.current !== eventSource) {
+          return; // 이미 새로운 연결이 있으면 무시
+        }
+
+        setState((prev) => ({
+          ...prev,
+          isConnected: false,
+          error: "Connection failed",
+          isEnded: false,
+        }));
+
+        // 자동 재연결 시도
+        if (state.retryCount < retry) {
+          retryTimeoutRef.current = setTimeout(() => {
+            // 여전히 같은 연결인지 확인
+            if (eventSourceRef.current === eventSource) {
+              setState((prev) => ({
+                ...prev,
+                retryCount: prev.retryCount + 1,
+                isEnded: false,
+              }));
+              connect();
+            }
+          }, retryInterval);
+        } else {
+          setState((prev) => ({
+            ...prev,
+            error: `Connection failed after ${retry} attempts`,
+          }));
+        }
+      };
+
+      // 공통 'end' 이벤트 처리 (사용자 정의 이벤트와 별도)
+      eventSource.addEventListener("end", () => {
+        console.log("SSE 연결 정상종료");
+        if (eventSourceRef.current === eventSource) {
+          eventSource.close();
+          eventSourceRef.current = null;
+          setState((prev) => ({
+            ...prev,
+            isConnected: false,
+            error: null, // 정상 종료
+            isEnded: true,
+          }));
+
+          if (handlersRef.current.end) {
+            const endHandler = handlersRef.current.end;
+            endHandler("end" as T[string]);
+          }
+        }
+      });
+
+      // 각 이벤트 타입별 리스너 등록
+      Object.keys(handlersRef.current).forEach((eventType) => {
+        const handler = handlersRef.current[eventType as keyof T];
+        if (handler) {
+          eventSource.addEventListener(eventType, (event) => {
+            // 여전히 현재 연결인지 확인
+            if (eventSourceRef.current !== eventSource) {
+              return; // 이미 새로운 연결로 교체되었으면 무시
+            }
+
+            try {
+              const data = JSON.parse(event.data);
+              handler(data);
+            } catch (error) {
+              console.error(`Failed to parse SSE data for event ${eventType}:`, error);
+            }
+            setState((prev) => ({
+              ...prev,
+              isEnded: false,
+            }));
+          });
+        }
+      });
+
+      // 기본 message 이벤트 처리 (event 타입이 없는 경우)
+      eventSource.onmessage = (event) => {
+        // 여전히 현재 연결인지 확인
+        if (eventSourceRef.current !== eventSource) {
+          return;
+        }
+
+        try {
+          const data = JSON.parse(event.data);
+          // 'message' 핸들러가 있으면 호출
+          const messageHandler = handlersRef.current["message" as keyof T];
+          if (messageHandler) {
+            messageHandler(data);
+          }
+        } catch (error) {
+          console.error("Failed to parse SSE message:", error);
+        }
+      };
+    } catch (error) {
+      setState((prev) => ({
+        ...prev,
+        error: error instanceof Error ? error.message : "Unknown error",
+        isConnected: false,
+        isEnded: false,
+      }));
+    }
+  };
+
+  // 연결 시작
+  useEffect(() => {
+    if (enabled) {
+      connect();
+    }
+
+    return () => {
+      // cleanup
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close();
+        eventSourceRef.current = null;
+      }
+      if (retryTimeoutRef.current) {
+        clearTimeout(retryTimeoutRef.current);
+        retryTimeoutRef.current = null;
+      }
+    };
+  }, [url, JSON.stringify(params), enabled]);
+
+  // 파라미터가 변경되면 재연결
+  useEffect(() => {
+    if (enabled && eventSourceRef.current) {
+      connect();
+    }
+  }, [JSON.stringify(params)]);
+
+  return state;
+}
+
+/*
+  Dictionary Helper
+*/
+export type PluralForms = {
+  zero?: string | ((n: number) => string);
+  one?: string | ((n: number) => string);
+  other?: string | ((n: number) => string);
+};
+
+export function plural(n: number, forms: PluralForms): string {
+  const form = (n === 0 && forms.zero) || (n === 1 && forms.one) || forms.other;
+  return typeof form === "function" ? form(n) : (form ?? n.toString());
+}
+
+export function createFormat(locale: string) {
+  return {
+    number: (n: number) => n.toLocaleString(locale),
+    date: (d: Date) => d.toLocaleDateString(locale),
+  };
+}
+
+export function josa(word: string, type: "은는" | "이가" | "을를" | "과와" | "으로") {
+  const has받침 = (() => {
+    const lastChar = word.charCodeAt(word.length - 1);
+    if (lastChar < 0xac00 || lastChar > 0xd7a3)
+      // 한글 유니코드 범위: 0xAC00 ~ 0xD7A3
+      return false;
+    return (lastChar - 0xac00) % 28 !== 0;
+  })();
+
+  const map = {
+    은는: has받침 ? "은" : "는",
+    이가: has받침 ? "이" : "가",
+    을를: has받침 ? "을" : "를",
+    과와: has받침 ? "과" : "와",
+    으로: has받침 ? "으로" : "로",
+  };
+
+  return word + map[type];
+}