@simplysm/sd-claude 14.0.65 → 14.0.66

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

@@ -0,0 +1,102 @@
+# sd-crud-list / sd-crud-detail 매뉴얼
+
+화면 작성 시 표준 목록 컴포넌트(`sd-crud-list`) 또는 표준 단건 편집 컴포넌트(`sd-crud-detail`) 를 채택하기로 결정했을 때의 사용법. 컴포넌트 일반 규약·데이터 흐름은 [client-component.md](./client-component.md).
+
+## `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 별 동작
+
+- **`'page'`** — 라우팅 진입 단위. 상단에 저장 버튼.
+- **`'control'`** — view 안에 임베드. 명령 영역에 저장 버튼.
+- **`'modal'`** — 모달. 하단 우측 "확인" 버튼이 자동.

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

@@ -0,0 +1,128 @@
+# 클라이언트 데모 작성 매뉴얼
+
+`@simplysm/angular` v14 로 spec.md §4.x 화면을 **데모** 로 옮길 때의 추가 처방. 컴포넌트 일반 규약(파일명·시그널·DI·핸들러·시트·폼·버튼·모달 호출·합성 패턴 등)은 [client-component.md](./client-component.md). 본 문서는 spec § → 산출물 매핑과 데모 한정 패턴만 다룬다.
+
+## §4.x 화면 유형 → 파일 역할
+
+| §4.x 패턴                                                | 파일 역할                                                                                       |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| 마스터(체크박스·`[E N]`·5버튼바) / 시트 단일             | `<domain>.list.ts`                                                                              |
+| 단건 입력 폼                                             | `<domain>.detail.ts`                                                                            |
+| 좌 목록 + 우 단건                                        | `<domain>.view.ts` + `.list.ts` + `.detail.ts`                                                  |
+| 좌 헤더 목록 + 우(헤더 정보 + 라인 시트) 마스터-라인     | `<domain>.view.ts` + `.list.ts` + `.detail.ts` — 우 라인 영역은 `.detail.ts` (헤더 단건 + 라인) |
+| 모달 (§동작에 `→ [화면.X] 을 모달로 띄움`)               | `<domain>.modal.ts`                                                                             |
+| 프린트 양식                                              | `<domain>.print-template.ts`                                                                    |
+
+`<domain>` = 화면명 dash-case 영문 음역 슬러그. 같은 도메인 폴더에 같은 역할이 2개 이상이면 `<domain>-<갈래>.<역할>.ts`.
+
+## 와이어프레임 권위
+
+§4.x 와이어프레임이 모든 시각 요소(버튼·필터·시트·탭·검색)의 **존재·영역·순서** 결정의 1순위. 표준 슬롯/기본 UI 와 충돌 시 와이어프레임에 맞춰 슬롯을 비우거나 컴포넌트 교체. 줄 수·픽셀 좌표는 권위 X (폼 inline 자동 wrap 등 표현 한계).
+
+`sd-crud-list` 의 표준 출력(`(create)/(delete)/(restore)`) 이 와이어프레임의 명시 버튼 위치를 가린다면 표준 출력 채택을 포기하고 슬롯 안에 `sd-button` 으로 직접 배치.
+
+## 항목표 `종류` → 입력 컨트롤
+
+[client-component.md "표준 입력 컨트롤"](./client-component.md) 표 적용. spec 의 `종류` 가 표 외 표기면 가장 가까운 매핑 + `// sd-demo: 종류 매핑 임의 — 확인 필요` 마커.
+
+## 도메인 데이터 (더미)
+
+- 컴포넌트 파일 안에 `interface DemoXxx { ... }` 로 spec §7 필드명만 일치하게 선언. 위에 `// sd-demo: 더미 타입 — 구현 단계에서 @모델/X 로 교체` 마커.
+- list 의 `items` / detail 의 `data` 는 이 인라인 타입으로 signal 선언.
+- 더미 데이터 1~수건 인라인 + `// sd-demo: 더미 — 구현 단계에서 교체` 마커.
+
+## 권한 path
+
+spec 에 권한 path 명시 없으면 임의 추정 + 마커:
+
+```ts
+perms = injectPermsSignal(
+  ["임의 권한 path"], // sd-demo: 권한 path 임의 — 확인 필요
+  ["use", "edit"],
+);
+```
+
+`restricted`/`readonly` 인라인 전달은 [client-component.md "권한 (perms)"](./client-component.md) 그대로.
+
+## 액션 핸들러 (시뮬레이션 X)
+
+데이터 변경 결과 반영 금지. 본문은 마커만:
+
+```ts
+async onSaveClick() {
+  if (this.busyCount() > 0) return;
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    // sd-demo: 미구현 — 동작 자리
+  });
+  this.busyCount.update((v) => v - 1);
+}
+```
+
+## 모달
+
+호출 측 후처리도 마커:
+
+```ts
+const result = await this._sdModal.showAsync({ ... });
+if (!result) return;
+// sd-demo: 미구현 — 동작 자리
+```
+
+영역 한정 호출 (`→ [화면.Y] 의 <영역> — 선택 전용` 등) 은 모달 입력 시그널(`selectMode` 등)로 전달.
+
+피호출 모달: `<sd-crud-detail>` 루트(`viewType='modal'` 자동 주입). 임의 `close` output 약속 만들지 X — `_sdModal.showAsync` 의 페이로드 회수 약속만 사용.
+
+**동반 모달**: §동작에 `→ [화면.Y] 을 모달로 띄움` 으로 등장하는 모든 모달은 같은 호출에서 함께 생성. 이미 존재하면 재사용.
+
+## 양식 매핑 (엑셀 업/다운로드)
+
+§4.x 에 양식 매핑 표 있으면 `#toolTpl` 에 버튼만 (핸들러 본문은 마커):
+
+```html
+<ng-template #toolTpl>
+  <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onExcelUploadClick()">
+    <ng-icon [svg]="tablerFileExcel" /> 엑셀 업로드
+  </sd-button>
+  <sd-button [size]="'sm'" [theme]="'link-primary'" (click)="onExcelDownloadClick()">
+    <ng-icon [svg]="tablerDownload" /> 엑셀 다운로드
+  </sd-button>
+</ng-template>
+```
+
+## 상태별 와이어프레임
+
+spec 이 `와이어프레임 (확정 전):` / `와이어프레임 (확정 후):` 로 분리하면:
+
+```ts
+// sd-demo: 더미 — 구현 단계에서 교체
+state = signal<"draft" | "confirmed">("draft");
+```
+
+```html
+@if (state() === "draft") {
+  <!-- 확정 전 와이어프레임 반영 -->
+} @else {
+  <!-- 확정 후 와이어프레임 반영 -->
+}
+```
+
+## "선택하세요." 빈 화면
+
+list+detail 합성 view 의 빈 상태는 시연 시 눈에 띄게:
+
+```html
+<div
+  class="flex-fill tx-theme-gray-default p-xxl"
+  style="font-size: 48px; line-height: 1.5em"
+>
+  <ng-icon [svg]="tablerArrowLeft" />
+  선택하세요.
+</div>
+```
+
+[client-component.md "list + detail 합성"](./client-component.md) 의 단순 `<div class="flex-fill p-default">선택하세요.</div>` 를 본 사례로 대체.
+
+## 라우팅·메뉴 답습
+
+답습 화면 1개의 라우팅·메뉴 등록 위치·방식 그대로. 라우트 경로는 화면명 dash-case 영문 음역 슬러그 (기존 슬러그 규칙 일관 시 답습). 메뉴 라벨은 spec 의 화면명 그대로.

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

@@ -0,0 +1,7 @@
+# 클라이언트 기본 지침
+
+클라이언트 코드(앱·`@simplysm/angular` 라이브러리 포함) 작성 시 공통으로 따르는 규칙.
+
+## Angular template 규칙
+
+- **`$any` 사용 금지** (lint error). template 에서 타입이 안 풀리면 컴포넌트 클래스의 타입 설계를 바로잡아 해결. `eslint-disable-next-line` 으로 우회 금지.

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

@@ -1,6 +1,6 @@
 # 클라이언트 환경 셋업 매뉴얼
 
-이 문서는 `@simplysm/angular` 위에 앱이 만들어두는 표준 추상화 계층(서비스 클라이언트·ORM·공유 데이터)을 정의·등록하는 컨벤션을 모은다. 화면 작성 시점에는 거의 건드리지 않으며, 새 앱 부트스트랩이나 새 서비스/마스터 데이터 추가 시에만 본다. 화면 컨벤션은 [client-component.md](./client-component.md) 참조.
+화면 작성 시점에는 거의 건드리지 않으며, 새 앱 부트스트랩이나 새 서비스/마스터 데이터 추가 시에만 본다.
 
 ## AppServiceProvider
 
@@ -148,7 +148,7 @@ export interface ISharedCustomer extends SharedDataBase<number> {
 - getter 의 select 결과에 매직 필드 포함:
   - `__valueKey` — 항목 키.
   - `__searchText` — 검색 텍스트.
-  - `__isHidden` — 숨김 여부 (보통 `isDeleted`).
+  - `__isHidden` — 숨김 여부 (예시: `isDeleted`).
 - `getter(changeKeys)` 가 있으면 그 키들만 다시 조회 (incremental refresh).
 - `orderBy` 는 정렬 키를 반환하는 함수 (`(item) => item.code`).
 - `useSharedSignal<K>(name)` 헬퍼 함수를 같이 export — 컴포넌트는 inject 없이 이름만으로 접근.

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

@@ -13,23 +13,25 @@
 
 ## 표준 패턴
 
-탭은 보통 **상단 고정 + 본문 fill** 구조. `sd-dock` 으로 탭바를 고정하고, 본문은 `@if` 분기.
+탭은 **상단 고정 + 본문 fill** 구조. flex-column 으로 탭바를 상단 고정, 본문은 `flex-fill` 안에 `@if` 분기.
 
 ```html
-<sd-dock-container>
-  <sd-dock class="pb-default">
+<div class="flex-column fill">
+  <div class="pb-default">
     <sd-tab [(value)]="activeTab">
       <sd-tab-item [value]="'info'">기본정보</sd-tab-item>
       <sd-tab-item [value]="'history'">이력</sd-tab-item>
     </sd-tab>
-  </sd-dock>
-
-  @if (activeTab() === "info") {
-    <app-info-list />
-  } @else {
-    <app-history-list />
-  }
-</sd-dock-container>
+  </div>
+
+  <div class="flex-fill">
+    @if (activeTab() === "info") {
+      <app-info-list />
+    } @else {
+      <app-history-list />
+    }
+  </div>
+</div>
 ```
 
 ```ts

package/claude/references/sd-simplysm14/{orm-union.md → manuals/orm-union.md}

@@ -8,7 +8,7 @@
 - 행 종류 구분 등 리터럴 값은 JS 값을 그대로 쓴다.
 - 한쪽에만 있는 컬럼은 NULL 자리채움이 필요한데 타입 추론이 안 되므로 `expr.raw("<type>")\`NULL\`` 로 명시한다.
 - 필터(`where`)는 union 전에 각 쿼리에 같은 조건으로 적용한다 — 각 소스에서 미리 행 수를 줄여야 union 비용이 작다 (predicate pushdown). union 결과에 필터를 걸면 두 소스를 다 읽은 뒤 거르게 되고, select 한 컬럼만 남아 join 컬럼으로 필터도 불가하다.
-- 총 건수는 가능하면 **각 소스에서 따로 `count` 후 합산**한다. union 결과의 `count` 는 양쪽 SELECT 를 모두 실행해 머티리얼라이즈한 뒤 세지만, 각각 세면 단순 집계로 끝난다. UNION DISTINCT 등으로 중복 제거가 필요해 합산이 부정확해질 때만 union 후 count.
+- 총 건수는 가능하면 **각 소스에서 따로 `count` 후 합산**한다. union 결과의 `count` 는 양쪽 SELECT 를 모두 실행해 머티리얼라이즈한 뒤 세지만, 각각 세면 단순 집계로 끝난다. 중복 제거가 필요해 합산이 부정확해질 때만 union 후 count.
 - `Queryable.union(...)` 결과는 의미상 wrap 된 derived table 로, 그 위에서 호출되는 모든 fluent 연산자(`orderBy` / `limit` / `top` / `distinct` / `groupBy` / `having` / `where` / `select` / `join` 등)는 외부 union 위에 자동 적용된다. sub 별 적용(predicate pushdown 등)을 원하면 union 전에 각 sub-Queryable 에 미리 호출한다.
 
 ## 예시

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

@@ -0,0 +1,75 @@
+# ORM 작업 가이드
+
+## 단일 쿼리 우선
+
+연관 데이터는 select 의 `join` 으로 한 쿼리에 모아 가져온다. 여러 쿼리로 나눠 받아 코드(서버/UI)에서 합치지 않는다.
+
+ORM 빌더로 표현 불가능한 경우, 작성 전 사용자 보고 후 중단.
+
+예외: raw query로도 표현 불가하거나 단일 쿼리화가 명백히 비효율일 때만. 사유를 코드 주석에 남긴다.
+
+이종 엔티티(예: 입고 + 출고)를 한 목록으로 보여줘야 할 때 두 결과를 코드에서 merge 하지 않으려면 → [orm-union.md](./orm-union.md) 참조.
+
+## 조회 목록 표준 흐름
+
+list / sheet 화면의 본 쿼리는 다음 순서로 작성한다:
+
+1. root queryable 빌드 (`db.X()`).
+2. 필요한 연관 데이터를 `joinSingle` 로 부착 — 본 행에 곧장 부착하지 않으면 안 되는 컬럼만. join 내부 쿼리도 동일 흐름 (`from → joinSingle → where → select`).
+3. `.select((p) => ({ ...도출 컬럼들... }))` — coalesce / CASE WHEN / 산식 등 모든 도출을 한 번에 projection. select 콜백 안에서 로컬 `const` 로 산식을 잘게 나눠 가독성 확보.
+4. WHERE 는 step 3 의 projected 컬럼 이름으로 직접 참조 (`r.psd`, `r.isCanceled`, `r.status`, …). framework 가 projected ExprUnit AST 를 WHERE 절에 그대로 inline 하므로 wrap 없이도 도출 컬럼 필터링이 동작한다.
+5. `count()` 로 총 건수.
+6. `orderBy(...).limit(page * size, size).execute()`.
+
+WHERE / SELECT 양쪽에서 동일 도출 산식을 쓰겠다고 `buildDerived(p)` 같은 helper 함수 만들지 말 것 — step 3 의 projected 컬럼이 자동으로 그 역할을 한다.
+
+화면 첫 진입 1회만 필요하고 refresh / 필터 변경에 무관한 데이터 (필터 dropdown 옵션 등) 는 본 목록 쿼리에 섞지 말 것. 별도 1회 effect 로 분리해 init 시점에만 로드한다.
+
+## 안티패턴
+
+### SELECT 절 안 `expr.subquery` / `expr.exists` 박지 말 것
+
+도메인 boolean (`isCompleted`, `hasAny` 등) / 집계 (`SUM`, `COUNT`, `MAX`) 가 필요하면 `joinSingle` 안에서 `from + where + select(aggregate)` 로 묶어 outer 행에 컬럼으로 부착한다. SELECT column 에 subquery / exists 박으면 outer 행마다 inner 가 N 회 실행된다.
+
+```ts
+// 나쁜 예 — 행당 subquery N회
+.select((p) => ({
+  isCompleted: expr.is(expr.exists(db.X().where(...))),
+  sumA: expr.subquery("number", db.Y().select(...)),
+}))
+
+// 좋은 예 — joinSingle 로 1회 부착, 컬럼으로 참조
+.joinSingle("state", (q, p) =>
+  q.from(X).where((x) => [expr.eq(x.fk, p.id)])
+    .select((x) => ({
+      rowCount: expr.count(),
+      completedCount: expr.count(x.completedAt),
+      sumA: expr.sum(x.amount),
+    })),
+)
+.select((p) => ({
+  isCompleted: expr.gt(p.state!.completedCount, 0),
+  sumA: expr.coalesce(p.state!.sumA, 0),
+}))
+```
+
+### 불필요한 `wrap()`
+
+`wrap()` 은 framework 가 명시 요구하는 경우에만 쓴다 (대표적으로 `count()` after `distinct()` / `groupBy()` 호출 같은 명시 요구).
+
+도출 컬럼 위에서 필터/정렬을 걸기 위해 wrap 을 끼우는 패턴은 불필요 — `.select(...).where((r) => [...])` 만으로 framework 가 projected ExprUnit AST 를 WHERE / ORDER BY 에 inline 한다.
+
+"Layer 1 = materialize, Layer 2 = derive" 같은 다층 wrap 구조도 군더더기. 단일 select 안 로컬 `const` 로 산식 분리하면 동일 SQL 이 나온다.
+
+## 스키마 정의
+
+컬럼은 `NOT NULL` 기본. `.nullable()`/`.default(...)` 는 도메인 근거가 있을 때만 붙인다.
+
+- `.nullable()`: 도메인상 값이 없을 수 있을 때만 (선택 입력, 미발생 이벤트 시각, 선택적 FK).
+- `.default(...)`: 사용자가 명시 지시한 경우에만.
+- "초기값 애매", "마이그레이션 중간 단계", "넣을 값 모름" 은 nullable/default 근거 아님. 호출자가 넣도록 강제하거나 backfill 후 `NOT NULL`로 전환.
+
+## 삭제 전략
+
+- **기초정보(마스터)**: soft delete (`isDisabled` 등). FK 참조 무결성 보존.
+- **프로세스 문서(트랜잭션)**: 물리 delete. 상세 행 포함 캐스케이드. 단, 다른 테이블이 FK로 참조 중이면 삭제 차단하고 최종 사용자에게 toast 등으로 사유 안내.