@simplysm/sd-claude 14.0.75 → 14.0.77

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

@@ -1,41 +1,82 @@
-# @simplysm/service-server — internals
+# @simplysm/service-server — 내부 전송 계층
 
-`ServiceServer.listen()` 이 자동으로 endpoint 에 연결하는 핸들러·소켓·프로토콜·레거시 유틸의 표면. 표준 부트스트랩에서는 호출할 필요가 없으며, 자체 Fastify 인스턴스에 라우트를 직접 부착하거나 비표준 전송을 만들 때만 직접 import 한다.
+`ServiceServer.listen()` 이 자동 결선하므로 일반 사용에선 불필요. 커스텀 Fastify 라우트·테스트·비표준 전송 시 참고.
 
-## HTTP 핸들러
+## HTTP
 
 ### `handleHttpRequest(req, reply, jwtSecret, runMethod)`
 
-`/api/:service/:method` 라우트 핸들러. `x-sd-client-name` 헤더 필수. `Authorization: Bearer <token>` 있으면 `verifyJwt` 검증 (실패 401). GET 은 `?json=<배열>`, POST 는 본문이 배열이어야 함. 결과를 `runMethod({serviceName, methodName, params, http})` 로 위임.
+`/api/:service/:method` 라우트 핸들러.
+
+- `x-sd-client-name` 헤더 필수(없으면 throw).
+- `Authorization: Bearer <jwt>` 있고 `jwtSecret` 도 있으면 `verifyJwt`. 토큰만 있고 secret 없으면 throw. 검증 실패 시 401 응답.
+- GET: `?json=<JSON encoded array>` → `json.parse`.
+- POST: body 가 배열이어야 함(아니면 400).
+- 그 외 메서드: 405.
+- `runMethod({ serviceName, methodName, params, http: { clientName, authTokenPayload } })` 호출 후 결과를 `reply.send`.
 
 ### `handleUpload(req, reply, rootPath, jwtSecret)`
 
-multipart 업로드. `Authorization` 필수 (없거나 검증 실패 시 401). 각 파일을 `<rootPath>/www/uploads/<uuid><ext>` 로 저장 후 `ServiceUploadResult[]` 반환. 중간 에러 시 이미 저장된 모든 파일 삭제 후 500.
+multipart 업로드. `Authorization` 헤더 필수(없으면 401, `jwtSecret` 미구성 시 401). 각 파일을 `<rootPath>/www/uploads/<uuid><ext>` 로 저장. 응답 `ServiceUploadResult[] = { path, filename, size }[]` (`path` = `uploads/<saveName>`). 도중 truncated 또는 에러 발생 시 진행 중 + 이미 저장된 모든 파일 삭제 후 500.
 
 ### `handleStaticFile(req, reply, rootPath, urlPath)`
 
-`<rootPath>/www/<urlPath>` 정적 서빙. 경로 탐색 가드(`pathx.isChildPath`), 디렉토리 슬래시 리다이렉트 후 `index.html` 폴백, 숨김 파일(`.` 시작) 403, ENOENT 404, 기타 500.
+`<rootPath>/www/<urlPath>` 정적 서빙.
+
+- 경로 탐색 차단: `pathx.isChildPath(targetFilePath, allowedRootPath)` 가드.
+- 디렉터리 + URL 미 trailing slash → `pathname + "/"` 리다이렉트. trailing slash 있으면 `<dir>/index.html` 사용.
+- 숨김 파일(basename 이 `.` 시작) → 403.
+- ENOENT 404, 기타 500. 에러는 HTML 응답.
+
+## WebSocket
+
+### `createWebSocketHandler(runMethod, jwtSecret): WebSocketHandler`
+
+여러 WS 연결 풀 관리. 처리 메시지:
+
+- `<service>.<method>` (body 가 배열) → RPC. `runMethod` 위임.
+- `evt:add { key, name, info }` — 이벤트 리스너 등록.
+- `evt:remove { key }` — 제거.
+- `evt:gets { name }` — 모든 소켓의 해당 이벤트 리스너 정보 조회.
+- `evt:emit { keys, data }` — 매칭 키 가진 소켓에게 `evt:on` 푸시.
+- `auth <token>` — JWT 검증 후 `socket.authTokenPayload` 설정.
+
+에러 코드: `BAD_MESSAGE`(알 수 없는 요청), `INTERNAL_ERROR`. `env("DEV")` truthy 시 `stack` 포함.
+
+`addSocket(socket, clientId, clientName, connReq)` 동일 clientId 이전 연결 자동 종료 후 교체. `emit(name, infoSelector, data)` 는 `ServiceServer.emitEvent` 의 백엔드.
+
+### `createServiceSocket(socket, clientId, clientName, connReq): ServiceSocket`
+
+단일 WS 관리.
+
+- 5초 ping/pong (`socket.ping()` → 응답 없으면 `terminate()`).
+- 1바이트 `0x01`(ping) 수신 → `0x02`(pong) 송신.
+- 메시지는 `createServerProtocolWrapper()` 통과. 진행률(`type === "progress"`) 디코드 결과는 자동으로 `progress` 메시지 회신.
 
-## WebSocket / 소켓
+표면: `connectedAtDateTime: DateTime`, `clientName`, `connReq`, `authTokenPayload`(get/set), `close()`, `send(uuid, msg)`(전송 바이트), `addListener(key, eventName, info)`, `removeListener(key)`, `getEventListeners(eventName)`, `filterEventTargetKeys(targetKeys)`, `on("error"|"close"|"message", handler)`.
 
-### `createWebSocketHandler(runMethod, jwtSecret) → WebSocketHandler`
+## 프로토콜 래퍼
 
-여러 WS 연결 풀 관리. `addSocket(socket, clientId, clientName, req)` 으로 등록(기존 동일 `clientId` 강제 교체). 메시지를 디코드해 `runMethod` 로 RPC, `evt:add/remove/gets/emit`, `auth` 메시지를 처리. `emit(name, infoSelector, data)` 로 매칭 클라이언트 푸시(`ServiceServer.emitEvent` 의 백엔드).
+### `createServerProtocolWrapper(): ServerProtocolWrapper`
 
-### `createServiceSocket(socket, clientId, clientName, connReq) → ServiceSocket`
+`@simplysm/service-common` 의 `createServiceProtocol()` 기반. 무거운 케이스만 워커 스레드로 위임:
 
-단일 WS 래퍼. 5초 ping/pong 헬스체크, `createServerProtocolWrapper` 로 메시지 인코딩, 이벤트 리스너 키 보관, `on("error"|"close"|"message")`.
+- encode: body 가 `Uint8Array` 이거나 `Uint8Array` 요소를 하나라도 가진 배열 → 워커.
+- decode: 입력 바이트 > 30KB → 워커.
 
-## 프로토콜
+워커는 모듈 로드 시 1회 생성 lazy singleton(`maxOldGenerationSizeMb: 4096`). 워커 모듈: `workers/service-protocol.worker.ts`.
 
-### `createServerProtocolWrapper() → ServerProtocolWrapper`
+표면: `encode(uuid, message)`, `decode(bytes)`, `dispose()`(메인 스레드 프로토콜만 정리, 워커는 공유).
 
-`@simplysm/service-common` 의 프로토콜을 worker(`service-protocol.worker`) 에 위임할지 메인 스레드에서 처리할지 자동 분기. encode 는 body 에 `Uint8Array` 가 있으면 worker, decode 는 30KB 초과 시 worker. `dispose()` 로 메인 스레드 프로토콜 정리.
+## 설정 캐시
 
-## V1 레거시
+### `getConfig<T>(filePath: string): Promise<T | undefined>`
 
-### `handleV1Connection(socket, optionsOrMethods, clientNameSetter?)`
+JSON 설정 파일 로더.
 
-`ver` 쿼리가 `"2"` 가 아닌 클라이언트를 처리. JSON 텍스트 프로토콜로 `{ uuid, command, params, clientName }` 수신. 사용자 `handlers` 가 `handled: true` 를 반환하면 그 결과, 아니면 `SdAutoUpdateService.getLastVersion` fallback, 그것도 아니면 `UPGRADE_REQUIRED` 에러 반환.
+- `LazyGcMap` 캐시: 만료 1시간, GC 10분 간격. 캐시 히트 시 만료 시간 자동 갱신.
+- 파일 없으면 undefined.
+- `FsWatcher` 로 변경 감시 → 100ms 디바운스 후 리로드. 삭제 감지 시 캐시·워처 정리.
+- 만료 시 워처도 함께 해제.
 
-타입: `V1Request`, `V1Response`, `V1AutoUpdateMethods`, `V1RequestHandler`, `V1RequestHandlerContext`, `V1RequestHandlerResult`, `V1ConnectionOptions`. `ServiceServerOptions.legacyV1Handlers` 에 `V1RequestHandler[]` 를 넘기면 `ServiceServer` 가 자동 사용.
+`ServiceContext.getConfig(section)` 이 root/client `.config.json` 두 경로를 이 함수로 읽어 `obj.merge`. 그 외 경로의 설정 파일을 읽을 때만 직접 호출.

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

@@ -1,66 +1,57 @@
-# @simplysm/service-server — server
+# @simplysm/service-server — 서버
 
-서버 인스턴스 부트스트랩 표면. `ServiceServer` 가 Fastify · WebSocket · JWT · 정적/업로드/API 라우트를 일괄 등록하고 SIGINT/SIGTERM 정상 종료까지 처리한다.
+## `createServiceServer<TAuthInfo>(options): ServiceServer<TAuthInfo>`
 
-## `ServiceServerOptions`
-
-```ts
-interface ServiceServerOptions {
-  rootPath: string;                                  // 정적/업로드/설정 루트 (www, .config.json 기준)
-  port: number;
-  ssl?: { pfxBytes: Uint8Array; passphrase: string };
-  auth?: { jwtSecret: string } | false;              // undefined: auth 미설정(=auth 서비스 등록 시 에러)
-                                                     // false: 의도적 비활성화 (검사 스킵)
-  services: ServiceDefinition[];                     // defineService 결과
-  legacyV1Handlers?: V1RequestHandler[];             // V1 클라이언트 fallback
-}
-```
+`new ServiceServer(options)` 단순 팩토리. `TAuthInfo` 는 JWT payload 의 `data` 필드 타입.
 
-## `createServiceServer<TAuthInfo>(opts) → ServiceServer<TAuthInfo>`
+## `ServiceServerOptions`
 
-`new ServiceServer(opts)` 단순 래퍼. `TAuthInfo` 는 JWT `data` 페이로드 타입.
+- `rootPath: string` — 정적/업로드/설정 루트. 정적은 `<rootPath>/www/`, 업로드 저장은 `<rootPath>/www/uploads/`, 설정은 `<rootPath>/.config.json` 및 `<rootPath>/www/<clientName>/.config.json`.
+- `port: number` — listen 포트. host 는 항상 `0.0.0.0`.
+- `ssl?: { pfxBytes: Uint8Array; passphrase: string }` — 지정 시 HTTPS. 내부에서 `Buffer.from(pfxBytes)` 변환. 미지정 시 helmet 의 `upgrade-insecure-requests` 제거, `hsts`/`crossOriginOpenerPolicy` 비활성.
+- `auth?: { jwtSecret: string } | false`
+  - `undefined`(미지정): auth 미구성. 인증 요구 서비스가 하나라도 있으면 `listen()` 시 throw.
+  - `false`: 의도적 비활성화. `auth()` 래핑된 서비스/메서드도 인증 스킵.
+  - 객체: jwt 시크릿 등록.
+- `services: ServiceDefinition[]` — `defineService()` 결과 배열.
+- `legacyV1Handlers?: V1RequestHandler[]` — ver≠"2" 로 접속한 클라이언트의 커스텀 핸들러. 이 배열도 비고 `AutoUpdate` 서비스도 services 에 없으면 V1 연결을 1008 로 거부.
 
 ## `ServiceServer<TAuthInfo>`
 
-```ts
-class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{ ready: void; close: void }> {
-  readonly fastify: FastifyInstance;
-  readonly options: ServiceServerOptions;
-  isOpen: boolean;
+`EventEmitter<{ ready: void; close: void }>` 상속.
 
-  listen(): Promise<void>;                           // 플러그인 등록 + 0.0.0.0 listen + SIGINT/SIGTERM 훅
-  close(): Promise<void>;                            // 모든 WS close + fastify.close
-  signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>;  // HS256, 12h
-  verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>;
-  getEvent<TEventDef>(eventName): ServerEventProxy<TEventDef>;
-  emitEvent<TEventDef>(name, infoSelector, data): Promise<void>;
-}
-```
+- `readonly options: ServiceServerOptions`
+- `readonly fastify: FastifyInstance` — 생성자에서 즉시 생성, 플러그인은 `listen()` 시 등록.
+- `isOpen: boolean`
+- `listen(): Promise<void>` — fastify 플러그인(`@fastify/websocket`, `@fastify/helmet`, `@fastify/multipart`, `@fastify/static`, `@fastify/cors`) 등록, JSON 파서/직렬화기를 `@simplysm/core-common` 의 `json` 으로 교체(Date/BigInt/Uint8Array 보존), 라우트 바인딩, `0.0.0.0:port` listen, SIGINT/SIGTERM 핸들러 등록(10초 후 `process.exit(1)` 강제), `ready` 이벤트 발생.
+- `close(): Promise<void>` — 모든 WebSocket 종료 → `fastify.close()` → `close` 이벤트.
+- `getEvent<TEventDef>(eventName): ServerEventProxy<TEventDef>` — `{ emit(infoSelector, data): Promise<void> }` 핸들 반환.
+- `emitEvent<TEventDef>(eventName, infoSelector, data): Promise<void>` — 클라이언트가 `evt:add` 로 등록한 리스너 중 `infoSelector(info) === true` 인 키에만 푸시.
+- `signAuthToken(payload: AuthTokenPayload<TAuthInfo>): Promise<string>` — HS256, `exp` 12h 고정. `jwtSecret` 미구성 시 throw.
+- `verifyAuthToken(token: string): Promise<AuthTokenPayload<TAuthInfo>>` — 만료/위조 시 throw.
 
-`listen()` 동작 — 한 번 호출로 모두 등록: helmet/cors/multipart/websocket/@fastify/static, `POST /api/:service/:method` (HTTP RPC), `ALL /upload` (multipart 업로드), `GET /` 및 `GET /ws` (WebSocket: `?ver=2&clientId=&clientName=` 필요. ver 누락 시 V1 레거시 분기), 와일드카드 `/*` (`<rootPath>/www` 정적 파일).
+`TEventDef` 는 `@simplysm/service-common` 의 `ServiceEventDef`(`{ $info; $data }` 형태). `infoSelector` 는 클라이언트가 listener 등록 시 보낸 `info` 객체를 받아 boolean 반환.
 
-`auth == null` 인데 `services` 중 하나라도 `authPermissions != null` 이면 `listen()` 에서 즉시 throw.
+## 자동 등록되는 라우트
 
-이벤트 브로드캐스트 — 서버는 클라이언트가 `evt:add` 로 등록한 리스너만 안다. `getEvent(name).emit(infoSelector, data)` 로 매칭된 리스너에게만 푸시:
+- `ALL /api/:service/:method` — RPC. `x-sd-client-name` 헤더 필수, `Authorization: Bearer <jwt>` 옵션. GET 은 `?json=<JSON encoded array>`, POST 는 body 가 params 배열. 그 외 HTTP 메서드 405.
+- `ALL /upload` — multipart 업로드. 인증 헤더 필수. 응답 `ServiceUploadResult[]`.
+- `GET /`, `GET /ws` — WebSocket. 쿼리 `ver=2&clientId=<id>&clientName=<name>` (clientId/clientName 누락 시 1008). ver≠"2" → V1 레거시.
+- `* /*` — 정적 서빙(`/api/...`·`/upload`·`/`·`/ws` 외).
 
-```ts
-server.getEvent<{ $info: { tenantId: string }; $data: { id: string } }>("orderCreated")
-  .emit((info) => info.tenantId === "T1", { id: "O-100" });
-```
-
-## `ServerEventProxy<TEventDef>`
-
-`getEvent()` 가 반환하는 핸들. `emit(infoSelector, data)` 만 노출.
-
-## 최소 예제
+## 예
 
 ```ts
-const server = createServiceServer<MyAuth>({
+const server = createServiceServer<{ userId: string }>({
   rootPath: process.cwd(),
   port: 50080,
-  auth: { jwtSecret: env("JWT_SECRET")! },
-  services: [OrmService, AutoUpdateService, MyService],
+  auth: { jwtSecret: process.env.JWT_SECRET! },
+  services: [UserService, OrmService],
 });
 server.on("ready", () => console.log("up"));
 await server.listen();
+
+const token = await server.signAuthToken({ roles: ["admin"], data: { userId: "u1" } });
+await server.getEvent<{ $info: { shopId: number }; $data: { id: number } }>("order-created")
+  .emit(info => info.shopId === 1, { id: 99 });
 ```

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

@@ -528,7 +528,9 @@ async onSubmit(): Promise<void> {
 - 단, **숫자 셀은 `tx-right` 기본 적용** (수량·금액·단가·합계 등 숫자값 컬럼).
 - `[cell]="items()"` 는 타입 추론용 더미 — 실제 행 데이터는 `<sd-sheet>` 의 `[items]` 가 들고 있다.
 - 셀 컨텍스트: `let-item="item"` / `let-index="index"` / `let-depth="depth"` / `let-edit="edit"`.
-- 셀 안 div 에 배경색 클래스(`bg-theme-*-lightest` 등)를 토글할 때는 빈 값 자리에 `&nbsp;` 등을 채워 div 가 셀 높이를 유지하게 한다. (table cell 자식 div 가 콘텐츠 없을 때 높이 0 → bg 가 셀에 차지 않음.)
+- 셀 안 div 에 배경색 클래스(`bg-theme-*-lightest` 등)를 토글할 때는 빈 값 자리에 `&nbsp;`를 채워 div 가 셀 높이를 유지하게 한다. (table cell 자식 div 가 콘텐츠 없을 때 높이 0 → bg 가 셀에 차지 않음.)
+  - 좋은 예: `{{ item.surveyLocationCode ?? "&nbsp" }}`
+  - 나쁜 예: `{{ item.surveyLocationCode }}`, `{{ item.surveyLocationCode ?? " " }}`, `{{ item.surveyLocationCode ?? " " }}`
 
 **list 안에서**: `<sd-crud-list>` 의 직속 자식으로 `<sd-sheet-column>` 을 두면 내부 시트로 자동 투영된다.
 

package/claude/references/sd-simplysm14/manuals/logging.md

@@ -4,16 +4,16 @@
 
 ## 원칙
 
-- 모든 로그는 `consola.withTag(<tag>)` 인스턴스로 출력. `console.*` 직접 호출 금지.
+- 모든 로그는 `createLogger(tag)` (`@simplysm/core-common`) 로 생성한 인스턴스로 출력. `console.*` 직접 호출 금지.
 - ESLint `no-console` 규칙은 의도된 게이트 — `eslint-disable`/`eslint-disable-next-line no-console` 우회 금지.
 - 메시지에 `[패키지]` 같은 수동 prefix 금지. tag 가 그 역할.
 
 ## 권장 패턴
 
 ```ts
-import consola from "consola";
+import { createLogger } from "@simplysm/core-common";
 
-const logger = consola.withTag("capacitor:auto-update");
+const logger = createLogger("capacitor:auto-update");
 
 // ...
 logger.info("최신 버전 확인 중");
@@ -40,19 +40,20 @@ const logger = {
 console.error("[X] 실패:", err);
 ```
 
-→ 모두 `consola.withTag("x")` 1줄로 대체.
+→ 모두 `createLogger("x")` 1줄로 대체.
 
 ## 환경별 셋업
 
 - **Node 진입점(서버·CLI)**: 진입점에서 `setupConsola()` 1회. 자세히 [apis/core-node/consola.md](../apis/core-node/consola.md).
 - **Browser·Capacitor 진입점**: `setupConsola` 호출 X (Node 전용). consola 기본 reporter 가 브라우저 콘솔로 출력. tag/level/통일된 호출면 충족.
 
-## 모듈-레벨 logger 주의 (Node 진입점)
+## 모듈-레벨 logger 주의
 
-Node 진입점에서 `setupConsola` 호출 **전** 에 모듈 레벨에서 `consola.withTag()` 를 호출하면 호출 시점의 옵션(level/reporters)이 스냅샷으로 고정되어 이후 setupConsola 변경이 반영되지 않는다.
+모듈 레벨에서 `consola.withTag()` 를 직접 호출하면 호출 시점의 options(level/reporters)가 스냅샷으로 고정되어, 이후 `setupConsola()` 가 reporters 를 갱신해도 child instance 에 반영되지 않는다.
 
-- 해결: `@simplysm/sd-cli` 의 `createLazyLogger(tag)` (`src/runtime/lazy-logger.ts`) 처럼 첫 접근 시점까지 `withTag` 생성을 지연.
-- 브라우저·Capacitor 는 setupConsola 가 없어 이 문제 없음 — 그냥 모듈 레벨 `consola.withTag()` OK.
+- **해결**: `createLogger(tag)` 사용 (`@simplysm/core-common`, 내부 구현은 lazy Proxy — 첫 메서드 접근 시점까지 `withTag` 생성을 지연).
+- 모든 환경(Node·브라우저·Capacitor)에서 위치(모듈 레벨·함수 내부·class field)에 관계없이 `createLogger` 로 통일.
+- `consola.withTag()` 직접 호출 금지.
 
 ## 예외 — `eslint-disable no-console` 가 정당화되는 자리