@simplysm/sd-claude 14.0.100 → 14.0.101

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

@@ -34,6 +34,7 @@ ORM 호출, 파일 변환, 비즈니스 로직 등은 위 두 경우에 해당
 | `sd-crud-list` / `sd-crud-detail` 채택한 목록·단건 화면 (편집 진입·삭제/복구·엑셀 다운로드·행 선택 제한) | [client-crud.md](./manuals/client-crud.md)             |
 | 클라이언트 데모 컴포넌트 작성                           | [client-demo.md](./manuals/client-demo.md)             |
 | `<sd-tab>` 사용                                         | [client-tab.md](./manuals/client-tab.md)               |
+| 화면 데이터를 종이 인쇄·PDF 출력 (`.print-template.ts` 작성, `printAsync`/`getPdfBufferAsync`, PDF 다운로드·이메일) | [client-print.md](./manuals/client-print.md)           |
 | 앱에서 서버 서비스·이벤트 호출 (provider 정의·항목 추가) | [client-service.md](./manuals/client-service.md)       |
 | 앱에서 ORM(DB) 사용 (AppOrmProvider 정의)               | [client-orm.md](./manuals/client-orm.md)               |
 | 앱에서 공유 마스터 데이터 사용 (provider 정의·항목 추가, 선택 컨트롤의 관리·선택 모달, 좌측 선택+우측 상세 레이아웃) | [client-shared-data.md](./manuals/client-shared-data.md) |
@@ -45,6 +46,7 @@ ORM 호출, 파일 변환, 비즈니스 로직 등은 위 두 경우에 해당
 | CRUD 처리에 데이터 변경 이력 적재·조회·표시 (누가·언제·무엇을 변경, 목록의 수정일시·수정자 컬럼) | [data-log.md](./manuals/data-log.md)                   |
 | 콘솔 로깅 코드 작성/수정 (모든 패키지)                  | [logging.md](./manuals/logging.md)                     |
 | 클라이언트 시스템 에러·로그를 DB 등 외부에 적재·조회    | [client-system-log.md](./manuals/client-system-log.md) |
+| 클라이언트 사용자별 UI·시스템 설정을 DB 등에 영속화 (`SdSystemConfigProvider.fn` 배선, 시트 컬럼 설정 서버 저장) | [client-system-config.md](./manuals/client-system-config.md) |
 | 패키지 테스트·통합 테스트 작성/추가                     | [test.md](./manuals/test.md)                           |
 
 ## 패키지 인덱스

package/claude/references/sd-simplysm14/apis/angular/features.md

@@ -6,16 +6,21 @@
 
 ### `SdThemeProvider`
 
-`@Injectable({ providedIn: "root" })`. (`provideSdAngular` 가 dark/fontSize 를 `SdLocalStorageProvider` 에 영속화)
+`@Injectable({ providedIn: "root" })`. (`provideSdAngular` 가 dark/blueprint/fontSize 를 `SdLocalStorageProvider` 에 영속화)
 
 - `dark: WritableSignal<boolean>` (초기 false) — `effect` 로 body `sd-theme-dark` 클래스 토글(브라우저 전용).
+- `blueprint: WritableSignal<boolean>` (초기 false) — `effect` 로 body `sd-theme-blueprint` 클래스 토글. dark 와 직교(독립).
 - `fontSize: WritableSignal<number>` (초기 12) — `effect` 로 `documentElement.style.fontSize` 설정.
 - `fontSizePresets: readonly number[]` = `[12, 14, 16, 20, 24, 28]`.
 - `increaseFontSize()` / `decreaseFontSize()` — 다음/이전 프리셋으로(경계에서 no-op).
 
+#### 블루프린트(엔지니어링 도면) 테마
+
+`blueprint`·`dark` 직교 조합으로 4면: 디폴트-라이트/다크, 블루프린트-트레이싱지(라이트)/시아노타입(다크). CSS 변수 오버라이드(`.sd-theme-blueprint` / `.sd-theme-blueprint.sd-theme-dark`)로 구현 — primary=제도 블루·danger=리드라인, 직각(라운드 0), 하드 오프셋 섀도(`--elevation-blur-mult: 0`). 모눈 그리드는 body·chrome(`sd-sidebar`·`sd-topbar`)에만, 콘텐츠(카드·시트 등)는 무지. 폰트는 앱 책임(프레임워크 미번들).
+
 ### `SdThemeSelector` — `<sd-theme-selector>`
 
-팔레트 아이콘 드롭다운(폰트 +/- · 다크모드 스위치). input 없음. `isMinFontSize`/`isMaxFontSize: computed` 로 +/- 버튼 비활성.
+팔레트 아이콘 드롭다운(폰트 +/- · 다크모드 스위치 · 블루프린트 스위치). input 없음. `isMinFontSize`/`isMaxFontSize: computed` 로 +/- 버튼 비활성.
 
 ## 주소
 

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

@@ -183,7 +183,7 @@ interface SdPostPublishScriptConfig { type: "script"; cmd: string; args: string[
 
 ```typescript
 "excel": { target: "neutral", publish: { type: "npm" } },
-"client": { target: "client", server: "server", publish: { type: "ftp", host: "...", path: "/www" } },
+"client-admin": { target: "client", server: "server", publish: { type: "ftp", host: "...", path: "/www/client-admin" } },
 ```
 
 ## Capacitor 설정 (SdCapacitorConfig)

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

@@ -29,17 +29,22 @@ function createServiceServer<TAuthInfo = unknown>(options: ServiceServerOptions)
 
 - `rootPath: string` — 서버 작업 루트. 정적 파일·업로드·자동업데이트는 `rootPath/www` 하위를, 설정은 `rootPath/.config.json` 을 기준으로 한다. 절대경로 권장.
 - `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 인증서. 형식은 들어온 필드로 구분한다.
+- `ssl?: { pfxBytes: Uint8Array; passphrase?: string } | { pemKeyBytes: Uint8Array; certBytes: Uint8Array; caBytes?: Uint8Array; passphrase?: string } | { letsencrypt: { domains: string[]; email: string; staging?: boolean; cloudflareApiToken?: string } }` — 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·테스트용).
+  - `letsencrypt` 가 있으면 Let's Encrypt 자동 발급/갱신. `domains` 인증서를 발급해 `rootPath/.acme/`(계정키·인증서·키)에 저장하고, 만료 30일 전 자동 갱신 후 무중단 교체한다. 챌린지 방식은 `cloudflareApiToken` 유무로 갈린다 — **미지정 시 TLS-ALPN-01**(서버가 443 핸드셰이크로 직접 응답), **지정 시 DNS-01**(Cloudflare 에 `_acme-challenge` TXT 를 자동 등록·삭제; 토큰은 `Zone:Read`+`Zone.DNS:Edit` 권한 필요, zone 은 도메인으로 자동 조회). `email` 은 LE 계정 연락처, `staging: true` 면 LE 스테이징(레이트리밋 회피, 테스트용)을 쓴다. 캐시된 유효 인증서가 있으면 즉시 적용하고, 없으면 최초 발급 완료까지 `listen()` 이 대기하며 발급 실패 시 throw 한다(`SD_ACME_DIRECTORY_URL` 로 ACME 디렉토리 URL, `SD_CLOUDFLARE_API_BASE_URL` 로 Cloudflare API base 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 로 아웃바운드가 가능해야 한다.
+  - **TLS-ALPN-01**(`cloudflareApiToken` 미지정):
+    - **Node 20.18.0+ 또는 22.9.0+** — 핸드셰이크 중 인증서를 주입하는 `TLSSocket.setKeyCert` 가 필요하다. 미만이면 기동 시 throw.
+    - **와일드카드 불가** — `domains` 는 정확한 FQDN.
+    - 검증 connection 이 포트 443 으로 인입되어 이 서버에 도달해야 한다: 공개 DNS A 레코드 → 서버, 앞단에 L4 프록시가 있으면 SNI 기준으로 이 서버에 패스스루(예: nginx `stream` + `ssl_preread`). 지역 차단(geo-block) 방화벽이면 LE 의 해외 검증 노드가 막혀 발급이 실패할 수 있다.
+  - **DNS-01**(`cloudflareApiToken` 지정):
+    - 인바운드 검증이 없어 방화벽/NAT 환경에서도 발급 가능하며 **와일드카드 가능**.
+    - 도메인 DNS 가 Cloudflare 로 관리되어야 하고, 서버에서 Cloudflare API 로 아웃바운드가 가능해야 한다.
+  - 공통: 도메인 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).

package/claude/references/sd-simplysm14/manuals/client-app-structure.md

@@ -134,4 +134,22 @@ this._sdAppStructure.usableModules.set(["scheduling"]);
 - `modules`: 나열한 모듈 중 **하나라도** 활성이면 표시(OR).
 - `requiredModules`: 나열한 모듈이 **모두** 활성이어야 표시(AND).
 - 조건을 건 항목은 해당 모듈이 `usableModules` 에 없으면 메뉴·권한에서 빠짐. 조건이 없는 항목은 모듈 설정과 무관하게 표시됨.
-- 모듈 기능을 쓰지 않는 앱은 `usableModules.set([])` 로 둠.
+- 모듈을 쓰지 않는 앱은 `usableModules` 설정을 생략 가능 — 모듈 조건(`modules`/`requiredModules`) 이 없는 항목은 `usableModules` 가 미설정(undefined) 이어도 항상 표시됨.
+
+## 6. 정의한 메뉴를 화면에 띄우기
+
+정의한 구조는 `SdAppStructureProvider.usableMenus()` 로 읽어 `<sd-sidebar-menu>` 에 바인딩. `usableMenus()` 는 권한(`permRecord`)·모듈(`usableModules`) 필터를 이미 적용한 최종 메뉴 트리를 반환.
+
+```ts
+private readonly _sdAppStructure = inject(SdAppStructureProvider);
+
+menus = computed(() => this._sdAppStructure.usableMenus());
+```
+
+```html
+<sd-sidebar-menu [menus]="menus()" />
+```
+
+- `usableMenus()` 는 권한 없는 화면·비활성 모듈을 이미 걸러낸 트리 — 컴포넌트에서 추가 필터를 두지 않음.
+- 권한 필터가 걸리려면 `permRecord` 가 set 돼 있어야 함(§4). 로그인 전에는 빈 권한이라 권한 화면이 메뉴에 안 나옴.
+- 사이드바·탑바 등 앱 셸 레이아웃 컴포넌트(`sd-sidebar`/`sd-sidebar-menu` 등) 자체는 [apis/angular/README.md](../apis/angular/README.md) 참조.

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

@@ -8,7 +8,7 @@
 
 | 파일명 형식                  | 역할                                                               |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `<domain>.view.ts`           | list/detail 합성 화면. list/detail 자식을 두고 상호 트리거를 중계. |
+| `<domain>.view.ts`           | 여러 영역을 합성·분할한 화면. list/detail 자식 합성형(트리거 중계) 또는 분할·리포트형(영역 직접 포함·직접 페치). |
 | `<domain>.list.ts`           | 목록. `sd-crud-list` 사용.                                         |
 | `<domain>.detail.ts`         | 단건 보기/편집. `sd-crud-detail` 사용.                             |
 | `<domain>.modal.ts`          | 모달 전용 화면.                                                    |
@@ -97,7 +97,9 @@ Angular 기본과 다른 부분만 명시:
 
 - **`*.list.ts`** — 자체 검색·페이지·정렬·재조회를 책임. `selectMode` 같은 입력을 받아 부모가 선택 동작을 제어할 수 있게 노출.
 - **`*.detail.ts`** — 식별자(`input.required`) 를 받아 자체 로드·저장. 변경·삭제 후 `submitted` output 으로 부모에게 알림.
-- **`*.view.ts`** — list/detail 합성 + 자식 간 트리거 중계. 데이터 페치는 view 에서 수행 금지.
+- **`*.view.ts`** — 여러 영역을 합성·분할한 화면. 두 형태:
+  - (a) **합성형** — list/detail 자식을 두고 자식 간 트리거만 중계. 데이터 페치는 자식에 위임하고 view 가 직접 페치하지 않음.
+  - (b) **분할·리포트형** — 재사용 list/detail 로 나누지 않고 필터·시트 등 영역을 view 가 직접 품는 읽기 전용 리포트·대시보드. 이 경우 view 가 직접 페치함.
 
 화면이 list 또는 detail 하나로 끝나면 view 를 만들지 않음. 이 경우 list/detail 자체가 라우팅 진입 단위.
 
@@ -624,6 +626,22 @@ async onSubmit(): Promise<void> {
 </sd-sheet-column>
 ```
 
+**다단(그룹) 헤더**: `[header]` 에 문자열 배열을 주면 다단 헤더가 됨. 배열의 각 원소가 위에서 아래로 헤더 행이 되고, 인접 컬럼이 같은 상위 행 텍스트를 가지면 그 상위 셀이 가로로 병합되어 그룹 헤더로 묶임. 단일 문자열 컬럼은 전체 헤더 높이를 세로로 차지.
+
+```html
+<sd-sheet-column [key]="'salesAmount'" [header]="['홈택스', '매출']">
+  <ng-template [cell]="items()" let-item="item">
+    <div class="p-xs-sm tx-right">{{ item.salesAmount | number }}</div>
+  </ng-template>
+</sd-sheet-column>
+<sd-sheet-column [key]="'salesVat'" [header]="['홈택스', '부가세']">
+  <ng-template [cell]="items()" let-item="item">...</ng-template>
+</sd-sheet-column>
+```
+
+- 두 컬럼이 상위 행에 같은 `'홈택스'` 를 가지므로 상단에 `홈택스` 그룹 헤더가 두 컬럼 위로 병합됨.
+- 배열 길이가 컬럼마다 달라도 됨 — 짧은 쪽은 마지막 원소가 아래 행까지 세로로 채워짐.
+
 **폭 약속**:
 
 - `[width]` 는 **미명시가 기본** (자동). px 지정은 사용자가 명시 지시한 경우에만 적용.
@@ -676,12 +694,26 @@ async onSubmit(): Promise<void> {
 
 - 컬럼 중 하나라도 `#summaryTpl` 을 가지면 요약 행 전체가 활성화됨. 정의 없는 컬럼은 빈 셀로 표시.
 - 셀 본문 약속(`p-xs-sm`, 정렬 클래스 등) 은 요약 셀에도 동일하게 적용.
-- 합계·평균 등 집계 값은 시트가 계산하지 않음. 화면 컴포넌트에서 `computed` 로 직접 만들어 노출.
+- 합계·평균 등 집계 값은 시트가 계산하지 않음. 집계 출처는 목록의 **페이징 여부** 로 갈림.
+
+**페이징 없는 전건 로드 목록** (자식·상세 목록 등) — `items()` 가 곧 전체이므로 `computed` 합산.
 
 ```ts
 totalQuantity = computed(() => this.items().sum((i) => i.quantity) ?? 0);
 ```
 
+**페이징 목록** — `items()` 는 현재 페이지뿐이라 `computed` 합산 금지 (페이지 합계만 나와 요약이 틀어짐). 전체 결과의 집계값을 별도 시그널로 받아 바인딩. 집계는 데이터 로딩 시 별도 쿼리로 구함 ([client-crud.md](./client-crud.md) 의 "페이징 목록 요약 집계" 참조).
+
+```ts
+summaryData = signal<{ amount: number }>({ amount: 0 });
+```
+
+```html
+<ng-template #summaryTpl>
+  <div class="p-xs-sm tx-right">{{ summaryData().amount | number }}</div>
+</ng-template>
+```
+
 ## 폼·입력 컨트롤
 
 ### 폼 항목 레이아웃

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

@@ -291,6 +291,31 @@ if (!this.sortingDefs().some((s) => s.key === "id")) {
 - 컬럼마다 `if (sort.key === "X") orderBy((c) => c.X, ...)` 식 분기 금지 — `sort.key` 가 select 별칭과 일치하므로 한 줄로 처리.
 - `obj` 는 `@simplysm/core-common`, `SortingDef` 는 `@simplysm/angular`.
 
+### 페이징 목록 요약 집계
+
+시트 요약 행([client-component.md](./client-component.md) 의 "요약 행")의 합계·평균은 **전체 필터 결과** 기준이어야 함. `items()` 는 현재 페이지뿐이라 컴포넌트에서 합산하면 페이지 합으로 틀어짐. `_search` 안에서 정렬·`limit` 적용 전 쿼리에 집계 쿼리를 별도로 실행해 받음.
+
+```ts
+summaryData = signal<{ amount: number }>({ amount: 0 });
+
+// _search 안 — 필터까지 적용한 쿼리(qr)에, orderBy·limit 적용 전 단계에서 집계
+const summary = { amount: 0 };
+if (usePagination) {
+  const row = await qr.select((r) => ({ amount: expr.sum(r.amount) })).single();
+  summary.amount = row?.amount ?? 0;
+}
+// 이후 qr 에 orderBy·limit 적용(→ qr2)해 items 조회, { items, pageLength, summary } 반환
+```
+
+```ts
+// _refresh 안 — 받은 집계를 시그널에 반영
+this.summaryData.set(r.summary);
+```
+
+- 집계는 `orderBy`·`limit` 적용 전 쿼리에 실행 — 정렬·현재 페이지와 무관한 전체 합. 정렬·페이지를 적용한 `qr2` 에 실행하면 페이지 합으로 잘못 나옴.
+- `usePagination=false`(엑셀 내보내기 등 전건 조회)면 집계 쿼리를 건너뜀 — 받은 전건을 컴포넌트에서 합산하면 됨.
+- 누적값(잔액 등)은 합산하지 않음 — 행별 누적값이라 합계가 의미 없음.
+
 ## `sd-crud-detail`
 
 단일 레코드 편집 화면의 표준 골격. 다음 기능을 일괄 제공: 폼 래핑, CTRL+S 단축키 저장, 저장 버튼, 모달의 "확인" 버튼 자동 처리.

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

@@ -32,6 +32,7 @@ export class AppOrmProvider {
 - `@Injectable({ providedIn: "root" })`.
 - DbContext 는 앱별로 정의 (예: `@adtek/db-main` 의 `MainDbContext`). 스키마 정의는 [orm.md](./orm.md).
 - 진입 메서드는 `connectAsync` (트랜잭션 포함).
+- `connectAsync` 는 콜백 안에서 난 FK(외래키) 제약 위반을 잡아 사용자 안내 메시지(`SdError`) 로 자동 변환함 — 참조 중인 데이터를 삭제하려 하면 "연관된 작업으로 인해 작업이 거부되었습니다" 류 경고가 화면에 뜸. 화면에서 같은 메시지를 따로 만들지 않음.
 - 콜백의 반환값이 그대로 메서드의 반환값이 됨.
 
 ## 화면·프로바이더에서 쿼리를 실행하려면

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

@@ -0,0 +1,134 @@
+# 인쇄·PDF 출력 매뉴얼
+
+화면 데이터를 종이로 인쇄하거나 PDF 로 받는 작업. `SdPrintProvider` 와 인쇄 템플릿(`<domain>.print-template.ts`) 으로 처리. **인쇄(브라우저 출력)와 PDF(이미지 캡처)는 페이지 분할 방식이 달라** 아래 함정을 함께 적용.
+
+## 인쇄 템플릿을 작성하려면
+
+`<domain>.print-template.ts` 에 `SdPrint` 를 구현한 컴포넌트를 둠. 인쇄·PDF 가 이 컴포넌트를 화면 밖에 임시로 렌더해 캡처함.
+
+```ts
+import { ChangeDetectionStrategy, Component, input, signal, ViewEncapsulation } from "@angular/core";
+import { DecimalPipe } from "@angular/common";
+import type { SdPrint } from "@simplysm/angular";
+
+@Component({
+  selector: "app-invoice-print-template",
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  standalone: true,
+  imports: [DecimalPipe],
+  template: `
+    @for (item of items(); track item.id) {
+      <div class="_page">
+        <h1 style="text-align: center">거래명세서</h1>
+        <!-- ... 본문 ... -->
+      </div>
+    }
+  `,
+  styles: [
+    /* language=SCSS */ `
+      app-invoice-print-template {
+        display: block;
+        background: white;
+
+        ._page {
+          padding: 50px;
+          page-break-after: always;
+        }
+      }
+    `,
+  ],
+})
+export class InvoicePrintTemplate implements SdPrint {
+  items = input.required<IInvoice[]>();
+  initialized = signal(true);
+}
+```
+
+- `implements SdPrint` — `initialized: Signal<boolean>` 보유 필수. provider 가 `initialized()` 가 true 가 될 때까지 기다린 뒤 인쇄/캡처함. 정적 템플릿은 `signal(true)` 로 즉시 완료, 템플릿이 자체 데이터 로딩을 하면 로딩 완료 후 `initialized.set(true)`.
+- 데이터는 `input` 으로 받음 — 호출 측이 `inputs` 로 주입.
+- `encapsulation: ViewEncapsulation.None` — 인쇄 시 전역으로 attach 되므로 스타일 캡슐화를 끔.
+- 페이지 단위 div(`._page`) 에 `page-break-after: always` 를 주면 인쇄 시 항목마다 페이지가 나뉨.
+
+## 화면에서 인쇄하려면
+
+`SdPrintProvider.printAsync` 에 템플릿 타입과 input 을 넘김. 브라우저 인쇄 대화상자가 뜸.
+
+```ts
+private readonly _sdPrint = inject(SdPrintProvider);
+
+await this._sdPrint.printAsync({
+  type: InvoicePrintTemplate,
+  inputs: { items: this.items() },
+});
+```
+
+- 둘째 인자 `options` 로 `{ size, margin }` 조정 가능 (기본 `size: "A4 auto"`, `margin: "0"`). `size` 는 CSS `@page size` 로 들어감.
+- 페이지 분할은 템플릿의 CSS `page-break-after`/`page-break-before` 로 제어 — `printAsync` 는 `window.print()` 를 호출하므로 브라우저 페이지 규칙을 따름.
+
+## PDF 로 받으려면
+
+`getPdfBufferAsync` 가 `Uint8Array`(PDF) 를 반환. `downloadBlob` 으로 파일 저장.
+
+```ts
+import { downloadBlob } from "@simplysm/core-browser";
+
+const pdfBuffer = await this._sdPrint.getPdfBufferAsync({
+  type: InvoicePrintTemplate,
+  inputs: { items: [item] },
+});
+downloadBlob(
+  new Blob([pdfBuffer], { type: "application/pdf" }),
+  `${item.code}_거래명세서.pdf`,
+);
+```
+
+- 둘째 인자 `options` 로 `{ orientation, pageSize }` 조정 (기본 `orientation: "p"`(portrait), `pageSize: "a4"`).
+- **PDF 페이지 분할은 인쇄와 다름** — `getPdfBufferAsync` 는 템플릿 안의 **`.page` 클래스**(언더스코어 없음) 엘리먼트를 각각 한 페이지로 캡처함. `.page` 가 하나도 없으면 **전체를 1페이지**로 만듦.
+  - 다중 페이지 PDF 가 필요하면 페이지 div 에 `.page` 클래스를 줌 (인쇄용 `._page` + `page-break` 와는 별개의 클래스).
+  - 또는 위 예시처럼 항목마다 `getPdfBufferAsync` 를 **단건 호출**해 1페이지 PDF 를 여러 개 만듦.
+
+## PDF 를 이메일로 보내려면
+
+생성한 PDF 버퍼를 메일 서비스의 첨부로 보냄. 메일 발송은 롤백 불가하므로, 다건은 **전원 PDF 를 먼저 생성한 뒤 발송**해 생성 단계 실패 시 한 건도 보내지 않게 함.
+
+```ts
+// 1) 전원 PDF 선생성 — 여기서 실패하면 발송은 시작도 안 함
+const prepared: { item: IInvoice; pdfBuffer: Uint8Array }[] = [];
+for (const item of targets) {
+  const pdfBuffer = await this._sdPrint.getPdfBufferAsync({
+    type: InvoicePrintTemplate,
+    inputs: { items: [item] },
+  });
+  prepared.push({ item, pdfBuffer });
+}
+
+// 2) 발송 — 중간 실패 시 성공/실패/미발송 경계를 담아 throw
+const sentCodes: string[] = [];
+for (let i = 0; i < prepared.length; i++) {
+  const { item, pdfBuffer } = prepared[i];
+  try {
+    await this._appService.mail.send({
+      to: item.email,
+      subject: "거래명세서",
+      html: "",
+      attachments: [{ filename: "거래명세서.pdf", content: pdfBuffer }],
+    });
+  } catch (err) {
+    const notSent = prepared.slice(i + 1).map((p) => p.item.code);
+    throw new Error(
+      `전송 중단 — 성공 ${sentCodes.length}건, 실패 ${item.code}, 미발송 ${notSent.length}건`,
+    );
+  }
+  sentCodes.push(item.code);
+}
+```
+
+- 메일 서비스(`mail.send`) 는 서버 서비스 — 호출 컨벤션은 [client-service.md](./client-service.md).
+- 첨부 대상이 누락된 항목(예: 이메일 미설정) 이 있으면 발송 전에 막고 대상 목록을 안내 — 일부만 보내고 나머지를 건너뛰지 않음.
+
+## 지킬 것
+
+- 인쇄 템플릿은 `implements SdPrint` + `initialized` 신호를 둠 — 누락 시 provider 가 렌더 완료를 못 기다려 빈 출력이 됨.
+- 인쇄 페이지 분할은 CSS `page-break`, PDF 페이지 분할은 `.page` 클래스 — 둘은 별개. PDF 가 한 장으로 뭉치면 `.page` 클래스 여부부터 확인.
+- 인쇄/PDF 호출은 `busyCount` + `_sdToast.try` 로 감쌈 ([client-component.md](./client-component.md) 의 '에러·토스트').

package/claude/references/sd-simplysm14/manuals/client-shared-data.md

@@ -69,7 +69,7 @@ export interface ISharedCustomer extends SharedDataBase<number> {
 
 ## 부트스트랩에 연결하려면 (새 앱 1회성)
 
-라이브러리 공유데이터 컨트롤(`sd-shared-data-select` · `sd-shared-data-select-list`)은 base 토큰 `SdSharedDataProvider` 를 inject 하므로, 부트스트랩 providers 에 앱 provider 를 그 토큰의 별칭으로 등록.
+CRUD 기반 컨테이너(`SdBaseContainer`)가 base 토큰 `SdSharedDataProvider` 를 optional inject(`inject(SdSharedDataProvider, { optional: true })`) 하므로, 부트스트랩 providers 에 앱 provider 를 그 토큰의 별칭으로 등록.
 
 ```ts
 // 앱 부트스트랩 (main.ts)
@@ -81,7 +81,7 @@ bootstrapApplication(AppRoot, {
 });
 ```
 
-- 이 별칭이 없으면 컨트롤이 데이터가 등록된 `AppSharedDataProvider` 가 아니라 빈 base 인스턴스를 잡아, 공유데이터 select 컨트롤에 항목이 표시되지 않음.
+- 이 별칭이 없으면 `SdBaseContainer` 의 optional inject 가 `null` 이 되어(추상 provider 라 `providedIn` 없음) 공유데이터 로딩 대기(`wait()`)를 건너뜀. select 컨트롤 자체는 화면의 `useSharedSignal(...)` → `items` 입력으로 데이터를 받으므로 이 별칭과 무관함.
 
 ## 마스터 데이터 항목을 추가하려면
 
@@ -155,6 +155,24 @@ sharedProducts = useSharedSignal("품목");
 
 - `register` 에 쓴 이름 문자열을 그대로 넘기면 `TAppSharedData` 에서 타입이 추론됨.
 
+## 변경을 통지하려면
+
+마스터를 CRUD(등록·수정·삭제·복구) 한 뒤 `emitAsync("<이름>", [changeKeys])` 로 통지하면, 그 마스터를 구독 중인 모든 화면의 공유 시그널이 자동 갱신됨. `register` 의 `getter(changeKeys)` 수신측과 짝을 이루는 발신측 — `emitAsync` 가 그 `changeKeys` 분기를 발동시킴.
+
+```ts
+private readonly _appSharedData = inject(AppSharedDataProvider);
+
+// 데이터 변경 트랜잭션이 커밋된 뒤 통지
+await this._appOrm.connectAsync(async (db) => {
+  // ... insert / update / soft delete ...
+});
+await this._appSharedData.emitAsync("역할", changedIds);
+```
+
+- 둘째 인자 `changeKeys` — 변경된 항목의 키 배열. 주면 수신측이 그 키들만 다시 조회해 부분 갱신(incremental refresh), 생략(`undefined`) 하면 전체 리로드.
+- 호출 위치는 변경 트랜잭션이 커밋된 뒤(= `connectAsync` 콜백 밖). 변경과 통지가 한 사용자 동작 안에서 이어짐.
+- `register` 안 한 이름을 넘기면 throw — 등록한 이름과 일치시킬 것.
+
 ## 선택 컨트롤에서 관리·선택 모달 띄우기
 
 공유데이터 선택 컨트롤(`sd-shared-data-select` · `sd-shared-data-select-list`)은 그 자리에서 해당 마스터를 관리·선택하는 모달을 여는 입력을 가짐. 마스터 목록 화면(`sd-crud-list` 기반)을 모달로 재사용해, 선택 컨트롤 옆에서 등록·수정·선택을 끝낼 수 있음.
@@ -235,4 +253,5 @@ constructor() {
 - 항목 추가 시 세 곳(`register` · `TAppSharedData` · 인터페이스)을 모두 갱신. 하나라도 빠지면 타입 불일치 또는 미등록 데이터가 됨.
 - select 결과에 매직 필드(`__valueKey` · `__searchText` · `__isHidden`)를 빠짐없이 포함.
 - `changeKeys` 분기를 생략하지 않음 — incremental refresh 가 동작하지 않으면 변경 시 전체 재조회가 됨.
+- 마스터 CRUD 후 `emitAsync` 통지를 빠뜨리지 않음 — 통지가 없으면 다른 화면의 공유 시그널이 옛 데이터를 유지함.
 - 공유데이터는 서버 연결을 전제하므로 프리렌더(SSG) 대상 화면의 초기화 경로에서 사용 금지 — 제약은 [client-ssg.md](./client-ssg.md) 참조.

package/claude/references/sd-simplysm14/manuals/client-system-config.md

@@ -0,0 +1,66 @@
+# 클라이언트 시스템 설정 영속화 매뉴얼
+
+클라이언트(Angular) 의 사용자별 UI·시스템 설정(시트 컬럼 너비/순서/숨김, 모달 크기·위치 등) 을 저장·복원하려 할 때 참조.
+
+`SdSystemConfigProvider`(`@simplysm/angular`, `providedIn: "root"`) 가 그 통로. `setAsync(key, data)` / `getAsync(key)` 로 키-값을 저장·조회하며, 프레임워크 컴포넌트(`sd-sheet` 컬럼 설정·`sd-modal` 크기 등) 가 이를 통해 상태를 보존함.
+
+저장 위치는 앱이 `fn` 을 배선했는지로 갈림:
+
+- `fn` **미배선(기본)** — 브라우저 `localStorage`. 그 기기·브라우저에만 남음.
+- `fn` **배선** — 앱이 준 `set`/`get` 으로 위임. 서버 DB 에 사용자별로 저장하면 기기가 바뀌어도 설정이 유지됨.
+
+## 사용자별로 서버(DB)에 저장하려면
+
+`provideAppInitializer` 안에서 `SdSystemConfigProvider.fn` 에 `set`/`get` 을 할당. 로그인 사용자(employee) 별로 설정을 DB 에 저장·조회.
+
+```ts
+import { inject, provideAppInitializer } from "@angular/core";
+import { json } from "@simplysm/core-common";
+import { expr } from "@simplysm/orm-common";
+import { SdSystemConfigProvider } from "@simplysm/angular";
+
+provideAppInitializer(() => {
+  const sdSystemConfig = inject(SdSystemConfigProvider);
+  const appAuth = inject(AppAuthProvider);
+  const appOrm = inject(AppOrmProvider);
+
+  sdSystemConfig.fn = {
+    set: async (key, val) => {
+      const employeeId = appAuth.authInfo()?.employeeId;
+      if (employeeId == null) return; // 로그인 전에는 저장하지 않음
+
+      await appOrm.connectAsync(async (db) => {
+        await db
+          .employeeConfig()
+          .where((item) => [expr.eq(item.employeeId, employeeId), expr.eq(item.code, key)])
+          .upsert(
+            () => ({ valueJson: json.stringify(val) }),
+            (updateRecord) => ({ ...updateRecord, employeeId, code: key }),
+          );
+      });
+    },
+    get: async (key) => {
+      const employeeId = appAuth.authInfo()?.employeeId;
+      if (employeeId == null) return; // 로그인 전에는 조회 불가 → undefined
+
+      return appOrm.connectAsync(async (db) => {
+        const row = await db
+          .employeeConfig()
+          .where((item) => [expr.eq(item.employeeId, employeeId), expr.eq(item.code, key)])
+          .single();
+        return row?.valueJson != null ? json.parse(row.valueJson) : undefined;
+      });
+    },
+  };
+});
+```
+
+- `key` 는 설정 항목 식별자(예: 시트 키), 값은 `json.stringify` 로 저장하고 `get` 에서 `json.parse` 로 복원.
+- 로그인 전(`employeeId == null`) 에는 `set` 을 건너뛰고 `get` 은 `undefined` 반환 — 인증 사용자별 설정이라 비로그인 상태로 저장하지 않음.
+- DB 에 둘 땐 `(employeeId, code)` 로 항목을 식별하는 사용자별 설정 테이블이 필요 — 스키마 정의는 [orm.md](./orm.md).
+
+## 지킬 것
+
+- `fn` 은 부트스트랩(`provideAppInitializer`) 에서 1회만 할당. 화면·서비스 코드에서 재할당하지 않음.
+- `fn` 미배선이면 자동으로 `localStorage` 폴백 — 기기 로컬 저장으로 충분하면 배선이 불필요.
+- 설정값은 `json` 으로 직렬화/역직렬화하여 컴포넌트가 넘긴 객체를 그대로 보존.

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

@@ -101,7 +101,7 @@ WHERE 와 SELECT 양쪽에서 동일 도출 산식을 쓰겠다고 `buildDerived
 
 ## 삭제 전략
 
-- **기초정보(마스터)**: soft delete (`isDisabled` 등) 사용. FK 참조 무결성 보존.
+- **기초정보(마스터)**: soft delete (`isDeleted` 등) 사용. FK 참조 무결성 보존.
 - **프로세스 문서(트랜잭션)**: 물리 delete. 상세 행을 포함해 캐스케이드. 단, 다른 테이블이 FK 로 참조 중이면 삭제를 차단하고 최종 사용자에게 toast 등으로 사유 안내.
 
 ## 유니크 전략 (활성 유니크 vs 완전 유니크)

package/claude/rules/sd-design-rules.md

@@ -4,20 +4,18 @@ Claude 에이전트가 코드 작성·설계·변경 시 따라야 할 행동
 
 ## 인터페이스 설계 시
 
-- 산출물에서 사용자가 접하는 면(공개 API·props·옵션·UI·출력 등)의 단순함이 내부 구현 단순함보다 우선:
-  - 복잡도는 내부에서 처리.
-  - 내부 처리 불가능할 경우 사용자에게 보고 후 사용자 결정에 따름.
-- 내부 구현 난이도를 회피하려고 사용자 요구를 완화·근사화하는 것 금지:
-  - 난이도는 내부에서 처리.
-  - 내부 처리 불가능할 경우 사용자에게 보고 후 사용자 결정에 따름.
-- 명시된 정의 자체를 임의로 단순화하여 처리 금지:
-  - 정확한 구현 부담이 크면 단순화안을 사용자에게 보고 후 사용자 합의에 따름.
+사용자가 접하는 면(공개 API·props·옵션·UI·출력)은 단순하고 정의에 충실하게 유지. 그 대가로 내부 구현이 복잡해지는 것은 당연히 떠안음 — 사용자 직관이 구현 편의보다 우선.
+
+- 사용자 면의 단순함이 내부 구현의 단순함보다 우선. 사용자가 직관적으로 쓰게 하려면 구현이 복잡해져야 하며, 이는 회피 대상이 아니라 당연한 일.
+- **구현이 복잡하다·부담된다는 사실은 기능을 빼거나, 사용자 요구를 완화·근사화하거나, 명시된 정의를 임의로 단순화하거나, 우회하자고 제안할 근거가 될 수 없음.** 구현 복잡도에 대한 불안을 결정 근거로 쓰지 않음.
+- "어렵다" 와 "불가능하다" 를 구분 — 어려우면 그냥 구현. 정말 불가능할 때만 그 사실을 중립적으로 보고("X 때문에 불가, 원인 Y")하고, 단순화·축소 여부는 사용자가 결정. "안 하자·우회하자" 식 추천 금지.
+    - 나쁜 예: "구현이 복잡해지니 이 기능은 빼거나 A 방식으로 우회하는 게 어떨까요?"
+    - 좋은 예: 복잡해도 정의대로 구현. 진짜 불가능하면 원인만 사실 보고.
 
 ## 불필요한 래핑·추상화 금지
 
-API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로 받으면 그대로 전달. "타입 안전"·"방어" 등을 명분으로 래핑·변환·간접층을 덧대지 말 것.
+API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로 받으면 그대로 전달. "타입 안전"·"방어" 등을 명분으로 래핑·변환·간접층을 덧대지 말 것 — 호출부 가독성을 해치고, 읽는 사람이 타입에 문제가 있나 의심하게 만듦.
 
-- 입력 타입이 단순 값을 허용하는데 래퍼로 감싸는 것 금지 — 호출부 가독성을 해치고, 읽는 사람이 타입에 문제가 있나 의심하게 만듦.
 - 래핑·변환은 타입이 래퍼만 받는 등 실제로 요구되는 자리에서만 사용.
 
 - 나쁜 예: 입력 타입이 `string | Wrapper<string>` 인데 항상 `wrap("재고", ...)` 로 감싸 전달.
@@ -42,14 +40,12 @@ API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로
 
 ## 라이브러리 우회 금지
 
-- 의존 라이브러리 동작에 이상이 있을 때 → 우회 코드 작성 전에 라이브러리 측 원인부터 먼저 조사.
-  - 라이브러리 버그·누락으로 판단될 시 → 사용자에게 보고 후 수정 방법 혹은 이슈 발행 제안.
-- 우회 코드 작성 금지:
-  - 불가피할 경우 사용자에게 보고 후 사용자 결정에 따름.
+- 의존 라이브러리 동작에 이상이 있으면, 우회 코드를 짜기 전에 라이브러리 측 원인부터 조사. 버그·누락으로 판단되면 사용자에게 보고 후 수정 방법 또는 이슈 발행을 제안.
+- 우회 코드는 작성하지 않음. 불가피하면 사용자에게 보고 후 그 결정에 따름.
 
 ## 에러 처리 시 throw 원칙
 
-문제 발생 시 throw:
+코드에서 예외·오류 상황을 만나면 throw:
 
 - silent skip 금지 — 예외를 잡은 후 대안 없이 진행하면 후속 프로세스가 결손된 채 동작함.
 - **자동 복구** (예: 의존성 미설치 → 설치·재시도 = 완전한 동작 회복) 는 silent skip 아님.
@@ -73,8 +69,11 @@ API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로
 
 사용자에게 노출되는 알림(로그·토스트·다이얼로그 등)의 심각도 분류 기준:
 
-- `error` (danger): 문제 발생. 예외를 잡았는지·무시했는지·재시도했는지 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당.
-- `warn`: 문제는 아니지만 사용자가 인지해야 할 중요한 알림.
-- `info`: 알면 좋은 일반 알림.
-- `success`: 정상 완료 알림.
+| 심각도          | 분류 기준                                                                                              |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `error`(danger) | 문제 발생. 예외를 잡았는지·무시했는지·재시도했는지 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당. |
+| `warn`          | 문제는 아니지만 사용자가 인지해야 할 중요한 알림.                                                      |
+| `info`          | 알면 좋은 일반 알림.                                                                                   |
+| `success`       | 정상 완료 알림.                                                                                        |
+
 - 안티패턴: 중단 없이 복구가 되었다는 이유로 `error` 대신 `warn` 을 선택 — 분류 기준 오용.