@simplysm/angular 14.0.48 → 14.0.51

package/docs/recipes/crud-detail.md

@@ -1,103 +1,60 @@
 # Recipe: CRUD 상세폼 화면 직접 조립
 
-소비 화면이 `<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` · `<sd-form>` 표준 컴포넌트를 **직접 조립**하여 단일 레코드 CRUD 상세폼을 구성한다. 과거 `SdDataDetail` / `SdDataDetailBase`가 감추고 있던 load·save·delete 라이프사이클, `obj.equal` snapshot 기반 변경 감지, `setupCanDeactivate` 이탈 방지, busy 카운트, `SdToastProvider.try` 에러 래핑, Ctrl+S/Ctrl+Alt+L 단축키를 화면 내부에 인라인으로 풀어쓴다.
-
-## 1. Overview
-
-- 제거된 추상화: `SdDataDetail`(컴포넌트) / `SdDataDetailBase<T, R>`(추상 클래스) / `SdDataDetailDataInfo`(타입) / `#toolTpl`·`#prevTpl`·`#contentTpl`·`#nextTpl`·`#modalActionTpl` 슬롯 5종
-- 대체: 소비 컴포넌트가 표준 조각을 직접 조립
-- 조립 요소:
-  - `<sd-busy-container [busy] [message]>` — 전체 busy 오버레이
-  - `<sd-topbar-container>` + `<sd-topbar>` — 페이지 뷰 상단 헤더
-  - `<sd-form #formCtrl (formSubmit)>` — Ctrl+S·submit 버튼 트리거
-  - `injectViewTypeSignal()` — page / modal / control 뷰 판정
-  - `injectPermsSignal()` — 권한 signal
-  - `setupCanDeactivate()` — 이탈 방지
-  - `SdToastProvider.try(fn, messageFn)` — 에러 래퍼 + busy 카운트
-  - `SdModalContentDef<R>` — 모달 컨텐츠 인터페이스 (소비 화면이 직접 `implements`)
-  - `SdCommandDirective`(`sdRefreshCommand` / `sdSaveCommand`) — Ctrl+Alt+L / Ctrl+S 단축키
-  - `getOrmDataEditToastErrorMessage(err)` — ORM 에러 → 사용자 메시지 변환
-- 데이터 비교:
-  - `obj.clone(data)` — snapshot 복제 (`@simplysm/core-common`)
-  - `obj.equal(a, b)` — deep equal
-
-## 2. 언제 사용하는가
-
-| 상황 | 적용 여부 |
-|---|---|
-| 단일 레코드 상세 폼 (로딩/저장/삭제/복구) | 본 레시피 전체 적용 |
-| 페이지 뷰와 모달 뷰 모두에서 재사용 | 3뷰 분기 구조(§3) 그대로 사용 |
-| 마스터-디테일의 "디테일" 영역 | control 뷰 분기 활용 |
-| 메인 폼과 별개의 "가져오기/출력" 보조 기능 필요 | 레시피 + [변형 1: 보조 기능 영역](#5-변형-보조-기능-영역) |
-| 상세 폼 내부에 하위 컬렉션(박스 목록 등) 편집 | 레시피 + [변형 2: 복합 상세 (내부 `<sd-sheet>`)](#6-변형-복합-상세-내부-sd-sheet) |
-| CRUD 리스트(시트) 화면 | 본 레시피 대신 [`crud-list.md`](./crud-list.md) 사용 |
-| 페이지/모달 뷰 분기만 필요한 단순 화면 | [`page-modal-container.md`](./page-modal-container.md) 사용 |
+단일 레코드 CRUD 상세폼을, `<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` · `<sd-form>` 표준 컴포넌트를 소비 화면이 **직접 조립**하여 구성한다. 과거 `SdDataDetail` / `SdDataDetailBase`가 감추고 있던 load·save·delete 라이프사이클, snapshot 기반 변경 감지, 이탈 방지, busy 카운트, Ctrl+S/Ctrl+Alt+L 단축키를 화면 내부에 인라인으로 풀어쓴다.
+
+## When to use / When NOT to use
+
+- ✅ 단일 레코드(고객, 주문 헤더 등)의 CRUD 상세폼을 만들 때
+- ✅ page / modal / control 뷰 중 **필요한 뷰만 선택적으로** 지원해야 할 때
+- ✅ 편집·저장·삭제·복구·보조 기능·복합 상세(내부 시트)를 상황에 따라 누적해야 할 때
+- ❌ CRUD 리스트(시트) 화면 → [`crud-list.md`](./crud-list.md)
+- ❌ 페이지/모달 뷰 분기만 필요한 단순 컨테이너(라이프사이클 없음) → [`page-modal-container.md`](./page-modal-container.md)
+- ❌ 다른 화면에서 데이터를 고르는 선택 버튼 → [`data-select-button.md`](./data-select-button.md)
+
+## 전제조건
+
+- `provideSdAngular({ clientName })` 부트스트랩 완료
+- 앱별 ORM provider (예: `AppOrmProvider`) — `@simplysm/angular`가 아니라 각 앱이 소유
+- 권한 제어가 있는 경우 `SdAppStructureProvider` 등록 (`injectPermsSignal` 전제)
 
-## 3. 완성 예제
+## 기본 레시피 (page 뷰, 읽기 전용)
 
-아래는 **page·modal·control 3뷰를 모두 커버하는** 완성 컴포넌트다. 모달로 띄우면 `viewType() === "modal"`로 자동 판정되어 하단 "확인/삭제" 바와 우측 상단 "새로고침" 액션이 표시되고, 라우트로 진입하면 `"page"`로 판정되어 topbar에 저장/새로고침 버튼이 표시된다. 마스터-디테일의 디테일로 `<app-customer-detail class="flex-fill">`처럼 삽입하면 `"control"`로 판정되어 상단 바에 저장/새로고침/삭제 버튼이 표시된다.
+라우트 진입 시 `itemId`를 받아 단일 레코드를 로드하고 읽기 전용 필드로 표시하는 최소 완성 컴포넌트다. 편집·삭제·modal·control·보조·복합이 필요하면 [변형](#변형-확장-a-f-인덱스)의 확장을 선택적으로 얹는다.
 
 ```typescript
-import { NgTemplateOutlet } from "@angular/common";
 import { NgIcon } from "@ng-icons/core";
-import {
-  tablerAlertTriangle,
-  tablerDeviceFloppy,
-  tablerEraser,
-  tablerRefresh,
-  tablerRestore,
-} from "@ng-icons/tabler-icons";
+import { tablerAlertTriangle, tablerRefresh } from "@ng-icons/tabler-icons";
 import {
   ChangeDetectionStrategy,
   Component,
-  computed,
   effect,
   inject,
   input,
-  output,
   signal,
-  TemplateRef,
   untracked,
-  viewChild,
   ViewEncapsulation,
 } from "@angular/core";
-import { type DateTime, obj } from "@simplysm/core-common";
+import type { DateTime } from "@simplysm/core-common";
 import {
   FormatPipe,
-  getOrmDataEditToastErrorMessage,
-  injectCurrentPageCodeSignal,
-  injectFullPageCodeSignal,
   injectPermsSignal,
-  injectViewTypeSignal,
-  SdActivatedModalProvider,
-  SdAnchor,
-  SdAppStructureProvider,
+  injectViewTitleSignal,
   SdBusyContainer,
   SdButton,
   SdCommandDirective,
   SdForm,
-  type SdModalContentDef,
-  SdSystemLogProvider,
   SdTextfield,
   SdToastProvider,
   SdTopbar,
   SdTopbarContainer,
-  setupCanDeactivate,
 } from "@simplysm/angular";
+// 앱별 대체: ORM provider + DbContext. @simplysm/angular가 아니라 각 앱이 소유한다.
+import { AppOrmProvider } from "@adtek/client-common";
 
 interface ICustomer {
-  id: number | undefined;
+  id: number | undefined;           // undefined면 신규 — 확장 A 편집/저장 시 활용
   name: string;
   phone: string;
-  isDeleted: boolean;
-  lastModifiedAt: DateTime | undefined;
-  lastModifiedBy: string | undefined;
-}
-
-// 과거 `SdDataDetailDataInfo`에 해당 — 화면 내부에서 직접 선언한다.
-interface IDataInfo {
-  isNew: boolean;
-  isDeleted: boolean;
   lastModifiedAt: DateTime | undefined;
   lastModifiedBy: string | undefined;
 }
@@ -109,752 +66,288 @@ interface IDataInfo {
   standalone: true,
   imports: [
     SdBusyContainer, SdTopbarContainer, SdTopbar,
-    SdForm, SdButton, SdAnchor, SdTextfield,
-    FormatPipe, NgIcon, NgTemplateOutlet,
+    SdForm, SdButton, SdTextfield,
+    FormatPipe, NgIcon,
   ],
   hostDirectives: [
-    { directive: SdCommandDirective, outputs: ["sdRefreshCommand", "sdSaveCommand"] },
+    { directive: SdCommandDirective, outputs: ["sdRefreshCommand"] },
   ],
   host: {
     "(sdRefreshCommand)": "onRefreshButtonClick()",
-    "(sdSaveCommand)": "onSubmitButtonClick()",
   },
   template: `
-    <sd-busy-container [busy]="busyCount() > 0" [message]="busyMessage()">
+    <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]="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>
-              @if (canEdit()) {
-                <sd-button [theme]="'link-primary'" (click)="onSubmitButtonClick()">
-                  <ng-icon [svg]="icons.tablerDeviceFloppy" />
-                  저장 <small>(CTRL+S)</small>
-                </sd-button>
-              }
+              <h4>{{ viewTitle() }}</h4>
+
               <sd-button [theme]="'link-info'" (click)="onRefreshButtonClick()">
-                <ng-icon [svg]="icons.tablerRefresh" />
-                새로고침 <small>(CTRL+ALT+L)</small>
+                <ng-icon [svg]="tablerRefresh" />
+                새로고침
+                <small>(CTRL+ALT+L)</small>
               </sd-button>
             </sd-topbar>
-            <div class="fill">
-              <ng-template [ngTemplateOutlet]="formTpl" />
-            </div>
-          </sd-topbar-container>
-        } @else if (viewType() === "modal") {
-          <div class="flex-column fill">
-            <div class="flex-fill">
-              <ng-template [ngTemplateOutlet]="formTpl" />
-            </div>
-            @if (canEdit()) {
-              <div class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest">
-                @if (!dataInfo()?.isNew && canDelete()) {
-                  @if (dataInfo()?.isDeleted) {
-                    <sd-button [size]="'sm'" [theme]="'warning'" (click)="onRestoreButtonClick()">
-                      복구
-                    </sd-button>
-                  } @else {
-                    <sd-button [size]="'sm'" [theme]="'danger'" (click)="onDeleteButtonClick()">
-                      삭제
-                    </sd-button>
-                  }
-                }
-                <div class="flex-fill flex-row gap-sm main-align-end">
-                  <sd-button [size]="'sm'" [theme]="'primary'" (click)="onSubmitButtonClick()">
-                    확인
-                  </sd-button>
+
+            <div class="flex-column fill">
+              <sd-form class="flex-fill">
+                <div class="p-default">
+                  <table class="form-table">
+                    <tbody>
+                      <tr>
+                        <th>명칭</th>
+                        <td>
+                          <sd-textfield
+                            [type]="'text'"
+                            [readonly]="true"
+                            [(value)]="data().name"
+                          />
+                        </td>
+                      </tr>
+                      <tr>
+                        <th>전화번호</th>
+                        <td>
+                          <sd-textfield
+                            [type]="'text'"
+                            [readonly]="true"
+                            [(value)]="data().phone"
+                          />
+                        </td>
+                      </tr>
+                    </tbody>
+                  </table>
                 </div>
-              </div>
-            }
-          </div>
-        } @else {
-          <!-- control 뷰: 다른 화면의 영역으로 삽입된 상태 -->
-          <div class="flex-column fill">
-            @if (canEdit()) {
-              <div class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">
-                <sd-button [theme]="'primary'" (click)="onSubmitButtonClick()">
-                  <ng-icon [svg]="icons.tablerDeviceFloppy" />
-                  저장 <small>(CTRL+S)</small>
-                </sd-button>
-                <sd-button [theme]="'info'" (click)="onRefreshButtonClick()">
-                  <ng-icon [svg]="icons.tablerRefresh" />
-                  새로고침 <small>(CTRL+ALT+L)</small>
-                </sd-button>
-                @if (!dataInfo()?.isNew && canDelete()) {
-                  @if (dataInfo()?.isDeleted) {
-                    <sd-button [theme]="'warning'" (click)="onRestoreButtonClick()">
-                      <ng-icon [svg]="icons.tablerRestore" />
-                      복구
-                    </sd-button>
-                  } @else {
-                    <sd-button [theme]="'danger'" (click)="onDeleteButtonClick()">
-                      <ng-icon [svg]="icons.tablerEraser" />
-                      삭제
-                    </sd-button>
+              </sd-form>
+
+              @if (data().lastModifiedAt || data().lastModifiedBy) {
+                <div class="p-sm-default">
+                  최종수정:
+                  @if (data().lastModifiedAt) {
+                    {{ data().lastModifiedAt | format: "yyyy-MM-dd HH:mm" }}
                   }
-                }
-              </div>
-            }
-            <div class="flex-fill">
-              <ng-template [ngTemplateOutlet]="formTpl" />
+                  @if (data().lastModifiedBy) {
+                    ({{ data().lastModifiedBy }})
+                  }
+                </div>
+              }
             </div>
-          </div>
+          </sd-topbar-container>
         }
       }
     </sd-busy-container>
-
-    <!-- 모달 뷰에서만 사용되는 우측 상단 액션 템플릿.
-         SdModalProvider가 contentComponent.actionTplRef를 setter 프록시로 감싸 SdModal로 브릿지한다.
-         (packages/angular/src/core/modal/sd-modal.provider.ts:140-150) -->
-    <ng-template #modalActionTpl>
-      <sd-anchor
-        [theme]="'gray'"
-        class="p-sm-default"
-        (click)="onRefreshButtonClick()"
-        title="새로고침(CTRL+ALT+L)"
-      >
-        <ng-icon [svg]="icons.tablerRefresh" />
-      </sd-anchor>
-    </ng-template>
-
-    <ng-template #formTpl>
-      <div class="flex-column fill">
-        <div class="flex-fill">
-          <sd-form #formCtrl (formSubmit)="onSubmit()">
-            <div class="p-default">
-              <table class="form-table">
-                <tbody>
-                  <tr>
-                    <th>명칭</th>
-                    <td>
-                      <sd-textfield
-                        [type]="'text'"
-                        [required]="true"
-                        [disabled]="!canEdit()"
-                        [(value)]="data().name"
-                      />
-                    </td>
-                  </tr>
-                  <tr>
-                    <th>전화번호</th>
-                    <td>
-                      <sd-textfield
-                        [type]="'text'"
-                        [disabled]="!canEdit()"
-                        [(value)]="data().phone"
-                      />
-                    </td>
-                  </tr>
-                </tbody>
-              </table>
-            </div>
-          </sd-form>
-        </div>
-        @if (dataInfo()?.lastModifiedAt || dataInfo()?.lastModifiedBy) {
-          <div
-            class="p-sm-default"
-            [class.bg-theme-gray-lightest]="viewType() === 'modal'"
-          >
-            최종수정:
-            @if (dataInfo()?.lastModifiedAt) {
-              {{ dataInfo()!.lastModifiedAt | format: "yyyy-MM-dd HH:mm" }}
-            }
-            @if (dataInfo()?.lastModifiedBy) {
-              ({{ dataInfo()?.lastModifiedBy }})
-            }
-          </div>
-        }
-      </div>
-    </ng-template>
   `,
 })
-export class CustomerDetail implements SdModalContentDef<boolean | undefined> {
+export class CustomerDetail {
   //== DI ==
+  private readonly _appOrm = inject(AppOrmProvider);
   private readonly _sdToast = inject(SdToastProvider);
-  private readonly _sdActivatedModal = inject(SdActivatedModalProvider, { optional: true });
-  private readonly _sdAppStructure = inject(SdAppStructureProvider);
-  private readonly _sdSystemLog = inject(SdSystemLogProvider);
 
   //== input ==
   itemId = input<number>();
 
-  //== 라우팅 / 권한 ==
-  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"],
-  );
-  // canDelete를 canEdit와 분리해서 제한하고 싶으면 별도 권한 signal로 교체
-  protected readonly canDelete = computed(() => this.canEdit());
+  //== 타이틀 / 권한 ==
+  protected readonly viewTitle = injectViewTitleSignal();
+  perms = injectPermsSignal(["sales.customer"], ["use"]);
 
   //== 상태 ==
   protected readonly busyCount = signal(0);
-  protected readonly busyMessage = signal<string | undefined>(undefined);
   protected readonly initialized = signal(false);
-  protected readonly data = signal<ICustomer>({} as ICustomer);
-  protected readonly dataInfo = signal<IDataInfo | undefined>(undefined);
-  private _snapshot?: ICustomer;
-
-  //== SdModalContentDef<boolean | undefined> 요구 필드 ==
-  close = output<boolean | undefined>();
-  // actionTplRef는 SdModal이 setter 프록시로 감싸므로 필드 선언만으로 충분
-  actionTplRef?: TemplateRef<any>;
-
-  //== viewChild ==
-  protected readonly formCtrl = viewChild<SdForm>("formCtrl");
-  private readonly _modalActionTpl = viewChild("modalActionTpl", { read: TemplateRef });
-
-  //== 파생 ==
-  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 "";
-    }
+  protected readonly data = signal<ICustomer>({
+    id: undefined,
+    name: "",
+    phone: "",
+    lastModifiedAt: undefined,
+    lastModifiedBy: undefined,
   });
 
-  protected readonly icons = {
-    tablerAlertTriangle, tablerDeviceFloppy, tablerEraser, tablerRefresh, tablerRestore,
-  };
-
   //== 라이프사이클 ==
   constructor() {
     // 최초 진입 + itemId 변경 시 재조회.
-    // effect의 자체 cleanup이 이중 실행을 방지하므로 queueMicrotask + cancelled 플래그는 불필요.
     effect(() => {
       this.itemId(); // 의존성 등록
-      if (!this.canUse()) {
+      if (!this.perms().includes("use")) {
         this.initialized.set(true);
         return;
       }
-      untracked(() => {
-        void this._initRefresh();
-      });
-    });
-
-    // 모달 뷰에서는 SdActivatedModal의 canDeactivateFn에, 페이지 뷰에서는 라우트 guard에 등록된다.
-    setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges());
 
-    // 모달 헤더 우측 액션 슬롯 브릿지 (control/page 뷰에선 _modalActionTpl이 렌더되지 않아 undefined)
-    effect(() => {
-      this.actionTplRef = this._modalActionTpl();
+      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);
+      });
     });
   }
 
   //== 이벤트 핸들러 ==
   protected async onRefreshButtonClick(): Promise<void> {
     if (this.busyCount() > 0) return;
-    if (!this.canUse()) return;
-    if (!this._checkIgnoreChanges()) return;
-    await this._refresh();
-  }
-
-  protected onSubmitButtonClick(): void {
-    this.formCtrl()?.requestSubmit();
-  }
-
-  protected async onSubmit(): Promise<void> {
-    if (this.busyCount() > 0) return;
-    if (!this.canEdit()) return;
-    const info = this.dataInfo();
-    if (info == null) return;
-
-    // isNew면 변경사항 체크 없이 저장. 기존 항목이면 snapshot 대비 변경사항 여부 판정.
-    if (!info.isNew && this._snapshot != null && obj.equal(this.data(), this._snapshot)) {
-      this._sdToast.info("변경사항이 없습니다.");
-      return;
-    }
+    if (!this.perms().includes("use")) return;
 
+    this.busyCount.update((v) => v + 1);
     await this._sdToast.try(async () => {
-      this.busyCount.update((v) => v + 1);
-      try {
-        const ok = await this._saveAsync(this.data());
-        if (!ok) return;
-        this._sdToast.success("저장되었습니다.");
-        this.close.emit(true);
-        await this._refresh();
-      } finally {
-        this.busyCount.update((v) => v - 1);
-      }
-    }, getOrmDataEditToastErrorMessage);
-  }
-
-  protected async onDeleteButtonClick(): Promise<void> {
-    await this._toggleDelete(true);
-  }
-
-  protected async onRestoreButtonClick(): Promise<void> {
-    await this._toggleDelete(false);
+      await this._refresh();
+    });
+    this.busyCount.update((v) => v - 1);
   }
 
   //== 내부 메서드 ==
-  private async _toggleDelete(del: boolean): Promise<void> {
-    if (this.busyCount() > 0) return;
-    if (!this.canEdit()) return;
-    if (!this.canDelete()) return;
-
-    await this._sdToast.try(async () => {
-      this.busyCount.update((v) => v + 1);
-      try {
-        const ok = await this._deleteAsync(del);
-        if (!ok) return;
-        this._sdToast.success(`${del ? "삭제" : "복구"}되었습니다.`);
-        this.close.emit(true);
-      } finally {
-        this.busyCount.update((v) => v - 1);
-      }
-    }, getOrmDataEditToastErrorMessage);
-  }
-
-  private _checkIgnoreChanges(): boolean {
-    return (
-      this._snapshot == null ||
-      obj.equal(this.data(), this._snapshot) ||
-      confirm("변경사항이 있습니다. 무시하고 진행하시겠습니까?")
-    );
-  }
-
-  private async _initRefresh(): Promise<void> {
-    await this._refresh();
-    this.initialized.set(true);
-  }
-
   private async _refresh(): Promise<void> {
-    await this._sdToast.try(async () => {
-      this.busyCount.update((v) => v + 1);
-      try {
-        const r = await this._loadAsync();
-        this.data.set(r.data);
-        this.dataInfo.set(r.info);
-        // isNew면 스냅샷 저장 생략 — 변경사항 체크를 항상 통과시켜 저장 허용
-        this._snapshot = r.info.isNew ? undefined : obj.clone(r.data);
-      } finally {
-        this.busyCount.update((v) => v - 1);
-      }
-    }, getOrmDataEditToastErrorMessage);
-  }
-
-  //== 앱별 구현 ==
-  private async _loadAsync(): Promise<{ data: ICustomer; info: IDataInfo }> {
+    let data: ICustomer;
     if (this.itemId() == null) {
-      return {
-        data: { id: undefined, name: "", phone: "", isDeleted: false,
-                lastModifiedAt: undefined, lastModifiedBy: undefined },
-        info: { isNew: true, isDeleted: false,
-                lastModifiedAt: undefined, lastModifiedBy: undefined },
+      data = {
+        id: undefined, name: "", phone: "",
+        lastModifiedAt: undefined, lastModifiedBy: undefined,
       };
+    } else {
+      // 앱별 ORM 조회 — 예:
+      //   data = await this._appOrm.connectAsync(async (db) =>
+      //     (await db.customer.where((it) => [expr.eq(it.id, this.itemId())]).single())!
+      //   );
+      throw new Error("구현 필요");
     }
-    // ORM 호출 예시:
-    //   return this._appOrm.connectAsync(async (db) => {
-    //     const data = (await db.customer
-    //       .where((it) => [expr.eq(it.id, this.itemId())])
-    //       .single())!;
-    //     return {
-    //       data,
-    //       info: { isNew: false, isDeleted: data.isDeleted,
-    //               lastModifiedAt: data.lastModifiedAt, lastModifiedBy: data.lastModifiedBy },
-    //     };
-    //   });
-    throw new Error("구현 필요");
-  }
 
-  private async _saveAsync(_data: ICustomer): Promise<boolean> {
-    // ORM upsert 후 true 반환. 검증 실패 시 undefined 반환하면 close/토스트 생략.
-    throw new Error("구현 필요");
+    this.data.set(data);
   }
 
-  private async _deleteAsync(_del: boolean): Promise<boolean> {
-    // if (del && !confirm("삭제하시겠습니까?")) return false;
-    // ORM delete/restore 후 true 반환
-    throw new Error("구현 필요");
-  }
+  //== for Template ==
+  protected readonly tablerAlertTriangle = tablerAlertTriangle;
+  protected readonly tablerRefresh = tablerRefresh;
 }
 ```
 
-## 4. 분해 설명
-
-각 블록의 역할과 원본 `SdDataDetail`/`SdDataDetailBase` 코드 대응 지점:
-
-| 블록 | 역할 | 원본 대응 |
-|---|---|---|
-| `<sd-busy-container [busy] [message]>` | 전체 busy 오버레이 | `sd-data-detail.ts:53-54` + `SdBaseContainer` |
-| `@if (initialized())` | 최초 조회 완료 전 본문 숨김 | `sd-data-detail.base.ts:92` `initialized.set(true)` |
-| `@if (!canUse())` | 권한 없음 메시지 | `sd-base-container.ts:44-51` + `page-modal-container.md` |
-| `@else if (viewType() === "page")` / `"modal"` / `@else` | 뷰 타입 분기 (`page-modal-container.md` 참조) | `sd-data-detail.ts:53, 56-58` `viewType` → `SdBaseContainer` 내부 분기 |
-| `<sd-topbar-container>` + `<sd-topbar>` | 페이지 뷰 헤더 (저장/새로고침) | `sd-data-detail.ts:60-73` `#pageTopbarTpl` |
-| modal 분기 하단 확인/삭제 바 | 모달 하단 액션 | `sd-data-detail.ts:151-175` `#modalBottomTpl` |
-| control 분기 상단 바 (저장/새로고침/삭제) | 마스터-디테일의 디테일 도구 바 | `sd-data-detail.ts:77-109` |
-| `<ng-template #modalActionTpl>` + `effect(() => actionTplRef = _modalActionTpl())` | 모달 우측 상단 새로고침 액션 (`SdModal`이 setter 프록시로 브릿지) | `sd-data-detail.ts:177-186, 201-207` `#modalActionTpl` + `parent.actionTplRef = ...` |
-| `<sd-form #formCtrl (formSubmit)>` + 최종수정 표시 | 폼 본문 + `lastModifiedAt/By` | `sd-data-detail.ts:121-140` |
-| `hostDirectives` + `SdCommandDirective` | Ctrl+Alt+L / Ctrl+S 단축키 | `sd-data-detail.ts:45-51` |
-| `setupCanDeactivate(() => viewType() === "modal" || checkIgnoreChanges())` | 라우트 이탈 시 변경사항 확인 | `sd-data-detail.base.ts:99` |
-| `_refresh()` 내 `busyCount.update + try/finally + sdToast.try` | busy 카운트 증감 + 에러 토스트 | `sd-data-detail.base.ts:86-91, 115-119` |
-| `_snapshot = obj.clone(data)` + `obj.equal` 비교 | 변경 감지 | `sd-data-detail.base.ts:66, 127, 102-108, 162` |
-| `effect(() => { itemId(); if (!canUse()) return; untracked(() => void this._initRefresh()); })` | 최초 로드 + input 변경 시 자동 reload | `sd-data-detail.base.ts:69-97` + `prepareRefreshEffect` 슬롯 |
-| `close = output<R | undefined>()` + `implements SdModalContentDef<R>` | 모달 컨텐츠 계약 | `sd-data-detail.base.ts:29-30, 59` |
-
-### 상태 분해
-
-| signal / 필드 | 역할 |
-|---|---|
-| `busyCount` | 중첩 비동기 작업 카운트 (0 초과 시 busy 표시) |
-| `busyMessage` | busy 오버레이 문구 |
-| `initialized` | 최초 조회 완료 여부 (완료 전 본문 숨김) |
-| `data` | 현재 편집 중인 데이터 (load 결과) |
-| `dataInfo` | isNew/isDeleted/lastModifiedAt/lastModifiedBy 메타 정보 |
-| `_snapshot` | 직전 `_refresh()` 시점의 data 깊은 복제본 (변경 감지용). `isNew`면 `undefined` |
-| `close` | 모달 결과 output (`SdModalContentDef` 요구) |
-| `actionTplRef` | 모달 우측 상단 액션 슬롯. `SdModal`이 setter 프록시로 자동 브릿지 |
-
-### 메서드 분해
-
-| 메서드 | 역할 |
-|---|---|
-| `onRefreshButtonClick()` | busy/권한/변경사항 가드 후 `_refresh()` |
-| `onSubmitButtonClick()` | `formCtrl()?.requestSubmit()` — Ctrl+S와 동일 경로 |
-| `onSubmit()` | `canEdit` 체크 + snapshot 대비 변경사항 여부 판정 + `_saveAsync(data)` + 성공 토스트 + `close.emit(true)` + `_refresh()` |
-| `onDeleteButtonClick()` / `onRestoreButtonClick()` | `_toggleDelete(del)` 호출 |
-| `_toggleDelete(del)` | busy/권한 가드 + `_deleteAsync(del)` + 토스트 + `close.emit(true)` |
-| `_checkIgnoreChanges()` | snapshot 없거나 동일하면 true, 아니면 `confirm(...)` |
-| `_initRefresh()` / `_refresh()` | `_loadAsync()` → `data.set` + `dataInfo.set` + snapshot 갱신 (isNew면 미저장) |
-| `_loadAsync()` / `_saveAsync(data)` / `_deleteAsync(del)` | 앱별 ORM/API 구현 |
+### 조건부 요소 포함 기준
 
-## 5. 변형: 보조 기능 영역
+인프라·라이프사이클 요소는 화면 요건에 따라 포함·생략한다. 필요 없는 요소를 기계적으로 포함하지 않는다.
 
-메인 폼의 submit과 별개인 보조 기능(예: 다른 사용자로부터 권한 복사, 출력 등)은 control 뷰 상단 바 또는 모달 하단 바 옆에 별도의 `<sd-form>`으로 배치한다. 과거 `#toolTpl` 슬롯이 담당하던 역할을 소비 화면에 직접 인라인한다.
+| 요소 | 포함 조건 | 생략 예시 |
+|------|----------|----------|
+| `<sd-topbar-container>` + `<sd-topbar>` | routes로 연결된 page에서 헤더가 필요할 때. 기본 레시피는 page 전용이라 조건 없이 렌더 | route 미연결(control·래퍼) |
+| `injectViewTitleSignal()` | topbar에 타이틀을 표시할 때 | topbar 없음·타이틀 불필요 |
+| `injectViewTypeSignal()` + 분기 | page 외에 modal/control로도 겸용될 때. 기본 레시피는 page 전용이므로 **미포함** — [확장 C](./crud-detail/extension-c-modal-view.md) / [확장 D](./crud-detail/extension-d-control-view.md)에서 도입 | page 전용 |
+| `injectPermsSignal()` + 권한 없음 블록 | 권한 제어가 있는 화면 | 권한 제어 없음 |
+| `<sd-busy-container>` + `busyCount` | 비동기 작업(DB 조회 등)이 있어 busy 표시가 필요할 때 | 동기 래퍼·레이아웃 |
+| `initialized` + `@if (initialized())` | 초기 로딩 완료 전 깜박임 방지가 필요할 때 | 빈 상태 렌더가 무방 |
 
-`CustomerDetail`을 기준으로 아래 변경을 적용한다.
-
-```typescript
-// 1) imports 추가
-import { SdSharedDataSelect } from "@simplysm/angular";
-// ... (앱 공용 useSharedSignal 등)
-
-// 2) 클래스에 필드 추가
-protected readonly permCopySourceId = signal<number | undefined>(undefined);
-protected readonly sharedUsers = useSharedSignal("사용자");  // 앱 공용 provider
-
-// 3) template — control 분기 또는 modal 분기 상단/하단에 보조 form 삽입.
-//    아래는 control 뷰 분기 내부에 추가하는 예시 (위치: "저장/새로고침/삭제" 바 옆).
-@if (viewType() === "control") {
-  <div class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">
-    <!-- 기본 저장/새로고침/삭제 버튼 -->
-    <!-- ... -->
-
-    <!-- 보조 기능: 다른 사용자로부터 가져오기 -->
-    <sd-form (formSubmit)="onImportFormSubmit()">
-      <div class="form-box-inline">
-        <div>
-          <label>가져오기</label>
-          <sd-shared-data-select
-            [items]="sharedUsers.items()"
-            [(value)]="permCopySourceId"
-            [inset]="true"
-            [size]="'sm'"
-          />
-        </div>
-        <div>
-          <sd-button [type]="'submit'" [disabled]="permCopySourceId() == null">
-            가져오기
-          </sd-button>
-        </div>
-      </div>
-    </sd-form>
-  </div>
-}
+## 변형 (확장 A~F 인덱스)
 
-// 4) 메서드 추가
-protected async onImportFormSubmit(): Promise<void> {
-  if (this.busyCount() > 0 || !this.canEdit()) return;
-  if (this.permCopySourceId() == null) return;
-  if (!this._checkIgnoreChanges()) return;
+| 상황 | 시작 지점 + 필요한 확장 |
+|---|---|
+| 단일 레코드 **읽기 전용 상세 폼** (page 뷰, 감사 필드 표시) | 기본 레시피만 |
+| 편집·저장 가능한 단일 레코드 상세 폼 | 기본 + [확장 A](./crud-detail/extension-a-edit-save.md) |
+| 삭제·복구 토글 포함 | 기본 + A + [확장 B](./crud-detail/extension-b-delete-restore.md) |
+| page + **modal 뷰** 재사용 (확인·취소·삭제·복구 하단 바) | 기본 + A + B + [확장 C](./crud-detail/extension-c-modal-view.md) |
+| 마스터-디테일의 "디테일" 영역 (**control 뷰**) | 기본 + A + B + [확장 D](./crud-detail/extension-d-control-view.md) |
+| page + modal + control **3뷰** 모두 지원 | 기본 + A + B + C + D |
+| 메인 폼과 별개의 **보조 기능** (가져오기/출력 등) | 기본 + A + [확장 E](./crud-detail/extension-e-auxiliary.md) |
+| 상세 폼 내부에 **하위 컬렉션** 편집 (박스 목록 등) | 기본 + A + [확장 F](./crud-detail/extension-f-complex-detail.md) |
 
-  await this._sdToast.try(async () => {
-    this.busyCount.update((v) => v + 1);
-    try {
-      // 서버 호출로 다른 사용자의 데이터를 조회
-      //   const src = await this._api.fetchByIdAsync(this.permCopySourceId()!);
-      //   this.data.set({ ...this.data(), ...src });
-    } finally {
-      this.busyCount.update((v) => v - 1);
-    }
-  }, getOrmDataEditToastErrorMessage);
-}
-```
+### 각 확장 요약
 
-**포인트:**
+- **A. 편집/저장** (선행: 없음) — 읽기 전용을 편집 가능으로 전환. snapshot 기반 변경 감지, `setupCanDeactivate` 이탈 방지, Ctrl+S 일괄 저장. → [상세](./crud-detail/extension-a-edit-save.md)
+- **B. 삭제/복구 토글** (선행: A) — soft-delete 전제. `isDeleted` 필드 + 삭제·복구 버튼. → [상세](./crud-detail/extension-b-delete-restore.md)
+- **C. modal 뷰** (선행: A + B) — `SdModalContentDef` 계약, 하단 액션 바, 모달 우측 상단 액션 슬롯. → [상세](./crud-detail/extension-c-modal-view.md)
+- **D. control 뷰** (선행: A + B) — 마스터-디테일 디테일 영역. 상단 `<sd-dock>` 도구 바. 확장 C와 병행 가능. → [상세](./crud-detail/extension-d-control-view.md)
+- **E. 보조 기능 영역** (선행: A) — 메인 submit과 분리된 보조 `<sd-form>`. 권한 복사·출력 등. → [상세](./crud-detail/extension-e-auxiliary.md)
+- **F. 복합 상세** (선행: A) — 내부 `<sd-sheet>` 중첩, `oneWayDiffs` 기반 일괄 저장. → [상세](./crud-detail/extension-f-complex-detail.md)
 
-- 보조 `<sd-form>`과 메인 `<sd-form #formCtrl>`은 **별도의 form**이다. 보조 form의 submit 버튼은 Ctrl+S와 연동되지 않는다(`SdCommandDirective`의 `sdSaveCommand`는 메인 `formCtrl`의 `requestSubmit()`에만 연결).
-- 보조 form의 작업 후에도 `_checkIgnoreChanges()`를 호출하여 메인 폼의 미저장 변경사항을 보호한다.
-- 출력·엑셀 다운로드 같은 read-only 보조 기능은 `formSubmit` 대신 버튼의 `(click)`으로 처리 가능. 이 경우 `<sd-form>` 래핑은 생략한다.
+## 🚫 흔한 실수 (Anti-patterns)
 
-## 6. 변형: 복합 상세 (내부 `<sd-sheet>`)
+> 공통 규칙(`mark` 오용, `injectViewTypeSignal()` 호출 위치, `_sdSharedData.wait()` 조건, 시트 셀 `[inset]`/`[size]`, soft-delete 선택 기준 등)은 [레시피 공통 규칙](./_common-rules.md)을 참조한다. 이 섹션은 **CRUD 상세폼 진입점 고유 실수**만 다룬다.
 
-상세 폼 안에 하위 컬렉션(박스 목록, 품목 라인 등)을 편집할 때 `<sd-form>` 본문 내부에 `<sd-sheet>`를 중첩한다. 하위 컬렉션의 행 추가·수정·삭제는 `item.isDeleted = true` 플래그로 soft-delete하여 `ArrayOneWayDiffResult` 기반 일괄 저장에 포함시킨다.
+### 지원할 뷰를 확인하지 않고 3뷰 분기를 미리 박는다
 
 ```typescript
-// 1) imports 추가
-import { SdSheet, SdSheetColumn, SdSheetColumnCellTemplate } from "@simplysm/angular";
-import { mark, Uuid } from "@simplysm/core-common";
-import { tablerCirclePlus } from "@ng-icons/tabler-icons";
-import "@simplysm/core-common";  // Array.prototype.oneWayDiffs 프로토타입 확장
-
-// 2) 데이터 타입 확장
-interface ICustomer {
-  id: number | undefined;
-  name: string;
-  phone: string;
-  isDeleted: boolean;
-  lastModifiedAt: DateTime | undefined;
-  lastModifiedBy: string | undefined;
-  boxes: ICustomerBox[];  // 하위 컬렉션 추가
-}
-
-interface ICustomerBox {
-  id: string;  // 클라이언트 생성 UUID (서버 저장 시 교체 가능)
-  seq: number;
-  note: string;
-  isDeleted: boolean;
-}
-
-// 3) template — formTpl 본문의 table 아래에 <sd-sheet> 중첩
-<ng-template #formTpl>
-  <div class="flex-column fill">
-    <div class="flex-fill flex-column">
-      <sd-form #formCtrl (formSubmit)="onSubmit()" class="flex-column fill">
-        <!-- 상단 단일 필드 -->
-        <div class="p-default">
-          <table class="form-table">
-            <tbody>
-              <tr>
-                <th>명칭</th>
-                <td>
-                  <sd-textfield
-                    [type]="'text'"
-                    [required]="true"
-                    [disabled]="!canEdit()"
-                    [(value)]="data().name"
-                  />
-                </td>
-              </tr>
-            </tbody>
-          </table>
-        </div>
-
-        <!-- 하위 컬렉션 도구 영역 -->
-        @if (canEdit()) {
-          <div class="flex-row gap-sm p-xs-default">
-            <sd-button [size]="'sm'" [theme]="'link-primary'" (click)="onAddBoxButtonClick()">
-              <ng-icon [svg]="icons.tablerCirclePlus" />
-              박스 추가
-            </sd-button>
-          </div>
+// ❌ 실제로는 page 뷰만 쓰는데 modal·control 분기를 선제 조립
+// close output, viewType, <sd-dock [position]="'bottom'">, <ng-template #modalActionTpl>가
+// 모두 죽은 코드로 남고, implements SdModalContentDef 경로는 호출되지 않는다.
+@Component({ /* ... */ })
+export class CustomerDetail implements SdModalContentDef<boolean | undefined> {
+  close = output<boolean | undefined>();
+  protected readonly viewType = injectViewTypeSignal();
+  // ...
+  template: `
+    <sd-topbar-container>
+      @if (viewType() === "page") { <sd-topbar>...</sd-topbar> }
+      <sd-dock-container>
+        @if (viewType() === "control" && canEdit()) { <sd-dock>...</sd-dock> }
+        @if (viewType() === "modal" && canEdit()) {
+          <sd-dock [position]="'bottom'">...</sd-dock>
         }
-
-        <!-- 하위 컬렉션 시트 -->
-        <div class="flex-fill">
-          <sd-sheet
-            [items]="data().boxes"
-            [trackByFn]="boxTrackByFn"
-            [getItemCellStyleFn]="getBoxCellStyleFn"
-          >
-            @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]="data().boxes" let-item="item">
-                  <div class="p-xs-sm tx-center">
-                    <sd-anchor
-                      [theme]="'danger'"
-                      (click)="onToggleDeleteBoxButtonClick(item)"
-                    >
-                      <ng-icon [svg]="item.isDeleted ? icons.tablerRestore : icons.tablerEraser" />
-                    </sd-anchor>
-                  </div>
-                </ng-template>
-              </sd-sheet-column>
-            }
-            <sd-sheet-column [key]="'seq'" [header]="'박스#'">
-              <ng-template [cell]="data().boxes" let-item="item">
-                <sd-textfield
-                  [type]="'number'"
-                  [required]="true"
-                  [disabled]="!canEdit()"
-                  [(value)]="item.seq"
-                  [inset]="true"
-                  [size]="'sm'"
-                />
-              </ng-template>
-            </sd-sheet-column>
-            <sd-sheet-column [key]="'note'" [header]="'비고'">
-              <ng-template [cell]="data().boxes" let-item="item">
-                <sd-textfield
-                  [type]="'text'"
-                  [disabled]="!canEdit()"
-                  [(value)]="item.note"
-                  [inset]="true"
-                  [size]="'sm'"
-                />
-              </ng-template>
-            </sd-sheet-column>
-          </sd-sheet>
-        </div>
-      </sd-form>
-    </div>
-    <!-- 최종수정 표시는 그대로 -->
-  </div>
-</ng-template>
-
-// 4) 메서드 추가
-protected readonly boxTrackByFn = (item: ICustomerBox): string => item.id;
-
-protected readonly getBoxCellStyleFn = (item: ICustomerBox): string | undefined =>
-  item.isDeleted ? "text-decoration: line-through;" : undefined;
-
-protected onAddBoxButtonClick(): void {
-  const newBox: ICustomerBox = {
-    id: Uuid.generate().toString(),
-    seq: (this.data().boxes.at(-1)?.seq ?? 0) + 1,
-    note: "",
-    isDeleted: false,
-  };
-  this.data().boxes.push(newBox);
-  mark(this.data);
+      </sd-dock-container>
+    </sd-topbar-container>
+    <ng-template #modalActionTpl>...</ng-template>
+  `
 }
 
-protected onToggleDeleteBoxButtonClick(item: ICustomerBox): void {
-  item.isDeleted = !item.isDeleted;
-  mark(this.data);
+// ✅ 기본 레시피는 page 전용으로 시작. 필요한 뷰가 생기면 확장을 얹는다
+// modal 뷰가 필요해지는 시점에 확장 C를, control 뷰는 확장 D를 추가.
+@Component({ /* ... */ })
+export class CustomerDetail {
+  itemId = input<number>();
+  // page 전용 — viewType 분기·close output 없음
 }
+```
 
-// 5) _saveAsync 내부에서 diff 계산 + 일괄 제출
-private async _saveAsync(data: ICustomer): Promise<boolean> {
-  // 삭제 플래그가 섞여 있으면 confirm
-  if (data.boxes.some((b) => b.isDeleted)) {
-    if (!confirm("삭제 표시된 박스가 있습니다. 정말 저장하시겠습니까?")) {
-      return false;
-    }
-  }
+**근거**: 실제 호출되지 않는 뷰의 계약·분기·슬롯은 죽은 코드로 남아 LLM이 모달 사용처 탐색 시 오판 원인이 된다. 지원할 뷰를 먼저 확정하고 필요한 확장만 얹는다.
 
-  // 하위 컬렉션 diff 계산 — `type: "create" | "update" | "same"`
-  const snapshotBoxes = this._snapshot?.boxes ?? [];
-  const boxDiffs = data.boxes.oneWayDiffs(snapshotBoxes, "id");
+### `effect` 내부 비동기 호출을 `untracked`로 감싸지 않는다
 
-  // ORM 호출 (앱별 구현):
-  //   await this._appOrm.connectAsync(async (db) => {
-  //     await db.customer.upsertAsync(data);
-  //     for (const d of boxDiffs) {
-  //       if (d.type === "create") await db.customerBox.insertAsync(d.target);
-  //       else if (d.type === "update") await db.customerBox.updateAsync(d.target);
-  //     }
-  //   });
+```typescript
+// ❌ _refresh() 내부에서 읽는 signal이 effect 의존성으로 등록 → 무한 루프
+constructor() {
+  effect(() => {
+    this.itemId();
+    void this._refresh(); // 내부의 this.data()·this.perms() 읽기가 그대로 의존성화
+  });
+}
 
-  return true;
+// ✅ 비동기 작업은 untracked로 감싸 의존성 등록을 차단한다
+constructor() {
+  effect(() => {
+    this.itemId(); // 여기서만 의존성 등록
+    void untracked(async () => {
+      await this._sdToast.try(() => this._refresh());
+    });
+  });
 }
 ```
 
-**포인트:**
-
-- 하위 컬렉션의 **삭제는 `isDeleted: true` 플래그로 표현**한다. `data().boxes`에서 row를 물리적으로 제거하면 `oneWayDiffs`가 해당 row를 감지하지 못한다 (`oneWayDiffs`는 `type: "create" | "update" | "same"`만 반환, **`"delete"` 없음**). 서버가 soft-delete 처리.
-- 시트 셀 내부 컨트롤은 **`[inset]="true" [size]="'sm'"` 명시 필수** (§9 관용 규칙 1 참조).
-- `data().boxes.push(newBox)` 같은 배열 mutation 후에는 `mark(this.data)`로 signal 참조를 갱신해야 OnPush 템플릿이 재렌더링된다(§9 관용 규칙 2 참조).
-- `id`는 **클라이언트에서 UUID로 생성**하여 `trackByFn` + `oneWayDiffs`의 key로 사용. 서버가 발급한 PK가 별도로 있다면 별도 컬럼으로 관리하고 클라이언트 UUID는 row 식별자로만 사용.
-
-## 7. 뷰 타입 분기
-
-`@if (viewType() === "page") ... @else if (viewType() === "modal") ... @else { ... }` 분기 구조와 `modalOrPageTitle` computed 계산은 [`page-modal-container.md`](./page-modal-container.md)의 레시피와 동일하다. 본 레시피의 완성 예제도 그 패턴을 그대로 사용한다.
-
-상세 폼 특화 사항:
-
-- **모달 우측 상단 액션**: `SdModalProvider`는 모달 컨텐츠 컴포넌트 생성 시에만 setter 프록시를 설치한다(`sd-modal.provider.ts:141` `if ("actionTplRef" in contentRef.instance)`). 모달 뷰에서는 `this.actionTplRef = ...` 할당이 프록시를 통해 `SdModal.actionTplRef` input으로 자동 전달되어 헤더에 렌더된다. page/control 뷰에서는 프록시가 설치되지 않으므로 할당이 인스턴스 필드에만 저장되고 부작용이 없다(`<ng-template #modalActionTpl>` 선언 자체는 뷰 타입과 무관하게 `viewChild`로 `TemplateRef` 인스턴스를 반환하지만, 그 TemplateRef를 소비할 SdModal이 없으므로 결과적으로 아무 일도 일어나지 않는다).
-- **모달 하단 확인/삭제 바**: 모달 뷰 분기 내부의 `<div class="p-sm-default flex-row gap-sm bdt bdt-theme-gray-lightest">` 블록으로 직접 구성. `[size]="'sm'"`로 버튼 크기를 모달에 맞춤.
-- **control 뷰 상단 바**: 페이지 뷰의 topbar가 없고 모달 뷰의 하단 바가 없는 대신, 상단에 `저장`/`새로고침`/`삭제` 버튼을 가로로 배치한 `<div class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">` 블록을 사용.
-
-## 8. 주의사항 (자주 하는 실수)
-
-### 공통 유틸 재도입 금지
-
-- `useDataDetail()`, `useCrudDetail()`, `setupDataDetail()` 같은 공통 헬퍼를 도입하지 말 것. 이 레시피가 제거한 추상화를 다시 만드는 행위다. 세 화면이 비슷해 보여도 화면마다 필드·동작 시그니처가 조금씩 다르므로 복사·수정이 낫다.
-
-### `_sdSharedData.wait()` 선택적 호출
-
-- 과거 `SdDataDetailBase`는 `_refresh()` 직전에 `await this._sdSharedData.wait()`를 호출했다. **공유 데이터를 화면에서 실제로 사용하지 않는다면 이 호출은 불필요**. 사용한다면 `_refresh()` 맨 앞에 `await inject(SdSharedDataProvider).wait();`를 삽입한다.
-
-### 커스텀 close 결과 (`R` 제네릭)
-
-- 모달이 boolean 대신 사용자 정의 결과를 돌려주어야 할 때, `close = output<FooResult | undefined>()` + `implements SdModalContentDef<FooResult | undefined>`로 선언한다. 호출 측은 `const result: FooResult | undefined = await sdModal.showAsync({ type: CustomerDetail, ... })`로 받는다.
-
-### 조용한 저장 (`hideNoChangeMessage` 대응)
+**근거**: Angular `effect`는 콜백 실행 중 읽힌 모든 signal을 의존성으로 등록한다. 비동기 함수 내부에서 signal을 읽으면 effect가 재실행되어 무한 루프가 발생한다.
 
-- 과거 `doSubmit({ hideNoChangeMessage: true })`는 "변경사항이 없습니다" info 토스트를 억제했다. 레시피에서는 `onSubmit()`의 `this._sdToast.info("변경사항이 없습니다.")` 호출부를 **조건으로 감싸** 직접 제어한다. 예: `if (!silent) this._sdToast.info("변경사항이 없습니다.");`. 프로그래밍 저장 메서드(`onPrintButtonClick` 등)는 `silent=true`로 호출.
+### `setupCanDeactivate`를 `computed`·`effect`·일반 메서드에서 호출한다
 
-### `effect` 내부 `untracked`
-
-- `effect(() => { this.itemId(); ... })` 안에서 비동기 `_refresh()`를 호출할 때 반드시 `untracked(() => void this._initRefresh())`로 감싼다. 그렇지 않으면 `_refresh` 내부의 signal 읽기가 effect 의존성으로 등록되어 무한 루프가 발생한다.
-
-### `setupCanDeactivate`는 생성자에서만
-
-- `setupCanDeactivate`는 `inject()`를 사용하므로 **생성자(또는 필드 이니셜라이저)**에서만 호출해야 한다. `computed`/`effect` 콜백 또는 일반 메서드에서 호출하면 `NG0203` 런타임 에러가 발생한다.
-
-### `injectViewTypeSignal()` 호출 시점
-
-- 동일하게 `injectViewTypeSignal()`도 생성자 또는 필드 이니셜라이저에서만 호출한다.
-
-### snapshot은 `obj.clone`로 깊은 복제
-
-- `this._snapshot = this.data()` 같은 얕은 참조 대입은 `data().field = "x"` mutation을 snapshot까지 오염시켜 변경 감지가 실패한다. 반드시 `obj.clone(data)`로 깊은 복제.
-
-## 9. 레시피 작성 관용 규칙
-
-향후 데이터 관련 레시피(CRUD 리스트·상세·선택 버튼 등) 전반에서 아래 규칙을 공통으로 따른다.
-
-### 규칙 1: 시트 셀 내부 컨트롤은 `[inset]="true" [size]="'sm'"` 명시
-
-- `<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이 빠뜨리기 쉽다.
-
-### 규칙 2: `mark(sig)`는 "저장 감지"가 아니라 "UI 동기화"
-
-- `mark(sig)`는 `WritableSignal`의 값을 shallow copy하여 **참조를 갱신**한다 (배열: `[...v]`, 객체: `{...v}`).
-- 역할: **OnPush 템플릿 재렌더링** + **다른 computed / effect의 의존성 갱신**.
-- **"저장 감지"가 아니다.** `obj.equal`(`packages/core-common/src/utils/obj.ts:172`)이 deep equal로 snapshot과 값 차이를 감지하므로, `data().field = value` 같은 mutation은 `mark` 없이도 `_checkIgnoreChanges()` / `onSubmit()`의 snapshot 비교에서 감지된다.
-- Chrome 61 호환성(Proxy 폴리필 불가)으로 signal 자동 notify가 불가하여 명시적 호출이 필요.
-- ❌ "mark 없으면 저장이 안 된다" 식 서술 금지.
-
-### 규칙 3: `setupCanDeactivate`는 뷰 타입에 따라 분기
+```typescript
+// ❌ NG0203 — inject()는 injection context에서만 호출 가능
+protected readonly canEdit = computed(() => {
+  setupCanDeactivate(() => !this._dirty()); // 런타임 에러
+  return true;
+});
 
-- 모달 뷰에서는 `SdActivatedModalProvider.canDeactivateFn`에 등록되고, 페이지 뷰에서는 라우트 guard로 등록된다. control 뷰에서는 아무 동작 하지 않는다 (`sd-data-detail.base.ts:99` + `setupCanDeactivate.ts:5`).
-- 레시피는 항상 `setupCanDeactivate(() => this.viewType() === "modal" || this._checkIgnoreChanges())` 형태로 호출한다. 모달에서는 `true`를 돌려 항상 이탈 허용하고(모달 자체 취소 버튼으로 제어), 페이지에서는 `_checkIgnoreChanges()`의 confirm 결과로 제어.
+// ✅ 생성자(또는 필드 이니셜라이저)에서만 호출
+constructor() {
+  setupCanDeactivate(() => !this._dirty());
+}
+```
 
----
+**근거**: `setupCanDeactivate`는 내부에서 `inject(Router)` 등을 사용하므로 injection context가 필수다. computed/effect 콜백이나 일반 메서드 호출 시점엔 context가 없다.
 
-## Cross-reference
+## 관련 Entry
 
-- CRUD 리스트(시트) 화면 — `<sd-sheet>` 직접 조립 레시피. → [`crud-list.md`](./crud-list.md)
-- 페이지/모달 컨테이너 분기 — → [`page-modal-container.md`](./page-modal-container.md)
-- `SdModalContentDef<R>` — 모달 컨텐츠 인터페이스. → [`../provider-types.md`](../provider-types.md)
-- `SdModalProvider.showAsync()` — 프로그래밍 방식 모달 호출. → [`../providers.md`](../providers.md)
-- `getOrmDataEditToastErrorMessage` — 저장 에러 메시지 변환. `SdToastProvider.try(fn, getOrmDataEditToastErrorMessage)` 패턴으로 사용.
+- [`crud-list.md`](./crud-list.md) — 시트 기반 CRUD 리스트. 차이: 단일 레코드 vs 컬렉션
+- [`page-modal-container.md`](./page-modal-container.md) — page/modal 뷰 분기만 필요한 단순 컨테이너. 차이: CRUD 라이프사이클 없음
+- [`data-select-button.md`](./data-select-button.md) — 데이터 선택 버튼. 차이: 모달 내부 선택 UI
+- [`_common-rules.md`](./_common-rules.md) — 레시피 공통 규칙 (✅ Always / ⚠️ Ask first / 🚫 Never)
+- [`SdModalContentDef`](../provider-types/sd-modal-content-def.md) — 확장 C(modal 뷰)에서 구현하는 계약
+- [`SdModalProvider.showAsync`](../providers/sd-modal-provider.md) — 프로그래밍 방식 모달 호출