@simplysm/sd-claude 14.0.65 → 14.0.68

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

@@ -0,0 +1,71 @@
+# @simplysm/service-server — define-service
+
+서비스 정의 + 인증 래퍼 + 컨텍스트. `ServiceServerOptions.services` 에 들어갈 단위를 만든다.
+
+## `defineService(name, factory) → ServiceDefinition<TMethods>`
+
+```ts
+defineService<TMethods extends Record<string, (...args: any[]) => any>>(
+  name: string | string[],          // 다중 이름 = alias (예: ["Orm", "SdOrmService"])
+  factory: (ctx: ServiceContext) => TMethods,
+): ServiceDefinition<TMethods>;
+```
+
+`factory` 는 호출마다 실행돼 메서드 객체를 생성한다 (요청별 컨텍스트 캡처). `factory` 가 `auth(...)` 로 감싸져 있으면 서비스 수준 인증으로 승격된다.
+
+## `auth(...)` — 인증 래퍼
+
+```ts
+auth(fn)                           // 로그인 필요
+auth(["admin", "owner"], fn)       // 해당 역할 중 하나 필요 (OR)
+```
+
+- 서비스 수준: `defineService("X", auth((ctx) => ({ ... })))`
+- 메서드 수준: 팩토리 안에서 메서드를 `auth(["admin"], () => result)` 로 감싼다. 메서드 권한이 있으면 서비스 권한을 **덮어쓴다**.
+- `auth: false` 옵션 시 검증 스킵, `auth: undefined` 인데 auth 필요 서비스 등록 시 `listen()` throw, auth 설정됐는데 토큰 없거나 권한 부족 시 메서드 호출에서 throw (`로그인이 필요합니다.` / `권한이 부족합니다.`).
+
+## `ServiceContext<TAuthInfo>`
+
+서비스 메서드가 받는 요청별 컨텍스트.
+
+```ts
+interface ServiceContext<TAuthInfo = unknown> {
+  server: ServiceServer<TAuthInfo>;
+  socket?: ServiceSocket;                            // WS 경로일 때만
+  http?: { clientName: string; authTokenPayload?: AuthTokenPayload<TAuthInfo> };
+  legacy?: { clientName?: string };                  // V1 레거시 경로
+
+  get authInfo(): TAuthInfo | undefined;             // payload.data
+  get clientName(): string | undefined;              // socket → http → legacy 순. 위험문자(.. / \) throw
+  get clientPath(): string | undefined;              // <rootPath>/www/<clientName>
+  getConfig<T>(section: string): Promise<T>;         // root + clientPath 의 .config.json merge, 누락 시 throw
+}
+```
+
+## `ServiceMethods<TDefinition>`
+
+클라이언트에서 메서드 시그니처만 공유하기 위한 추출 타입.
+
+```ts
+export const UserService = defineService("User", (ctx) => ({ ... }));
+export type UserServiceType = ServiceMethods<typeof UserService>;
+// 클라이언트: client.getService<UserServiceType>("User")
+```
+
+## 보조
+
+- `createServiceContext(server, socket?, http?, legacy?)` — 컨텍스트 직조 (커스텀 라우트용).
+- `getServiceAuthPermissions(fn)` — `auth()` 가 함수에 심볼로 심어둔 권한 배열을 읽는다 (내부 executor 가 사용).
+
+## 예제
+
+```ts
+const HealthService = defineService("Health", () => ({
+  check: () => ({ status: "ok" }),
+}));
+
+const UserService = defineService("User", auth((ctx) => ({
+  me: () => ctx.authInfo,
+  adminOnly: auth(["admin"], () => "ok"),
+})));
+```

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

@@ -0,0 +1,41 @@
+# @simplysm/service-server — internals
+
+`ServiceServer.listen()` 이 자동으로 endpoint 에 연결하는 핸들러·소켓·프로토콜·레거시 유틸의 표면. 표준 부트스트랩에서는 호출할 필요가 없으며, 자체 Fastify 인스턴스에 라우트를 직접 부착하거나 비표준 전송을 만들 때만 직접 import 한다.
+
+## 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})` 로 위임.
+
+### `handleUpload(req, reply, rootPath, jwtSecret)`
+
+multipart 업로드. `Authorization` 필수 (없거나 검증 실패 시 401). 각 파일을 `<rootPath>/www/uploads/<uuid><ext>` 로 저장 후 `ServiceUploadResult[]` 반환. 중간 에러 시 이미 저장된 모든 파일 삭제 후 500.
+
+### `handleStaticFile(req, reply, rootPath, urlPath)`
+
+`<rootPath>/www/<urlPath>` 정적 서빙. 경로 탐색 가드(`pathx.isChildPath`), 디렉토리 슬래시 리다이렉트 후 `index.html` 폴백, 숨김 파일(`.` 시작) 403, ENOENT 404, 기타 500.
+
+## WebSocket / 소켓
+
+### `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` 의 백엔드).
+
+### `createServiceSocket(socket, clientId, clientName, connReq) → ServiceSocket`
+
+단일 WS 래퍼. 5초 ping/pong 헬스체크, `createServerProtocolWrapper` 로 메시지 인코딩, 이벤트 리스너 키 보관, `on("error"|"close"|"message")`.
+
+## 프로토콜
+
+### `createServerProtocolWrapper() → ServerProtocolWrapper`
+
+`@simplysm/service-common` 의 프로토콜을 worker(`service-protocol.worker`) 에 위임할지 메인 스레드에서 처리할지 자동 분기. encode 는 body 에 `Uint8Array` 가 있으면 worker, decode 는 30KB 초과 시 worker. `dispose()` 로 메인 스레드 프로토콜 정리.
+
+## V1 레거시
+
+### `handleV1Connection(socket, optionsOrMethods, clientNameSetter?)`
+
+`ver` 쿼리가 `"2"` 가 아닌 클라이언트를 처리. JSON 텍스트 프로토콜로 `{ uuid, command, params, clientName }` 수신. 사용자 `handlers` 가 `handled: true` 를 반환하면 그 결과, 아니면 `SdAutoUpdateService.getLastVersion` fallback, 그것도 아니면 `UPGRADE_REQUIRED` 에러 반환.
+
+타입: `V1Request`, `V1Response`, `V1AutoUpdateMethods`, `V1RequestHandler`, `V1RequestHandlerContext`, `V1RequestHandlerResult`, `V1ConnectionOptions`. `ServiceServerOptions.legacyV1Handlers` 에 `V1RequestHandler[]` 를 넘기면 `ServiceServer` 가 자동 사용.

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

@@ -0,0 +1,66 @@
+# @simplysm/service-server — server
+
+서버 인스턴스 부트스트랩 표면. `ServiceServer` 가 Fastify · WebSocket · JWT · 정적/업로드/API 라우트를 일괄 등록하고 SIGINT/SIGTERM 정상 종료까지 처리한다.
+
+## `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
+}
+```
+
+## `createServiceServer<TAuthInfo>(opts) → ServiceServer<TAuthInfo>`
+
+`new ServiceServer(opts)` 단순 래퍼. `TAuthInfo` 는 JWT `data` 페이로드 타입.
+
+## `ServiceServer<TAuthInfo>`
+
+```ts
+class ServiceServer<TAuthInfo = unknown> extends EventEmitter<{ ready: void; close: void }> {
+  readonly fastify: FastifyInstance;
+  readonly options: ServiceServerOptions;
+  isOpen: boolean;
+
+  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>;
+}
+```
+
+`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` 정적 파일).
+
+`auth == null` 인데 `services` 중 하나라도 `authPermissions != null` 이면 `listen()` 에서 즉시 throw.
+
+이벤트 브로드캐스트 — 서버는 클라이언트가 `evt:add` 로 등록한 리스너만 안다. `getEvent(name).emit(infoSelector, data)` 로 매칭된 리스너에게만 푸시:
+
+```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>({
+  rootPath: process.cwd(),
+  port: 50080,
+  auth: { jwtSecret: env("JWT_SECRET")! },
+  services: [OrmService, AutoUpdateService, MyService],
+});
+server.on("ready", () => console.log("up"));
+await server.listen();
+```

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

@@ -0,0 +1,69 @@
+# @simplysm/storage
+
+FTP/FTPS/SFTP 원격 스토리지에 동일 인터페이스(`StorageClient`)로 파일을 읽고/쓰는 Node 라이브러리.
+
+## 사용 트리거 인덱스
+
+- **`StorageFactory.connect`** — FTP/FTPS/SFTP 어느 것이든 연결→작업→자동 종료를 한 번에 처리할 때 (권장 진입점).
+- **`StorageClient`** — 콜백 안에서 사용하는 공통 파일 작업 인터페이스(mkdir/list/readFile/put/uploadDir/remove/rename/exists).
+- **`FtpStorageClient` / `SftpStorageClient`** — 연결 생명주기를 직접 관리해야 할 때만 (장기 연결 풀 등). 그 외엔 `StorageFactory.connect` 사용.
+- **`StorageConnConfig`, `StorageProtocol`, `FileInfo`** — 위 API 호출 시 타입.
+
+## StorageFactory.connect
+
+```ts
+class StorageFactory {
+  static connect<R>(
+    type: StorageProtocol,                                   // "ftp" | "ftps" | "sftp"
+    config: StorageConnConfig,
+    fn: (storage: StorageClient) => R | Promise<R>,
+  ): Promise<R>;
+}
+```
+
+- `type` 에 따라 `FtpStorageClient(secure=false)` / `FtpStorageClient(secure=true)` / `SftpStorageClient` 생성.
+- 콜백 실행 전 `connect`, 콜백 종료(예외 포함) 후 `close` 자동 호출. `close` 실패는 무시.
+
+```ts
+const list = await StorageFactory.connect("sftp", { host, user, password }, async (s) => {
+  await s.mkdir("/up/2026");
+  await s.put(Buffer.from("hi"), "/up/2026/a.txt");
+  return await s.list("/up/2026");
+});
+```
+
+## StorageClient
+
+```ts
+interface StorageClient {
+  connect(config: StorageConnConfig): Promise<void>;
+  mkdir(dirPath: string): Promise<void>;                              // 부모 디렉토리 자동 생성
+  rename(fromPath: string, toPath: string): Promise<void>;
+  list(dirPath: string): Promise<FileInfo[]>;                         // { name, isFile }
+  readFile(filePath: string): Promise<Bytes>;                         // Bytes = Uint8Array (@simplysm/core-common)
+  exists(filePath: string): Promise<boolean>;                         // 모든 예외 시 false
+  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;  // string=로컬 경로, Bytes=메모리 버퍼
+  uploadDir(fromPath: string, toPath: string): Promise<void>;         // 디렉토리 통째로 업로드
+  remove(filePath: string): Promise<void>;
+  close(): Promise<void>;                                             // 이미 종료돼 있어도 안전
+}
+
+interface StorageConnConfig { host: string; port?: number; user?: string; password?: string; }
+interface FileInfo { name: string; isFile: boolean; }
+type StorageProtocol = "ftp" | "ftps" | "sftp";
+```
+
+## FtpStorageClient / SftpStorageClient
+
+`StorageClient` 구현체. 직접 사용 시 주의:
+
+- `connect` 후 반드시 `close`. 동일 인스턴스에서 `connect` 중복 호출 금지(연결 누수 → `SdError` throw). `close` 후 재연결은 가능.
+- `FtpStorageClient(secure: boolean)` — `secure=true` 가 FTPS.
+- `SftpStorageClient` — `config.password` 가 있으면 비밀번호 인증. 없으면 `~/.ssh/id_ed25519` 키 + (있으면) `SSH_AUTH_SOCK` agent 로 시도, 키 파싱 실패 시 agent 단독 재시도.
+- `FtpStorageClient.exists` — 파일은 `size()` 로 O(1), 디렉토리는 부모 `list()` 스캔. 슬래시 없는 경로는 `/` 기준.
+
+```ts
+const client = new SftpStorageClient();
+await client.connect({ host, user, password });
+try { /* ... */ } finally { await client.close(); }
+```

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

@@ -1,14 +1,12 @@
 # 클라이언트 화면 작성 매뉴얼
 
-이 문서는 `@simplysm/angular` v14 패키지로 화면을 만들 때 따르는 컨벤션을 모은다.
-
 ## 파일명·역할·위치
 
 화면 파일은 `<domain>.<역할>.ts` 형식, 역할 접미사로 책임을 표시한다.
 
 | 파일명 형식                  | 역할                                                                      |
 | ---------------------------- | ------------------------------------------------------------------------- |
-| `<domain>.view.ts`           | list/detail 로 깔끔히 나뉘지 않는 화면. 보통 list/detail 의 orchestrator. |
+| `<domain>.view.ts`           | list/detail 로 깔끔히 나뉘지 않는 화면. (예시: list/detail 의 orchestrator) |
 | `<domain>.list.ts`           | 목록. `sd-crud-list` 사용.                                                |
 | `<domain>.detail.ts`         | 단건 보기/편집. `sd-crud-detail` 사용.                                    |
 | `<domain>.modal.ts`          | 모달 전용 화면.                                                           |
@@ -65,6 +63,8 @@ Angular 기본과 다른 부분만 명시:
 
 화면이 list 또는 detail 하나로 끝나면 view 를 만들지 않고 list/detail 자체가 라우팅 진입 단위가 된다.
 
+### list + detail 합성
+
 view 의 합성 패턴 (예: `outbound-instruction.view.ts`):
 
 ```html
@@ -74,7 +74,7 @@ view 의 합성 패턴 (예: `outbound-instruction.view.ts`):
       <app-outbound-instruction-list #headerSheet selectMode="single" class="flex-min" />
 
       @let _selectedId = headerSheet.selectedKeys().first(); @if (_selectedId == null) {
-      <div class="flex-fill ...">선택하세요.</div>
+      <div class="flex-fill p-default">선택하세요.</div>
       } @else {
       <app-outbound-instruction-detail
         class="flex-fill"
@@ -93,9 +93,40 @@ view 의 합성 패턴 (예: `outbound-instruction.view.ts`):
 - detail 의 단건 변경·삭제는 list 가 표시하는 같은 데이터에 반영돼야 하므로, detail 의 `submitted` → list 의 `doRefresh()` 호출로 동기화한다.
 - view 는 `sd-base-container` 를 루트로 두고, 내부 컨텐츠는 `#contentTpl` 슬롯에 둔다.
 
+### list + list 합성 (마스터-라인)
+
+좌 list 가 마스터(헤더), 우 list 가 디테일(라인) 역할로 합성:
+
+```html
+<sd-base-container [(ready)]="ready" [initialized]="initialized()" [(busyCount)]="busyCount" ...>
+  <ng-template #contentTpl>
+    <div class="flex-row fill">
+      <app-master-list #headerSheet selectMode="single" class="flex-min" />
+
+      @let _selectedId = headerSheet.selectedKeys().first();
+      @if (_selectedId == null) {
+        <div class="flex-fill p-default">선택하세요.</div>
+      } @else {
+        <app-line-list
+          class="flex-fill"
+          [headerId]="_selectedId"
+          (submitted)="headerSheet.doRefresh()"
+        />
+      }
+    </div>
+  </ng-template>
+</sd-base-container>
+```
+
+핵심 약속:
+
+- 우 list 는 좌의 선택 키를 `input` 으로 받아 자동 재조회. (외부 input → filter 머지 패턴은 §"외부 input 을 filter 에 반영" 참조.)
+- 우 list 의 저장·삭제 후 좌 헤더 목록까지 갱신해야 하면 우 list 가 `submitted` output 을 emit, view 가 받아 `#headerSheet.doRefresh()` 호출.
+- 우 list 안에 추가 분기(탭 등)는 [client-tab.md](./client-tab.md) 매뉴얼 채택.
+
 ## 화면 컴포넌트의 표준 시그널
 
-화면 컴포넌트(view/list/detail/modal) 가 공통으로 쓰는 시그널 5종. **필요한 것만 채택**하되, 채택할 때는 아래 약속된 이름·의미·전파를 그대로 따른다.
+화면 컴포넌트(view/list/detail/modal) 가 공통으로 쓰는 시그널 4종. **필요한 것만 채택**하되, 채택할 때는 아래 약속된 이름·의미·전파를 그대로 따른다.
 
 | 이름          | 종류                     | 의미                                                                                                                                  |
 | ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -103,16 +134,9 @@ view 의 합성 패턴 (예: `outbound-instruction.view.ts`):
 | `initialized` | `signal(false)`          | 첫 데이터 로드까지 끝났는지. 자식이 자기 로드 끝낸 뒤 set true.                                                                       |
 | `busyCount`   | `signal(0)`              | 진행 중인 비동기 작업 수. 시작 시 `+1`, 끝나면 `-1`. > 0 이면 화면이 busy 표시.                                                       |
 | `viewType`    | `injectViewTypeSignal()` | 화면이 page / control / modal 어느 컨텍스트에서 동작 중인지. 라우팅 진입이면 `'page'`, view 자식이면 `'control'`, 모달이면 `'modal'`. |
-| `restricted`  | `computed`               | 권한 부족 등으로 컴포넌트를 비활성화할지. 보통 `!perms().includes('use')`.                                                            |
 
 **전파**: 부모가 자식에게 위 시그널들을 그대로 흘려보낸다. `sd-base-container` / `sd-crud-list` / `sd-crud-detail` 가 이들을 입력으로 받는 표준.
 
-**`viewType` 결정**:
-
-- **라우팅 진입 단위**(view 또는 단독 list/detail) — `viewType = injectViewTypeSignal()` 로 받음.
-- **view 의 자식**(view 안에 임베드되는 list/detail) — 보통 `'control'` 고정값으로 전달.
-- **모달 진입** — modal 컴포넌트의 `viewType` 은 `'modal'` 로 자동 주입됨.
-
 **`busyCount` 사용 패턴**:
 
 ```ts
@@ -141,7 +165,7 @@ perms = injectPermsSignal(
 
 - 단순한 권한 체크는 `this.perms().includes("use")` 를 템플릿·코드에 인라인으로 쓴다. 별도 computed 로 묶지 않는다.
 - `restricted` 입력은 `[restricted]="!perms().includes('use')"` 형태로 인라인 전달. (별도 `canUse` / `restricted` computed 만들지 않는다.)
-- 권한 체크 뒤에 추가 조건(데이터 상태 등)이 결합되어 **빈번히 쓰일 때만** computed 로 묶는다.
+- 권한 체크 뒤에 추가 조건(데이터 상태 등)이 결합되어 **같은 결합이 2회 이상 참조될 때만** computed 로 묶는다.
 
 ```ts
 canEdit = computed(() => this.perms().includes("edit") && this.data().state === "작성");
@@ -224,7 +248,7 @@ if (!result) return;
 - **`type`** — `SdModal` 을 구현(상속)한 컴포넌트 클래스.
 - **`title`** — 모달 헤더 제목.
 - **`inputs`** — 모달 컴포넌트가 받을 input 시그널 값. 없으면 `{}`.
-- **반환값** — 모달 컴포넌트가 close 시 emit 한 페이로드. 사용자가 X/취소로 닫으면 `undefined`.
+- **반환값** — 모달 컴포넌트가 close 시 emit 한 페이로드. 사용자가 닫기(X)/취소로 닫으면 `undefined`.
 
 ## `mark` 헬퍼
 
@@ -329,6 +353,25 @@ private async _refresh(): Promise<void> {
 
 `_search` 는 ORM 쿼리 실행. 자세한 사용은 [orm.md](./orm.md) 참조.
 
+### 페이지네이션
+
+두 패턴 중 택일. 데이터 규모와 검색·정렬 책임에 따라 화면 작성자가 판단(명확한 컷오프 없음).
+
+**서버 페이징** — 한 페이지 분량만 매번 서버에서 가져옴. 위 §시그널 구성/effect/`_refresh` 가 가정한 디폴트 패턴.
+
+- `pageLength` 시그널을 두고 `_refresh` 에서 서버 응답의 총 페이지 수로 set.
+- `page` / `sortingDefs` / `lastFilter` 모두 effect 의존성. 변경 시 재조회.
+- `<sd-crud-list>` 에 `[totalPageCount]="pageLength()"` 전달. `[itemsPerPage]` 는 생략(=0).
+
+**클라이언트 페이징** — 전체 데이터를 한 번에 로드, 시트가 자체 slice/sort.
+
+- `pageLength` 시그널·`sortingDefs` effect 의존성 불필요. (정렬은 시트 내부에서 처리.)
+- `_refresh` 는 전체 아이템을 한 번에 `items.set(all)`.
+- `<sd-crud-list>` 에 `[itemsPerPage]="<페이지당 행 수>"` 전달. `[totalPageCount]` 는 생략(=0).
+- `[(sorts)]` 는 화면이 정렬 상태를 들고 있어야 할 때만 묶음. 아니면 생략.
+
+**`[visiblePageCount]`** (기본 10) — 페이지네이터가 한 번에 표시하는 페이지 번호 개수. 두 패턴 모두 사용자가 명시 지시한 경우에만 명시.
+
 ### 외부 input 을 filter 에 반영
 
 list 가 다른 화면 안에 임베드되어 외부에서 filter 의 일부를 input 으로 받을 때, effect 로 input → filter → lastFilter 흐름을 만든다.
@@ -466,19 +509,26 @@ async onSubmit(): Promise<void> {
 ## 시트 컬럼·셀 표준
 
 ```html
-<sd-sheet-column [key]="'name'" [header]="'이름'" [width]="'160px'">
+<sd-sheet-column [key]="'name'" [header]="'이름'">
   <ng-template [cell]="items()" let-item="item">
     <div class="p-xs-sm">{{ item.name }}</div>
   </ng-template>
 </sd-sheet-column>
 ```
 
+**폭 약속**:
+
+- `[width]` 는 **명시하지 않음이 기본** — 자동. px 지정은 사용자가 명시 지시한 경우에만.
+- 영역 폭(`flex-min` 의 `style="width: ..."` 등) 도 동일.
+
 **셀 본문 약속**:
 
 - 시트 셀에는 패딩이 없으므로 본문 div 에 `p-xs-sm` 클래스를 붙이는 게 기본.
-- 정렬은 `tx-right` (숫자), `tx-center` (라벨/아이콘), 기본 left.
+- 정렬 클래스(`tx-right` / `tx-center` / `tx-left`)는 **사용자가 명시 지시한 경우에만** 사용. 기본은 미지정(브라우저 기본 left). "라벨은 가운데" 같은 자동 휴리스틱 적용 금지.
+- 단, **숫자 셀은 `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 가 셀에 차지 않음.)
 
 **list 안에서**: `<sd-crud-list>` 의 직속 자식으로 `<sd-sheet-column>` 을 두면 내부 시트로 자동 투영된다.
 
@@ -492,21 +542,47 @@ async onSubmit(): Promise<void> {
 </sd-crud-list>
 ```
 
+### 요약 행
+
+컬럼에 `<ng-template #summaryTpl>` 을 두면 시트의 헤더 영역 하단(`thead` 내부)에 요약 행이 렌더된다. 스크롤 시 헤더와 함께 상단 고정되며, 배경은 warning 계열로 자동 강조된다.
+
+```html
+<sd-sheet-column [key]="'quantity'" [header]="'수량'">
+  <ng-template #summaryTpl>
+    <div class="p-xs-sm tx-right">{{ totalQuantity() }}</div>
+  </ng-template>
+  <ng-template [cell]="items()" let-item="item">
+    <div class="p-xs-sm tx-right">{{ item.quantity }}</div>
+  </ng-template>
+</sd-sheet-column>
+```
+
+- 컬럼 중 하나라도 `#summaryTpl` 을 가지면 요약 행 전체가 활성화된다. 정의 없는 컬럼은 빈 셀.
+- 셀 본문 약속(`p-xs-sm`, 정렬 클래스 등)은 요약 셀에도 동일하게 적용.
+- 합계·평균 등 집계 값은 시트가 계산해주지 않는다. 화면 컴포넌트에서 `computed` 로 직접 만들어 노출한다.
+
+```ts
+totalQuantity = computed(() => this.items().sum((i) => i.quantity) ?? 0);
+```
+
 ## 폼·입력 컨트롤
 
 ### 폼 항목 레이아웃
 
-여러 입력 항목을 가로로 나열할 때 `form-box-inline` 컨테이너 + 항목별 `form-box-item`:
+label + 입력 그룹을 묶는 전용 클래스 3종:
+
+- `form-box` — 세로 스택. `> div` 또는 `> div` 안에 `<label>` + 입력. 항목 사이 `gap-default`.
+- `form-box-inline` — 가로 인라인 flex (wrap). 라벨이 입력 옆에 붙음. 검색·필터폼에 사용. 라벨 없는 `form-box-item` 도 허용 (버튼 등).
+- `form-table` — `<table>` 기반. `<th>` 가 우측 정렬 라벨, `<td>` 가 입력. `<th class="form-table-header">` 는 섹션 헤더(좌측 정렬, 회색, 위쪽 여백 큼). 라벨/입력 폭을 정렬해야 하는 등록·편집 폼에 사용.
 
 ```html
 <div class="form-box-inline">
-  <div class="form-box-item">
-    <label>이름</label>
-    <sd-textfield [(value)]="data().name" (valueChange)="mark(data)" />
+  <div>
+    <label>기준 일자</label>
+    <sd-modal-select-button [(value)]="baseDate" ...>{{ baseDate() ?? "선택" }}</sd-modal-select-button>
   </div>
-  <div class="form-box-item">
-    <label>등록일</label>
-    <sd-textfield [type]="'date'" [(value)]="data().createdAt" (valueChange)="mark(data)" />
+  <div>
+    <sd-button [theme]="'primary'" (click)="onCompareButtonClick()">비교</sd-button>
   </div>
 </div>
 ```
@@ -531,6 +607,16 @@ async onSubmit(): Promise<void> {
 | 라벨/배지            | `<sd-label [theme]>`                                         |
 | 버튼/액션            | `<sd-button>`, `<sd-anchor>`                                 |
 
+### 버튼 스타일
+
+화면 액션 `<sd-button>` 은 역할별로 `theme`·`size` 를 구분.
+
+| 역할                                                          | `[theme]`                                                                   | `[size]` |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------- | -------- |
+| 데이터 자체를 통으로 변경하는 최상위 액션 (저장·삭제·생성 등) | 일반 시리즈 (`primary` / `danger` / `success` / `warning` 등 의미에 맞춰)   | 기본     |
+| 위 액션 옆 유틸리티 버튼 (양식 다운로드·인쇄 등)              | link 시리즈 (`link-primary` 등)                                             | 기본     |
+| 시트 위(또는 시트 셀 안)에 나열되는 버튼                      | link 시리즈 또는 `link`                                                     | `sm`     |
+
 ### `<sd-form>` 으로 감싸기
 
 폼 안 입력에서 enter 키 → submit 자동 처리되게 하려면 `<sd-form>` 으로 감싸고 `(formSubmit)` 로 받는다. `sd-crud-list` / `sd-crud-detail` 는 내부에 이미 `sd-form` 을 갖고 있어 별도 래핑 불필요.
@@ -578,18 +664,33 @@ sharedCustomers = useSharedSignal("고객사");
 
 ## 레이아웃·유틸 클래스
 
-**화면 레이아웃** (영역 분할 — 상단/하단/좌/우/중앙): `<sd-dock-container>` + `<sd-dock>`.
+**화면 레이아웃** (영역 분할): flex 유틸 클래스.
+
+상하 분할 (상단 고정 + 본문 fill):
 
 ```html
-<sd-dock-container>
-  <sd-dock class="pb-sm">
+<div class="flex-column fill">
+  <div class="pb-sm">
     <!-- 상단 고정 영역 -->
-  </sd-dock>
-  <!-- 본문 (남은 공간 자동) -->
-</sd-dock-container>
+  </div>
+  <div class="flex-fill">
+    <!-- 본문 (남은 공간 자동) -->
+  </div>
+</div>
 ```
 
-**아이템 레이아웃** (영역 안 항목 배치): flex 유틸 클래스.
+좌우 분할 (좌측 콘텐츠 폭 + 우측 fill):
+
+```html
+<div class="flex-row fill">
+  <div class="flex-min">
+    <!-- 좌측 -->
+  </div>
+  <div class="flex-fill">
+    <!-- 우측 -->
+  </div>
+</div>
+```
 
 자주 쓰는 유틸:
 
@@ -602,7 +703,7 @@ sharedCustomers = useSharedSignal("고객사");
 
 **약속**:
 
-- 영역 분할은 `sd-dock-container` / `sd-dock`, 영역 안 배치는 flex 유틸 클래스를 우선한다. 자체 styles 작성은 마지막 수단.
+- 영역 분할·배치 모두 flex 유틸 클래스 우선. 자체 styles 작성은 마지막 수단.
 - 글로벌 클래스 정의는 `@simplysm/angular/scss/commons/`.
 
 ## 아이콘
@@ -631,101 +732,6 @@ export class SomeComponent {
 - 아이콘 셋트는 `tabler-icons` 통일.
 - 사용할 아이콘은 컴포넌트 클래스에 `protected readonly tablerXxx = tablerXxx` 로 노출 후 템플릿에서 `[svg]` 바인딩.
 
-## `sd-crud-list`
-
-목록 화면의 표준 골격. 시트 + 검색 폼 + 등록/삭제/복구 버튼 + CTRL+S 저장 + 모달 선택 모드를 한꺼번에 처리.
-
-### 표준 호출
-
-```html
-<sd-crud-list
-  [(ready)]="ready"
-  [initialized]="initialized()"
-  [(busyCount)]="busyCount"
-  [restricted]="!perms().includes('use')"
-  [readonly]="!canEdit()"
-  [viewType]="viewType()"
-  [selectMode]="selectMode() ?? 'multi'"
-  [key]="'<도메인-키>'"
-  [items]="items()"
-  [trackByFn]="trackByFn"
-  [(selectedKeys)]="selectedKeys"
-  [(currentPage)]="page"
-  [totalPageCount]="pageLength()"
-  [(sorts)]="sortingDefs"
-  (filterSubmit)="onFilterSubmit()"
-  (submit)="onSubmit()"
-  (create)="onCreate()"
-  (delete)="onDelete($event)"
-  (restore)="onRestore($event)"
->
-  <ng-template #filterTpl>...</ng-template>
-  <ng-template #toolTpl>...</ng-template>
-
-  <sd-sheet-column ...>
-    <ng-template [cell]="items()" let-item="item">...</ng-template>
-  </sd-sheet-column>
-</sd-crud-list>
-```
-
-### 슬롯 약속
-
-| 슬롯                | 용도                                                                       |
-| ------------------- | -------------------------------------------------------------------------- |
-| `#filterTpl`        | 검색 폼 필드. 있으면 상단에 조회 버튼과 함께 노출.                         |
-| `#toolTpl`          | 등록/삭제 버튼 옆 추가 도구 버튼.                                          |
-| `#commandTpl`       | 상단(또는 modal/control 모드의 명령 영역) 추가 액션 버튼.                  |
-| `#bottomCommandTpl` | modal 하단 좌측 영역. modal + selectMode 면 "선택 해제/확인" 과 함께 표시. |
-
-`<sd-sheet-column>` 은 `<sd-crud-list>` 의 직속 자식으로 두면 내부 시트로 자동 투영된다.
-
-### viewType 별 동작
-
-- **`'page'`** — 라우팅 진입 단위. 상단에 저장 버튼.
-- **`'control'`** — view 안에 임베드. 명령 영역에 저장 버튼.
-- **`'modal'`** — 모달. `selectMode` 와 함께 쓰면 close 페이로드 `{ selectedKeys }` 자동 처리.
-
-### 모달 선택 모드
-
-`viewType="modal"` + `selectMode` 지정 시:
-
-- `single` — 행 클릭 즉시 modal close.
-- `multi` — 하단 "확인(N)" 버튼이 close 발생.
-
-호출측은 `_sdModal.showAsync(...)` 결과로 `{ selectedKeys }` 페이로드 회수.
-
-## `sd-crud-detail`
-
-단일 레코드 편집 화면의 표준 골격. 폼 래핑 + CTRL+S/저장 버튼 + 모달의 "확인" 버튼 자동 처리.
-
-### 표준 호출
-
-```html
-<sd-crud-detail
-  [(ready)]="ready"
-  [initialized]="initialized()"
-  [(busyCount)]="busyCount"
-  [restricted]="!perms().includes('use')"
-  [readonly]="!canEdit()"
-  [viewType]="viewType()"
-  (submit)="onSubmit()"
->
-  <ng-template #contentTpl>
-    <!-- 폼 본문 -->
-  </ng-template>
-</sd-crud-detail>
-```
-
-### 슬롯 약속
-
-| 슬롯                 | 용도                                                              |
-| -------------------- | ----------------------------------------------------------------- |
-| `#contentTpl` (필수) | 폼 본문. `readonly` 면 `<sd-form>` 래핑 없이 그냥 표시된다.       |
-| `#commandTpl`        | 상단/명령 영역 추가 버튼.                                         |
-| `#bottomCommandTpl`  | modal 하단 좌측. modal 일 때 우측 "확인" 버튼이 항상 자동 추가됨. |
-
-### viewType 별 동작
+## sd-crud-* 컴포넌트
 
-- **`'page'`** — 라우팅 진입 단위. 상단에 저장 버튼.
-- **`'control'`** — view 안에 임베드. 명령 영역에 저장 버튼.
-- **`'modal'`** — 모달. 하단 우측 "확인" 버튼이 자동.
+목록 화면 표준 골격 `sd-crud-list`, 단건 편집 화면 표준 골격 `sd-crud-detail`. 화면 작성 시 이 둘을 채택할지 결정한다. 채택 시 사용법은 [client-crud.md](./client-crud.md).