@simplysm/sd-claude 14.0.65 → 14.0.66

package/claude/references/sd-simplysm14/apis/sd-cli/sd-config.md

@@ -0,0 +1,155 @@
+# @simplysm/sd-cli — sd-config
+
+`sd.config.ts` 작성용 타입 모음. 진실 근거: `packages/sd-cli/src/sd-config.types.ts`.
+
+## 진입 타입
+
+```typescript
+import type { SdConfig, SdConfigFn, SdConfigParams } from "@simplysm/sd-cli";
+
+const config: SdConfigFn = (params) => ({
+  packages: {
+    "core-common": { target: "neutral" },
+    "core-node": { target: "node" },
+  },
+});
+export default config;
+```
+
+- `SdConfigFn = (params: SdConfigParams) => SdConfig | Promise<SdConfig>`
+- `SdConfigParams = { cwd: string; dev: boolean; opt: string[] }` — `opt` 는 CLI `-o` 플래그.
+- `SdConfig = { packages: Record<string, SdPackageConfig | undefined>; replaceDeps?: Record<string, string>; postPublish?: SdPostPublishScriptConfig[] }`
+  - `packages` 키 = `packages/` 하위 디렉토리명.
+  - `replaceDeps`: node_modules 의 패키지를 로컬 소스로 심링크 교체. 예: `{ "@simplysm/*": "../simplysm/packages/*" }` (key 의 `*` 가 value 의 `*` 로 치환).
+
+## 패키지 설정
+
+`SdPackageConfig = SdBuildPackageConfig | SdClientPackageConfig | SdServerPackageConfig | SdScriptsPackageConfig`.
+
+### SdBuildPackageConfig (라이브러리: node/browser/neutral)
+
+```typescript
+{
+  target: "node" | "browser" | "neutral";   // BuildTarget
+  publish?: SdPublishConfig;
+  copySrc?: string[];                        // src/ 기준 glob → dist/ 로 복사
+  watch?: SdWatchHookConfig;                 // watch 모드 훅
+}
+```
+
+### SdClientPackageConfig (Frontend 앱)
+
+```typescript
+{
+  target: "client";
+  server: string | number;                   // 연결 서버 패키지명, 또는 포트
+  env?: Record<string, string>;              // esbuild define 으로 process.env 치환
+  publish?: SdPublishConfig;
+  capacitor?: SdCapacitorConfig;
+  electron?: SdElectronConfig;
+  configs?: Record<string, unknown>;         // 런타임 설정 → dist/.config.json
+  exclude?: string[];                        // Capacitor/Electron package.json 에 추가
+  browserSupport?: SdBrowserSupportConfig;
+  pwa?: false | SdPwaConfig;                 // 미지정 시 기본값으로 활성
+}
+```
+
+### SdServerPackageConfig (Fastify 서버)
+
+```typescript
+{
+  target: "server";
+  env?: Record<string, string>;              // esbuild banner 로 process.env.KEY 상수 치환
+  publish?: SdPublishConfig;
+  configs?: Record<string, unknown>;         // 런타임 설정 → dist/.config.json
+  externals?: string[];                      // esbuild external (binding.gyp 자동 감지에 추가)
+  pm2?: { name?: string; ignoreWatchPaths?: string[] };  // 지정 시 dist/pm2.config.cjs 생성
+  packageManager?: "volta" | "mise";         // mise.toml / volta 설정 생성에 영향
+}
+```
+
+### SdScriptsPackageConfig (유틸·임의 명령 실행)
+
+```typescript
+{
+  target: "scripts";
+  publish?: SdPublishConfig;
+  watch?: SdWatchHookConfig;                 // 미지정이면 watch/typecheck 에서 제외
+}
+```
+
+`SdWatchHookConfig`: `{ target: string[]; cmd: string; args?: string[] }`. `target` 은 패키지 디렉토리 기준 glob. 매칭 변경 시 `cmd args` 실행.
+
+## 배포 설정
+
+`SdPublishConfig`:
+- `{ type: "npm" }` — npm 레지스트리.
+- `{ type: "local-directory"; path: string }` — 로컬 복사. `path` 에 `%VER%`, `%PROJECT%` 치환.
+- `{ type: "ftp" | "ftps" | "sftp"; host; port?; path?; user?; password? }`.
+
+`postPublish` 항목 `SdPostPublishScriptConfig`: `{ type: "script"; cmd: string; args: string[] }`. `args` 의 `%VER%`, `%PROJECT%` 치환.
+
+## 클라이언트 부속 옵션
+
+### SdCapacitorConfig
+
+```typescript
+{
+  appId: string;                             // 예 "com.example.app"
+  appName: string;
+  plugins?: Record<string, Record<string, unknown> | true>;
+  icon?: string;                             // 패키지 기준 상대 경로
+  debug?: boolean;
+  platform?: { android?: SdCapacitorAndroidConfig };
+}
+```
+
+`SdCapacitorAndroidConfig`: `config`(AndroidManifest application 속성), `bundle`(true=AAB, false=APK), `intentFilters`, `sign: SdCapacitorSignConfig`, `sdkVersion`, `permissions: SdCapacitorPermission[]`.
+
+- `SdCapacitorSignConfig`: `keystore, storePassword, alias, password, keystoreType?` (기본 `"jks"`).
+- `SdCapacitorPermission`: `{ name; maxSdkVersion?; ignore? }`.
+- `SdCapacitorIntentFilter`: `{ action?; category? }`.
+
+### SdElectronConfig
+
+```typescript
+{
+  appId: string;
+  portable?: boolean;                        // true=포터블 exe, 미지정/false=NSIS 설치본
+  installerIcon?: string;                    // .ico, 패키지 기준 상대 경로
+  reinstallDependencies?: string[];          // 네이티브 모듈 등
+  postInstallScript?: string;
+  nsisOptions?: Record<string, unknown>;
+  env?: Record<string, string>;              // electron-main.ts 의 process.env
+}
+```
+
+### SdPwaConfig
+
+```typescript
+{
+  manifest?: {
+    name?; short_name?;
+    display?: "standalone" | "fullscreen" | "minimal-ui" | "browser";
+    theme_color?; background_color?;
+    icons?: Array<{ src: string; sizes: string; type?: string }>;
+  };
+}
+```
+
+`pwa: false` 로 비활성. 미지정 시 기본값으로 활성.
+
+### SdBrowserSupportConfig
+
+```typescript
+{
+  browserslist?: string | string[];          // 예 "last 2 Chrome versions"
+  postCss?: { plugins: [string, (object | string)?][] };
+  legacyModule?: boolean;                    // 코드 분할 비활성 + import.meta 치환
+}
+```
+
+## 부수 타입
+
+- `BuildTarget = "node" | "browser" | "neutral"` — `SdBuildPackageConfig.target`.
+- `NpmConfig` — `package.json` 구조 헬퍼 (`name`, `version`, `dependencies`, `devDependencies`, `peerDependencies`, `volta?`).

package/claude/references/sd-simplysm14/apis/service-client/README.md

@@ -0,0 +1,92 @@
+# @simplysm/service-client
+
+`@simplysm/service-server` 와 WebSocket 으로 통신하는 클라이언트. RPC 호출·이벤트 구독·파일 업/다운로드·원격 ORM 실행을 단일 `ServiceClient` 에서 제공한다 (Node/브라우저 공용).
+
+## 사용 트리거 인덱스
+- **createServiceClient / ServiceConnectionOptions** — 클라이언트 인스턴스 생성·서버 접속/종료할 때.
+- **getService / send / ServiceProxy** — 서버 서비스 메서드를 타입 안전 RPC 로 호출할 때.
+- **auth** — 서버 인증 토큰을 등록하고 재연결 시 자동 재인증되게 할 때.
+- **getEvent / addListener / removeListener / emitEvent** — 서버 사이드 이벤트 구독 또는 다른 클라이언트로 이벤트 발행할 때.
+- **uploadFile / downloadFileBuffer** — 서버에 파일을 올리거나 정적 경로에서 바이트로 받을 때.
+- **createOrmClientConnector / OrmConnectOptions** — 서버의 ORM 서비스를 통해 DbContext 트랜잭션을 원격 실행할 때.
+- **ServiceClient 이벤트 (`state`, `request-progress`, `response-progress`, `server-progress`)** — 연결 상태와 전송/응답/서버 진행률을 구독할 때.
+
+## 연결/생성
+```ts
+createServiceClient(name: string, options: ServiceConnectionOptions): ServiceClient
+interface ServiceConnectionOptions { port: number; host: string; ssl?: boolean; maxReconnectCount?: number; }
+client.connect(): Promise<void>
+client.close(): Promise<void>
+client.connected: boolean
+client.hostUrl: string  // `${ssl?https:http}://host:port`
+```
+- WebSocket URL 은 `${ws|wss}://host:port/ws` 로 고정.
+- `maxReconnectCount` 기본 10, `0` 이면 재연결 비활성.
+- 5s ping / 30s 무응답 시 강제 재연결, 재연결 성공 시 인증 토큰과 이벤트 리스너가 자동 복구됨.
+
+## RPC 호출
+```ts
+client.getService<TService>(serviceName): ServiceProxy<TService>
+client.send(serviceName, methodName, params, progress?): Promise<unknown>
+type ServiceProxy<T> = { [K in keyof T]: T[K] extends (...a:infer P)=>infer R ? (...a:P)=>Promise<Awaited<R>> : never }
+interface ServiceProgress { request?(s); response?(s); server?(s); }
+interface ServiceProgressState { uuid: string; totalSize: number; completedSize: number; }
+```
+- `getService` 는 Proxy 라 임의 메서드명 호출 가능. 타입은 `TService` 로만 보장됨.
+- 메시지 이름은 `"<serviceName>.<methodName>"` 으로 전송.
+- 30KB 초과 또는 `Uint8Array`/큰 배열 페이로드는 Worker 에서 인코딩/디코딩.
+
+## 인증
+```ts
+client.auth(token: string): Promise<void>
+```
+- 서버에 `auth` 메시지를 보내고 토큰을 내부 저장. 재연결 시 자동으로 같은 토큰으로 재인증.
+- `uploadFile` 은 인증 토큰이 없으면 에러를 던짐.
+
+## 이벤트 (서버 push)
+```ts
+client.getEvent<TEventDef>(eventName): ClientEventProxy<TEventDef>
+client.addListener<TEventDef>(eventName, info, cb): Promise<string>   // key 반환
+client.removeListener(key): Promise<void>
+client.emitEvent<TEventDef>(eventName, infoSelector, data): Promise<void>
+interface ClientEventProxy<T> { addListener(info, cb): Promise<string>; removeListener(key): Promise<void>; emit(infoSelector, data): Promise<void>; }
+```
+- `addListener` 는 연결 상태에서만 가능. 로컬 맵에도 보관해 재연결 시 자동 재구독.
+- `emitEvent` 는 서버에 `evt:gets` 로 후보를 받아 `infoSelector` 통과분에만 `evt:emit` 호출.
+- 핸들러 내부 에러는 로깅만 되고 다른 핸들러 호출은 계속됨.
+
+## 파일 업/다운로드
+```ts
+client.uploadFile(files: File[] | FileCollection | { name: string; data: BlobInput }[]): Promise<ServiceUploadResult[]>
+client.downloadFileBuffer(relPath: string): Promise<Uint8Array>
+type BlobInput = Blob | Uint8Array<ArrayBuffer> | ArrayBuffer | string
+interface FileCollection { length; item(i); [i]; [Symbol.iterator]() }  // 브라우저 FileList 호환
+```
+- 업로드: `POST {hostUrl}/upload` (multipart). 헤더 `x-sd-client-name`, `Authorization: Bearer <token>`. 인증 필수.
+- 다운로드: `GET {hostUrl}/{relPath}` 의 응답 본문을 `Uint8Array` 로 반환.
+- 브라우저 전용 `File`/`FileList` 대신 `BlobInput`/`FileCollection` 으로 Node 환경도 지원.
+
+## ORM 클라이언트
+```ts
+createOrmClientConnector(client: ServiceClient): OrmClientConnector
+interface OrmConnectOptions<T extends DbContext> {
+  DbClass: new (executor, { database, schema? }) => T;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: { database: string; schema: string };
+}
+connector.connect(config, async db => ...)               // 트랜잭션 래핑
+connector.connectWithoutTransaction(config, async db => ...)
+```
+- 서버의 `"Orm"` 서비스에 RPC 를 걸어 `getInfo` → `connect` → `executeDefs` 등을 실행.
+- `dbContextOpt` 생략 시 서버가 알려준 `database`/`schema` 사용. 둘 다 비면 에러.
+- 외래키 참조 위반 에러(`a parent row: a foreign key constraint` / `conflicted with the REFERENCE`)는 사용자 메시지로 변환되어 throw.
+
+## 상태/진행률 이벤트
+```ts
+client.on("state", (s: "connected" | "closed" | "reconnecting") => ...)
+client.on("request-progress",  (s: ServiceProgressState) => ...)  // 클라이언트 → 서버 전송 청크 진행
+client.on("response-progress", (s: ServiceProgressState) => ...)  // 서버 → 클라이언트 응답 청크 진행
+client.on("server-progress",   (s: ServiceProgressState) => ...)  // 서버가 명시적으로 보내는 진행률
+```
+- 단일 청크 메시지에는 progress 가 발행되지 않음(분할 메시지에서만).
+- `send` 호출 시 전달한 `progress?: ServiceProgress` 콜백은 인스턴스 이벤트와 별도로 호출됨.

package/claude/references/sd-simplysm14/apis/service-common/README.md

@@ -0,0 +1,29 @@
+# @simplysm/service-common
+
+서버/클라이언트가 공유하는 서비스 프로토콜·메시지 타입·서비스 인터페이스·앱 구조 정의·이벤트 정의 유틸.
+
+## 사용 트리거 인덱스
+
+- **`createServiceProtocol` / `ServiceProtocol` / `ServiceMessageDecodeResult` / `PROTOCOL_CONFIG`** — 서버/클라이언트 transport 의 바이너리 V2 프로토콜(헤더 28B + JSON, 3MB↑ 자동 청킹, 100MB 한계) 인/디코더 생성. 자세히: [protocol.md](./protocol.md)
+- **메시지 타입 (`ServiceMessage` / `ServiceClientMessage` / `ServiceServerMessage` / `ServiceServerRawMessage` 및 9 종의 개별 메시지)** — 프로토콜 위에 실리는 메시지 식별·타입 가드·핸들러 분기. 자세히: [messages.md](./messages.md)
+- **서비스 인터페이스 (`OrmService` / `AutoUpdateService` / `AppStructureService` / `DbConnOptions`)** — 서버 구현·클라이언트 호출 양쪽이 공유하는 빌트인 서비스의 시그니처. 자세히: [service-types.md](./service-types.md)
+- **앱 구조 (`AppStructureItem` / `AppStructureGroupItem` / `AppStructureLeafItem` / `AppStructureSubPermission` / `FlatPermission` + `isUsableModules` / `isUsableModulesChain` / `getFlatPermissions`)** — 메뉴/권한 트리 정의와 모듈 기반 가용성 평가·평탄화. 자세히: [app-structure.md](./app-structure.md)
+- **`defineEvent` / `ServiceEventDef`** — 서버 발신·클라이언트 구독에서 `info`/`data` 타입을 공유하기 위한 이벤트 정의.
+- **`ServiceUploadResult`** — 파일 업로드 결과(저장 경로·원본명·바이트 크기).
+
+## defineEvent / ServiceEventDef
+
+```ts
+function defineEvent<TInfo, TData>(eventName: string): ServiceEventDef<TInfo, TData>
+interface ServiceEventDef<TInfo, TData> { eventName: string; readonly $info: TInfo; readonly $data: TData; }
+```
+
+`$info`/`$data` 는 런타임 미사용, 타입 추출 전용 마커. 서버는 `defineEvent` 로 정의·export 하고, 클라이언트는 `import type` 으로 가져와 `addListener<typeof Evt>(...)` / `emitEvent<typeof Evt>(...)` 에 전달해 `info` 필터·`data` 페이로드를 정적으로 검증한다.
+
+## ServiceUploadResult
+
+```ts
+interface ServiceUploadResult { path: string; filename: string; size: number; }
+```
+
+서버 업로드 핸들러가 클라이언트로 반환하는 결과. `path` 는 서버 내부 저장 경로다.

package/claude/references/sd-simplysm14/apis/service-common/app-structure.md

@@ -0,0 +1,63 @@
+# @simplysm/service-common — app-structure
+
+메뉴/권한 트리 정의 타입과 모듈(라이선스/플랜 등) 기반 가용성 평가·평탄화 함수.
+
+## 타입
+
+```ts
+type AppStructureItem<TModule = unknown> =
+  | AppStructureGroupItem<TModule>
+  | AppStructureLeafItem<TModule>;
+
+interface AppStructureGroupItem<TModule> {
+  code: string; title: string;
+  modules?: TModule[]; requiredModules?: TModule[];
+  icon?: string;
+  children: AppStructureItem<TModule>[];
+}
+
+interface AppStructureLeafItem<TModule> {
+  code: string; title: string;
+  modules?: TModule[]; requiredModules?: TModule[];
+  perms?: ("use" | "edit")[];
+  subPerms?: AppStructureSubPermission<TModule>[];
+  icon?: string; url?: string;
+  isNotMenu?: boolean;
+}
+
+interface AppStructureSubPermission<TModule> {
+  code: string; title: string;
+  modules?: TModule[]; requiredModules?: TModule[];
+  perms: ("use" | "edit")[];
+}
+
+interface FlatPermission<TModule = unknown> {
+  titleChain: string[];
+  codeChain: string[];     // [...상위 code, perm] 또는 [...상위 code, subPerm.code, perm]
+  modulesChain: TModule[][];
+}
+```
+
+Group/Leaf 는 `children` 존재로 구분(`"children" in item`).
+
+## isUsableModules(modules, requiredModules, usableModules) → boolean
+
+- `requiredModules` (AND): 모두 `usableModules` 에 포함되어야 함. 없거나 빈 배열이면 통과.
+- `modules` (OR): 비었거나 그 중 하나라도 `usableModules` 에 있으면 통과.
+
+## isUsableModulesChain(modulesChain, requiredModulesChain, usableModules) → boolean
+
+체인 각 레벨에 대해 `modules` OR 와 `requiredModules` AND 모두 만족해야 통과. 트리 깊이별 누적 조건 평가용.
+
+## getFlatPermissions(items, usableModules) → FlatPermission[]
+
+트리를 BFS 로 순회하며 각 leaf 의 `perms` / `subPerms` 를 평탄화한다.
+
+- 진행 중 노드 단위로 `isUsableModulesChain` 체크 — 실패 시 하위 폐기.
+- `subPerms` 도 자체 `modules`/`requiredModules` 로 추가 필터.
+- 결과 `codeChain` 마지막에 권한값(`"use"|"edit"`)이 붙는다.
+
+```ts
+const perms = getFlatPermissions(items, ["BASIC", "PRO"]);
+// [{ titleChain: ["주문","주문등록"], codeChain: ["order","register","use"], modulesChain: [["PRO"]] }, ...]
+```

package/claude/references/sd-simplysm14/apis/service-common/messages.md

@@ -0,0 +1,56 @@
+# @simplysm/service-common — messages
+
+`ServiceProtocol` 위에 실리는 메시지 식별자(`name`) 별 바디 스키마. 모든 인터페이스는 `name` discriminator 로 좁힌다.
+
+## 유니언
+
+```ts
+type ServiceMessage =
+  | ServiceRequestMessage | ServiceAuthMessage
+  | ServiceProgressMessage | ServiceResponseMessage | ServiceErrorMessage
+  | ServiceAddEventListenerMessage | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage
+  | ServiceEmitEventMessage | ServiceEventMessage;
+
+type ServiceClientMessage =      // 클라이언트 → 서버
+  | ServiceRequestMessage | ServiceAuthMessage
+  | ServiceAddEventListenerMessage | ServiceRemoveEventListenerMessage
+  | ServiceGetEventListenerInfosMessage | ServiceEmitEventMessage;
+
+type ServiceServerMessage =      // 서버 → 클라이언트 (디스패치 대상)
+  | ServiceResponseMessage | ServiceErrorMessage | ServiceEventMessage;
+
+type ServiceServerRawMessage =   // 서버 → 클라이언트 (progress 포함 전체)
+  | ServiceProgressMessage | ServiceServerMessage;
+```
+
+## 시스템
+
+- `ServiceProgressMessage` — `name: "progress"`, `body: { totalSize, completedSize }`. 서버가 청크 수신 진행률 알림.
+- `ServiceErrorMessage` — `name: "error"`, `body: { name, message, code, stack?, detail?, cause? }`. 처리 중 에러 알림.
+- `ServiceAuthMessage` — `name: "auth"`, `body: string` (토큰). 클라이언트 인증.
+
+## 서비스 메서드
+
+- `ServiceRequestMessage` — `` name: `${string}.${string}` `` (예: `"User.findOne"`), `body: unknown[]` (매개변수 배열).
+- `ServiceResponseMessage` — `name: "response"`, `body?: unknown` (반환값).
+
+## 이벤트
+
+- `ServiceAddEventListenerMessage` — `name: "evt:add"`, `body: { key, name, info }`. `key` 는 uuid (remove 키).
+- `ServiceRemoveEventListenerMessage` — `name: "evt:remove"`, `body: { key }`.
+- `ServiceGetEventListenerInfosMessage` — `name: "evt:gets"`, `body: { name }`. 동일 이벤트 구독자들의 `info` 목록 요청.
+- `ServiceEmitEventMessage` — `name: "evt:emit"`, `body: { keys, data }`. 클라이언트 발생.
+- `ServiceEventMessage` — `name: "evt:on"`, `body: { keys, data }`. 서버 알림.
+
+## 사용
+
+```ts
+function dispatch(msg: ServiceServerMessage) {
+  switch (msg.name) {
+    case "response": return resolveCall(msg.body);
+    case "error":    return rejectCall(msg.body);
+    case "evt:on":   return notifyListeners(msg.body.keys, msg.body.data);
+  }
+}
+```

package/claude/references/sd-simplysm14/apis/service-common/protocol.md

@@ -0,0 +1,64 @@
+# @simplysm/service-common — protocol
+
+서비스 transport(웹소켓 등) 위에 얹는 바이너리 메시지 프로토콜(V2). 메시지를 청크로 자르고/재조립하며, 청크 누적의 GC 까지 캡슐화한다.
+
+## PROTOCOL_CONFIG
+
+```ts
+const PROTOCOL_CONFIG = {
+  MAX_TOTAL_SIZE: 100 * 1024 * 1024, // 100MB 한계 (인/디코딩 양쪽에서 검사)
+  SPLIT_MESSAGE_SIZE: 3 * 1024 * 1024, // 이 크기 초과 시 청크 분할
+  CHUNK_SIZE: 300 * 1024,              // 청크 본문 크기
+  GC_INTERVAL: 10 * 1000,              // 청크 누적기 GC 주기
+  EXPIRE_TIME: 60 * 1000,              // 미완성 메시지 만료
+} as const;
+```
+
+`as const`. 임계값 조정 필요 시 이 상수를 참조한다.
+
+## ServiceProtocol
+
+```ts
+interface ServiceProtocol {
+  encode(uuid: string, message: ServiceMessage): { chunks: Bytes[]; totalSize: number };
+  decode<T extends ServiceMessage>(bytes: Bytes): ServiceMessageDecodeResult<T>;
+  dispose(): void;
+}
+```
+
+- 청크 헤더 28B: UUID 16B + TotalSize 8B(uint64, 상위 4B 는 0) + Index 4B(uint32), Big Endian.
+- 본문: `json.stringify([name, body?])` UTF-8.
+- `dispose()` 는 내부 `LazyGcMap` 의 GC 타이머를 해제. 인스턴스 종료 시 반드시 호출.
+
+## ServiceMessageDecodeResult
+
+```ts
+type ServiceMessageDecodeResult<T extends ServiceMessage> =
+  | { type: "complete"; uuid: string; message: T }
+  | { type: "progress"; uuid: string; totalSize: number; completedSize: number };
+```
+
+- `complete`: 모든 청크 수신·재조립 완료. 메시지 디스패치 가능.
+- `progress`: 청크 일부만 도착. 진행률 표시·`progress` 알림 송신에 사용.
+
+## createServiceProtocol()
+
+`ServiceProtocol` 인스턴스를 생성한다. 서버·클라이언트 각자 1 개씩 보유하는 것이 일반적.
+
+```ts
+const proto = createServiceProtocol();
+const { chunks } = proto.encode(uuid, { name: "User.findOne", body: [{ id: 1 }] });
+for (const c of chunks) socket.send(c);
+
+const res = proto.decode<ServiceServerMessage>(receivedBytes);
+if (res.type === "complete") handle(res.message);
+```
+
+예외:
+
+- `MAX_TOTAL_SIZE` 초과: `ArgumentError("메시지 크기가 제한을 초과했습니다.")`.
+- 헤더(<28B) 미달: `ArgumentError("버퍼 크기가 헤더 크기보다 작습니다.")`.
+- 본문 JSON 파싱 실패: `ArgumentError("메시지 디코딩에 실패했습니다.", { uuid, cause })`.
+- 무결성 위반(누적 크기 > totalSize): `ArgumentError("프로토콜 무결성 위반: ...")`.
+
+중복 청크는 인덱스가 이미 채워진 경우 무시(방어). 만료(`EXPIRE_TIME`) 시 누적 항목은 GC 가 폐기.

package/claude/references/sd-simplysm14/apis/service-common/service-types.md

@@ -0,0 +1,43 @@
+# @simplysm/service-common — service-types
+
+서버 구현·클라이언트 호출이 공유하는 빌트인 서비스 인터페이스. 서버는 인터페이스를 구현, 클라이언트는 동일 시그니처로 RPC 호출한다.
+
+## OrmService
+
+```ts
+interface OrmService {
+  getInfo(opt: DbConnOptions & { configName: string }): Promise<{ dialect: Dialect; database?: string; schema?: string }>;
+  connect(opt: DbConnOptions & { configName: string }): Promise<number>; // connId
+  close(connId: number): Promise<void>;
+  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[][]>;
+  bulkInsert(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>;
+}
+
+type DbConnOptions = { configName?: string; config?: Record<string, unknown> };
+```
+
+MySQL / MSSQL / PostgreSQL 공통 추상. `connId` 단위로 트랜잭션·세션 식별. `Dialect`·`IsolationLevel`·`QueryDef`·`ColumnMeta`·`ResultMeta` 는 `@simplysm/orm-common` 정의.
+
+## AutoUpdateService
+
+```ts
+interface AutoUpdateService {
+  getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>;
+}
+```
+
+`platform` 예: `"win32" | "darwin" | "linux"`. 등록된 버전 없으면 `undefined`.
+
+## AppStructureService
+
+```ts
+interface AppStructureService {
+  getItems(): Record<string, AppStructureItem[]>;
+}
+```
+
+키는 클라이언트명, 값은 해당 클라이언트의 앱 구조 트리. `AppStructureItem` 은 [app-structure.md](./app-structure.md) 참조.

package/claude/references/sd-simplysm14/apis/service-server/README.md

@@ -0,0 +1,20 @@
+# @simplysm/service-server
+
+Fastify 기반 서비스 서버. HTTP/WebSocket 양 전송 위에서 "서비스(`이름`+`메서드 맵`)" 단위로 RPC, JWT 인증, 정적 파일, 업로드, 이벤트 브로드캐스트, V1 레거시 호환을 제공한다.
+
+## 사용 트리거 인덱스
+
+- **`ServiceServer` / `createServiceServer` / `ServiceServerOptions`** — 서버 인스턴스 생성·기동·종료·이벤트 브로드캐스트·JWT 발급. 자세히: [server.md](./server.md)
+- **`defineService` / `auth` / `ServiceContext` / `ServiceMethods`** — 서비스 정의 및 메서드/팩토리 인증 래퍼, 컨텍스트 헬퍼. 자세히: [define-service.md](./define-service.md)
+- **`AuthTokenPayload` / `signJwt` / `verifyJwt` / `decodeJwt`** — JWT 토큰 페이로드 타입 및 직접 서명/검증 유틸. 자세히: [auth.md](./auth.md)
+- **빌트인 서비스 (`OrmService` / `AutoUpdateService` / `AppStructureService`)** — `services` 옵션에 그대로 등록해 ORM 프록시·자동 업데이트·앱 메뉴 트리 제공. 자세히: [builtin-services.md](./builtin-services.md)
+- **전송/프로토콜/레거시 내부** (`handleHttpRequest`, `handleUpload`, `handleStaticFile`, `createWebSocketHandler`, `createServiceSocket`, `createServerProtocolWrapper`, `handleV1Connection` 등) — `ServiceServer.listen()` 이 자동 사용. 커스텀 Fastify 라우트 직조 시에만 직접 호출. 자세히: [internals.md](./internals.md)
+
+## `getConfig`
+
+```ts
+import { getConfig } from "@simplysm/service-server";
+const conf = await getConfig<{ orm: { default: DbConnConfig } }>(filePath);
+```
+
+`<rootPath>/.config.json` 같은 JSON 설정 파일을 읽고 LazyGcMap 캐시 + `FsWatcher` 로 핫리로드한다. 보통은 `ctx.getConfig(section)` 으로 충분하며, 이 함수를 직접 호출할 일은 root/client 경로 외 설정 파일을 읽을 때만 있다.

package/claude/references/sd-simplysm14/apis/service-server/auth.md

@@ -0,0 +1,31 @@
+# @simplysm/service-server — auth
+
+JWT 페이로드 타입 및 서명/검증 유틸. 일반 시나리오에서는 `server.signAuthToken` / `server.verifyAuthToken` 이 동일 알고리즘으로 감싸므로 그쪽을 쓴다. 이 모듈을 직접 import 하는 경우는 토큰 발급/검증을 서버 인스턴스 없이 수행해야 할 때 (테스트, 별도 인증 서비스, 디코드 등).
+
+## `AuthTokenPayload<TAuthInfo>`
+
+```ts
+interface AuthTokenPayload<TAuthInfo = unknown> extends jose.JWTPayload {
+  roles: string[];                 // auth(["role"], fn) 검사 대상
+  data: TAuthInfo;                 // ctx.authInfo 로 노출
+}
+```
+
+## `signJwt(jwtSecret, payload) → Promise<string>`
+
+HS256, `iat` 자동, 만료 `12h` 고정. 토큰 수명을 바꿔야 하면 이 함수 대신 직접 `jose.SignJWT` 를 쓴다.
+
+## `verifyJwt<TAuthInfo>(jwtSecret, token) → Promise<AuthTokenPayload<TAuthInfo>>`
+
+검증 실패 시 `토큰이 만료되었습니다.` 또는 `유효하지 않은 토큰입니다.` 를 throw.
+
+## `decodeJwt<TAuthInfo>(token) → AuthTokenPayload<TAuthInfo>`
+
+서명 검증 없이 페이로드만 디코드. 클라이언트 측 만료 표시 등 비보안 용도에만.
+
+## 예제
+
+```ts
+const token = await signJwt(secret, { roles: ["admin"], data: { userId: "U1" } });
+const payload = await verifyJwt<{ userId: string }>(secret, token);
+```

package/claude/references/sd-simplysm14/apis/service-server/builtin-services.md

@@ -0,0 +1,47 @@
+# @simplysm/service-server — builtin-services
+
+`ServiceServerOptions.services` 에 그대로 푸시해서 쓰는 사전 정의 서비스. 각각의 `*ServiceType` 은 클라이언트 측에서 `client.getService<*ServiceType>("<이름>")` 로 타입 공유한다.
+
+## `OrmService` / `OrmServiceType`
+
+이름 alias: `["Orm", "SdOrmService"]`. **WebSocket 전용** (HTTP 호출 시 throw — 트랜잭션을 소켓 라이프타임에 묶기 위함). `auth()` 로 감싸져 있어 로그인 필요.
+
+설정: `ctx.getConfig("orm")` 으로 `Record<string, DbConnConfig>` 를 읽고 `opt.configName` 으로 선택. 클라이언트가 `opt.config` 로 일부 필드 override 가능.
+
+메서드: `getInfo`, `connect → connId`, `close(connId)`, `beginTransaction(connId, isolation?)`, `commitTransaction`, `rollbackTransaction`, `executeParametrized(connId, sql, params?)`, `executeDefs(connId, defs, optionsMeta?)`, `bulkInsert(connId, table, colDefs, records)`. 소켓 close 시 그 소켓의 모든 연결을 자동 정리.
+
+## `AutoUpdateService` / `AutoUpdateServiceType`
+
+이름 alias: `["AutoUpdate", "SdAutoUpdateService"]`. 인증 없음.
+
+`getLastVersion(platform)` — `<clientPath>/<platform>/updates/` 디렉토리에서 `android` 는 `.apk`, 그 외는 `.exe` 중 `semver.maxSatisfying("*")` 으로 최신을 골라 `{ version, downloadPath }` 반환. 없으면 `undefined`.
+
+## `AppStructureService(itemsMap) → ServiceDefinition` / `AppStructureServiceType`
+
+다른 두 서비스와 달리 **팩토리 호출 결과**를 등록한다. 이름 `"AppStructure"`, 인증 없음.
+
+```ts
+import { AppStructureService } from "@simplysm/service-server";
+import type { AppStructureItem } from "@simplysm/service-common";
+
+const itemsMap: Record<string, AppStructureItem[]> = { admin: [...], shop: [...] };
+services: [AppStructureService(itemsMap)];
+```
+
+`getItems()` 한 메서드만 노출. 클라이언트 메뉴/라우트 트리 공급용.
+
+## 등록 예제
+
+```ts
+import { createServiceServer, OrmService, AutoUpdateService, AppStructureService } from "@simplysm/service-server";
+
+createServiceServer({
+  rootPath, port: 50080, auth: { jwtSecret },
+  services: [
+    OrmService,
+    AutoUpdateService,
+    AppStructureService(appItemsMap),
+    MyAppService,
+  ],
+});
+```