@simplysm/sd-claude 14.0.42 → 14.0.44

package/claude/references/sd-simplysm14/sd-cli/usage.md

@@ -40,6 +40,14 @@ npm install @simplysm/sd-cli
 | `SdConfigParams` | interface | sd.config.ts 함수에 전달되는 매개변수 |
 | `SdConfigFn` | type | sd.config.ts default export 함수 타입 |
 
+### TypeScript Compiler
+
+| API | Type | Description |
+|-----|------|-------------|
+| `SdTsCompiler` | class | TypeScript AOT 컴파일러 (Angular 및 일반 TS 패키지 지원) |
+| `ISdTsCompilerOptions` | interface | SdTsCompiler 생성 옵션 |
+| `ISdTsCompilerResult` | interface | SdTsCompiler.compileAsync() 반환 타입 |
+
 ### Angular Vite Plugin
 
 | API | Type | Description |
@@ -47,6 +55,127 @@ npm install @simplysm/sd-cli
 | `SdAngularPluginOptions` | interface | sdAngularPlugin 옵션 |
 | `sdAngularPlugin` | function | Angular AOT 컴파일을 수행하는 Vite 플러그인 |
 
+## TypeScript Compiler 상세
+
+### `SdTsCompiler`
+
+TypeScript AOT 컴파일러. Angular 패키지와 일반 TypeScript 패키지 모두 지원하며 증분 빌드, lint 통합, SCSS 컴파일을 관리한다.
+
+```typescript
+export class SdTsCompiler {
+  constructor(options: ISdTsCompilerOptions);
+  
+  async compileAsync(
+    modifiedFiles?: ReadonlySet<string>,
+    emitOptions?: ISdTsCompilerEmitOptions,
+  ): Promise<ISdTsCompilerResult>;
+  
+  compileSideEffectScss(): void;
+  
+  findAffectedByScss(scssPath: string): string[];
+  
+  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `compileAsync()` | TypeScript 컴파일 실행. modifiedFiles 지정 시 증분 빌드 수행. emitOptions로 emit 방식 제어 |
+| `compileSideEffectScss()` | sideEffectScssRegistry의 모든 항목을 SCSS로 컴파일 |
+| `findAffectedByScss()` | SCSS 경로에 의존하는 TypeScript 파일 목록 반환 (watch 역방향 추적용) |
+| `sideEffectScssRegistry` | getter. Angular component @Component.styles 항목 저장소 |
+
+### `ISdTsCompilerOptions`
+
+SdTsCompiler 생성 옵션.
+
+```typescript
+export interface ISdTsCompilerOptions {
+  pkgDir: string;
+  cwd: string;
+  output: { js: boolean; dts: boolean };
+  includeTests?: boolean;
+  env?: TypecheckEnv;
+  sourceFileCache?: AngularSourceFileCache;
+  transformStylesheet?: (data: string, containingFile: string, stylesheetFile?: string) => Promise<string | null>;
+  externalStylesheets?: Map<string, string>;
+  compilerOptionsTransformer?: (options: ts.CompilerOptions) => ts.CompilerOptions;
+  lint?: boolean;
+  globalScss?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pkgDir` | `string` | 패키지 디렉토리 (절대 경로) |
+| `cwd` | `string` | workspace 루트 (diagnostics 필터링 등에 사용) |
+| `output` | `{ js: boolean; dts: boolean }` | emit 제어: js (JavaScript emit), dts (타입 선언 emit) |
+| `includeTests` | `boolean?` | tests/ 파일을 rootNames에 포함할지 여부 (기본값: false) |
+| `env` | `TypecheckEnv?` | 타입체크 환경. 설정 시 getCompilerOptionsForEnv() 적용 |
+| `sourceFileCache` | `AngularSourceFileCache?` | Angular 증분 빌드용 SourceFile 캐시. 미제공 시 내부 생성 |
+| `transformStylesheet` | `(data: string, containingFile: string, stylesheetFile?: string) => Promise<string \| null>?` | 스타일시트 변환 콜백 (Angular only) |
+| `externalStylesheets` | `Map<string, string>?` | 외부 스타일시트 맵 (클라이언트 빌드용, resourceNameToFileName에서 사용) |
+| `compilerOptionsTransformer` | `(options: ts.CompilerOptions) => ts.CompilerOptions?` | compilerOptions 후처리 (클라이언트의 target/module 강제 등) |
+| `lint` | `boolean?` | lint 실행 여부. true이면 compileAsync 결과에 lint 결과 포함 |
+| `globalScss` | `boolean?` | 글로벌 SCSS 컴파일 여부. true이면 scss/styles.scss → dist/styles.css 생성 |
+
+### `ISdTsCompilerEmitOptions`
+
+compileAsync()의 emit 옵션. Angular 컴파일러만 지원.
+
+```typescript
+export interface ISdTsCompilerEmitOptions {
+  sourceFilter?: (fileName: string) => boolean;
+  additionalTransformers?: {
+    before?: ts.TransformerFactory<ts.SourceFile>[];
+    after?: ts.TransformerFactory<ts.SourceFile>[];
+  };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sourceFilter` | `(fileName: string) => boolean?` | emit 대상 소스 필터 (지정 시 해당 파일만 EmitResult에 포함). Angular only |
+| `additionalTransformers` | `{ before?: ts.TransformerFactory<ts.SourceFile>[]; after?: ts.TransformerFactory<ts.SourceFile>[]; }?` | Angular transformers 외 추가 transformers. Angular only |
+
+### `ISdTsCompilerResult`
+
+compileAsync() 반환 타입.
+
+```typescript
+export interface ISdTsCompilerResult {
+  program: ts.Program;
+  builderProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram;
+  isForAngular: boolean;
+  affectedFiles: ReadonlySet<string> | undefined;
+  diagnostics: SerializedDiagnostic[];
+  errorCount: number;
+  warningCount: number;
+  errors?: string[];
+  ngtscProgram?: NgtscProgram;
+  emitResults?: EmitResult[];
+  lint?: LintWithProgramResult;
+  scssErrors: string[];
+  scssDependencies: ReadonlyMap<string, ReadonlySet<string>>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `program` | `ts.Program` | TypeScript Program 참조 (lint, 외부 도구용) |
+| `builderProgram` | `ts.EmitAndSemanticDiagnosticsBuilderProgram` | Builder Program 참조 (증분 빌드 상태) |
+| `isForAngular` | `boolean` | Angular 패키지 여부 (tsconfig.json에 angularCompilerOptions 존재) |
+| `affectedFiles` | `ReadonlySet<string> \| undefined` | 이 빌드에서 영향받은 파일 (posix 경로). undefined = 전역 변경 (전체 리빌드) |
+| `diagnostics` | `SerializedDiagnostic[]` | 직렬화된 진단 정보 (Worker 경계 통과용) |
+| `errorCount` | `number` | Error 카테고리 진단 수 |
+| `warningCount` | `number` | Warning 카테고리 진단 수 |
+| `errors` | `string[]?` | Error 카테고리 진단을 "파일:줄:열: TS코드: 메시지" 형식으로 포맷한 배열 |
+| `ngtscProgram` | `NgtscProgram?` | NgtscProgram 참조 (Angular only, HMR용). Non-Angular이면 undefined |
+| `emitResults` | `EmitResult[]?` | Angular emit 결과 (Non-Angular이면 undefined — writeFile 훅으로 디스크 직접 쓰기) |
+| `lint` | `LintWithProgramResult?` | lint 결과 (lint 옵션 활성 시) |
+| `scssErrors` | `string[]` | SCSS 컴파일 에러 목록 |
+| `scssDependencies` | `ReadonlyMap<string, ReadonlySet<string>>` | SCSS 의존성 맵 (소유자 파일 → 의존 SCSS 경로 집합). watch 역방향 탐색용 |
+
 ## Config 상세
 
 ### `NpmConfig`
@@ -407,7 +536,7 @@ export interface SdClientPackageConfig {
 | `capacitor` | `SdCapacitorConfig?` | Capacitor 설정 |
 | `electron` | `SdElectronConfig?` | Electron 설정 |
 | `configs` | `Record<string, unknown>?` | 런타임 설정 (빌드 시 dist/.config.json으로 기록) |
-| `exclude` | `string[]?` | Vite optimizeDeps에서 제외하고 Capacitor/Electron package.json에 추가할 패키지 |
+| `exclude` | `string[]?` | Capacitor/Electron package.json에 추가할 패키지 |
 | `browserSupport` | `SdBrowserSupportConfig?` | 브라우저 지원 설정 |
 | `pwa` | `false \| SdPwaConfig?` | PWA 설정. false이면 비활성화. 미지정 시 기본값으로 활성화 |
 
@@ -572,6 +701,52 @@ Vite 훅: `config` (pkgDir 초기화), `watchChange` (파일 변경 추적), `bu
 
 ## Usage Examples
 
+### SdTsCompiler를 사용한 TypeScript 컴파일
+
+```typescript
+import { SdTsCompiler } from "@simplysm/sd-cli";
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/workspace/packages/my-lib",
+  cwd: "/workspace",
+  output: { js: true, dts: true },
+  lint: true,
+  globalScss: true,
+});
+
+// 초기 컴파일
+const result = await compiler.compileAsync();
+
+if (result.errors) {
+  console.error("Compilation errors:", result.errors);
+  process.exit(1);
+}
+
+console.log(`Compiled ${result.affectedFiles?.size ?? "all"} files`);
+```
+
+### watch 모드에서 증분 컴파일
+
+```typescript
+import { SdTsCompiler } from "@simplysm/sd-cli";
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/workspace/packages/my-lib",
+  cwd: "/workspace",
+  output: { js: true, dts: true },
+});
+
+// 초기 컴파일
+let result = await compiler.compileAsync();
+
+// 파일 변경 감지 시 증분 컴파일
+const changedFiles = new Set(["/workspace/packages/my-lib/src/foo.ts"]);
+result = await compiler.compileAsync(changedFiles);
+
+// SCSS 의존성이 변경된 TS 파일 찾기
+const affectedByScss = compiler.findAffectedByScss("/workspace/packages/my-lib/scss/variables.scss");
+```
+
 ### sd.config.ts 작성
 
 ```typescript

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

@@ -1,6 +1,6 @@
 # @simplysm/service-client
 
-WebSocket 기반 서비스 서버 클라이언트. 서비스 호출, 실시간 이벤트, 파일 업로드/다운로드, ORM 원격 실행을 지원한다.
+WebSocket 기반 서비스 서버 클라이언트로, 서비스 호출, 실시간 이벤트 구독/발행, 파일 업로드/다운로드, ORM 원격 실행을 지원한다.
 
 ## Installation
 
@@ -10,118 +10,142 @@ npm install @simplysm/service-client
 
 ## API Overview
 
-### Types
+### Core Client
 
 | API | Type | Description |
 |-----|------|-------------|
-| `BlobInput` | type | Blob constructor가 허용하는 데이터 타입 (DOM BlobPart 대체) |
-| `FileCollection` | interface | File 컬렉션 인터페이스 (DOM FileList 대체) |
-| `WorkerLike` | interface | Web Worker 인터페이스 (DOM Worker 대체) |
-| `isWorkerSupported` | function | Web Worker API 지원 여부 확인 |
-| `createBrowserWorker` | function | Web Worker 생성 (미지원 환경이면 undefined 반환) |
-| `ServiceConnectionOptions` | interface | 서비스 연결 옵션 (host, port, ssl, maxReconnectCount) |
-| `ServiceProgress` | interface | 요청/응답/서버 progress 콜백 컨테이너 |
-| `ServiceProgressState` | interface | progress 상태 (uuid, totalSize, completedSize) |
+| `ServiceClient` | class | WebSocket 서비스 클라이언트 최상위 파사드 (연결, RPC, 이벤트, 파일, ORM 통합) |
+| `createServiceClient()` | function | ServiceClient 인스턴스 생성 팩토리 함수 |
+| `ServiceProxy<T>` | type | 서비스 메서드 반환 타입을 Promise로 래핑하는 타입 변환기 |
 
-→ See [docs/types.md](./docs/types.md) for details.
+→ See [docs/main.md](./docs/main.md) for details.
 
-### Transport
+### Transport Layer
 
 | API | Type | Description |
 |-----|------|-------------|
-| `SocketProviderEvents` | interface | SocketProvider 이벤트 타입 맵 (message, state) |
-| `SocketProvider` | interface | WebSocket 래퍼 인터페이스 (연결, 재연결, 하트비트) |
-| `createSocketProvider` | function | SocketProvider 팩토리. URL, clientName, maxReconnectCount로 생성 |
-| `ServiceTransportEvents` | interface | ServiceTransport 이벤트 타입 맵 (event) |
-| `ServiceTransport` | interface | 요청-응답 매핑, progress 중계, 이벤트 디스패치 인터페이스 |
-| `createServiceTransport` | function | ServiceTransport 팩토리. SocketProvider와 ClientProtocolWrapper 조합 |
+| `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
+### Protocol & Encoding
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ClientProtocolWrapper` | interface | 인코딩/디코딩 인터페이스 (30KB 이상이면 Web Worker로 오프로드) |
-| `createClientProtocolWrapper` | function | ClientProtocolWrapper 팩토리. ServiceProtocol을 래핑 |
+| `ClientProtocolWrapper` | interface | 메시지 인코딩/디코딩 (30KB 이상 시 Web Worker 오프로드) |
+| `createClientProtocolWrapper()` | function | ClientProtocolWrapper 팩토리. ServiceProtocol 래핑 |
 
 → See [docs/protocol.md](./docs/protocol.md) for details.
 
-### Features
+### Event Management
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ClientEventProxy` | interface | `getEvent()`가 반환하는 이벤트 프록시 (이벤트 이름+타입 캡처) |
-| `EventClient` | interface | 서버 이벤트 구독/발행 인터페이스 (재연결 시 자동 재구독) |
-| `createEventClient` | function | EventClient 팩토리. ServiceTransport를 사용 |
-| `FileClient` | interface | 파일 업로드(POST)/다운로드(GET) 인터페이스 |
-| `createFileClient` | function | FileClient 팩토리. hostUrl과 clientName으로 생성 |
-| `OrmConnectOptions` | interface | ORM 연결 옵션 (DbClass, connOpt, dbContextOpt) |
-| `OrmClientConnector` | interface | DbContext 트랜잭션 연결 헬퍼 인터페이스 |
-| `createOrmClientConnector` | function | OrmClientConnector 팩토리. ServiceClient를 사용 |
-| `OrmClientDbContextExecutor` | class | DbContextExecutor 구현체 (서버로 원격 호출) |
+| `EventClient` | interface | 서버 이벤트 구독/발행 관리 (재연결 시 자동 재구독) |
+| `createEventClient()` | function | EventClient 팩토리. ServiceTransport 사용 |
+| `ClientEventProxy<T>` | interface | 특정 이벤트에 대한 프록시 인터페이스 |
 
 → See [docs/features.md](./docs/features.md) for details.
 
-### Main
+### File Operations
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ServiceClient` | class | 최상위 파사드 클래스. WebSocket 연결, 서비스 호출, 이벤트, 파일, ORM 통합 |
-| `ServiceProxy` | type | 서비스 메서드 반환 타입을 Promise로 래핑하는 유틸리티 타입 |
-| `createServiceClient` | function | ServiceClient 팩토리 함수 |
+| `FileClient` | interface | 파일 업로드(POST)/다운로드(GET) 인터페이스 |
+| `createFileClient()` | function | FileClient 팩토리. hostUrl과 clientName으로 생성 |
 
-→ See [docs/main.md](./docs/main.md) for details.
+### 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
 
-### 서비스 연결 및 RPC 호출
+### Basic Service Connection & RPC
 
 ```typescript
-import { ServiceClient } from "@simplysm/service-client";
+import { createServiceClient } from "@simplysm/service-client";
 
-const client = new ServiceClient("my-app", {
+const client = createServiceClient("my-app", {
   host: "localhost",
   port: 3000,
   ssl: false,
+  maxReconnectCount: 10,  // 자동 재연결 (0으로 비활성화)
 });
 
 await client.connect();
-await client.auth("my-auth-token");
+await client.auth("jwt-token");
 
 // 타입 안전한 서비스 프록시
 const userSvc = client.getService<UserService>("User");
-const users = await userSvc.getList();
+const users = await userSvc.getAll();
 
 await client.close();
 ```
 
-### 이벤트 구독
+### Event Subscription
 
 ```typescript
-import { defineEvent } from "@simplysm/service-common";
+// 이벤트 리스너 등록 (selector로 필터링)
+const listenerId = await client.addListener(
+  "user:created",
+  { userId: 123 },  // info selector (서버와 공유되는 필터 정보)
+  async (data) => {
+    console.log("새 사용자:", data.name);
+  },
+);
 
-// 서버에서 이벤트 정의 + 타입 export
-export const ChatEvent = defineEvent<{ roomId: string }, { message: string }>("Chat");
+// 이벤트 발행 (특정 selector에 매칭하는 리스너에만 전송)
+await client.emitEvent(
+  "user:created",
+  (info) => info.userId === 123,
+  { name: "Alice", email: "alice@example.com" },
+);
 
-// 클라이언트에서 import type으로 타입만 가져옴
-// import type { ChatEvent } from "@server-package";
+// 리스너 제거
+await client.removeListener(listenerId);
+```
 
-// 이벤트 프록시 방식 (권장 — getService()와 동일한 패턴)
-const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
-const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
-  // data.message는 string으로 타입 추론
-});
-await chatEvt.removeListener(key);
+### File Upload & Download
 
-// 직접 호출 방식 (하위 호환)
-const key2 = await client.addListener<typeof ChatEvent>("Chat", { roomId: "room-1" }, async (data) => {
-  // data.message는 string으로 타입 추론
-});
-await client.removeListener(key2);
+```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 원격 연결
+### ORM Remote Execution
 
 ```typescript
 import { createOrmClientConnector } from "@simplysm/service-client";
@@ -129,9 +153,50 @@ import { createOrmClientConnector } from "@simplysm/service-client";
 const connector = createOrmClientConnector(client);
 
 const result = await connector.connect(
-  { DbClass: MyDbContext, connOpt: { configName: "main" } },
+  {
+    DbClass: MyDbContext,
+    connOpt: { configName: "main", username: "user", password: "pass" },
+  },
   async (db) => {
-    return db.myTable.select((item) => ({ id: item.id, name: item.name }));
+    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/usage.md

@@ -1,6 +1,6 @@
 # @simplysm/service-common
 
-서비스 클라이언트와 서버가 공유하는 프로토콜, 메시지 타입, 서비스 인터페이스, 앱 구조 정의 패키지.
+서비스 클라이언트와 서버가 공유하는 바이너리 프로토콜, 메시지 타입, 서비스 인터페이스, 앱 구조 정의 패키지.
 
 ## Installation
 
@@ -15,23 +15,23 @@ npm install @simplysm/service-common
 | API | Type | Description |
 |-----|------|-------------|
 | `PROTOCOL_CONFIG` | const | 프로토콜 설정 상수 (최대 크기, 청킹 임계값, 청크 크기, GC 주기, 만료 시간) |
-| `ServiceMessage` | type | 모든 서비스 메시지의 유니언 타입 |
-| `ServiceServerMessage` | type | 서버 → 클라이언트 메시지 유니언 (응답, 에러, 이벤트 알림) |
-| `ServiceServerRawMessage` | type | `ServiceProgressMessage \| ServiceServerMessage` |
-| `ServiceClientMessage` | type | 클라이언트 → 서버 메시지 유니언 (요청, 인증, 이벤트 관련) |
-| `ServiceProgressMessage` | interface | 청크 수신 진행 상태 알림 메시지 |
-| `ServiceErrorMessage` | interface | 서버 에러 알림 메시지 |
+| `ServiceMessage` | type | 양방향 메시지의 유니언 타입 |
+| `ServiceClientMessage` | type | 클라이언트 → 서버 메시지 유니언 |
+| `ServiceServerMessage` | type | 서버 → 클라이언트 메시지 유니언 |
+| `ServiceServerRawMessage` | type | 진행 상태를 포함한 서버 메시지 유니언 |
+| `ServiceProgressMessage` | interface | 청크 수신 진행 상태 알림 |
+| `ServiceErrorMessage` | interface | 서버 에러 알림 |
 | `ServiceAuthMessage` | interface | 클라이언트 인증 메시지 (토큰) |
-| `ServiceRequestMessage` | interface | 서비스 메서드 요청 메시지 |
-| `ServiceResponseMessage` | interface | 서비스 메서드 응답 메시지 |
-| `ServiceAddEventListenerMessage` | interface | 이벤트 리스너 추가 메시지 |
-| `ServiceRemoveEventListenerMessage` | interface | 이벤트 리스너 제거 메시지 |
-| `ServiceGetEventListenerInfosMessage` | interface | 이벤트 리스너 정보 목록 요청 메시지 |
-| `ServiceEmitEventMessage` | interface | 이벤트 발생 메시지 |
-| `ServiceEventMessage` | interface | 서버 이벤트 알림 메시지 |
-| `ServiceProtocol` | interface | 바이너리 프로토콜 인코더/디코더 인터페이스 |
-| `ServiceMessageDecodeResult` | type | 디코딩 결과 (complete 또는 progress) |
-| `createServiceProtocol` | function | ServiceProtocol 인스턴스 팩토리 함수 |
+| `ServiceRequestMessage` | interface | 서비스 메서드 요청 |
+| `ServiceResponseMessage` | interface | 서비스 메서드 응답 |
+| `ServiceAddEventListenerMessage` | interface | 이벤트 리스너 추가 요청 |
+| `ServiceRemoveEventListenerMessage` | interface | 이벤트 리스너 제거 요청 |
+| `ServiceGetEventListenerInfosMessage` | interface | 이벤트 리스너 정보 목록 요청 |
+| `ServiceEmitEventMessage` | interface | 이벤트 발생 요청 |
+| `ServiceEventMessage` | interface | 서버 이벤트 알림 |
+| `ServiceProtocol` | interface | 바이너리 프로토콜 인코더/디코더 |
+| `ServiceMessageDecodeResult` | type | 디코딩 결과 유니언 (complete \| progress) |
+| `createServiceProtocol` | function | ServiceProtocol 인스턴스 생성 팩토리 |
 
 → See [docs/protocol.md](./docs/protocol.md) for details.
 
@@ -39,10 +39,10 @@ npm install @simplysm/service-common
 
 | API | Type | Description |
 |-----|------|-------------|
-| `OrmService` | interface | DB 연결, 트랜잭션 관리, 쿼리 실행 인터페이스 |
-| `DbConnOptions` | type | 데이터베이스 연결 옵션 |
-| `AutoUpdateService` | interface | 클라이언트 최신 버전 정보 조회 인터페이스 |
-| `AppStructureService` | interface | 서버에 등록된 앱 구조 항목을 클라이언트명 기준 맵으로 조회하는 인터페이스 |
+| `OrmService` | interface | DB 연결, 트랜잭션, 쿼리 실행 서비스 인터페이스 |
+| `DbConnOptions` | type | DB 연결 옵션 타입 |
+| `AutoUpdateService` | interface | 클라이언트 최신 버전 조회 서비스 인터페이스 |
+| `AppStructureService` | interface | 앱 구조 항목 조회 서비스 인터페이스 |
 
 → See [docs/service-types.md](./docs/service-types.md) for details.
 
@@ -50,7 +50,7 @@ npm install @simplysm/service-common
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ServiceUploadResult` | interface | 파일 업로드 결과 (경로, 파일명, 크기) |
+| `ServiceUploadResult` | interface | 파일 업로드 결과 |
 
 → See [docs/types.md](./docs/types.md) for details.
 
@@ -58,14 +58,14 @@ npm install @simplysm/service-common
 
 | API | Type | Description |
 |-----|------|-------------|
-| `AppStructureItem` | type | 앱 구조 항목 유니언 (그룹 또는 리프) |
+| `AppStructureItem` | type | 앱 구조 항목 (그룹 또는 리프) |
 | `AppStructureGroupItem` | interface | 자식을 가진 그룹 메뉴 항목 |
 | `AppStructureLeafItem` | interface | 말단 메뉴 항목 (권한, URL 포함) |
 | `AppStructureSubPermission` | interface | 리프 항목의 하위 권한 정의 |
-| `FlatPermission` | interface | 트리를 플래트닝한 권한 결과 |
-| `isUsableModules` | function | 모듈 접근 가능 여부 판단 (modules OR, requiredModules AND) |
+| `FlatPermission` | interface | 플래트닝된 권한 결과 |
+| `isUsableModules` | function | 개별 항목의 모듈 접근 가능 여부 판단 |
 | `isUsableModulesChain` | function | 모듈 체인 전체의 접근 가능 여부 판단 |
-| `getFlatPermissions` | function | 앱 구조 트리를 모듈 조건 필터링하여 FlatPermission[]으로 플래트닝 |
+| `getFlatPermissions` | function | 앱 구조 트리를 플래트닝하여 권한 배열 반환 |
 
 → See [docs/app-structure.md](./docs/app-structure.md) for details.
 
@@ -73,8 +73,8 @@ npm install @simplysm/service-common
 
 | API | Type | Description |
 |-----|------|-------------|
-| `ServiceEventDef` | interface | defineEvent()로 생성된 이벤트 정의 (타입 마커 포함) |
-| `defineEvent` | function | 타입 안전한 서비스 이벤트를 정의하는 팩토리 함수 |
+| `ServiceEventDef` | interface | 타입 안전 이벤트 정의 인터페이스 |
+| `defineEvent` | function | 타입 안전 이벤트를 정의하는 팩토리 함수 |
 
 → See [docs/events.md](./docs/events.md) for details.