@simplysm/sd-claude 14.0.89 → 14.0.91

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

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

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

@@ -1,140 +1,135 @@
-# 앱 구조(AppStructure) 매뉴얼
-
-앱의 메뉴·권한·기능 모듈을 한 군데서 정의하는 방법. 메뉴 트리, 화면 접근 권한, 모듈별 on/off 가 모두 이 구조 하나에서 나옴. 새 화면을 메뉴에 올리거나 권한을 거는 작업 시 참조.
-
-## 1. 앱 구조 정의 위치
-
-common 패키지에 클라이언트별 `AppStructureItem[]` 상수를 두고, 앱 부트스트랩에서 `SdAppStructureProvider.initialize(items)` 로 연결함.
-
-```ts
-// common/src/app-structure-items.ts
-import type { AppStructureItem } from "@simplysm/service-common";
-import { tablerBox } from "@ng-icons/tabler-icons"; // 아이콘은 @ng-icons 의 SVG 문자열 상수
-
-export const adminAppStructureItems: AppStructureItem[] = [
-  /* ... */
-];
-```
-
-```ts
-// 앱 부트스트랩 (main.ts)
-provideAppInitializer(async () => {
-  const appService = inject(AppServiceProvider);
-  const sdAppStructure = inject(SdAppStructureProvider);
-
-  await appService.connectAsync();
-  sdAppStructure.initialize(adminAppStructureItems); // 동기 — await 불필요
-});
-```
-
-- 한 서버가 여러 앱(admin·pda 등)을 서비스해도, **클라이언트마다 자기 배열만** 정의해 import.
-- 서버에 등록하지 않음 — common 에서 클라이언트가 직접 import 함.
-
-## 2. 메뉴 추가
-
-배열에 항목을 추가하면 메뉴에 올라감. **그룹**(하위 메뉴를 묶음)과 **화면**(실제 라우팅 대상)으로 나뉨.
-
-```ts
-export const adminAppStructureItems: AppStructureItem[] = [
-  {
-    title: "재고관리", // 그룹: children 보유
-    code: "inventory",
-    icon: tablerBox,
-    children: [
-      { title: "품목별 재고", code: "goods-inventory", perms: ["use"] }, // 화면(leaf)
-      { title: "재고 실사", code: "stock-take", perms: ["use", "edit"] },
-    ],
-  },
-];
-```
-
-- `code` 는 부모부터 dot 으로 이어져 화면을 식별함 (위 예: `inventory.goods-inventory`). 라우팅 경로·권한 키가 모두 이 코드 기준.
-- 그룹은 `children` 만 두고 `perms`·`url` 을 두지 않음. 표시 가능한 자식이 하나도 없으면 그룹도 메뉴에서 자동으로 빠짐.
-- 외부 링크 화면은 `url` 지정.
-
-| 필드       | 위치      | 용도                                       |
-| ---------- | --------- | ------------------------------------------ |
-| `title`    | 그룹·화면 | 메뉴에 표시할 이름                         |
-| `code`     | 그룹·화면 | 항목 코드 (부모와 dot 으로 이어 화면 식별) |
-| `icon`     | 그룹·화면 | 메뉴 아이콘                                |
-| `children` | 그룹      | 하위 항목 배열                             |
-| `url`      | 화면      | 외부 링크 등 이동 경로                     |
-
-## 3. 메뉴에 안 띄우고 화면만 두기
-
-라우팅·내부 이동용이라 사이드 메뉴에는 노출하고 싶지 않은 화면은 `isNotMenu: true`.
-
-```ts
-export const adminAppStructureItems: AppStructureItem[] = [
-  { title: "메인메뉴", code: "main", isNotMenu: true }, // 홈/메인 화면
-  { title: "내 정보 수정", code: "my-info", isNotMenu: true }, // 사용자 본인 정보 화면
-
-  { title: "재고관리", code: "inventory", children: [ /* ... */ ] }, // 이하 실제 메뉴 그룹
-];
-```
-
-- 메뉴에서만 숨고, 화면(라우팅 대상) 자체는 그대로 존재함.
-- 홈(`main`)·내 정보 수정처럼 메뉴를 거치지 않고 직접 진입하는 화면은 배열 **맨 앞**에 root-level leaf(그룹·`children` 없이)로 모아두는 게 관례. 권한을 걸지 않으므로 `perms` 도 두지 않음.
-
-## 4. 권한으로 접근 제한
-
-권한을 걸려면 화면에 `perms` 를 정의함. 그러면 ① 권한 관리 페이지에 체크 항목으로 나오고 ② 권한 없는 사용자에게는 메뉴가 자동으로 숨겨지고 ③ 화면 안에서 권한 보유 여부를 체크할 수 있음.
-
-```ts
-{
-  title: "입고지시",
-  code: "inbound-instruction",
-  perms: ["use", "edit"],
-  subPerms: [
-    { code: "document", title: "문서작업", perms: ["edit"] }, // 화면 내 세부 권한
-  ],
-},
-```
-
-- `perms`: 부여할 권한 종류. `"use"`(조회) / `"edit"`(편집). `perms` 를 지정한 화면만 권한 페이지·권한 체크 대상이 됨.
-- `subPerms`: 한 화면 안의 세부 기능 권한.
-
-**권한을 사용자에게 부여** — 권한 관리 화면은 `getPermissionsByStructure(items)` 결과를 `<sd-permission-table>` 에 넘김. 저장한 결과는 사용자별 권한 레코드로 서버에 저장됨.
-
-```ts
-permissions = computed(() =>
-  this._sdAppStructure.getPermissionsByStructure(this._sdAppStructure.items()),
-);
-// template: <sd-permission-table [items]="permissions()" [(value)]="data" />
-```
-
-**로그인 시 권한 연결** — 인증 후 사용자의 권한 레코드를 `permRecord` 에 set 하면 메뉴 필터·권한 체크에 반영됨.
-
-```ts
-this._sdAppStructure.permRecord.set(this.authInfo()!.user.permissionRecord);
-```
-
-**화면 안에서 권한 체크** — `injectPermsSignal` 로 현재 사용자의 활성 권한을 읽음.
-
-```ts
-perms = injectPermsSignal(["base.user-permission"], ["use", "edit"]);
-canEdit = computed(() => this.perms().includes("edit"));
-// → 권한 없으면 빈 배열. 예: ["use"]
-```
-
-- 첫 인자는 화면의 fullCode(들), 둘째 인자는 확인할 권한 종류.
-- `perms` 를 정의하지 않은 화면은 제약이 없으므로 항상 모든 권한이 활성으로 나옴.
-
-## 5. 기능 모듈로 메뉴 on/off
-
-계약·라이선스 등으로 앱마다 켜고 끄는 기능 묶음이 있으면 `modules`/`requiredModules` 로 조건을 걸고, 앱에서 활성 모듈을 `usableModules` 에 set 함.
-
-```ts
-{ title: "스케쥴링", code: "scheduling", modules: ["scheduling"], children: [ /* ... */ ] },
-{ title: "고급분석", code: "advanced", requiredModules: ["analytics", "pro"] },
-```
-
-```ts
-// 앱 초기화 시 활성 모듈 지정
-this._sdAppStructure.usableModules.set(["scheduling"]);
-```
-
-- `modules`: 나열한 모듈 중 **하나라도** 활성이면 표시(OR).
-- `requiredModules`: 나열한 모듈이 **모두** 활성이어야 표시(AND).
-- 조건을 건 항목은 해당 모듈이 `usableModules` 에 없으면 메뉴·권한에서 빠짐. 조건이 없는 항목은 모듈 설정과 무관하게 표시됨.
-- 모듈 기능을 쓰지 않는 앱은 `usableModules.set([])` 로 둠.
+# 앱 구조(AppStructure) 매뉴얼
+
+앱의 메뉴·권한·기능 모듈을 한 군데서 정의하는 방법. 메뉴 트리, 화면 접근 권한, 모듈별 on/off 가 모두 이 구조 하나에서 나옴. 새 화면을 메뉴에 올리거나 권한을 거는 작업 시 참조.
+
+## 1. 앱 구조 정의 위치
+
+common 패키지에 클라이언트별 `AppStructureItem[]` 상수를 두고, 앱 부트스트랩에서 `SdAppStructureProvider.initialize(items)` 로 연결함.
+
+```ts
+// common/src/app-structure-items.ts
+import type { AppStructureItem } from "@simplysm/service-common";
+import { tablerBox } from "@ng-icons/tabler-icons"; // 아이콘은 @ng-icons 의 SVG 문자열 상수
+
+export const adminAppStructureItems: AppStructureItem[] = [
+  /* ... */
+];
+```
+
+```ts
+// 앱 부트스트랩 (main.ts)
+provideAppInitializer(() => {
+  inject(SdAppStructureProvider).initialize(adminAppStructureItems);
+});
+```
+
+- 한 서버가 여러 앱(admin·pda 등)을 서비스해도, **클라이언트마다 자기 배열만** 정의해 import.
+- 서버에 등록하지 않음 — common 에서 클라이언트가 직접 import 함.
+
+## 2. 메뉴 추가
+
+배열에 항목을 추가하면 메뉴에 올라감. **그룹**(하위 메뉴를 묶음)과 **화면**(실제 라우팅 대상)으로 나뉨.
+
+```ts
+export const adminAppStructureItems: AppStructureItem[] = [
+  {
+    title: "재고관리", // 그룹: children 보유
+    code: "inventory",
+    icon: tablerBox,
+    children: [
+      { title: "품목별 재고", code: "goods-inventory", perms: ["use"] }, // 화면(leaf)
+      { title: "재고 실사", code: "stock-take", perms: ["use", "edit"] },
+    ],
+  },
+];
+```
+
+- `code` 는 부모부터 dot 으로 이어져 화면을 식별함 (위 예: `inventory.goods-inventory`). 라우팅 경로·권한 키가 모두 이 코드 기준.
+- 그룹은 `children` 만 두고 `perms`·`url` 을 두지 않음. 표시 가능한 자식이 하나도 없으면 그룹도 메뉴에서 자동으로 빠짐.
+- 외부 링크 화면은 `url` 지정.
+
+| 필드       | 위치      | 용도                                       |
+| ---------- | --------- | ------------------------------------------ |
+| `title`    | 그룹·화면 | 메뉴에 표시할 이름                         |
+| `code`     | 그룹·화면 | 항목 코드 (부모와 dot 으로 이어 화면 식별) |
+| `icon`     | 그룹·화면 | 메뉴 아이콘                                |
+| `children` | 그룹      | 하위 항목 배열                             |
+| `url`      | 화면      | 외부 링크 등 이동 경로                     |
+
+## 3. 메뉴에 안 띄우고 화면만 두기
+
+라우팅·내부 이동용이라 사이드 메뉴에는 노출하고 싶지 않은 화면은 `isNotMenu: true`.
+
+```ts
+export const adminAppStructureItems: AppStructureItem[] = [
+  { title: "메인메뉴", code: "main", isNotMenu: true }, // 홈/메인 화면
+  { title: "내 정보 수정", code: "my-info", isNotMenu: true }, // 사용자 본인 정보 화면
+
+  {
+    title: "재고관리",
+    code: "inventory",
+    children: [
+      /* ... */
+    ],
+  }, // 이하 실제 메뉴 그룹
+];
+```
+
+- 메뉴에서만 숨고, 화면(라우팅 대상) 자체는 그대로 존재함.
+- 홈(`main`)·내 정보 수정처럼 메뉴를 거치지 않고 직접 진입하는 화면은 배열 **맨 앞**에 root-level leaf(그룹·`children` 없이)로 모아두는 게 관례. 권한을 걸지 않으므로 `perms` 도 두지 않음.
+
+## 4. 권한으로 접근 제한
+
+권한을 걸려면 화면에 `perms` 를 정의함. 그러면 ① 권한 관리 페이지에 체크 항목으로 나오고 ② 권한 없는 사용자에게는 메뉴가 자동으로 숨겨지고 ③ 화면 안에서 권한 보유 여부를 체크할 수 있음.
+
+```ts
+{
+  title: "입고지시",
+  code: "inbound-instruction",
+  perms: ["use", "edit"],
+  subPerms: [
+    { code: "document", title: "문서작업", perms: ["edit"] }, // 화면 내 세부 권한
+  ],
+},
+```
+
+- `perms`: 부여할 권한 종류. `"use"`(조회) / `"edit"`(편집). `perms` 를 지정한 화면만 권한 페이지·권한 체크 대상이 됨.
+- `subPerms`: 한 화면 안의 세부 기능 권한.
+
+**권한을 사용자에게 부여** — 권한 관리 화면은 `getPermissionsByStructure(items)` 결과를 `<sd-permission-table>` 에 넘김. 저장한 결과는 사용자별 권한 레코드로 서버에 저장됨.
+
+```ts
+permissions = computed(() =>
+  this._sdAppStructure.getPermissionsByStructure(this._sdAppStructure.items()),
+);
+// template: <sd-permission-table [items]="permissions()" [(value)]="data" />
+```
+
+**로그인 시 권한 연결** — 인증 후 사용자의 권한 레코드를 `permRecord` 에 set 하면 메뉴 필터·권한 체크에 반영됨.
+
+```ts
+this._sdAppStructure.permRecord.set(this.authInfo()!.user.permissionRecord);
+```
+
+**화면 안에서 권한 체크** — 화면 컴포넌트에서 `injectPermsSignal(<path>, <actions>)` 로 정의된 권한을 읽어 체크함. 첫 인자(권한 path)는 이 구조의 화면 fullCode(들). 체크 작성 관례(단순 체크는 인라인, `computed` 사용 기준)는 [client-component.md](./client-component.md) 의 '권한' 참조.
+
+- `perms` 를 정의하지 않은 화면은 제약이 없으므로 항상 모든 권한이 활성으로 나옴.
+
+## 5. 기능 모듈로 메뉴 on/off
+
+계약·라이선스 등으로 앱마다 켜고 끄는 기능 묶음이 있으면 `modules`/`requiredModules` 로 조건을 걸고, 앱에서 활성 모듈을 `usableModules` 에 set 함.
+
+```ts
+{ title: "스케쥴링", code: "scheduling", modules: ["scheduling"], children: [ /* ... */ ] },
+{ title: "고급분석", code: "advanced", requiredModules: ["analytics", "pro"] },
+```
+
+```ts
+// 앱 초기화 시 활성 모듈 지정
+this._sdAppStructure.usableModules.set(["scheduling"]);
+```
+
+- `modules`: 나열한 모듈 중 **하나라도** 활성이면 표시(OR).
+- `requiredModules`: 나열한 모듈이 **모두** 활성이어야 표시(AND).
+- 조건을 건 항목은 해당 모듈이 `usableModules` 에 없으면 메뉴·권한에서 빠짐. 조건이 없는 항목은 모듈 설정과 무관하게 표시됨.
+- 모듈 기능을 쓰지 않는 앱은 `usableModules.set([])` 로 둠.

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

@@ -19,7 +19,7 @@ export class AppOrmProvider {
       {
         DbClass: MainDbContext,
         connOpt: { configName: "MAIN" },
-        dbContextOpt: { database: "...", schema: "dbo" },
+        dbContextOpt: { database: "..." },
       },
       callback,
     );

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

@@ -16,22 +16,21 @@ ORM 사용은 [client-orm.md](./client-orm.md), 이벤트 정의·발생 메커
 export class AppServiceProvider {
   private readonly _sdServiceClientFactory = inject(SdServiceClientFactoryProvider);
 
-  private _orm?: OrmClientConnector;
-  private _user?: ServiceProxy<UserServiceMethods>;
-  private _authInfoEvent?: ClientEventProxy<typeof AuthInfoEvent>;
-
   get client() {
     return this._sdServiceClientFactory.get("MAIN");
   }
 
+  private _orm?: OrmClientConnector;
   get orm(): OrmClientConnector {
     return (this._orm ??= createOrmClientConnector(this.client));
   }
 
+  private _user?: ServiceProxy<UserServiceMethods>;
   get user(): ServiceProxy<UserServiceMethods> {
     return (this._user ??= this.client.getService<UserServiceMethods>("User"));
   }
 
+  private _authInfoEvent?: ClientEventProxy<typeof AuthInfoEvent>;
   get authInfoEvent(): ClientEventProxy<typeof AuthInfoEvent> {
     return (this._authInfoEvent ??= this.client.getEvent(AuthInfoEvent));
   }
@@ -49,6 +48,19 @@ export class AppServiceProvider {
 - `orm` getter — `createOrmClientConnector(this.client)` 결과. DB 설정을 얹는 `AppOrmProvider` 가 이 위에 올라감 ([client-orm.md](./client-orm.md)).
 - `connectAsync()` — 앱 부트스트랩 시점에 서버 연결 수행. `addListener` 등 통신은 이 호출 이후에만 가능.
 
+## 부트스트랩에서 서버에 연결하려면
+
+`provideAppInitializer` 안에서 `AppServiceProvider.connectAsync()` 를 호출하고 그 Promise 를 반환. Angular 가 이 Promise 를 기다린 뒤 앱을 띄우므로, 화면·프로바이더가 통신을 시작하는 시점에는 연결이 이미 끝나 있음.
+
+```ts
+// 앱 부트스트랩 (main.ts)
+provideAppInitializer(async () => {
+  await inject(AppServiceProvider).connectAsync();
+});
+```
+
+- `connectAsync()` 의 Promise 를 **반환**해야 Angular 가 연결 완료까지 부트스트랩을 대기. 반환을 빠뜨리면 연결 전에 화면이 떠 통신 호출이 실패함.
+
 ## 새 서비스 호출을 추가하려면
 
 `client.getService<XxxServiceMethods>("XxxName")` 결과를 캐시 필드 + getter 로 노출.
@@ -56,7 +68,7 @@ export class AppServiceProvider {
 ```ts
 @Injectable({ providedIn: "root" })
 export class AppServiceProvider {
-  // ... 기존 필드 ...
+  // ... 기존 멤버 ...
   private _order?: ServiceProxy<OrderServiceMethods>;
 
   get order(): ServiceProxy<OrderServiceMethods> {
@@ -76,7 +88,7 @@ export class AppServiceProvider {
 ```ts
 @Injectable({ providedIn: "root" })
 export class AppServiceProvider {
-  // ... 기존 필드 ...
+  // ... 기존 멤버 ...
   private _orderStatusChangedEvent?: ClientEventProxy<typeof OrderStatusChangedEvent>;
 
   get orderStatusChangedEvent(): ClientEventProxy<typeof OrderStatusChangedEvent> {
@@ -91,6 +103,6 @@ export class AppServiceProvider {
 
 ## 지킬 것
 
-- 캐시 필드는 `private _xxx?`, 노출은 getter, 초기화는 `??=` — 항목마다 동일 패턴 유지.
+- 캐시 필드(`private _xxx?`)와 getter(`??=`)를 항목별로 인접 배치하고, 항목마다 동일 패턴 유지.
 - 서비스 이름·이벤트 정의 객체는 단일 소스(server `defineService` 이름 / 공통 `defineEvent` 객체)를 그대로 따름. 호출부에서 문자열·제네릭을 중복으로 적지 않음.
 - `connectAsync()` 이전에는 통신 호출 불가 — 부트스트랩 순서 준수.

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

@@ -34,7 +34,7 @@ export class AppSharedDataProvider extends SdSharedDataProvider<TAppSharedData>
             isDisabled: item.isDisabled,
 
             __valueKey: item.id,
-            __searchText: expr.concat(item.code, "|_|", item.name),
+            __searchText: expr.concat(item.code, "|", item.name),
             __isHidden: item.isDisabled,
           }));
 
@@ -85,7 +85,7 @@ this.register("품목", {
         isDisabled: item.isDisabled,
 
         __valueKey: item.id,
-        __searchText: expr.concat(item.code, "|_|", item.name),
+        __searchText: expr.concat(item.code, "|", item.name),
         __isHidden: item.isDisabled,
       }));
 

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

@@ -36,21 +36,33 @@ export const SystemLog = Table("SystemLog")
 
 ## 부트스트랩에서 외부 적재를 배선하려면
 
-`provideAppInitializer` 안에서 `SdSystemLogProvider.writeFn` 에 적재 함수를 할당. 트랜잭션이 필요 없는 단순 insert 이므로 `connectWithoutTransAsync` 를 사용.
+`provideAppInitializer` 안에서 `SdSystemLogProvider.writeFn` 에 적재 함수를 할당.
 
 ```ts
+import { inject, provideAppInitializer } from "@angular/core";
+import { DateTime, json } from "@simplysm/core-common";
+import { SdSystemLogProvider } from "@simplysm/angular";
+
 provideAppInitializer(() => {
   const appService = inject(AppServiceProvider);
   const appOrm = inject(AppOrmProvider);
   const appAuth = inject(AppAuthProvider);
 
   inject(SdSystemLogProvider).writeFn = async (severity, ...data) => {
-    await appOrm.connectWithoutTransAsync(async (db) => {
+    await appOrm.connectAsync(async (db) => {
       await db.systemLog().insert([
         {
           dateTime: new DateTime(),
           severity,
-          message: JSON.stringify(data),
+          message: data
+            .map((l) =>
+              typeof l === "string"
+                ? l
+                : l instanceof Error
+                  ? (l.stack ?? l.message)
+                  : json.stringify(l, { space: 2 }),
+            )
+            .join(" "),
           clientName: CLIENT_NAME,
           employeeId: appAuth.authInfo()?.employeeId,
         },
@@ -63,7 +75,7 @@ provideAppInitializer(() => {
 ```
 
 - `CLIENT_NAME` 은 `provideSdAngular({ clientName: CLIENT_NAME })` 에 넘긴 값과 동일하게 두어 어느 앱에서 난 로그인지 구분.
-- `data` 는 가변 인자 배열이므로 `JSON.stringify(data)` 로 통째로 저장.
+- `data` 는 가변 인자 배열. 각 인자를 string→그대로 / Error→`stack` / 객체→`json.stringify` 로 문자열화해 공백으로 join 하여 저장(Error 의 `stack` 보존).
 - `writeFn` 미설정 시 외부 적재는 일어나지 않고 콘솔 출력만 수행됨. DB 적재가 필요한 앱에서만 배선.
 
 ## 자동으로 적재되는 로그

package/claude/references/sd-simplysm14/manuals/data-log.md

@@ -137,7 +137,6 @@ Queryable.prototype.joinLastDataLog = function (this: Queryable<any, any>, opts)
 
 ```ts
 // main.db-context.ts
-import "./system-data-log.ext"; // side-effect: Queryable.prototype 확장 로드 보장
 // ...
 export class MainDbContext extends DbContext {
   role = this.queryable(Role);

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

@@ -61,6 +61,22 @@ WHERE 와 SELECT 양쪽에서 동일 도출 산식을 쓰겠다고 `buildDerived
 
 "Layer 1 = materialize, Layer 2 = derive" 같은 다층 wrap 구조도 군더더기. 단일 select 안에서 로컬 `const` 로 산식을 분리하면 동일한 SQL 이 생성됨.
 
+### 불필요한 `expr.val` 사용 금지
+
+`where` 비교·`update`/`upsert`/`insert` 값은 `ExprInput`(= `ExprUnit | T`) 자리라 리터럴을 그대로 넘김 — `expr.val` 로 감싸지 말 것.
+
+```ts
+// 나쁜 예 — 불필요한 래핑
+.update((u) => ({ name: expr.val("string", "새이름") }))
+.where((u) => [expr.eq(u.status, expr.val("string", "active"))])
+
+// 좋은 예 — 리터럴 직접 전달
+.update((u) => ({ name: "새이름" }))
+.where((u) => [expr.eq(u.status, "active")])
+```
+
+`expr.val` 은 `select` 콜백에서 리터럴 상수 컬럼을 만들 때처럼 `ExprUnit` 이 요구되는 자리에서만 사용.
+
 ## 스키마 정의
 
 컬럼은 `NOT NULL` 기본. `.nullable()` / `.default(...)` 는 도메인 근거가 있을 때만 사용.

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

@@ -13,6 +13,16 @@ Claude 에이전트가 코드 작성·설계·변경 시 따라야 할 행동
 - 명시된 정의 자체를 임의로 단순화하여 처리 금지:
   - 정확한 구현 부담이 크면 단순화안을 사용자에게 보고 후 사용자 합의에 따름.
 
+## 불필요한 래핑·추상화 금지
+
+API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로 받으면 그대로 전달. "타입 안전"·"방어" 등을 명분으로 래핑·변환·간접층을 덧대지 말 것.
+
+- 입력 타입이 단순 값을 허용하는데 래퍼로 감싸는 것 금지 — 호출부 가독성을 해치고, 읽는 사람이 타입에 문제가 있나 의심하게 만듦.
+- 래핑·변환은 타입이 래퍼만 받는 등 실제로 요구되는 자리에서만 사용.
+
+- 나쁜 예: 입력 타입이 `string | Wrapper<string>` 인데 항상 `wrap("재고", ...)` 로 감싸 전달.
+- 좋은 예: `"재고"` 를 그대로 전달, 래퍼만 받는 자리에서만 `wrap(...)` 사용.
+
 ## 결측(null/undefined) 보존
 
 데이터가 "값 없음"(null/undefined)을 가질 수 있으면, 그 결측을 타입·계산·출력 전 계층에서 그대로 전파. 결측을 임의 값으로 치환하거나 타입에서 비결측으로 숨기지 말 것.

package/claude/skills/sd-demo/SKILL.md

@@ -30,12 +30,6 @@ spec.md 의 화면 1개를 클라이언트 패키지의 화면 컴포넌트 자
 
 **충돌 확인**: 대상 화면(또는 동반 모달 화면) 의 파일이 이미 존재하면 묻기 — ① 덮어쓰기 / ② spec 변경분만 보강 / ③ 취소. 호출자 발화에 명시된 분기가 있으면 묻지 않고 그 분기로 진행.
 
-**마커 점검**: 대상 화면(또는 동반 모달 화면) 의 헤더 마커 확인.
-
-- 헤더 미확정(마커 없음) / `[확정: 날짜]` → 본문에 와이어프레임·항목 초안이 있으면 그대로 진행 (미확정은 미검토 초안이지만 데모가 그 검토를 돕는 시각화이므로 정상).
-- 단 미확정 섹션의 본문이 와이어프레임·항목 없이 분석 방법뿐이면 → 시각화할 내용 없음. 사용자에게 보고하고 중단 (sd-spec 으로 해당 화면을 먼저 채우도록 안내).
-- 본문 인라인 `[OPEN]` 항목 → 4단계의 더미 마커로 placeholder 처리.
-
 ### 2단계: 대상 화면 항목 분석
 
 spec.md 의 대상 화면 항목에서 다음을 추출: