@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/angular/recipes/crud-detail/extension-e-auxiliary.md

@@ -0,0 +1,87 @@
+← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
+
+# 확장 E: 보조 기능 영역
+
+> **선행:** [확장 A: 편집/저장](./extension-a-edit-save.md)
+
+확장 A(편집/저장)를 전제로, 메인 폼의 submit과 **별개인 보조 기능**(예: 다른 사용자로부터 권한 복사, 출력, 엑셀 다운로드 등)을 추가한다. 과거 `#toolTpl` 슬롯이 담당하던 역할을 소비 화면에 직접 인라인한다. 보조 영역은 control 뷰 상단 `<sd-dock>` 내부 / modal 뷰 하단 바 옆 / main 영역 내 별도 `<sd-form>` 중 하나에 배치한다. 뷰별 UI 배치 본문은 [확장 C](./extension-c-modal-view.md) / [확장 D](./extension-d-control-view.md)에서 처리한다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `SdSharedDataSelect` (`@simplysm/angular`), 앱 공용 `useSharedSignal` (예: `@adtek/client-common` — `SdSharedDataProvider` 위에 각 앱이 정의하는 공용 훅)
+- **상태:** 예시 — `permCopySourceId = signal<number | undefined>(undefined)`, `sharedUsers = useSharedSignal("사용자")`
+- **메서드:** 예시 — `onImportFormSubmit` (권한·busy 가드 + 메인 폼 변경 보호 호출 + 앱별 ORM 조회·병합)
+- **템플릿 추가:** 보조 `<sd-form (formSubmit)="onImportFormSubmit()">` 블록을 배치(아래 예시는 control 뷰 `<sd-dock>` 내부). 메인 `<sd-form #formCtrl>`과 **별도** 인스턴스
+- **공유 데이터 대기:** 본 확장이 `useSharedSignal`을 도입하므로 `_refresh()` 선두에 `await this._sdSharedData.wait();`가 필요해진다 → [공통 규칙: `_sdSharedData.wait()`](../_common-rules.md#공유-데이터-사용-화면은-_refresh-선두에서-_sdshareddatawait를-호출한다)
+
+> 상세: [`<sd-shared-data-select>`](../../ui-form/sd-shared-data-select.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A) 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가
+import { SdSharedDataSelect } from "@simplysm/angular";
+// 앱 공용 훅 — @simplysm/angular 소유 아님. 각 앱이 SdSharedDataProvider 위에 정의.
+import { useSharedSignal } from "@adtek/client-common";
+
+// 2) 클래스에 상태 추가
+protected readonly permCopySourceId = signal<number | undefined>(undefined);
+protected readonly sharedUsers = useSharedSignal("사용자");
+
+// 3) template — 보조 form 블록을 배치한다. 아래는 control 뷰 <sd-dock>(상단 바) 내부 예시.
+//    modal 뷰는 하단 바(<sd-dock [position]="'bottom'">) 옆, main 영역은 메인 form 옆이나 아래에 배치할 수 있다.
+@if (viewType() === "control" && canEdit()) {
+  <sd-dock class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">
+    <!-- 기본 저장/삭제 버튼 (확장 D) -->
+    <!-- ... -->
+
+    <!-- 보조 기능: 다른 사용자로부터 가져오기 -->
+    <sd-form (formSubmit)="onImportFormSubmit()">
+      <div class="form-box-inline">
+        <div class="form-box-item">
+          <label>가져오기</label>
+          <sd-shared-data-select
+            [items]="sharedUsers.items()"
+            [(value)]="permCopySourceId"
+            [inset]="true"
+            [size]="'sm'"
+          />
+        </div>
+        <div class="form-box-item">
+          <sd-button [type]="'submit'" [disabled]="permCopySourceId() == null">
+            가져오기
+          </sd-button>
+        </div>
+      </div>
+    </sd-form>
+  </sd-dock>
+}
+
+// 4) 메서드 추가
+protected async onImportFormSubmit(): Promise<void> {
+  if (this.busyCount() > 0 || !this.perms().includes("edit")) return;
+  if (this.permCopySourceId() == null) return;
+  // 메인 폼의 미저장 변경사항 보호 — 확장 A가 제공하는 _checkIgnoreChanges() 재호출
+  if (!this._checkIgnoreChanges()) return;
+
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    // 앱별 서버 호출로 다른 사용자의 데이터를 조회·병합 — 예:
+    //   const src = await this._appOrm.connectAsync(async (db) =>
+    //     (await db.customer.where((it) => [expr.eq(it.id, this.permCopySourceId())]).single())!
+    //   );
+    //   this.data.set({ ...this.data(), ...src });
+  });
+  this.busyCount.update((v) => v - 1);
+}
+```
+
+**포인트:**
+
+- **보조 `<sd-form>`은 메인 `<sd-form #formCtrl>`과 별도 인스턴스**다. `SdCommandDirective.sdSaveCommand` → `formCtrl()?.requestSubmit()` 경로는 메인 form 한 곳에만 연결된다(확장 A). 보조 form의 submit 버튼은 Ctrl+S와 연동되지 않고 버튼 클릭(또는 submit 버튼에서 Enter 제출)만 발동한다. 보조 form에는 `#formCtrl` template 변수를 부여하지 않는다.
+- **보조 작업 전에도 `_checkIgnoreChanges()`를 호출**하여 메인 폼의 미저장 변경사항을 보호한다. 보조 form이 메인 `data()`를 덮어쓰는 경우(권한 복사 등) 필수. `_checkIgnoreChanges`는 확장 A가 제공하므로 재정의하지 않는다.
+- **공유 데이터 도입으로 `_refresh()` 선두에 `await this._sdSharedData.wait();`가 필요해진다.** 판정 기준·코드 예시는 [공통 규칙: `_sdSharedData.wait()`](../_common-rules.md#공유-데이터-사용-화면은-_refresh-선두에서-_sdshareddatawait를-호출한다) 참조.
+- **`<sd-shared-data-select>`에 `[inset]="true" [size]="'sm'"`을 명시**한다. `<sd-dock>` 도구 바 내부 치수와 `form-box-inline` 간격이 sm 기준으로 정합하므로 인셋·사이즈를 생략하면 컨트롤 높이가 들쭉날쭉해진다.
+- **배치 위치 선택:** control 뷰는 상단 `<sd-dock>` 안, modal 뷰는 하단 바(`<sd-dock [position]="'bottom'">`) 옆, main 영역에서는 메인 form과 나란한 별도 블록. 뷰 분기 본문 UI는 [확장 C](./extension-c-modal-view.md) / [확장 D](./extension-d-control-view.md)에서 정의한다.
+- **읽기 전용 보조(출력·엑셀 다운로드 등)는 `<sd-form>` 래핑 없이 버튼 `(click)`으로 직접 처리 가능**하다. 입력 값을 수집하지 않는 단일 액션은 form submit 절차가 불필요하다. 이 경우 `_checkIgnoreChanges()` 호출도 상황에 맞게 판단한다(읽기 전용이라 메인 변경 보호가 불필요할 수 있음).
+- **`useSharedSignal`은 `@simplysm/angular` 제공이 아님** — `SdSharedDataProvider`(`packages/angular/src/core/shared-data/sd-shared-data.provider.ts`) 위에서 각 앱이 정의하는 공용 훅이다. 배포 패키지 소속이 다르므로 import 경로 혼동에 주의한다.

package/claude/references/sd-simplysm-v14/angular/recipes/crud-detail/extension-f-complex-detail.md

@@ -0,0 +1,202 @@
+← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
+
+# 확장 F: 복합 상세 (내부 `<sd-sheet>`)
+
+> **선행:** [확장 A: 편집/저장](./extension-a-edit-save.md)
+
+확장 A(편집/저장)를 전제로, 상세 폼 안에 **하위 컬렉션**(박스 목록, 품목 라인 등)을 편집하는 구조를 도입한다. `<sd-form>` 본문 내부에 `<sd-sheet>`를 중첩하고, 하위 컬렉션의 행 추가·수정·삭제는 `item.isDeleted = true` 플래그로 표현하여 `oneWayDiffs` 기반 일괄 저장에 포함시킨다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** `SdSheet`, `SdSheetColumn`, `SdSheetColumnCellTemplate`, `SdAnchor`(하위 행 삭제/복구 아이콘 호스트), `Uuid`, `oneWayDiffs`(side-effect import), 아이콘 `tablerCirclePlus` / `tablerEraser` / `tablerRestore` (`mark`는 확장 A에서 이미 도입)
+- **데이터 타입 확장:** `ICustomer.boxes: ICustomerBox[]` + `interface ICustomerBox { id: string; seq: number; note: string; isDeleted: boolean; }`
+- **data 초기값:** `boxes: []` 필드 추가
+- **시트 함수 (클래스 필드):** `boxTrackByFn`, `getBoxCellStyleFn`
+- **메서드:** `onAddBoxButtonClick`, `onToggleDeleteBoxButtonClick`
+- **템플릿:** main 영역 `<sd-form>` 내부를 [상단 단일 필드 블록 + 하위 컬렉션 도구 dock(`<sd-button>` "박스 추가") + 하위 `<sd-sheet>` 중첩] 구조로 교체
+- **onSubmit 변경:** `_sdToast.try(...)` 블록 내부를 diff 계산(`data().boxes.oneWayDiffs(_dataSnapshot?.boxes, "id")`) + 일괄 제출로 교체
+
+> 상세: [`<sd-sheet>`](../../ui-data/sd-sheet.md) · [`<sd-sheet-column>`](../../ui-data/sd-sheet.md#sdsheetcolumn) · [`[cell]`](../../ui-data/sd-sheet.md#sdsheetcolumncelltemplate) · [`<sd-anchor>`](../../ui-form/sd-anchor.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A) 위에 번호 순서대로 삽입·교체할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가 — @simplysm/angular에 {SdSheet, SdSheetColumn, SdSheetColumnCellTemplate, SdAnchor} 추가.
+//    @simplysm/core-common에서 {Uuid} 추가 + 프로토타입 확장 활성화용 side-effect import.
+//    아이콘에 tablerCirclePlus / tablerEraser / tablerRestore 추가. (mark는 확장 A에서 이미 import됨)
+import { SdSheet, SdSheetColumn, SdSheetColumnCellTemplate, SdAnchor } from "@simplysm/angular";
+import { Uuid } from "@simplysm/core-common";
+import { tablerCirclePlus, tablerEraser, tablerRestore } from "@ng-icons/tabler-icons";
+import "@simplysm/core-common";  // Array.prototype.oneWayDiffs 활성화 (side-effect import)
+
+// 2) 데이터 타입 확장 — 진입점 3.1 최소 뼈대의 ICustomer에 boxes 필드만 추가, ICustomerBox 신설
+//    (확장 B를 함께 적용하면 ICustomer.isDeleted 필드가 별도로 들어가며, 본 확장 단독 적용에는 포함되지 않는다)
+interface ICustomer {
+  id: number | undefined;
+  name: string;
+  phone: string;
+  lastModifiedAt: DateTime | undefined;
+  lastModifiedBy: string | undefined;
+  boxes: ICustomerBox[];  // 하위 컬렉션 추가
+}
+
+interface ICustomerBox {
+  id: string;  // 클라이언트 생성 UUID (서버 저장 시 교체 가능)
+  seq: number;
+  note: string;
+  isDeleted: boolean;
+}
+
+// 3) data 초기값에 boxes: [] 추가 — 진입점 3.1 최소 뼈대의 data = signal<ICustomer>({ ... }) 초기값에 포함
+
+// 4) template — main 영역(<sd-dock-container> 안쪽 <sd-form> 내부)을
+//    [단일 필드 + 도구 dock + 시트]로 교체. 최종수정 표시 블록은 최소 뼈대와 동일.
+<div class="flex-column fill">
+  <sd-form #formCtrl (formSubmit)="onSubmit()" class="flex-fill flex-column">
+    <!-- 상단 단일 필드 -->
+    <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]="tablerCirclePlus" />
+          박스 추가
+        </sd-button>
+      </div>
+    }
+
+    <!-- 하위 컬렉션 시트 -->
+    <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]="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 ? tablerRestore : 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>
+
+// 5) 시트 함수 (클래스 필드) 추가
+protected readonly boxTrackByFn = (item: ICustomerBox): string => item.id;
+
+protected readonly getBoxCellStyleFn = (item: ICustomerBox): string | undefined =>
+  item.isDeleted ? "text-decoration: line-through;" : undefined;
+
+// 6) 메서드 추가
+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);
+}
+
+protected onToggleDeleteBoxButtonClick(item: ICustomerBox): void {
+  item.isDeleted = !item.isDeleted;
+  mark(this.data);
+}
+
+// 7) onSubmit의 _sdToast.try(...) 블록 내부 교체 — diff 계산 + 일괄 제출
+await this._sdToast.try(async () => {
+  // 삭제 플래그가 섞여 있으면 사용자 확인
+  if (this.data().boxes.some((b) => b.isDeleted)) {
+    if (!confirm("삭제 표시된 박스가 있습니다. 정말 저장하시겠습니까?")) return;
+  }
+
+  // 하위 컬렉션 diff 계산 — 반환 type은 "create" | "update" | "same" 3종
+  const snapshotBoxes = this._dataSnapshot?.boxes ?? [];
+  const boxDiffs = this.data().boxes.oneWayDiffs(snapshotBoxes, "id");
+
+  // 앱별 ORM 호출:
+  //   await this._appOrm.connectAsync(async (db) => {
+  //     await db.customer().where((c) => [expr.eq(c.id, this.data().id)])
+  //       .upsert(() => ({ name: this.data().name, phone: this.data().phone }));
+  //     for (const d of boxDiffs) {
+  //       if (d.type === "create") {
+  //         await db.customerBox().insert({ ...d.item, customerId: this.data().id! });
+  //       } else if (d.type === "update") {
+  //         await db.customerBox().where((c) => [expr.eq(c.id, d.item.id)])
+  //           .update(() => d.item);
+  //       }
+  //     }
+  //   });
+
+  this._sdToast.success("저장되었습니다.");
+  // 확장 C(modal 뷰)가 함께 적용된 경우에만 존재: this.close.emit(true); — modal 호출 측에 결과 전달
+  await this._refresh();
+});
+```
+
+**포인트:**
+
+- **하위 컬렉션의 삭제는 `isDeleted: true` 플래그로 표현한다.** 이것은 상위 테이블의 삭제 방식([공통 규칙: 삭제 방식](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다))과 **무관**하게, `oneWayDiffs`가 `"delete"` 타입을 지원하지 않기 때문에 하위 컬렉션에서는 항상 이 방식을 사용한다. 반환 `type`은 `"create" | "update" | "same"` 3종뿐이다(`packages/core-common/src/extensions/arr-ext.types.ts:206`). 서버는 `isDeleted: true` row를 soft-delete 또는 물리 삭제로 처리한다.
+- **시트 셀 내부 컨트롤은 `[inset]="true" [size]="'sm'"` 명시 필수** — [공통 규칙: 시트 셀 `[inset]/[size]`](../_common-rules.md#시트-셀-내부-컨트롤에-insettrue-sizesm을-명시한다).
+- **`data().boxes.push(newBox)` 같은 배열 mutation 후에는 `mark(this.data)`로 signal 참조를 갱신한다** — OnPush 템플릿 재렌더링·연계 computed 갱신 용도의 **통지**이며, 값 비교(저장 감지)와는 별개다: [공통 규칙: `mark(sig)`…](../_common-rules.md#marksig를-저장-감지-수단으로-사용하지-않는다).
+- **`id`는 클라이언트에서 UUID로 생성** — `Uuid.generate().toString()`으로 문자열 key를 만들어 `trackByFn` + `oneWayDiffs`의 key로 사용한다. 서버가 발급한 PK가 별도로 있다면 별도 컬럼으로 관리하고 클라이언트 UUID는 row 식별자로만 쓴다.
+- **삭제 플래그 혼재 시 `confirm`** — `this.data().boxes.some((b) => b.isDeleted)`이면 저장 직전 사용자 확인을 요청한다.
+
+> 공통 규칙(시트 셀 `[inset]/[size]`, `mark` 오용, 상위 테이블 soft-delete 선택 기준)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다.

package/claude/references/sd-simplysm-v14/angular/recipes/crud-detail.md

@@ -0,0 +1,280 @@
+# Recipe: CRUD 상세폼 화면 직접 조립
+
+단일 레코드 CRUD 상세폼을, `<sd-busy-container>` · `<sd-topbar-container>` · `<sd-topbar>` · `<sd-form>` 표준 컴포넌트를 소비 화면이 **직접 조립**하여 구성한다. 과거 `SdDataDetail` / `SdDataDetailBase`가 감추고 있던 load·save·delete 라이프사이클, snapshot 기반 변경 감지, 이탈 방지, busy 카운트, Ctrl+S 단축키를 화면 내부에 인라인으로 풀어쓴다.
+
+## 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` 전제)
+- 횡단 규칙: [`_common-rules.md`](./_common-rules.md)에 정의된 공통 규칙을 모두 준수한다
+  - [화면 레이아웃 구간과 버튼 스타일 구분](./_common-rules.md#화면-레이아웃-구간과-버튼-스타일을-구분한다)
+  - [page 컴포넌트가 `<sd-topbar>`를 소유](./_common-rules.md#page-컴포넌트가-sd-topbar-container와-sd-topbar를-소유한다)
+
+## 기본 레시피 (page 뷰, 읽기 전용)
+
+라우트 진입 시 `itemId`를 받아 단일 레코드를 로드하고 읽기 전용 필드로 표시하는 최소 완성 컴포넌트다. 편집·삭제·modal·control·보조·복합이 필요하면 [변형](#변형-확장-a-f-인덱스)의 확장을 선택적으로 얹는다.
+
+```typescript
+import {
+  ChangeDetectionStrategy,
+  Component,
+  effect,
+  inject,
+  input,
+  signal,
+  untracked,
+  ViewEncapsulation,
+} from "@angular/core";
+import type { DateTime } from "@simplysm/core-common";
+import {
+  FormatPipe,
+  injectPermsSignal,
+  injectViewTitleSignal,
+  SdBusyContainer,
+  SdButton,
+  SdForm,
+  SdTextfield,
+  SdToastProvider,
+  SdTopbar,
+  SdTopbarContainer,
+} from "@simplysm/angular";
+// 앱별 대체: ORM provider + DbContext. @simplysm/angular가 아니라 각 앱이 소유한다.
+import { AppOrmProvider } from "@adtek/client-common";
+
+interface ICustomer {
+  id: number | undefined;           // undefined면 신규 — 확장 A 편집/저장 시 활용
+  name: string;
+  phone: string;
+  lastModifiedAt: DateTime | undefined;
+  lastModifiedBy: string | undefined;
+}
+
+@Component({
+  selector: "app-customer-detail",
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  standalone: true,
+  imports: [
+    SdBusyContainer, SdTopbarContainer, SdTopbar,
+    SdForm, SdButton, SdTextfield,
+    FormatPipe,
+  ],
+  template: `
+    <sd-busy-container [busy]="busyCount() > 0">
+      @if (initialized()) {
+        <sd-topbar-container>
+            <sd-topbar>
+              <h4>{{ viewTitle() }}</h4>
+            </sd-topbar>
+
+            <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>
+              </sd-form>
+
+              @if (data().lastModifiedAt || data().lastModifiedBy) {
+                <div class="p-sm-default">
+                  최종수정:
+                  @if (data().lastModifiedAt) {
+                    {{ data().lastModifiedAt | format: "yyyy-MM-dd HH:mm" }}
+                  }
+                  @if (data().lastModifiedBy) {
+                    ({{ data().lastModifiedBy }})
+                  }
+                </div>
+              }
+            </div>
+          </sd-topbar-container>
+      }
+    </sd-busy-container>
+  `,
+})
+export class CustomerDetail {
+  //== DI ==
+  private readonly _appOrm = inject(AppOrmProvider);
+  private readonly _sdToast = inject(SdToastProvider);
+
+  //== input ==
+  itemId = input<number>();
+
+  //== 타이틀 / 권한 ==
+  protected readonly viewTitle = injectViewTitleSignal();
+  perms = injectPermsSignal(["sales.customer"], ["use"]);
+
+  //== 상태 ==
+  protected readonly busyCount = signal(0);
+  protected readonly initialized = signal(false);
+  protected readonly data = signal<ICustomer>({
+    id: undefined,
+    name: "",
+    phone: "",
+    lastModifiedAt: undefined,
+    lastModifiedBy: undefined,
+  });
+
+  //== 라이프사이클 ==
+  constructor() {
+    // 최초 진입 + itemId 변경 시 재조회.
+    effect(() => {
+      this.itemId(); // 의존성 등록
+      if (!this.perms().includes("use")) {
+        this.initialized.set(true);
+        return;
+      }
+
+      void untracked(async () => {
+        this.busyCount.update((v) => v + 1);
+        await this._sdToast.try(async () => {
+          await this._refresh();
+        });
+        this.busyCount.update((v) => v - 1);
+        this.initialized.set(true);
+      });
+    });
+  }
+
+  //== 내부 메서드 ==
+  private async _refresh(): Promise<void> {
+    let data: ICustomer;
+    if (this.itemId() == null) {
+      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("구현 필요");
+    }
+
+    this.data.set(data);
+  }
+
+}
+```
+
+### 조건부 요소 포함 기준
+
+인프라·라이프사이클 요소는 화면 요건에 따라 포함·생략한다. 필요 없는 요소를 기계적으로 포함하지 않는다.
+
+| 요소 | 포함 조건 | 생략 예시 |
+|------|----------|----------|
+| `<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()` + effect 내 권한 체크 | 권한 제어가 있는 화면. effect에서 `perms().includes("use")` 검사 후 미보유 시 `return` | 권한 제어 없음 |
+| `<sd-busy-container>` + `busyCount` | 비동기 작업(DB 조회 등)이 있어 busy 표시가 필요할 때 | 동기 래퍼·레이아웃 |
+| `initialized` + `@if (initialized())` | 초기 로딩 완료 전 깜박임 방지가 필요할 때 | 빈 상태 렌더가 무방 |
+
+## 변형 (확장 A~F 인덱스)
+
+| 상황 | 시작 지점 + 필요한 확장 |
+|---|---|
+| 단일 레코드 **읽기 전용 상세 폼** (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) |
+
+### 각 확장 요약
+
+- **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)
+
+## 🚫 흔한 실수 (Anti-patterns)
+
+> 공통 규칙(`mark` 오용, `injectViewTypeSignal()` 호출 위치, `_sdSharedData.wait()` 조건, 시트 셀 `[inset]`/`[size]`, soft-delete 선택 기준 등)은 [레시피 공통 규칙](./_common-rules.md)을 참조한다. 이 섹션은 **CRUD 상세폼 진입점 고유 실수**만 다룬다.
+
+### 지원할 뷰를 확인하지 않고 3뷰 분기를 미리 박는다
+
+```typescript
+// ✅ 기본 레시피는 page 전용으로 시작. 필요한 뷰가 생기면 확장을 얹는다
+// modal 뷰가 필요해지는 시점에 확장 C를, control 뷰는 확장 D를 추가.
+@Component({ /* ... */ })
+export class CustomerDetail {
+  itemId = input<number>();
+  // page 전용 — viewType 분기·close output 없음
+}
+```
+
+**근거**: 실제 호출되지 않는 뷰의 계약·분기·슬롯은 죽은 코드로 남아 LLM이 모달 사용처 탐색 시 오판 원인이 된다. 지원할 뷰를 먼저 확정하고 필요한 확장만 얹는다.
+
+### `effect` 내부 비동기 호출을 `untracked`로 감싸지 않는다
+
+```typescript
+// ✅ 비동기 작업은 untracked로 감싸 의존성 등록을 차단한다
+constructor() {
+  effect(() => {
+    this.itemId(); // 여기서만 의존성 등록
+    void untracked(async () => {
+      await this._sdToast.try(() => this._refresh());
+    });
+  });
+}
+```
+
+**근거**: Angular `effect`는 콜백 실행 중 읽힌 모든 signal을 의존성으로 등록한다. 비동기 함수 내부에서 signal을 읽으면 effect가 재실행되어 무한 루프가 발생한다.
+
+### `setupCanDeactivate`를 `computed`·`effect`·일반 메서드에서 호출한다
+
+```typescript
+// ✅ 생성자(또는 필드 이니셜라이저)에서만 호출
+constructor() {
+  setupCanDeactivate(() => !this._dirty());
+}
+```
+
+**근거**: `setupCanDeactivate`는 내부에서 `inject(Router)` 등을 사용하므로 injection context가 필수다. computed/effect 콜백이나 일반 메서드 호출 시점엔 context가 없다.
+
+## 관련 Entry
+
+- [`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) — 프로그래밍 방식 모달 호출