@simplysm/sd-claude 14.0.47 → 14.0.49

package/claude/references/sd-simplysm14/angular/usage.md

@@ -1,489 +0,0 @@
-# @simplysm/angular
-
-Angular 21 기반 UI 컴포넌트 라이브러리. Zoneless, signal-based, standalone 컴포넌트로 구성된다.
-
-> **NOTE:** 이 문서는 `@simplysm/angular` 라이브러리의 사용법만 다룬다. Angular 프레임워크 자체의 사용법(컴포넌트 작성, DI, 라우팅, signal 등)은 `angular-cli` MCP를 활용한다.
-
-## Installation
-
-```bash
-npm install @simplysm/angular
-```
-
-## API Overview
-
-### Bootstrap
-
-| API | Type | Description |
-|-----|------|-------------|
-| `provideSdAngular` | function | 모든 기반 설정을 제공하는 환경 프로바이더 팩토리 |
-| `SdAngularConfigProvider` | class | `clientName` 설정을 보유하는 프로바이더 |
-| `TXT_CHANGE_IGNORE_CONFIRM` | const | 변경사항 무시 확인 메시지 문자열 |
-
--> See [docs/bootstrap.md](./docs/bootstrap.md) for details.
-
-### Providers
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdThemeProvider` | class | 다크모드/폰트 크기 프로바이더 (`dark`, `fontSize` signal) |
-| `SdThemeSelector` | component | 테마 설정 드롭다운 (다크모드 토글, 폰트 크기 조절) |
-| `SdSystemLogProvider` | class | 시스템 로그 기록 프로바이더 |
-| `SdAppStructureProvider` | class | 앱 구조(메뉴/권한) 관리 프로바이더 |
-| `injectPermsSignal` | function | 현재 뷰의 권한 목록을 signal로 반환 |
-| `SdAppStructureUtils` | class | 앱 구조 유틸리티 (메뉴/권한 조회 정적 메서드) |
-| `SdFileDialogProvider` | class | 네이티브 파일 선택 대화상자 프로바이더 |
-| `SdLocalStorageProvider` | class | `clientName` 스코프 localStorage 래퍼 |
-| `SdSystemConfigProvider` | class | 비동기 설정 저장/조회 프로바이더 |
-| `SdServiceClientFactoryProvider` | class | ServiceClient 인스턴스 팩토리/관리 |
-| `SdSharedDataProvider` | class | 이벤트 기반 공유 데이터 캐시 추상 프로바이더 |
-| `SdSharedDataChangeEvent` | const | 공유 데이터 변경 이벤트 정의 |
-| `SdNavigateWindowProvider` | class | 새 윈도우 네비게이션 + 자동 닫기 |
-| `SdActivatedModalProvider` | class | 모달 내부에서 inject하여 모달/컨텐츠 참조 |
-| `SdToastProvider` | class | 토스트 알림 (info/success/warning/danger) |
-| `SdBusyProvider` | class | 글로벌 busy 상태 관리 (spinner/bar/cube) |
-| `SdPrintProvider` | class | 인쇄 및 PDF 생성 프로바이더 |
-| `SdModalProvider` | class | 프로그래밍 방식 모달 생성 |
-
--> See [docs/providers.md](./docs/providers.md) for details.
-
-### Provider Types
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdMenu` | interface | 메뉴 트리 노드 |
-| `SdFlatMenu` | interface | 플랫 메뉴 항목 |
-| `SdPermission` | interface | 권한 트리 노드 |
-| `SharedDataBase` | interface | 공유 데이터 기본 인터페이스 |
-| `SharedDataInfo` | interface | 공유 데이터 등록 정보 |
-| `SharedDataHandle` | interface | 공유 데이터 핸들 (items signal + get) |
-| `SdModalContentDef` | interface | 모달 컴포넌트 구현 인터페이스 |
-| `SdModalInfo` | interface | 모달 생성 시 전달하는 정보 |
-| `SdModalOptions` | interface | 모달 옵션 (크기, 위치, 동작) |
-| `SdToastContentDef` | interface | 토스트 컴포넌트 구현 인터페이스 |
-| `SdToastInput` | interface | 커스텀 토스트 생성 입력 |
-| `SdToastSeverity` | type | 토스트 심각도 (`"info" \| "success" \| "warning" \| "danger"`) |
-| `SdToastTheme` | type | 토스트 테마 (severity + `"primary" \| "secondary" \| "gray" \| "blue-gray"`) |
-| `SdBusyType` | type | busy 표시 유형 (`"spinner" \| "bar" \| "cube"`) |
-| `SdPrint` | interface | 인쇄 컴포넌트 구현 인터페이스 |
-| `SdPrintInput` | interface | 인쇄 생성 입력 |
-| `SelectModalOutputResult` | interface | 모달 선택 결과 (`selectedItemKeys`, `selectedItems`) |
-
--> See [docs/provider-types.md](./docs/provider-types.md) for details.
-
-### Directives
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdEvents` | directive | `.capture`, `.passive`, `.once` 수식어 및 커스텀 이벤트 바인딩 |
-| `SdRipple` | directive | `[sdRipple]` 리플 효과 |
-| `SdShowEffect` | directive | `[sdShowEffect]` 뷰포트 진입 시 reveal 애니메이션 |
-| `SdInvalid` | directive | `[sdInvalid]` 유효성 검증 표시기 |
-| `SdTypedTemplate` | directive | `ng-template[typed]` 템플릿 컨텍스트 타입 가드 |
-| `SdItemOfTemplate` | directive | `ng-template[itemOf]` 항목 반복 템플릿 타입 가드 |
-| `SdItemOfTemplateContext` | interface | itemOf 템플릿 컨텍스트 (`$implicit`, `item`, `index`, `depth`) |
-| `SdRouterLink` | directive | `[sdRouterLink]` 라우터 네비게이션 (Ctrl+클릭 새 창) |
-| `SdCommandDirective` | directive | `[sdSaveCommand]`, `[sdRefreshCommand]`, `[sdInsertCommand]` 키보드 단축키 output 이벤트 디렉티브 |
-| `SdResizeDirective` | directive | `[sdResize]` ResizeObserver 기반 resize output 이벤트 디렉티브 |
-| `SdResizeEvent` | interface | resize 이벤트 데이터 (`heightChanged`, `widthChanged`, `target`, `contentRect`) |
-| `SdIntersectionDirective` | directive | `[sdIntersection]` IntersectionObserver 기반 intersection output 이벤트 디렉티브 |
-| `SdIntersectionEvent` | interface | intersection 이벤트 데이터 (`entry`) |
-
--> See [docs/directives.md](./docs/directives.md) for details.
-
-### Plugins
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdOptionEventPlugin` | class | `.capture`, `.passive`, `.once` 이벤트 옵션 플러그인 (`provideSdAngular`에서 자동 등록) |
-| `SdGlobalErrorHandlerPlugin` | class | 글로벌 에러 핸들러 (PromiseRejection, ErrorEvent 등) |
-
--> See [docs/plugins.md](./docs/plugins.md) for details.
-
-### Pipes
-
-| API | Type | Description |
-|-----|------|-------------|
-| `FormatPipe` | pipe | DateTime/DateOnly/string 포매팅 파이프 |
-
--> See [docs/pipes.md](./docs/pipes.md) for details.
-
-### Utils & Setups
-
-| API | Type | Description |
-|-----|------|-------------|
-| `mark` | function | WritableSignal 변경 알림 트리거 (shallow copy) |
-| `withBusy` | function | busy count 증감과 함께 비동기 작업 실행 |
-| `injectParent` | function | 가장 가까운 부모 컴포넌트 인스턴스 주입 |
-| `setSafeStyle` | function | Renderer2로 여러 CSS 스타일 일괄 적용 |
-| `injectSdSystemConfigResource` | function | 시스템 설정 resource 래퍼 |
-| `injectCurrentPageCodeSignal` | function | 현재 페이지 코드 signal |
-| `injectFullPageCodeSignal` | function | 전체 페이지 코드 signal (NavigationEnd 기반) |
-| `injectViewTitleSignal` | function | 현재 뷰 타이틀 signal |
-| `injectViewTypeSignal` | function | 현재 뷰 타입 signal (`page \| modal \| control`) |
-| `useSelectionManager` | function | 선택 관리 composable (single/multi) |
-| `useSortingManager` | function | 정렬 관리 composable |
-| `useExpandingManager` | function | 트리 확장/축소 관리 composable |
-| `setupBgTheme` | function | body 배경 테마 색상 설정 |
-| `setupRipple` | function | 리플 효과 설정 |
-| `setupRevealOnShow` | function | 뷰포트 진입 시 reveal 애니메이션 설정 |
-| `setupInvalid` | function | 유효성 검증 표시기 설정 |
-| `setupModelHook` | function | model signal의 set을 가드 함수로 래핑 |
-| `setupCanDeactivate` | function | 모달/라우트 canDeactivate 설정 |
-| `setupCumulateSelectedKeys` | function | 선택된 항목의 키 누적 동기화 |
-| `setupCloserWhenSingleSelectionChange` | function | 단일 선택 변경 시 모달 자동 닫기 |
-
--> See [docs/utils.md](./docs/utils.md) for details.
-
-### Type Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `DirectiveInputSignals` | type | InputSignal 프로퍼티에서 값 타입 추출 |
-| `UndefToOptional` | type | undefined 포함 프로퍼티를 optional로 변환 |
-| `WithOptional` | type | 특정 키를 optional로 변환 |
-| `SdViewType` | type | 뷰 타입 (`"page" \| "modal" \| "control"`) |
-| `SortingDef` | interface | 정렬 정의 (`key`, `desc`) |
-| `ExpandItemDef` | interface | 트리 확장 항목 정의 |
-| `SdSelectModal` | interface | 모달 선택 컴포넌트 인터페이스 |
-| `SdSelectModalInfo` | type | 모달 선택 정보 타입 |
-| `SdTextfieldTypes` | type | 텍스트필드 타입별 값 타입 매핑 |
-| `sdTextfieldTypes` | const | 텍스트필드 타입 문자열 배열 |
-| `SelectModeValue` | type | select mode별 value 타입 매핑 |
-
--> See [docs/type-utilities.md](./docs/type-utilities.md) for details.
-
-### Features
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdBaseContainer` | component | 페이지/모달/뷰 공통 레이아웃 컨테이너 |
-| `SdAddressSearchModal` | component | Daum Postcode 주소 검색 모달 |
-| `Address` | interface | 주소 검색 결과 |
-| `SdPermissionTable` | component | 권한 매트릭스 테이블 (items, value) |
-| `SdDataSheetBase` | class | 데이터 시트 CRUD 추상 클래스 |
-| `SdDataSheet` | component | 데이터 시트 presentation 컴포넌트 |
-| `SdDataSheetColumn` | directive | 데이터 시트 컬럼 (edit 추가) |
-| `SdDataDetailBase` | class | 상세 폼 추상 클래스 |
-| `SdDataDetail` | component | 상세 폼 presentation 컴포넌트 |
-| `SdDataSelectButtonBase` | class | 모달 기반 선택 버튼 추상 클래스 |
-| `SdDataSelectButton` | component | 선택 버튼 presentation 컴포넌트 |
-| `SdSharedDataSelect` | component | 공유 데이터 드롭다운 선택 |
-| `SdSharedDataSelectButton` | component | 공유 데이터 모달 선택 버튼 |
-| `SdSharedDataSelectList` | component | 공유 데이터 목록형 선택 (selectedItem model) |
-| `matchesSearchText` | function | 공백 구분 AND 조건 텍스트 검색 매칭 |
-| `getOrmDataEditToastErrorMessage` | function | ORM 편집 에러 메시지 변환 (FK 위반 등 DB 에러를 한국어 메시지로) |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### Feature Types
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdDataSheetItemPropInfo` | interface | 데이터 시트 항목 속성 정보 |
-| `SdDataSheetItemInfo` | interface | 데이터 시트 항목 정보 (key, canSelect 등) |
-| `SdDataSheetSearchResult` | interface | 데이터 시트 검색 결과 |
-| `SdDataDetailDataInfo` | interface | 상세 폼 데이터 정보 |
-
--> See [docs/features.md](./docs/features.md) for details.
-
-### UI - Layout
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdDockContainer` | component | 도킹 레이아웃 컨테이너 |
-| `SdDock` | component | 도킹 영역 (top/bottom/left/right) |
-| `SdGap` | component | 간격 (gap) 컴포넌트 |
-| `SdKanbanBoard` | component | 칸반 보드 (드래그앤드롭, selectedValues) |
-| `SdKanbanBoardDropInfo` | interface | 칸반 보드 드롭 이벤트 정보 |
-| `SdKanbanDragRef` | interface | 칸반 드래그 참조 인터페이스 |
-| `SdKanbanDropTarget` | interface | 칸반 드롭 타겟 인터페이스 |
-| `SdKanban` | component | 칸반 아이템 |
-| `SdKanbanLane` | component | 칸반 레인 |
-
--> See [docs/ui-layout.md](./docs/ui-layout.md) for details.
-
-### UI - Form
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdButton` | component | 버튼 |
-| `SdAnchor` | component | 앵커 (인라인 버튼) |
-| `SdAdditionalButton` | component | 추가 동작 버튼 (드롭다운 포함) |
-| `SdModalSelectButton` | component | 모달 선택 버튼 |
-| `SdTextfield` | component | 텍스트 입력 (13가지 타입: number, text, password, color, email, format, date, month, year, datetime, datetime-sec, time, time-sec) |
-| `SdTextarea` | component | 멀티라인 텍스트 입력 |
-| `SdNumpad` | component | 숫자 패드 |
-| `SdRange` | component | 범위 슬라이더 |
-| `SdDateRangePicker` | component | 날짜 범위 선택기 |
-| `SdStatePreset` | component | 상태 프리셋 저장/불러오기 |
-| `SdStatePresetDef` | interface | 상태 프리셋 데이터 (name, state) |
-| `SdCheckbox` | component | 체크박스 |
-| `SdSwitch` | component | 스위치 토글 |
-| `SdCheckboxGroup` | component | 체크박스 그룹 |
-| `SdCheckboxGroupItem` | component | 체크박스 그룹 항목 |
-| `SdTiptapEditor` | component | TipTap 리치 텍스트 에디터 |
-| `SdSelect` | component | 드롭다운 선택 (single/multi) |
-| `SdSelectItem` | component | 드롭다운 선택 항목 |
-| `SdSelectButton` | component | 버튼 스타일 선택 |
-| `SdForm` | component | 폼 래퍼 (submit 이벤트, busy 관리) |
-
--> See [docs/ui-form.md](./docs/ui-form.md) for details.
-
-### UI - Navigation
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdCollapse` | component | 접기/펼치기 패널 |
-| `SdCollapseIcon` | component | 접기/펼치기 아이콘 |
-| `SdTab` | component | 탭 컨테이너 |
-| `SdTabItem` | component | 탭 항목 |
-| `SdPagination` | component | 페이지네이션 |
-| `SdSidebarContainer` | component | 사이드바 컨테이너 |
-| `SdSidebar` | component | 사이드바 |
-| `SdSidebarMenu` | component | 사이드바 메뉴 |
-| `SdSidebarUser` | component | 사이드바 사용자 영역 |
-| `SdSidebarUserMenu` | interface | 사이드바 사용자 메뉴 항목 |
-| `SdTopbarContainer` | component | 탑바 컨테이너 |
-| `SdTopbar` | component | 탑바 |
-| `SdTopbarMenu` | component | 탑바 메뉴 |
-| `SdTopbarUser` | component | 탑바 사용자 영역 |
-| `SdTopbarUserMenu` | interface | 탑바 사용자 메뉴 항목 |
-| `getMenuRouterLinkOption` | function | 메뉴에서 라우터 링크 옵션 추출 |
-| `getIsMenuSelected` | function | 메뉴 선택 여부 확인 |
-
--> See [docs/ui-navigation.md](./docs/ui-navigation.md) for details.
-
-### UI - Data
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdList` | component | 리스트 |
-| `SdListItem` | component | 리스트 항목 |
-| `SdSheet` | component | 스프레드시트 (정렬, 고정, 리사이즈). `key`로 설정 저장 |
-| `SdSheetColumn` | directive | 시트 컬럼 정의 (헤더, 너비, 고정, 정렬 등) |
-| `SdSheetColumnCellTemplate` | directive | 시트 컬럼 셀 내용 정의 (`ng-template[cell]`), `SdSheetCellContext` 타입 가드 제공 |
-| `SdSheetCellContext` | interface | 시트 셀 템플릿 컨텍스트 (`$implicit`, `item`, `index`, `depth`, `edit`) |
-| `SdSheetConfigModal` | component | 시트 설정 모달 |
-| `SdSheetColumnDef` | interface | 시트 컬럼 정의 데이터 |
-| `SdSheetConfig` | interface | 시트 설정 데이터 |
-| `SdSheetHeaderDef` | interface | 시트 헤더 정의 |
-| `SdSheetItemKeydownEventParam` | interface | 시트 항목 keydown 이벤트 파라미터 |
-| `SdSheetCellKeydownEventParam` | interface | 시트 셀 keydown 이벤트 파라미터 |
-
--> See [docs/ui-data.md](./docs/ui-data.md) for details.
-
-### UI - Visual
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdLabel` | component | 라벨 (테마, 크기) |
-| `SdNote` | component | 노트/알림 메시지 |
-| `SdProgress` | component | 진행률 바 |
-| `SdCalendar` | component | 캘린더 |
-| `SdBarcode` | component | 바코드 생성 (bwip-js) |
-| `SdEcharts` | component | ECharts 차트 래퍼 |
-| `BarcodeType` | type | 바코드 타입 |
-
--> See [docs/ui-visual.md](./docs/ui-visual.md) for details.
-
-### UI - Overlay
-
-| API | Type | Description |
-|-----|------|-------------|
-| `SdDropdown` | component | 드롭다운 트리거 |
-| `SdDropdownPopup` | component | 드롭다운 팝업 |
-| `SdModal` | component | 모달 래퍼 컴포넌트 |
-| `SdPromptModal` | component | 프롬프트 입력 모달 |
-| `SdConfirmModal` | component | 확인/취소 모달 |
-| `SdToast` | component | 토스트 개별 항목 |
-| `SdToastContainer` | component | 토스트 컨테이너 |
-| `SdBusyContainer` | component | busy 표시 컨테이너 |
-
--> See [docs/ui-overlay.md](./docs/ui-overlay.md) for details.
-
-### Styling
-
-| API | Type | Description |
-|-----|------|-------------|
-| `.flex-row`, `.flex-column` 등 | CSS class | Flexbox 레이아웃 유틸리티 |
-| `.grid`, `.grid-{1..12}` | CSS class | Grid 레이아웃 유틸리티 |
-| `.card` | CSS class | 카드 스타일 |
-| `.form-box`, `.form-table` | CSS class | 폼 레이아웃 |
-| `.table` | CSS class | 테이블 스타일 |
-| `.p-*`, `.m-*`, `.gap-*` 등 | CSS class | 간격 유틸리티 |
-| `--theme-*-*` | CSS custom property | OKLCH 색상 팔레트 (17+5색 x 7단계) |
-| `.sd-theme-dark` | theme class | 다크 모드 테마 |
-
--> See [docs/styling.md](./docs/styling.md) for details.
-
-## 컴포넌트 비동기 초기화 규칙
-
-컴포넌트에서 비동기 초기화가 필요한 경우 `async ngOnInit()`을 사용한다.
-
-```typescript
-export class SomePage implements OnInit {
-  busyCount = signal(0);
-
-  async ngOnInit() {
-    this.busyCount.update((v) => v + 1);
-    await this._sdToast.try(async () => {
-      // 비동기 초기화 로직
-    });
-    this.busyCount.update((v) => v - 1);
-  }
-}
-```
-
-- constructor 내 `void (async () => { ... })()` IIFE 패턴 **금지**
-- constructor 내 `void this._init()` 같은 수동 호출 패턴 **금지** — ngOnInit이 이미 같은 역할
-- `resource()` / `httpResource()`는 데이터 로딩 → signal 매핑 용도. 사이드이펙트(라우팅, toast 등) 포함 초기화에는 사용하지 않는다
-
-## 소비 프로젝트 네이밍 규칙
-
-`@simplysm/angular`를 소비하는 앱 프로젝트에서의 파일명·클래스명 규칙이다.
-파일명은 **kebab-case + dot-suffix**, 클래스명은 **PascalCase**를 따른다.
-
-| 접미어 | 조건 | 파일명 예시 | 클래스명 예시 |
-|--------|------|-------------|---------------|
-| `.sheet.ts` / `*Sheet` | `SdDataSheetBase` 상속 | `outbound-instruction.sheet.ts` | `OutboundInstructionSheet` |
-| `.detail.ts` / `*Detail` | `SdDataDetailBase` 상속 | `outbound-instruction.detail.ts` | `OutboundInstructionDetail` |
-| `.view.ts` / `*View` | sheet/detail 아닌 병합 컴포넌트 + route 연결 | `dashboard.view.ts` | `DashboardView` |
-| `.modal.ts` / `*Modal` | 모달 전용 컴포넌트 | `item-select.modal.ts` | `ItemSelectModal` |
-| `.provider.ts` / `*Provider` | `@Injectable` 클래스 (**`*Service` 금지**) | `app-service.provider.ts` | `AppServiceProvider` |
-| 접미어 없음 | route 미연결 일반 컨트롤 컴포넌트 | `instruction-item.ts` | `InstructionItem` |
-
-- `pipe`, `directive` 등 기타 Angular 구성요소는 `@simplysm/angular` 패키지 자체의 네이밍 패턴(`.pipe.ts`, `.directive.ts`)을 따른다
-
-## 소비 프로젝트 디렉토리 구조
-
-```
-src/
-├── app/                                  # 라우팅 페이지 (사이드바 메뉴 트리 구조와 대응)
-│   ├── login/
-│   └── home/
-│       ├── {메뉴-그룹}/                  # 사이드바 메뉴 그룹
-│       │   └── {도메인}/                 # 개별 도메인 (트리 깊이 제한 없음)
-│       │       ├── {도메인}.view.ts      # route 연결 병합 컴포넌트
-│       │       ├── {도메인}.sheet.ts     # SdDataSheetBase 상속
-│       │       ├── {도메인}.detail.ts    # SdDataDetailBase 상속
-│       │       ├── {이름}.modal.ts       # 도메인 전용 모달
-│       │       └── {이름}.ts            # 일반 컨트롤 (route 미연결)
-│       └── main/
-├── controls/                             # 앱 공유 컨트롤 컴포넌트
-├── directives/                           # 앱 공유 디렉티브
-├── modals/                               # 앱 전역 공통 모달
-├── providers/                            # 앱 전역 프로바이더
-├── types/                                # 타입 정의
-└── utils/                                # 유틸리티
-```
-
-- `app/` 하위 트리는 사이드바 메뉴 구조와 거의 대응된다
-- **배치 기준은 "어느 도메인에 소속되는가"**이다. provider, modal, directive, print-template, util 등 모든 종류의 파일이 소속 도메인 폴더 안에 배치된다 (다른 도메인에서 import하여 사용하는 것은 자유)
-- 특정 도메인에 소속되지 않는 공통 파일만 `src/` 직하의 `controls/`, `modals/`, `providers/` 등에 배치한다
-
-## inject 네이밍 컨벤션
-
-`Sd*Provider`를 `inject()`할 때 변수명은 다음 규칙을 따른다:
-
-- **Sd 접두어 유지**: 클래스명에서 `Sd`를 camelCase로 변환하여 유지한다
-- **Provider 접미어 제거**: 변수명에서 `Provider`를 제거한다
-
-| inject 대상 | 클래스 필드 | 로컬 변수 |
-|-------------|-----------|----------|
-| `SdToastProvider` | `private _sdToast = inject(SdToastProvider)` | `const sdToast = inject(SdToastProvider)` |
-| `SdModalProvider` | `private _sdModal = inject(SdModalProvider)` | `const sdModal = inject(SdModalProvider)` |
-| `SdServiceClientFactoryProvider` | `private _sdServiceClientFactory = inject(SdServiceClientFactoryProvider)` | `const sdServiceClientFactory = inject(...)` |
-
-## Usage Examples
-
-### 앱 부트스트랩
-
-```typescript
-import { provideSdAngular } from "@simplysm/angular";
-
-bootstrapApplication(AppComponent, {
-  providers: [
-    provideSdAngular({ clientName: "my-app" }),
-    provideRouter(routes),
-  ],
-});
-```
-
-### 모달 표시
-
-```typescript
-import { SdModalProvider, type SdModalInfo } from "@simplysm/angular";
-
-const sdModal = inject(SdModalProvider);
-
-const result = await sdModal.showAsync(
-  { title: "사용자 선택", type: UserSelectModal, inputs: { filter: "active" } },
-  { useCloseByBackdrop: true },
-);
-```
-
-### 서비스 + 이벤트 프록시 (AppServiceProvider 패턴)
-
-소비 프로젝트에서 서비스와 이벤트를 한 곳에서 관리하는 패턴:
-
-```typescript
-import { inject, Injectable } from "@angular/core";
-import { SdServiceClientFactoryProvider } from "@simplysm/angular";
-import { createOrmClientConnector, type OrmClientConnector, type ServiceProxy } from "@simplysm/service-client";
-import type { SystemLogServiceType } from "@my-server-package";
-import type { OrderUpdatedEvent } from "@my-server-package"; // import type만 가능
-
-@Injectable({ providedIn: "root" })
-export class AppServiceProvider {
-  private readonly _sdServiceClientFactory = inject(SdServiceClientFactoryProvider);
-
-  get client() {
-    return this._sdServiceClientFactory.get("MAIN");
-  }
-
-  // 서비스 프록시 — getService() 패턴
-  get systemLog() {
-    return this.client.getService<SystemLogServiceType>("SystemLog");
-  }
-
-  // 이벤트 프록시 — getEvent() 패턴 (getService()와 동일)
-  get orderUpdated() {
-    return this.client.getEvent<typeof OrderUpdatedEvent>("OrderUpdated");
-  }
-}
-```
-
-사용처에서:
-
-```typescript
-const appSvc = inject(AppServiceProvider);
-
-// 서비스 호출
-await appSvc.systemLog.writeLog("hello");
-
-// 이벤트 구독 — 이벤트 이름과 제네릭 타입을 반복 지정할 필요 없음
-const key = await appSvc.orderUpdated.addListener({ orderId: 123 }, async (data) => {
-  // data.status는 string으로 타입 추론
-});
-
-// 이벤트 발행
-await appSvc.orderUpdated.emit((info) => info.orderId === 123, { status: "shipped" });
-
-// 구독 해제
-await appSvc.orderUpdated.removeListener(key);
-```
-
-### 토스트 알림
-
-```typescript
-import { SdToastProvider } from "@simplysm/angular";
-
-const sdToast = inject(SdToastProvider);
-
-sdToast.success("저장되었습니다.");
-const result = await sdToast.try(async () => {
-  return await someAsyncWork();
-});
-```
-

package/claude/references/sd-simplysm14/capacitor-plugin-auto-update/usage.md

@@ -1,182 +0,0 @@
-# @simplysm/capacitor-plugin-auto-update
-
-심플리즘 패키지 - Capacitor 자동 업데이트 플러그인. 서버 버전 비교 후 APK 다운로드·설치를 처리하며, 외부 저장소(USB 등)에서도 업데이트할 수 있다.
-
-## Installation
-
-```bash
-npm install @simplysm/capacitor-plugin-auto-update
-```
-
-피어 의존성으로 `@capacitor/core ^7`이 필요하다. Android 네이티브 플러그인이 포함되어 있으므로 `npx cap sync` 후 사용한다.
-
-## API Overview
-
-### APK 설치
-
-| API | Type | Description |
-|-----|------|-------------|
-| `VersionInfo` | interface | 앱 버전 정보 (versionName, versionCode) |
-| `ApkInstallerPlugin` | interface | Capacitor 네이티브 플러그인 인터페이스 (직접 사용하지 않음) |
-| `ApkInstaller` | abstract class | APK 설치 플러그인 정적 파사드 — 권한 확인/요청, 설치, 버전 조회 |
-
-### 자동 업데이트
-
-| API | Type | Description |
-|-----|------|-------------|
-| `AutoUpdate` | abstract class | 자동 업데이트 오케스트레이터 — 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치 |
-
----
-
-## `VersionInfo`
-
-앱 버전 정보를 나타내는 인터페이스.
-
-```typescript
-export interface VersionInfo {
-  versionName: string;
-  versionCode: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `versionName` | `string` | 앱 버전 이름. semver 형식 (예: `"1.2.3"`). `AutoUpdate`의 버전 비교에 사용된다. |
-| `versionCode` | `string` | 앱 버전 코드. 정수를 문자열로 표현 (예: `"42"`). |
-
-## `ApkInstallerPlugin`
-
-Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `ApkInstaller` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
-
-```typescript
-export interface ApkInstallerPlugin {
-  install(options: { uri: string }): Promise<void>;
-  checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
-  requestPermissions(): Promise<void>;
-  getVersionInfo(): Promise<VersionInfo>;
-}
-```
-
-| Method | Return | Description |
-|--------|--------|-------------|
-| `install(options: { uri: string })` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치 인텐트 실행 |
-| `checkPermissions()` | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부(`granted`)와 AndroidManifest 선언 여부(`manifest`) 동시 확인 |
-| `requestPermissions()` | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청 — 시스템 설정 화면으로 이동 |
-| `getVersionInfo()` | `Promise<VersionInfo>` | PackageManager에서 현재 앱 버전 정보 조회 |
-
-## `ApkInstaller`
-
-APK 설치 플러그인 정적 파사드 클래스. Android에서는 네이티브 플러그인을 실행하고, 브라우저 환경에서는 `ApkInstallerWeb`으로 폴백한다. 브라우저 폴백: `install()`은 `alert()` 표시 후 반환, `checkPermissions()`는 항상 `{ granted: true, manifest: true }` 반환, `requestPermissions()`는 무동작, `getVersionInfo()`는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환.
-
-```typescript
-export abstract class ApkInstaller {
-  static async checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
-  static async requestPermissions(): Promise<void>;
-  static async install(apkUri: string): Promise<void>;
-  static async getVersionInfo(): Promise<VersionInfo>;
-}
-```
-
-| Method | Parameters | Return | Description |
-|--------|-----------|--------|-------------|
-| `checkPermissions` | 없음 | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부와 AndroidManifest 선언 여부 확인. `manifest: false`이면 APK를 재설치해야 한다. |
-| `requestPermissions` | 없음 | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청. 시스템 설정 화면으로 이동하므로 이후 `checkPermissions`로 결과를 폴링해야 한다. |
-| `install` | `apkUri: string` | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치. `FileSystem.getUri(filePath)`로 URI를 얻는다. |
-| `getVersionInfo` | 없음 | `Promise<VersionInfo>` | 현재 설치된 앱의 버전 정보 조회. 브라우저 환경에서는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환한다. |
-
-## `AutoUpdate`
-
-자동 업데이트 오케스트레이터. 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치한다. 모든 메서드가 `static`이며 인스턴스화하지 않는다. Android 환경 전용이며, 비-Android에서 호출하면 에러를 표시하고 앱을 무한 대기 상태로 전환한다.
-
-```typescript
-export abstract class AutoUpdate {
-  static async run(opt: {
-    log: (messageHtml: string) => void;
-    serviceClient: ServiceClient;
-  }): Promise<void>;
-
-  static async runByExternalStorage(opt: {
-    log: (messageHtml: string) => void;
-    dirPath: string;
-  }): Promise<void>;
-}
-```
-
-| Method | Parameters | Description |
-|--------|-----------|-------------|
-| `run` | `opt.log: (messageHtml: string) => void`, `opt.serviceClient: ServiceClient` | `AutoUpdateService.getLastVersion("android")`로 서버에서 최신 버전 정보를 조회한 뒤, 현재 버전보다 높으면 APK를 다운로드하여 설치한다. 업데이트 후 `_freezeApp()`으로 앱을 무한 대기 상태로 전환한다. |
-| `runByExternalStorage` | `opt.log: (messageHtml: string) => void`, `opt.dirPath: string` | 외부 저장소의 `opt.dirPath` 디렉토리에서 `{semver}.apk` 패턴 파일 중 최신 버전을 찾아 설치한다. 현재 버전보다 높은 경우에만 업데이트한다. |
-
-**`opt.log` 콜백**: HTML 문자열을 받아 사용자에게 진행 상황을 표시한다. 버튼(`<button>`) 등 인터랙티브 HTML이 포함될 수 있다. 에러 발생 시에도 `log`로 에러 메시지를 표시한 뒤 `_freezeApp()`으로 전환한다.
-
-**권한 처리**: 두 메서드 모두 내부적으로 `_checkPermission()`을 호출한다. `manifest: false`이면 재설치 에러를 throw하고, `granted: false`이면 권한 요청 후 최대 300초간 폴링한다.
-
-**버전 비교**: `semver` 라이브러리를 사용한다. `versionName`이 유효한 semver 형식이 아니면 업데이트 확인을 건너뛴다.
-
-## Usage Examples
-
-### 서버 기반 자동 업데이트
-
-앱 부트스트랩 시 `AutoUpdate.run()`을 호출한다. `AutoUpdateService`는 `@simplysm/service-common`의 서비스 인터페이스다.
-
-```typescript
-import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
-import type { ServiceClient } from "@simplysm/service-client";
-
-async function checkForUpdate(serviceClient: ServiceClient) {
-  const statusEl = document.getElementById("status")!;
-
-  await AutoUpdate.run({
-    log: (messageHtml) => {
-      statusEl.innerHTML = messageHtml;
-    },
-    serviceClient,
-  });
-
-  // 업데이트가 없거나 업데이트가 완료되면(무한 대기 전환 전) 이 줄에 도달한다.
-  statusEl.innerHTML = "";
-}
-```
-
-### 외부 저장소(USB) 기반 업데이트
-
-`opt.dirPath`는 외부 저장소 루트 기준 상대 경로다. 해당 경로에 `1.2.3.apk` 형식 파일이 있어야 한다.
-
-```typescript
-import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
-
-await AutoUpdate.runByExternalStorage({
-  log: (messageHtml) => {
-    document.getElementById("status")!.innerHTML = messageHtml;
-  },
-  dirPath: "updates/my-app",
-});
-```
-
-### APK 설치 직접 제어
-
-`AutoUpdate`를 사용하지 않고 `ApkInstaller`를 직접 제어하는 경우:
-
-```typescript
-import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
-import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
-
-// 권한 확인
-const { granted, manifest } = await ApkInstaller.checkPermissions();
-if (!manifest) {
-  // AndroidManifest.xml에 REQUEST_INSTALL_PACKAGES 미선언 → APK 재설치 필요
-  throw new Error("앱을 재설치해야 합니다.");
-}
-if (!granted) {
-  await ApkInstaller.requestPermissions();
-}
-
-// 현재 버전 확인
-const versionInfo = await ApkInstaller.getVersionInfo();
-// versionInfo.versionName → "1.2.3"
-// versionInfo.versionCode → "42"
-
-// APK 설치 (filePath는 FileSystem으로 저장한 경로)
-const apkUri = await FileSystem.getUri("/path/to/latest.apk");
-await ApkInstaller.install(apkUri);
-```