@simplysm/angular 14.0.49 → 14.0.51

package/docs/recipes/crud-list.md

@@ -1,90 +1,67 @@
-# Recipe: CRUD 리스트 화면 직접 조립
-
-소비 화면이 `<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` · `<sd-form>` · `<sd-sheet>` · `<sd-sheet-column>` 표준 컴포넌트를 **직접 조립**하여 CRUD 리스트 화면을 구성한다. 과거 `SdDataSheet` / `SdDataSheetBase` / `SdDataSheetColumn`이 감추고 있던 필터·페이지네이션·정렬·선택·편집·삭제복구·엑셀 업로드·다운로드·단축키 흐름을 화면 내부에 인라인으로 풀어쓴다.
-
-## 1. Overview
-
-- 제거된 추상화: `SdDataSheet`(컴포넌트) / `SdDataSheetBase`(추상 클래스) / `SdDataSheetColumn`(디렉티브) / `SdDataSheetItemPropInfo`·`SdDataSheetItemInfo`·`SdDataSheetSearchResult`(타입 3종) / `setupCloserWhenSingleSelectionChange`(단일 선택 시 모달 자동 닫기 유틸) / 내부 Manager 5종(`injectDataSheet{Refresh,InlineEdit,ModalEdit,Excel}Manager`, `useDataSheetFilterManager`)
-- 대체: 소비 컴포넌트가 표준 조각을 직접 조립
-- 조립 요소:
-  - `<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
-  - `setupCanDeactivate()` — 이탈 방지
-  - `mark(sig)` — signal 참조 갱신
-  - `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.clone(items)` — snapshot 깊은 복제 (`@simplysm/core-common`)
-
-## 2. 언제 사용하는가
-
-| 상황 | 적용 여부 |
-|---|---|
-| 필터 + 페이지네이션 + 정렬 + 선택 + 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. 완성 예제
-
-아래는 **page + modal 2뷰 동시 지원 + inline 편집** 기준 완성 컴포넌트다. 하나의 화면이 라우트로 진입하면 CRUD 리스트(조회·등록·inline 수정·선택 삭제/복구)로 동작하고, `SdModalProvider.showAsync()`로 열리면 동일 화면이 "선택 모달"로 전환된다(selectMode에 따라 single/multi, 선택 결과를 `close.emit`). inline 삭제 열 / 엑셀 업로드·다운로드 / 모달로 row 편집은 `## 5`~`## 7`의 변형 스니펫으로 교체·추가한다.
+# CRUD 리스트 화면 직접 조립
+
+`<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` · `<sd-form>` · `<sd-sheet>` · `<sd-sheet-column>` 표준 컴포넌트를 소비 화면이 **직접 조립**하여 CRUD 리스트 화면을 구성하는 레시피. 최소 뼈대(조회 전용 page) 위에 편집·선택·모달·엑셀 등 필요한 확장만 선택적으로 얹는다.
+
+> **modal 뷰는 용도(선택 모달 vs 조회 전용)를 먼저 확정한다.** 상세와 회피 방법은 아래 [🚫 흔한 실수](#-흔한-실수-anti-patterns)의 "modal = 선택 모달로 반사적 부착" 참조.
+
+## When to use / When NOT to use
+
+- ✅ 검색·페이지네이션·정렬을 갖춘 리스트 조회 화면
+- ✅ 셀 직접 편집·일괄 저장·선택 삭제·엑셀 업로드/다운로드가 필요한 리스트 CRUD
+- ✅ 같은 리스트 화면을 page·select-modal·readonly-modal 등으로 재사용
+- ❌ 단일 레코드 상세 폼 → [`crud-detail.md`](./crud-detail.md)
+- ❌ 모달 선택 버튼(항목을 골라 받는 버튼) 조립 → [`data-select-button.md`](./data-select-button.md)
+- ❌ 뷰 분기(page/modal/control) 공통 껍데기만 필요 → [`page-modal-container.md`](./page-modal-container.md)
+
+### 뷰 범위 선택
+
+- **page**: 라우트로 진입하는 주 리스트 화면 → 본 파일의 [기본 레시피](#기본-레시피) 그대로
+- **modal (선택)**: 다른 화면에서 항목을 골라 `close.emit`으로 돌려주는 selector → [확장 D](./crud-list/extension-d-select-modal.md)
+- **modal (조회 전용)**: 부모 레코드의 자식 목록·이력을 input으로 받아 읽기 전용으로 표시(닫기는 SdModal 기본 "X") → [확장 E](./crud-list/extension-e-readonly-modal.md)
+- **control**: 마스터-디테일의 리스트 영역으로 임베딩 → [공통 규칙 "page가 topbar 소유"](./_common-rules.md#page-컴포넌트가-sd-topbar-container와-sd-topbar를-소유한다) + 필요 시 확장 D/E 참조
+
+## 전제조건
+
+- Provider: 앱 루트에 `provideSdAngular`가 등록되어 있음
+- peer: Angular 21 standalone, zoneless, `@simplysm/angular`
+- 앱별: ORM provider + `DbContext` (예제의 `AppOrmProvider`·`@adtek/client-common`은 각 앱이 소유하는 placeholder)
+- 횡단 규칙: [`_common-rules.md`](./_common-rules.md)에 정의된 공통 규칙을 모두 준수한다. 본 파일에서 재정의하지 않는다
+  - [`injectViewTypeSignal()` 호출 시점](./_common-rules.md#injectviewtypesignal은-생성자-또는-필드-이니셜라이저에서만-호출한다)
+  - [page 컴포넌트가 `<sd-topbar>`를 소유](./_common-rules.md#page-컴포넌트가-sd-topbar-container와-sd-topbar를-소유한다)
+  - [시트 셀 컨트롤에 `[inset]="true" [size]="'sm'"` 명시](./_common-rules.md#시트-셀-내부-컨트롤에-insettrue-sizesm을-명시한다)
+  - [input 변경을 effect에서 filter·lastFilter·page에 반영](./_common-rules.md#input-변경을-effect-내부에서-filterlastfilterpage에-반영한다)
+  - [`void this._initAsync()` 금지](./_common-rules.md#input-의존-데이터-로딩에-void-this_initasync를-사용하지-않는다) / [signal 필드 초기값에서 다른 signal 읽기 금지](./_common-rules.md#signal-필드-초기값에서-다른-signal을-읽지-않는다) / [`mark()`를 저장 감지 수단으로 오해 금지](./_common-rules.md#marksig를-저장-감지-수단으로-사용하지-않는다)
+
+## 기본 레시피
+
+조회 전용 page 기준의 최소 뼈대 완성 컴포넌트. 라우트로 진입하면 검색 + 페이지네이션 + 정렬이 동작하는 읽기 전용 리스트로 표시된다. 편집·선택·모달·엑셀은 아래 [변형](#변형-variation) 표에서 필요한 확장을 선택적으로 얹는다.
+
+> **이 최소 뼈대가 포함하지 않는 것:** 감사 필드(`lastModifiedAt`/`lastModifiedBy`) · 카테고리 등 FK 표시 컬럼 · 편집 권한(`"edit"`) · 편집용 컨트롤은 모두 확장 A 이후에 도입된다. (참고: `crud-detail.md` 최소 뼈대는 page 전용 읽기 폼이므로 감사 필드 2열을 포함한다 — 도메인 범위는 같지만 뼈대 범위가 다르다.)
 
 ```typescript
 import { NgIcon } from "@ng-icons/core";
-import {
-  tablerAlertTriangle,
-  tablerCirclePlus,
-  tablerEraser,
-  tablerDeviceFloppy,
-  tablerRefresh,
-  tablerRestore,
-  tablerSearch,
-  tablerX,
-} from "@ng-icons/tabler-icons";
+import { tablerAlertTriangle, tablerRefresh, tablerSearch } from "@ng-icons/tabler-icons";
 import {
   ChangeDetectionStrategy,
   Component,
-  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 { str } from "@simplysm/core-common";
 import {
-  FormatPipe,
   injectPermsSignal,
   injectViewTitleSignal,
   injectViewTypeSignal,
   mark,
-  SdAnchor,
   SdBusyContainer,
   SdButton,
-  SdCheckbox,
   SdCommandDirective,
   SdDock,
   SdDockContainer,
   SdForm,
-  SdItemOfTemplate,
-  type SdSelectModal,
-  SdSharedDataSelect,
   SdSheet,
   SdSheetColumn,
   SdSheetColumnCellTemplate,
@@ -92,28 +69,19 @@ import {
   SdToastProvider,
   SdTopbar,
   SdTopbarContainer,
-  type SelectModalOutputResult,
-  setupCanDeactivate,
   type SortingDef,
 } from "@simplysm/angular";
-// 앱별 대체: ORM/공유 데이터/인증 provider + DbContext. simplysm 패키지가 아니라 각 앱이 소유한다.
-import { AppOrmProvider, AppSharedDataProvider, useSharedSignal } from "@adtek/client-common";
-import type { MainDbContext } from "@adtek/db-main";
-import { AppAuthProvider } from "../../../providers/AppAuthProvider";
+// 앱별 대체: ORM provider + DbContext. simplysm 패키지가 아니라 각 앱이 소유한다.
+import { AppOrmProvider } from "@adtek/client-common";
 
 interface IFilter {
   searchText?: string;
-  isIncludeDeleted: boolean;
 }
 
 interface ICustomer {
-  id?: number;
-  name?: string;
+  id: number;
+  name: string;
   phone?: string;
-  categoryId?: number;
-  isDeleted: boolean;
-  lastModifiedAt?: DateTime;
-  lastModifiedBy?: string;
 }
 
 @Component({
@@ -125,21 +93,19 @@ interface ICustomer {
     SdBusyContainer, SdTopbarContainer, SdTopbar,
     SdDockContainer, SdDock,
     SdForm, SdSheet, SdSheetColumn, SdSheetColumnCellTemplate,
-    SdButton, SdAnchor, SdCheckbox, SdTextfield,
-    SdSharedDataSelect, SdItemOfTemplate,
-    NgIcon, FormatPipe,
+    SdButton, SdTextfield,
+    NgIcon,
   ],
   hostDirectives: [
-    { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
+    { directive: SdCommandDirective, outputs: ["sdRefreshCommand"] },
   ],
   host: {
     "(sdRefreshCommand)": "onRefreshButtonClick()",
-    "(sdSaveCommand)": "onSaveButtonClick()",
   },
   template: `
     <sd-busy-container [busy]="busyCount() > 0">
       @if (initialized()) {
-        @if (!canUse()) {
+        @if (!perms().includes("use")) {
           <div class="fill tx-theme-gray-light p-xxl tx-center">
             <br />
             <ng-icon [svg]="tablerAlertTriangle" [size]="'5em'" />
@@ -158,13 +124,6 @@ interface ICustomer {
                   새로고침
                   <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>
             }
 
@@ -188,166 +147,37 @@ interface ICustomer {
                         (valueChange)="mark(filter)"
                       />
                     </div>
-                    <div class="form-box-item">
-                      <sd-checkbox
-                        [(value)]="filter().isIncludeDeleted"
-                        (valueChange)="mark(filter)"
-                      >
-                        삭제항목 포함
-                      </sd-checkbox>
-                    </div>
                   </div>
                 </sd-form>
               </sd-dock>
 
-              <!-- 도구 (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
-                    [size]="'sm'"
-                    [theme]="'link-danger'"
-                    (click)="onToggleDeleteItemsButtonClick(true)"
-                    [disabled]="!hasSelectedNotDeleted()"
-                  >
-                    <ng-icon [svg]="tablerEraser" />
-                    선택 삭제
-                  </sd-button>
-                  @if (hasSelectedDeleted()) {
-                    <sd-button
-                      [size]="'sm'"
-                      [theme]="'link-warning'"
-                      (click)="onToggleDeleteItemsButtonClick(false)"
-                    >
-                      <ng-icon [svg]="tablerRestore" />
-                      선택 복구
-                    </sd-button>
-                  }
-                </sd-dock>
-              }
-
               <!-- 시트 (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>
-                    </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-sheet
+                [key]="'customer-list-sheet'"
+                [items]="items()"
+                [(currentPage)]="page"
+                [totalPageCount]="pageLength()"
+                [(sorts)]="sortingDefs"
+                [trackByFn]="trackByFn"
+              >
+                <sd-sheet-column [fixed]="true" [header]="'#'" [key]="'id'">
+                  <ng-template [cell]="items()" let-item="item">
+                    <div class="p-xs-sm tx-right">{{ item.id }}</div>
+                  </ng-template>
+                </sd-sheet-column>
+
+                <sd-sheet-column [header]="'이름'" [key]="'name'">
+                  <ng-template [cell]="items()" let-item="item">
+                    <div class="p-xs-sm">{{ item.name }}</div>
+                  </ng-template>
+                </sd-sheet-column>
+
+                <sd-sheet-column [header]="'전화번호'" [key]="'phone'">
+                  <ng-template [cell]="items()" let-item="item">
+                    <div class="p-xs-sm">{{ item.phone }}</div>
+                  </ng-template>
+                </sd-sheet-column>
+              </sd-sheet>
             </sd-dock-container>
           </sd-topbar-container>
         }
@@ -355,63 +185,37 @@ interface ICustomer {
     </sd-busy-container>
   `,
 })
-export class CustomerListPage implements SdSelectModal<ICustomer> {
+export class CustomerList {
   //== DI ==
   private readonly _appOrm = inject(AppOrmProvider);
-  private readonly _appAuth = inject(AppAuthProvider);
-  private readonly _appSharedData = inject(AppSharedDataProvider);
   private readonly _sdToast = inject(SdToastProvider);
 
-  //== 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");
+  perms = injectPermsSignal(["sales.customer"], ["use"]);
 
   viewType = injectViewTypeSignal();
   viewTitle = injectViewTitleSignal();
 
-  //== 공유 데이터 ==
-  sharedCategories = useSharedSignal("카테고리");
-
   //== 상태 ==
-  initialized = signal(false);
-  busyCount = signal(0);
+  initialized = signal(false);   // 최초 조회 완료 — @if (initialized()) 가드 해제
+  busyCount = signal(0);         // 중첩 비동기 작업 카운트 (0 초과 시 busy 표시)
 
-  private _itemsSnapshot: ICustomer[] = [];
   items = signal<ICustomer[]>([]);
-  selectedItems = signal<ICustomer[]>([]);
-  diffs = computed(() => this.items().oneWayDiffs(this._itemsSnapshot, "id"));
 
   page = signal(0);
   pageLength = signal(0);
   sortingDefs = signal<SortingDef[]>([]);
 
-  filter = signal<IFilter>({ isIncludeDeleted: false });
-  lastFilter = signal<IFilter>({ isIncludeDeleted: false });
-
-  //== 파생 ==
-  hasSelectedDeleted = computed(() => this.selectedItems().some((it) => it.isDeleted));
-  hasSelectedNotDeleted = computed(() => this.selectedItems().some((it) => !it.isDeleted));
+  filter = signal<IFilter>({});      // 입력 버퍼. onFilterSubmit 시 lastFilter로 스냅샷
+  lastFilter = signal<IFilter>({});  // 조회 트리거 — effect 의존성은 이 signal
 
   //== 시트 fn ==
   trackByFn = (item: ICustomer) => item.id;
-  getItemCellStyleFn = (item: ICustomer): string | undefined =>
-    item.isDeleted ? "text-decoration: line-through;" : undefined;
 
   constructor() {
     // 필터/페이지/정렬/perms 변경 시 재조회
     effect(() => {
-      if (!this.canUse()) {
+      if (!this.perms().includes("use")) {
         this.initialized.set(true);
         return;
       }
@@ -429,29 +233,6 @@ export class CustomerListPage implements SdSelectModal<ICustomer> {
         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(() => {
-        const sel = currItems.filter((it) => keys.includes(this.trackByFn(it)));
-        if (sel.length > 0) this.selectedItems.set(sel);
-      });
-    });
-
-    setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
-  }
-
-  getIsItemChanged(item: ICustomer): boolean {
-    if (item.id == null) return true;
-    return this.diffs().some((diff) => diff.item.id === item.id);
   }
 
   //== Handlers ==
@@ -462,96 +243,20 @@ export class CustomerListPage implements SdSelectModal<ICustomer> {
 
   onRefreshButtonClick(): void {
     if (this.busyCount() > 0) return;
-    if (!this.canUse()) return;
-    if (!this._checkIgnoreChanges()) return;
-
-    mark(this.lastFilter);
-  }
+    if (!this.perms().includes("use")) return;
 
-  onSaveButtonClick(): void {
-    this.formCtrl()?.requestSubmit();
-  }
-
-  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 () => {
-      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);
-  }
-
-  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: [] });
-    }
+    mark(this.lastFilter);  // 값 변경 없이 참조만 갱신 → effect 재실행
   }
 
   //== Internals ==
-  private _checkIgnoreChanges(): boolean {
-    return this.diffs().length === 0 || confirm("변경사항이 있습니다. 무시하고 진행하시겠습니까?");
-  }
-
-  // 로드+snapshot만 담당. busy/try는 호출부에서 처리.
   private async _refresh(): Promise<void> {
     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 _search(
-    usePagination: boolean,
+    usePagination: boolean,  // false는 전체 조회 (엑셀 다운로드 등에서 재사용)
   ): Promise<{ items: ICustomer[]; pageLength: number }> {
     const filter = this.lastFilter();
     const sortingDefs = this.sortingDefs();
@@ -563,22 +268,17 @@ export class CustomerListPage implements SdSelectModal<ICustomer> {
       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)]);
-      }
 
+      // 페이지당 50건 — 시트 화면 표준치 (조정 시 UX 확인 필요)
       const pageLength = usePagination ? Math.ceil((await qr1.count()) / 50) : 0;
 
-      let qr2 = qr1.joinLastDataLog().select((item) => ({
+      let qr2 = qr1.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,
       }));
 
+      // orderBy는 string overload 사용 — 람다+obj.getChainValue는 Anti-patterns 참조
       for (const sortingDef of sortingDefs) {
         qr2 = qr2.orderBy(sortingDef.key, sortingDef.desc ? "DESC" : "ASC");
       }
@@ -595,443 +295,152 @@ export class CustomerListPage implements SdSelectModal<ICustomer> {
     });
   }
 
-  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;
 }
 ```
 
-## 4. 분해 설명
-
-각 블록의 역할과 원본 `SdDataSheet` 코드 대응 지점:
-
-| 블록 | 역할 | 원본 대응 |
-|---|---|---|
-| `<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` |
-| `<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` |
-| 호출부(`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 표시) |
-| `initialized` | 최초 조회 완료 여부 (완료 전 본문 숨김) |
-| `items` | 현재 페이지 items |
-| `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)]>`로 양방향 |
-| `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)` — 참조 갱신으로 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`를 기준으로 아래 변경을 적용한다.
+본 섹션에 등장하는 개별 API의 단독 사용법은 각 문서를 참조한다:
 
-```typescript
-// 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">
-        <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>
-  }
-  <!-- 나머지 컬럼(id, name, phone, categoryId, ...)은 기본 예제 그대로 -->
-</sd-sheet>
+- [`<sd-busy-container>`](../ui-overlay/sd-busy-container.md) — busy 오버레이 + busyCount 카운트 패턴
+- [`<sd-topbar-container>` · `<sd-topbar>`](../ui-navigation/sd-topbar-container.md) — 탑바
+- [`<sd-dock-container>` · `<sd-dock>`](../ui-layout/sd-dock-container.md) — 도킹 레이아웃
+- [`<sd-form>`](../ui-form/sd-form.md) — 폼 래퍼 + `(formSubmit)` + `requestSubmit()`
+- [`<sd-button>`](../ui-form/sd-button.md) · [`<sd-textfield>`](../ui-form/sd-textfield.md)
+- [`<sd-sheet>` · `<sd-sheet-column>` · `<ng-template [cell]>`](../ui-data/sd-sheet.md)
+- [`injectViewTypeSignal`](../utils/inject-routing-signals.md#injectviewtypesignal) · [`injectViewTitleSignal`](../utils/inject-routing-signals.md#injectviewtitlesignal) · [`mark`](../utils/mark.md) · [`injectPermsSignal`](../utils/inject-routing-signals.md#injectpermssignal) · [`SdToastProvider.try`](../providers/sd-toast-provider.md#try-사용-패턴)
 
-// 3) 메서드 추가
-protected onToggleDeleteItemButtonClick(item: ICustomer): void {
-  item.isDeleted = !item.isDeleted;
-  mark(this.items); // OnPush 재렌더 + effect 알림
-}
-```
+### 조건부 요소 포함 기준
 
-**포인트:**
+최소 뼈대의 인프라·라이프사이클 요소는 화면의 필요에 따라 포함·생략한다. 필요 없는 요소를 기계적으로 포함하지 않는다.
 
-- inline 삭제도 **`item.isDeleted` 플래그 토글**로 표현. 행을 `items`에서 제거하면 `oneWayDiffs`가 누락한다. DB 반영은 저장 버튼 클릭 시 `onSubmit`에서 일괄 처리(soft-delete).
-- **`canEdit() && viewType() === "page"` 조건**: modal 뷰 / 권한 없음이면 열 자체 숨김 (`canEdit`은 이미 page 한정이지만 명시적으로 쓰면 의도가 분명).
-- 컬럼 key는 **`"_isDeleted"`** (언더스코어 prefix) — 서버 정렬·컬럼 지속성 설정과 충돌하지 않는 임의 키.
-- 기본 예제의 상단 "선택 삭제/복구" 버튼과 **공존** 가능. row별 빠른 처리 + 다건 일괄 처리.
+| 요소 | 포함 조건 | 생략하는 경우 예시 |
+|------|----------|-------------------|
+| `<sd-topbar-container>` + `<sd-topbar>` | routes로 연결된 페이지에서 헤더를 표시할 때 | route 미연결 컴포넌트(control, 래퍼 등) |
+| `injectViewTitleSignal()` | 타이틀이 필요할 때. topbar에 타이틀을 표시하는 page에는 보통 포함 | topbar가 없거나 타이틀 표시가 불필요한 화면 |
+| `injectViewTypeSignal()` + `@if (viewType() === "page")` 가드 | 해당 컴포넌트가 page 외에 modal 또는 control로도 겸용될 때 | page 전용 리스트, page 전용 대시보드 |
+| `injectPermsSignal()` + 권한 없음 메시지 | 권한 제어가 있는 화면. 권한 제어 자체가 있으면 필수 | 권한 제어가 없는 화면 |
+| `<sd-busy-container>` + `busyCount` | 화면에 비동기 작업(DB 조회, API 호출 등)이 있어서 busy 표시가 필요할 때 | 비동기 로딩 없이 동기적으로 렌더되는 래퍼/레이아웃 화면 |
+| `initialized` + `@if (initialized())` 가드 | 초기 데이터 로딩이 완료되기 전에는 화면을 그리면 안 되는 경우 (깜박임 방지) | 초기 로딩이 필요 없거나, 빈 상태로 보여줘도 무방한 화면 |
+| `SHARED_DATA_KEY` + `emitAsync()` 호출 | 해당 화면에서 `SdSharedDataProvider`에 등록된 데이터를 변경(생성/수정/삭제)하는 경우 | 조회만 하는 화면, sharedData에 등록되지 않은 데이터를 다루는 화면 |
 
-> **`oneWayDiffs`는 delete를 다루지 않는다.** `newItems.oneWayDiffs(orgItems, keyFn)`은 `type: "create" | "update" | "same"`만 반환한다. 삭제 의사는 **`item.isDeleted = true` 플래그**로 표현하여 `"update"` diff로 전송된다. 행을 `items` 배열에서 물리적으로 제거하면 diff에서 누락되므로 절대 삭제하지 않는다.
+## 변형 (Variation)
 
-## 6. 변형: 모달 편집 모드
+아래 확장 중 필요한 것만 선택적으로 얹는다. 각 확장은 self-contained 문서에서 최소 뼈대 대비 diff를 제공한다.
 
-기본 예제는 시트 셀 직접 수정(inline 편집) + 일괄 저장 방식이지만, 행 클릭 시 **편집 모달을 띄워 한 행씩 편집**하는 모드가 필요하면 아래 변경을 적용한다. 일괄 저장(diff) / snapshot / `_checkIgnoreChanges` / `setupCanDeactivate`는 불필요해져 모두 제거된다.
+| 확장 | 언제 쓰나 | 전제 | 문서 |
+|---|---|---|---|
+| A | 셀 직접 편집 + 일괄 저장(inline 편집) | 없음 | [extension-a-inline-edit.md](./crud-list/extension-a-inline-edit.md) |
+| B | 선택 체크박스 + 선택 삭제·복구 | A | [extension-b-selection.md](./crud-list/extension-b-selection.md) |
+| C | 시트 맨 앞 고정 열에 row별 inline 삭제·복구 | A + B | [extension-c-inline-delete.md](./crud-list/extension-c-inline-delete.md) |
+| D | 선택 모달 전환(항목을 골라 `close.emit`으로 돌려줌) | A + B | [extension-d-select-modal.md](./crud-list/extension-d-select-modal.md) |
+| E | 조회 전용 modal(부모 레코드의 자식 목록·이력을 input으로 받아 읽기 전용 표시) | 없음 (최소 뼈대에 직접) | [extension-e-readonly-modal.md](./crud-list/extension-e-readonly-modal.md) |
+| F | 모달 편집 모드(행 클릭 → 편집 모달). A와 상호 배타 | 없음 | [extension-f-modal-edit.md](./crud-list/extension-f-modal-edit.md) |
+| G | 엑셀 업로드/다운로드 (`_upsertItem` 재사용) | A | [extension-g-excel.md](./crud-list/extension-g-excel.md) |
 
-```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) template — inline 편집용 도구 <sd-dock>의 "등록" 버튼은 _editItem() 호출로 바꿈.
-//    "선택 삭제/복구"는 bulk API로 별도 처리(개별 _refresh 필요).
-<sd-button ... (click)="onCreateItemButtonClick()">등록</sd-button>
-
-// 6) 메서드 교체
-protected async onCreateItemButtonClick(): Promise<void> {
-  await this._editItem();
-}
+## 🚫 흔한 실수 (Anti-patterns)
 
-protected async onEditItemButtonClick(item: ICustomer, event: MouseEvent): Promise<void> {
-  event.preventDefault();
-  event.stopPropagation();
-  await this._editItem(item);
-}
+### modal = 선택 모달로 반사적 부착
 
-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) 제거:
-//    - 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 편집 아님). 읽기 전용 표시만.
-- "선택 삭제/복구"를 남길 경우 `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);
-  }
-  ```
-
-## 7. 변형: 엑셀 업로드/다운로드
-
-`SdFileDialogProvider`로 파일 선택, `ExcelWrapper`(@simplysm/excel) + `zod` 스키마로 읽기/쓰기. 다운로드는 `_search(false)`로 전체 페이지 조회 후 `@simplysm/core-browser`의 `downloadBlob`으로 내려받는다.
+`viewType() === "modal"`이라는 사실만으로 "선택 모달"이라고 단정하고 `SdSelectModal<T>` 계약을 부착하지 않는다. modal 용도는 최소 두 가지다 — (a) 선택 모달(확장 D): 항목을 골라 `close.emit`으로 돌려줌 / (b) 조회 전용(확장 E): 부모 레코드의 자식 목록·이력을 읽기 전용으로 표시, 닫기는 SdModal 기본 "X".
 
 ```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) 클래스 필드 추가 — 아이콘 + 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>
-  @if (canEdit()) {
-    <sd-button [theme]="'link-success'" (click)="onUploadExcelButtonClick()">
-      <ng-icon [svg]="tablerUpload" />
-      엑셀 업로드
-    </sd-button>
-  }
-</sd-topbar>
-
-// 5) 메서드 추가
-async onDownloadExcelButtonClick(): Promise<void> {
-  if (this.busyCount() > 0) return;
-
-  this.busyCount.update((v) => v + 1);
-  await this._sdToast.try(async () => {
-    // 전체 조회 (페이지네이션 없이) — 기본 예제의 _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);
+// ❌ viewType() === "modal"만 보고 선택 모달 계약을 반사적으로 부착
+export class CustomerList implements SdSelectModal<ICustomer> {
+  selectMode = input<"single" | "multi">();
+  selectedItemKeys = input<any[]>([]);
+  close = output<SelectModalOutputResult<ICustomer>>();
+  // ... 조회 전용인데도 하단 "선택 해제 / 확인" 바, cumulativeSelection까지 전부 이식
 }
 
-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);
-}
+// ✅ modal 용도를 먼저 확정한다
+//   (a) 선택 모달이면 확장 D 스켈레톤부터 시작
+//   (b) 조회 전용이면 확장 E 스켈레톤부터 시작 — SdSelectModal 계약 부착 안 함
 ```
 
-**포인트:**
-
-- 다운로드는 **`_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. 뷰 타입 분기
-
-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. 주의사항 (자주 하는 실수)
-
-### 공통 유틸 재도입 금지
-
-- `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]` 생략 가능
+**근거**: 조회 전용 modal에 선택 계약을 부착하면 호출되지 않아 죽은 코드가 된다. LLM이 풀 스택 합본을 복사하면서 "modal 지원"이라는 이유로 반사적으로 이식하는 회귀가 잦다. [확장 E](./crud-list/extension-e-readonly-modal.md) 참조.
 
-### `oneWayDiffs`의 삭제 처리
+### viewType 추측으로 3뷰 모두 박기 / 완전 분리 블록 작성
 
-- `newItems.oneWayDiffs(orgItems, keyFn)`은 **삭제(delete)를 다루지 않는다**. `type: "create" | "update" | "same"`만 반환
-- 삭제 의사 표현은 **`item.isDeleted = true` 플래그**로 하고 `"update"` diff로 전송 (서버가 soft-delete 처리)
-- inline 편집 시 `items` 배열에서 row를 제거하지 말 것. diff에서 해당 row가 누락되어 서버가 변경을 감지할 수 없다
+화면이 실제 어떤 뷰로 쓰이는지 확정하지 않은 채 page·modal·control 3뷰용 조각을 모두 배치하지 않는다(당장 쓰지 않는 뷰의 계약·분기는 죽은 코드가 된다). 또한 시트 페이지를 page와 modal로 겸용할 때(확장 D)도 page 블록과 modal 블록을 각각 완성하면서 필터·시트를 중복 작성하지 않는다. 하나의 `<sd-topbar-container>` + `<sd-dock-container>` 공통 껍데기 위에 뷰별로 다른 조각만 `@if`로 얹는다.
 
-### `selectedItemKeys`는 `filterExists()`로 undefined 제거
-
-- `<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).
+```html
+<!-- ❌ page 블록과 modal 블록을 각각 완성 — 필터·시트가 중복되어 수정 시 양쪽을 고쳐야 함 -->
+@if (viewType() === "page") {
+  <sd-topbar-container>
+    <sd-topbar>...</sd-topbar>
+    <sd-dock-container>
+      <sd-dock class="p-default"><sd-form>...</sd-form></sd-dock>
+      <sd-sheet ...>...</sd-sheet>
+    </sd-dock-container>
+  </sd-topbar-container>
+}
+@if (viewType() === "modal") {
+  <sd-topbar-container>
+    <sd-dock-container>
+      <sd-dock class="p-default"><sd-form>...</sd-form></sd-dock>
+      <sd-sheet ...>...</sd-sheet>
+    </sd-dock-container>
+  </sd-topbar-container>
+}
 
-### `injectViewTypeSignal()` 호출 시점
+<!-- ✅ 하나의 껍데기 + 차이점만 @if로 얹는다 -->
+<sd-topbar-container>
+  @if (viewType() === "page") { <sd-topbar>...</sd-topbar> }
+  <sd-dock-container>
+    <sd-dock class="p-default"><sd-form>...</sd-form></sd-dock>
+    <sd-sheet ...>...</sd-sheet>
+  </sd-dock-container>
+</sd-topbar-container>
+```
 
-- `injectViewTypeSignal()`은 생성자 실행 중 또는 필드 이니셜라이저에서만 호출한다. `computed`·`effect` 콜백이나 일반 메서드에서 호출하면 `NG0203` 런타임 에러가 발생한다 (Angular `inject()` 제약)
+**근거**: 필터 한 줄을 수정할 때 두 블록을 모두 고쳐야 하는 상황이 생기면 구조가 잘못된 것이다. "완전 분리"는 확장 D에서 modal 하단 바 같은 **뷰별 고유 조각**에만 적용한다.
 
-### `busyMessage`는 필요할 때만 추가
+### `orderBy` 람다 + `obj.getChainValue` 회귀
 
-- 기본 예제는 `<sd-busy-container [busy]="busyCount() > 0">`만 사용하고 `busyMessage` signal을 두지 않는다. 짧은 CRUD는 progress 아이콘만으로 충분.
-- 오래 걸리는 작업(대량 엑셀 업로드·집계 등)에 진행 문구가 필요하면 **필요한 화면에만** `busyMessage = signal<string | undefined>(undefined)` 추가 + `[message]="busyMessage()"` 바인딩 + 구간별 `busyMessage.set(...)`/`set(undefined)` 제어. 미사용 시 선언·바인딩 모두 생략.
+`Queryable.orderBy`는 string overload를 지원하므로(`packages/orm-common/src/exec/queryable.ts:420`), 람다 + `obj.getChainValue` 우회 코드를 쓰지 않는다.
 
-### 테스트만을 위한 public API 금지
+```typescript
+// ❌ overload 도입 전 우회 코드 — LLM 훈련 데이터에 잔존
+for (const s of sortingDefs) {
+  qr2 = qr2.orderBy(
+    (item) => obj.getChainValue(item, s.key, true) as any,
+    s.desc ? "DESC" : "ASC",
+  );
+}
 
-- `async submit(diffs) { await this._submitAsync(diffs); }` 같이 "테스트에서 호출하려고" private 메서드의 얇은 public wrapper를 노출하지 않는다. 캡슐화를 깨고 컴포넌트의 외부 API 인상을 오염시킨다. 테스트는 TestBed fixture + click/dispatch 이벤트 경로 또는 host의 `sdSaveCommand` 트리거로 수행.
+// ✅ string overload 사용. 체인 경로도 string으로 지원: qr.orderBy("user.name")
+for (const s of sortingDefs) {
+  qr2 = qr2.orderBy(s.key, s.desc ? "DESC" : "ASC");
+}
+```
 
-## 10. 레시피 작성 관용 규칙
+**근거**: 람다 형태는 타입 추론을 깨뜨리고 `as any` 캐스팅을 강제한다. string overload는 체인 경로까지 타입 안전하게 지원한다.
 
-향후 `crud-detail.md` · `data-select-button.md` 등 데이터 관련 레시피가 추가될 때 아래 3개 규칙을 공통으로 따른다.
+### 테스트용 public API 노출
 
-### 규칙 1: 시트 셀 내부 컨트롤은 `[inset]="true" [size]="'sm'"` 명시
+테스트에서 호출하려고 private 메서드의 얇은 public wrapper를 노출하지 않는다.
 
-- `<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]` 생략
-- 누락 시 컴파일 에러가 발생하지 않아 LLM이 빠뜨리기 쉽다. 자주 하는 실수 섹션에 명시
+```typescript
+// ❌ "테스트에서 호출하려고" private 메서드를 public으로 노출
+async submit(diffs: IDiff[]): Promise<void> {
+  await this._submitAsync(diffs);
+}
 
-### 규칙 2: `mark(sig)`는 "저장 감지"가 아니라 "UI 동기화"
+// ✅ TestBed fixture + click/dispatch 이벤트 경로 또는 host의 sdSaveCommand 트리거
+fixture.nativeElement.dispatchEvent(
+  new KeyboardEvent("keydown", { key: "s", ctrlKey: true }),
+);
+```
 
-- `mark(sig)`는 `WritableSignal`의 값을 shallow copy하여 **참조를 갱신**한다 (배열: `[...v]`, 객체: `{...v}`)
-- 역할: **OnPush 템플릿 재렌더링** + **다른 computed / effect의 의존성 갱신**
-- **"저장 감지"가 아니다.** `obj.equal`이 deep equal로 값 차이를 감지하므로, `item.name = "new"` 같은 mutation은 `mark` 없이도 `diffs()` / submit에서 감지된다
-- Chrome 61 호환성(Proxy 폴리필 불가)으로 signal 자동 notify가 불가하여 명시적 호출이 필요
-- ❌ "mark 없으면 저장이 안 된다" 식 서술 금지
+**근거**: public wrapper는 캡슐화를 깨고 컴포넌트의 외부 API 인상을 오염시킨다. 실제 사용자가 쓰지 않는 진입점을 공개 API로 만들면 추후 리팩토링 시 제약이 된다.
 
-### 규칙 3: `sortingDefs` + `orderBy` 체인은 string overload 사용
+## 관련 Entry
 
-- `Queryable.orderBy`는 string overload를 지원한다 (`packages/orm-common/src/exec/queryable.ts:420`)
-- 레시피는 아래 형태로 작성:
-  ```typescript
-  for (const s of sortingDefs) {
-    qr = qr.orderBy(s.key, s.desc ? "DESC" : "ASC");
-  }
-  ```
-- 체인 경로도 string으로 지원: `qr.orderBy("user.name")` 형태
-- 과거 람다 형태 (`qr.orderBy((item) => obj.getChainValue(item, s.key, true) as any, ...)`)는 **쓰지 않는다** — overload 도입 전 우회 코드였다
+- [`_common-rules.md`](./_common-rules.md) — 4계열 레시피 횡단 공통 규칙. 본 파일에서 재정의하지 않는 모든 규칙은 여기에 있음
+- [`crud-detail.md`](./crud-detail.md) — 차이: 단일 레코드 상세 폼(뷰 범위 선택·편집·저장·삭제/복구)
+- [`data-select-button.md`](./data-select-button.md) — 차이: 모달 기반 선택 버튼 직접 조립(`<sd-modal-select-button>`)
+- [`page-modal-container.md`](./page-modal-container.md) — 차이: page/modal/control 3뷰 재사용 공통 껍데기만