@simplysm/sd-claude 14.0.84 → 14.0.86

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

@@ -30,10 +30,16 @@ 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)               |
-| 새 앱 부트스트랩 또는 새 서비스·마스터 데이터 추가      | [client-setup.md](./manuals/client-setup.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) |
+| 클라이언트·서버 간 실시간 이벤트 정의·발생·구독         | [event.md](./manuals/event.md)                         |
+| 앱 메뉴 구조·권한 정의 추가/수정                        | [client-app-structure.md](./manuals/client-app-structure.md) |
 | DB 스키마 정의 또는 ORM 쿼리 작성                       | [orm.md](./manuals/orm.md)                             |
 | 이종 엔티티를 한 목록으로 합쳐 표시 (UNION)             | [orm-union.md](./manuals/orm-union.md)                 |
+| CRUD 처리에 데이터 변경 이력 적재·조회 (누가·언제·무엇을 변경) | [data-log.md](./manuals/data-log.md)                   |
 | 콘솔 로깅 코드 작성/수정 (모든 패키지)                  | [logging.md](./manuals/logging.md)                     |
+| 클라이언트 시스템 에러·로그를 DB 등 외부에 적재·조회    | [client-system-log.md](./manuals/client-system-log.md) |
 | 패키지 테스트·통합 테스트 작성/추가                     | [test.md](./manuals/test.md)                           |
 
 ## 패키지 인덱스

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

@@ -0,0 +1,140 @@
+# 앱 구조(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([])` 로 둠.

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

@@ -245,7 +245,7 @@ if (!result) return;
 // result 처리
 ```
 
-- **`type`** — `SdModal` 을 구현(상속) 한 컴포넌트 클래스.
+- **`type`** — `SdModalContentDef<O>` 를 구현한 컴포넌트 클래스 (`initialized` 시그널 + `close` output 보유. `O` 는 close 페이로드 타입). `SdModal` 은 라이브러리 모달 셸 컴포넌트이므로 상속 대상이 아님.
 - **`title`** — 모달 헤더 제목.
 - **`inputs`** — 모달 컴포넌트가 받을 input 시그널 값. 없으면 `{}`.
 - **반환값** — 모달 컴포넌트가 close 시 emit 한 페이로드. 사용자가 닫기(X)·취소로 닫으면 `undefined`.
@@ -629,10 +629,11 @@ label 과 입력 그룹을 묶는 전용 클래스 3종:
 private readonly _appService = inject(AppServiceProvider);
 
 await this._appService.user.someMethod(...);
-this._appService.authInfoEvent.subscribe(...);
+
+const listenerKey = await this._appService.authInfoEvent.addListener(info, async (data) => { ... });
 ```
 
-Provider 정의·서비스 추가 컨벤션은 [client-setup.md#appserviceprovider](./client-setup.md#appserviceprovider) 참조.
+Provider 정의·서비스·이벤트 호출 추가 컨벤션은 [client-service.md](./client-service.md) 참조.
 
 ## ORM 호출 (`AppOrmProvider`)
 
@@ -645,7 +646,7 @@ await this._appOrm.connectAsync(async (db) => {
 ```
 
 - 기본은 `connectAsync` (트랜잭션). `connectWithoutTransAsync` 는 트랜잭션 안에서 동작하지 않는 작업용 헬퍼.
-- 쿼리 작성법은 [orm.md](./orm.md), Provider 정의 컨벤션은 [client-setup.md#appormprovider](./client-setup.md#appormprovider) 참조.
+- 쿼리 작성법은 [orm.md](./orm.md), Provider 정의 컨벤션은 [client-orm.md](./client-orm.md) 참조.
 
 ## 공유 데이터 (`useSharedSignal`)
 
@@ -662,7 +663,7 @@ sharedCustomers = useSharedSignal("고객사");
 <sd-shared-data-select [items]="sharedCustomers.items()" [(value)]="data().customerId" ... />
 ```
 
-새 마스터 데이터 등록·Provider 정의 컨벤션은 [client-setup.md#appshareddataprovider](./client-setup.md#appshareddataprovider) 참조.
+Provider 정의·새 마스터 데이터 등록 컨벤션은 [client-shared-data.md](./client-shared-data.md) 참조.
 
 ## 레이아웃·유틸 클래스
 

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

@@ -0,0 +1,62 @@
+# 앱에서 ORM(DB) 사용 매뉴얼
+
+앱에서 ORM(Object-Relational Mapping) 으로 DB(데이터베이스)에 접근하려면 `AppOrmProvider` 가 필요. `AppServiceProvider.orm` 위에 앱별 DB 설정(DbContext·데이터베이스명·스키마명)을 고정해 둔 root provider 로, 화면·프로바이더는 DB 옵션을 매번 적지 않고 `connectAsync` 한 번으로 쿼리를 실행.
+
+- 전제: `AppServiceProvider` 가 먼저 있어야 함 ([client-service.md](./client-service.md) — `orm` getter 가 이 provider 의 기반).
+- 쿼리 작성법(스키마 정의·`Queryable` 체이닝·`expr`)은 [orm.md](./orm.md) 참조.
+
+## AppOrmProvider 를 정의하려면 (새 앱 1회성)
+
+앱의 DbContext·DB명·스키마를 한 곳에 고정하고, 트랜잭션 유무별 진입 메서드를 제공.
+
+```ts
+@Injectable({ providedIn: "root" })
+export class AppOrmProvider {
+  private readonly _appService = inject(AppServiceProvider);
+
+  connectAsync<R>(callback: (db: MainDbContext) => Promise<R>): Promise<R> {
+    return this._appService.orm.connect(
+      {
+        DbClass: MainDbContext,
+        connOpt: { configName: "MAIN" },
+        dbContextOpt: { database: "...", schema: "dbo" },
+      },
+      callback,
+    );
+  }
+
+  connectWithoutTransAsync<R>(callback: (db: MainDbContext) => Promise<R>): Promise<R> {
+    return this._appService.orm.connectWithoutTransaction(
+      { /* 같은 옵션 */ },
+      callback,
+    );
+  }
+}
+```
+
+**약속**:
+
+- `@Injectable({ providedIn: "root" })`.
+- DbContext 는 앱별로 정의 (예: `@adtek/db-main` 의 `MainDbContext`). 스키마 정의는 [orm.md](./orm.md).
+- 기본 메서드는 `connectAsync` (트랜잭션 포함). `connectWithoutTransAsync` 는 initialize 등 트랜잭션 안에서 동작하지 않는 작업 전용 헬퍼.
+- 콜백의 반환값이 그대로 메서드의 반환값이 됨.
+
+## 화면·프로바이더에서 쿼리를 실행하려면
+
+`AppOrmProvider` 를 inject 하고 `connectAsync` 콜백 안에서 쿼리.
+
+```ts
+private readonly _appOrm = inject(AppOrmProvider);
+
+const rows = await this._appOrm.connectAsync(async (db) => {
+  return db.order().select((item) => ({ id: item.id, status: item.status })).execute();
+});
+```
+
+- 콜백 인자 `db` 는 `MainDbContext`. 테이블·뷰 빌더와 쿼리 작성은 [orm.md](./orm.md).
+- 트랜잭션이 곤란한 작업(initialize 등)만 `connectWithoutTransAsync` 사용.
+
+## 지킬 것
+
+- DB 옵션(`DbClass`·`connOpt`·`dbContextOpt`)은 `AppOrmProvider` 한 곳에만 두고, 화면·프로바이더는 `connectAsync`/`connectWithoutTransAsync` 만 호출. 옵션을 호출부에 흩뿌리지 않음.
+- 기본은 `connectAsync`. 트랜잭션 없이 돌려야 하는 명확한 이유가 있을 때만 `connectWithoutTransAsync`.

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

@@ -0,0 +1,96 @@
+# 앱에서 서버 서비스·이벤트 호출 매뉴얼
+
+앱이 서버와 통신(서비스 RPC 호출·실시간 이벤트 구독)하려면 `AppServiceProvider` 가 필요. `@simplysm/service-client` 위에 앱이 만드는 root provider 로, 서버 연결·서비스 프록시·이벤트 프록시·ORM 커넥터의 공통 진입점.
+
+- 새 앱이라 provider 자체가 없으면 → 아래 "AppServiceProvider 를 정의하려면".
+- provider 는 이미 있고 서비스·이벤트만 더할 때 → "새 서비스 호출을 추가하려면" / "새 이벤트 프록시를 추가하려면".
+
+ORM 사용은 [client-orm.md](./client-orm.md), 이벤트 정의·발생 메커니즘은 [event.md](./event.md) 참조.
+
+## AppServiceProvider 를 정의하려면 (새 앱 1회성)
+
+서버 연결·서비스·이벤트·ORM 진입점을 한 root provider 에 모음. 서비스·이벤트는 `private _xxx?` 캐시 필드 + getter 로 lazy 노출(`??=`).
+
+```ts
+@Injectable({ providedIn: "root" })
+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");
+  }
+
+  get orm(): OrmClientConnector {
+    return (this._orm ??= createOrmClientConnector(this.client));
+  }
+
+  get user(): ServiceProxy<UserServiceMethods> {
+    return (this._user ??= this.client.getService<UserServiceMethods>("User"));
+  }
+
+  get authInfoEvent(): ClientEventProxy<typeof AuthInfoEvent> {
+    return (this._authInfoEvent ??= this.client.getEvent(AuthInfoEvent));
+  }
+
+  async connectAsync() {
+    await this._sdServiceClientFactory.connectAsync("MAIN");
+  }
+}
+```
+
+**약속**:
+
+- `@Injectable({ providedIn: "root" })`.
+- `client` getter — `SdServiceClientFactoryProvider.get("MAIN")` 결과. 서비스·이벤트·ORM 의 공통 진입점.
+- `orm` getter — `createOrmClientConnector(this.client)` 결과. DB 설정을 얹는 `AppOrmProvider` 가 이 위에 올라감 ([client-orm.md](./client-orm.md)).
+- `connectAsync()` — 앱 부트스트랩 시점에 서버 연결 수행. `addListener` 등 통신은 이 호출 이후에만 가능.
+
+## 새 서비스 호출을 추가하려면
+
+`client.getService<XxxServiceMethods>("XxxName")` 결과를 캐시 필드 + getter 로 노출.
+
+```ts
+@Injectable({ providedIn: "root" })
+export class AppServiceProvider {
+  // ... 기존 필드 ...
+  private _order?: ServiceProxy<OrderServiceMethods>;
+
+  get order(): ServiceProxy<OrderServiceMethods> {
+    return (this._order ??= this.client.getService<OrderServiceMethods>("Order"));
+  }
+}
+```
+
+- 타입 `XxxServiceMethods` 는 server 패키지가 export 한 `ServiceMethods<typeof XxxService>`.
+- 첫 인자 `"XxxName"` 은 server 의 `defineService("XxxName", ...)` 이름과 일치해야 함.
+- 호출: `await this._appService.order.ship(orderId)`.
+
+## 새 이벤트 프록시를 추가하려면
+
+`client.getEvent(XxxEvent)` 결과를 캐시 필드 + getter 로 노출. `appService.client.getEvent(...)` 를 매번 적는 대신 `appService.xxxEvent` 로 짧게 씀.
+
+```ts
+@Injectable({ providedIn: "root" })
+export class AppServiceProvider {
+  // ... 기존 필드 ...
+  private _orderStatusChangedEvent?: ClientEventProxy<typeof OrderStatusChangedEvent>;
+
+  get orderStatusChangedEvent(): ClientEventProxy<typeof OrderStatusChangedEvent> {
+    return (this._orderStatusChangedEvent ??= this.client.getEvent(OrderStatusChangedEvent));
+  }
+}
+```
+
+- `XxxEvent` 는 공통 패키지가 `defineEvent(...)` 로 export 한 정의 객체 — 이름·타입이 객체에서 추론됨. 문자열 이름이나 `<typeof X>` 를 따로 적지 않음.
+- 구독: `const key = await this._appService.orderStatusChangedEvent.addListener(info, cb)`.
+- 이벤트 정의·발생·구독 메커니즘 전반은 [event.md](./event.md) 참조.
+
+## 지킬 것
+
+- 캐시 필드는 `private _xxx?`, 노출은 getter, 초기화는 `??=` — 항목마다 동일 패턴 유지.
+- 서비스 이름·이벤트 정의 객체는 단일 소스(server `defineService` 이름 / 공통 `defineEvent` 객체)를 그대로 따름. 호출부에서 문자열·제네릭을 중복으로 적지 않음.
+- `connectAsync()` 이전에는 통신 호출 불가 — 부트스트랩 순서 준수.

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

@@ -0,0 +1,146 @@
+# 앱에서 공유 마스터 데이터 사용 매뉴얼
+
+화면에서 자주 참조하는 마스터 데이터(고객사·품목·로케이션 등)를 공유 시그널로 쓰려면 `AppSharedDataProvider` 가 필요. `@simplysm/angular` 의 `SdSharedDataProvider` 를 상속해, 한 번 등록해 두면 어느 화면에서든 `useSharedSignal("<이름>")` 로 동일 데이터를 공유.
+
+- 새 앱이라 provider 자체가 없으면 → "AppSharedDataProvider 를 정의하려면".
+- provider 는 있고 데이터 항목만 더할 때 → "마스터 데이터 항목을 추가하려면".
+- 전제: getter 가 DB 를 조회하므로 `AppOrmProvider` 가 먼저 있어야 함 ([client-orm.md](./client-orm.md)).
+
+## AppSharedDataProvider 를 정의하려면 (새 앱 1회성)
+
+`SdSharedDataProvider<TAppSharedData>` 를 상속하고, `useSharedSignal` 헬퍼를 함께 export. `initialize()` 안에서 항목을 `register`.
+
+```ts
+export function useSharedSignal<K extends keyof TAppSharedData>(
+  name: K,
+): SharedDataHandle<TAppSharedData[K]> {
+  const appSharedData = inject(AppSharedDataProvider);
+  return appSharedData.getHandle(name);
+}
+
+@Injectable({ providedIn: "root" })
+export class AppSharedDataProvider extends SdSharedDataProvider<TAppSharedData> {
+  private readonly _appOrm = inject(AppOrmProvider);
+
+  override initialize() {
+    this.register("고객사", {
+      serviceKey: "MAIN",
+      getter: async (changeKeys) => {
+        return this._appOrm.connectAsync(async (db) => {
+          let qr = db.customer().select((item) => ({
+            id: item.id,
+            code: item.code,
+            name: item.name,
+            isDisabled: item.isDisabled,
+
+            __valueKey: item.id,
+            __searchText: expr.concat(item.code, "|_|", item.name),
+            __isHidden: item.isDisabled,
+          }));
+
+          if (changeKeys) {
+            qr = qr.where((item) => [expr.in(item.id, changeKeys as number[])]);
+          }
+          return qr.execute();
+        });
+      },
+      orderBy: (item) => item.code,
+    });
+  }
+}
+
+export type TAppSharedData = {
+  고객사: ISharedCustomer;
+};
+
+export interface ISharedCustomer extends SharedDataBase<number> {
+  id: number;
+  code: string;
+  name: string;
+  isDisabled: boolean;
+}
+```
+
+**약속**:
+
+- `@Injectable({ providedIn: "root" })` 사용, `SdSharedDataProvider<TAppSharedData>` 를 상속.
+- 등록은 `override initialize()` 안에서 `this.register(name, opts)` 호출로 수행.
+- `useSharedSignal<K>(name)` 헬퍼를 함께 export — 컴포넌트는 inject 없이 이름만으로 접근.
+
+## 마스터 데이터 항목을 추가하려면
+
+세 곳을 함께 손봄: ① `initialize()` 의 `register` ② `TAppSharedData` 타입 항목 ③ 항목 인터페이스.
+
+### 1. `initialize()` 에 `register` 추가
+
+```ts
+this.register("품목", {
+  serviceKey: "MAIN",
+  getter: async (changeKeys) => {
+    return this._appOrm.connectAsync(async (db) => {
+      let qr = db.product().select((item) => ({
+        id: item.id,
+        code: item.code,
+        name: item.name,
+        isDisabled: item.isDisabled,
+
+        __valueKey: item.id,
+        __searchText: expr.concat(item.code, "|_|", item.name),
+        __isHidden: item.isDisabled,
+      }));
+
+      if (changeKeys) {
+        qr = qr.where((item) => [expr.in(item.id, changeKeys as number[])]);
+      }
+      return qr.execute();
+    });
+  },
+  orderBy: (item) => item.code,
+});
+```
+
+- getter 의 select 결과에 매직 필드를 포함:
+  - `__valueKey` — 항목의 키.
+  - `__searchText` — 검색용 텍스트.
+  - `__isHidden` — 숨김 여부 (예: `isDisabled` 값으로 지정).
+- `getter(changeKeys)` 의 `changeKeys` 인자가 주어지면 해당 키들만 다시 조회 (incremental refresh). 위 `where` 분기가 그 처리.
+- `orderBy` 는 정렬 키를 반환하는 함수.
+
+### 2. `TAppSharedData` 에 항목 추가
+
+```ts
+export type TAppSharedData = {
+  고객사: ISharedCustomer;
+  품목: ISharedProduct;
+};
+```
+
+### 3. 항목 인터페이스 정의 (`SharedDataBase` 상속)
+
+```ts
+export interface ISharedProduct extends SharedDataBase<number> {
+  id: number;
+  code: string;
+  name: string;
+  isDisabled: boolean;
+}
+```
+
+- 제네릭 인자는 키 타입(여기선 `number`).
+
+## 화면에서 참조하려면
+
+```ts
+sharedProducts = useSharedSignal("품목");
+
+// sharedProducts.items()  — 시그널, 항목 배열
+// sharedProducts.get(id)  — id 로 단건 조회
+```
+
+- `register` 에 쓴 이름 문자열을 그대로 넘기면 `TAppSharedData` 에서 타입이 추론됨.
+
+## 지킬 것
+
+- 항목 추가 시 세 곳(`register` · `TAppSharedData` · 인터페이스)을 모두 갱신. 하나라도 빠지면 타입 불일치 또는 미등록 데이터가 됨.
+- select 결과에 매직 필드(`__valueKey` · `__searchText` · `__isHidden`)를 빠짐없이 포함.
+- `changeKeys` 분기를 생략하지 않음 — incremental refresh 가 동작하지 않으면 변경 시 전체 재조회가 됨.

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

@@ -0,0 +1,96 @@
+# 클라이언트 시스템 로그 적재 매뉴얼
+
+클라이언트(Angular)에서 프레임워크가 잡은 시스템 에러·경고를 DB 등 외부 저장소에 적재하고, 직접 시스템 로그를 남기려 할 때 참조.
+
+`SdSystemLogProvider`(`@simplysm/angular`, `providedIn: "root"`)가 그 통로. 내부적으로는 `createLogger("angular:system-log")` 로 **항상 콘솔에 먼저 출력**한 뒤, 앱이 꽂은 `writeFn` 이 있으면 추가로 외부에 흘려보냄. 즉 [logging.md](./logging.md)의 콘솔 출력 표준 위에 "외부 적재 훅 + 프레임워크 자동 연동"을 얹은 것이며, `createLogger` 를 대체하지 않음.
+
+지원 심각도: `"error" | "warn" | "log"`.
+
+## 시스템 로그 테이블을 정의하려면
+
+외부 적재 대상이 DB 라면 로그 테이블을 먼저 정의. 시간 역순 조회가 잦으므로 `dateTime` 에 DESC 인덱스를 둠.
+
+```ts
+import { Table } from "@simplysm/orm-common";
+import { Employee } from "./employee";
+
+export const SystemLog = Table("SystemLog")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    dateTime: c.datetime(),
+    severity: c.varchar(50), // "error" | "warn" | "log"
+    message: c.text(), // writeFn 의 data 를 JSON 직렬화해 저장
+    clientName: c.varchar(200), // 어느 클라이언트에서 발생했는지
+    employeeId: c.bigint().nullable(), // 인증 전 로그도 적재되므로 nullable
+  }))
+  .primaryKey("id")
+  .indexes((i) => [i.index("dateTime").orderBy("DESC")])
+  .relations((r) => ({
+    employee: r.foreignKey(["employeeId"], () => Employee),
+  }));
+```
+
+- `severity` 는 `SdSystemLogProvider` 가 넘기는 세 값(`error`/`warn`/`log`)을 그대로 저장.
+- `message` 는 `writeFn` 의 가변 인자 `data` 전체를 담을 수 있게 `text` + JSON 직렬화로 둠.
+- `employeeId` 는 로그인 이전 시점의 에러도 기록되므로 `nullable`.
+
+## 부트스트랩에서 외부 적재를 배선하려면
+
+`provideAppInitializer` 안에서 `SdSystemLogProvider.writeFn` 에 적재 함수를 할당. 트랜잭션이 필요 없는 단순 insert 이므로 `connectWithoutTransAsync` 를 사용.
+
+```ts
+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 db.systemLog().insert([
+        {
+          dateTime: new DateTime(),
+          severity,
+          message: JSON.stringify(data),
+          clientName: CLIENT_NAME,
+          employeeId: appAuth.authInfo()?.employeeId,
+        },
+      ]);
+    });
+  };
+
+  return appService.connectAsync();
+}),
+```
+
+- `CLIENT_NAME` 은 `provideSdAngular({ clientName: CLIENT_NAME })` 에 넘긴 값과 동일하게 두어 어느 앱에서 난 로그인지 구분.
+- `data` 는 가변 인자 배열이므로 `JSON.stringify(data)` 로 통째로 저장.
+- `writeFn` 미설정 시 외부 적재는 일어나지 않고 콘솔 출력만 수행됨. DB 적재가 필요한 앱에서만 배선.
+
+## 자동으로 적재되는 로그
+
+다음 프레임워크 지점이 별도 호출 없이 `writeAsync` 를 부르므로, `writeFn` 만 배선하면 자동으로 외부에 적재됨:
+
+- `SdGlobalErrorHandlerPlugin` — 미처리 에러·미처리 Promise 거부를 `writeAsync("error", ...)`, `error` 가 없는 `ErrorEvent` 는 `writeAsync("warn", ...)`.
+- `SdToastProvider.try()` / `.danger()` — 잡은 에러를 토스트로 띄울 때 `writeAsync("error", ...)`.
+
+## 직접 시스템 로그를 남기려면
+
+업무 코드에서 직접 적재하려면 프로바이더를 주입해 `writeAsync` 호출:
+
+```ts
+private readonly _sdSystemLog = inject(SdSystemLogProvider);
+
+await this._sdSystemLog.writeAsync("error", "결제 승인 실패", err.stack);
+```
+
+- 콘솔 출력은 항상 일어나고, `writeFn` 이 배선돼 있으면 외부 적재까지 이어짐.
+
+## 적재된 로그를 조회하려면
+
+`SystemLog` 테이블을 일반 ORM 조회로 읽으면 됨([orm.md](./orm.md) 참조). 시간 역순 인덱스를 활용해 `dateTime` 내림차순으로 정렬.
+
+## 지킬 것
+
+- `writeFn` 안의 적재 실패는 throw 하지 않음. `SdSystemLogProvider` 가 `writeFn` 호출을 try/catch 로 감싸 실패를 `logger.error` 로만 남기고 삼킴 — 로그 적재 실패가 원래 동작(에러 처리·화면 흐름)을 막지 않게 하기 위한 설계. 이 자리는 silent skip 금지 원칙의 예외가 아니라, "로그 싱크 실패는 본 동작과 분리한다"는 의도된 동작.
+- `writeFn` 은 부트스트랩(`provideAppInitializer`)에서 1회만 할당. 화면·서비스 코드에서 재할당하지 않음.
+- 콘솔에 찍는 것 자체는 `SdSystemLogProvider` 가 내부에서 `createLogger` 로 처리하므로, 시스템 로그를 남기려고 `console.*` 를 직접 호출하지 않음([logging.md](./logging.md)).