@simplysm/sd-claude 14.0.47 → 14.0.49

package/claude/references/sd-simplysm14/service-client/usage.md

@@ -1,202 +0,0 @@
-# @simplysm/service-client
-
-WebSocket 기반 서비스 서버 클라이언트로, 서비스 호출, 실시간 이벤트 구독/발행, 파일 업로드/다운로드, ORM 원격 실행을 지원한다.
-
-## Installation
-
-```bash
-npm install @simplysm/service-client
-```
-
-## API Overview
-
-### Core Client
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceClient` | class | WebSocket 서비스 클라이언트 최상위 파사드 (연결, RPC, 이벤트, 파일, ORM 통합) |
-| `createServiceClient()` | function | ServiceClient 인스턴스 생성 팩토리 함수 |
-| `ServiceProxy<T>` | type | 서비스 메서드 반환 타입을 Promise로 래핑하는 타입 변환기 |
-
-→ See [docs/main.md](./docs/main.md) for details.
-
-### Transport Layer
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SocketProvider` | interface | WebSocket 래퍼 인터페이스 (connect, close, send, on, off, heartbeat) |
-| `createSocketProvider()` | function | SocketProvider 팩토리. 재연결 및 하트비트 관리 |
-| `SocketProviderEvents` | interface | SocketProvider 이벤트 맵 (message, state) |
-| `ServiceTransport` | interface | 요청-응답 매핑, progress 중계, 이벤트 디스패치 |
-| `createServiceTransport()` | function | ServiceTransport 팩토리. SocketProvider와 ClientProtocolWrapper 조합 |
-| `ServiceTransportEvents` | interface | ServiceTransport 이벤트 맵 (event) |
-
-→ See [docs/transport.md](./docs/transport.md) for details.
-
-### Protocol & Encoding
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ClientProtocolWrapper` | interface | 메시지 인코딩/디코딩 (30KB 이상 시 Web Worker 오프로드) |
-| `createClientProtocolWrapper()` | function | ClientProtocolWrapper 팩토리. ServiceProtocol 래핑 |
-
-→ See [docs/protocol.md](./docs/protocol.md) for details.
-
-### Event Management
-
-| API | Type | Description |
-|-----|------|-------------|
-| `EventClient` | interface | 서버 이벤트 구독/발행 관리 (재연결 시 자동 재구독) |
-| `createEventClient()` | function | EventClient 팩토리. ServiceTransport 사용 |
-| `ClientEventProxy<T>` | interface | 특정 이벤트에 대한 프록시 인터페이스 |
-
-→ See [docs/features.md](./docs/features.md) for details.
-
-### File Operations
-
-| API | Type | Description |
-|-----|------|-------------|
-| `FileClient` | interface | 파일 업로드(POST)/다운로드(GET) 인터페이스 |
-| `createFileClient()` | function | FileClient 팩토리. hostUrl과 clientName으로 생성 |
-
-### ORM Remote Execution
-
-| API | Type | Description |
-|-----|------|-------------|
-| `OrmClientConnector` | interface | DbContext 원격 트랜잭션 연결 헬퍼 |
-| `createOrmClientConnector()` | function | OrmClientConnector 팩토리. ServiceClient 사용 |
-| `OrmConnectOptions<T>` | interface | ORM 연결 설정 (DbClass, connOpt, dbContextOpt) |
-| `OrmClientDbContextExecutor` | class | DbContextExecutor 구현체 (서버로 원격 호출) |
-
-### Types & Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ServiceConnectionOptions` | interface | 서버 연결 옵션 (host, port, ssl, maxReconnectCount) |
-| `ServiceProgress` | interface | progress 콜백 인터페이스 (request, response, server) |
-| `ServiceProgressState` | interface | progress 상태 (uuid, totalSize, completedSize) |
-| `BlobInput` | type | Blob \| Uint8Array \| ArrayBuffer \| string (Blob 생성자 허용 타입) |
-| `FileCollection` | interface | FileList 호환 컬렉션 인터페이스 |
-| `WorkerLike` | interface | Web Worker 호환 인터페이스 |
-| `isWorkerSupported()` | function | Web Worker 지원 여부 확인 |
-| `createBrowserWorker()` | function | Web Worker 인스턴스 생성 (미지원 환경이면 undefined) |
-
-→ See [docs/types.md](./docs/types.md) for details.
-
-## Usage Examples
-
-### Basic Service Connection & RPC
-
-```typescript
-import { createServiceClient } from "@simplysm/service-client";
-
-const client = createServiceClient("my-app", {
-  host: "localhost",
-  port: 3000,
-  ssl: false,
-  maxReconnectCount: 10,  // 자동 재연결 (0으로 비활성화)
-});
-
-await client.connect();
-await client.auth("jwt-token");
-
-// 타입 안전한 서비스 프록시
-const userSvc = client.getService<UserService>("User");
-const users = await userSvc.getAll();
-
-await client.close();
-```
-
-### Event Subscription
-
-```typescript
-// 이벤트 리스너 등록 (selector로 필터링)
-const listenerId = await client.addListener(
-  "user:created",
-  { userId: 123 },  // info selector (서버와 공유되는 필터 정보)
-  async (data) => {
-    console.log("새 사용자:", data.name);
-  },
-);
-
-// 이벤트 발행 (특정 selector에 매칭하는 리스너에만 전송)
-await client.emitEvent(
-  "user:created",
-  (info) => info.userId === 123,
-  { name: "Alice", email: "alice@example.com" },
-);
-
-// 리스너 제거
-await client.removeListener(listenerId);
-```
-
-### File Upload & Download
-
-```typescript
-// 파일 업로드 (인증 필수)
-const files = [
-  new File(["content"], "file.txt", { type: "text/plain" }),
-];
-const results = await client.uploadFile(files);
-console.log("업로드 결과:", results);
-
-// 파일 다운로드
-const buffer = await client.downloadFileBuffer("/uploaded/file.txt");
-console.log("다운로드 바이트:", buffer.length);
-```
-
-### ORM Remote Execution
-
-```typescript
-import { createOrmClientConnector } from "@simplysm/service-client";
-
-const connector = createOrmClientConnector(client);
-
-const result = await connector.connect(
-  {
-    DbClass: MyDbContext,
-    connOpt: { configName: "main", username: "user", password: "pass" },
-  },
-  async (db) => {
-    return db.users.select().execute();
-  },
-);
-
-console.log("조회 결과:", result);
-```
-
-### Progress Tracking
-
-```typescript
-const progress = {
-  request: (state) => {
-    console.log(`요청 전송: ${state.completedSize}/${state.totalSize} bytes`);
-  },
-  response: (state) => {
-    console.log(`응답 수신: ${state.completedSize}/${state.totalSize} bytes`);
-  },
-  server: (state) => {
-    console.log(`서버 처리: ${state.completedSize}/${state.totalSize}`);
-  },
-};
-
-await client.send("Service", "method", [arg1, arg2], progress);
-```
-
-### Connection State & Events
-
-```typescript
-// 연결 상태 모니터링
-client.on("state", (state) => {
-  console.log("연결 상태:", state); // "connected" | "closed" | "reconnecting"
-});
-
-client.on("request-progress", (state) => {
-  console.log(`요청 진행: ${state.completedSize}/${state.totalSize}`);
-});
-
-// 연결 확인
-if (client.connected) {
-  console.log("서버에 연결됨");
-}
-```

package/claude/references/sd-simplysm14/service-common/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`으로 변환

package/claude/references/sd-simplysm14/service-common/docs/events.md

@@ -1,64 +0,0 @@
-# Events
-
-## `ServiceEventDef`
-
-`defineEvent()`로 생성된 이벤트 정의. `$info`와 `$data`는 런타임에서 사용되지 않는 타입 전용 마커다.
-
-```typescript
-export interface ServiceEventDef<TInfo = unknown, TData = unknown> {
-  eventName: string;
-  readonly $info: TInfo;
-  readonly $data: TData;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `eventName` | `string` | 이벤트 이름 |
-| `$info` | `TInfo` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 필터링 조건 타입 |
-| `$data` | `TData` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 페이로드 타입 |
-
-`TInfo`와 `TData`는 제네릭 파라미터로, `defineEvent<TInfo, TData>()` 호출 시 지정된 타입이 할당된다. 기본값은 `unknown`.
-
-## `defineEvent`
-
-타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
-
-```typescript
-export function defineEvent<TInfo = unknown, TData = unknown>(
-  eventName: string,
-): ServiceEventDef<TInfo, TData>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `eventName` | `string` | 이벤트 이름 (고유해야 함) |
-
-| Type Parameter | Default | Description |
-|---------------|---------|-------------|
-| `TInfo` | `unknown` | 이벤트 필터링 조건의 타입. 구독 시 필터로 사용 |
-| `TData` | `unknown` | 이벤트 페이로드의 타입. 이벤트 발생/수신 시 데이터 타입 |
-
-반환: `ServiceEventDef<TInfo, TData>` 인스턴스.
-
-사용 예:
-
-```typescript
-// 서버에서 이벤트 정의 + 타입 export
-export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
-
-// 서버에서 이벤트 발생 — getEvent() 프록시 방식 (권장)
-const orderEvt = server.getEvent<typeof OrderUpdated>("OrderUpdated");
-await orderEvt.emit((info) => info.orderId === 123, { status: "shipped" });
-
-// 클라이언트에서 구독 (import type으로 타입만 가져옴)
-import type { OrderUpdated } from "@server-package";
-const orderEvt = client.getEvent<typeof OrderUpdated>("OrderUpdated");
-const key = await orderEvt.addListener({ orderId: 123 }, async (data) => {
-  // data.status는 string으로 타입 추론됨
-});
-
-// 직접 호출 방식 (하위 호환)
-await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
-await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => { ... });
-```