@simplysm/angular 14.0.48 → 14.0.51

package/docs/recipes/crud-detail/extension-d-control-view.md

@@ -0,0 +1,103 @@
+← [CRUD 상세폼 레시피 진입점](../crud-detail.md)
+
+# 확장 D: control 뷰
+
+> **선행:** [확장 A: 편집/저장](./extension-a-edit-save.md) + [확장 B: 삭제/복구 토글](./extension-b-delete-restore.md)
+
+확장 A(편집/저장) + 확장 B(삭제/복구)를 전제로, 동일 컴포넌트를 **control 뷰**(마스터-디테일의 디테일 영역)로도 재사용한다. 마스터 화면이 `<app-customer-detail [itemId]="selectedId()" class="flex-fill">`처럼 컴포넌트 selector를 직접 삽입하면 `viewType() === "control"`로 자동 판정되어, 상단 바에 저장·새로고침·삭제·복구 버튼이 가로로 배치된다. page 뷰의 topbar가 없고 modal 뷰의 하단 바가 없는 대신, main 영역 위에 `<sd-dock>` 상단 바가 놓인다.
+
+**이 확장이 도입하는 요소:**
+
+- **imports:** [확장 C](./extension-c-modal-view.md)에서 이미 도입된 `injectViewTypeSignal`, `SdDockContainer`, `SdDock`, `tablerDeviceFloppy`, `tablerRefresh`, `tablerEraser`, `tablerRestore`를 재사용. 확장 D를 확장 C 없이 단독 적용하는 경우 동일 imports를 신규 도입
+- **파생:** `viewType = injectViewTypeSignal()` (확장 C 없이 단독 적용 시 신규 도입)
+- **템플릿 추가:** [확장 C](./extension-c-modal-view.md)가 도입한 `<sd-dock-container>` 내부에 `@if (viewType() === "control" && canEdit())` 블록으로 `<sd-dock>` 상단 바(저장·새로고침·삭제·복구) 추가 — 확장 C의 modal 하단 바 블록과 나란히 배치
+
+> 상세: [`injectViewTypeSignal`](../../utils/inject-routing-signals.md#injectviewtypesignal)
+
+> 상세: [`<sd-dock> position 기본 "top"`](../../ui-layout/sd-dock.md)
+
+> **아래 코드 블록은 diff 조각이다.** 독립 실행 가능한 완성 클래스가 아니며, 선행 확장(A+B) 위에 번호 순서대로 삽입할 지점을 나타낸다. 그대로 컴파일되지 않는다.
+
+```typescript
+// 1) imports 추가 (확장 D를 확장 C 없이 단독 적용하는 경우)
+import { injectViewTypeSignal, SdDock, SdDockContainer } from "@simplysm/angular";
+
+// 2) 파생 추가 (확장 C 없이 단독 적용 시)
+protected readonly viewType = injectViewTypeSignal();
+
+// 3) template — <sd-dock-container> 내부(확장 C 블록과 나란히)에 control 뷰 상단 바 추가
+template: `
+  <sd-dock-container>
+    <!-- control 뷰 상단 바: 저장·새로고침·삭제·복구 -->
+    @if (viewType() === "control" && canEdit()) {
+      <sd-dock class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">
+        <sd-button [theme]="'primary'" (click)="onSaveButtonClick()">
+          <ng-icon [svg]="tablerDeviceFloppy" /> 저장 <small>(CTRL+S)</small>
+        </sd-button>
+        <sd-button [theme]="'info'" (click)="onRefreshButtonClick()">
+          <ng-icon [svg]="tablerRefresh" /> 새로고침 <small>(CTRL+ALT+L)</small>
+        </sd-button>
+        @if (!isNew() && canEdit()) {
+          @if (data().isDeleted) {
+            <sd-button [theme]="'warning'" (click)="onRestoreButtonClick()">
+              <ng-icon [svg]="tablerRestore" /> 복구
+            </sd-button>
+          } @else {
+            <sd-button [theme]="'danger'" (click)="onDeleteButtonClick()">
+              <ng-icon [svg]="tablerEraser" /> 삭제
+            </sd-button>
+          }
+        }
+      </sd-dock>
+    }
+
+    @if (viewType() === "modal" && canEdit()) {
+      <!-- modal 하단 바 (확장 C) -->
+    }
+
+    <!-- main: form + 최종수정 (확장 A/B 동일) -->
+  </sd-dock-container>
+`
+```
+
+**포인트:**
+
+- **control 뷰 = 마스터-디테일의 디테일 영역**. 마스터 화면이 `<app-customer-detail [itemId]="selectedId()" class="flex-fill">`처럼 직접 삽입하여 좌측 리스트 선택에 따라 우측에 상세 폼을 표시한다. `injectViewTypeSignal()`은 `ActivatedRoute.component`의 selector와 호스트 `tagName`이 **다를 때** control로 판정한다(page는 일치, modal은 `SdActivatedModalProvider` 주입 시 우선).
+- **상단 바는 `[position]` 생략** — `<sd-dock>`의 `[position]` 기본값이 `"top"`이므로 명시하지 않는다. modal 하단 바와 달리 기본 동작을 그대로 쓴다.
+- **[확장 C](./extension-c-modal-view.md)(modal 뷰)와 병행 가능** — 두 분기 블록(`@if (viewType() === "control")` / `@if (viewType() === "modal")`)이 상호 배타이므로 같은 `<sd-dock-container>` 내부에 나란히 둬도 안전하다. [변형 확장 A~F 인덱스](../crud-detail.md#변형-확장-a-f-인덱스)가 이 조합을 수용한다.
+- **control 뷰에서는 `setupCanDeactivate`가 아무 동작 하지 않는다** — 라우트 guard도 모달 canDeactivateFn도 연결되지 않는다(`packages/angular/src/core/routing/setupCanDeactivate.ts:10-26`). 마스터 화면이 이동할 때의 이탈 확인은 마스터 화면이 자체적으로 처리한다.
+
+## 🚫 흔한 실수 (Anti-patterns)
+
+> 공통 규칙(topbar 소유권, `mark` 오용, `setupCanDeactivate` 호출 위치 등)은 [레시피 공통 규칙](../_common-rules.md)을 참조한다. 이 섹션은 **control 뷰 확장 고유 실수**만 다룬다.
+
+### control 뷰 분기에 자체 `<sd-topbar>`를 추가한다
+
+```typescript
+// ❌ control 분기용으로 별도 <sd-topbar> 추가 — 마스터 화면이 이 컴포넌트를
+//    <app-customer-detail />로 포함할 때, 마스터 화면이 이미 소유한
+//    <sd-topbar-container> + <sd-topbar>와 중첩되어 레이아웃이 깨진다.
+@if (viewType() === "control" && canEdit()) {
+  <sd-topbar>
+    <h4>{{ viewTitle() }}</h4>
+    <sd-button [theme]="'link-primary'" (click)="onSaveButtonClick()"> 저장 </sd-button>
+    <!-- ... -->
+  </sd-topbar>
+}
+
+// ✅ control 분기에는 <sd-dock> 상단 바만 둔다. page가 소유한 topbar와
+//    중첩되지 않으며, 저장/새로고침/삭제/복구 버튼을 가로로 배치한다.
+@if (viewType() === "control" && canEdit()) {
+  <sd-dock class="p-default flex-row gap-default bdb bdb-theme-gray-lightest">
+    <sd-button [theme]="'primary'" (click)="onSaveButtonClick()">
+      <ng-icon [svg]="tablerDeviceFloppy" /> 저장 <small>(CTRL+S)</small>
+    </sd-button>
+    <sd-button [theme]="'info'" (click)="onRefreshButtonClick()">
+      <ng-icon [svg]="tablerRefresh" /> 새로고침 <small>(CTRL+ALT+L)</small>
+    </sd-button>
+    <!-- 삭제/복구는 @if (!isNew() && canEdit()) 블록으로 (확장 B 조건 재사용) -->
+  </sd-dock>
+}
+```
+
+**근거**: control 뷰는 마스터 화면이 `<app-customer-detail [itemId]="..." />`처럼 디테일 영역으로 직접 삽입하는 구조다. 마스터 화면은 이미 `<sd-topbar-container>`와 `<sd-topbar>`를 소유하므로, 내부 컴포넌트가 동일 구조를 중첩하면 타이틀·액션 영역이 이중으로 렌더링되어 레이아웃이 깨진다. control 분기의 상단 액션 영역은 `<sd-dock-container>` 내부 `<sd-dock>`으로 구성한다. → [공통 규칙: page 컴포넌트가 `<sd-topbar-container>`와 `<sd-topbar>`를 소유한다](../_common-rules.md#page-컴포넌트가-sd-topbar-container와-sd-topbar를-소유한다)

package/docs/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/docs/recipes/crud-detail/extension-f-complex-detail.md

@@ -0,0 +1,234 @@
+← [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)을 참조한다. 이 섹션은 **복합 상세(하위 컬렉션) 확장 고유 실수**만 다룬다.
+
+### `data().boxes`에서 기존 row를 물리 제거한다
+
+```typescript
+// ❌ 기존 row를 하위 컬렉션 배열에서 제거 — oneWayDiffs는 delete를 반환하지 않으므로
+//    저장 시 서버는 이 row가 사라진 사실을 감지하지 못한다.
+onRemoveBox(box: ICustomerBox): void {
+  this.data.update((d) => ({
+    ...d,
+    boxes: d.boxes.filter((b) => b.id !== box.id),
+  }));
+}
+
+// ✅ 삭제 의사는 isDeleted 플래그로 표현 → diff의 type: "update"로 전송
+onToggleDeleteBoxButtonClick(box: ICustomerBox): void {
+  box.isDeleted = !box.isDeleted;
+  mark(this.data);  // OnPush 재렌더링 통지
+}
+
+// ✅ 예외: 신규 row(snapshot에 없는 클라이언트 UUID)는 저장 포기 시 물리 제거해도 된다
+//    — snapshot에 존재하지 않으므로 diff 자체가 발생하지 않는다.
+onCancelNewBox(box: ICustomerBox): void {
+  this.data.update((d) => ({
+    ...d,
+    boxes: d.boxes.filter((b) => b.id !== box.id),
+  }));
+}
+```
+
+**근거**: `oneWayDiffs`의 반환 `type`은 `"create" | "update" | "same"` 3종뿐이며 delete를 다루지 않는다(`packages/core-common/src/extensions/arr-ext.types.ts:206`). 기존 row를 화면에서 제거하면 diff가 발생하지 않아 서버 저장 경로를 우회한다. 하위 컬렉션 삭제는 상위 테이블의 soft-delete 여부와 무관하게 항상 `isDeleted` 플래그를 쓴다 — [공통 규칙: 삭제 방식](../_common-rules.md#삭제-방식은-db-스키마에-따라-결정한다)은 상위 테이블 단위 결정이며, 하위 컬렉션은 `oneWayDiffs` delete 미지원이라는 기술적 제약이 원인이다.