@simplysm/sd-claude 14.0.98 → 14.0.99

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

@@ -1,15 +1,15 @@
 # @simplysm/service-server
 
-Fastify 기반 RPC 서비스 서버. WebSocket/HTTP 두 전송으로 서비스 메서드를 노출하고, JWT 인증·정적 파일·파일 업로드·서버측 이벤트 브로드캐스트·내장 ORM/자동업데이트 서비스를 한 프로세스에서 제공한다.
+Fastify 위에서 동작하는 RPC 서버. `defineService` 로 정의한 서비스를 WebSocket·HTTP(`/api/:service/:method`) 두 전송으로 노출하고, JWT 인증·정적 파일 서빙·파일 업로드·서버측 이벤트 브로드캐스트·내장 ORM/자동업데이트 서비스를 한 프로세스에서 제공한다.
 
 ## 사용 트리거 인덱스
 
-- **서버 부트스트랩** (`createServiceServer`, `ServiceServer`, `ServiceServerOptions`, `getEvent`/`emitEvent`) — 서버 앱 진입점에서 옵션을 주고 서버를 띄우거나, 서비스 메서드에서 클라이언트로 이벤트를 발생시킬 때. 아래 인라인 섹션.
-- **서비스 작성** (`defineService`, `auth`, `ServiceContext`, `ServiceMethods`, `ServiceDefinition`, `getServiceAuthPermissions`) — RPC 로 노출할 서비스 메서드를 정의하고 컨텍스트·인증·권한을 붙일 때. 자세히: [service-authoring.md](./service-authoring.md)
-- **JWT 인증 토큰** (`signJwt`, `verifyJwt`, `decodeJwt`, `AuthTokenPayload`) — 로그인 처리에서 토큰을 서명·검증할 때. 아래 인라인 섹션.
-- **내장 서비스** (`OrmService`, `AutoUpdateService` 및 `*Methods` 타입) — DB 원격 실행·앱 자동업데이트를 서버 옵션 `services` 에 끼워넣을 때. 아래 인라인 섹션.
-- **전송 계층 내부** (`executeServiceMethod`, `createServiceContext`, `ServiceSocket`, `WebSocketHandler`, `ServerProtocolWrapper`, HTTP/정적/업로드 핸들러, `getConfig`) — 커스텀 전송·테스트·디버깅에서 내부 구성요소를 직접 다룰 때. 자세히: [transport-internals.md](./transport-internals.md)
-- **V1 레거시 지원** (`handleV1Connection`, `V1ConnectionOptions`, `V1RequestHandler` 등) — 구버전(ver≠2) 클라이언트의 WebSocket 연결을 받아 자동업데이트만 응대할 때. 자세히: [v1-legacy.md](./v1-legacy.md)
+- **서버 부트스트랩** (이 문서 인라인): `createServiceServer` / `ServiceServer` / `ServiceServerOptions` / `ServerEventProxy` — 서버 앱 진입점에서 옵션을 주고 기동·종료하거나, 서비스 메서드에서 클라이언트로 이벤트를 발생시킬 때.
+- **JWT 인증 토큰** (이 문서 인라인): `AuthTokenPayload` / `signJwt` / `verifyJwt` / `decodeJwt` — 로그인 처리에서 토큰을 서명·검증할 때.
+- **서비스 작성** — `defineService` / `auth` / `getServiceAuthPermissions` / `ServiceContext` / `createServiceContext` / `ServiceDefinition` / `ServiceMethods`. 자세히: [service-authoring.md](./service-authoring.md)
+- **내장 서비스** — `OrmService` / `OrmServiceMethods` / `AutoUpdateService` / `AutoUpdateServiceMethods`. 자세히: [built-in-services.md](./built-in-services.md)
+- **전송 계층 내부** — `executeServiceMethod` / `createServiceContext` / `ServiceSocket` / `createServiceSocket` / `WebSocketHandler` / `createWebSocketHandler` / `ServerProtocolWrapper` / `createServerProtocolWrapper` / `handleHttpRequest` / `handleUpload` / `handleStaticFile` / `getConfig`. 자세히: [transport-internals.md](./transport-internals.md)
+- **V1 레거시** — `handleV1Connection` / `V1ConnectionOptions` / `V1Request` / `V1Response` / `V1AutoUpdateMethods` / `V1RequestHandler` / `V1RequestHandlerResult` / `V1RequestHandlerContext`. 자세히: [v1-legacy.md](./v1-legacy.md)
 
 ## 서버 부트스트랩
 
@@ -17,24 +17,40 @@ Fastify 기반 RPC 서비스 서버. WebSocket/HTTP 두 전송으로 서비스
 
 ### createServiceServer / ServiceServer
 
-`createServiceServer<TAuthInfo = unknown>(options: ServiceServerOptions): ServiceServer<TAuthInfo>` — 옵션으로 서버 인스턴스를 생성(아직 리슨 안 함). `new ServiceServer<TAuthInfo>(options)` 직접 생성과 동일. `TAuthInfo` 는 인증 토큰 `data` 페이로드 타입으로 `server.signAuthToken`·`server.verifyAuthToken`·`ctx.authInfo` 에 그대로 흐른다.
+```ts
+function createServiceServer<TAuthInfo = unknown>(options: ServiceServerOptions): ServiceServer<TAuthInfo>;
+```
+
+옵션으로 서버 인스턴스를 생성한다(이 시점엔 아직 리슨하지 않음). `new ServiceServer<TAuthInfo>(options)` 직접 생성과 동일하다.
+
+- `TAuthInfo` — 인증 토큰 `data` 페이로드 타입. `signAuthToken`·`verifyAuthToken`·`ServiceContext.authInfo` 가 모두 이 타입으로 묶인다.
 
 `ServiceServerOptions` 필드:
 
 - `rootPath: string` — 서버 작업 루트. 정적 파일·업로드·자동업데이트는 `rootPath/www` 하위를, 설정은 `rootPath/.config.json` 을 기준으로 한다. 절대경로 권장.
-- `port: number` — 리슨 포트(`host: "0.0.0.0"` 고정). `0` 을 주면 OS 가 임의 포트를 할당하므로 테스트용으로 쓰고, 실제 포트는 `server.fastify.server.address()` 로 확인.
-- `ssl?: { pfxBytes: Uint8Array; passphrase: string }` — HTTPS 인증서. `pfxBytes` = PFX 바이트(내부에서 `Buffer` 로 변환), `passphrase` = PFX 비밀번호. 지정 시 HTTPS 로 기동하고 HSTS·crossOriginOpenerPolicy 보안 헤더가 켜진다. 미지정 시 HTTP(평문)로 뜨고 `upgrade-insecure-requests` CSP 가 해제된다. 사내망 평문이면 생략, 외부 노출이면 지정.
-- `auth?: { jwtSecret: string } | false` — JWT 인증 설정. 객체면 `jwtSecret` 으로 토큰 서명·검증; `false` 면 인증을 의도적으로 비활성(권한 요구 메서드도 인증 검사 스킵); `undefined`(미지정)이면서 권한 요구(`auth(...)` 래핑) 서비스가 하나라도 있으면 `listen()` 이 에러로 중단. 인증 쓰는 앱이면 객체, 인증을 명시적으로 끄려면 `false`.
-- `services: ServiceDefinition[]` — `defineService` 로 만든 서비스 정의 배열. RPC 로 노출할 서비스 전부를 여기 등록.
-- `legacyV1Handlers?: V1RequestHandler[]` — V1(ver≠2) 레거시 클라이언트의 커스텀 요청 핸들러. 자세히: [v1-legacy.md](./v1-legacy.md).
+- `port: number` — 리슨 포트(바인딩 호스트는 `"0.0.0.0"` 고정). `0` 을 주면 OS 가 임의 포트를 할당하므로 테스트에 쓰고, 실제 포트는 `server.fastify.server.address()` 로 확인한다.
+- `ssl?: { pfxBytes: Uint8Array; passphrase?: string } | { pemKeyBytes: Uint8Array; certBytes: Uint8Array; caBytes?: Uint8Array; passphrase?: string } | { letsencrypt: { domains: string[]; email: string; staging?: boolean } }` — HTTPS 인증서. 형식은 들어온 필드로 구분한다.
+  - `pfxBytes` 가 있으면 PFX 방식(인증서+키 번들, `passphrase` 는 PFX 비밀번호).
+  - `pemKeyBytes`+`certBytes` 가 있으면 PEM 방식(`pemKeyBytes` 개인키·`certBytes` 인증서, 선택적으로 `caBytes` 중간 CA 체인·`passphrase` 암호화된 키 비밀번호). 바이트는 내부에서 `Buffer` 로 변환.
+  - `letsencrypt` 가 있으면 Let's Encrypt 자동 발급/갱신. `domains` 인증서를 TLS-ALPN-01 챌린지로 발급해 `rootPath/.acme/`(계정키·인증서·키)에 저장하고, 만료 30일 전 자동 갱신 후 무중단 교체한다. `email` 은 LE 계정 연락처, `staging: true` 면 LE 스테이징(레이트리밋 회피, 테스트용)을 쓴다. 캐시된 유효 인증서가 있으면 즉시 적용하고, 없으면 최초 발급 완료까지 `listen()` 이 대기하며 발급 실패 시 throw 한다(`SD_ACME_DIRECTORY_URL` 환경변수로 ACME 디렉토리 URL 재정의 가능 — 사설 CA·테스트용).
+
+  지정 시(어느 방식이든) HTTPS 로 기동하고 HSTS·`crossOriginOpenerPolicy` 보안 헤더가 켜진다. 미지정 시 HTTP(평문)로 뜨고 `upgrade-insecure-requests` CSP 가 해제된다. 사내망 평문이면 생략, 외부 노출이면 지정.
+
+  `letsencrypt` 전제(코드 밖, 운영자 책임):
+  - **Node 20.18.0+ 또는 22.9.0+** — 핸드셰이크 중 인증서를 주입하는 `TLSSocket.setKeyCert` 가 필요하다. 미만이면 기동 시 throw.
+  - TLS-ALPN-01 은 **와일드카드 불가** — `domains` 는 정확한 FQDN.
+  - 검증 connection 이 포트 443 으로 인입되어 이 서버에 도달해야 한다: 공개 DNS A 레코드 → 서버, 앞단에 L4 프록시가 있으면 SNI 기준으로 이 서버에 패스스루(예: nginx `stream` + `ssl_preread`). 도메인 CAA 가 `letsencrypt.org` 를 허용하고, 서버에서 LE API 로 아웃바운드가 가능해야 한다.
+- `auth?: { jwtSecret: string } | false` — JWT 인증 설정. 객체면 `jwtSecret` 으로 토큰을 서명·검증한다. `false` 면 인증을 **의도적으로 비활성화**(`auth(...)` 래핑 메서드도 인증 검사 스킵). `undefined`(미지정)인데 권한 요구(`auth(...)` 래핑) 서비스가 하나라도 등록돼 있으면 `listen()` 이 throw — 설정 누락과 의도적 비활성화를 구분한다.
+- `services: ServiceDefinition[]` — `defineService` 로 만든 서비스 정의 배열. RPC 로 노출할 서비스 전부를 여기 등록한다. 라우팅은 정의의 `names` 매칭으로 이뤄진다.
+- `legacyV1Handlers?: V1RequestHandler[]` — V1(ver≠2) 레거시 클라이언트용 커스텀 요청 핸들러(선택). 자세히: [v1-legacy.md](./v1-legacy.md).
 
 `ServiceServer<TAuthInfo>` 멤버(`EventEmitter<{ ready: void; close: void }>` 상속):
 
 - `readonly options: ServiceServerOptions` — 생성 시 받은 옵션 원본.
-- `readonly fastify: FastifyInstance` — 내부 Fastify 인스턴스. 포트 조회·추가 라우트 등록 등에 직접 접근.
-- `isOpen: boolean` — 리슨 성공 후 `true`, `close()` 후 `false`.
-- `listen(): Promise<void>` — 플러그인 등록(websocket/helmet/multipart/static/cors) 후 리슨. 완료 시 `"ready"` 이벤트 발생, `SIGINT`/`SIGTERM` 정상 종료 핸들러 등록(10초 내 미종료 시 강제 `process.exit(1)`). `auth` 미설정인데 권한 요구 서비스가 있으면 시작 전 throw.
-- `close(): Promise<void>` — 모든 WebSocket 종료 후 Fastify 종료, `"close"` 이벤트 발생.
+- `readonly fastify: FastifyInstance` — 내부 Fastify 인스턴스. 실제 포트 조회·추가 라우트 등록 등에 직접 접근한다.
+- `isOpen: boolean` — `listen()` 성공 후 `true`, `close()` 후 `false`. 정상 종료 핸들러가 중복 close 를 막는 데 쓴다.
+- `listen(): Promise<void>` — 플러그인 등록(websocket·helmet·multipart·static·cors) → 라우트 바인딩 → 리슨 → 정상 종료 핸들러(`SIGINT`/`SIGTERM`, 10초 내 미종료 시 강제 `process.exit(1)`) 등록 후 `"ready"` 이벤트 발생. `auth` 미설정인데 권한 요구 서비스가 있으면 시작 전 throw.
+- `close(): Promise<void>` — 모든 WebSocket 연결 종료 후 Fastify 종료, `"close"` 이벤트 발생.
 - `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>` — `auth.jwtSecret` 으로 토큰 서명. 시크릿 미설정 시 throw.
 - `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>` — 토큰 검증·디코드. 시크릿 미설정 시 throw.
 - `getEvent`/`emitEvent` — 아래 "서버측 이벤트 발생" 참조.
@@ -50,14 +66,14 @@ const server = createServiceServer<AuthInfo>({
 await server.listen();
 ```
 
-주의: `auth` 를 미지정한 채 권한 요구 서비스를 등록하면 `listen()` 이 즉시 throw 한다. 인증을 끄려면 `auth: false` 를 명시할 것.
+주의: `auth` 를 미지정한 채 권한 요구 서비스를 등록하면 `listen()` 이 즉시 throw 한다. 인증을 끄려면 `auth: false` 를 명시한다.
 
 ### 서버측 이벤트 발생
 
 서비스 메서드 처리 결과를 구독 중인 클라이언트에 브로드캐스트할 때. 이벤트 정의 객체(`@simplysm/service-common` 의 `defineEvent`)는 클라이언트·서버가 공유한다.
 
-- `emitEvent<TEventDef>(eventDef: TEventDef, infoSelector: (info: TEventDef["$info"]) => boolean, data: TEventDef["$data"]): Promise<void>` — `eventDef.eventName` 을 구독한 전 클라이언트 리스너 중 `infoSelector(info)` 가 `true` 인 대상에게만 `data` 전송. 전체 전송은 `() => true`, 어느 구독에도 안 걸리면 전송 자체가 생략됨.
-- `getEvent<TEventDef>(eventDef): ServerEventProxy<TEventDef>` — 같은 이벤트를 반복 발생시킬 때 쓰는 프록시. `proxy.emit(infoSelector, data)` 는 `emitEvent` 와 동일.
+- `emitEvent<TEventDef>(eventDef: TEventDef, infoSelector: (info: TEventDef["$info"]) => boolean, data: TEventDef["$data"]): Promise<void>` — `eventDef.eventName` 을 구독한 전 클라이언트 리스너 중 `infoSelector(info)` 가 `true` 인 대상에게만 `data` 전송. 전체 전송은 `() => true`, 어느 구독에도 안 걸리면 전송 자체가 생략된다.
+- `getEvent<TEventDef>(eventDef): ServerEventProxy<TEventDef>` — 같은 이벤트를 반복 발생시킬 때 쓰는 프록시. `proxy.emit(infoSelector, data)` 는 `emitEvent` 와 동일하게 동작한다.
 - `ServerEventProxy<TEventDef>` — `{ emit(infoSelector, data): Promise<void> }` 형태. 구독(리스너 등록)은 클라이언트 전용이라 서버에는 발생 메서드만 있다.
 
 ```ts
@@ -75,14 +91,14 @@ export const OrderService = defineService("Order", (ctx) => ({
 
 ## JWT 인증 토큰
 
-로그인 서비스 메서드에서 자격 확인 후 토큰을 발급하고, 다른 메서드에서 토큰을 검증할 때. 보통은 `server.signAuthToken`/`server.verifyAuthToken`(시크릿 자동 사용)을 쓰고, 시크릿을 직접 다룰 때만 아래 함수를 호출.
+로그인 서비스 메서드에서 자격 확인 후 토큰을 발급하고, 다른 메서드에서 토큰을 검증할 때. 보통은 `server.signAuthToken`/`server.verifyAuthToken`(시크릿 자동 사용)을 쓰고, 시크릿을 직접 다룰 때만 아래 함수를 호출한다.
 
-- `AuthTokenPayload<TAuthInfo>` — JWT 페이로드. `jose` 의 `JWTPayload`(`exp`/`iat` 등)를 확장하며 다음을 추가한다.
-  - `roles: string[]` — 권한 역할 목록. `auth(["admin"], ...)` 의 권한 매칭 대상.
-  - `data: TAuthInfo` — 앱 정의 사용자 정보. `ctx.authInfo` 로 노출.
-- `signJwt<TAuthInfo>(jwtSecret: string, payload: AuthTokenPayload<TAuthInfo>): Promise<string>` — HS256 으로 서명. `iat` 자동 설정, 만료 12시간 고정.
-- `verifyJwt<TAuthInfo>(jwtSecret: string, token: string): Promise<AuthTokenPayload<TAuthInfo>>` — 서명·만료 검증 후 페이로드 반환. 만료 시 "토큰이 만료되었습니다.", 그 외 검증 실패 시 "유효하지 않은 토큰입니다." 로 throw.
-- `decodeJwt<TAuthInfo>(token: string): AuthTokenPayload<TAuthInfo>` — 서명 검증 없이 페이로드만 디코드(동기). 검증이 끝난 토큰의 내용만 다시 읽을 때 사용하고, 만료·위변조 판정에는 쓰지 말 것.
+- `AuthTokenPayload<TAuthInfo>` — JWT 페이로드. `jose` 의 `JWTPayload`(`exp`·`iat` 등)를 확장하며 다음을 추가한다.
+  - `roles: string[]` — 권한 역할 목록. `auth(["admin"], ...)` 의 권한 매칭 대상으로, 요구 역할 중 하나라도 이 배열에 있으면 통과.
+  - `data: TAuthInfo` — 앱이 정의하는 사용자 정보. `ctx.authInfo` 로 노출된다.
+- `signJwt<TAuthInfo>(jwtSecret: string, payload: AuthTokenPayload<TAuthInfo>): Promise<string>` — HS256 으로 서명. `iat` 자동 설정, 만료는 12시간 고정.
+- `verifyJwt<TAuthInfo>(jwtSecret: string, token: string): Promise<AuthTokenPayload<TAuthInfo>>` — 서명·만료 검증 후 페이로드 반환. 만료(`ERR_JWT_EXPIRED`)면 `"토큰이 만료되었습니다."`, 그 외 검증 실패면 `"유효하지 않은 토큰입니다."` 로 throw.
+- `decodeJwt<TAuthInfo>(token: string): AuthTokenPayload<TAuthInfo>` — 서명 검증 없이 페이로드만 디코드(동기). 이미 검증된 토큰의 내용만 다시 읽을 때 쓰고, 만료·위변조 판정에는 쓰지 말 것.
 
 ```ts
 const AuthService = defineService("Auth", (ctx) => ({
@@ -92,23 +108,3 @@ const AuthService = defineService("Auth", (ctx) => ({
   },
 }));
 ```
-
-## 내장 서비스
-
-서버 옵션 `services` 배열에 그대로 추가해 쓰는 미리 정의된 서비스. 두 이름(별칭)으로 노출되며, 클라이언트 타입 공유용 `*Methods` 타입도 함께 export 된다.
-
-- `OrmService` / `OrmServiceMethods` — `["Orm", "SdOrmService"]` 두 이름으로 노출. 전체가 `auth(...)` 래핑이라 로그인 필요하고, **WebSocket 전송 전용**(소켓 단위로 DB 커넥션을 풀링하므로 HTTP 호출 시 throw). DB 접속 정보는 `ctx.getConfig("orm")[configName]` 으로 `rootPath/.config.json` 의 `orm` 섹션에서 읽는다. 소켓이 닫히면 그 소켓의 모든 커넥션을 자동 정리. 메서드:
-  - `getInfo(opt)` — dialect·database·schema 조회(`mssql-azure` 는 `mssql` 로 정규화).
-  - `connect(opt)` — 새 DB 연결을 풀에 추가하고 정수 `connId` 반환.
-  - `close(connId)` — 해당 연결 종료.
-  - `beginTransaction(connId, isolationLevel?)` / `commitTransaction(connId)` / `rollbackTransaction(connId)` — connId 대상 트랜잭션 제어.
-  - `executeParametrized(connId, query, params?)` — 파라미터 바인딩 SQL 실행.
-  - `executeDefs(connId, defs, options?)` — `QueryDef[]` 를 dialect 에 맞춰 빌드·실행하고, `options[i]` 가 있으면 결과를 파싱·반환(전부 `null` 이면 일괄 실행만).
-  - `bulkInsert(connId, tableName, columnDefs, records)` — 대량 삽입.
-- `AutoUpdateService` / `AutoUpdateServiceMethods` — `["AutoUpdate", "SdAutoUpdateService"]` 두 이름으로 노출. 인증 불필요. 메서드 `getLastVersion(platform: string)` 은 `rootPath/www/<clientName>/<platform>/updates` 에서 `android` 면 `.apk`, 그 외면 `.exe` 파일 중 semver 최대 버전을 찾아 `{ version, downloadPath }` 반환(대상 없으면 `undefined`).
-
-```ts
-services: [OrmService, AutoUpdateService, ...앱서비스들]
-```
-
-주의: 두 내장 서비스는 클라이언트가 짧은 이름(`getService("Orm")`/`getService("AutoUpdate")`) 또는 레거시 이름(`SdOrmService`/`SdAutoUpdateService`) 어느 쪽으로도 호출할 수 있다.

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

@@ -0,0 +1,35 @@
+# @simplysm/service-server — 내장 서비스
+
+서버 옵션 `services` 배열에 그대로 추가해 쓰는 미리 정의된 `ServiceDefinition` 두 개. 각각 두 이름(별칭)으로 노출되며, 클라이언트 타입 공유용 `*Methods` 타입도 함께 export 된다. 클라이언트는 짧은 이름 또는 레거시 이름 어느 쪽으로도 호출할 수 있다.
+
+```ts
+services: [OrmService, AutoUpdateService, ...앱서비스들]
+```
+
+## OrmService / OrmServiceMethods
+
+`["Orm", "SdOrmService"]` 두 이름으로 노출. DB 접속을 원격 실행 RPC 로 제공하는 서비스로, 클라이언트의 ORM 커넥터가 호출한다.
+
+- 전체가 `auth(...)` 래핑이라 **로그인 필요**.
+- **WebSocket 전송 전용** — 소켓 단위로 DB 커넥션을 풀링(`WeakMap<ServiceSocket, Map<connId, DbConn>>`)하므로, `ctx.socket` 이 없는 HTTP 호출 시 `"WebSocket 연결이 필요합니다..."` throw.
+- DB 접속 정보는 `ctx.getConfig<...>("orm")[configName]` 으로 `rootPath/.config.json` 의 `orm` 섹션에서 읽고, 호출 `opt.config` 로 덮어쓴다. 설정이 없으면 throw.
+- 소켓이 닫히면 그 소켓의 열린 모든 커넥션을 자동 정리한다.
+
+메서드(`OrmServiceMethods`):
+
+- `getInfo(opt: DbConnOptions & { configName }): Promise<{ dialect; database?; schema? }>` — 접속 설정의 dialect·database·schema 조회. `dialect` 가 `"mssql-azure"` 면 `"mssql"` 로 정규화해 돌려준다.
+- `connect(opt: DbConnOptions & { configName }): Promise<number>` — 새 DB 연결을 풀에 추가하고 정수 `connId` 반환. 같은 소켓의 첫 연결 시 소켓 `close` 핸들러를 걸어 종료 시 정리하도록 등록한다.
+- `close(connId: number): Promise<void>` — 해당 연결 종료. 종료 중 에러는 무시(warn 로그)된다.
+- `beginTransaction(connId: number, isolationLevel?: IsolationLevel): Promise<void>` — 트랜잭션 시작. `isolationLevel` 미지정 시 드라이버 기본값.
+- `commitTransaction(connId: number): Promise<void>` / `rollbackTransaction(connId: number): Promise<void>` — `connId` 대상 트랜잭션 커밋·롤백.
+- `executeParametrized(connId: number, query: string, params?: unknown[]): Promise<unknown[][]>` — 파라미터 바인딩 SQL 실행.
+- `executeDefs(connId: number, defs: QueryDef[], options?: (ResultMeta | undefined)[]): Promise<unknown[][]>` — `QueryDef[]` 를 dialect 에 맞춰 빌드·실행. `options` 가 전부 `null`/`undefined` 면 전체를 한 번에 일괄 실행만 하고 빈 결과를 돌려주며, 각 `options[i]` 가 있으면 해당 결과셋을 파싱해 반환한다.
+- `bulkInsert(connId: number, tableName: string, columnDefs: Record<string, ColumnMeta>, records: Record<string, unknown>[]): Promise<void>` — 대량 삽입.
+
+## AutoUpdateService / AutoUpdateServiceMethods
+
+`["AutoUpdate", "SdAutoUpdateService"]` 두 이름으로 노출. 인증 불필요. 배포된 앱 클라이언트가 최신 설치본을 조회하는 데 쓴다.
+
+- `getLastVersion(platform: string): Promise<{ version: string; downloadPath: string } | undefined>` — `rootPath/www/<clientName>/<platform>/updates` 디렉터리에서 후보 파일을 골라 semver 최대 버전을 찾는다. `platform === "android"` 면 `.apk`, 그 외면 `.exe` 확장자에 파일명이 `^[0-9.]*$` 인 것만 후보. 대상 버전이 있으면 `{ version, downloadPath }`(다운로드 경로는 `/<clientName>/<platform>/updates/<파일>` posix 경로), 없으면 `undefined`. `ctx.clientPath` 가 없으면 throw.
+
+주의: `getLastVersion` 은 ver≠2 레거시 클라이언트의 `SdAutoUpdateService.getLastVersion` fallback 으로도 자동 연결된다(레거시 흐름은 [v1-legacy.md](./v1-legacy.md) 참조).

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

@@ -1,6 +1,6 @@
 # @simplysm/service-server — 서비스 작성
 
-RPC 로 노출할 서비스 메서드를 정의하고, 컨텍스트로 인증 정보·클라이언트 정보·설정에 접근하며, 인증·권한을 붙일 때 같이 읽는 묶음. 서버 옵션 `services` 에 등록할 `ServiceDefinition` 을 만드는 것이 목표.
+RPC 로 노출할 서비스 메서드를 정의하고, 요청 컨텍스트로 인증 정보·클라이언트 정보·설정에 접근하며, 인증·권한을 붙일 때 읽는 묶음. 서버 옵션 `services` 에 등록할 `ServiceDefinition` 을 만드는 것이 목표다.
 
 ## defineService
 
@@ -8,12 +8,13 @@ RPC 로 노출할 서비스 메서드를 정의하고, 컨텍스트로 인증
 function defineService<TMethods extends Record<string, (...args: any[]) => any>>(
   name: string | string[],
   factory: (ctx: ServiceContext) => TMethods,
-): ServiceDefinition<TMethods>
+): ServiceDefinition<TMethods>;
 ```
 
-- `name: string | string[]` — 서비스 이름. 배열이면 여러 이름(별칭)으로 동시 노출하며 첫 요소가 대표 이름(`definition.name`). 빈 배열이면 throw. 클라이언트는 이 이름으로 `getService("<name>")` 호출. 신/구 이름을 같이 받으려면 `["New", "Old"]`.
-- `factory: (ctx) => TMethods` — **요청마다 호출**되어 메서드 객체를 반환하는 팩토리. `ctx` 로 그 요청의 인증·클라이언트 정보가 들어오므로 메서드 안에서 `ctx.*` 를 자유롭게 참조. 요청 간 공유 상태(커넥션 풀 등)는 팩토리 바깥 모듈 스코프에 둘 것.
-- 반환 `TMethods` 의 각 값은 클라이언트가 호출할 메서드. 동기·비동기 모두 가능하며 반환값이 그대로 응답으로 직렬화된다.
+- `name: string | string[]` — 서비스 이름. 배열이면 여러 이름(별칭)으로 동시 노출하며 첫 요소가 대표 이름(`definition.name`)이 된다. 빈 배열이면 throw. 클라이언트는 이 이름으로 `getService("<name>")` 호출한다. 신·구 이름을 같이 받으려면 `["New", "Old"]`.
+- `factory: (ctx) => TMethods` — **요청마다 호출**되어 메서드 객체를 반환하는 팩토리. `ctx` 로 그 요청의 인증·클라이언트 정보가 들어오므로 메서드 안에서 `ctx.*` 를 참조한다. 요청 간 공유 상태(커넥션 풀 등)는 팩토리 바깥 모듈 스코프에 둔다.
+- 반환 `TMethods` 의 각 값이 클라이언트가 호출할 메서드. 동기·비동기 모두 가능하며 반환값이 그대로 응답으로 직렬화된다.
+- 반환 `ServiceDefinition` 의 `authPermissions` 는 `factory` 가 `auth(...)` 래핑이면 그 권한 배열, 아니면 `undefined` 로 자동 채워진다.
 
 ```ts
 export const UserService = defineService("User", (ctx) => ({
@@ -32,11 +33,11 @@ function auth<TFn extends (...args: any[]) => any>(fn: TFn): TFn;
 function auth<TFn extends (...args: any[]) => any>(permissions: string[], fn: TFn): TFn;
 ```
 
-- `auth(fn)` — 로그인만 요구(권한 역할 무관). 토큰이 없으면 "로그인이 필요합니다." throw.
-- `auth(permissions, fn)` — `permissions: string[]` 의 역할 중 하나라도 토큰 `roles` 에 있어야 통과. 없으면 "권한이 부족합니다." throw. 빈 배열은 `auth(fn)` 과 동일(로그인만).
-- **서비스 수준**: `defineService("User", auth((ctx) => ({ ... })))` — 그 서비스의 모든 메서드에 적용. `defineService` 가 `authPermissions` 로 추출.
-- **메서드 수준**: 반환 객체 안 개별 메서드를 `auth(...)` 로 감쌈. 메서드 수준 권한이 서비스 수준보다 우선.
-- 적용 우선순위: 메서드 래핑 권한 → 없으면 서비스 권한. 서버 옵션 `auth` 가 `undefined` 면 권한 요구 메서드 호출 시 설정 오류 throw, `false` 면 인증 검사 자체를 스킵.
+- `auth(fn)` — 로그인만 요구(권한 역할 무관). 토큰이 없으면 `"로그인이 필요합니다."` throw.
+- `auth(permissions, fn)` — `permissions: string[]` 의 역할 중 하나라도 토큰 `roles` 에 있어야 통과. 없으면 `"권한이 부족합니다."` throw. 빈 배열은 `auth(fn)` 과 동일(로그인만).
+- **서비스 수준 적용**: `defineService("User", auth((ctx) => ({ ... })))` — 그 서비스의 모든 메서드에 적용. `defineService` 가 권한을 `authPermissions` 로 추출한다.
+- **메서드 수준 적용**: 반환 객체 안 개별 메서드를 `auth(...)` 로 감싼다. 메서드 수준 권한이 서비스 수준보다 우선한다.
+- 적용 우선순위: 메서드 래핑 권한 → 없으면 서비스 권한. 서버 옵션 `auth` 가 `undefined` 면 권한 요구 메서드 호출 시 설정 오류 throw, `false` 면 인증 검사 자체를 스킵한다.
 
 ```ts
 export const AdminService = defineService("Admin", auth((ctx) => ({
@@ -45,18 +46,18 @@ export const AdminService = defineService("Admin", auth((ctx) => ({
 })));
 ```
 
-## ServiceContext
+## ServiceContext / createServiceContext
 
-`factory` 가 요청마다 받는 컨텍스트. 메서드 안에서 인증·클라이언트·설정·서버에 접근하는 통로.
+`factory` 가 요청마다 받는 컨텍스트. 메서드 안에서 인증·클라이언트·설정·서버에 접근하는 통로다. `createServiceContext(server, socket?, http?, legacy?)` 가 생성하나, 일반 작성에서는 `factory` 의 인자로 자동 주입되므로 직접 만들 일은 테스트뿐이다.
 
 - `server: ServiceServer<TAuthInfo>` — 서버 인스턴스. `ctx.server.emitEvent(...)` 로 이벤트 발생, `ctx.server.signAuthToken(...)` 로 토큰 발급.
-- `socket?: ServiceSocket` — WebSocket 요청일 때만 존재하는 소켓. HTTP 요청이면 `undefined`(소켓 필요한 기능은 존재 검사 필수).
+- `socket?: ServiceSocket` — WebSocket 요청일 때만 존재하는 소켓. HTTP 요청이면 `undefined`(소켓이 필요한 기능은 존재 검사 필수).
 - `http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> }` — HTTP 요청일 때만 존재.
 - `legacy?: { clientName?: string }` — V1 레거시 연결 컨텍스트(자동업데이트 전용).
-- `get authInfo(): TAuthInfo | undefined` — 검증된 토큰의 `data` 페이로드(소켓→HTTP 순). 비로그인 요청이면 `undefined`(결측을 그대로 노출하므로 받는 쪽도 옵셔널로 다룰 것).
-- `get clientName(): string | undefined` — 요청 클라이언트 이름(소켓→HTTP→레거시 순 우선). 빈 문자열·`..`·슬래시(`/`,`\`) 포함 등 경로 탈출 위험 값이면 throw.
-- `get clientPath(): string | undefined` — `rootPath/www/<clientName>` 절대경로. clientName 없으면 `undefined`.
-- `getConfig<T>(section: string): Promise<T>` — `rootPath/.config.json` 루트 설정에 클라이언트별 `www/<clientName>/.config.json` 을 머지한 뒤 `section` 키 값을 반환. 섹션이 없으면 throw. 설정 파일은 변경 시 자동 리로드(파일 워처 + 캐시).
+- `get authInfo(): TAuthInfo | undefined` — 검증된 토큰의 `data` 페이로드(소켓→HTTP 순으로 조회). 비로그인 요청이면 `undefined` — 결측을 그대로 노출하므로 받는 쪽도 옵셔널로 다룬다.
+- `get clientName(): string | undefined` — 요청 클라이언트 이름(소켓→HTTP→레거시 순 우선). 빈 문자열·`..`·슬래시(`/`·`\`) 포함 등 경로 탈출 위험 값이면 throw.
+- `get clientPath(): string | undefined` — `rootPath/www/<clientName>` 절대경로. `clientName` 이 없으면 `undefined`.
+- `getConfig<T>(section: string): Promise<T>` — `rootPath/.config.json` 루트 설정에 클라이언트별 `www/<clientName>/.config.json` 을 머지한 뒤 `section` 키 값을 반환. 섹션이 없으면 throw. 설정 파일은 변경 시 자동 리로드된다(파일 워처 + 캐시).
 
 ```ts
 export const ReportService = defineService("Report", auth((ctx) => ({
@@ -68,7 +69,7 @@ export const ReportService = defineService("Report", auth((ctx) => ({
 ## ServiceDefinition / ServiceMethods / getServiceAuthPermissions
 
 - `ServiceDefinition<TMethods>` — `defineService` 반환 타입. `{ name: string; names: string[]; factory: (ctx) => TMethods; authPermissions?: string[] }`. `name` 은 대표 이름, `names` 는 별칭 전체, `authPermissions` 는 서비스 수준 `auth` 권한(없으면 `undefined`).
-- `type ServiceMethods<TDefinition>` — `ServiceDefinition<M>` 에서 메서드 시그니처 `M` 만 추출하는 타입 유틸. 클라이언트와 서비스 타입을 공유하려고 common 패키지에 `export type XxxServiceMethods = ServiceMethods<typeof XxxService>` 로 재노출하고, 클라이언트는 `client.getService<XxxServiceMethods>("Xxx")` 로 사용.
-- `getServiceAuthPermissions(fn: Function): string[] | undefined` — `auth(...)` 로 래핑된 함수에서 권한 배열을 읽음. 래핑 안 됐으면 `undefined`. 내부 실행기·커스텀 전송에서만 필요(일반 작성에서는 불필요).
+- `type ServiceMethods<TDefinition>` — `ServiceDefinition<M>` 에서 메서드 시그니처 `M` 만 추출하는 타입 유틸. 클라이언트와 서비스 타입을 공유하려고 common 패키지에 `export type XxxServiceMethods = ServiceMethods<typeof XxxService>` 로 재노출하고, 클라이언트는 `client.getService<XxxServiceMethods>("Xxx")` 로 쓴다.
+- `getServiceAuthPermissions(fn: Function): string[] | undefined` — `auth(...)` 로 래핑된 함수에서 권한 배열을 읽는다. 래핑 안 됐으면 `undefined`. 내부 실행기·커스텀 전송에서만 필요하고 일반 작성에서는 쓰지 않는다.
 
 주의: 클라이언트가 쓰는 서비스 이름 문자열과 `ServiceMethods` 타입은 단일 소스(`defineService` 이름 / `typeof XxxService`)를 따른다. 호출부에서 이름·제네릭을 중복 정의하지 말 것.

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

@@ -14,22 +14,20 @@ function executeServiceMethod(
     socket?: ServiceSocket;
     http?: { clientName: string; authTokenPayload?: AuthTokenPayload };
   },
-): Promise<unknown>
+): Promise<unknown>;
 ```
 
-요청 1건을 실제 서비스 메서드로 라우팅·실행하는 핵심 게이트키퍼. WebSocket/HTTP 핸들러가 모두 이 함수로 수렴한다.
+요청 1건을 실제 서비스 메서드로 라우팅·실행하는 핵심 게이트키퍼. WebSocket·HTTP 핸들러가 모두 이 함수로 수렴한다.
 
-- `serviceName` / `methodName` — `server.options.services` 의 `names` 매칭으로 서비스를, 그 팩토리 산출 객체에서 메서드를 찾음. 없으면 throw.
-- `params: unknown[]` — 메서드 인자 배열. 스프레드되어 메서드에 전달.
-- `socket?` / `http?` — 둘 중 하나로 요청 출처 전달. `clientName` 에 `..`·슬래시(`/`,`\`)가 있으면 보안 차단 throw.
-- 동작: 컨텍스트 생성 → 팩토리 호출 → 메서드 조회 → 인증/권한 검사(`auth` 래핑 권한 기준) → 실행 후 반환값 반환. `auth: false` 면 인증 스킵, `auth` 미설정인데 권한 요구 메서드면 설정 오류 throw.
+- `serviceName` / `methodName` — `server.options.services` 의 `names` 매칭으로 서비스를, 그 팩토리 산출 객체에서 메서드를 찾는다. 없으면 throw.
+- `params: unknown[]` — 메서드 인자 배열. 스프레드되어 메서드에 전달된다.
+- `socket?` / `http?` — 둘 중 하나로 요청 출처를 전달. `clientName` 에 `..`·슬래시(`/`·`\`)가 있으면 보안 차단 throw.
+- 동작 순서: 컨텍스트 생성 → 팩토리 호출 → 메서드 조회 → 인증·권한 검사(`auth` 래핑 권한 기준) → 실행 후 반환값 반환. `auth: false` 면 인증 스킵, `auth` 미설정인데 권한 요구 메서드면 설정 오류 throw.
 
 ## createServiceContext
 
 ```ts
-function createServiceContext<TAuthInfo>(
-  server, socket?, http?, legacy?,
-): ServiceContext<TAuthInfo>
+function createServiceContext<TAuthInfo>(server, socket?, http?, legacy?): ServiceContext<TAuthInfo>;
 ```
 
 `ServiceContext`(인증·클라이언트·설정 접근자) 인스턴스를 만든다.
@@ -39,23 +37,23 @@ function createServiceContext<TAuthInfo>(
 - `http?: { clientName; authTokenPayload? }` — HTTP 요청 출처.
 - `legacy?: { clientName? }` — V1 레거시 출처(`clientName` 만).
 
-컨텍스트 필드 의미는 [service-authoring.md](./service-authoring.md) 의 ServiceContext 절 참조. 테스트에서 컨텍스트를 직접 만들어 서비스 메서드를 단위 호출할 때 유용.
+컨텍스트 필드 의미는 [service-authoring.md](./service-authoring.md) 의 ServiceContext 절 참조. 테스트에서 컨텍스트를 직접 만들어 서비스 메서드를 단위 호출할 때 유용하다.
 
 ## ServiceSocket / createServiceSocket
 
-단일 WebSocket 연결을 감싸 프로토콜 인코딩·ping/pong 연결 유지·이벤트 리스너 추적을 담당하는 인터페이스. `createServiceSocket(socket, clientId, clientName, connReq)` 로 생성.
+단일 WebSocket 연결을 감싸 프로토콜 인코딩·ping/pong 연결 유지·이벤트 리스너 추적을 담당하는 인터페이스. `createServiceSocket(socket, clientId, clientName, connReq)` 로 생성한다.
 
 - `readonly connectedAtDateTime: DateTime` — 연결 성립 시각.
 - `readonly clientName: string` — 연결 시 받은 클라이언트 이름.
 - `readonly connReq: FastifyRequest` — 원본 연결 요청(원격 주소 등).
 - `authTokenPayload?: AuthTokenPayload` — 소켓 `auth` 메시지로 검증된 토큰. 이후 그 소켓 요청의 `ctx.authInfo` 출처(set 으로 갱신).
 - `close(): void` — 소켓 즉시 종료(terminate).
-- `send(uuid, msg): Promise<number>` — 서버 메시지를 프로토콜로 인코딩해 전송, 보낸 바이트 수 반환(소켓 미개방이면 `0`).
-- `addListener(key, eventName, info): void` — 이벤트 구독 등록. `key` = 구독 식별자, `info` = selector 매칭용 메타.
+- `send(uuid, msg): Promise<number>` — 서버 메시지를 프로토콜로 인코딩해 전송하고 보낸 바이트 수 반환(소켓 미개방이면 `0`).
+- `addListener(key, eventName, info): void` — 이벤트 구독 등록. `key` 는 구독 식별자, `info` 는 selector 매칭용 메타.
 - `removeListener(key): void` — `key` 로 구독 1건 해제.
-- `getEventListeners(eventName): { key, info }[]` — 해당 이벤트의 구독 목록 조회.
+- `getEventListeners(eventName): { key; info }[]` — 해당 이벤트의 구독 목록 조회.
 - `filterEventTargetKeys(targetKeys): string[]` — 주어진 키 중 이 소켓에 존재하는 것만 반환.
-- `on("error" | "close" | "message", handler): void` — 소켓 이벤트 후킹. 5초 주기 ping, pong 미수신 시 자동 terminate.
+- `on("error" | "close" | "message", handler): void` — 소켓 이벤트 후킹. 5초 주기로 ping 하고 pong 미수신 시 자동 terminate 한다.
 
 ## WebSocketHandler / createWebSocketHandler
 
@@ -63,36 +61,36 @@ function createServiceContext<TAuthInfo>(
 function createWebSocketHandler(
   runMethod: (def) => Promise<unknown>,
   jwtSecret: string | undefined,
-): WebSocketHandler
+): WebSocketHandler;
 ```
 
 여러 `ServiceSocket` 을 `clientId` 로 관리하고, 클라이언트 메시지를 `runMethod`(보통 `executeServiceMethod` 바인딩)로 라우팅하며, 이벤트를 브로드캐스트한다.
 
-- `addSocket(socket, clientId, clientName, connReq): void` — 연결 등록. 같은 `clientId` 의 기존 연결은 닫고 교체. 생성 중 예외 시 소켓 terminate.
+- `addSocket(socket, clientId, clientName, connReq): void` — 연결 등록. 같은 `clientId` 의 기존 연결은 닫고 교체한다. 생성 중 예외 시 소켓 terminate.
 - `closeAll(): void` — 모든 연결 종료(서버 `close()` 시 호출).
 - `emit<TEventDef>(eventName, infoSelector, data): Promise<void>` — 전 소켓의 해당 이벤트 구독 중 `infoSelector(info)` 가 `true` 인 키에게만 `evt:on` 메시지 전송. `ServiceServer.emitEvent` 의 실제 구현.
-- 처리하는 클라이언트 메시지 종류: `"<service>.<method>"`(RPC 호출), `evt:add`/`evt:remove`/`evt:gets`/`evt:emit`(이벤트 구독·해제·조회·발생), `auth`(소켓 토큰 검증). 그 외는 `BAD_MESSAGE` 에러 응답. 처리 중 예외는 `INTERNAL_ERROR` 응답이며, `DEV` 환경에서만 에러 스택 포함.
+- 처리하는 클라이언트 메시지 종류: `"<service>.<method>"`(RPC 호출), `evt:add`·`evt:remove`·`evt:gets`·`evt:emit`(이벤트 구독·해제·조회·발생), `auth`(소켓 토큰 검증). 그 외는 `BAD_MESSAGE` 에러 응답. 처리 중 예외는 `INTERNAL_ERROR` 응답이며, `DEV` 환경에서만 에러 스택을 포함한다.
 
 ## HTTP / 정적 / 업로드 핸들러
 
-`fastify` 라우트에 직접 물리는 저수준 함수들. 커스텀 라우트를 짤 때만 직접 사용.
+`fastify` 라우트에 직접 물리는 저수준 함수들. 커스텀 라우트를 짤 때만 직접 사용한다.
 
-- `handleHttpRequest(req, reply, jwtSecret, runMethod)` — `/api/:service/:method` 처리. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <token>` 검증(실패 시 401). GET 은 `?json=` 쿼리, POST 는 배열 본문에서 파라미터를 받아 `runMethod` 실행. 본문이 배열이 아니면 400, 그 외 HTTP 메서드는 405.
-- `handleUpload(req, reply, rootPath, jwtSecret)` — `/upload` multipart 처리. multipart 아니면 400, 인증 토큰 필수(없거나 무효면 401). 파일을 `rootPath/www/uploads/<uuid><ext>` 로 저장하고 `ServiceUploadResult[]`(`{ path, filename, size }`) 반환. 도중 실패 시 그 요청에서 저장한 파일을 모두 롤백 삭제 후 500.
+- `handleHttpRequest(req, reply, jwtSecret, runMethod)` — `/api/:service/:method` 처리. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <token>` 검증(실패 시 401). GET 은 `?json=` 쿼리, POST 는 배열 본문에서 파라미터를 받아 `runMethod` 를 실행한다. 본문이 배열이 아니면 400, 그 외 HTTP 메서드는 405.
+- `handleUpload(req, reply, rootPath, jwtSecret)` — `/upload` multipart 처리. multipart 가 아니면 400, 인증 토큰 필수(없거나 무효면 401). 파일을 `rootPath/www/uploads/<uuid><ext>` 로 저장하고 `ServiceUploadResult[]`(`{ path, filename, size }`) 반환. 도중 실패하면 그 요청에서 저장한 파일을 모두 롤백 삭제 후 500.
 - `handleStaticFile(req, reply, rootPath, urlPath)` — `rootPath/www` 하위 정적 파일 전송. `www` 밖 경로는 차단(throw), 디렉터리면 슬래시 리다이렉트 후 `index.html`, `.` 으로 시작하는 숨김 파일은 403, 미존재는 404, 그 외 전송 실패는 500 HTML 응답. SPA 폴백: 미존재 + 확장자 없는 페이지 요청이면 `www` 루트 방향으로 가장 가까운 `index.csr.html`(SSG 클라이언트의 SPA 셸)을 찾아 반환 — 셸 파일이 없는 기존 클라이언트는 그대로 404.
 
 ## ServerProtocolWrapper / createServerProtocolWrapper
 
-메시지 인코딩/디코딩을 크기·내용에 따라 worker 스레드와 메인 스레드로 자동 분배하는 래퍼. `createServerProtocolWrapper()` 로 생성(worker 는 지연 싱글턴, 소켓 간 공유).
+메시지 인코딩·디코딩을 크기·내용에 따라 worker 스레드와 메인 스레드로 자동 분배하는 래퍼. `createServerProtocolWrapper()` 로 생성한다(worker 는 지연 싱글턴이라 소켓 간 공유).
 
-- `encode(uuid, message): Promise<{ chunks: Bytes[]; totalSize: number }>` — `body` 에 `Uint8Array` 가 있으면(단일 또는 배열 요소 중 하나라도) worker, 아니면 메인 스레드에서 인코딩.
-- `decode(bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>` — 청크 재조립(stateful)은 항상 메인 스레드 단일 누적기에서, 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 worker 위임. 진행 중이면 `{ type: "progress" }`, 완료면 `{ type: "complete", uuid, message }`.
+- `encode(uuid, message): Promise<{ chunks: Bytes[]; totalSize: number }>` — `body` 에 `Uint8Array` 가 있으면(단일이거나 배열 요소 중 하나라도) worker, 아니면 메인 스레드에서 인코딩.
+- `decode(bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>>` — 청크 재조립(stateful)은 항상 메인 스레드 단일 누적기에서 수행하고, 재조립 완료 후 30KB 초과 JSON 파싱(stateless)만 worker 에 위임. 진행 중이면 `{ type: "progress" }`, 완료면 `{ type: "complete", uuid, message }`.
 - `dispose(): void` — 프로토콜 리소스 해제.
 
 ## getConfig
 
 ```ts
-function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>
+function getConfig<TConfig>(filePath: string): Promise<TConfig | undefined>;
 ```
 
 `filePath` JSON 설정을 읽어 캐시·파일워치한다. `ServiceContext.getConfig` 의 내부 구현. 캐시 히트 시 즉시 반환(접근 시 만료 시간 갱신), 파일 변경 시 자동 리로드, 1시간 무접근 시 캐시·워처 GC. 파일이 없으면 `undefined`.

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

@@ -1,6 +1,6 @@
 # @simplysm/service-server — V1 레거시 지원
 
-`ver !== "2"`(구버전) WebSocket 클라이언트를 받기 위한 레거시 핸들러. 주로 구버전 앱의 자동업데이트(`SdAutoUpdateService.getLastVersion`) 요청을 처리한다. `ServiceServer` 는 ver=2 가 아닌 연결을 자동으로 이 핸들러로 넘긴다(`AutoUpdate` 서비스나 `legacyV1Handlers` 가 있을 때만, 둘 다 없으면 코드 1008 로 연결 거부). `ServiceServerOptions.legacyV1Handlers` 로 커스텀 핸들러를 끼울 때만 직접 다룬다.
+`ver !== "2"`(구버전) WebSocket 클라이언트를 받기 위한 레거시 핸들러. 주로 구버전 앱의 자동업데이트(`SdAutoUpdateService.getLastVersion`) 요청을 처리한다. `ServiceServer` 는 ver=2 가 아닌 연결을 자동으로 이 핸들러로 넘기며(`AutoUpdate` 서비스나 `legacyV1Handlers` 가 있을 때만, 둘 다 없으면 코드 1008 로 연결 거부), `ServiceServerOptions.legacyV1Handlers` 로 커스텀 핸들러를 끼울 때만 직접 다룬다.
 
 ## handleV1Connection
 
@@ -9,27 +9,27 @@ function handleV1Connection(socket, autoUpdateMethods: V1AutoUpdateMethods, clie
 function handleV1Connection(socket, options: V1ConnectionOptions): void;
 ```
 
-V1 WebSocket 연결 1건을 받아 연결 알림(`{ name: "connected" }`) 전송 후 메시지를 처리한다. 처리 순서: 커스텀 핸들러들 → (미처리 시) `SdAutoUpdateService.getLastVersion` fallback → 그래도 미처리면 `UPGRADE_REQUIRED` 에러 응답. 메시지 파싱·처리 중 예외는 잡아 warn 로그만 남기고 응답하지 않는다.
+V1 WebSocket 연결 1건을 받아 연결 알림(`{ name: "connected" }`)을 보낸 뒤 메시지를 처리한다. 처리 순서: 커스텀 핸들러들 → (미처리 시) `SdAutoUpdateService.getLastVersion` fallback → 그래도 미처리면 `UPGRADE_REQUIRED` 에러 응답. 메시지 파싱·처리 중 예외는 잡아 warn 로그만 남기고 응답하지 않는다.
 
 - `socket: WebSocket` — `ws` 의 원시 소켓.
-- 2번째 인자 — `V1AutoUpdateMethods` 객체(자동업데이트만 응대)이거나 `V1ConnectionOptions`(핸들러·팩토리 포함). `"getLastVersion" in arg` 로 분기.
-- `clientNameSetter?` — 첫 시그니처에서만. 요청의 `clientName` 을 외부에 통지하는 콜백.
+- 2번째 인자 — `V1AutoUpdateMethods` 객체(자동업데이트만 응대)이거나 `V1ConnectionOptions`(핸들러·팩토리 포함). `"getLastVersion" in arg` 로 분기한다.
+- `clientNameSetter?` — 첫 시그니처에서만 받는다. 요청의 `clientName` 을 외부에 통지하는 콜백.
 
 ## V1ConnectionOptions
 
 - `serviceContext?: ServiceContext` — 모든 요청에서 공유할 고정 컨텍스트.
-- `serviceContextFactory?: (request: V1Request) => ServiceContext` — 요청마다 컨텍스트를 새로 만들 때. `serviceContext` 보다 우선.
-- `handlers?: V1RequestHandler[]` — 커스텀 요청 핸들러 목록. 앞에서부터 호출되며 첫 `handled: true` 에서 멈춤. 핸들러가 있는데 컨텍스트가 없으면 throw.
+- `serviceContextFactory?: (request: V1Request) => ServiceContext` — 요청마다 컨텍스트를 새로 만들 때. `serviceContext` 보다 우선한다.
+- `handlers?: V1RequestHandler[]` — 커스텀 요청 핸들러 목록. 앞에서부터 호출되며 첫 `handled: true` 에서 멈춘다. 핸들러가 있는데 컨텍스트가 없으면 throw.
 - `autoUpdateMethods?: V1AutoUpdateMethods` — 자동업데이트 fallback 구현(고정).
-- `autoUpdateMethodsFactory?: (ctx: V1RequestHandlerContext) => V1AutoUpdateMethods` — 요청마다 fallback 구현 생성. 지정 시 `autoUpdateMethods` 대신 사용(컨텍스트 없으면 throw).
+- `autoUpdateMethodsFactory?: (ctx: V1RequestHandlerContext) => V1AutoUpdateMethods` — 요청마다 fallback 구현을 생성. 지정 시 `autoUpdateMethods` 대신 사용하며 컨텍스트가 없으면 throw.
 - `clientNameSetter?: (clientName: string | undefined) => void` — 매 요청 `clientName` 통지 콜백.
 
 ## V1RequestHandler 와 관련 타입
 
 - `V1Request` — `{ uuid: string; command: string; params: unknown[]; clientName?: string }`. 구버전 클라이언트가 보내는 요청 형태. `command` 는 `"<service>.<method>"` 형태의 명령 키.
-- `V1Response` — `{ name: "response"; reqUuid: string; state: "success" | "error"; body: unknown }`. 서버가 돌려보내는 응답 형태. `state` = 응답 상태로 `"success"`(정상)·`"error"`(오류) 구분.
+- `V1Response` — `{ name: "response"; reqUuid: string; state: "success" | "error"; body: unknown }`. 서버가 돌려보내는 응답 형태. `state` 는 응답 상태로 `"success"`(정상)·`"error"`(오류)를 구분.
 - `V1RequestHandlerContext` — `{ request: V1Request; serviceContext: ServiceContext }`. 핸들러가 받는 인자.
-- `V1RequestHandlerResult` — `{ handled: true; state?: "success" | "error"; body: unknown } | { handled: false }`. `handled` = 이 핸들러가 요청을 처리했는지. `false` 면 다음 핸들러·fallback 으로 넘어가고, `true` 면 그 `state`(기본 `"success"`)·`body` 로 즉시 응답.
+- `V1RequestHandlerResult` — `{ handled: true; state?: "success" | "error"; body: unknown } | { handled: false }`. `handled` 는 이 핸들러가 요청을 처리했는지 여부. `false` 면 다음 핸들러·fallback 으로 넘어가고, `true` 면 그 `state`(기본 `"success"`)·`body` 로 즉시 응답한다.
 - `V1RequestHandler` — `(ctx: V1RequestHandlerContext) => V1RequestHandlerResult | Promise<V1RequestHandlerResult>`. 동기·비동기 모두 가능.
 - `V1AutoUpdateMethods` — `{ getLastVersion: (platform: string) => Promise<unknown> | unknown }`. `SdAutoUpdateService.getLastVersion` 명령의 fallback 인터페이스.
 

package/claude/references/sd-simplysm14/apis/storage/README.md

@@ -1,17 +1,17 @@
 # @simplysm/storage
 
-Node.js 환경에서 FTP/FTPS/SFTP 원격 스토리지에 접속해 파일·디렉토리를 업로드·다운로드·조회·삭제하는 라이브러리. 프로토콜별 구현을 동일 인터페이스(`StorageClient`)로 통일하고, `StorageFactory.connect` 콜백 패턴으로 연결/종료를 자동 관리한다. 전 구현이 Node 전용(`basic-ftp`·`ssh2-sftp-client`·`fs`/`os`/`path`/`stream` 의존)이라 브라우저에서 사용 불가.
+Node 전용 라이브러리. FTP/FTPS/SFTP 원격 스토리지에 접속해 파일·디렉토리를 업로드·다운로드·조회·삭제한다. 프로토콜별 구현(`basic-ftp`·`ssh2-sftp-client`)을 단일 인터페이스 `StorageClient` 로 통일하고, `StorageFactory.connect` 콜백 패턴으로 연결/종료를 자동 관리한다. `fs`/`os`/`path`/`stream` 에 의존하므로 브라우저에서는 사용 불가.
 
 ## 사용 트리거 인덱스
 
-- **StorageFactory.connect** — 프로토콜·접속정보로 연결을 열고 콜백 안에서 파일 작업 후 자동 종료할 때. 직접 클라이언트 인스턴스화보다 권장되는 진입점.
-- **StorageClient** — connect 콜백이 받는 파일 작업 인터페이스(mkdir/list/put/readFile/exists/remove/rename/uploadDir 등). 어떤 메서드를 호출할 수 있는지 확인할 때.
+- **StorageFactory** — 프로토콜·접속정보로 연결을 열고 콜백 안에서 파일 작업 후 자동 종료할 때. 권장 진입점.
+- **StorageClient** — connect 콜백이 받는 파일 작업 인터페이스(connect/mkdir/rename/list/readFile/exists/put/uploadDir/remove/close). 호출 가능한 메서드를 확인할 때.
 - **StorageConnConfig / StorageProtocol / FileInfo** — connect 인자 형태, 지원 프로토콜 리터럴, list 반환 항목 형태를 확인할 때.
-- **FtpStorageClient / SftpStorageClient** — 팩토리 없이 연결을 직접 잡거나(수명·재연결 직접 제어), 프로토콜별 인증·동작 차이를 확인할 때. 비권장.
+- **FtpStorageClient / SftpStorageClient** — 팩토리 없이 연결 수명을 직접 제어하거나 프로토콜별 인증·동작 차이를 확인할 때. 비권장.
 
 ## StorageFactory (진입점)
 
-스토리지 접속 진입점. 인스턴스를 만들 필요 없이 정적 `connect` 만 사용한다. 연결 생성 → 콜백 실행 → 자동 종료를 한 번에 묶어 처리한다.
+스토리지 접속 진입점. 인스턴스화 없이 정적 `connect` 만 호출한다. 연결 생성 → 콜백 실행 → 자동 종료를 한 번에 묶어 처리한다.
 
 ```ts
 class StorageFactory {
@@ -23,10 +23,10 @@ class StorageFactory {
 }
 ```
 
-- `type: StorageProtocol` — 사용할 프로토콜. 내부에서 `"sftp"` → `SftpStorageClient`, `"ftps"` → `FtpStorageClient(secure=true)`, `"ftp"` → `FtpStorageClient(secure=false)` 를 생성. 보안 전송이 필요하면 `"ftps"`/`"sftp"`.
+- `type: StorageProtocol` — 사용할 프로토콜. 내부에서 `"sftp"` → `new SftpStorageClient()`, `"ftps"` → `new FtpStorageClient(true)`, `"ftp"` → `new FtpStorageClient(false)` 로 클라이언트를 생성. 보안 전송이 필요하면 `"ftps"`/`"sftp"`.
 - `config: StorageConnConfig` — 접속 설정(host/port/user/password). 아래 StorageConnConfig 참조.
-- `fn: (storage: StorageClient) => R | Promise<R>` — 연결된 `StorageClient` 를 받아 파일 작업을 수행하는 콜백. 반환값이 그대로 `connect` 의 결과(`Promise<R>`) 가 됨. 동기·비동기 모두 허용.
-- 동작: `client.connect(config)` 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 중 오류는 무시(이미 종료된 경우 대비). 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨.
+- `fn: (storage: StorageClient) => R | Promise<R>` — 연결된 `StorageClient` 를 받아 파일 작업을 수행하는 콜백. 반환값이 그대로 `connect` 의 결과(`Promise<R>`)가 됨. 동기·비동기 모두 허용.
+- 동작: `client.connect(config)` 성공 후 `fn` 실행, `finally` 에서 `client.close()` 호출하며 종료 중 오류는 `.catch(() => {})` 로 무시(이미 종료된 경우 대비). 콜백에서 예외가 나도 연결은 반드시 닫히고 예외는 그대로 전파됨.
 
 ```ts
 const names = await StorageFactory.connect("sftp", { host: "10.0.0.1", user: "u", password: "p" }, async (s) => {
@@ -49,9 +49,9 @@ interface StorageConnConfig { host: string; port?: number; user?: string; passwo
 ```
 
 - `host: string` — 접속 대상 서버 호스트명 또는 IP. 필수.
-- `port?: number` — 접속 포트. 미지정 시 각 라이브러리 기본값(FTP 21, SFTP 22) 사용. 비표준 포트면 명시.
-- `user?: string` — 로그인 사용자명. 미지정 시 익명/기본 사용자.
-- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 미지정이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키 + SSH agent(`SSH_AUTH_SOCK` 환경변수가 있으면 `agent` 옵션)로 인증을 시도하고, 키 파싱 실패(암호화 키 등) 시 agent 단독 재시도. FTP/FTPS 에서는 미지정 시 라이브러리 기본(익명) 처리. SFTP 키 인증을 쓰려면 password 를 넘기지 말 것.
+- `port?: number` — 접속 포트. 미지정 시 그대로 `undefined` 로 전달되어 각 라이브러리 기본 포트(`basic-ftp`/`ssh2-sftp-client` 기본값)를 사용. 비표준 포트면 명시.
+- `user?: string` — 로그인 사용자명(FTP `user`, SFTP `username` 으로 매핑). 미지정 시 라이브러리 기본 사용자.
+- `password?: string` — 로그인 비밀번호. **SFTP 에서 이 값이 `null`(미지정)이면** password 인증 대신 `~/.ssh/id_ed25519` 개인키로 인증을 시도하고(`SSH_AUTH_SOCK` 환경변수가 있으면 `agent` 옵션도 함께 사용), 키 파싱이 실패하면(암호화된 키 등) agent 단독으로 재시도한다. FTP/FTPS 는 미지정 시 그대로 라이브러리에 위임. SFTP 키 인증을 쓰려면 password 를 넘기지 말 것.
 
 ### StorageProtocol
 
@@ -59,9 +59,9 @@ interface StorageConnConfig { host: string; port?: number; user?: string; passwo
 type StorageProtocol = "ftp" | "ftps" | "sftp";
 ```
 
-- `"ftp"` — 평문 FTP. 보안 채널 없음(`FtpStorageClient` 를 `secure=false` 로 생성). 내부망·테스트에서만 권장.
-- `"ftps"` — TLS 로 암호화된 FTP(`FtpStorageClient` 를 `secure=true` 로 생성). 외부망 FTP 접속 시.
-- `"sftp"` — SSH 기반 SFTP(`SftpStorageClient`). 가장 일반적인 보안 전송.
+- `"ftp"` — 평문 FTP. `FtpStorageClient(false)` 생성(`secure=false`, TLS 없음). 내부망·테스트에서만 권장.
+- `"ftps"` — TLS 로 암호화된 FTP. `FtpStorageClient(true)` 생성(`secure=true`). 외부망 FTP 접속 시.
+- `"sftp"` — SSH 기반 SFTP. `SftpStorageClient` 생성. 가장 일반적인 보안 전송.
 
 ### FileInfo
 
@@ -72,11 +72,11 @@ interface FileInfo { name: string; isFile: boolean; }
 ```
 
 - `name: string` — 항목 이름(파일명 또는 디렉토리명, 경로 아님).
-- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. 디렉토리 탐색 시 파일만 골라 처리하는 분기 기준으로 사용. FTP 는 라이브러리의 `isFile`, SFTP 는 항목 type 이 `"-"`(일반 파일)인 경우만 `true`(디렉토리·심볼릭 링크는 `false`).
+- `isFile: boolean` — 파일이면 `true`, 디렉토리면 `false`. 디렉토리 탐색 시 파일만 골라 처리하는 분기 기준으로 사용. FTP 는 라이브러리의 `isFile` 값을 그대로 사용, SFTP 는 항목 `type` 이 `"-"`(일반 파일)일 때만 `true`(디렉토리·심볼릭 링크는 `false`).
 
 ### StorageClient
 
-`connect` 콜백 안에서 받는 파일 작업 인터페이스. `FtpStorageClient`·`SftpStorageClient` 가 구현. 모든 메서드는 `Promise` 반환. 경로는 원격 기준 경로 문자열.
+`connect` 콜백 안에서 받는 파일 작업 인터페이스. `FtpStorageClient`·`SftpStorageClient` 가 구현. 모든 메서드는 `Promise` 반환. 경로 인자는 원격 기준 경로 문자열.
 
 ```ts
 interface StorageClient {
@@ -93,15 +93,15 @@ interface StorageClient {
 }
 ```
 
-- `connect(config)` — 서버에 연결. 이미 연결된 인스턴스에서 재호출하면 `SdError` throw(먼저 `close()` 필요). `StorageFactory.connect` 사용 시 직접 호출 불필요. 연결 도중 실패하면 내부 라이브러리 연결을 닫고 예외를 다시 throw.
-- `mkdir(dirPath)` — 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성(FTP `ensureDir`, SFTP 재귀 `mkdir`).
-- `rename(fromPath, toPath)` — 파일/디렉토리 경로 이동·이름 변경. `toPath` 로 옮기거나 새 이름을 부여할 때.
+- `connect(config)` — 서버에 연결. 이미 연결된 인스턴스에서 재호출하면 `SdError`("이미 연결되어 있습니다") throw(먼저 `close()` 필요). 연결 도중 실패하면 내부 라이브러리 연결을 닫고(FTP `close()`, SFTP `end()`) 예외를 다시 throw. `StorageFactory.connect` 사용 시 직접 호출 불필요.
+- `mkdir(dirPath)` — 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성(FTP `ensureDir`, SFTP 재귀 `mkdir(path, true)`).
+- `rename(fromPath, toPath)` — 파일/디렉토리를 `fromPath` 에서 `toPath` 로 이동·이름 변경.
 - `list(dirPath)` — 디렉토리 내 항목을 `FileInfo[]` 로 반환. 목록을 파일/폴더로 갈라 처리할 때.
-- `readFile(filePath)` — 원격 파일 전체를 `Bytes`(Uint8Array) 로 메모리에 다운로드(스트리밍 아님 — 큰 파일은 메모리 부담). 텍스트가 필요하면 호출 측에서 디코딩. SFTP 는 응답이 예상 타입(Buffer/string) 이 아니면 `SdError` throw.
-- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 없음·권한·네트워크 오류 포함) 에 대해 `false` 반환** — throw 없음이므로 `true` 만 "확실히 존재"로 신뢰한다. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록으로 디렉토리 확인(슬래시 없는 경로는 루트 `/` 기준이라 항목 많은 디렉토리에서는 느려질 수 있음). SFTP 는 `exists()` 결과가 문자열(`'d'`/`'-'`/`'l'`)이면 존재로 판정. 작업 전 분기 확인에 사용.
-- `put(localPathOrBuffer, storageFilePath)` — 단일 파일 업로드. 첫 인자가 `string` 이면 로컬 파일 경로에서, `Bytes` 면 메모리 바이트에서 업로드. 생성한 콘텐츠를 바로 올릴 땐 `Bytes` 로 전달.
-- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 전체를 원격 디렉토리로 재귀 업로드. 빌드 산출물 폴더를 통째로 배포할 때.
-- `remove(filePath)` — 원격 파일 삭제.
+- `readFile(filePath)` — 원격 파일 전체를 `Bytes`(Uint8Array)로 메모리에 다운로드(스트리밍 아님 — 큰 파일은 메모리 부담). 텍스트가 필요하면 호출 측에서 디코딩(예: `new TextDecoder().decode(...)`). SFTP 는 응답이 예상 타입(Uint8Array/string)이 아니면 `SdError`("예상하지 못한 응답 타입입니다") throw.
+- `exists(filePath)` — 파일/디렉토리 존재 여부. **모든 예외(부모 디렉토리 없음·권한·네트워크 오류 포함)에 대해 `false` 반환** — throw 하지 않으므로 `true` 만 "확실히 존재"로 신뢰한다. FTP 는 `size()` 로 파일을 O(1) 확인 후 실패 시 부모 디렉토리 목록(`list`)으로 디렉토리/파일을 재확인(슬래시 없는 경로는 루트 `/` 기준 — 항목이 많은 디렉토리에서는 느려질 수 있음). SFTP 는 `exists()` 결과가 문자열(`'d'` 디렉토리/`'-'` 파일/`'l'` 심볼릭 링크)이면 존재로 판정. 작업 전 분기 확인에 사용.
+- `put(localPathOrBuffer, storageFilePath)` — 단일 파일 업로드. 첫 인자가 `string` 이면 로컬 파일 경로에서(FTP `uploadFrom`, SFTP `fastPut`), `Bytes` 면 메모리 바이트에서 업로드(FTP 는 `Readable.from` 스트림, SFTP 는 `Buffer.from` 변환). 생성한 콘텐츠를 바로 올릴 땐 `Bytes` 로 전달.
+- `uploadDir(fromPath, toPath)` — 로컬 디렉토리 `fromPath` 전체를 원격 디렉토리 `toPath` 로 재귀 업로드. 빌드 산출물 폴더를 통째로 배포할 때.
+- `remove(filePath)` — 원격 파일 삭제(FTP `remove`, SFTP `delete`).
 - `close()` — 연결 종료. 이미 종료/미연결 상태에서 호출해도 오류 없음. 종료 후 같은 인스턴스에서 `connect()` 로 재연결 가능. `StorageFactory.connect` 사용 시 직접 호출 불필요.
 
 미연결 상태에서 작업 메서드를 호출하면 모든 구현체가 `SdError`("연결되어 있지 않습니다") throw.
@@ -115,9 +115,9 @@ new FtpStorageClient(secure?: boolean)  // secure=true → FTPS, 생략/false
 new SftpStorageClient()
 ```
 
-- `FtpStorageClient` 의 `secure` 생성자 인자 — `true` 면 TLS(FTPS), 생략/`false`(기본) 면 평문 FTP. 팩토리는 `"ftps"`→`true`, `"ftp"`→`false` 로 매핑.
+- `FtpStorageClient` 의 `secure` 생성자 인자 — `true` 면 TLS(FTPS), 생략/`false`(기본)면 평문 FTP. 팩토리는 `"ftps"`→`true`, `"ftp"`→`false` 로 매핑.
 - `SftpStorageClient` 는 생성자 인자 없음. password 미지정 시 키/agent 인증 경로를 탄다(StorageConnConfig 의 `password` 풀이 참조).
-- 직접 사용 시 `connect()` → 작업 → `close()` 순으로 호출하고, 예외 발생 시에도 `close()` 가 호출되도록 `try/finally` 로 감쌀 것. 동일 인스턴스에서 `close()` 없이 `connect()` 를 재호출하면 연결 누수로 throw.
+- 직접 사용 시 `connect()` → 작업 → `close()` 순으로 호출하고, 예외 발생 시에도 `close()` 가 호출되도록 `try/finally` 로 감쌀 것. 동일 인스턴스에서 `close()` 없이 `connect()` 를 재호출하면 `SdError` throw(연결 누수 방지).
 
 ```ts
 const client = new SftpStorageClient();

package/claude/references/sd-simplysm14/manuals/client-component.md

@@ -1,5 +1,7 @@
 # 클라이언트 화면 작성 매뉴얼
 
+프리렌더(SSG) 대상 화면을 작성할 때는 [client-ssg.md](./client-ssg.md) 의 SSR-safe·서버 연결 제약을 함께 적용.
+
 ## 파일명·역할·위치
 
 화면 파일명은 `<domain>.<역할>.ts` 형식. 역할 접미사로 책임을 표시.
@@ -643,7 +645,13 @@ async onSubmit(): Promise<void> {
 
 ```html
 <sd-crud-list ...>
-  <ng-template #filterTpl>...</ng-template>
+  <ng-template #filterTpl>
+    <!-- sd-crud-list 가 이미 form-box-inline 으로 감싸므로 여기서 다시 묶지 않음 -->
+    <div>
+      <label>검색어</label>
+      <sd-textfield [type]="'text'" [(value)]="filter().searchText" (valueChange)="mark(filter)" />
+    </div>
+  </ng-template>
 
   <sd-sheet-column [key]="..." [header]="...">
     <ng-template [cell]="items()" let-item="item">...</ng-template>