@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-pwa-config.md

@@ -0,0 +1,41 @@
+# SdPwaConfig
+
+PWA(Progressive Web App) 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `pwa` 필드에 사용한다.
+
+```typescript
+export interface SdPwaConfig {
+  manifest?: SdPwaManifestConfig;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `manifest` | `SdPwaManifestConfig?` | PWA manifest 설정 |
+
+## Related Types
+
+### `SdPwaManifestConfig`
+
+PWA `manifest.json` 설정.
+
+```typescript
+export interface SdPwaManifestConfig {
+  name?: string;
+  short_name?: string;
+  display?: "standalone" | "fullscreen" | "minimal-ui" | "browser";
+  theme_color?: string;
+  background_color?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string }>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string?` | 앱 이름 |
+| `short_name` | `string?` | 앱 짧은 이름 |
+| `display` | `"standalone" \| "fullscreen" \| "minimal-ui" \| "browser"?` | 디스플레이 모드 |
+| `theme_color` | `string?` | 테마 색상 (hex 코드) |
+| `background_color` | `string?` | 배경 색상 (hex 코드) |
+| `icons` | `Array<{ src: string; sizes: string; type?: string }>?` | 아이콘 목록 |

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-scripts-package-config.md

@@ -0,0 +1,19 @@
+# SdScriptsPackageConfig
+
+`scripts` 타겟 패키지 설정. 빌드 엔진이 없으며, `watch` 훅이 설정된 경우에만 watch/typecheck 대상에 포함된다.
+
+```typescript
+export interface SdScriptsPackageConfig {
+  target: "scripts";
+  publish?: SdPublishConfig;
+  watch?: SdWatchHookConfig;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"scripts"` | 빌드 타겟 식별자 |
+| `publish` | [`SdPublishConfig?`](./sd-publish-config.md) | 배포 설정 |
+| `watch` | [`SdWatchHookConfig?`](./sd-watch-hook-config.md) | watch 훅 설정. 설정 시 watch 모드에 패키지가 포함된다 |

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-server-package-config.md

@@ -0,0 +1,32 @@
+# SdServerPackageConfig
+
+`server` 타겟 패키지 설정. esbuild로 단일 번들 빌드되며 Fastify 서버로 실행된다.
+
+```typescript
+export interface SdServerPackageConfig {
+  target: "server";
+  env?: Record<string, string>;
+  publish?: SdPublishConfig;
+  configs?: Record<string, unknown>;
+  externals?: string[];
+  pm2?: {
+    name?: string;
+    ignoreWatchPaths?: string[];
+  };
+  packageManager?: "volta" | "mise";
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"server"` | 빌드 타겟 식별자 |
+| `env` | `Record<string, string>?` | 빌드 시 치환할 환경 변수. `process.env.KEY`를 상수로 치환 |
+| `publish` | [`SdPublishConfig?`](./sd-publish-config.md) | 배포 설정 |
+| `configs` | `Record<string, unknown>?` | 런타임 설정. 빌드 시 `dist/.config.json`으로 기록 |
+| `externals` | `string[]?` | esbuild 번들에 포함하지 않을 외부 모듈. 자동 `binding.gyp` 감지 목록에 추가 |
+| `pm2` | `{ name?: string; ignoreWatchPaths?: string[] }?` | PM2 설정. 지정 시 `dist/pm2.config.cjs` 생성 |
+| `pm2.name` | `string?` | PM2 프로세스 이름. 미지정 시 `package.json`의 `name`에서 생성 |
+| `pm2.ignoreWatchPaths` | `string[]?` | PM2 watch에서 제외할 경로 |
+| `packageManager` | `"volta" \| "mise"?` | 사용할 패키지 매니저. `mise.toml` 또는 `volta` 설정 생성에 영향 |

package/claude/references/sd-simplysm-v14/sd-cli/config/sd-watch-hook-config.md

@@ -0,0 +1,19 @@
+# SdWatchHookConfig
+
+watch 모드에서 파일 변경을 감지하고 명령어를 실행하는 훅 설정. [`SdBuildPackageConfig`](./sd-build-package-config.md) 및 [`SdScriptsPackageConfig`](./sd-scripts-package-config.md)의 `watch` 필드에 사용한다.
+
+```typescript
+export interface SdWatchHookConfig {
+  target: string[];
+  cmd: string;
+  args?: string[];
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `string[]` | 감시할 glob 패턴 목록. 패키지 디렉토리 기준 상대 경로 |
+| `cmd` | `string` | 파일 변경 시 실행할 명령어 |
+| `args` | `string[]?` | 명령어 인수 |

package/claude/references/sd-simplysm-v14/sd-cli/ts-compiler/sd-ts-compiler.md

@@ -0,0 +1,158 @@
+# SdTsCompiler
+
+TypeScript AOT 컴파일러. Angular 패키지(`angularCompilerOptions`가 `tsconfig.json`에 있는 경우)와 일반 TypeScript 패키지를 모두 지원한다. 증분 빌드, lint 통합, SCSS 컴파일을 관리한다.
+
+## When to use
+
+- ✅ Angular/TS 패키지를 프로그래매틱하게 컴파일해야 할 때 (커스텀 빌드 파이프라인, Vite 플러그인 내부 등)
+- ✅ 증분 빌드가 필요한 watch 모드 구현 시
+- ❌ CLI 명령어로 빌드할 때 — `pnpm build`/`pnpm watch` 사용. `SdTsCompiler`는 sd-cli 내부 엔진과 [`sdAngularPlugin`](../angular-vite-plugin/sd-angular-plugin.md)에서 사용하는 저수준 API
+
+```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>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `compileAsync` | method | `(modifiedFiles?, emitOptions?) => Promise<ISdTsCompilerResult>` | TypeScript 컴파일 실행. `modifiedFiles` 지정 시 증분 빌드 수행 |
+| `compileSideEffectScss` | method | `() => void` | `sideEffectScssRegistry`의 모든 항목을 CSS로 컴파일 |
+| `findAffectedByScss` | method | `(scssPath: string) => string[]` | SCSS 경로에 의존하는 TypeScript 파일 목록 반환. watch 역방향 추적용 |
+| `sideEffectScssRegistry` | getter | `Map<string, SideEffectScssEntry>` | Angular 컴포넌트 `@Component.styles` 항목 저장소 |
+
+## Related Types
+
+### `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, containingFile, stylesheetFile?) => Promise<string \| null>?` | 스타일시트 변환 콜백. Angular 패키지 전용 |
+| `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` 생성 |
+
+### `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` 존재 시 `true` |
+| `affectedFiles` | `ReadonlySet<string> \| undefined` | 이 빌드에서 영향받은 파일 (posix 경로). `undefined` = 전역 변경 (전체 리빌드) |
+| `diagnostics` | `SerializedDiagnostic[]` | 직렬화된 진단 정보. Worker 경계 통과용 |
+| `errorCount` | `number` | Error 카테고리 진단 수 |
+| `warningCount` | `number` | Warning 카테고리 진단 수 |
+| `errors` | `string[]?` | Error 카테고리 진단을 `"파일:줄:열: TS코드: 메시지"` 형식으로 포맷한 배열. 에러 없으면 `undefined` |
+| `ngtscProgram` | `NgtscProgram?` | NgtscProgram 참조. Angular 패키지 전용, 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 의존성 맵. key: 소유자 파일, value: 의존 SCSS 경로 집합. watch 역방향 탐색용 |
+
+## Usage
+
+### 초기 컴파일
+
+```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);
+}
+```
+
+### 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");
+```

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

@@ -0,0 +1,74 @@
+# @simplysm/service-client
+
+> WebSocket 기반 서비스 서버 클라이언트. `@simplysm/service-server`(Fastify)에 연결하여 RPC 호출, 실시간 이벤트 구독/발행, 파일 업로드/다운로드, ORM 원격 실행을 수행한다. 브라우저와 Node.js 양쪽에서 동작하며, `ws` 패키지를 선택적 peer dependency로 사용한다.
+
+## Installation
+
+```bash
+npm install @simplysm/service-client
+```
+
+Node.js 환경에서 사용 시:
+
+```bash
+npm install ws
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 서버 연결 및 RPC 호출 | [ServiceClient](./main/service-client.md) |
+| 실시간 이벤트 구독/발행 | [EventClient](./features/event-client.md) |
+| 파일 업로드/다운로드 | [FileClient](./features/file-client.md) |
+| ORM 원격 트랜잭션 실행 | [OrmClientConnector](./features/orm-client-connector.md) |
+| progress 모니터링 | [ServiceProgress](./types/service-progress.md) |
+| 연결 옵션 설정 | [ServiceConnectionOptions](./types/service-connection-options.md) |
+
+## API Overview
+
+### Main
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServiceClient`](./main/service-client.md) | class | 서버에 연결하여 RPC, 이벤트, 파일, ORM 기능을 통합 사용할 때 |
+| [`ServiceProxy<T>`](./main/service-client.md) | type | `getService<T>()`의 반환 타입으로, 서비스 메서드를 Promise로 래핑할 때 |
+| [`createServiceClient()`](./main/service-client.md) | function | `new ServiceClient()` 대신 팩토리 함수로 인스턴스를 생성할 때 |
+
+### Transport
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`SocketProvider`](./transport/socket-provider.md) | interface | WebSocket 연결/재연결/하트비트를 직접 제어할 때 (일반적으로 `ServiceClient`가 내부 사용) |
+| [`ServiceTransport`](./transport/service-transport.md) | interface | 요청-응답 매핑과 progress 중계를 직접 제어할 때 (일반적으로 `ServiceClient`가 내부 사용) |
+
+### Protocol
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ClientProtocolWrapper`](./protocol/client-protocol-wrapper.md) | interface | 메시지 인코딩/디코딩을 직접 제어하거나 Worker 오프로드 동작을 이해할 때 (일반적으로 `ServiceClient`가 내부 사용) |
+
+### Features
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`EventClient`](./features/event-client.md) | interface | 서버 이벤트를 구독/발행할 때 (`ServiceClient.getEvent()` 경유 권장) |
+| [`FileClient`](./features/file-client.md) | interface | 파일 업로드/다운로드를 직접 제어할 때 (`ServiceClient.uploadFile()`/`downloadFileBuffer()` 경유 권장) |
+| [`OrmClientConnector`](./features/orm-client-connector.md) | interface | `DbContext` 트랜잭션을 원격 서버에서 실행할 때 |
+| [`OrmClientDbContextExecutor`](./features/orm-client-db-context-executor.md) | class | `DbContextExecutor` 원격 구현체가 필요할 때 (`OrmClientConnector` 경유 권장) |
+
+### Types
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ServiceConnectionOptions`](./types/service-connection-options.md) | interface | `ServiceClient` 생성자에 전달할 연결 옵션을 구성할 때 |
+| [`ServiceProgress`](./types/service-progress.md) | interface | 요청/응답/서버 처리 progress를 모니터링할 때 |
+| [`BlobInput`](./types/blob-input.md) | type | 파일 업로드 시 데이터 타입을 지정할 때 |
+| [`FileCollection`](./types/file-collection.md) | interface | DOM `FileList` 호환 타입이 필요할 때 |
+| [`BrowserWorker`](./types/browser-worker.md) | interface | Worker 인터페이스의 cross-env 타입 호환이 필요할 때 |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- 서버 측 로직 구현 → [`@simplysm/service-server`](../service-server/README.md)
+- 서버-클라이언트 공유 프로토콜/타입 정의 → [`@simplysm/service-common`](../service-common/README.md)
+- ORM 스키마 정의나 쿼리빌더 → [`@simplysm/orm-common`](../orm-common/README.md)

package/claude/references/sd-simplysm-v14/service-client/features/event-client.md

@@ -0,0 +1,93 @@
+# `EventClient`
+
+서버 이벤트 구독/발행 관리 인터페이스. 재연결 시 자동 재구독된다. 팩토리 함수 `createEventClient`로 생성한다.
+
+## When to use
+
+- ✅ 서버에서 발행하는 실시간 이벤트를 구독하거나 다른 클라이언트에 이벤트를 발행할 때
+- ❌ 일반적으로 `ServiceClient.getEvent()` / `ServiceClient.addListener()`를 통해 간접 사용한다. 직접 생성은 커스텀 전송 계층 구현 시에만 필요하다.
+
+```typescript
+export interface EventClient {
+  getEvent<TEventDef extends ServiceEventDef>(
+    eventName: string,
+  ): ClientEventProxy<TEventDef>;
+  addListener<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emit<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+  resubscribeAll(): Promise<void>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `getEvent(eventName)` | method | `ClientEventProxy<TEventDef>` | 이벤트 이름과 타입을 캡처한 프록시 반환 |
+| `addListener(eventName, info, cb)` | method | `Promise<string>` | 이벤트 리스너 등록. 반환값은 `key` (제거 시 사용) |
+| `removeListener(key)` | method | `Promise<void>` | 등록된 이벤트 리스너 제거 |
+| `emit(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`가 참인 대상에게 데이터 발행 |
+| `resubscribeAll()` | method | `Promise<void>` | 재연결 시 모든 리스너를 서버에 재등록. `ServiceClient`가 자동 호출 |
+
+## Related Types
+
+### `ClientEventProxy`
+
+`getEvent()`가 반환하는 이벤트 프록시 인터페이스. 이벤트 이름과 제네릭 타입이 캡처되어 있어 호출 시 반복 지정이 불필요하다.
+
+```typescript
+export interface ClientEventProxy<TEventDef extends ServiceEventDef> {
+  addListener(
+    info: TEventDef["$info"],
+    cb: (data: TEventDef["$data"]) => PromiseLike<void>,
+  ): Promise<string>;
+  removeListener(key: string): Promise<void>;
+  emit(
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+}
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `addListener(info, cb)` | `Promise<string>` | 이벤트 리스너 등록. 반환값은 `key` (제거 시 사용) |
+| `removeListener(key)` | `Promise<void>` | 등록된 이벤트 리스너 제거 |
+| `emit(infoSelector, data)` | `Promise<void>` | `infoSelector`가 참인 대상에게 데이터 발행 |
+
+## `createEventClient`
+
+`EventClient` 팩토리 함수.
+
+```typescript
+export function createEventClient(transport: ServiceTransport): EventClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `transport` | [`ServiceTransport`](../transport/service-transport.md) | 서비스 전송 계층 |
+
+## Usage
+
+```typescript
+// getEvent() 방식 (권장 — 이벤트 이름과 타입이 캡처됨)
+const chatEvt = client.getEvent<typeof ChatEvent>("Chat");
+const key = await chatEvt.addListener({ roomId: "room-1" }, async (data) => {
+  console.log("메시지:", data.message);
+});
+await chatEvt.removeListener(key);
+
+// 이벤트 발행
+await chatEvt.emit(
+  (info) => info.roomId === "room-1",
+  { message: "hello" },
+);
+```

package/claude/references/sd-simplysm-v14/service-client/features/file-client.md

@@ -0,0 +1,63 @@
+# `FileClient`
+
+파일 업로드(POST `/upload`)/다운로드(GET) 인터페이스. 팩토리 함수 `createFileClient`로 생성한다.
+
+## When to use
+
+- ✅ 서버에 파일을 업로드하거나 서버에서 파일을 다운로드할 때
+- ❌ 일반적으로 `ServiceClient.uploadFile()` / `ServiceClient.downloadFileBuffer()`를 통해 간접 사용한다. 직접 생성은 인증 없이 다운로드만 수행하거나 커스텀 URL 구성이 필요할 때에만 사용한다.
+
+```typescript
+export interface FileClient {
+  download(relPath: string): Promise<Bytes>;
+  upload(
+    files: File[] | FileCollection | { name: string; data: BlobInput }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `download(relPath)` | method | `Promise<Bytes>` | `GET {hostUrl}{relPath}`로 파일 다운로드. `Uint8Array` 반환 |
+| `upload(files, authToken)` | method | `Promise<ServiceUploadResult[]>` | `POST {hostUrl}/upload`로 파일 업로드. `multipart/form-data` 사용 |
+
+### `upload` Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `files` | `File[] \| FileCollection \| { name: string; data: BlobInput }[]` | 업로드할 파일 목록 |
+| `authToken` | `string` | 인증 토큰 (`Authorization: Bearer {token}` 헤더로 전송) |
+
+## `createFileClient`
+
+`FileClient` 팩토리 함수.
+
+```typescript
+export function createFileClient(hostUrl: string, clientName: string): FileClient;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hostUrl` | `string` | 서버 기본 URL (`http://host:port` 형식) |
+| `clientName` | `string` | 클라이언트 식별자 (`x-sd-client-name` 헤더로 전송) |
+
+## Usage
+
+```typescript
+// 일반적으로 ServiceClient를 통해 간접 사용한다
+// 파일 업로드 (auth() 호출 후 사용)
+const results = await client.uploadFile([
+  new File(["content"], "file.txt", { type: "text/plain" }),
+]);
+
+// 커스텀 데이터 업로드
+const results2 = await client.uploadFile([
+  { name: "report.csv", data: "col1,col2\nval1,val2" },
+]);
+
+// 파일 다운로드
+const bytes = await client.downloadFileBuffer("/uploaded/file.txt");
+```

package/claude/references/sd-simplysm-v14/service-client/features/orm-client-connector.md

@@ -0,0 +1,89 @@
+# `OrmClientConnector`
+
+`DbContext` 트랜잭션 연결을 원격 서버에서 실행하는 헬퍼 인터페이스. 팩토리 함수 `createOrmClientConnector`로 생성한다.
+
+## When to use
+
+- ✅ 클라이언트에서 `DbContext`를 통해 원격 DB 트랜잭션을 실행할 때
+- ✅ FK 제약 위반 시 사용자 친화적 에러 메시지가 필요할 때 (`connect()` 메서드가 자동 변환)
+- ❌ 서버 측에서 직접 DB에 접근할 때 → `@simplysm/orm-node` 사용
+
+```typescript
+export interface OrmClientConnector {
+  connect<T extends DbContext, R>(
+    config: OrmConnectOptions<T>,
+    callback: (db: T) => Promise<R> | R,
+  ): Promise<R>;
+  connectWithoutTransaction<T extends DbContext, R>(
+    config: OrmConnectOptions<T>,
+    callback: (db: T) => Promise<R> | R,
+  ): Promise<R>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `connect(config, callback)` | method | `Promise<R>` | 트랜잭션 모드로 연결. FK 제약 위반 시 사용자 친화적 에러 메시지로 변환 |
+| `connectWithoutTransaction(config, callback)` | method | `Promise<R>` | 트랜잭션 없이 연결 |
+
+## Related Types
+
+### `OrmConnectOptions`
+
+ORM 원격 연결에 필요한 옵션 인터페이스.
+
+```typescript
+export interface OrmConnectOptions<T extends DbContext> {
+  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `DbClass` | `new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T` | required | 사용할 `DbContext` 서브클래스 생성자 |
+| `connOpt` | `DbConnOptions & { configName: string }` | required | DB 연결 옵션. `configName`은 서버 설정 키 |
+| `dbContextOpt` | `{ database: string; schema: string }` | optional | DB 컨텍스트 옵션. 생략하면 서버에서 조회한 `info.database`/`info.schema` 사용 |
+
+## `createOrmClientConnector`
+
+`OrmClientConnector` 팩토리 함수.
+
+```typescript
+export function createOrmClientConnector(serviceClient: ServiceClient): OrmClientConnector;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `serviceClient` | [`ServiceClient`](../main/service-client.md) | 이미 연결된 서비스 클라이언트 |
+
+## Usage
+
+```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.myTable.select((item) => ({ id: item.id, name: item.name }));
+  },
+);
+
+// 트랜잭션 없이
+const result2 = await connector.connectWithoutTransaction(
+  { DbClass: MyDbContext, connOpt: { configName: "main" } },
+  async (db) => db.myTable.select(),
+);
+```

package/claude/references/sd-simplysm-v14/service-client/features/orm-client-db-context-executor.md

@@ -0,0 +1,31 @@
+# `OrmClientDbContextExecutor`
+
+`DbContextExecutor` 인터페이스 구현체. `DbContext`의 쿼리 실행을 서버 `OrmService`에 원격 호출한다.
+
+## When to use
+
+- ✅ `DbContext`에 주입할 원격 executor가 필요할 때 (커스텀 연결 로직 구현 시)
+- ❌ 일반적으로 [`createOrmClientConnector`](./orm-client-connector.md)를 통해 간접 사용한다. 직접 사용은 트랜잭션 관리를 수동으로 제어해야 하는 특수한 경우에만 필요하다.
+
+```typescript
+export class OrmClientDbContextExecutor implements DbContextExecutor {
+  constructor(
+    private readonly _client: ServiceClient,
+    private readonly _opt: DbConnOptions & { configName: string },
+  );
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `getInfo()` | method | `Promise<{ dialect: Dialect; database?: string; schema?: string }>` | 서버에서 DB dialect, database, schema 조회 |
+| `connect()` | method | `Promise<void>` | 서버에서 DB 연결 생성. `_connId` 할당 |
+| `beginTransaction(isolationLevel?)` | method | `Promise<void>` | 트랜잭션 시작 |
+| `commitTransaction()` | method | `Promise<void>` | 트랜잭션 커밋 |
+| `rollbackTransaction()` | method | `Promise<void>` | 트랜잭션 롤백 |
+| `close()` | method | `Promise<void>` | DB 연결 종료 및 `_connId` 해제 |
+| `executeDefs(defs, options?)` | method | `Promise<T[][]>` | QueryDef 배열을 서버에서 실행 |
+| `executeParametrized(query, params?)` | method | `Promise<unknown[][]>` | 파라미터화된 쿼리를 서버에서 실행 |
+| `bulkInsert(tableName, columnDefs, records)` | method | `Promise<void>` | 대량 INSERT를 서버에서 실행 |