@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/service-server/core/define-service.md

@@ -0,0 +1,81 @@
+# defineService
+
+이름과 팩토리 함수로 서비스를 정의한다. 팩토리가 `auth()`로 래핑되어 있으면 자동으로 `authPermissions`를 추출한다.
+
+## When to use
+
+- ✅ 서버에 등록할 서비스를 정의할 때
+- ❌ 기존 내장 서비스(`OrmService`, `AutoUpdateService`)를 사용할 때는 직접 호출 불필요 — 이미 `defineService`로 정의되어 있다
+
+```typescript
+function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
+  name: string,
+  factory: (ctx: ServiceContext) => TMethods,
+): ServiceDefinition<TMethods>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 서비스 이름. HTTP에서 `/api/{name}/{method}`, WebSocket에서 `{name}.{method}`로 라우팅된다 |
+| `factory` | `(ctx: ServiceContext) => TMethods` | 요청마다 호출되는 팩토리 함수. 메서드 객체를 반환한다 |
+
+## Returns
+
+[`ServiceDefinition<TMethods>`](#servicedefinition) — 서비스 정의 객체.
+
+## Related Types
+
+### `ServiceDefinition`
+
+서비스 정의 구조체.
+
+```typescript
+interface ServiceDefinition<TMethods = Record<string, (...args: any[]) => any>> {
+  name: string;
+  factory: (ctx: ServiceContext) => TMethods;
+  authPermissions?: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 서비스 이름 |
+| `factory` | `(ctx: ServiceContext) => TMethods` | 요청마다 호출되는 팩토리 함수 |
+| `authPermissions` | `string[]` (optional) | `auth()`로 래핑된 팩토리의 서비스 수준 권한 배열 |
+
+### `ServiceMethods`
+
+`ServiceDefinition`에서 메서드 시그니처를 추출하는 유틸리티 타입. 클라이언트 측 타입 공유에 사용한다.
+
+```typescript
+type ServiceMethods<TDefinition> =
+  TDefinition extends ServiceDefinition<infer M> ? M : never;
+```
+
+사용 예:
+
+```typescript
+export type UserServiceType = ServiceMethods<typeof UserService>;
+// 클라이언트: client.getService<UserServiceType>("User");
+```
+
+## Usage
+
+```typescript
+// 기본 서비스 (인증 불필요)
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+// 서비스 수준 인증 (모든 메서드에 로그인 필요)
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+  // 메서드 수준 인증 (admin 역할 필요)
+  deleteUser: auth(["admin"], (id: number) => { /* ... */ }),
+})));
+
+// 클라이언트에 타입 공유
+export type UserServiceType = ServiceMethods<typeof UserService>;
+```

package/claude/references/sd-simplysm-v14/service-server/core/execute-service-method.md

@@ -0,0 +1,43 @@
+# executeServiceMethod
+
+서비스 조회 → 컨텍스트 생성 → 인증 확인 → 메서드 실행 파이프라인을 수행한다.
+
+## When to use
+
+- ✅ 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때
+- ❌ 일반적인 서버 사용 시에는 `ServiceServer`가 내부적으로 호출하므로 직접 사용할 필요가 없다
+
+```typescript
+async function executeServiceMethod(
+  server: ServiceServer,
+  def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    socket?: ServiceSocket;
+    http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
+  },
+): Promise<unknown>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `server` | `ServiceServer` | 서버 인스턴스 |
+| `def.serviceName` | `string` | 호출할 서비스 이름 |
+| `def.methodName` | `string` | 호출할 메서드 이름 |
+| `def.params` | `unknown[]` | 메서드 매개변수 배열 |
+| `def.socket` | `ServiceSocket` (optional) | WebSocket 연결 (WebSocket 요청 시) |
+| `def.http` | `{ clientName: string; authTokenPayload? }` (optional) | HTTP 요청 정보 |
+
+## Returns
+
+`Promise<unknown>` — 메서드 실행 결과.
+
+인증 검사 로직:
+
+1. 메서드 수준 `auth()` 권한이 있으면 이를 사용하고, 없으면 서비스 수준 `authPermissions`를 사용한다
+2. 인증이 필요한데 `server.options.auth`가 `undefined`이면 설정 오류로 에러를 던진다
+3. `server.options.auth`가 `false`이면 인증 검사를 스킵한다
+4. 인증이 활성화되어 있으면 토큰 존재 여부를 확인하고, 역할 배열이 비어있지 않으면 역할 매칭을 수행한다

package/claude/references/sd-simplysm-v14/service-server/core/service-context.md

@@ -0,0 +1,79 @@
+# ServiceContext
+
+서비스 팩토리 함수에 전달되는 컨텍스트 인터페이스. 전송 방식(WebSocket/HTTP)에 무관하게 동일한 인터페이스를 제공한다.
+
+```typescript
+interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;
+  socket?: ServiceSocket;
+  http?: {
+    clientName: string;
+    authTokenPayload?: AuthTokenPayload<TAuthInfo>;
+  };
+  legacy?: {
+    clientName?: string;
+  };
+
+  get authInfo(): TAuthInfo | undefined;
+  get clientName(): string | undefined;
+  get clientPath(): string | undefined;
+  getConfig<T>(section: string): Promise<T>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `server` | property | `ServiceServer<TAuthInfo>` | 서버 인스턴스 참조 |
+| `socket` | property | `ServiceSocket` (optional) | WebSocket 요청일 때만 존재하는 소켓 객체 |
+| `http` | property | `{ clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }` (optional) | HTTP 요청일 때만 존재 |
+| `legacy` | property | `{ clientName?: string }` (optional) | V1 레거시 컨텍스트 (자동 업데이트 전용) |
+| `authInfo` | getter | `TAuthInfo \| undefined` | 토큰에서 추출한 사용자 데이터. WebSocket은 소켓의 `authTokenPayload.data`, HTTP는 헤더의 `authTokenPayload.data`에서 읽는다 |
+| `clientName` | getter | `string \| undefined` | 클라이언트 앱 이름. `..`, `/`, `\`를 포함하면 에러를 던진다 (경로 탐색 공격 방지) |
+| `clientPath` | getter | `string \| undefined` | `{rootPath}/www/{clientName}` 경로. `clientName`이 없으면 `undefined` |
+| `getConfig<T>(section)` | method | `Promise<T>` | `.config.json`에서 섹션을 읽는다. 루트 설정을 먼저 읽고 클라이언트별 설정으로 덮어쓴다. 섹션이 없으면 에러를 던진다 |
+
+## Related Types
+
+### `createServiceContext`
+
+`ServiceContext` 인스턴스를 생성한다.
+
+```typescript
+function createServiceContext<TAuthInfo = unknown>(
+  server: ServiceServer<TAuthInfo>,
+  socket?: ServiceSocket,
+  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> },
+  legacy?: { clientName?: string },
+): ServiceContext<TAuthInfo>;
+```
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `server` | `ServiceServer<TAuthInfo>` | 서버 인스턴스 |
+| `socket` | `ServiceSocket` (optional) | WebSocket 연결 (WebSocket 요청 시) |
+| `http` | `{ clientName: string; authTokenPayload? }` (optional) | HTTP 요청 정보 |
+| `legacy` | `{ clientName?: string }` (optional) | V1 레거시 컨텍스트 |
+
+## Usage
+
+```typescript
+const MyService = defineService("My", (ctx) => ({
+  getProfile: () => {
+    // 인증 정보 접근
+    return ctx.authInfo;
+  },
+
+  readConfig: async () => {
+    // 설정 파일 읽기
+    const config = await ctx.getConfig<{ apiKey: string }>("myapp");
+    return config.apiKey;
+  },
+
+  socketOnly: () => {
+    if (ctx.socket == null) throw new Error("WebSocket만 허용");
+    return ctx.socket.clientName;
+  },
+}));
+```

package/claude/references/sd-simplysm-v14/service-server/legacy/handle-v1-connection.md

@@ -0,0 +1,25 @@
+# handleV1Connection
+
+V1 레거시 WebSocket 프로토콜 호환 레이어. 자동 업데이트(`SdAutoUpdateService.getLastVersion`)만 지원하고, 그 외 모든 요청은 업그레이드 필요 에러를 반환한다.
+
+```typescript
+function handleV1Connection(
+  socket: WebSocket,
+  autoUpdateMethods: { getLastVersion: (platform: string) => Promise<any> },
+  clientNameSetter?: (clientName: string | undefined) => void,
+): void;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `socket` | `WebSocket` | 기저 WebSocket 인스턴스 |
+| `autoUpdateMethods` | `{ getLastVersion: (platform: string) => Promise<any> }` | AutoUpdateService의 메서드 객체 |
+| `clientNameSetter` | `(clientName: string \| undefined) => void` (optional) | V1 요청의 `clientName`을 레거시 컨텍스트에 설정하는 콜백 |
+
+V1 프로토콜:
+- 연결 시 `{ name: "connected" }` 메시지를 전송한다
+- 요청 형식: `{ uuid: string; command: string; params: unknown[]; clientName?: string }`
+- 응답 형식: `{ name: "response"; reqUuid: string; state: "success" | "error"; body: unknown }`
+- `command`가 `"SdAutoUpdateService.getLastVersion"`이면 처리하고, 그 외는 `UPGRADE_REQUIRED` 에러를 반환한다

package/claude/references/sd-simplysm-v14/service-server/main/create-service-server.md

@@ -0,0 +1,32 @@
+# createServiceServer
+
+`ServiceServer` 인스턴스를 생성하는 팩토리 함수.
+
+```typescript
+function createServiceServer<TAuthInfo = unknown>(
+  options: ServiceServerOptions,
+): ServiceServer<TAuthInfo>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `options` | [`ServiceServerOptions`](../types/service-server-options.md) | 서버 설정 옵션 |
+
+## Returns
+
+`ServiceServer<TAuthInfo>` — 생성된 서버 인스턴스. `listen()`을 호출해야 실제로 시작된다.
+
+## Usage
+
+```typescript
+const server = createServiceServer<MyAuthInfo>({
+  rootPath: "/app",
+  port: 3000,
+  auth: { jwtSecret: "secret" },
+  services: [UserService, OrmService],
+});
+
+await server.listen();
+```

package/claude/references/sd-simplysm-v14/service-server/main/service-server.md

@@ -0,0 +1,113 @@
+# ServiceServer
+
+Fastify를 래핑한 서비스 서버 클래스. WebSocket/HTTP 이중 전송, JWT 인증, 이벤트 브로드캐스트, graceful shutdown을 처리한다. `EventEmitter<{ ready: void; close: void }>`를 확장한다.
+
+## When to use
+
+- ✅ Fastify 기반 서비스 서버를 생성하고 시작할 때
+- ✅ WebSocket/HTTP 이중 전송으로 서비스를 제공할 때
+- ✅ 서버에서 클라이언트에 이벤트를 브로드캐스트할 때
+- ❌ 브라우저에서 서버에 연결 → `@simplysm/service-client`
+
+```typescript
+class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{
+  ready: void;
+  close: void;
+}> {
+  isOpen: boolean;
+  readonly fastify: FastifyInstance;
+  readonly options: ServiceServerOptions;
+
+  constructor(options: ServiceServerOptions);
+
+  async listen(): Promise<void>;
+  async close(): Promise<void>;
+  getEvent<TEventDef extends ServiceEventDef>(eventName: string): ServerEventProxy<TEventDef>;
+  async emitEvent<TEventDef extends ServiceEventDef>(
+    eventName: string,
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+  async signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;
+  async verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `isOpen` | property | `boolean` | 서버가 리스닝 중인지 여부 |
+| `fastify` | property | `FastifyInstance` | 내부 Fastify 인스턴스. 직접 접근이 필요할 때 사용 |
+| `options` | property | `ServiceServerOptions` | 생성 시 전달된 옵션 |
+| `listen()` | method | `Promise<void>` | 서버를 시작한다. 플러그인 등록, 라우트 설정, SIGINT/SIGTERM 핸들러 등록을 수행한다. 완료 시 `ready` 이벤트를 발생시킨다 |
+| `close()` | method | `Promise<void>` | 모든 WebSocket 연결을 닫고 Fastify 서버를 종료한다. 완료 시 `close` 이벤트를 발생시킨다 |
+| `getEvent(eventName)` | method | `ServerEventProxy<TEventDef>` | 타입 안전한 이벤트 프록시를 반환한다. `emit(infoSelector, data)` 메서드를 포함 |
+| `emitEvent(eventName, infoSelector, data)` | method | `Promise<void>` | `infoSelector`에 매칭되는 WebSocket 클라이언트에 이벤트를 브로드캐스트한다 |
+| `signAuthToken(payload)` | method | `Promise<string>` | JWT 토큰을 서명한다. `options.auth`가 설정되지 않으면 에러를 던진다 |
+| `verifyAuthToken(token)` | method | `Promise<AuthTokenPayload<TAuthInfo>>` | JWT 토큰을 검증하고 페이로드를 반환한다. `options.auth`가 설정되지 않으면 에러를 던진다 |
+
+`listen()` 시 등록되는 라우트:
+
+| Route | Method | Handler |
+|-------|--------|---------|
+| `/api/:service/:method` | GET/POST | `handleHttpRequest` — 서비스 메서드 호출 |
+| `/upload` | POST | `handleUpload` — multipart 파일 업로드 |
+| `/`, `/ws` | WebSocket | WebSocket 핸들러. `ver=2` 쿼리 시 V2 프로토콜, 그 외 V1 레거시 |
+| `/*` | GET/POST/PUT/DELETE/PATCH/HEAD | `handleStaticFile` — 정적 파일 서빙 |
+
+`listen()` 시 Fastify 플러그인 등록 순서: `@fastify/websocket` → `@fastify/helmet` → `@fastify/multipart` → `@fastify/static` → `@fastify/cors`
+
+Graceful shutdown: `SIGINT`/`SIGTERM` 시그널 수신 시 `close()`를 호출하고, 10초 내에 종료되지 않으면 `process.exit(1)`로 강제 종료한다.
+
+## Related Types
+
+### `ServerEventProxy`
+
+`getEvent()`가 반환하는 타입 안전한 이벤트 프록시 인터페이스.
+
+```typescript
+interface ServerEventProxy<TEventDef extends ServiceEventDef> {
+  emit(
+    infoSelector: (item: TEventDef["$info"]) => boolean,
+    data: TEventDef["$data"],
+  ): Promise<void>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `emit(infoSelector, data)` | `infoSelector`에 매칭되는 이벤트 리스너를 가진 WebSocket 클라이언트에 이벤트를 브로드캐스트한다 |
+
+## Usage
+
+```typescript
+import { createServiceServer, defineService, auth } from "@simplysm/service-server";
+
+const HealthService = defineService("Health", (ctx) => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const UserService = defineService("User", auth((ctx) => ({
+  getProfile: () => ctx.authInfo,
+})));
+
+const server = createServiceServer<{ userId: string }>({
+  rootPath: "/app",
+  port: 3000,
+  auth: { jwtSecret: "my-secret" },
+  services: [HealthService, UserService],
+});
+
+await server.listen();
+
+// JWT 토큰 발급
+const token = await server.signAuthToken({
+  roles: ["admin"],
+  data: { userId: "123" },
+});
+
+// 이벤트 브로드캐스트
+const evt = server.getEvent<typeof MyEvent>("MyEvent");
+await evt.emit((info) => info.userId === "123", { name: "새 이름" });
+```

package/claude/references/sd-simplysm-v14/service-server/protocol/server-protocol-wrapper.md

@@ -0,0 +1,35 @@
+# ServerProtocolWrapper
+
+메시지 인코딩/디코딩 래퍼 인터페이스. 무거운 메시지는 worker 스레드에 자동으로 위임하고, 가벼운 작업은 메인 스레드에서 처리한다.
+
+```typescript
+interface ServerProtocolWrapper {
+  encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }>;
+  decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>;
+  dispose(): void;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `encode(uuid, message)` | method | `Promise<{ chunks: Bytes[]; totalSize: number }>` | 메시지를 인코딩한다. 바이너리 데이터(Uint8Array)가 포함된 메시지는 worker 스레드에 위임한다 |
+| `decode(bytes)` | method | `Promise<ServiceMessageDecodeResult<ServiceMessage>>` | 메시지를 디코딩한다. 30KB 초과 메시지는 worker 스레드에 위임한다 |
+| `dispose()` | method | `void` | 내부 프로토콜 리소스를 해제한다 |
+
+Worker 위임 기준:
+- **encode**: 메시지 body가 `Uint8Array`이거나, 배열 내에 `Uint8Array` 요소가 있을 때 worker 사용
+- **decode**: 메시지 크기가 30KB(30 * 1024 바이트)를 초과할 때 worker 사용
+
+Worker는 지연 싱글턴으로 생성되며, `maxOldGenerationSizeMb: 4096`의 리소스 제한이 설정되어 있다.
+
+## Related Types
+
+### `createServerProtocolWrapper`
+
+`ServerProtocolWrapper` 인스턴스를 생성한다. 내부적으로 `@simplysm/service-common`의 `createServiceProtocol()`을 사용한다.
+
+```typescript
+function createServerProtocolWrapper(): ServerProtocolWrapper;
+```

package/claude/references/sd-simplysm-v14/service-server/services/app-structure-service.md

@@ -0,0 +1,59 @@
+# AppStructureService
+
+앱 구조 정보 서비스를 생성하는 팩토리 함수. `defineService`를 래핑하여 `Record<string, AppStructureItem[]>` 맵을 받아 서비스 정의를 반환한다. 인증 불필요.
+
+## When to use
+
+- ✅ 클라이언트에 앱의 메뉴/페이지 구조 정보를 제공할 때
+- ❌ 동적으로 변하는 구조를 제공해야 할 때는 별도 서비스를 정의한다 — `AppStructureService`는 생성 시 전달된 정적 맵을 반환한다
+
+```typescript
+function AppStructureService(
+  itemsMap: Record<string, AppStructureItem[]>,
+): ServiceDefinition;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `itemsMap` | `Record<string, AppStructureItem[]>` | 앱 구조 아이템 맵. `AppStructureItem`은 `@simplysm/service-common`에서 import한다 |
+
+## Returns
+
+`ServiceDefinition` — `defineService("AppStructure", ...)`로 생성된 서비스 정의.
+
+제공 메서드:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getItems` | `() => Record<string, AppStructureItem[]>` | 생성 시 전달된 `itemsMap`을 그대로 반환한다 |
+
+## Related Types
+
+### `AppStructureServiceType`
+
+`AppStructureService`가 반환하는 서비스의 메서드 시그니처 타입.
+
+```typescript
+type AppStructureServiceType = ServiceMethods<ReturnType<typeof AppStructureService>>;
+```
+
+## Usage
+
+```typescript
+import { AppStructureService } from "@simplysm/service-server";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const itemsMap: Record<string, AppStructureItem[]> = {
+  "my-client": [
+    { title: "홈", path: "/home" },
+    { title: "설정", path: "/settings" },
+  ],
+};
+
+const server = createServiceServer({
+  services: [AppStructureService(itemsMap)],
+  // ...
+});
+```

package/claude/references/sd-simplysm-v14/service-server/services/auto-update-service.md

@@ -0,0 +1,34 @@
+# AutoUpdateService
+
+자동 업데이트 서비스 정의. `defineService("AutoUpdate", (ctx) => ...)`로 정의되어 있다. 인증 불필요.
+
+## When to use
+
+- ✅ 클라이언트 앱(Android APK / Windows EXE)의 자동 업데이트를 서버에서 제공할 때
+- ❌ 웹 클라이언트 업데이트에는 사용하지 않는다 — 웹은 브라우저 캐시/서비스 워커로 처리한다
+
+```typescript
+const AutoUpdateService: ServiceDefinition;
+```
+
+## Members
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getLastVersion` | `(platform: string) => Promise<{ version: string; downloadPath: string } \| undefined>` | `{clientPath}/{platform}/updates/` 디렉토리에서 최신 버전 파일을 찾아 반환한다 |
+
+`getLastVersion` 동작:
+- `platform`이 `"android"`이면 `.apk` 파일을, 그 외에는 `.exe` 파일을 탐색한다
+- 파일명이 `{version}.{ext}` 형식이어야 하며 (예: `1.2.3.apk`), `semver.maxSatisfying`으로 최대 버전을 결정한다
+- `clientPath`가 없으면 에러를 던진다
+- 업데이트 디렉토리나 매칭 파일이 없으면 `undefined`를 반환한다
+
+## Related Types
+
+### `AutoUpdateServiceType`
+
+`AutoUpdateService`의 메서드 시그니처 타입.
+
+```typescript
+type AutoUpdateServiceType = ServiceMethods<typeof AutoUpdateService>;
+```

package/claude/references/sd-simplysm-v14/service-server/services/orm-service.md

@@ -0,0 +1,43 @@
+# OrmService
+
+ORM 브리지 서비스 정의. WebSocket 전용이며 `auth()`로 래핑되어 로그인이 필수다. `defineService("Orm", auth((ctx) => ...))`로 정의되어 있다.
+
+## When to use
+
+- ✅ 클라이언트에서 WebSocket을 통해 DB 연결/쿼리를 수행해야 할 때
+- ❌ HTTP API로 DB 작업을 수행하려면 별도 서비스를 정의한다 — OrmService는 WebSocket 전용이다
+
+```typescript
+const OrmService: ServiceDefinition;
+```
+
+소켓별 DB 연결 관리:
+- `WeakMap<ServiceSocket, Map<number, DbConn>>`으로 소켓별 연결 상태를 관리한다
+- 소켓이 닫히면 해당 소켓의 열린 DB 연결을 모두 자동 종료한다
+- `getConfig("orm")`에서 `configName`으로 DB 연결 설정을 읽는다
+
+HTTP 요청 시 "WebSocket 연결이 필요합니다" 에러를 던진다.
+
+## Members
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getInfo` | `(opt: DbConnOptions & { configName: string }) => Promise<{ dialect: Dialect; database?: string; schema?: string }>` | DB 연결 정보를 반환한다. `mssql-azure` dialect은 `mssql`로 변환된다 |
+| `connect` | `(opt: DbConnOptions & { configName: string }) => Promise<number>` | DB에 연결하고 연결 ID를 반환한다 |
+| `close` | `(connId: number) => Promise<void>` | DB 연결을 종료한다 |
+| `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 배열을 SQL로 변환하여 실행한다. `options`가 모두 `undefined`이면 쿼리를 합쳐 한 번에 실행한다 |
+| `bulkInsert` | `(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]) => Promise<void>` | 대량 삽입을 수행한다 |
+
+## Related Types
+
+### `OrmServiceType`
+
+`OrmService`의 메서드 시그니처 타입. 클라이언트 측 타입 공유에 사용한다.
+
+```typescript
+type OrmServiceType = ServiceMethods<typeof OrmService>;
+```

package/claude/references/sd-simplysm-v14/service-server/transport-http/handle-http-request.md

@@ -0,0 +1,33 @@
+# handleHttpRequest
+
+GET/POST `/api/:service/:method` 경로의 HTTP 요청을 처리한다. `x-sd-client-name` 헤더가 필수이며, `Authorization` 헤더가 있으면 JWT 토큰을 검증한다.
+
+```typescript
+async function handleHttpRequest<TAuthInfo = unknown>(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  jwtSecret: string | undefined,
+  runMethod: (def: {
+    serviceName: string;
+    methodName: string;
+    params: unknown[];
+    http: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
+  }) => Promise<unknown>,
+): Promise<void>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `req` | `FastifyRequest` | Fastify 요청 객체 |
+| `reply` | `FastifyReply` | Fastify 응답 객체 |
+| `jwtSecret` | `string \| undefined` | JWT 시크릿. `Authorization` 헤더가 있는데 시크릿이 없으면 에러를 던진다 |
+| `runMethod` | `(def) => Promise<unknown>` | 서비스 메서드 실행 콜백 |
+
+요청 매개변수 파싱:
+- **GET**: `?json=` 쿼리 파라미터에서 JSON 배열을 파싱한다
+- **POST**: 요청 본문이 JSON 배열이어야 한다. 배열이 아니면 400을 반환한다
+- **그 외**: 405 Method Not Allowed를 반환한다
+
+인증 실패 시 401 응답을 반환한다.

package/claude/references/sd-simplysm-v14/service-server/transport-http/handle-static-file.md

@@ -0,0 +1,29 @@
+# handleStaticFile
+
+정적 파일 서빙을 처리한다. 경로 탐색 공격 방지와 숨김 파일 접근 차단이 포함되어 있다.
+
+```typescript
+async function handleStaticFile(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  urlPath: string,
+): Promise<void>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `req` | `FastifyRequest` | Fastify 요청 객체 |
+| `reply` | `FastifyReply` | Fastify 응답 객체 |
+| `rootPath` | `string` | 서버 루트 경로. `{rootPath}/www/` 하위에서 파일을 찾는다 |
+| `urlPath` | `string` | 요청 URL 경로 (슬래시 제거됨) |
+
+보안 처리:
+- `{rootPath}/www/` 외부 경로 접근 시 에러를 던진다 (경로 탐색 공격 방지)
+- `.`으로 시작하는 파일은 403 Forbidden을 반환한다
+
+디렉토리 처리:
+- 디렉토리 요청 시 끝에 슬래시가 없으면 슬래시를 추가하여 리다이렉트한다
+- 디렉토리에 대해 `index.html`을 자동으로 서빙한다

package/claude/references/sd-simplysm-v14/service-server/transport-http/handle-upload.md

@@ -0,0 +1,33 @@
+# handleUpload
+
+`/upload` 경로의 multipart 파일 업로드를 처리한다. 인증 필수 (Authorization 헤더 필수).
+
+```typescript
+async function handleUpload(
+  req: FastifyRequest,
+  reply: FastifyReply,
+  rootPath: string,
+  jwtSecret: string | undefined,
+): Promise<void>;
+```
+
+## Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `req` | `FastifyRequest` | Fastify 요청 객체 |
+| `reply` | `FastifyReply` | Fastify 응답 객체 |
+| `rootPath` | `string` | 서버 루트 경로. 파일은 `{rootPath}/www/uploads/`에 저장된다 |
+| `jwtSecret` | `string \| undefined` | JWT 시크릿 |
+
+동작:
+- 파일명은 UUID로 변환되고 원래 확장자를 유지한다
+- 파일 크기 제한 초과 시 에러를 던진다
+- 에러 발생 시 불완전한 파일과 이미 저장된 파일을 모두 정리한다
+
+응답: `ServiceUploadResult[]` (from `@simplysm/service-common`)
+
+```typescript
+// ServiceUploadResult 구조
+{ path: "uploads/{uuid}.ext", filename: "원본파일명.ext", size: number }
+```