@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/angular/recipes/crud-list/extension-d-select-modal.md

@@ -0,0 +1,193 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 D: 선택 모달 전환
+
+> **선행:** [확장 A: inline 편집/저장](./extension-a-inline-edit.md) + [확장 B: 선택 기능](./extension-b-selection.md)
+
+같은 리스트 화면이 **다른 화면에서 항목을 골라주는 "선택 모달"로도 재사용**되도록 한다. 라우트로 진입하면 page 뷰(CRUD 리스트), `SdModalProvider.showAsync()`로 열리면 modal 뷰(selectMode에 따라 single/multi)로 자동 전환되며, 선택 결과를 `close.emit`으로 돌려준다.
+
+## When to use / When NOT to use
+
+- ✅ 같은 리스트를 라우트 페이지와 "선택 모달" 두 용도로 겸용
+- ✅ 항목을 골라 호출 측에 `SelectModalOutputResult<T>`로 돌려주는 selector 화면
+- ✅ multi 선택에서 페이지 이동 후에도 선택을 누적 유지해야 하는 경우
+- ❌ 부모 레코드의 자식 목록·이력을 **읽기 전용으로** 표시(닫기는 SdModal 기본 "X") → [확장 E](./extension-e-readonly-modal.md)
+- ❌ 리스트 **자체는 page** 이고 행 클릭 시 **편집 모달**만 띄우는 경우 → [확장 F](./extension-f-modal-edit.md). 확장 A(inline 편집)와 상호 배타
+- ❌ 리스트가 아닌 단일 값 셀렉트 버튼 → [`data-select-button.md`](../data-select-button.md)
+
+## 전제조건
+
+- 선행: 확장 A(inline 편집/저장) + 확장 B(선택 기능). 본 확장의 코드는 A의 `canEdit` / `_checkIgnoreChanges` 와 B의 `selectedItems` / `isDeleted` / `getItemCellStyleFn` / `selectMode="multi"` 를 그대로 재사용한다
+- 횡단 규칙: [`_common-rules.md`](../_common-rules.md) — 특히 [`injectViewTypeSignal()` 호출 시점](../_common-rules.md#injectviewtypesignal은-생성자-또는-필드-이니셜라이저에서만-호출한다), [signal 필드 초기값에서 다른 signal 읽기 금지](../_common-rules.md#signal-필드-초기값에서-다른-signal을-읽지-않는다)
+- 호출 측: `SdModalProvider.showAsync(CustomerList, { inputs: { selectMode: "multi", selectedItemKeys: [...] } })` 형태로 연다
+
+## 이 확장이 도입하는 요소
+
+| 영역 | 추가 |
+|------|------|
+| imports | `input`, `output` (`@angular/core`), `type SdSelectModal`, `type SelectModalOutputResult` (`@simplysm/angular`) |
+| 계약 | `implements SdSelectModal<ICustomer>` + `selectMode` input + `selectedItemKeys` input + `close` output |
+| 생성자 effect | modal 뷰일 때 `selectedItemKeys` → `selectedItems` 복원 (items 로드 후) |
+| `setupCanDeactivate` | modal 뷰에서 변경사항 체크 스킵 |
+| 메서드 | `onSelectedItemsChange` — modal + single 모드일 때 선택 즉시 자동 닫기 |
+| 메서드 | `onModalConfirmClick`, `onModalCancelClick` |
+| 파생 | `canEdit = computed(() => perms().includes("edit") && viewType() === "page")` — modal에서는 inline 편집 자동 비활성화 |
+| 템플릿 | `<sd-sheet>`에 `[selectMode]` 조건부 바인딩 + `[autoSelect]` single 모드 클릭 자동선택 + modal 전용 하단 dock (확인/선택 해제) |
+
+## 코드 (확장 A + B 위에 얹는 diff)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A+B) 위에 번호 순서대로 삽입·교체할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { input, output } from "@angular/core";
+import { type SdSelectModal, type SelectModalOutputResult } from "@simplysm/angular";
+
+// 2) 클래스에 SdSelectModal<ICustomer> 계약 구현
+export class CustomerList implements SdSelectModal<ICustomer> {
+  // ... 기존 확장 A + B 멤버 ...
+
+  //== SdSelectModal<ICustomer> 계약 ==
+  selectMode = input<"single" | "multi" | undefined>();
+  selectedItemKeys = input<(number | undefined)[]>([]);
+  close = output<SelectModalOutputResult<ICustomer> | undefined>();
+
+  //== 파생 재정의 — modal 뷰에서는 inline 편집 자동 비활성화 ==
+  // canEdit을 viewType=="page" 조건으로 묶어, modal 뷰에서는 편집 셀·저장·등록 버튼이 자동으로 숨겨진다
+  canEdit = computed(() => this.perms().includes("edit") && this.viewType() === "page");
+
+  constructor() {
+    // ... 기존 초기 effect (필터/페이지/정렬 재조회) ...
+
+    // modal 뷰: selectedItemKeys → selectedItems 복원 (items 로드 후)
+    effect(() => {
+      if (this.viewType() !== "modal") return;
+
+      const keys = this.selectedItemKeys();
+      if (keys.length === 0) return;
+
+      const currItems = this.items();
+      if (currItems.length === 0) return;
+
+      untracked(() => {
+        const sel = currItems.filter((it) => keys.includes(this.trackByFn(it)));
+        if (sel.length > 0) this.selectedItems.set(sel);
+      });
+    });
+
+    // modal 뷰는 라우트 이탈 개념이 없으므로 변경사항 체크 스킵
+    setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
+  }
+
+  // 3) 메서드 추가
+
+  // modal + single 모드: 선택 즉시 자동 닫기
+  onSelectedItemsChange(): void {
+    if (this.viewType() !== "modal") return;
+    if (this.selectMode() !== "single") return;
+
+    const sel = this.selectedItems();
+    if (sel.length !== 1) return;
+
+    const selKey = this.trackByFn(sel[0]);
+    if (this.selectedItemKeys().includes(selKey)) return;
+
+    this.close.emit({
+      selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+      selectedItems: sel,
+    });
+  }
+
+  onModalConfirmClick(): void {
+    const sel = this.selectedItems();
+    this.close.emit({
+      // id=undefined 신규 행 제거 — index fallback 금지(아래 Anti-patterns 참조)
+      selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+      selectedItems: sel,
+    });
+  }
+
+  onModalCancelClick(): void {
+    this.selectedItems.set([]);
+
+    // single 모드에서만 즉시 close (multi는 "확인" 버튼 필요 — 아래 Anti-patterns 참조)
+    if (this.selectMode() === "single") {
+      this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+    }
+  }
+}
+```
+
+```html
+<!-- 4) template — <sd-sheet>에 selectMode + autoSelect 추가, selectedItemsChange 이벤트, 시트 뒤에 modal 하단 dock 배치 -->
+<sd-sheet
+  ...(기존)
+  [selectMode]="selectMode() ?? 'multi'"
+  [autoSelect]="viewType() === 'modal' && selectMode() === 'single' ? 'click' : undefined"
+  [(selectedItems)]="selectedItems"
+  (selectedItemsChange)="onSelectedItemsChange()"
+>
+  <!-- 컬럼들 동일 -->
+</sd-sheet>
+
+<!-- modal 하단 확인 바 -->
+@if (viewType() === "modal") {
+  <sd-dock
+    [position]="'bottom'"
+    class="p-sm-default flex-row main-align-end gap-sm bdt bdt-theme-gray-lightest"
+  >
+    <sd-button [size]="'sm'" [theme]="'danger'"
+      (click)="onModalCancelClick()"
+      [disabled]="selectedItems().length < 1">
+      선택 해제
+    </sd-button>
+    @if (selectMode() === "multi") {
+      <sd-button [size]="'sm'" [theme]="'primary'" (click)="onModalConfirmClick()">
+        확인({{ selectedItems().length }})
+      </sd-button>
+    }
+  </sd-dock>
+}
+```
+
+## 포인트
+
+- **`canEdit`에 `viewType() === "page"` 조건 추가.** modal 뷰에서 자동으로 inline 편집 셀이 읽기 전용이 되고, 상단 "저장" 버튼과 inline 도구 dock(등록/선택 삭제·복구)이 숨겨진다. 선택 모달은 편집 목적이 아니다.
+- **`[autoSelect]="'click'"` — modal + single 모드 전용.** 클릭 한 번으로 행이 즉시 선택되도록 한다. multi 모드에서는 `undefined`(기본 동작)로 두어 체크박스 누적 선택이 유지된다.
+- **`(selectedItemsChange)` 이벤트에서 single 자동 닫기.** modal + single 모드일 때 행 하나가 선택되면 `close.emit`으로 결과를 즉시 반환한다. 이미 선택된 key와 동일한 행을 클릭하면 무시하여 중복 닫기를 방지한다.
+## 🚫 Anti-patterns
+
+### multi 모드에서 "선택 해제"가 close까지 호출
+
+```typescript
+// ✅ single에서만 즉시 close. multi는 set([])만 수행 후 "확인" 버튼으로 최종 emit
+onModalCancelClick(): void {
+  this.selectedItems.set([]);
+  if (this.selectMode() === "single") {
+    this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+  }
+}
+```
+
+**근거**: multi에서 "선택 해제" = "취소 + 닫기"가 되면 사용자가 다시 선택을 시작하려고 모달을 재오픈해야 한다. multi는 여러 행을 점진적으로 누적하는 UX이므로 닫는 트리거는 "확인" 버튼에만 둔다.
+
+### `selectedItemKeys` 반환에 index fallback
+
+```typescript
+// ✅ undefined를 제거하여 확정된 key만 전달
+this.close.emit({
+  selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+  selectedItems: sel,
+});
+```
+
+**근거**: `SelectModalOutputResult<T>.selectedItemKeys`는 호출 측이 DB 식별자로 사용한다(`packages/angular/src/core/select-modal-output-result.ts:4`). 신규 행 index를 섞으면 호출 측의 "이미 저장된 id" 집합과 충돌한다.
+
+## 관련 Entry
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 선행: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) — `canEdit` / `_checkIgnoreChanges` 제공
+- 선행: [확장 B: 선택 기능](./extension-b-selection.md) — `selectedItems` / multi 선택 / `getItemCellStyleFn` 제공
+- 대안: [확장 E: 조회 전용 modal](./extension-e-readonly-modal.md) — 부모 레코드의 자식 목록·이력을 input으로 받아 읽기 전용 표시. `SdSelectModal<T>` 계약을 부착하지 않는다
+- 대안: [확장 F: 모달 편집 모드](./extension-f-modal-edit.md) — page 상에서 행 클릭 시 편집 모달. inline 편집(확장 A)과 상호 배타
+- 계약 타입: `SdSelectModal<T>` (`packages/angular/src/controls/button/sd-modal-select-button.ts:30`), `SelectModalOutputResult<T>` (`packages/angular/src/core/select-modal-output-result.ts:4`)

package/claude/references/sd-simplysm-v14/angular/recipes/crud-list/extension-e-readonly-modal.md

@@ -0,0 +1,140 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 E: 조회 전용 modal
+
+> **선행:** 없음 (최소 뼈대 §3에 직접 얹음 — 확장 A/B/D 미사용)
+
+호출자(상세 화면 등)가 부모 레코드 식별자를 input으로 전달하면, 이 modal은 해당 부모의 자식 목록·이력만 필터링해 읽기 전용으로 표시한다. 닫기는 SdModal 기본 "X" 버튼이며, 선택·확정·저장·이탈 방지는 전부 불필요하다.
+
+- ✅ 부모 레코드의 자식 목록·이력만 필터링해 읽기 전용으로 표시할 때
+- ❌ 항목을 골라 호출자에게 돌려줘야 할 때 → [확장 D: 선택 모달](./extension-d-select-modal.md)
+- ❌ 부모 레코드에 대한 inline 편집·삭제가 필요할 때 → [확장 A](./extension-a-inline-edit.md)(+B) 또는 [확장 F: 모달 편집](./extension-f-modal-edit.md)
+
+호출 예:
+
+```typescript
+await this._sdModal.showAsync({
+  title: "고객 주문 이력",
+  type: CustomerOrderHistoryModal,
+  inputs: { customerId: 123 },
+});
+```
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `input`(`@angular/core`), `expr`(`@simplysm/orm-common`) 추가
+- **input:** 부모 식별자(예: `customerId = input.required<number>()`)
+- **초기 effect 의존성:** 부모 식별자 input 추가
+- **`_search` 변경:** where절에 부모 식별자 하드 필터(`expr.eq(...)`), 기존 `filter.searchText` 조건과 AND
+- **부착하지 않는 요소:** `implements SdSelectModal<T>` 계약, `selectedItems` / 하단 확인 바 / `canEdit` / `diffs` / `setupCanDeactivate` / `<sd-form #formCtrl>` 래퍼
+
+```typescript
+// 1) imports 추가 — @angular/core의 {input}
+import { input } from "@angular/core";
+
+// 2) 클래스 선언 — implements 없음. SdSelectModal<T> 계약 3종 부착 안 함
+export class CustomerOrderHistoryModal {
+  // ...DI, perms, 상태는 최소 뼈대와 동일
+
+  // 3) 부모 식별자 input (필수) — 맥락에 맞는 이름(customerId / orderId / companyId 등)
+  customerId = input.required<number>();
+
+  // 4) 초기 effect 의존성에 input 추가
+  constructor() {
+    effect(() => {
+      if (!this.perms().includes("use")) {
+        this.initialized.set(true);
+        return;
+      }
+
+      this.lastFilter();
+      this.page();
+      this.sortingDefs();
+      this.customerId();        // ← input 의존성 추가
+
+      void untracked(async () => {
+        this.busyCount.update((v) => v + 1);
+        await this._sdToast.try(async () => { await this._refresh(); });
+        this.busyCount.update((v) => v - 1);
+        this.initialized.set(true);
+      });
+    });
+  }
+
+  // 5) _search — where절에 부모 식별자 하드 필터. filter.searchText 등 기존 조건과 AND
+  private async _search(usePagination: boolean): Promise<{ items: ICustomerOrder[]; pageLength: number }> {
+    const filter = this.lastFilter();
+    const sortingDefs = this.sortingDefs();
+    const page = this.page();
+    const customerId = this.customerId();    // ← input 값
+
+    return this._appOrm.connectAsync(async (db) => {
+      let qr1 = db.customerOrder()
+        .where((item) => [expr.eq(item.customerId, customerId)]);
+
+      if (!str.isNullOrEmpty(filter.searchText)) {
+        qr1 = qr1.search((item) => [item.name], filter.searchText);
+      }
+      // 나머지는 최소 뼈대 _search와 동일 (paging/sorting/select/limit)
+      // ...
+    });
+  }
+}
+
+// 6) template — modal 전용 레이아웃. <sd-sheet>에 selectMode / selectedItems 미사용.
+//    시트 셀은 순수 표시({{ item.name }}). 하단 "선택 해제 / 확인" 바, 상단 inline 도구 dock 부재.
+`
+<sd-topbar-container>
+  <sd-dock-container>
+    <sd-dock class="p-default">
+      <sd-form (formSubmit)="onFilterSubmit()">
+        <!-- 필터 (최소 뼈대와 동일) -->
+      </sd-form>
+    </sd-dock>
+
+    <sd-sheet
+      [key]="'customer-order-history-sheet'"
+      [items]="items()"
+      [(currentPage)]="page"
+      [totalPageCount]="pageLength()"
+      [(sorts)]="sortingDefs"
+      [trackByFn]="trackByFn"
+    >
+      <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>
+      <!-- 필요한 조회 컬럼만 -->
+    </sd-sheet>
+  </sd-dock-container>
+</sd-topbar-container>
+`
+```
+
+**포인트:**
+
+- **부모 식별자는 호출자가 `inputs`으로 전달한다.** 값이 반드시 주어져야 하면 `input.required<T>()`, 없으면 전체 조회로 fallback하는 설계면 `input<T | undefined>()`. 어느 쪽이든 `_search`의 `where` 절과 초기 effect 의존성에 반드시 포함시킨다.
+- **닫기 = SdModal 기본 "X".** `close` output이 없으므로 `SdModalProvider.showAsync`의 리턴값도 사용하지 않는다. 호출 측은 `await showAsync(...)` 결과를 버리거나 `void`로 처리한다.
+- **시트는 읽기 전용.** `[cell]` 템플릿에 `<sd-textfield>` 대신 `{{ item.name }}` 같은 순수 표시만 쓰고, `let-edit="edit"` / `[readonly]="!edit"` / `(valueChange)="mark(items)"`는 제거한다. `canEdit` / `diffs` / `_itemsSnapshot` / `setupCanDeactivate`도 함께 제거한다.
+- **`viewType()` 분기는 쓰지 않아도 된다.** 조회 전용 modal은 보통 modal 전용으로 라우트 없이 등록된다. page/modal 양쪽을 모두 지원해야 할 때만 `viewType()`으로 topbar 영역을 분기하고, 시트·필터는 공통으로 둔다.
+- **input 반영 패턴은 공통 규칙을 따른다.** → [공통 규칙: input 변경을 effect 내부에서 filter·lastFilter·page에 반영한다](../_common-rules.md#input-변경을-effect-내부에서-filterlastfilterpage에-반영한다) · [공통 규칙: input 의존 데이터 로딩에 `void this._initAsync()`를 사용하지 않는다](../_common-rules.md#input-의존-데이터-로딩에-void-this_initasync를-사용하지-않는다)
+
+## 🚫 흔한 실수
+
+### signal 필드 초기값에서 부모 식별자 input 읽기
+
+```typescript
+// ✅ 기본값은 고정, 부모 식별자는 _search 호출부에서 input을 직접 읽는다
+filter = signal<IFilter>({});
+// _search 내부:
+const customerId = this.customerId();
+qr1 = qr1.where((item) => [expr.eq(item.customerId, customerId)]);
+```
+
+**근거**: 필드 이니셜라이저는 부모로부터 input 값이 전달되기 전에 실행되므로 항상 기본값만 반환한다. → [공통 규칙: signal 필드 초기값에서 다른 signal을 읽지 않는다](../_common-rules.md#signal-필드-초기값에서-다른-signal을-읽지-않는다)
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 관련: [확장 D: 선택 모달 전환](./extension-d-select-modal.md) (계약이 다른 modal 변형) · [확장 F: 모달 편집 모드](./extension-f-modal-edit.md) (부모 레코드 편집 modal)

package/claude/references/sd-simplysm-v14/angular/recipes/crud-list/extension-f-modal-edit.md

@@ -0,0 +1,123 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 F: 모달 편집 모드
+
+> **선행:** 없음 (최소 뼈대 §3에 직접 얹음 — [확장 A: inline 편집/저장](./extension-a-inline-edit.md)와 **상호 배타**)
+
+시트 셀 직접 수정(inline 편집) + 일괄 저장 대신, **행 클릭 시 편집 모달을 띄워 한 행씩 편집**하는 모드. 확장 A(inline 편집)와 **상호 배타**이므로 확장 A가 덧씌우는 파이프라인(`diffs` / `_itemsSnapshot` / `onSubmit` / `setupCanDeactivate` / `hostDirectives.sdSaveCommand` / `<sd-form #formCtrl>` 래퍼)을 이 확장에서는 부착하지 않는다. 대신 [`SdModalProvider.showAsync`](../../providers/sd-modal-provider.md)로 편집 모달을 호출하고, 모달 close 후 `_refresh()`로 리스트를 재조회한다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `SdAnchor`, `SdModalProvider`, `tablerEdit`
+- **DI:** `SdModalProvider`
+- **클래스 필드:** `tablerEdit` 아이콘 템플릿 참조
+- **메서드:** `onCreateItemButtonClick`, `onEditItemButtonClick`, `_editItem`
+- **템플릿:** 이름 컬럼 셀을 `<sd-anchor>` + 편집 아이콘으로 교체한다. inline 편집용 `<sd-textfield let-edit="edit">`는 사용하지 않는다. 등록 버튼은 `_editItem()` 직접 호출로 전환한다
+- **제거 대상(확장 A가 이미 적용되어 있는 경우):** `hostDirectives.sdSaveCommand` / `host (sdSaveCommand)` / `onSaveButtonClick` / `onSubmit` / `diffs` / `_itemsSnapshot` / `_checkIgnoreChanges` / `_upsertItem` / `getIsItemChanged` / `onRemoveNewItemButtonClick` / `setupCanDeactivate` / `<sd-form #formCtrl (formSubmit)="onSubmit()">` 래퍼
+
+> 상세: [`SdModalProvider.showAsync` 편집 모달 호출](../../providers/sd-modal-provider.md#편집-모달-호출) · [`<sd-anchor>`](../../ui-form/sd-anchor.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 최소 뼈대 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { SdAnchor, SdModalProvider } from "@simplysm/angular";
+import { tablerEdit } from "@ng-icons/tabler-icons";
+// 앱별 편집 모달 컴포넌트 (crud-detail.md 레시피로 작성):
+import { CustomerEditModal } from "./CustomerEditModal";
+
+// 2) DI 추가
+private readonly _sdModal = inject(SdModalProvider);
+
+// 3) 클래스 필드 추가 — 편집 버튼 아이콘
+protected readonly tablerEdit = tablerEdit;
+
+// 4) template — 이름 컬럼 셀을 <sd-anchor> + 편집 아이콘으로 교체한다.
+//    inline 편집용 <sd-textfield> / let-edit 바인딩은 쓰지 않는다.
+`
+<sd-sheet-column [key]="'name'" [header]="'이름'">
+  <ng-template [cell]="items()" let-item="item">
+    <sd-anchor (click)="onEditItemButtonClick(item, $event)" class="flex-row">
+      <div class="p-xs-sm">
+        <ng-icon [svg]="tablerEdit" />
+      </div>
+      <div class="flex-fill p-xs-sm">{{ item.name }}</div>
+    </sd-anchor>
+  </ng-template>
+</sd-sheet-column>
+`
+
+// 5) inline 편집용 도구 dock의 "등록" 버튼은 _editItem() 호출로 바꾼다.
+//    "선택 삭제/복구"를 남기려면 bulk API로 전환한다(아래 포인트 참조).
+// template:
+`<sd-button ... (click)="onCreateItemButtonClick()">등록</sd-button>`
+
+// 6) 메서드 교체
+protected async onCreateItemButtonClick(): Promise<void> {
+  await this._editItem();
+}
+
+protected async onEditItemButtonClick(item: ICustomer, event: MouseEvent): Promise<void> {
+  event.preventDefault();
+  event.stopPropagation();
+  await this._editItem(item);
+}
+
+private async _editItem(item?: ICustomer): Promise<void> {
+  const r = await this._sdModal.showAsync({
+    title: item == null ? "고객 등록" : "고객 수정",
+    type: CustomerEditModal,
+    inputs: { itemId: item?.id },
+  });
+  if (r != null) await this._refresh();
+}
+
+// 7) 제거 대상 (확장 A가 이미 적용되어 있는 경우 — 위 "제거 대상" 불릿 참조):
+//    - @Component hostDirectives의 sdSaveCommand / host의 (sdSaveCommand)
+//    - onSaveButtonClick / onSubmit / onAddItemButtonClick
+//    - diffs computed / _itemsSnapshot / _checkIgnoreChanges / _upsertItem
+//    - getIsItemChanged / onRemoveNewItemButtonClick
+//    - setupCanDeactivate(...) 호출 (이탈 방지는 편집 모달 쪽 책임)
+//    - <sd-form #formCtrl (formSubmit)="onSubmit()"> 래퍼 → <sd-sheet>를 main 영역에 직접 배치
+```
+
+**포인트:**
+
+- **모달 편집 모드에는 inline diff 개념이 없다.** 개별 item 변경은 `CustomerEditModal`(상세 폼) 내부에서 즉시 upsert하고 결과를 `close.emit(true)` 같은 신호로 반환한다. 리스트는 모달 close 후 `_refresh()`로 재조회한다.
+- **`CustomerEditModal`은 [`crud-detail.md`](../crud-detail.md) 레시피로 별도 작성한다.** modal 뷰 분기를 그대로 활용한다.
+- **시트 `[cell]` 템플릿에 `let-edit="edit"` / `[readonly]="!edit"` 바인딩은 불필요** — inline 편집이 아니며 읽기 전용 표시만 한다.
+- **"선택 삭제/복구"를 남길 경우 (확장 B와 병용):** `onToggleDeleteItemsButtonClick(del)` 내부를 diff 방식 대신 **bulk API 호출 + `_refresh()`** 로 구현한다. 확장 F는 `diffs` 파이프라인이 없어 확장 B 원본의 diff 경로가 동작하지 않기 때문이다.
+- **`itemId: item?.id`**: `item`이 undefined이면 "등록", id가 있으면 "수정"으로 위임한다. `CustomerEditModal` 내부에서 id 유무로 분기한다.
+
+**🚫 흔한 실수**
+
+> 공통 규칙(`mark` 오용, `setupCanDeactivate` 호출 위치, 시트 셀 `[inset]`/`[size]` 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **모달 편집 모드 고유 실수**만 다룬다.
+
+### 확장 A의 inline 편집 파이프라인과 동시 적용
+
+```typescript
+// ✅ 두 경로 중 하나만 선택한다. 확장 F를 선택하면 확장 A가 덧씌웠던 파이프라인은 전부 제거한다.
+@Component({
+  // hostDirectives / sdSaveCommand 불필요 — 모달 편집 모드는 inline 저장이 없다
+  template: `
+    <!-- <sd-form #formCtrl (formSubmit)="onSubmit()"> 래퍼 없음 -->
+    <sd-sheet ...>
+      <sd-sheet-column [key]="'name'">
+        <ng-template [cell]="items()" let-item="item">
+          <sd-anchor (click)="onEditItemButtonClick(item, $event)">
+            <ng-icon [svg]="tablerEdit" /> {{ item.name }}
+          </sd-anchor>
+        </ng-template>
+      </sd-sheet-column>
+    </sd-sheet>
+  `,
+})
+```
+
+**근거**: Ctrl+S가 어느 폼을 submit할지 모호해지고, `setupCanDeactivate`가 편집 모달 open 중에 이중 발동하며, 동일 행 편집 경로(inline vs 모달)가 둘 다 활성화되어 UX가 깨진다. "편집 모드"는 하나만 선택한다.
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 관련: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) (이 확장과 상호 배타)
+- 공통 규칙: [_common-rules.md](../_common-rules.md)

package/claude/references/sd-simplysm-v14/angular/recipes/crud-list/extension-g-excel.md

@@ -0,0 +1,145 @@
+← [CRUD 리스트 레시피 진입점](../crud-list.md)
+
+# 확장 G: 엑셀 업로드/다운로드
+
+> **선행:** [확장 A: inline 편집/저장](./extension-a-inline-edit.md) (`_upsertItem` / `_search` / 감사 로그 재사용)
+
+`SdFileDialogProvider`로 파일 선택, `ExcelWrapper`(@simplysm/excel) + `zod` 스키마로 읽기/쓰기를 수행한다. 다운로드는 확장 A의 `_search(false)`로 페이지네이션 없이 전체를 조회한 뒤 `@simplysm/core-browser`의 `downloadBlob`으로 내려받는다. 업로드된 각 행은 확장 A의 `_upsertItem`을 재사용해 중복 검사·감사 로그를 일관된 경로로 적용한다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `SdFileDialogProvider`, `DateTime`, `downloadBlob`(@simplysm/core-browser), `ExcelWrapper`(@simplysm/excel), `z`(zod), `tablerFileExcel`, `tablerUpload`
+- **DI:** `SdFileDialogProvider`
+- **필드:** `tablerFileExcel` / `tablerUpload` 아이콘, `_excelWrapper` (zod 스키마로 컬럼 정의)
+- **메서드:** `onUploadExcelButtonClick`, `onDownloadExcelButtonClick`
+- **템플릿:** 확장 A가 도입한 inline 도구 dock 뒤쪽에 엑셀 업로드/다운로드 버튼 2개 추가
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A) 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { tablerFileExcel, tablerUpload } from "@ng-icons/tabler-icons";
+import { SdFileDialogProvider } from "@simplysm/angular";
+import { DateTime } from "@simplysm/core-common";
+import { downloadBlob } from "@simplysm/core-browser";
+import { ExcelWrapper } from "@simplysm/excel";
+import { z } from "zod";
+
+// 2) DI 추가
+private readonly _sdFileDialog = inject(SdFileDialogProvider);
+
+// 3) 클래스 필드 — 아이콘 + ExcelWrapper (zod 스키마로 컬럼 정의)
+protected readonly tablerFileExcel = tablerFileExcel;
+protected readonly tablerUpload = tablerUpload;
+
+private readonly _excelWrapper = new ExcelWrapper(
+  z.object({
+    id: z.number().optional().describe("ID"),
+    name: z.string().describe("이름"),
+    phone: z.string().optional().describe("전화번호"),
+    categoryId: z.number().optional().describe("카테고리.ID"),
+    // isDeleted는 확장 B 적용 시(DB Table에 isDeleted 컬럼이 있는 경우)에만 추가:
+    //   isDeleted: z.boolean().describe("삭제"),
+    lastModifiedAt: z.custom<DateTime>().optional().describe("최종수정일시"),
+    lastModifiedBy: z.string().optional().describe("최종수정자"),
+  }),
+);
+
+// 4) template — 확장 A가 도입한 inline 도구 dock 뒤쪽에 엑셀 버튼 2개 추가.
+//    확장 B가 함께 적용되면 동일 dock 안에 "등록 → 선택 삭제 → 선택 복구 → 엑셀 업로드 → 엑셀 다운로드" 순으로 배치한다.
+`
+  <!-- 확장 A가 도입한 도구 dock (canEdit && page 가드) -->
+  @if (canEdit() && viewType() === "page") {
+    <sd-dock class="flex-row gap-sm p-xs-default">
+      <sd-button [size]="'sm'" [theme]="'link-primary'" (click)="onAddItemButtonClick()">
+        <ng-icon [svg]="tablerCirclePlus" /> 등록
+      </sd-button>
+      <!-- 확장 B 적용 시: 선택 삭제 / 선택 복구 버튼이 여기에 위치 -->
+
+      <!-- ↓ 확장 G가 추가 -->
+      <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onUploadExcelButtonClick()">
+        <ng-icon [svg]="tablerUpload" /> 엑셀 업로드
+      </sd-button>
+      <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onDownloadExcelButtonClick()">
+        <ng-icon [svg]="tablerFileExcel" /> 엑셀 다운로드
+      </sd-button>
+    </sd-dock>
+  }
+`
+
+// 5) 메서드 추가
+async onUploadExcelButtonClick(): Promise<void> {
+  const file = await this._sdFileDialog.showAsync(false, ".xlsx");
+  if (file == null) return;
+  if (Array.isArray(file)) return;
+
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    const excelItems = await this._excelWrapper.read(file);
+    const changedIds: number[] = [];
+    await this._appOrm.connectAsync(async (db) => {
+      for (const raw of excelItems) {
+        changedIds.push(await this._upsertItem(db, raw, "엑셀업로드"));
+      }
+    });
+    await this._appSharedData.emitAsync(this.SHARED_DATA_KEY, changedIds);
+
+    this._sdToast.success("업로드되었습니다.");
+
+    await this._refresh();
+  });
+  this.busyCount.update((v) => v - 1);
+}
+
+async onDownloadExcelButtonClick(): Promise<void> {
+  if (this.busyCount() > 0) return;
+
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    // 전체 조회 (페이지네이션 없이) — 확장 A의 _search를 그대로 재사용
+    const r = await this._search(false);
+    const wb = await this._excelWrapper.write(this.viewTitle(), r.items);
+    try {
+      downloadBlob(
+        await wb.toBlob(),
+        `${this.viewTitle()}_${new DateTime().toFormatString("yyMMdd")}.xlsx`,
+      );
+    } finally {
+      await wb.close();
+    }
+  });
+  this.busyCount.update((v) => v - 1);
+}
+```
+
+**포인트:**
+
+- **다운로드는 `_search(false)`로 전체를 쿼리한다.** 페이지당 50건 제한이 걸리면 현재 페이지만 다운로드되므로 `usePagination: false`를 명시한다.
+- **업로드는 `_excelWrapper.read(file)` → `_upsertItem` 루프로 수행한다.** 확장 A의 중복 검사·감사 로그가 동일하게 적용되며, `logType: "엑셀업로드"`로 감사 로그를 구분한다. 상세 Usage는 [`SdFileDialogProvider.showAsync`](../../providers/sd-file-dialog-provider.md#usage) 참조.
+- **엑셀의 텍스트 컬럼을 FK id로 변환해야 하면** DB 재조회 대신 `useSharedSignal(...)`로 이미 로드된 공유 데이터를 `toMapValues`로 변환하여 재사용한다.
+
+**🚫 흔한 실수**
+
+> 공통 규칙(`mark` 오용, `setupCanDeactivate` 호출 위치, 시트 셀 `[inset]/[size]`, 공유 데이터 `wait()` 호출 위치 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **엑셀 업로드/다운로드 고유 실수**만 다룬다.
+
+### 필수 필드를 `z.string().optional()`로 선언
+
+```typescript
+// ✅ 필수 필드는 .optional() 없이 선언 — 빈 셀 행은 ExcelWrapper가 safeParse 단계에서 차단
+new ExcelWrapper(
+  z.object({
+    id: z.number().optional().describe("ID"),
+    name: z.string().describe("이름"),                      // ← 필수
+    phone: z.string().optional().describe("전화번호"),
+    categoryId: z.number().optional().describe("카테고리.ID"),
+  }),
+);
+```
+
+**근거**: `ExcelWrapper.read`는 각 행을 `_schema.safeParse(record)`로 검증하고 실패 시 에러를 던진다(`packages/excel/src/excel-wrapper.ts:77`). zod 스키마가 업로드 유효성의 유일한 방어선이므로, 필수 필드에 `.optional()`을 달면 검증 자체를 통과해 잘못된 값이 `_upsertItem`까지 내려간다. `isDeleted` 컬럼이 있는 테이블에서는 [공통 규칙: 삭제 방식](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다)에 따라 `isDeleted: z.boolean().describe("삭제")` 필드를 추가한다(확장 B 병용).
+
+## Cross-reference
+
+- 진입점: [crud-list.md](../crud-list.md)
+- 선행: [확장 A: inline 편집/저장](./extension-a-inline-edit.md) (`_upsertItem`/`_search`/감사 로그 재사용)
+- 병용 가능: [확장 B: 선택 기능 + 선택 삭제/복구](./extension-b-selection.md) (`isDeleted` 컬럼이 있는 테이블 — zod 스키마에 `isDeleted` 필드 추가)