@simplysm/service-common 14.0.49 → 14.0.50

package/docs/protocol/service-message.md

@@ -0,0 +1,52 @@
+# ServiceMessage
+
+모든 서비스 메시지의 유니언 타입. 클라이언트·서버 양방향 메시지를 모두 포함한다.
+
+```typescript
+export type ServiceMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceProgressMessage
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage
+  | ServiceEventMessage;
+```
+
+## Related Types
+
+### `ServiceClientMessage`
+
+클라이언트 → 서버 메시지 유니언.
+
+```typescript
+export type ServiceClientMessage =
+  | ServiceRequestMessage
+  | ServiceAuthMessage
+  | ServiceAddEventListenerMessage
+  | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage;
+```
+
+### `ServiceServerMessage`
+
+서버 → 클라이언트 메시지 유니언.
+
+```typescript
+export type ServiceServerMessage =
+  | ServiceResponseMessage
+  | ServiceErrorMessage
+  | ServiceEventMessage;
+```
+
+### `ServiceServerRawMessage`
+
+서버가 보내는 모든 메시지 (진행 상태 포함).
+
+```typescript
+export type ServiceServerRawMessage = ServiceProgressMessage | ServiceServerMessage;
+```

package/docs/protocol/service-progress-message.md

@@ -0,0 +1,21 @@
+# ServiceProgressMessage
+
+서버가 보내는 청크 수신 진행 상태 알림 메시지.
+
+```typescript
+export interface ServiceProgressMessage {
+  name: "progress";
+  body: {
+    totalSize: number;
+    completedSize: number;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"progress"` | 고정 문자열 discriminant |
+| `body.totalSize` | `number` | 전체 메시지 크기 (바이트) |
+| `body.completedSize` | `number` | 현재까지 수신 완료된 크기 (바이트) |

package/docs/protocol/service-remove-event-listener-message.md

@@ -0,0 +1,19 @@
+# ServiceRemoveEventListenerMessage
+
+클라이언트가 보내는 이벤트 리스너 제거 메시지.
+
+```typescript
+export interface ServiceRemoveEventListenerMessage {
+  name: "evt:remove";
+  body: {
+    key: string;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:remove"` | 고정 문자열 discriminant |
+| `body.key` | `string` | 제거할 리스너 키 (UUID) |

package/docs/protocol/service-request-message.md

@@ -0,0 +1,17 @@
+# ServiceRequestMessage
+
+클라이언트가 보내는 서비스 메서드 요청 메시지.
+
+```typescript
+export interface ServiceRequestMessage {
+  name: `${string}.${string}`;
+  body: unknown[];
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `` `${string}.${string}` `` | 서비스명.메서드명 형식 (예: `"OrmService.connect"`) |
+| `body` | `unknown[]` | 메서드 매개변수 배열 |

package/docs/protocol/service-response-message.md

@@ -0,0 +1,17 @@
+# ServiceResponseMessage
+
+서버가 보내는 서비스 메서드 응답 메시지.
+
+```typescript
+export interface ServiceResponseMessage {
+  name: "response";
+  body?: unknown;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"response"` | 고정 문자열 discriminant |
+| `body` | `unknown?` | 메서드 실행 결과 (없으면 void) |

package/docs/service-types/app-structure-service.md

@@ -0,0 +1,15 @@
+# AppStructureService
+
+서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 서비스 인터페이스.
+
+```typescript
+export interface AppStructureService {
+  getItems(): Record<string, AppStructureItem[]>;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getItems` | 없음 | `Record<string, AppStructureItem[]>` | 클라이언트명을 키로, 해당 클라이언트의 앱 구조 항목 배열을 값으로 하는 맵 반환 |

package/docs/service-types/auto-update-service.md

@@ -0,0 +1,20 @@
+# AutoUpdateService
+
+클라이언트 애플리케이션의 최신 버전 정보를 조회하는 서비스 인터페이스.
+
+```typescript
+export interface AutoUpdateService {
+  getLastVersion(platform: string): Promise<
+    | { version: string; downloadPath: string }
+    | undefined
+  >;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getLastVersion` | `platform: string` | `Promise<{ version: string; downloadPath: string } \| undefined>` | 지정된 플랫폼의 최신 버전 정보 조회. 버전이 없으면 `undefined` |
+
+`platform` 예시: `"win32"`, `"darwin"`, `"linux"`

package/docs/{service-types.md → service-types/orm-service.md}

@@ -1,90 +1,61 @@
-# Service Types
-
-## `OrmService`
-
-데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공하는 서비스 인터페이스. MySQL, MSSQL, PostgreSQL을 지원한다. 이 패키지에는 구현체가 없으며, 서버(`service-server`)와 클라이언트(`service-client`)가 공유하는 타입 계약이다.
-
-```typescript
-export interface OrmService {
-  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
-    dialect: Dialect;
-    database?: string;
-    schema?: string;
-  }>;
-  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
-  close(connId: number): Promise<void>;
-  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(connId: number): Promise<void>;
-  rollbackTransaction(connId: number): Promise<void>;
-  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
-  executeDefs(
-    connId: number,
-    defs: QueryDef[],
-    options?: (ResultMeta | undefined)[],
-  ): Promise<unknown[][]>;
-  bulkInsert(
-    connId: number,
-    tableName: string,
-    columnDefs: Record<string, ColumnMeta>,
-    records: Record<string, unknown>[],
-  ): Promise<void>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect, database?, schema? }>` | DB 연결 정보 (dialect, database, schema) 조회 |
-| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | DB 연결을 생성하고 연결 ID 반환 |
-| `close` | `connId: number` | `Promise<void>` | 연결 종료 |
-| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | 트랜잭션 시작 |
-| `commitTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 커밋 |
-| `rollbackTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 롤백 |
-| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | 파라미터 바인딩 쿼리 실행 |
-| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | QueryDef 배열로 쿼리 실행 |
-| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | 대량 삽입 |
-
-사용 순서: `connect()` -> `beginTransaction()` -> `executeDefs()`/`executeParametrized()` -> `commitTransaction()`/`rollbackTransaction()` -> `close()`
-
-## `DbConnOptions`
-
-데이터베이스 연결 옵션.
-
-```typescript
-export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `configName` | `string?` | 서버에 등록된 DB 설정 이름 |
-| `config` | `Record<string, unknown>?` | 직접 지정하는 DB 연결 설정 |
-
-## `AutoUpdateService`
-
-클라이언트 애플리케이션의 최신 버전 정보를 조회하는 서비스 인터페이스.
-
-```typescript
-export interface AutoUpdateService {
-  getLastVersion(platform: string): Promise<
-    | { version: string; downloadPath: string }
-    | undefined
-  >;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getLastVersion` | `platform: string` | `Promise<{ version, downloadPath } \| undefined>` | 지정된 플랫폼(예: "win32", "darwin", "linux")의 최신 버전 정보 조회. 버전이 없으면 undefined |
-
-## `AppStructureService`
-
-서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 서비스 인터페이스.
-
-```typescript
-export interface AppStructureService {
-  getItems(): Record<string, AppStructureItem[]>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `getItems` | 없음 | `Record<string, AppStructureItem[]>` | 클라이언트명을 키로, 해당 클라이언트의 앱 구조 항목 배열을 값으로 하는 맵 반환 |
+# OrmService
+
+데이터베이스 연결, 트랜잭션 관리, 쿼리 실행을 제공하는 서비스 인터페이스. MySQL, MSSQL, PostgreSQL을 지원한다. 이 패키지에는 구현체가 없으며, 서버(`service-server`)와 클라이언트(`service-client`)가 공유하는 타입 계약이다.
+
+```typescript
+export interface OrmService {
+  getInfo(opt: DbConnOptions & { configName: string }): Promise<{
+    dialect: Dialect;
+    database?: string;
+    schema?: string;
+  }>;
+  connect(opt: DbConnOptions & { configName: string }): Promise<number>;
+  close(connId: number): Promise<void>;
+  beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(connId: number): Promise<void>;
+  rollbackTransaction(connId: number): Promise<void>;
+  executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>;
+  executeDefs(
+    connId: number,
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<unknown[][]>;
+  bulkInsert(
+    connId: number,
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+## Members
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `getInfo` | `opt: DbConnOptions & { configName: string }` | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | DB 연결 정보 조회 |
+| `connect` | `opt: DbConnOptions & { configName: string }` | `Promise<number>` | DB 연결을 생성하고 연결 ID 반환 |
+| `close` | `connId: number` | `Promise<void>` | 연결 종료 |
+| `beginTransaction` | `connId: number, isolationLevel?: IsolationLevel` | `Promise<void>` | 트랜잭션 시작 |
+| `commitTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 커밋 |
+| `rollbackTransaction` | `connId: number` | `Promise<void>` | 트랜잭션 롤백 |
+| `executeParametrized` | `connId: number, query: string, params?: unknown[]` | `Promise<unknown[][]>` | 파라미터 바인딩 쿼리 실행 |
+| `executeDefs` | `connId: number, defs: QueryDef[], options?: (ResultMeta \| undefined)[]` | `Promise<unknown[][]>` | QueryDef 배열로 쿼리 실행 |
+| `bulkInsert` | `connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]` | `Promise<void>` | 대량 삽입 |
+
+사용 순서: `connect()` → `beginTransaction()` → `executeDefs()`/`executeParametrized()` → `commitTransaction()`/`rollbackTransaction()` → `close()`
+
+## Related Types
+
+### `DbConnOptions`
+
+데이터베이스 연결 옵션.
+
+```typescript
+export type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `configName` | `string?` | 서버에 등록된 DB 설정 이름 |
+| `config` | `Record<string, unknown>?` | 직접 지정하는 DB 연결 설정 |

package/docs/{types.md → types/service-upload-result.md}

@@ -1,19 +1,19 @@
-# Types
-
-## `ServiceUploadResult`
-
-파일 업로드 결과. 서버에 업로드된 파일의 정보를 포함한다.
-
-```typescript
-export interface ServiceUploadResult {
-  path: string;
-  filename: string;
-  size: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `path` | `string` | 서버 내 저장 경로 |
-| `filename` | `string` | 원본 파일명 |
-| `size` | `number` | 파일 크기 (바이트) |
+# ServiceUploadResult
+
+파일 업로드 결과. 서버에 업로드된 파일의 정보를 포함한다.
+
+```typescript
+export interface ServiceUploadResult {
+  path: string;
+  filename: string;
+  size: number;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `path` | `string` | 서버 내 저장 경로 |
+| `filename` | `string` | 원본 파일명 |
+| `size` | `number` | 파일 크기 (바이트) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/service-common",
-  "version": "14.0.49",
+  "version": "14.0.50",
   "description": "심플리즘 패키지 - 서비스 (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -22,7 +22,7 @@
     "@types/node": "^20.19.39"
   },
   "dependencies": {
-    "@simplysm/core-common": "14.0.49",
-    "@simplysm/orm-common": "14.0.49"
+    "@simplysm/core-common": "14.0.50",
+    "@simplysm/orm-common": "14.0.50"
   }
 }

package/docs/app-structure.md

@@ -1,175 +0,0 @@
-# App Structure
-
-## `AppStructureItem`
-
-앱 구조 항목 유니언 타입. `children` 필드 유무로 그룹과 리프를 구분한다.
-
-```typescript
-export type AppStructureItem<TModule = unknown> =
-  | AppStructureGroupItem<TModule>
-  | AppStructureLeafItem<TModule>;
-```
-
-`TModule` 제네릭은 모듈 식별자 타입이다 (일반적으로 `string`).
-
-## `AppStructureGroupItem`
-
-자식을 가진 그룹 메뉴 항목. `children` 필드로 하위 항목을 재귀적으로 포함한다.
-
-```typescript
-export interface AppStructureGroupItem<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  icon?: string;
-  children: AppStructureItem<TModule>[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 항목 코드 (권한 코드 체인에 사용) |
-| `title` | `string` | 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건: 하나라도 있으면 접근 가능) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건: 모두 있어야 접근 가능) |
-| `icon` | `string?` | 아이콘 식별자 |
-| `children` | `AppStructureItem<TModule>[]` | 하위 메뉴 항목 배열 |
-
-## `AppStructureLeafItem`
-
-말단 메뉴 항목. 실제 페이지 URL과 권한(perms)을 가진다.
-
-```typescript
-export interface AppStructureLeafItem<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  perms?: ("use" | "edit")[];
-  subPerms?: AppStructureSubPermission<TModule>[];
-  icon?: string;
-  url?: string;
-  isNotMenu?: boolean;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 항목 코드 |
-| `title` | `string` | 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
-| `perms` | `("use" \| "edit")[]?` | 이 항목에 부여 가능한 권한 종류 |
-| `subPerms` | `AppStructureSubPermission<TModule>[]?` | 하위 권한 정의 배열 |
-| `icon` | `string?` | 아이콘 식별자 |
-| `url` | `string?` | 페이지 URL |
-| `isNotMenu` | `boolean?` | true이면 메뉴에 표시하지 않음 |
-
-## `AppStructureSubPermission`
-
-리프 항목의 하위 권한 정의. 각 하위 권한도 모듈 접근 제어를 가진다.
-
-```typescript
-export interface AppStructureSubPermission<TModule> {
-  code: string;
-  title: string;
-  modules?: TModule[];
-  requiredModules?: TModule[];
-  perms: ("use" | "edit")[];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `code` | `string` | 하위 권한 코드 |
-| `title` | `string` | 하위 권한 표시 이름 |
-| `modules` | `TModule[]?` | 접근에 필요한 모듈 목록 (OR 조건) |
-| `requiredModules` | `TModule[]?` | 접근에 필수인 모듈 목록 (AND 조건) |
-| `perms` | `("use" \| "edit")[]` | 부여 가능한 권한 종류 |
-
-## `FlatPermission`
-
-트리를 플래트닝한 권한 결과. `getFlatPermissions()`의 반환 타입이다.
-
-```typescript
-export interface FlatPermission<TModule = unknown> {
-  titleChain: string[];
-  codeChain: string[];
-  modulesChain: TModule[][];
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `titleChain` | `string[]` | 루트부터 현재 권한까지의 표시 이름 체인 (예: `[관리, 사용자]`) |
-| `codeChain` | `string[]` | 루트부터 현재 권한까지의 코드 체인 (예: `[admin, user, use]`) |
-| `modulesChain` | `TModule[][]` | 각 레벨에서 필요한 모듈 목록의 체인 |
-
-## `isUsableModules`
-
-단일 항목의 모듈 접근 가능 여부를 판단한다.
-
-```typescript
-export function isUsableModules<TModule>(
-  modules: TModule[] | undefined,
-  requiredModules: TModule[] | undefined,
-  usableModules: TModule[] | undefined,
-): boolean;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `modules` | `TModule[] \| undefined` | OR 조건 모듈 목록. 하나라도 `usableModules`에 포함되면 통과 |
-| `requiredModules` | `TModule[] \| undefined` | AND 조건 모듈 목록. 모두 `usableModules`에 포함되어야 통과 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
-
-반환: `modules`와 `requiredModules` 조건을 모두 만족하면 `true`.
-
-- `modules`가 undefined이거나 빈 배열이면 OR 조건은 자동 통과
-- `requiredModules`가 undefined이거나 빈 배열이면 AND 조건은 자동 통과
-- `usableModules`가 undefined이면 `modules`가 있을 때 `false`
-
-## `isUsableModulesChain`
-
-모듈 체인 전체의 접근 가능 여부를 판단한다. 트리의 각 레벨에서 모듈 조건을 모두 만족해야 한다.
-
-```typescript
-export function isUsableModulesChain<TModule>(
-  modulesChain: TModule[][],
-  requiredModulesChain: TModule[][],
-  usableModules: TModule[] | undefined,
-): boolean;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `modulesChain` | `TModule[][]` | 각 레벨의 OR 조건 모듈 배열 |
-| `requiredModulesChain` | `TModule[][]` | 각 레벨의 AND 조건 모듈 배열 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
-
-반환: 모든 레벨의 조건을 만족하면 `true`. 하나라도 실패하면 `false`.
-
-## `getFlatPermissions`
-
-앱 구조 트리를 BFS로 순회하며 모듈 조건을 필터링하여 `FlatPermission[]`으로 플래트닝한다.
-
-```typescript
-export function getFlatPermissions<TModule>(
-  items: AppStructureItem<TModule>[],
-  usableModules: TModule[] | undefined,
-): FlatPermission<TModule>[];
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `items` | `AppStructureItem<TModule>[]` | 앱 구조 트리의 최상위 항목 배열 |
-| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록. undefined이면 모듈 조건이 없는 항목만 포함 |
-
-반환: 모듈 조건을 만족하는 모든 권한의 플랫 목록.
-
-처리 로직:
-1. BFS로 트리를 순회하며 각 레벨의 `modules`(OR)와 `requiredModules`(AND) 조건을 체크
-2. 조건 미충족 항목은 하위 트리 전체를 건너뜀
-3. `AppStructureLeafItem`의 `perms`를 `codeChain`에 추가하여 `FlatPermission` 생성
-4. `subPerms`도 개별 모듈 조건을 체크하여 `FlatPermission`으로 변환