@simplysm/sd-claude 14.0.53 → 14.0.55

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

@@ -9,154 +9,69 @@
 npm install @simplysm/service-server
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
-
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| 서버 생성 및 시작 | [`ServiceServer`](./main/service-server.md) |
-| 서비스 정의 | [`defineService`](./core/define-service.md) |
-| 인증 적용 | [`auth`](./core/auth.md) |
-| JWT 토큰 발급/검증 | [`signJwt`](./auth/sign-jwt.md), [`verifyJwt`](./auth/verify-jwt.md) |
-| 이벤트 브로드캐스트 | [`ServiceServer`](./main/service-server.md) (`getEvent` / `emitEvent`) |
-| ORM 서비스 등록 | [`OrmService`](./services/orm-service.md) |
-| 자동 업데이트 서비스 등록 | [`AutoUpdateService`](./services/auto-update-service.md) |
-| 파일 업로드 처리 | [`handleUpload`](./transport-http/handle-upload.md) |
-| 설정 파일 읽기 | [`getConfig`](./utils/get-config.md) |
+## 하려는 작업 → 읽을 파일
 
-## API Overview
-
-### Main
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServiceServer`](./main/service-server.md) | class | 서버를 생성하고 시작할 때. WebSocket/HTTP 라우팅, JWT 인증, 이벤트 브로드캐스트, graceful shutdown을 처리한다 |
-| [`ServerEventProxy`](./main/service-server.md#servereventproxy) | interface | `getEvent()`의 반환 타입을 참조할 때 |
-| [`createServiceServer`](./main/create-service-server.md) | function | `new ServiceServer()` 대신 팩토리 함수로 서버를 생성할 때 |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServiceServerOptions`](./types/service-server-options.md) | interface | 서버 생성 옵션을 구성할 때 (rootPath, port, ssl, auth, services) |
-
-### Auth
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`AuthTokenPayload`](./auth/auth-token-payload.md) | interface | JWT 페이로드 타입을 참조할 때 |
-| [`signJwt`](./auth/sign-jwt.md) | function | 서버 외부에서 직접 JWT 토큰을 서명할 때. 일반적으로는 `server.signAuthToken()` 사용을 권장 |
-| [`verifyJwt`](./auth/verify-jwt.md) | function | 서버 외부에서 직접 JWT 토큰을 검증할 때. 일반적으로는 `server.verifyAuthToken()` 사용을 권장 |
-| [`decodeJwt`](./auth/verify-jwt.md#decodejwt) | function | 검증 없이 토큰 내용을 확인할 때 (디버깅 등) |
-
-### Core
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`defineService`](./core/define-service.md) | function | 서비스를 정의할 때. 이름과 팩토리 함수로 구성한다 |
-| [`ServiceDefinition`](./core/define-service.md#servicedefinition) | interface | 서비스 정의 타입을 참조할 때 |
-| [`ServiceMethods`](./core/define-service.md#servicemethods) | type | 클라이언트 측 타입 공유를 위해 서비스 메서드 시그니처를 추출할 때 |
-| [`auth`](./core/auth.md) | function | 서비스 또는 메서드에 인증을 요구할 때 |
-| [`getServiceAuthPermissions`](./core/auth.md#getserviceauthpermissions) | function | `auth()`로 래핑된 함수의 권한 배열을 프로그래밍적으로 읽을 때 |
-| [`ServiceContext`](./core/service-context.md) | interface | 서비스 팩토리에서 컨텍스트 타입을 참조할 때 |
-| [`createServiceContext`](./core/service-context.md#createservicecontext) | function | 테스트 등에서 `ServiceContext`를 직접 생성할 때 |
-| [`executeServiceMethod`](./core/execute-service-method.md) | function | 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때 |
-
-### Transport - Socket
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`WebSocketHandler`](./transport-socket/websocket-handler.md) | interface | WebSocket 메시지 라우팅 및 이벤트 브로드캐스트 동작을 이해할 때 |
-| [`createWebSocketHandler`](./transport-socket/websocket-handler.md#createwebsockethandler) | function | 커스텀 WebSocket 핸들러를 생성할 때 |
-| [`ServiceSocket`](./transport-socket/service-socket.md) | interface | WebSocket 연결 추상화를 참조할 때. `ServiceContext.socket`의 타입이다 |
-| [`createServiceSocket`](./transport-socket/service-socket.md#createservicesocket) | function | 테스트 등에서 `ServiceSocket`을 직접 생성할 때 |
-
-### Transport - HTTP
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`handleHttpRequest`](./transport-http/handle-http-request.md) | function | HTTP API 요청 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
-| [`handleUpload`](./transport-http/handle-upload.md) | function | 파일 업로드 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
-| [`handleStaticFile`](./transport-http/handle-static-file.md) | function | 정적 파일 서빙 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다 |
-
-### Protocol
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`ServerProtocolWrapper`](./protocol/server-protocol-wrapper.md) | interface | 프로토콜 인코딩/디코딩 래퍼의 동작을 이해할 때. worker 스레드 자동 위임 기준을 확인할 때 |
-| [`createServerProtocolWrapper`](./protocol/server-protocol-wrapper.md#createserverprotocolwrapper) | function | 커스텀 프로토콜 래퍼를 생성할 때 |
-
-### Services
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`OrmService`](./services/orm-service.md) | const | DB 연결을 서비스 계층에서 제공할 때. WebSocket 전용, 인증 필수 |
-| [`OrmServiceType`](./services/orm-service.md#ormservicetype) | type | 클라이언트에서 ORM 서비스 타입을 참조할 때 |
-| [`AutoUpdateService`](./services/auto-update-service.md) | const | 클라이언트 앱 자동 업데이트를 제공할 때 |
-| [`AutoUpdateServiceType`](./services/auto-update-service.md#autoupdateservicetype) | type | 클라이언트에서 자동 업데이트 서비스 타입을 참조할 때 |
-| [`AppStructureService`](./services/app-structure-service.md) | function | 앱 구조 정보를 클라이언트에 제공할 때 |
-| [`AppStructureServiceType`](./services/app-structure-service.md#appstructureservicetype) | type | 클라이언트에서 앱 구조 서비스 타입을 참조할 때 |
-
-### Utils
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`getConfig`](./utils/get-config.md) | function | `.config.json` 파일을 캐싱 및 자동 리로드로 읽을 때 |
-
-### Legacy
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`handleV1Connection`](./legacy/handle-v1-connection.md) | function | V1 WebSocket 프로토콜 호환이 필요할 때. 자동 업데이트만 지원한다 |
-
-## Usage Examples
-
-### 서버 생성 및 시작
-
-```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,
-})));
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| Fastify 기반 서비스 서버를 생성하고 시작할 때 | [ServiceServer](./main/service-server.md) |
+| `new ServiceServer()` 대신 팩토리 함수로 서버를 생성할 때 | [createServiceServer](./main/create-service-server.md) |
+| 서버 생성 옵션(rootPath, port, ssl, auth, services)을 구성할 때 | [ServiceServerOptions](./types/service-server-options.md) |
 
-const server = createServiceServer<{ userId: string }>({
-  rootPath: "/app",
-  port: 3000,
-  auth: { jwtSecret: "my-secret" },
-  services: [HealthService, UserService],
-});
+### 서비스 정의 및 인증
 
-await server.listen();
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 이름과 팩토리 함수로 서비스를 정의할 때 | [defineService](./core/define-service.md) |
+| 서비스 또는 메서드에 로그인/역할 인증을 적용할 때 | [auth](./core/auth.md) |
+| 서비스 팩토리에서 컨텍스트(인증 정보, 설정 파일 등)에 접근할 때 | [ServiceContext](./core/service-context.md) |
+| 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때 | [executeServiceMethod](./core/execute-service-method.md) |
 
-### JWT 토큰 발급 및 검증
+### JWT 인증
 
-```typescript
-const token = await server.signAuthToken({
-  roles: ["admin"],
-  data: { userId: "123" },
-});
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| JWT 페이로드 타입을 참조할 때 | [AuthTokenPayload](./auth/auth-token-payload.md) |
+| 서버 외부에서 직접 JWT 토큰을 서명할 때 | [signJwt](./auth/sign-jwt.md) |
+| 서버 외부에서 직접 JWT 토큰을 검증/디코딩할 때 | [verifyJwt](./auth/verify-jwt.md) |
 
-const payload = await server.verifyAuthToken(token);
-// payload.data.userId === "123"
-```
+### 내장 서비스 등록
 
-### 이벤트 브로드캐스트
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 클라이언트에서 WebSocket으로 DB 연결/쿼리를 수행할 때 | [OrmService](./services/orm-service.md) |
+| 클라이언트 앱(APK/EXE) 자동 업데이트를 제공할 때 | [AutoUpdateService](./services/auto-update-service.md) |
+| 클라이언트에 앱 구조(메뉴/페이지) 정보를 제공할 때 | [AppStructureService](./services/app-structure-service.md) |
 
-```typescript
-import { defineEvent } from "@simplysm/service-common";
+### 전송 계층 (내부 동작 이해)
 
-export const UserUpdatedEvent = defineEvent<{ userId: string }, { name: string }>("UserUpdated");
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| WebSocket 메시지 라우팅/이벤트 브로드캐스트 동작을 이해할 때 | [WebSocketHandler](./transport-socket/websocket-handler.md) |
+| WebSocket 연결 추상화(`ServiceContext.socket`의 타입)를 참조할 때 | [ServiceSocket](./transport-socket/service-socket.md) |
+| HTTP API 요청 처리 동작을 이해할 때 | [handleHttpRequest](./transport-http/handle-http-request.md) |
+| 파일 업로드 처리 동작을 이해할 때 | [handleUpload](./transport-http/handle-upload.md) |
+| 정적 파일 서빙 동작을 이해할 때 | [handleStaticFile](./transport-http/handle-static-file.md) |
 
-const userUpdatedEvt = server.getEvent<typeof UserUpdatedEvent>("UserUpdated");
-await userUpdatedEvt.emit((info) => info.userId === "123", { name: "새 이름" });
-```
+### 프로토콜 및 유틸리티
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 프로토콜 인코딩/디코딩 래퍼(worker 자동 위임)를 이해할 때 | [ServerProtocolWrapper](./protocol/server-protocol-wrapper.md) |
+| `.config.json` 파일을 캐싱/자동 리로드로 읽을 때 | [getConfig](./utils/get-config.md) |
+
+### 레거시
+
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| V1 WebSocket 프로토콜 호환이 필요할 때 (자동 업데이트만 지원) | [handleV1Connection](./legacy/handle-v1-connection.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 브라우저 환경에서 서버에 연결 → `@simplysm/service-client`
 - 서버-클라이언트 공유 타입/프로토콜 정의 → `@simplysm/service-common`
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

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

@@ -0,0 +1,87 @@
+# API Index — @simplysm/service-server
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Main
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServiceServer` | class | [service-server.md](./main/service-server.md) | 서버를 생성하고 시작할 때 |
+| `ServerEventProxy` | interface | [service-server.md](./main/service-server.md#servereventproxy) | `getEvent()`의 반환 타입을 참조할 때 |
+| `createServiceServer` | function | [create-service-server.md](./main/create-service-server.md) | 팩토리 함수로 서버를 생성할 때 |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServiceServerOptions` | interface | [service-server-options.md](./types/service-server-options.md) | 서버 생성 옵션을 구성할 때 |
+
+## Auth
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `AuthTokenPayload` | interface | [auth-token-payload.md](./auth/auth-token-payload.md) | JWT 페이로드 타입을 참조할 때 |
+| `signJwt` | function | [sign-jwt.md](./auth/sign-jwt.md) | JWT 토큰을 서명할 때 |
+| `verifyJwt` | function | [verify-jwt.md](./auth/verify-jwt.md) | JWT 토큰을 검증할 때 |
+| `decodeJwt` | function | [verify-jwt.md](./auth/verify-jwt.md#decodejwt) | 검증 없이 토큰 내용을 확인할 때 |
+
+## Core
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `defineService` | function | [define-service.md](./core/define-service.md) | 서비스를 정의할 때 |
+| `ServiceDefinition` | interface | [define-service.md](./core/define-service.md#servicedefinition) | 서비스 정의 타입을 참조할 때 |
+| `ServiceMethods` | type | [define-service.md](./core/define-service.md#servicemethods) | 클라이언트 측 타입 공유를 위해 메서드 시그니처를 추출할 때 |
+| `auth` | function | [auth.md](./core/auth.md) | 서비스 또는 메서드에 인증을 요구할 때 |
+| `getServiceAuthPermissions` | function | [auth.md](./core/auth.md#getserviceauthpermissions) | `auth()`로 래핑된 함수의 권한 배열을 읽을 때 |
+| `ServiceContext` | interface | [service-context.md](./core/service-context.md) | 서비스 팩토리에서 컨텍스트 타입을 참조할 때 |
+| `createServiceContext` | function | [service-context.md](./core/service-context.md#createservicecontext) | 테스트 등에서 `ServiceContext`를 직접 생성할 때 |
+| `executeServiceMethod` | function | [execute-service-method.md](./core/execute-service-method.md) | 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때 |
+
+## Transport - Socket
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `WebSocketHandler` | interface | [websocket-handler.md](./transport-socket/websocket-handler.md) | WebSocket 메시지 라우팅 동작을 이해할 때 |
+| `createWebSocketHandler` | function | [websocket-handler.md](./transport-socket/websocket-handler.md#createwebsockethandler) | 커스텀 WebSocket 핸들러를 생성할 때 |
+| `ServiceSocket` | interface | [service-socket.md](./transport-socket/service-socket.md) | WebSocket 연결 추상화를 참조할 때 |
+| `createServiceSocket` | function | [service-socket.md](./transport-socket/service-socket.md#createservicesocket) | 테스트 등에서 `ServiceSocket`을 직접 생성할 때 |
+
+## Transport - HTTP
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `handleHttpRequest` | function | [handle-http-request.md](./transport-http/handle-http-request.md) | HTTP API 요청 처리 동작을 이해할 때 |
+| `handleUpload` | function | [handle-upload.md](./transport-http/handle-upload.md) | 파일 업로드 처리 동작을 이해할 때 |
+| `handleStaticFile` | function | [handle-static-file.md](./transport-http/handle-static-file.md) | 정적 파일 서빙 동작을 이해할 때 |
+
+## Protocol
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `ServerProtocolWrapper` | interface | [server-protocol-wrapper.md](./protocol/server-protocol-wrapper.md) | 프로토콜 인코딩/디코딩 래퍼의 동작을 이해할 때 |
+| `createServerProtocolWrapper` | function | [server-protocol-wrapper.md](./protocol/server-protocol-wrapper.md#createserverprotocolwrapper) | 커스텀 프로토콜 래퍼를 생성할 때 |
+
+## Services
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `OrmService` | const | [orm-service.md](./services/orm-service.md) | DB 연결을 서비스 계층에서 제공할 때 |
+| `OrmServiceType` | type | [orm-service.md](./services/orm-service.md#ormservicetype) | 클라이언트에서 ORM 서비스 타입을 참조할 때 |
+| `AutoUpdateService` | const | [auto-update-service.md](./services/auto-update-service.md) | 클라이언트 앱 자동 업데이트를 제공할 때 |
+| `AutoUpdateServiceType` | type | [auto-update-service.md](./services/auto-update-service.md#autoupdateservicetype) | 클라이언트에서 자동 업데이트 서비스 타입을 참조할 때 |
+| `AppStructureService` | function | [app-structure-service.md](./services/app-structure-service.md) | 앱 구조 정보를 클라이언트에 제공할 때 |
+| `AppStructureServiceType` | type | [app-structure-service.md](./services/app-structure-service.md#appstructureservicetype) | 클라이언트에서 앱 구조 서비스 타입을 참조할 때 |
+
+## Utils
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `getConfig` | function | [get-config.md](./utils/get-config.md) | `.config.json` 파일을 캐싱/자동 리로드로 읽을 때 |
+
+## Legacy
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `handleV1Connection` | function | [handle-v1-connection.md](./legacy/handle-v1-connection.md) | V1 WebSocket 프로토콜 호환이 필요할 때 |

package/claude/references/sd-simplysm-v14/service-server/auth/auth-token-payload.md

@@ -1,4 +1,6 @@
-# AuthTokenPayload
+# `AuthTokenPayload`
+
+> **읽어야 하는 상황**: JWT 페이로드 타입을 참조하거나 `signAuthToken`/`verifyAuthToken`의 페이로드 구조를 확인할 때.
 
 JWT 페이로드 인터페이스. `jose` 라이브러리의 `JWTPayload`를 확장한다.
 

package/claude/references/sd-simplysm-v14/service-server/auth/sign-jwt.md

@@ -1,4 +1,6 @@
-# signJwt
+# `signJwt`
+
+> **읽어야 하는 상황**: 서버 외부에서 직접 JWT 토큰을 서명할 때. 일반적으로는 `server.signAuthToken()`을 사용한다.
 
 HS256 알고리즘과 12시간 유효기간으로 JWT 토큰을 서명한다.
 

package/claude/references/sd-simplysm-v14/service-server/auth/verify-jwt.md

@@ -1,4 +1,6 @@
-# verifyJwt
+# `verifyJwt`
+
+> **읽어야 하는 상황**: 서버 외부에서 직접 JWT 토큰을 검증하거나 디코딩할 때. 일반적으로는 `server.verifyAuthToken()`을 사용한다. 검증 없이 내용만 확인하려면 `decodeJwt`를 사용한다.
 
 JWT 토큰을 검증하고 페이로드를 반환한다. 만료된 토큰은 "토큰이 만료되었습니다." 에러를, 그 외 유효하지 않은 토큰은 "유효하지 않은 토큰입니다." 에러를 던진다.
 

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

@@ -1,4 +1,6 @@
-# auth
+# `auth`
+
+> **읽어야 하는 상황**: 서비스 전체 또는 특정 메서드에 로그인/역할 기반 인증을 적용할 때. 서비스 정의는 [`defineService`](./define-service.md) 참조.
 
 서비스 팩토리 또는 메서드에 인증을 요구하는 래퍼 함수. 래핑된 함수에 `AUTH_PERMISSIONS` 심볼로 권한 배열을 부착한다.
 

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

@@ -1,4 +1,6 @@
-# defineService
+# `defineService`
+
+> **읽어야 하는 상황**: 서버에 등록할 커스텀 서비스를 정의할 때. 인증이 필요하면 [`auth`](./auth.md)와 함께 사용한다.
 
 이름과 팩토리 함수로 서비스를 정의한다. 팩토리가 `auth()`로 래핑되어 있으면 자동으로 `authPermissions`를 추출한다.
 

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

@@ -1,4 +1,6 @@
-# executeServiceMethod
+# `executeServiceMethod`
+
+> **읽어야 하는 상황**: 커스텀 전송 계층에서 서비스 실행 파이프라인을 직접 호출할 때. 일반적인 서버 사용 시에는 `ServiceServer`가 내부적으로 호출하므로 직접 사용할 필요가 없다.
 
 서비스 조회 → 컨텍스트 생성 → 인증 확인 → 메서드 실행 파이프라인을 수행한다.
 

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

@@ -1,4 +1,6 @@
-# ServiceContext
+# `ServiceContext`
+
+> **읽어야 하는 상황**: 서비스 팩토리에서 인증 정보, 클라이언트 경로, 설정 파일 등에 접근할 때. 전송 방식(WebSocket/HTTP)에 무관하게 동일한 인터페이스를 제공한다.
 
 서비스 팩토리 함수에 전달되는 컨텍스트 인터페이스. 전송 방식(WebSocket/HTTP)에 무관하게 동일한 인터페이스를 제공한다.
 

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

@@ -1,4 +1,6 @@
-# handleV1Connection
+# `handleV1Connection`
+
+> **읽어야 하는 상황**: V1 WebSocket 프로토콜과의 호환이 필요할 때. 자동 업데이트(`SdAutoUpdateService.getLastVersion`)만 지원하고, 그 외 모든 요청은 업그레이드 필요 에러를 반환한다.
 
 V1 레거시 WebSocket 프로토콜 호환 레이어. 자동 업데이트(`SdAutoUpdateService.getLastVersion`)만 지원하고, 그 외 모든 요청은 업그레이드 필요 에러를 반환한다.
 

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

@@ -1,4 +1,6 @@
-# createServiceServer
+# `createServiceServer`
+
+> **읽어야 하는 상황**: `new ServiceServer()` 대신 팩토리 함수로 서버 인스턴스를 생성할 때. 서버의 전체 API는 [`ServiceServer`](./service-server.md) 참조.
 
 `ServiceServer` 인스턴스를 생성하는 팩토리 함수.
 

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

@@ -1,4 +1,6 @@
-# ServiceServer
+# `ServiceServer`
+
+> **읽어야 하는 상황**: Fastify 기반 서비스 서버를 생성하고 시작할 때. 팩토리 함수를 선호하면 [`createServiceServer`](./create-service-server.md) 참조.
 
 Fastify를 래핑한 서비스 서버 클래스. WebSocket/HTTP 이중 전송, JWT 인증, 이벤트 브로드캐스트, graceful shutdown을 처리한다. `EventEmitter<{ ready: void; close: void }>`를 확장한다.
 

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

@@ -1,4 +1,6 @@
-# ServerProtocolWrapper
+# `ServerProtocolWrapper`
+
+> **읽어야 하는 상황**: 프로토콜 인코딩/디코딩의 worker 스레드 자동 위임 기준을 이해할 때. `ServiceSocket`이 내부적으로 사용한다.
 
 메시지 인코딩/디코딩 래퍼 인터페이스. 무거운 메시지는 worker 스레드에 자동으로 위임하고, 가벼운 작업은 메인 스레드에서 처리한다.
 

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

@@ -1,4 +1,6 @@
-# AppStructureService
+# `AppStructureService`
+
+> **읽어야 하는 상황**: 클라이언트에 앱의 메뉴/페이지 구조 정보를 정적으로 제공할 때. 동적으로 변하는 구조가 필요하면 별도 서비스를 정의한다.
 
 앱 구조 정보 서비스를 생성하는 팩토리 함수. `defineService`를 래핑하여 `Record<string, AppStructureItem[]>` 맵을 받아 서비스 정의를 반환한다. 인증 불필요.
 

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

@@ -1,4 +1,6 @@
-# AutoUpdateService
+# `AutoUpdateService`
+
+> **읽어야 하는 상황**: 클라이언트 앱(Android APK / Windows EXE)의 자동 업데이트를 서버에서 제공할 때. 웹 클라이언트 업데이트에는 사용하지 않는다.
 
 자동 업데이트 서비스 정의. `defineService("AutoUpdate", (ctx) => ...)`로 정의되어 있다. 인증 불필요.
 

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

@@ -1,4 +1,6 @@
-# OrmService
+# `OrmService`
+
+> **읽어야 하는 상황**: 클라이언트에서 WebSocket을 통해 DB 연결/쿼리를 수행하는 서비스를 등록할 때. HTTP API로 DB 작업이 필요하면 별도 서비스를 정의한다.
 
 ORM 브리지 서비스 정의. WebSocket 전용이며 `auth()`로 래핑되어 로그인이 필수다. `defineService("Orm", auth((ctx) => ...))`로 정의되어 있다.
 

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

@@ -1,4 +1,6 @@
-# handleHttpRequest
+# `handleHttpRequest`
+
+> **읽어야 하는 상황**: HTTP API 요청(`/api/:service/:method`) 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다.
 
 GET/POST `/api/:service/:method` 경로의 HTTP 요청을 처리한다. `x-sd-client-name` 헤더가 필수이며, `Authorization` 헤더가 있으면 JWT 토큰을 검증한다.
 

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

@@ -1,4 +1,6 @@
-# handleStaticFile
+# `handleStaticFile`
+
+> **읽어야 하는 상황**: 정적 파일 서빙 동작(경로 탐색 방지, 숨김 파일 차단, 디렉토리 처리)을 이해할 때. `ServiceServer`가 내부적으로 사용한다.
 
 정적 파일 서빙을 처리한다. 경로 탐색 공격 방지와 숨김 파일 접근 차단이 포함되어 있다.
 

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

@@ -1,4 +1,6 @@
-# handleUpload
+# `handleUpload`
+
+> **읽어야 하는 상황**: 파일 업로드(`/upload`) 처리 동작을 이해할 때. 인증 필수. `ServiceServer`가 내부적으로 사용한다.
 
 `/upload` 경로의 multipart 파일 업로드를 처리한다. 인증 필수 (Authorization 헤더 필수).
 

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

@@ -1,4 +1,6 @@
-# ServiceSocket
+# `ServiceSocket`
+
+> **읽어야 하는 상황**: WebSocket 연결 추상화를 참조할 때. `ServiceContext.socket`의 타입이다. 소켓별 상태 관리(이벤트 리스너, 인증 토큰)를 이해할 때.
 
 프로토콜 인코딩/디코딩, ping/pong 연결 유지, 이벤트 리스너 추적이 포함된 단일 WebSocket 연결 인터페이스.
 

package/claude/references/sd-simplysm-v14/service-server/transport-socket/websocket-handler.md

@@ -1,4 +1,6 @@
-# WebSocketHandler
+# `WebSocketHandler`
+
+> **읽어야 하는 상황**: WebSocket 메시지 라우팅, 이벤트 브로드캐스트, 인증 메시지 처리 동작을 이해할 때. `ServiceServer`가 내부적으로 사용한다.
 
 다중 WebSocket 연결을 관리하고, 메시지를 서비스로 라우팅하며, 이벤트 브로드캐스팅을 처리하는 인터페이스.
 

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

@@ -1,4 +1,6 @@
-# ServiceServerOptions
+# `ServiceServerOptions`
+
+> **읽어야 하는 상황**: 서버 생성 옵션(rootPath, port, ssl, auth, services)을 구성할 때. 특히 `auth` 필드의 세 가지 상태(`{ jwtSecret }`, `false`, `undefined`)를 이해해야 할 때.
 
 서버 생성 시 전달하는 옵션 인터페이스.
 

package/claude/references/sd-simplysm-v14/service-server/utils/get-config.md

@@ -1,4 +1,6 @@
-# getConfig
+# `getConfig`
+
+> **읽어야 하는 상황**: `.config.json` 파일을 캐싱/자동 리로드로 직접 읽을 때. 일반적으로는 `ServiceContext.getConfig()`를 사용한다 -- 루트/클라이언트별 설정 병합을 자동으로 처리한다.
 
 `.config.json` 파일을 읽고 캐싱한다. 파일 변경 시 자동 리로드되며, 캐시는 1시간 후 만료된다.
 

package/claude/references/sd-simplysm-v14/storage/README.md

@@ -8,92 +8,29 @@
 npm install @simplysm/storage
 ```
 
-## 하려는 작업 → 먼저 읽을 파일
+## 하려는 작업 → 읽을 파일
 
-| 작업 | 먼저 읽을 파일 |
-|------|----------------|
-| FTP/SFTP 서버에 파일 업로드/다운로드 | [`StorageFactory`](./factory/storage-factory.md) |
-| 프로토콜별 구현 차이 확인 (FTP/FTPS) | [`FtpStorageClient`](./clients/ftp-storage-client.md) |
-| SFTP 인증 방식 (패스워드/SSH 키) 확인 | [`SftpStorageClient`](./clients/sftp-storage-client.md) |
-| 스토리지 작업을 추상화하는 함수 작성 | [`StorageClient`](./types/storage-client.md) |
-| 연결 설정 타입 확인 | [`StorageConnConfig`](./types/storage-conn-config.md) |
+### 파일 전송
 
-## API Overview
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| FTP/FTPS/SFTP 서버에 파일 업로드·다운로드·목록 조회 | [`StorageFactory`](./factory/storage-factory.md) |
+| FTP/FTPS 연결을 직접 생명주기 관리 (장시간 연결 유지 등) | [`FtpStorageClient`](./clients/ftp-storage-client.md) |
+| SFTP 연결을 직접 생명주기 관리하거나 SSH 키 인증 방식 확인 | [`SftpStorageClient`](./clients/sftp-storage-client.md) |
 
-### Factory
+### 타입 활용
 
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`StorageFactory`](./factory/storage-factory.md) | class | 스토리지 서버에 연결하여 파일 작업을 수행할 때 (기본 진입점) |
-
-### Clients
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`FtpStorageClient`](./clients/ftp-storage-client.md) | class | FTP/FTPS 클라이언트를 직접 생명주기 관리해야 할 때 |
-| [`SftpStorageClient`](./clients/sftp-storage-client.md) | class | SFTP 클라이언트를 직접 생명주기 관리해야 할 때 |
-
-### Types
-
-| Entry | Kind | 언제 쓰나 |
-|-------|------|-----------|
-| [`StorageClient`](./types/storage-client.md) | interface | 스토리지 작업을 프로토콜 무관하게 추상화하는 함수 시그니처에 사용할 때 |
-| [`StorageConnConfig`](./types/storage-conn-config.md) | interface | 연결 설정 객체를 타입으로 지정할 때 |
-| [`FileInfo`](./types/file-info.md) | interface | `list()` 반환값을 처리할 때 |
-
-## Usage Examples
-
-### SFTP로 파일 업로드 (StorageFactory 사용 권장)
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user", password: "pass" },
-  async (storage) => {
-    await storage.mkdir("/remote/dir");
-    await storage.put("/local/file.txt", "/remote/dir/file.txt");
-  },
-);
-```
-
-콜백이 완료되거나 예외가 발생하면 자동으로 연결이 종료된다.
-
-### FTP로 파일 목록 조회 및 다운로드
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-const files = await StorageFactory.connect(
-  "ftp",
-  { host: "ftp.example.com", port: 21, user: "user", password: "pass" },
-  async (storage) => {
-    const list = await storage.list("/data");
-    for (const file of list.filter((f) => f.isFile)) {
-      const content = await storage.readFile(`/data/${file.name}`);
-      // content는 Bytes (Uint8Array)
-    }
-    return list;
-  },
-);
-```
-
-### SSH 키 인증으로 SFTP 연결 (비밀번호 생략)
-
-```typescript
-import { StorageFactory } from "@simplysm/storage";
-
-await StorageFactory.connect(
-  "sftp",
-  { host: "sftp.example.com", user: "user" }, // password 생략 → SSH agent/키 파일 인증
-  async (storage) => {
-    const list = await storage.list("/home/user");
-  },
-);
-```
+| 하려는 작업 | 읽을 파일 |
+|-------------|-----------|
+| 프로토콜 무관하게 스토리지 작업을 추상화하는 함수 시그니처 작성 | [`StorageClient`](./types/storage-client.md) |
+| 연결 설정 객체의 타입 확인 | [`StorageConnConfig`](./types/storage-conn-config.md) |
+| `list()` 반환값의 구조 확인 | [`FileInfo`](./types/file-info.md) |
 
 ## 이 패키지를 쓰지 말아야 할 때
 
 - 브라우저 환경에서 파일 업로드/다운로드 → 이 패키지는 Node.js 전용이다
 - HTTP/S3 등 FTP/SFTP 이외의 프로토콜 → 이 패키지는 FTP/FTPS/SFTP만 지원한다
+
+---
+
+> API 이름으로 검색: [_api-index.md](./_api-index.md)

package/claude/references/sd-simplysm-v14/storage/_api-index.md

@@ -0,0 +1,26 @@
+# API Index — @simplysm/storage
+
+> API 이름을 알고 있을 때 해당 문서를 찾는 인덱스.
+> 작업 기반으로 찾으려면 [README.md](./README.md) 참조.
+
+## Factory
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `StorageFactory` | class | [storage-factory.md](./factory/storage-factory.md) | 스토리지 서버에 연결하여 파일 작업을 수행할 때 (기본 진입점) |
+
+## Clients
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `FtpStorageClient` | class | [ftp-storage-client.md](./clients/ftp-storage-client.md) | FTP/FTPS 클라이언트를 직접 생명주기 관리해야 할 때 |
+| `SftpStorageClient` | class | [sftp-storage-client.md](./clients/sftp-storage-client.md) | SFTP 클라이언트를 직접 생명주기 관리해야 할 때 |
+
+## Types
+
+| API | Kind | 문서 | 언제 쓰나 |
+|-----|------|------|-----------|
+| `StorageClient` | interface | [storage-client.md](./types/storage-client.md) | 스토리지 작업을 프로토콜 무관하게 추상화하는 함수 시그니처에 사용할 때 |
+| `StorageConnConfig` | interface | [storage-conn-config.md](./types/storage-conn-config.md) | 연결 설정 객체를 타입으로 지정할 때 |
+| `FileInfo` | interface | [file-info.md](./types/file-info.md) | `list()` 반환값을 처리할 때 |
+| `StorageProtocol` | type | [storage-factory.md](./factory/storage-factory.md#storageprotocol) | `StorageFactory.connect()`의 `type` 파라미터 타입을 확인할 때 |

package/claude/references/sd-simplysm-v14/storage/clients/ftp-storage-client.md

@@ -1,6 +1,8 @@
 # `FtpStorageClient`
 
-FTP/FTPS 프로토콜을 사용하는 스토리지 클라이언트. `basic-ftp` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
+> **읽어야 하는 상황**: FTP/FTPS 연결을 직접 생명주기 관리해야 할 때 (장시간 연결 유지 등). 단일 작업 단위로 자동 관리하려면 [`StorageFactory`](../factory/storage-factory.md) 사용.
+
+`basic-ftp` 라이브러리 기반. [`StorageClient`](../types/storage-client.md) 인터페이스를 구현한다.
 
 ## When to use