@simplysm/angular 14.0.48 → 14.0.49

package/docs/recipes/crud-list.md

@@ -7,49 +7,51 @@
 - 제거된 추상화: `SdDataSheet`(컴포넌트) / `SdDataSheetBase`(추상 클래스) / `SdDataSheetColumn`(디렉티브) / `SdDataSheetItemPropInfo`·`SdDataSheetItemInfo`·`SdDataSheetSearchResult`(타입 3종) / `setupCloserWhenSingleSelectionChange`(단일 선택 시 모달 자동 닫기 유틸) / 내부 Manager 5종(`injectDataSheet{Refresh,InlineEdit,ModalEdit,Excel}Manager`, `useDataSheetFilterManager`)
 - 대체: 소비 컴포넌트가 표준 조각을 직접 조립
 - 조립 요소:
-  - `<sd-busy-container [busy] [message]>` — 전체 busy 오버레이
-  - `<sd-topbar-container>` + `<sd-topbar>` — 페이지 뷰 상단 헤더
-  - `<sd-form (formSubmit)>` — 필터 제출 / inline 편집 저장 트리거
+  - `<sd-busy-container [busy]>` — 전체 busy 오버레이
+  - `<sd-topbar-container>` + `<sd-topbar>` — 공통 컨테이너, `<sd-topbar>`는 page 뷰에서만 조건부 렌더
+  - `<sd-dock-container>` + `<sd-dock>` — 필터 / 도구 / 모달 하단 바를 dock로 부착, 본문(시트)은 main 영역
+  - `<sd-form (formSubmit)>` — 필터 제출 / inline 편집 일괄 저장 트리거
   - `<sd-sheet>` + `<sd-sheet-column>` + `<ng-template [cell]>` — 시트 본체 (items, 페이지네이션, 정렬, 선택, `cumulativeSelection`, 셀 스타일)
   - `injectViewTypeSignal()` — page / modal / control 뷰 판정
   - `injectPermsSignal()` — 권한 signal
-  - `useSortingManager()` — 정렬 def 관리 (선택적)
   - `setupCanDeactivate()` — 이탈 방지
   - `mark(sig)` — signal 참조 갱신
-  - `SdToastProvider.try(fn, messageFn)` — 에러 래퍼 + busy 카운트
-  - `SdModalProvider.showAsync(...)` — 편집 모달 호출
-  - `SdFileDialogProvider.showAsync(...)` — 엑셀 업로드 파일 선택
-  - `getOrmDataEditToastErrorMessage(err)` — ORM 에러 → 사용자 메시지 변환
+  - `SdToastProvider.try(fn)` — 에러 래퍼 (busy 카운트는 호출부에서 `busyCount.update`로 직접 제어)
+  - `SdSelectModal<T>` — 선택 모달 계약. 소비 화면이 직접 `implements`하여 `selectMode` / `selectedItemKeys` input + `close` output 노출
   - `SdCommandDirective`(`sdRefreshCommand` / `sdSaveCommand`) — Ctrl+Alt+L / Ctrl+S 단축키
+- 선택적:
+  - `SdFileDialogProvider.showAsync(...)` — 엑셀 업로드 파일 선택 (`## 7` 변형)
 - 데이터 비교:
   - `Array.prototype.oneWayDiffs(orgItems, keyFn)` (`@simplysm/core-common` side-effect import) — `ArrayOneWayDiffResult<T>[]` 반환 (`type: "create" | "update" | "same"`)
-  - `obj.equal(a, b)` — deep equal
+  - `obj.clone(items)` — snapshot 깊은 복제 (`@simplysm/core-common`)
 
 ## 2. 언제 사용하는가
 
 | 상황 | 적용 여부 |
 |---|---|
-| 필터 + 페이지네이션 + 정렬 + 선택이 있는 일반 CRUD 리스트 | 본 레시피 전체 적용 |
-| 행을 직접 수정하는 인라인 편집 화면 | 레시피 + [변형 1: inline 편집 모드](#5-변형-inline-편집-모드) |
-| 다른 화면에서 항목을 고르는 선택 모달 | 레시피 + [변형 2: 선택 모달](#6-변형-선택-모달-뷰) |
+| 필터 + 페이지네이션 + 정렬 + 선택 + inline 편집이 있는 일반 CRUD 리스트 | 본 레시피 전체 적용 (기본 예제가 page 뷰) |
+| 다른 화면에서 항목을 고르는 선택 모달로도 재사용 | 기본 예제가 page + modal 2뷰를 함께 지원 — 별도 variant 불필요 |
+| 시트 첫 열에 row별 inline 삭제/복구 버튼이 필요 | 레시피 + [변형 1: inline 삭제 열](#5-변형-inline-삭제-열) |
+| 행 클릭 시 편집 모달을 띄우는 모달 편집 모드 | 레시피 + [변형 2: 모달 편집 모드](#6-변형-모달-편집-모드) |
 | 엑셀 업로드 / 다운로드가 필요 | 레시피 + [변형 3: 엑셀 업로드·다운로드](#7-변형-엑셀-업로드다운로드) |
 | 상세 폼(단일 레코드 편집) | 본 레시피 대신 [`crud-detail.md`](./crud-detail.md) 사용 |
 | 페이지 / 모달 뷰 분기만 필요한 단순 화면 | [`page-modal-container.md`](./page-modal-container.md) 사용 |
 
 ## 3. 완성 예제
 
-아래는 **페이지 뷰 + modal 편집 모드** 기준 완성 컴포넌트다. CRUD 리스트의 가장 일반적 형태(필터 검색 → 페이지네이션 + 정렬 → 모달로 row 편집 → 선택 삭제/복구)를 커버한다. inline / 선택 모달 / 엑셀은 `## 5`~`## 7`의 변형 스니펫으로 교체·추가한다.
+아래는 **page + modal 2뷰 동시 지원 + inline 편집** 기준 완성 컴포넌트다. 하나의 화면이 라우트로 진입하면 CRUD 리스트(조회·등록·inline 수정·선택 삭제/복구)로 동작하고, `SdModalProvider.showAsync()`로 열리면 동일 화면이 "선택 모달"로 전환된다(selectMode에 따라 single/multi, 선택 결과를 `close.emit`). inline 삭제 열 / 엑셀 업로드·다운로드 / 모달로 row 편집은 `## 5`~`## 7`의 변형 스니펫으로 교체·추가한다.
 
 ```typescript
 import { NgIcon } from "@ng-icons/core";
 import {
   tablerAlertTriangle,
   tablerCirclePlus,
-  tablerEdit,
   tablerEraser,
+  tablerDeviceFloppy,
   tablerRefresh,
   tablerRestore,
   tablerSearch,
+  tablerX,
 } from "@ng-icons/tabler-icons";
 import {
   ChangeDetectionStrategy,
@@ -57,53 +59,61 @@ import {
   computed,
   effect,
   inject,
+  input,
+  output,
   signal,
   untracked,
+  viewChild,
   ViewEncapsulation,
 } from "@angular/core";
+import { ArgumentError, type DateTime, obj, str } from "@simplysm/core-common";
+import { expr } from "@simplysm/orm-common";
 import {
-  getOrmDataEditToastErrorMessage,
-  injectCurrentPageCodeSignal,
-  injectFullPageCodeSignal,
+  FormatPipe,
   injectPermsSignal,
+  injectViewTitleSignal,
   injectViewTypeSignal,
   mark,
-  SdActivatedModalProvider,
   SdAnchor,
-  SdAppStructureProvider,
   SdBusyContainer,
   SdButton,
+  SdCheckbox,
   SdCommandDirective,
+  SdDock,
+  SdDockContainer,
   SdForm,
-  SdModalProvider,
+  SdItemOfTemplate,
+  type SdSelectModal,
+  SdSharedDataSelect,
   SdSheet,
   SdSheetColumn,
   SdSheetColumnCellTemplate,
-  SdSystemLogProvider,
   SdTextfield,
   SdToastProvider,
   SdTopbar,
   SdTopbarContainer,
+  type SelectModalOutputResult,
   setupCanDeactivate,
   type SortingDef,
 } from "@simplysm/angular";
-import "@simplysm/core-common";  // Array.prototype.oneWayDiffs 등 프로토타입 확장
+// 앱별 대체: ORM/공유 데이터/인증 provider + DbContext. simplysm 패키지가 아니라 각 앱이 소유한다.
+import { AppOrmProvider, AppSharedDataProvider, useSharedSignal } from "@adtek/client-common";
+import type { MainDbContext } from "@adtek/db-main";
+import { AppAuthProvider } from "../../../providers/AppAuthProvider";
+
+interface IFilter {
+  searchText?: string;
+  isIncludeDeleted: boolean;
+}
 
 interface ICustomer {
-  id: string;
-  name: string;
-  phone: string;
+  id?: number;
+  name?: string;
+  phone?: string;
+  categoryId?: number;
   isDeleted: boolean;
-}
-
-interface ICustomerFilter {
-  search: string;
-}
-
-interface ICustomerSearchResult {
-  items: ICustomer[];
-  pageLength: number;
-  summary: Partial<ICustomer>;
+  lastModifiedAt?: DateTime;
+  lastModifiedBy?: string;
 }
 
 @Component({
@@ -113,60 +123,92 @@ interface ICustomerSearchResult {
   standalone: true,
   imports: [
     SdBusyContainer, SdTopbarContainer, SdTopbar,
+    SdDockContainer, SdDock,
     SdForm, SdSheet, SdSheetColumn, SdSheetColumnCellTemplate,
-    SdButton, SdAnchor, SdTextfield, NgIcon,
+    SdButton, SdAnchor, SdCheckbox, SdTextfield,
+    SdSharedDataSelect, SdItemOfTemplate,
+    NgIcon, FormatPipe,
   ],
   hostDirectives: [
-    { directive: SdCommandDirective, outputs: ["sdRefreshCommand"] },
+    { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
   ],
   host: {
     "(sdRefreshCommand)": "onRefreshButtonClick()",
+    "(sdSaveCommand)": "onSaveButtonClick()",
   },
   template: `
-    <sd-busy-container [busy]="busyCount() > 0" [message]="busyMessage()">
+    <sd-busy-container [busy]="busyCount() > 0">
       @if (initialized()) {
         @if (!canUse()) {
           <div class="fill tx-theme-gray-light p-xxl tx-center">
             <br />
-            <ng-icon [svg]="icons.tablerAlertTriangle" [size]="'5em'" />
-            <br /><br />
-            '{{ modalOrPageTitle() }}'에 대한 사용권한이 없습니다. 시스템 관리자에게 문의하세요.
+            <ng-icon [svg]="tablerAlertTriangle" [size]="'5em'" />
+            <br />
+            <br />
+            '{{ viewTitle() }}'에 대한 사용권한이 없습니다. 시스템 관리자에게 문의하세요.
           </div>
-        } @else if (viewType() === "page") {
+        } @else {
           <sd-topbar-container>
-            <sd-topbar>
-              <h4>{{ modalOrPageTitle() }}</h4>
-              <sd-button [theme]="'link-info'" (click)="onRefreshButtonClick()">
-                <ng-icon [svg]="icons.tablerRefresh" />
-                새로고침 <small>(CTRL+ALT+L)</small>
-              </sd-button>
-            </sd-topbar>
-
-            <div class="flex-column fill">
-              <!-- 필터 영역 -->
-              <div class="p-default">
+            @if (viewType() === "page") {
+              <sd-topbar>
+                <h4>{{ viewTitle() }}</h4>
+
+                <sd-button [theme]="'link-info'" (click)="onRefreshButtonClick()">
+                  <ng-icon [svg]="tablerRefresh" />
+                  새로고침
+                  <small>(CTRL+ALT+L)</small>
+                </sd-button>
+                @if (canEdit()) {
+                  <sd-button [theme]="'link-primary'" (click)="onSaveButtonClick()">
+                    <ng-icon [svg]="tablerDeviceFloppy" />
+                    저장
+                    <small>(CTRL+S)</small>
+                  </sd-button>
+                }
+              </sd-topbar>
+            }
+
+            <sd-dock-container>
+              <!-- 필터 -->
+              <sd-dock class="p-default">
                 <sd-form (formSubmit)="onFilterSubmit()">
                   <div class="form-box-inline">
-                    <sd-button [type]="'submit'" [theme]="'info'">
-                      <ng-icon [svg]="icons.tablerSearch" />
-                      조회
-                    </sd-button>
-                    <sd-textfield
-                      [type]="'text'"
-                      [placeholder]="'이름/전화번호 검색'"
-                      [(value)]="filterSearch"
-                      [inset]="true"
-                      [size]="'sm'"
-                    />
+                    <div class="form-box-item">
+                      <sd-button [type]="'submit'" [theme]="'info'">
+                        <ng-icon [svg]="tablerSearch" />
+                        조회
+                      </sd-button>
+                    </div>
+                    <div class="form-box-item">
+                      <label>검색어</label>
+                      <sd-textfield
+                        [type]="'text'"
+                        [placeholder]="'이름/전화번호'"
+                        [(value)]="filter().searchText"
+                        (valueChange)="mark(filter)"
+                      />
+                    </div>
+                    <div class="form-box-item">
+                      <sd-checkbox
+                        [(value)]="filter().isIncludeDeleted"
+                        (valueChange)="mark(filter)"
+                      >
+                        삭제항목 포함
+                      </sd-checkbox>
+                    </div>
                   </div>
                 </sd-form>
-              </div>
+              </sd-dock>
 
-              <!-- 도구 영역 -->
-              @if (canEdit()) {
-                <div class="flex-row gap-sm p-xs-default">
-                  <sd-button [size]="'sm'" [theme]="'link-primary'" (click)="onCreateItemButtonClick()">
-                    <ng-icon [svg]="icons.tablerCirclePlus" />
+              <!-- 도구 (inline 편집용, 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>
                   <sd-button
@@ -175,7 +217,7 @@ interface ICustomerSearchResult {
                     (click)="onToggleDeleteItemsButtonClick(true)"
                     [disabled]="!hasSelectedNotDeleted()"
                   >
-                    <ng-icon [svg]="icons.tablerEraser" />
+                    <ng-icon [svg]="tablerEraser" />
                     선택 삭제
                   </sd-button>
                   @if (hasSelectedDeleted()) {
@@ -184,224 +226,428 @@ interface ICustomerSearchResult {
                       [theme]="'link-warning'"
                       (click)="onToggleDeleteItemsButtonClick(false)"
                     >
-                      <ng-icon [svg]="icons.tablerRestore" />
+                      <ng-icon [svg]="tablerRestore" />
                       선택 복구
                     </sd-button>
                   }
-                </div>
+                </sd-dock>
               }
 
-              <!-- 시트 -->
-              <sd-sheet
-                [key]="'customer-list-sheet'"
-                [items]="items()"
-                [(currentPage)]="page"
-                [totalPageCount]="pageLength()"
-                [(sorts)]="sortingDefs"
-                [selectMode]="'multi'"
-                [(selectedItems)]="selectedItems"
-                [trackByFn]="trackByFn"
-                [getItemCellStyleFn]="getItemCellStyleFn"
-                class="flex-fill p-default pt-0"
-              >
-                <sd-sheet-column [key]="'name'" [header]="'이름'" [width]="'200px'">
-                  <ng-template [cell]="items()" let-item="item">
-                    <sd-anchor (click)="onEditItemButtonClick(item, $event)" class="flex-row">
-                      <div class="p-xs-sm">
-                        <ng-icon [svg]="icons.tablerEdit" />
+              <!-- 시트 (main 영역) -->
+              <sd-form #formCtrl (formSubmit)="onSubmit()" class="block fill p-default pt-0">
+                <sd-sheet
+                  [key]="'customer-list-sheet'"
+                  [items]="items()"
+                  [(currentPage)]="page"
+                  [totalPageCount]="pageLength()"
+                  [(sorts)]="sortingDefs"
+                  [selectMode]="selectMode() ?? 'multi'"
+                  [(selectedItems)]="selectedItems"
+                  [trackByFn]="trackByFn"
+                  [getItemCellStyleFn]="getItemCellStyleFn"
+                  [cumulativeSelection]="viewType() === 'modal' && selectMode() === 'multi'"
+                >
+                  <sd-sheet-column [fixed]="true" [key]="'id'" [header]="'#'">
+                    <ng-template [cell]="items()" let-item="item">
+                      <div
+                        class="p-xs-sm"
+                        [class.tx-right]="item.id"
+                        [style.background]="getIsItemChanged(item) ? 'yellow' : ''"
+                      >
+                        @if (item.id) {
+                          {{ item.id }}
+                        } @else if (canEdit()) {
+                          <sd-anchor (click)="onRemoveNewItemButtonClick(item)">
+                            <ng-icon [svg]="tablerX" />
+                          </sd-anchor>
+                        }
+                      </div>
+                    </ng-template>
+                  </sd-sheet-column>
+
+                  <sd-sheet-column [key]="'name'" [header]="'이름'">
+                    <ng-template [cell]="items()" let-item="item" let-edit="edit">
+                      <sd-textfield
+                        [type]="'text'"
+                        [inset]="true"
+                        [size]="'sm'"
+                        [required]="true"
+                        [disabled]="!canEdit()"
+                        [readonly]="!edit"
+                        [(value)]="item.name"
+                        (valueChange)="mark(items)"
+                      />
+                    </ng-template>
+                  </sd-sheet-column>
+
+                  <sd-sheet-column [key]="'phone'" [header]="'전화번호'">
+                    <ng-template [cell]="items()" let-item="item" let-edit="edit">
+                      <sd-textfield
+                        [type]="'text'"
+                        [inset]="true"
+                        [size]="'sm'"
+                        [disabled]="!canEdit()"
+                        [readonly]="!edit"
+                        [(value)]="item.phone"
+                        (valueChange)="mark(items)"
+                      />
+                    </ng-template>
+                  </sd-sheet-column>
+
+                  <sd-sheet-column [key]="'categoryId'" [header]="'카테고리'">
+                    <ng-template [cell]="items()" let-item="item">
+                      <sd-shared-data-select
+                        [inset]="true"
+                        [size]="'sm'"
+                        [disabled]="!canEdit()"
+                        [items]="sharedCategories.items()"
+                        [(value)]="item.categoryId"
+                        (valueChange)="mark(items)"
+                      >
+                        <ng-template [itemOf]="sharedCategories.items()" let-cat>
+                          {{ cat.name }}
+                        </ng-template>
+                      </sd-shared-data-select>
+                    </ng-template>
+                  </sd-sheet-column>
+
+                  <sd-sheet-column [key]="'lastModifiedAt'" [header]="'수정일시'" [hidden]="true">
+                    <ng-template [cell]="items()" let-item="item">
+                      <div class="p-xs-sm tx-center">
+                        {{ item.lastModifiedAt | format: "yyyy-MM-dd HH:mm" }}
                       </div>
-                      <div class="flex-fill p-xs-sm">{{ item.name }}</div>
-                    </sd-anchor>
-                  </ng-template>
-                </sd-sheet-column>
-                <sd-sheet-column [key]="'phone'" [header]="'전화번호'">
-                  <ng-template [cell]="items()" let-item="item">
-                    <div class="p-xs-sm">{{ item.phone }}</div>
-                  </ng-template>
-                </sd-sheet-column>
-              </sd-sheet>
-            </div>
+                    </ng-template>
+                  </sd-sheet-column>
+
+                  <sd-sheet-column [key]="'lastModifiedBy'" [header]="'수정자'" [hidden]="true">
+                    <ng-template [cell]="items()" let-item="item">
+                      <div class="p-xs-sm tx-center">{{ item.lastModifiedBy }}</div>
+                    </ng-template>
+                  </sd-sheet-column>
+                </sd-sheet>
+              </sd-form>
+
+              <!-- 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>
+              }
+            </sd-dock-container>
           </sd-topbar-container>
-        } @else if (viewType() === "modal") {
-          <!-- 모달 뷰 분기는 변형 2 "선택 모달" 참조 -->
-        } @else {
-          <!-- control 뷰: 다른 화면의 영역으로 삽입될 때 -->
         }
       }
     </sd-busy-container>
   `,
 })
-export class CustomerListPage {
+export class CustomerListPage implements SdSelectModal<ICustomer> {
   //== DI ==
+  private readonly _appOrm = inject(AppOrmProvider);
+  private readonly _appAuth = inject(AppAuthProvider);
+  private readonly _appSharedData = inject(AppSharedDataProvider);
   private readonly _sdToast = inject(SdToastProvider);
-  private readonly _sdModal = inject(SdModalProvider);
-  private readonly _sdActivatedModal = inject(SdActivatedModalProvider, { optional: true });
-  private readonly _sdAppStructure = inject(SdAppStructureProvider);
-  private readonly _sdSystemLog = inject(SdSystemLogProvider);
-
-  //== 라우팅 / 권한 ==
-  private readonly _fullPageCode = injectFullPageCodeSignal();
-  private readonly _currPageCode = injectCurrentPageCodeSignal();
-  protected readonly viewType = injectViewTypeSignal();
-  protected readonly canUse = injectPermsSignal(
-    () => ["sales.customer"],
-    () => ["use"],
-  );
-  protected readonly canEdit = injectPermsSignal(
-    () => ["sales.customer"],
-    () => ["edit"],
-  );
+
+  //== SdSelectModal<ICustomer> 계약 ==
+  selectMode = input<"single" | "multi" | undefined>();
+  selectedItemKeys = input<(number | undefined)[]>([]);
+  close = output<SelectModalOutputResult<ICustomer> | undefined>();
+
+  //== viewChild ==
+  formCtrl = viewChild<SdForm>("formCtrl");
+
+  //== 식별 / 권한 ==
+  SHARED_DATA_KEY = "고객" as const;
+
+  perms = injectPermsSignal(["sales.customer"], ["use", "edit"]);
+  canUse = computed(() => this.perms().includes("use"));
+  canEdit = computed(() => this.perms().includes("edit") && this.viewType() === "page");
+
+  viewType = injectViewTypeSignal();
+  viewTitle = injectViewTitleSignal();
+
+  //== 공유 데이터 ==
+  sharedCategories = useSharedSignal("카테고리");
 
   //== 상태 ==
-  protected readonly busyCount = signal(0);
-  protected readonly busyMessage = signal<string | undefined>(undefined);
-  protected readonly initialized = signal(false);
-
-  protected readonly items = signal<ICustomer[]>([]);
-  protected readonly summaryData = signal<Partial<ICustomer>>({});
-  protected readonly selectedItems = signal<ICustomer[]>([]);
-  protected readonly page = signal(0);
-  protected readonly pageLength = signal(0);
-  protected readonly sortingDefs = signal<SortingDef[]>([{ key: "name", desc: false }]);
-  protected readonly filterSearch = signal("");
-  private readonly _lastFilter = signal<ICustomerFilter>({ search: "" });
-  private _snapshot: ICustomer[] = [];
+  initialized = signal(false);
+  busyCount = signal(0);
 
-  //== 파생 ==
-  protected readonly modalOrPageTitle = computed(() => {
-    try {
-      return (
-        this._sdActivatedModal?.modalComponent()?.title() ??
-        this._sdAppStructure.getTitleByFullCode(this._currPageCode?.() ?? this._fullPageCode())
-      );
-    } catch (err) {
-      void this._sdSystemLog.writeAsync("warn", `title 계산 실패: ${String(err)}`);
-      return "";
-    }
-  });
+  private _itemsSnapshot: ICustomer[] = [];
+  items = signal<ICustomer[]>([]);
+  selectedItems = signal<ICustomer[]>([]);
+  diffs = computed(() => this.items().oneWayDiffs(this._itemsSnapshot, "id"));
 
-  protected readonly hasSelectedDeleted = computed(() =>
-    this.selectedItems().some((it) => it.isDeleted),
-  );
-  protected readonly hasSelectedNotDeleted = computed(() =>
-    this.selectedItems().some((it) => !it.isDeleted),
-  );
+  page = signal(0);
+  pageLength = signal(0);
+  sortingDefs = signal<SortingDef[]>([]);
 
-  protected readonly trackByFn = (item: ICustomer): string => item.id;
+  filter = signal<IFilter>({ isIncludeDeleted: false });
+  lastFilter = signal<IFilter>({ isIncludeDeleted: false });
 
-  protected readonly getItemCellStyleFn = (item: ICustomer): string | undefined =>
-    item.isDeleted ? "text-decoration: line-through;" : undefined;
+  //== 파생 ==
+  hasSelectedDeleted = computed(() => this.selectedItems().some((it) => it.isDeleted));
+  hasSelectedNotDeleted = computed(() => this.selectedItems().some((it) => !it.isDeleted));
 
-  protected readonly icons = {
-    tablerAlertTriangle, tablerCirclePlus, tablerEdit, tablerEraser,
-    tablerRefresh, tablerRestore, tablerSearch,
-  };
+  //== 시트 fn ==
+  trackByFn = (item: ICustomer) => item.id;
+  getItemCellStyleFn = (item: ICustomer): string | undefined =>
+    item.isDeleted ? "text-decoration: line-through;" : undefined;
 
-  //== 라이프사이클 ==
   constructor() {
-    // 최초 로딩 + 필터/페이지/정렬 변경 시 재조회
+    // 필터/페이지/정렬/perms 변경 시 재조회
     effect(() => {
-      this._lastFilter();
+      if (!this.canUse()) {
+        this.initialized.set(true);
+        return;
+      }
+
+      this.lastFilter();
       this.page();
       this.sortingDefs();
-      if (!this.canUse()) return;
+
+      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);
+      });
+    });
+
+    // 모달 뷰: selectedItemKeys → selectedItems 복원
+    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(() => {
-        void this._refresh();
+        const sel = currItems.filter((it) => keys.includes(this.trackByFn(it)));
+        if (sel.length > 0) this.selectedItems.set(sel);
       });
     });
 
     setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
   }
 
-  //== 메서드 ==
-  protected onFilterSubmit(): void {
+  getIsItemChanged(item: ICustomer): boolean {
+    if (item.id == null) return true;
+    return this.diffs().some((diff) => diff.item.id === item.id);
+  }
+
+  //== Handlers ==
+  onFilterSubmit(): void {
     this.page.set(0);
-    this._lastFilter.set({ search: this.filterSearch() });
+    this.lastFilter.set({ ...this.filter() });
   }
 
-  protected onRefreshButtonClick(): void {
+  onRefreshButtonClick(): void {
     if (this.busyCount() > 0) return;
     if (!this.canUse()) return;
     if (!this._checkIgnoreChanges()) return;
-    mark(this._lastFilter); // 참조만 갱신 → effect 재실행
-  }
 
-  protected async onCreateItemButtonClick(): Promise<void> {
-    await this._editItem();
+    mark(this.lastFilter);
   }
 
-  protected async onEditItemButtonClick(item: ICustomer, event: MouseEvent): Promise<void> {
-    event.preventDefault();
-    event.stopPropagation();
-    await this._editItem(item);
+  onSaveButtonClick(): void {
+    this.formCtrl()?.requestSubmit();
   }
 
-  protected async onToggleDeleteItemsButtonClick(del: boolean): Promise<void> {
+  async onSubmit(): Promise<void> {
+    if (this.busyCount() > 0) return;
+
+    const diffs = this.diffs();
+    if (diffs.length === 0) {
+      this._sdToast.info("변경사항이 없습니다.");
+      return;
+    }
+
+    this.busyCount.update((v) => v + 1);
     await this._sdToast.try(async () => {
-      this.busyCount.update((v) => v + 1);
-      try {
-        // 서버 호출 (앱별 구현):
-        //   await this._api.toggleDeleteAsync(this.selectedItems().map((it) => it.id), del);
-        await this._refresh();
-      } finally {
-        this.busyCount.update((v) => v - 1);
-      }
-    }, getOrmDataEditToastErrorMessage);
+      const changedIds: number[] = [];
+      await this._appOrm.connectAsync(async (db) => {
+        for (const diff of diffs) {
+          const changedId = await this._upsertItem(
+            db,
+            diff.item,
+            diff.type === "create" ? "등록" : "수정",
+          );
+          changedIds.push(changedId);
+        }
+      });
+      await this._appSharedData.emitAsync(this.SHARED_DATA_KEY, changedIds);
+
+      this._sdToast.success("저장되었습니다.");
+
+      await this._refresh();
+    });
+
+    this.busyCount.update((v) => v - 1);
   }
 
-  private _checkIgnoreChanges(): boolean {
-    return this._getDiffs().length === 0
-      || confirm("변경사항이 있습니다. 무시하고 진행하시겠습니까?");
+  onAddItemButtonClick(): void {
+    this.items.update((list) => [{ isDeleted: false }, ...list]);
+  }
+
+  onRemoveNewItemButtonClick(item: ICustomer): void {
+    this.items.update((list) => list.filter((it) => it !== item));
+  }
+
+  onToggleDeleteItemsButtonClick(del: boolean): void {
+    for (const it of this.selectedItems()) it.isDeleted = del;
+    mark(this.items);
+  }
+
+  onModalConfirmClick(): void {
+    const sel = this.selectedItems();
+    this.close.emit({
+      selectedItemKeys: sel.map((it) => this.trackByFn(it)).filterExists(),
+      selectedItems: sel,
+    });
+  }
+
+  onModalCancelClick(): void {
+    this.selectedItems.set([]);
+
+    if (this.selectMode() === "single") {
+      this.close.emit({ selectedItemKeys: [], selectedItems: [] });
+    }
   }
 
-  private _getDiffs() {
-    return this.items().oneWayDiffs(this._snapshot, "id");
+  //== Internals ==
+  private _checkIgnoreChanges(): boolean {
+    return this.diffs().length === 0 || confirm("변경사항이 있습니다. 무시하고 진행하시겠습니까?");
   }
 
+  // 로드+snapshot만 담당. busy/try는 호출부에서 처리.
   private async _refresh(): Promise<void> {
-    await this._sdToast.try(async () => {
-      this.busyCount.update((v) => v + 1);
-      try {
-        const r = await this._fetchList(this._lastFilter(), this.page(), this.sortingDefs());
-        this.items.set(r.items);
-        this.pageLength.set(r.pageLength);
-        this.summaryData.set(r.summary);
-        // 선택 유지 (현재 items에 없는 item 제외)
-        const currKeys = new Set(r.items.map((it) => this.trackByFn(it)));
-        this.selectedItems.update((sel) =>
-          sel.filter((it) => currKeys.has(this.trackByFn(it))),
-        );
-        this._snapshot = r.items.map((it) => ({ ...it }));
-        this.initialized.set(true);
-      } finally {
-        this.busyCount.update((v) => v - 1);
-      }
-    }, getOrmDataEditToastErrorMessage);
+    const r = await this._search(true);
+    this.items.set(r.items);
+    this.pageLength.set(r.pageLength);
+
+    const currKeys = new Set(r.items.map((it) => this.trackByFn(it)));
+    this.selectedItems.update((sel) => sel.filter((it) => currKeys.has(this.trackByFn(it))));
+
+    this._itemsSnapshot = obj.clone(r.items);
   }
 
-  private async _editItem(item?: ICustomer): Promise<void> {
-    // 편집 모달 (소비 앱이 구현한 CustomerEditModal 사용):
-    //   const r = await this._sdModal.showAsync({
-    //     title: item == null ? "고객 등록" : "고객 수정",
-    //     type: CustomerEditModal,
-    //     inputs: { itemId: item?.id },
-    //   });
-    //   if (r != null) await this._refresh();
+  private async _search(
+    usePagination: boolean,
+  ): Promise<{ items: ICustomer[]; pageLength: number }> {
+    const filter = this.lastFilter();
+    const sortingDefs = this.sortingDefs();
+    const page = this.page();
+
+    return this._appOrm.connectAsync(async (db) => {
+      let qr1 = db.customer();
+
+      if (!str.isNullOrEmpty(filter.searchText)) {
+        qr1 = qr1.search((item) => [item.name, item.phone], filter.searchText);
+      }
+      if (!filter.isIncludeDeleted) {
+        qr1 = qr1.where((item) => [expr.eq(item.isDeleted, false)]);
+      }
+
+      const pageLength = usePagination ? Math.ceil((await qr1.count()) / 50) : 0;
+
+      let qr2 = qr1.joinLastDataLog().select((item) => ({
+        id: item.id,
+        name: item.name,
+        phone: item.phone,
+        categoryId: item.categoryId,
+        isDeleted: item.isDeleted,
+        lastModifiedAt: item.lastDataLog?.dateTime,
+        lastModifiedBy: item.lastDataLog?.userName,
+      }));
+
+      for (const sortingDef of sortingDefs) {
+        qr2 = qr2.orderBy(sortingDef.key, sortingDef.desc ? "DESC" : "ASC");
+      }
+      if (!sortingDefs.some((s) => s.key === "name")) {
+        qr2 = qr2.orderBy((item) => item.name);
+      }
+
+      if (usePagination) {
+        qr2 = qr2.limit(page * 50, 50);
+      }
+
+      const items = await qr2.execute();
+      return { items, pageLength };
+    });
   }
 
-  private async _fetchList(
-    filter: ICustomerFilter,
-    page: number,
-    sortingDefs: SortingDef[],
-  ): Promise<ICustomerSearchResult> {
-    // 예시 (orm-common):
-    //   let qr = this._dbCtx.customer.where((it) => ... filter.search ... );
-    //   for (const s of sortingDefs) qr = qr.orderBy(s.key, s.desc ? "DESC" : "ASC");
-    //   const items = await qr.limit(page * 50, 50).resultAsync();
-    //   const pageLength = Math.ceil((await qr.countAsync()) / 50);
-    //   return { items, pageLength, summary: {} };
-    throw new Error("구현 필요");
+  private async _upsertItem(
+    db: MainDbContext,
+    item: ICustomer,
+    logType: string,
+  ): Promise<number> {
+    if (
+      !item.isDeleted &&
+      (await db
+        .customer()
+        .where((c) => [
+          expr.eq(c.name, item.name),
+          expr.not(expr.eq(c.id, item.id)),
+          expr.eq(c.isDeleted, false),
+        ])
+        .exists())
+    ) {
+      throw new ArgumentError("동일한 명칭이 이미 등록되어 있습니다.", { 명칭: item.name });
+    }
+
+    const upsertResult = await db
+      .customer()
+      .where((c) => [expr.eq(c.id, item.id)])
+      .upsert(
+        () => ({
+          name: item.name!,
+          phone: item.phone,
+          categoryId: item.categoryId,
+          isDeleted: item.isDeleted,
+        }),
+        ["id"],
+      );
+    const upsertId = upsertResult[0].id;
+
+    await db.customer().insertDataLogAsync({
+      type: logType,
+      itemId: upsertId,
+      valueJson: undefined,
+      userId: this._appAuth.authInfo()!.user.id,
+    });
+
+    return upsertId;
   }
+
+  //== 아이콘 ==
+  protected readonly tablerAlertTriangle = tablerAlertTriangle;
+  protected readonly tablerCirclePlus = tablerCirclePlus;
+  protected readonly tablerDeviceFloppy = tablerDeviceFloppy;
+  protected readonly tablerEraser = tablerEraser;
+  protected readonly tablerRefresh = tablerRefresh;
+  protected readonly tablerRestore = tablerRestore;
+  protected readonly tablerSearch = tablerSearch;
+  protected readonly tablerX = tablerX;
+  protected readonly mark = mark;
 }
 ```
 
@@ -411,317 +657,308 @@ export class CustomerListPage {
 
 | 블록 | 역할 | 원본 대응 |
 |---|---|---|
-| `<sd-busy-container [busy] [message]>` | 전체 busy 오버레이 | `sd-data-sheet.ts:65-71` + `SdBaseContainer` |
-| `@if (initialized())` | 초기 데이터 로딩 전 콘텐츠 숨김 (깜박임 방지) | `sd-data-sheet.base.ts:94`·`_refresh()` 말미 `initialized.set(true)` |
+| `<sd-busy-container [busy]>` | 전체 busy 오버레이 | `sd-data-sheet.ts:65-71` + `SdBaseContainer` |
+| `@if (initialized())` | 초기 데이터 로딩 전 콘텐츠 숨김 (깜박임 방지) | `sd-data-sheet.base.ts:94`·initial effect 말미 `initialized.set(true)` |
 | `@if (!canUse())` | 권한 없음 메시지 | `sd-base-container.ts:44-51` + `page-modal-container.md` |
-| `@if (viewType() === "page")` / `"modal"` / else | 뷰 타입 분기 (`page-modal-container.md` 참조) | `sd-data-sheet.ts:65` `viewType` → `SdBaseContainer` 내부 분기 |
-| `<sd-topbar-container>` + `<sd-topbar>` | 페이지 뷰 헤더 | `sd-data-sheet.ts:72-87` `pageTopbarTpl` |
-| `<sd-form (formSubmit)>` + `form-box-inline` | 필터 제출 폼 | `sd-data-sheet.ts:111-125` 필터 슬롯 |
-| 도구 영역 (`<sd-button size=sm theme=link-*>`) | 등록 / 선택 삭제 / 선택 복구 | `sd-data-sheet.ts:127-203` 도구 영역 |
-| `<sd-sheet>` + `<sd-sheet-column>` + `<ng-template [cell]>` | 시트 본체, 셀 렌더링 | `sd-data-sheet.ts:205-346` |
-| `[cell]` 템플릿의 `<sd-anchor (click)>` | 셀 클릭 → 편집 모달 진입 | `sd-data-sheet.ts:284-315` |
+| `<sd-topbar-container>` 공통 껍데기 + `@if (viewType() === "page")` 내부 `<sd-topbar>` | page 뷰만 topbar 표시, modal/control은 topbar 없는 컨테이너로 사용 | `sd-data-sheet.ts:65-87` `pageTopbarTpl` |
+| `<sd-dock-container>` + `<sd-dock>` (필터 / inline 도구 / modal 하단 바) | 필터·도구·modal 하단 바를 dock로 부착, 본문(`<sd-form>` + `<sd-sheet>`)은 main 영역 | `sd-data-sheet.ts:89-203` |
+| `<sd-form (formSubmit)>` + `form-box-inline` + `form-box-item` | 필터 제출 폼 — 각 입력을 `<div class="form-box-item">`로 감싸 label/버튼 배치 | `sd-data-sheet.ts:111-125` 필터 슬롯 |
+| inline 도구 `<sd-dock>` (page 뷰 + canEdit에만) | 등록 / 선택 삭제 / 선택 복구 | `sd-data-sheet.ts:127-203` 도구 영역 |
+| `<sd-form #formCtrl (formSubmit)="onSubmit()">` + `<sd-sheet>` | main 영역의 일괄 저장 form + 시트 본체 | `sd-data-sheet.ts:205-346` + `inline-edit` 매니저 |
+| `[cell]` 템플릿의 `let-edit="edit"` + `[readonly]="!edit"` | inline 편집 가능 셀 (`[inset]="true" [size]="'sm'"` 필수) | — |
 | `getItemCellStyleFn` | `isDeleted` 시 취소선 | `sd-data-sheet.base.ts:137-140` |
+| modal 하단 `<sd-dock [position]="'bottom'">` | 모달 뷰에서만 "선택 해제 / 확인" 바 노출 | `sd-data-sheet.ts:287-315` 모달 하단 바 |
 | `hostDirectives` + `SdCommandDirective` | Ctrl+Alt+L / Ctrl+S 단축키 | `sd-data-sheet.ts:57-63` |
 | `setupCanDeactivate(() => viewType() === "modal" || checkIgnoreChanges())` | 라우트 이탈 시 변경사항 확인 | `sd-data-sheet.base.ts:227` |
-| `_refresh()` 내 `busyCount.update + try/finally + sdToast.try` | busy 카운트 증감 + 에러 토스트 | `injectDataSheetRefreshManager.ts:33-46` (삭제됨) |
-| `_getDiffs()` = `items.oneWayDiffs(snapshot, "id")` | 변경 감지 | `injectDataSheetRefreshManager.ts`의 `getDiffs()` (삭제됨) |
-| `effect(() => { lastFilter(); page(); sortingDefs(); ... })` | 필터/페이지/정렬 변경 시 재조회 | `injectDataSheetRefreshManager.ts` (삭제됨) |
-| `mark(this._lastFilter)` | lastFilter 참조 갱신 → effect 재실행 (값 변경 없음) | `sd-data-sheet.base.ts:245` |
-| `modalOrPageTitle` computed | `modal title ?? app structure title` | `sd-base-container.ts:102-113` (`header ??` 부분은 필요 시 `input()` 추가) |
+| 호출부(`onRefresh`/`onSubmit`/초기 effect) 내 `busyCount.update` + `sdToast.try(...)` | busy 카운트 증감 + 에러 토스트 래핑 | `injectDataSheetRefreshManager.ts:33-46` (삭제됨) |
+| `diffs = computed(() => items.oneWayDiffs(_itemsSnapshot, "id"))` | 변경 감지 signal — 템플릿·호출부 모두에서 `this.diffs()`로 참조 | `injectDataSheetRefreshManager.ts`의 `getDiffs()` (삭제됨) |
+| `effect(() => { if (!canUse()) ...; lastFilter(); page(); sortingDefs(); untracked(async ...); })` | 필터/페이지/정렬/perms 변경 시 재조회 + 초기 로드 | `injectDataSheetRefreshManager.ts` (삭제됨) |
+| `effect(() => { if (viewType() !== "modal") return; selectedItemKeys() → selectedItems })` | 모달 뷰 초기 selection 복원 | `sd-data-sheet.base.ts:165-183` |
+| `mark(this.lastFilter)` | lastFilter 참조 갱신 → effect 재실행 (값 변경 없음) | `sd-data-sheet.base.ts:245` |
 
 ### 상태 분해
 
 | signal / computed | 역할 |
 |---|---|
 | `busyCount` | 중첩 비동기 작업 카운트 (0 초과 시 busy 표시) |
-| `busyMessage` | busy 오버레이 문구 |
 | `initialized` | 최초 조회 완료 여부 (완료 전 본문 숨김) |
 | `items` | 현재 페이지 items |
-| `summaryData` | 서버가 반환한 합계·집계 (선택적으로 시트 summary row에 표시) |
 | `selectedItems` | 선택된 item 배열 (`<sd-sheet [(selectedItems)]>`로 양방향) |
+| `diffs` | `computed(() => items().oneWayDiffs(_itemsSnapshot, "id"))` — 변경 감지 signal. 템플릿(`getIsItemChanged`)·호출부(`onSubmit`·`_checkIgnoreChanges`) 모두에서 `diffs()`로 참조 |
 | `page` / `pageLength` | 0-based 현재 페이지 / 전체 페이지 수 |
 | `sortingDefs` | `SortingDef[]` — `{ key: string; desc: boolean }[]`, `<sd-sheet [(sorts)]>`로 양방향 |
-| `filterSearch` / `_lastFilter` | filter는 입력 버퍼, lastFilter는 "조회" 제출 시점 스냅샷 |
-| `_snapshot` | 최근 `_refresh()` 시점의 items 복사본 (변경 감지용) |
+| `filter` / `lastFilter` | `filter`는 입력 버퍼, `lastFilter`는 "조회" 제출 시점 스냅샷 (effect 의존성) |
+| `_itemsSnapshot` | 최근 `_refresh()` 시점의 items 깊은 복제 (변경 감지용) |
+| `hasSelectedDeleted` / `hasSelectedNotDeleted` | 선택 항목의 삭제 상태 — 선택 삭제/복구 버튼 조건 |
+| `perms` / `canUse` / `canEdit` | 권한. `canEdit`은 page 뷰 + edit 권한일 때만 true (modal에선 항상 false) |
+| `close` (output) | `SdSelectModal<T>` 요구 — 모달 결과 전달 |
 
 ### 메서드 분해
 
 | 메서드 | 역할 |
 |---|---|
-| `onFilterSubmit()` | page=0 리셋 + `_lastFilter.set(filter 스냅샷)` |
-| `onRefreshButtonClick()` | busy/권한/변경사항 확인 후 `mark(_lastFilter)` |
-| `_refresh()` | search → items.set + pageLength + summary + 선택 유지 + snapshot 갱신 |
-| `_editItem(item?)` | `SdModalProvider.showAsync(...)`로 편집 모달 실행 후 refresh |
-| `onToggleDeleteItemsButtonClick(del)` | 선택 item ID들을 서버에 전송하여 isDeleted 토글 + refresh |
-| `_checkIgnoreChanges()` | snapshot 대비 diff 없으면 true, 있으면 `confirm` 후 true/false |
-| `_getDiffs()` | `items.oneWayDiffs(_snapshot, "id")` — `ArrayOneWayDiffResult<T>[]` |
-
-## 5. 변형: inline 편집 모드
-
-행을 직접 수정하고 `ArrayOneWayDiffResult` 기반 diff로 일괄 저장한다. `CustomerListPage`를 기준으로 아래 변경을 적용한다:
+| `onFilterSubmit()` | page=0 리셋 + `lastFilter.set({ ...filter() })` |
+| `onRefreshButtonClick()` | busy/권한/변경사항 확인 후 `mark(lastFilter)` — 참조 갱신으로 effect 재실행 |
+| `onSaveButtonClick()` | `formCtrl()?.requestSubmit()` — Ctrl+S와 동일 경로. `host`의 `sdSaveCommand`와 어휘 일치 |
+| `onSubmit()` | diff 0건이면 정보 토스트 → `busyCount` 증가 → `_sdToast.try(diff 일괄 upsert + emit + _refresh)` → `busyCount` 감소 |
+| `onAddItemButtonClick()` | `items.update((list) => [{ isDeleted: false }, ...list])` — 신규 행을 맨 앞에 삽입 |
+| `onToggleDeleteItemsButtonClick(del)` | 선택 항목의 `isDeleted = del` 토글 + `mark(items)`. 실제 DB 반영은 저장 버튼 클릭 시 `onSubmit`에서 일괄 처리 |
+| `onModalConfirmClick()` / `onModalCancelClick()` | 모달 결과 emit. 취소는 `selectMode === "single"`일 때만 즉시 close |
+| `_checkIgnoreChanges()` | `diffs()` 길이 0이면 true, 아니면 `confirm` 후 true/false |
+| `getIsItemChanged(item)` | row 하이라이트 판정 — `item.id == null`(신규) 또는 `diffs()`에 해당 id가 포함되면 true |
+| `onRemoveNewItemButtonClick(item)` | 저장 전 신규 row(`id == null`) 제거 — reference 기반 `filter((it) => it !== item)` |
+| `_refresh()` | `_search(true)` → `items.set` + `pageLength.set` + 선택 유지 + `_itemsSnapshot = obj.clone(r.items)`. busy/try는 호출부 책임 |
+| `_search(usePagination)` | ORM 쿼리 (filter/sort/limit) — `_refresh`와 엑셀 다운로드 등에서 재사용 |
+| `_upsertItem(db, item, logType)` | 중복 검사 → `upsert(() => record, ["id"])` → `insertDataLogAsync` |
+
+## 5. 변형: inline 삭제 열
+
+기본 예제는 상단 "선택 삭제 / 선택 복구" 버튼만 사용하지만, row별 inline 삭제/복구 버튼을 함께 제공하고 싶으면 시트 맨 앞 고정 컬럼에 `<sd-anchor>`를 추가한다. `CustomerListPage`를 기준으로 아래 변경을 적용한다.
 
 ```typescript
-// 1) imports에 추가: FormatPipe (선택)
-//    host에 sdSaveCommand 추가
-hostDirectives: [
-  { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
-],
-host: {
-  "(sdRefreshCommand)": "onRefreshButtonClick()",
-  "(sdSaveCommand)": "onSaveButtonClick()",
-},
-
-// 2) template — 도구 영역에 "행 추가" 버튼 추가
-<sd-button [size]="'sm'" [theme]="'link-primary'" (click)="onAddItemButtonClick()">
-  <ng-icon [svg]="icons.tablerCirclePlus" />
-  행 추가
-</sd-button>
-
-// 3) template — <sd-sheet>를 <sd-form>으로 감싸고 (formSubmit)="onSubmit()" 추가
-<sd-form #formCtrl (formSubmit)="onSubmit()" class="flex-fill p-default pt-0">
-  <sd-sheet ...>
-    <!-- isDeleted 전용 고정 컬럼 -->
-    @if (canEdit()) {
-      <sd-sheet-column [fixed]="true" [key]="'isDeleted'">
-        <ng-template #headerTpl>
-          <div class="p-xs-sm tx-center"><ng-icon [svg]="icons.tablerEraser" /></div>
-        </ng-template>
-        <ng-template [cell]="items()" let-item="item">
-          <div class="p-xs-sm tx-center">
-            <sd-anchor
-              [theme]="'danger'"
-              (click)="onToggleDeleteItemButtonClick(item)"
-            >
-              <ng-icon [svg]="item.isDeleted ? icons.tablerRestore : icons.tablerEraser" />
-              {{ item.isDeleted ? "복구" : "삭제" }}
-            </sd-anchor>
-          </div>
-        </ng-template>
-      </sd-sheet-column>
-    }
-
-    <!-- 편집 가능 셀: sd-textfield 등은 [inset]="true" [size]="'sm'" 명시 -->
-    <sd-sheet-column [key]="'name'" [header]="'이름'">
+// 1) imports 추가
+import { SdAnchor } from "@simplysm/angular";
+// @Component imports 배열에도 SdAnchor 추가
+
+// 2) template — <sd-sheet> 가장 앞에 isDeleted 고정 컬럼 삽입
+<sd-sheet ...>
+  @if (canEdit() && viewType() === "page") {
+    <sd-sheet-column [fixed]="true" [key]="'_isDeleted'">
+      <ng-template #headerTpl>
+        <div class="p-xs-sm tx-center">
+          <ng-icon [svg]="tablerEraser" />
+        </div>
+      </ng-template>
       <ng-template [cell]="items()" let-item="item">
-        <sd-textfield [type]="'text'" [(value)]="item.name" [inset]="true" [size]="'sm'" />
+        <div class="p-xs-sm tx-center">
+          <sd-anchor
+            [theme]="'danger'"
+            (click)="onToggleDeleteItemButtonClick(item)"
+          >
+            <ng-icon [svg]="item.isDeleted ? tablerRestore : tablerEraser" />
+            {{ item.isDeleted ? "복구" : "삭제" }}
+          </sd-anchor>
+        </div>
       </ng-template>
     </sd-sheet-column>
-  </sd-sheet>
-</sd-form>
-
-// 4) 메서드 추가/대체
-protected readonly formCtrl = viewChild<SdForm>("formCtrl");
-
-protected onSaveButtonClick(): void {
-  this.formCtrl()?.requestSubmit();
-}
-
-protected onAddItemButtonClick(): void {
-  const newItem: ICustomer = { id: Uuid.generate().toString(), name: "", phone: "", isDeleted: false };
-  this.items.update((list) => [newItem, ...list]);
-}
+  }
+  <!-- 나머지 컬럼(id, name, phone, categoryId, ...)은 기본 예제 그대로 -->
+</sd-sheet>
 
+// 3) 메서드 추가
 protected onToggleDeleteItemButtonClick(item: ICustomer): void {
   item.isDeleted = !item.isDeleted;
   mark(this.items); // OnPush 재렌더 + effect 알림
 }
-
-protected async onSubmit(): Promise<void> {
-  const diffs = this._getDiffs();
-  if (diffs.length === 0) {
-    this._sdToast.info("변경사항이 없습니다.");
-    return;
-  }
-  await this._sdToast.try(async () => {
-    this.busyCount.update((v) => v + 1);
-    try {
-      // 서버 호출: await this._api.submitAsync(diffs);
-      //   diffs.forEach((d) => {
-      //     if (d.type === "create") { ... insert ... }
-      //     else if (d.type === "update") { ... update ... }
-      //     // "same"은 includeSame=true 옵션에서만 등장. 여기서는 create/update만.
-      //   });
-      // 삭제는 `isDeleted: true`로 업데이트 → 서버가 soft-delete 처리
-      await this._refresh();
-    } finally {
-      this.busyCount.update((v) => v - 1);
-    }
-  }, getOrmDataEditToastErrorMessage);
-}
 ```
 
-> **`oneWayDiffs`는 delete를 다루지 않는다.** `newItems.oneWayDiffs(orgItems, keyFn)`은 `type: "create" | "update" | "same"`만 반환한다. 삭제 의사는 **`item.isDeleted = true` 플래그**로 표현하여 `"update"` diff로 전송된다. 행을 items 배열에서 제거하면 diff에서 누락되므로 절대 삭제하지 않는다.
-
-## 6. 변형: 선택 모달 뷰
+**포인트:**
 
-화면을 선택 모달로 재사용한다. `<sd-sheet>`가 items 기반이므로 key는 `selectedItems().map((it, i) => trackByFn(it, i))` 수동 변환으로 `SelectModalOutputResult<T>`를 구성한다.
+- inline 삭제도 **`item.isDeleted` 플래그 토글**로 표현. 행을 `items`에서 제거하면 `oneWayDiffs`가 누락한다. DB 반영은 저장 버튼 클릭 시 `onSubmit`에서 일괄 처리(soft-delete).
+- **`canEdit() && viewType() === "page"` 조건**: modal 뷰 / 권한 없음이면 열 자체 숨김 (`canEdit`은 이미 page 한정이지만 명시적으로 쓰면 의도가 분명).
+- 컬럼 key는 **`"_isDeleted"`** (언더스코어 prefix) — 서버 정렬·컬럼 지속성 설정과 충돌하지 않는 임의 키.
+- 기본 예제의 상단 "선택 삭제/복구" 버튼과 **공존** 가능. row별 빠른 처리 + 다건 일괄 처리.
 
-```typescript
-// 1) 컴포넌트 import
-import {
-  type SdSelectModal,
-  type SelectModalOutputResult,
-} from "@simplysm/angular";
-import { input, output, model } from "@angular/core";
+> **`oneWayDiffs`는 delete를 다루지 않는다.** `newItems.oneWayDiffs(orgItems, keyFn)`은 `type: "create" | "update" | "same"`만 반환한다. 삭제 의사는 **`item.isDeleted = true` 플래그**로 표현하여 `"update"` diff로 전송된다. 행을 `items` 배열에서 물리적으로 제거하면 diff에서 누락되므로 절대 삭제하지 않는다.
 
-// 2) 클래스 선언에 implements 추가
-export class CustomerListPage implements SdSelectModal<ICustomer> {
-  // ...기존 필드 유지
+## 6. 변형: 모달 편집 모드
 
-  // SdModalContentDef<SelectModalOutputResult<ICustomer>> 요구 필드
-  close = output<SelectModalOutputResult<ICustomer> | undefined>();
+기본 예제는 시트 셀 직접 수정(inline 편집) + 일괄 저장 방식이지만, 행 클릭 시 **편집 모달을 띄워 한 행씩 편집**하는 모드가 필요하면 아래 변경을 적용한다. 일괄 저장(diff) / snapshot / `_checkIgnoreChanges` / `setupCanDeactivate`는 불필요해져 모두 제거된다.
 
-  // SdSelectModal<ICustomer> 요구 필드
-  selectMode = input<"single" | "multi">();
-  selectedItemKeys = input<string[]>([]);
+```typescript
+// 1) imports 추가
+import { SdAnchor, SdModalProvider } from "@simplysm/angular";
+import { tablerEdit } from "@ng-icons/tabler-icons";
+// 앱별 편집 모달 컴포넌트 (crud-detail.md 레시피로 작성):
+import { CustomerEditModal } from "./CustomerEditModal";
 
-  // initialized는 WritableSignal이 아닌 Signal을 요구하므로 computed 또는 기존 signal 그대로 노출
-  // (위 완성 예제의 protected readonly initialized = signal(false) 를 그대로 사용)
+// 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) template — inline 편집용 도구 <sd-dock>의 "등록" 버튼은 _editItem() 호출로 바꿈.
+//    "선택 삭제/복구"는 bulk API로 별도 처리(개별 _refresh 필요).
+<sd-button ... (click)="onCreateItemButtonClick()">등록</sd-button>
+
+// 6) 메서드 교체
+protected async onCreateItemButtonClick(): Promise<void> {
+  await this._editItem();
 }
 
-// 3) template — 시트의 selectMode를 input 값으로 연결, 누적 선택 활성화
-<sd-sheet
-  ...
-  [selectMode]="selectMode()"
-  [cumulativeSelection]="viewType() === 'modal' && selectMode() === 'multi'"
-  [trackByFn]="trackByFn"
-  [(selectedItems)]="selectedItems"
->
-  ...
-</sd-sheet>
-
-// 4) template — 모달 뷰 분기 (page-modal-container.md 기반)
-} @else if (viewType() === "modal") {
-  <div class="flex-column fill">
-    <div class="flex-fill">
-      <!-- 필터 / 도구 / 시트를 이곳에 동일하게 배치 (page 분기와 같은 구조) -->
-    </div>
-    <!-- 하단 액션 바 -->
-    <div class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest">
-      <div class="flex-fill"></div>
-      @if (selectedItems().length > 0) {
-        <sd-button [size]="'sm'" [theme]="'danger'" (click)="onModalCancelClick()">
-          {{ selectMode() === "multi" ? "모두" : "선택" }} 해제
-        </sd-button>
-      }
-      @if (selectMode() === "multi") {
-        <sd-button [size]="'sm'" [theme]="'primary'" (click)="onModalConfirmClick()">
-          확인({{ selectedItems().length }})
-        </sd-button>
-      }
-    </div>
-  </div>
+protected async onEditItemButtonClick(item: ICustomer, event: MouseEvent): Promise<void> {
+  event.preventDefault();
+  event.stopPropagation();
+  await this._editItem(item);
 }
 
-// 5) 메서드 추가 — close.emit 수동 변환
-protected onModalConfirmClick(): void {
-  const items = this.selectedItems();
-  this.close.emit({
-    selectedItemKeys: items.map((it, i) => this.trackByFn(it, i) as string),
-    selectedItems: items,
+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();
 }
 
-protected onModalCancelClick(): void {
-  this.selectedItems.set([]);
-  this.close.emit({ selectedItemKeys: [], selectedItems: [] });
-}
-
-// 6) 최초 진입 시 selectedItemKeys input으로 전달된 key들에 해당하는 item을 미리 선택에 반영
-//    (필요한 경우 refresh 직후 effect 하나 추가)
-effect(() => {
-  const keys = this.selectedItemKeys();
-  if (keys.length === 0) return;
-  untracked(() => {
-    const selected = this.items().filter((it) => keys.includes(this.trackByFn(it)));
-    if (selected.length > 0) this.selectedItems.set(selected);
-  });
-});
+// 7) 제거:
+//    - hostDirectives의 sdSaveCommand / host의 (sdSaveCommand)
+//    - onSaveButtonClick / onSubmit / onAddItemButtonClick
+//    - diffs computed / _itemsSnapshot / _checkIgnoreChanges / _upsertItem / getIsItemChanged / onRemoveNewItemButtonClick
+//    - setupCanDeactivate(...) 호출 (다른 화면의 이탈 방지는 편집 모달이 책임짐)
+//    - <sd-form #formCtrl (formSubmit)="onSubmit()"> 래퍼 → <sd-sheet>를 main 영역에 직접 배치
 ```
 
-### `cumulativeSelection` 동적 바인딩 원칙
-
-- `cumulativeSelection` **기본값은 `false`** — `<sd-sheet>`의 items가 교체될 때 `selectedItems`가 빈 배열로 초기화된다
-- 선택 모달(`viewType() === "modal"`) + 다중 선택(`selectMode() === "multi"`) 조합에서는 **여러 페이지를 돌며 선택 누적**이 필요하므로 `true`로 바인딩
-- 그 외(page 뷰 또는 single selectMode)는 현재 뷰의 **일괄 작업**이 일반적 — `false`(기본값)가 맞다
-- 그러므로 정적 `true`가 아니라 **동적 computed**로 바인딩:
-  ```html
-  <sd-sheet
-    [cumulativeSelection]="viewType() === 'modal' && selectMode() === 'multi'"
-    [trackByFn]="trackByFn"
-    ...
-  >
+**포인트:**
+
+- 모달 편집 모드에서는 **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 편집 아님). 읽기 전용 표시만.
+- "선택 삭제/복구"를 남길 경우 `onToggleDeleteItemsButtonClick(del)` 내부를 diff 방식 대신 **bulk API 호출 + `_refresh()`** 로 구현한다:
+  ```typescript
+  protected async onToggleDeleteItemsButtonClick(del: boolean): Promise<void> {
+    if (this.busyCount() > 0) return;
+    const ids = this.selectedItems().map((it) => this.trackByFn(it)).filterExists();
+    if (ids.length === 0) return;
+
+    this.busyCount.update((v) => v + 1);
+    await this._sdToast.try(async () => {
+      await this._appOrm.connectAsync((db) => db.customer().where((c) => [expr.in(c.id, ids)]).updateAsync(() => ({ isDeleted: del })));
+      await this._appSharedData.emitAsync(this.SHARED_DATA_KEY, ids);
+      this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
+      await this._refresh();
+    });
+    this.busyCount.update((v) => v - 1);
+  }
   ```
-- 누적 모드 사용 시 `trackByFn` 명시 필수. 기본 `(item) => item`은 reference 기반이라 서버 페이지네이션에서 새 객체 reference가 내려오면 `obj.equal`로 비교해도 실패할 수 있다. `(item) => item.id` 같은 key 추출 함수를 반드시 지정한다.
 
 ## 7. 변형: 엑셀 업로드/다운로드
 
-`SdFileDialogProvider`로 파일 선택, 서버 API로 처리, `SdToastProvider.try`로 래핑한다.
+`SdFileDialogProvider`로 파일 선택, `ExcelWrapper`(@simplysm/excel) + `zod` 스키마로 읽기/쓰기. 다운로드는 `_search(false)`로 전체 페이지 조회 후 `@simplysm/core-browser`의 `downloadBlob`으로 내려받는다.
 
 ```typescript
 // 1) import 추가
 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) icons 맵에 추가
-protected readonly icons = {
-  ...existingIcons,
-  tablerFileExcel, tablerUpload,
-};
-
-// 4) template — 도구 영역 끝에 추가
-@if (canEdit()) {
-  <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onUploadExcelButtonClick()">
-    <ng-icon [svg]="icons.tablerUpload" />
-    엑셀 업로드
+// 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: z.boolean().describe("삭제"),
+    lastModifiedAt: z.custom<DateTime>().optional().describe("최종수정일시"),
+    lastModifiedBy: z.string().optional().describe("최종수정자"),
+  }),
+);
+
+// 4) template — page 뷰 topbar에 엑셀 버튼 2개 추가
+<sd-topbar>
+  <!-- 기존 "새로고침" / "저장" 버튼 옆 -->
+  <sd-button [theme]="'link-success'" (click)="onDownloadExcelButtonClick()">
+    <ng-icon [svg]="tablerFileExcel" />
+    엑셀 다운로드
   </sd-button>
-}
-<sd-button [size]="'sm'" [theme]="'link-success'" (click)="onDownloadExcelButtonClick()">
-  <ng-icon [svg]="icons.tablerFileExcel" />
-  엑셀 다운로드
-</sd-button>
+  @if (canEdit()) {
+    <sd-button [theme]="'link-success'" (click)="onUploadExcelButtonClick()">
+      <ng-icon [svg]="tablerUpload" />
+      엑셀 업로드
+    </sd-button>
+  }
+</sd-topbar>
 
 // 5) 메서드 추가
-protected async onDownloadExcelButtonClick(): Promise<void> {
+async onDownloadExcelButtonClick(): Promise<void> {
+  if (this.busyCount() > 0) return;
+
+  this.busyCount.update((v) => v + 1);
   await this._sdToast.try(async () => {
-    this.busyCount.update((v) => v + 1);
-    this.busyMessage.set("엑셀 다운로드 중...");
+    // 전체 조회 (페이지네이션 없이) — 기본 예제의 _search를 그대로 재사용
+    const r = await this._search(false);
+    const wb = await this._excelWrapper.write(this.viewTitle(), r.items);
     try {
-      // 전체 조회 (페이지네이션 없이)
-      const r = await this._fetchList(this._lastFilter(), 0, this.sortingDefs());
-      // 서버 호출 또는 클라이언트 변환 (앱별):
-      //   await this._api.downloadExcelAsync(r.items);
+      downloadBlob(
+        await wb.toBlob(),
+        `${this.viewTitle()}_${new DateTime().toFormatString("yyMMdd")}.xlsx`,
+      );
     } finally {
-      this.busyMessage.set(undefined);
-      this.busyCount.update((v) => v - 1);
+      await wb.close();
     }
-  }, getOrmDataEditToastErrorMessage);
+  });
+  this.busyCount.update((v) => v - 1);
 }
 
-protected async onUploadExcelButtonClick(): Promise<void> {
+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 () => {
-    this.busyCount.update((v) => v + 1);
-    this.busyMessage.set("엑셀 업로드 중...");
-    try {
-      // 서버 호출 (앱별):
-      //   await this._api.uploadExcelAsync(file);
-      await this._refresh();
-    } finally {
-      this.busyMessage.set(undefined);
-      this.busyCount.update((v) => v - 1);
-    }
-  }, getOrmDataEditToastErrorMessage);
+    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);
 }
 ```
 
+**포인트:**
+
+- 다운로드는 **`_search(false)`**(페이지네이션 없이 전체)로 쿼리. 페이지당 50건 제한이 걸리면 현재 페이지만 다운로드되는 실수가 생기므로 `usePagination: false` 명시 필수.
+- 업로드는 `_excelWrapper.read(file)` → `_upsertItem`(기본 예제의 메서드) **재사용**. 중복 검사·DataLog 기록 로직이 동일하게 적용됨.
+- 엑셀의 텍스트 컬럼(고객사명·MPN 등)을 FK id로 변환해야 하면 **DB 재조회 대신 `useSharedSignal(...)`로 이미 로드된 공유 데이터를 재사용**한다. 예: `this.sharedCustomers.items().toMapValues((it) => it.name, (it) => it.orderBy((v) => (v.__isHidden ? 1 : 0))[0])`. 같은 키에 숨김·비숨김 항목이 섞여 있으면 `orderBy`로 비숨김(`__isHidden: false`)을 우선순위로 정렬한다. 별도 `_buildIdMap` 같은 helper로 분리하지 말고 `toMapValues`를 `onUploadExcelButtonClick` 내부에 직접 인라인한다 (단일 호출처).
+- 오래 걸리는 대량 업로드에는 §9 "`busyMessage`는 필요할 때만 추가"를 참조하여 `busyMessage.set("엑셀 업로드 중...")`을 선택적으로 부착.
+
 ## 8. 뷰 타입 분기
 
-`@if (viewType() === "page") ... @else if (viewType() === "modal") ... @else { ... }` 분기 구조와 `modalOrPageTitle` computed 계산은 [`page-modal-container.md`](./page-modal-container.md)의 레시피와 동일하다. 본 레시피의 완성 예제도 그 패턴을 그대로 사용한다. control 뷰(다른 화면의 영역으로 삽입)로만 쓰일 경우에는 `@if` 분기를 생략하고 본문만 작성한다.
+page·modal·control 세 뷰는 **하나의 `<sd-topbar-container>` + `<sd-dock-container>` 공통 껍데기** 위에 뷰별로 다른 조각만 `@if`로 얹어 구성한다. 세 뷰별로 별도 블록을 전체 복제하지 않는다.
+
+| 뷰 | topbar | dock (도구 바) | main (시트) | 하단 바 |
+|---|---|---|---|---|
+| page | `<sd-topbar>` (새로고침/저장/...) | inline 도구 `<sd-dock>` (canEdit) | `<sd-form>` + `<sd-sheet>` | 없음 |
+| modal | 없음 | inline 도구 숨김 (`canEdit` = false) | 동일 | `<sd-dock [position]="'bottom'">` (선택 해제 / 확인) |
+| control | 없음 | 필요 시 주석만 | 동일 | 없음 |
+
+- **`<sd-dock>` position 명시**: 필터·inline 도구는 기본 `"top"`. **modal 하단 바는 반드시 `[position]="'bottom'"`를 명시**한다 — 누락하면 상단에 쌓여 필터·도구와 겹친다(`packages/angular/src/layout/dock/sd-dock.ts:97`).
+- **`canEdit = perms().includes("edit") && viewType() === "page"`**: edit 권한이 있어도 modal 뷰에서는 항상 false. 시트 셀의 `[readonly]="!edit"`·inline 도구 바 모두 자동으로 비활성화.
+- **`selectMode ?? 'multi'`**: modal로 호출할 때 input으로 `"single"` / `"multi"` 전달. 기본은 page 뷰용 `'multi'`로 fallback.
+- **`cumulativeSelection="viewType() === 'modal' && selectMode() === 'multi'"`**: 모달 + 다중 선택 조합에서만 페이지를 넘어 선택 누적. 기본값(`false`)이면 페이지 이동 시 선택이 초기화되는데, 일괄 작업 대상 리스트에서 이는 의도적 동작.
 
 ## 9. 주의사항 (자주 하는 실수)
 
@@ -729,6 +966,14 @@ protected async onUploadExcelButtonClick(): Promise<void> {
 
 - `useCrudList()`, `useDataSheet()`, `setupCumulateSelectedKeys2()` 같은 공통 헬퍼를 도입하지 말 것. 이 레시피가 제거한 추상화를 다시 만드는 행위다. 세 화면이 비슷해 보여도 화면마다 필드·동작 시그니처가 조금씩 다르므로 복사·수정이 낫다
 
+### 뷰 분기를 "완전 분리 블록"으로 쓰지 않는다
+
+- 시트 페이지를 modal로도 쓰는 경우, LLM이 page 블록과 modal 블록을 각각 완성하면서 **필터·시트를 중복 작성**하기 쉽다. 본 레시피의 기본 예제처럼 **하나의 껍데기 + 차이점만 `@if`** 로 얹어야 한다. 필터 하나를 수정할 때 두 블록을 모두 고치는 상황이 나오면 구조가 잘못된 것.
+
+### `<sd-dock>` position 누락
+
+- `<sd-dock>`의 `position` input 기본값은 `"top"`이다(`sd-dock.ts:97`). 모달 하단 "확인 바"에 `[position]="'bottom'"`을 빠뜨리면 필터 위에 쌓여 레이아웃이 깨진다.
+
 ### 시트 셀 스타일 함정
 
 - `<sd-sheet-column>`의 `[cell]` 템플릿 내부에 삽입되는 컨트롤(`sd-textfield` / `sd-select` / `sd-checkbox` / `sd-numpad` / `sd-date-range-picker` / `sd-textarea` 등)은 **`[inset]="true" [size]="'sm'"` 명시 필수**. 누락 시 컴파일 에러 없이 스타일만 깨진다(테두리·여백이 시트 셀에 맞지 않음). 예외: 복합 구조(텍스트+컨트롤)는 `[inset]="false"`, 시트 행 높이가 큰 경우는 `[size]` 생략 가능
@@ -739,15 +984,28 @@ protected async onUploadExcelButtonClick(): Promise<void> {
 - 삭제 의사 표현은 **`item.isDeleted = true` 플래그**로 하고 `"update"` diff로 전송 (서버가 soft-delete 처리)
 - inline 편집 시 `items` 배열에서 row를 제거하지 말 것. diff에서 해당 row가 누락되어 서버가 변경을 감지할 수 없다
 
-### `selectedItemKeys` 수동 변환
+### `selectedItemKeys`는 `filterExists()`로 undefined 제거
 
-- `<sd-sheet>`는 key 기반이 아니라 item 기반이다. `SelectModalOutputResult<T>.selectedItemKeys`를 구성하려면 `selectedItems().map((it, i) => trackByFn(it, i))`로 수동 변환한다
-- `trackByFn`의 signature는 `(item: T, index: number) => unknown`이므로 두 번째 인자(index)를 전달해야 타입이 맞는다
+- `<sd-sheet>`는 key 기반이 아니라 item 기반이므로 `SelectModalOutputResult<T>.selectedItemKeys`는 수동 변환한다: `selectedItems().map((it) => trackByFn(it)).filterExists()`.
+- **index fallback(`trackByFn(it, i) ?? i`) 금지.** id가 `undefined`인 신규 row가 있을 때 0, 1, 2 같은 index 값이 가짜 key로 들어가 호출 측이 잘못된 selection을 돌려받는다. `filterExists()`로 `undefined`를 제거하는 게 안전하다.
+
+### 모달 "선택 해제"는 single 모드에서만 close
+
+- `onModalCancelClick`에서 `this.close.emit`을 무조건 호출하면 multi 모드에서 "선택 해제 = 취소 + 닫기"가 되어 다시 선택하려면 모달을 재오픈해야 한다. multi에서는 `selectedItems.set([])`만 하고 close는 호출하지 않는다(사용자가 "확인" 버튼으로 최종 emit).
 
 ### `injectViewTypeSignal()` 호출 시점
 
 - `injectViewTypeSignal()`은 생성자 실행 중 또는 필드 이니셜라이저에서만 호출한다. `computed`·`effect` 콜백이나 일반 메서드에서 호출하면 `NG0203` 런타임 에러가 발생한다 (Angular `inject()` 제약)
 
+### `busyMessage`는 필요할 때만 추가
+
+- 기본 예제는 `<sd-busy-container [busy]="busyCount() > 0">`만 사용하고 `busyMessage` signal을 두지 않는다. 짧은 CRUD는 progress 아이콘만으로 충분.
+- 오래 걸리는 작업(대량 엑셀 업로드·집계 등)에 진행 문구가 필요하면 **필요한 화면에만** `busyMessage = signal<string | undefined>(undefined)` 추가 + `[message]="busyMessage()"` 바인딩 + 구간별 `busyMessage.set(...)`/`set(undefined)` 제어. 미사용 시 선언·바인딩 모두 생략.
+
+### 테스트만을 위한 public API 금지
+
+- `async submit(diffs) { await this._submitAsync(diffs); }` 같이 "테스트에서 호출하려고" private 메서드의 얇은 public wrapper를 노출하지 않는다. 캡슐화를 깨고 컴포넌트의 외부 API 인상을 오염시킨다. 테스트는 TestBed fixture + click/dispatch 이벤트 경로 또는 host의 `sdSaveCommand` 트리거로 수행.
+
 ## 10. 레시피 작성 관용 규칙
 
 향후 `crud-detail.md` · `data-select-button.md` 등 데이터 관련 레시피가 추가될 때 아래 3개 규칙을 공통으로 따른다.
@@ -762,7 +1020,7 @@ protected async onUploadExcelButtonClick(): Promise<void> {
 
 - `mark(sig)`는 `WritableSignal`의 값을 shallow copy하여 **참조를 갱신**한다 (배열: `[...v]`, 객체: `{...v}`)
 - 역할: **OnPush 템플릿 재렌더링** + **다른 computed / effect의 의존성 갱신**
-- **"저장 감지"가 아니다.** `obj.equal`이 deep equal로 값 차이를 감지하므로, `item.name = "new"` 같은 mutation은 `mark` 없이도 `_getDiffs()` / submit에서 감지된다
+- **"저장 감지"가 아니다.** `obj.equal`이 deep equal로 값 차이를 감지하므로, `item.name = "new"` 같은 mutation은 `mark` 없이도 `diffs()` / submit에서 감지된다
 - Chrome 61 호환성(Proxy 폴리필 불가)으로 signal 자동 notify가 불가하여 명시적 호출이 필요
 - ❌ "mark 없으면 저장이 안 된다" 식 서술 금지