@simplysm/sd-claude 14.0.51 → 14.0.52

package/claude/references/sd-simplysm-v14/service-common/README.md

@@ -0,0 +1,161 @@
+# @simplysm/service-common
+
+> 서비스 클라이언트(`@simplysm/service-client`)와 서버(`@simplysm/service-server`)가 공유하는 바이너리 프로토콜, 메시지 타입, 서비스 인터페이스, 앱 구조 정의 패키지.
+> 의존성: `@simplysm/core-common`, `@simplysm/orm-common`. Node.js 및 브라우저 양쪽에서 사용 가능.
+
+## 소비앱 설치 안내 (v14)
+
+v14에서는 `import type`으로 타입을 직접 가져올 수 있으므로, 이전 버전에서 클라이언트-서버 간 타입 공유를 위해 필요하던 중간 패키지(`@simplysm/service-common`, `@simplysm/orm-common`)는 **소비앱의 의존성으로 불필요**하다. 서버 패키지(`@simplysm/service-server`, `@simplysm/orm-node`)의 타입을 직접 import하여 사용한다.
+
+```typescript
+// v14: 서버 패키지에서 타입을 직접 import — common 패키지 의존성 불필요
+import type { ServiceMethods } from "@simplysm/service-server";
+```
+
+## Installation
+
+```bash
+npm install @simplysm/service-common
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| WebSocket 메시지 인코딩/디코딩 | [create-service-protocol.md](./protocol/create-service-protocol.md) |
+| 프로토콜 상수 확인 (크기 제한, 청킹 등) | [protocol-config.md](./protocol/protocol-config.md) |
+| 타입 안전 이벤트 정의 | [define-event.md](./events/define-event.md) |
+| 메뉴 트리·권한 구조 정의 | [app-structure-item.md](./app-structure/app-structure-item.md) |
+| 모듈 기반 권한 필터링 | [get-flat-permissions.md](./app-structure/get-flat-permissions.md) |
+| ORM 서비스 타입 계약 확인 | [orm-service.md](./service-types/orm-service.md) |
+| 메시지 타입 구조 파악 | [service-message.md](./protocol/service-message.md) |
+
+## API Overview
+
+### Protocol
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`PROTOCOL_CONFIG`](./protocol/protocol-config.md) | const | 프로토콜 크기 제한·청킹 임계값 등 설정 상수를 참조할 때 |
+| [`ServiceMessage`](./protocol/service-message.md) | type | 양방향 메시지의 전체 유니언과 방향별 하위 유니언을 참조할 때 |
+| [`ServiceProgressMessage`](./protocol/service-progress-message.md) | interface | 청크 수신 진행 상태를 처리할 때 |
+| [`ServiceErrorMessage`](./protocol/service-error-message.md) | interface | 서버 에러 응답을 처리할 때 |
+| [`ServiceAuthMessage`](./protocol/service-auth-message.md) | interface | 클라이언트 인증 토큰을 전송할 때 |
+| [`ServiceRequestMessage`](./protocol/service-request-message.md) | interface | 서비스 메서드를 호출할 때 |
+| [`ServiceResponseMessage`](./protocol/service-response-message.md) | interface | 서비스 메서드 응답을 처리할 때 |
+| [`ServiceAddEventListenerMessage`](./protocol/service-add-event-listener-message.md) | interface | 이벤트 리스너를 등록할 때 |
+| [`ServiceRemoveEventListenerMessage`](./protocol/service-remove-event-listener-message.md) | interface | 이벤트 리스너를 제거할 때 |
+| [`ServiceGetEventListenerInfosMessage`](./protocol/service-get-event-listener-infos-message.md) | interface | 등록된 이벤트 리스너 정보를 조회할 때 |
+| [`ServiceEmitEventMessage`](./protocol/service-emit-event-message.md) | interface | 클라이언트에서 이벤트를 발생시킬 때 |
+| [`ServiceEventMessage`](./protocol/service-event-message.md) | interface | 서버에서 수신된 이벤트 알림을 처리할 때 |
+| [`createServiceProtocol`](./protocol/create-service-protocol.md) | function | WebSocket 메시지를 인코딩/디코딩할 때 (자동 청킹·재조립 포함) |
+
+### Service Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`OrmService`](./service-types/orm-service.md) | interface | DB 연결·트랜잭션·쿼리 실행의 서버-클라이언트 타입 계약을 정의할 때 |
+| [`AutoUpdateService`](./service-types/auto-update-service.md) | interface | 클라이언트 자동 업데이트 버전 조회 타입 계약을 정의할 때 |
+| [`AppStructureService`](./service-types/app-structure-service.md) | interface | 앱 구조 항목을 서버에서 조회하는 타입 계약을 정의할 때 |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServiceUploadResult`](./types/service-upload-result.md) | interface | 파일 업로드 결과를 타입으로 사용할 때 |
+
+### App Structure
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`AppStructureItem`](./app-structure/app-structure-item.md) | type | 앱 메뉴 트리·권한 구조를 정의할 때 |
+| [`isUsableModules`](./app-structure/is-usable-modules.md) | function | 단일 항목의 모듈 접근 가능 여부를 판단할 때 |
+| [`isUsableModulesChain`](./app-structure/is-usable-modules-chain.md) | function | 트리 경로 전체의 모듈 접근 가능 여부를 판단할 때 |
+| [`getFlatPermissions`](./app-structure/get-flat-permissions.md) | function | 앱 구조 트리를 플래트닝하여 권한 목록을 얻을 때 |
+
+### Events
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`defineEvent`](./events/define-event.md) | function | 서버-클라이언트 간 타입 안전 이벤트를 정의할 때 |
+
+## Usage Examples
+
+### 프로토콜 인코딩/디코딩
+
+```typescript
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+
+// 메시지 인코딩 (3MB 초과 시 자동 청킹)
+const { chunks, totalSize } = protocol.encode(uuid, {
+  name: "OrmService.connect",
+  body: [{ configName: "default" }],
+});
+
+// 메시지 디코딩 (청크 자동 재조립)
+for (const chunk of chunks) {
+  const result = protocol.decode(chunk);
+  if (result.type === "complete") {
+    // result.message: 재조립된 메시지
+  }
+}
+
+// 사용 후 반드시 해제
+protocol.dispose();
+```
+
+### 타입 안전 이벤트 정의
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+// 서버에서 이벤트 정의 + 타입 export
+export const OrderUpdated = defineEvent<{ orderId: number }, { status: string }>("OrderUpdated");
+
+// 서버에서 이벤트 발생 (제네릭 타입 파라미터 + 문자열 이름 패턴)
+await server.emitEvent<typeof OrderUpdated>("OrderUpdated", (info) => info.orderId === 123, { status: "shipped" });
+
+// 클라이언트에서 구독 (import type으로 타입만 가져옴)
+import type { OrderUpdated } from "@server-package";
+await client.addListener<typeof OrderUpdated>("OrderUpdated", { orderId: 123 }, async (data) => {
+  // data.status는 string으로 타입 추론됨
+});
+```
+
+### 앱 구조 권한 플래트닝
+
+```typescript
+import { getFlatPermissions, isUsableModules } from "@simplysm/service-common";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const items: AppStructureItem<string>[] = [
+  {
+    code: "admin",
+    title: "관리",
+    children: [
+      { code: "user", title: "사용자", perms: ["use", "edit"] },
+    ],
+  },
+  {
+    code: "report",
+    title: "리포트",
+    modules: ["moduleA"],
+    perms: ["use"],
+  },
+];
+
+// 활성 모듈 기준으로 권한 플래트닝
+const perms = getFlatPermissions(items, ["moduleA"]);
+// [{ codeChain: ["admin", "user", "use"], ... }, { codeChain: ["admin", "user", "edit"], ... }, ...]
+
+// 개별 모듈 접근 가능 여부 확인
+const canAccess = isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true (OR 조건)
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 서버 로직 구현 (서비스 메서드 등록, WebSocket 핸들링) → `@simplysm/service-server`
+- 클라이언트에서 서버 호출 (RPC, 이벤트 구독) → `@simplysm/service-client`
+- v14 소비앱에서 타입만 필요할 때 → 서버 패키지에서 직접 `import type`

package/claude/references/sd-simplysm-v14/service-common/app-structure/app-structure-item.md

@@ -0,0 +1,107 @@
+# AppStructureItem
+
+앱 구조 항목 유니언 타입. `children` 필드 유무로 그룹(`AppStructureGroupItem`)과 리프(`AppStructureLeafItem`)를 구분한다.
+
+```typescript
+export type AppStructureItem<TModule = unknown> =
+  | AppStructureGroupItem<TModule>
+  | AppStructureLeafItem<TModule>;
+```
+
+`TModule` 제네릭은 모듈 식별자 타입이다 (일반적으로 `string`).
+
+## Related Types
+
+### `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`](./get-flat-permissions.md)의 반환 타입이다.
+
+```typescript
+export interface FlatPermission<TModule = unknown> {
+  titleChain: string[];
+  codeChain: string[];
+  modulesChain: TModule[][];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `titleChain` | `string[]` | 루트부터 현재 권한까지의 표시 이름 체인 (예: `["관리", "사용자"]`) |
+| `codeChain` | `string[]` | 루트부터 현재 권한까지의 코드 체인 (예: `["admin", "user", "use"]`) |
+| `modulesChain` | `TModule[][]` | 각 레벨에서 필요한 모듈 목록의 체인 |

package/claude/references/sd-simplysm-v14/service-common/app-structure/get-flat-permissions.md

@@ -0,0 +1,57 @@
+# getFlatPermissions
+
+앱 구조 트리를 BFS로 순회하며 모듈 조건을 필터링하여 [`FlatPermission`](./app-structure-item.md)`[]`으로 플래트닝한다.
+
+```typescript
+export function getFlatPermissions<TModule>(
+  items: AppStructureItem<TModule>[],
+  usableModules: TModule[] | undefined,
+): FlatPermission<TModule>[];
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `items` | `AppStructureItem<TModule>[]` | 앱 구조 트리의 최상위 항목 배열 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록. `undefined`이면 모듈 조건이 없는 항목만 포함 |
+
+## Returns
+
+`FlatPermission<TModule>[]` — 모듈 조건을 만족하는 모든 권한의 플랫 목록.
+
+처리 로직:
+1. BFS로 트리를 순회하며 각 레벨의 `modules`(OR)와 `requiredModules`(AND) 조건을 체크
+2. 조건 미충족 항목은 하위 트리 전체를 건너뜀
+3. `AppStructureLeafItem`의 `perms`를 `codeChain`에 추가하여 `FlatPermission` 생성
+4. `subPerms`도 개별 모듈 조건을 체크하여 `FlatPermission`으로 변환
+
+## Usage
+
+```typescript
+import { getFlatPermissions } from "@simplysm/service-common";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const items: AppStructureItem<string>[] = [
+  {
+    code: "admin",
+    title: "관리",
+    children: [
+      { code: "user", title: "사용자", perms: ["use", "edit"] },
+    ],
+  },
+  {
+    code: "report",
+    title: "리포트",
+    modules: ["moduleA"],
+    perms: ["use"],
+  },
+];
+
+const perms = getFlatPermissions(items, ["moduleA"]);
+// [
+//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "use"], modulesChain: [] },
+//   { titleChain: ["관리", "사용자"], codeChain: ["admin", "user", "edit"], modulesChain: [] },
+//   { titleChain: ["리포트"], codeChain: ["report", "use"], modulesChain: [["moduleA"]] },
+// ]
+```

package/claude/references/sd-simplysm-v14/service-common/app-structure/is-usable-modules-chain.md

@@ -0,0 +1,23 @@
+# isUsableModulesChain
+
+모듈 체인 전체의 접근 가능 여부를 판단한다. 트리의 각 레벨에서 모듈 조건을 모두 만족해야 한다.
+
+```typescript
+export function isUsableModulesChain<TModule>(
+  modulesChain: TModule[][],
+  requiredModulesChain: TModule[][],
+  usableModules: TModule[] | undefined,
+): boolean;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `modulesChain` | `TModule[][]` | 각 레벨의 OR 조건 모듈 배열 |
+| `requiredModulesChain` | `TModule[][]` | 각 레벨의 AND 조건 모듈 배열 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
+
+## Returns
+
+`boolean` — 모든 레벨의 조건을 만족하면 `true`. 하나라도 실패하면 `false`.

package/claude/references/sd-simplysm-v14/service-common/app-structure/is-usable-modules.md

@@ -0,0 +1,42 @@
+# isUsableModules
+
+단일 항목의 모듈 접근 가능 여부를 판단한다.
+
+```typescript
+export function isUsableModules<TModule>(
+  modules: TModule[] | undefined,
+  requiredModules: TModule[] | undefined,
+  usableModules: TModule[] | undefined,
+): boolean;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `modules` | `TModule[] \| undefined` | OR 조건 모듈 목록. 하나라도 `usableModules`에 포함되면 통과 |
+| `requiredModules` | `TModule[] \| undefined` | AND 조건 모듈 목록. 모두 `usableModules`에 포함되어야 통과 |
+| `usableModules` | `TModule[] \| undefined` | 사용자가 보유한 활성 모듈 목록 |
+
+## Returns
+
+`boolean` — `modules`와 `requiredModules` 조건을 모두 만족하면 `true`.
+
+- `modules`가 `undefined`이거나 빈 배열이면 OR 조건은 자동 통과
+- `requiredModules`가 `undefined`이거나 빈 배열이면 AND 조건은 자동 통과
+- `usableModules`가 `undefined`이면 `modules`가 있을 때 `false`
+
+## Usage
+
+```typescript
+import { isUsableModules } from "@simplysm/service-common";
+
+// OR 조건: moduleA 또는 moduleB 중 하나라도 있으면 true
+isUsableModules(["moduleA", "moduleB"], undefined, ["moduleA"]); // true
+
+// AND 조건: 모두 있어야 true
+isUsableModules(undefined, ["moduleA", "moduleB"], ["moduleA"]); // false
+
+// 모듈 없음: 자동 통과
+isUsableModules(undefined, undefined, undefined); // true
+```

package/claude/references/sd-simplysm-v14/service-common/events/define-event.md

@@ -0,0 +1,68 @@
+# defineEvent
+
+타입 안전한 서비스 이벤트를 정의하는 팩토리 함수.
+
+```typescript
+export function defineEvent<TInfo = unknown, TData = unknown>(
+  eventName: string,
+): ServiceEventDef<TInfo, TData>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `eventName` | `string` | 이벤트 이름 (고유해야 함) |
+
+| Type Parameter | Default | Description |
+|---------------|---------|-------------|
+| `TInfo` | `unknown` | 이벤트 필터링 조건의 타입. 구독 시 필터로 사용 |
+| `TData` | `unknown` | 이벤트 페이로드의 타입. 이벤트 발생/수신 시 데이터 타입 |
+
+## Returns
+
+`ServiceEventDef<TInfo, TData>` — 이벤트 정의 인스턴스.
+
+## Related Types
+
+### `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` | 타입 추출 전용 마커 (런타임에서 사용하지 않음). 이벤트 페이로드 타입 |
+
+## Usage
+
+```typescript
+import { defineEvent } from "@simplysm/service-common";
+
+// 서버에서 이벤트 정의 + 타입 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) => { /* ... */ });
+```

package/claude/references/sd-simplysm-v14/service-common/protocol/create-service-protocol.md

@@ -0,0 +1,93 @@
+# createServiceProtocol
+
+ServiceProtocol 인스턴스를 생성하는 팩토리 함수.
+
+```typescript
+export function createServiceProtocol(): ServiceProtocol;
+```
+
+내부에 `LazyGcMap` 기반 청크 누적기를 캡슐화한다. 미완성 메시지는 60초 후 GC로 자동 정리된다. 사용 후 반드시 `dispose()`를 호출하여 GC 타이머를 해제해야 한다.
+
+## Returns
+
+`ServiceProtocol` — 인코딩/디코딩/해제 메서드를 포함한 프로토콜 인스턴스.
+
+## Related Types
+
+### `ServiceProtocol`
+
+바이너리 프로토콜 V2 인코더/디코더 인터페이스.
+
+```typescript
+export interface ServiceProtocol {
+  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
+  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
+  dispose(): void;
+}
+```
+
+| Method | Parameters | Return | Description |
+|--------|-----------|--------|-------------|
+| `encode` | `uuid: string, message: ServiceMessage` | `{ chunks: Bytes[]; totalSize: number }` | 메시지를 인코딩한다. 3MB 초과 시 300KB 청크로 자동 분할. `totalSize` > 100MB이면 `ArgumentError` 발생 |
+| `decode` | `bytes: Bytes` | `ServiceMessageDecodeResult<T>` | 청크를 디코딩한다. 청크가 모두 도착하면 `complete`, 아니면 `progress` 반환 |
+| `dispose` | 없음 | `void` | 내부 GC 타이머와 청크 누적기를 해제한다. 사용 후 반드시 호출 |
+
+헤더 구조 (28바이트, Big Endian):
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 0 | 16 | UUID (바이너리) |
+| 16 | 8 | TotalSize (uint64, 상위 4바이트 = 0) |
+| 24 | 4 | Index (uint32) |
+
+### `ServiceMessageDecodeResult`
+
+메시지 디코딩 결과 유니언 타입. `type` 필드로 분기한다.
+
+```typescript
+export type ServiceMessageDecodeResult<TMessage extends ServiceMessage> =
+  | { type: "complete"; uuid: string; message: TMessage }
+  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
+```
+
+**Variant: `complete`** — 모든 청크가 도착하여 메시지 재조립이 완료된 상태.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"complete"` | discriminant |
+| `uuid` | `string` | 메시지 UUID |
+| `message` | `TMessage` | 재조립된 메시지 |
+
+**Variant: `progress`** — 청크 메시지 수신 진행 중.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"progress"` | discriminant |
+| `uuid` | `string` | 메시지 UUID |
+| `totalSize` | `number` | 전체 크기 (바이트) |
+| `completedSize` | `number` | 수신 완료된 크기 (바이트) |
+
+## Usage
+
+```typescript
+import { createServiceProtocol } from "@simplysm/service-common";
+
+const protocol = createServiceProtocol();
+
+// 메시지 인코딩 (3MB 초과 시 자동 청킹)
+const { chunks, totalSize } = protocol.encode(uuid, {
+  name: "OrmService.connect",
+  body: [{ configName: "default" }],
+});
+
+// 메시지 디코딩 (청크 자동 재조립)
+for (const chunk of chunks) {
+  const result = protocol.decode(chunk);
+  if (result.type === "complete") {
+    // result.message: 재조립된 메시지
+  }
+}
+
+// 사용 후 반드시 해제
+protocol.dispose();
+```

package/claude/references/sd-simplysm-v14/service-common/protocol/protocol-config.md

@@ -0,0 +1,21 @@
+# PROTOCOL_CONFIG
+
+서비스 프로토콜 설정 상수.
+
+```typescript
+export const PROTOCOL_CONFIG = {
+  MAX_TOTAL_SIZE: 100 * 1024 * 1024,
+  SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024,
+  CHUNK_SIZE: 300 * 1024,
+  GC_INTERVAL: 10 * 1000,
+  EXPIRE_TIME: 60 * 1000,
+} as const;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `MAX_TOTAL_SIZE` | `number` | 단일 메시지의 최대 허용 크기 (100MB). 초과 시 `ArgumentError` 발생 |
+| `SPLIT_MESSAGE_SIZE` | `number` | 이 크기를 초과하면 자동으로 청크 분할 (3MB) |
+| `CHUNK_SIZE` | `number` | 분할된 각 청크의 크기 (300KB) |
+| `GC_INTERVAL` | `number` | 내부 청크 누적기의 가비지 컬렉션 주기 (10초, 밀리초 단위) |
+| `EXPIRE_TIME` | `number` | 미완성 청크 메시지의 만료 시간 (60초). 이 시간 내에 모든 청크가 도착하지 않으면 제거 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-add-event-listener-message.md

@@ -0,0 +1,23 @@
+# ServiceAddEventListenerMessage
+
+클라이언트가 보내는 이벤트 리스너 추가 메시지.
+
+```typescript
+export interface ServiceAddEventListenerMessage {
+  name: "evt:add";
+  body: {
+    key: string;
+    name: string;
+    info: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:add"` | 고정 문자열 discriminant |
+| `body.key` | `string` | 리스너 키 (UUID). `ServiceRemoveEventListenerMessage`에서 사용 |
+| `body.name` | `string` | 이벤트 이름 (`ServiceEventDef.eventName`) |
+| `body.info` | `unknown` | 이벤트 발생 시 필터링을 위한 추가 리스너 정보 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-auth-message.md

@@ -0,0 +1,17 @@
+# ServiceAuthMessage
+
+클라이언트가 보내는 인증 메시지.
+
+```typescript
+export interface ServiceAuthMessage {
+  name: "auth";
+  body: string;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"auth"` | 고정 문자열 discriminant |
+| `body` | `string` | 인증 토큰 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-emit-event-message.md

@@ -0,0 +1,21 @@
+# ServiceEmitEventMessage
+
+클라이언트가 보내는 이벤트 발생 메시지.
+
+```typescript
+export interface ServiceEmitEventMessage {
+  name: "evt:emit";
+  body: {
+    keys: string[];
+    data: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"evt:emit"` | 고정 문자열 discriminant |
+| `body.keys` | `string[]` | 대상 리스너 키 목록 |
+| `body.data` | `unknown` | 이벤트 데이터 |

package/claude/references/sd-simplysm-v14/service-common/protocol/service-error-message.md

@@ -0,0 +1,29 @@
+# ServiceErrorMessage
+
+서버가 보내는 에러 알림 메시지.
+
+```typescript
+export interface ServiceErrorMessage {
+  name: "error";
+  body: {
+    name: string;
+    message: string;
+    code: string;
+    stack?: string;
+    detail?: unknown;
+    cause?: unknown;
+  };
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `"error"` | 고정 문자열 discriminant |
+| `body.name` | `string` | 에러 이름 (클래스명) |
+| `body.message` | `string` | 에러 메시지 |
+| `body.code` | `string` | 에러 코드 |
+| `body.stack` | `string?` | 스택 트레이스 (선택) |
+| `body.detail` | `unknown?` | 추가 상세 정보 (선택) |
+| `body.cause` | `unknown?` | 원인 에러 (선택) |