@simplysm/sd-claude 14.0.65 → 14.0.68

package/claude/references/sd-simplysm14/apis/angular/modal.md

@@ -0,0 +1,63 @@
+# @simplysm/angular — modal
+
+선언형 `<sd-modal>` 과 프로그래밍 방식 `SdModalProvider` 둘 다 지원.
+
+## 프로그래밍 방식
+
+```typescript
+const result = await inject(SdModalProvider).showAsync(
+  {
+    title: "주문 선택",
+    type: OrderSelectModal,            // SdModalContentDef<TOutput> 구현
+    inputs: { mode: "single" },        // DirectiveInputSignals<T> (close/initialized 등 제외)
+  },
+  { fill: true, resizable: true, key: "order-select" },
+);
+```
+
+- `showAsync<T>(info, options?)` → `Promise<TOutput | undefined>`. `close.emit(value)` 시 resolve.
+- `SdModalProvider.modalCount = signal(0)` (열린 모달 수).
+- `key`를 주면 `SdSystemConfigProvider` 통해 width/height/위치 영속화.
+- `noFirstControlFocusing: true`면 첫 tabbable 요소가 아닌 dialog 자체 포커스.
+
+### 모달 컨텐츠 컴포넌트 인터페이스
+
+```typescript
+interface SdModalContentDef<O> {
+  initialized: Signal<boolean>;
+  close: OutputEmitterRef<O | undefined>;
+  actionTplRef?: TemplateRef<any>;
+  readonly _optionalModalInputs?: string;   // 키 union → 해당 input들이 optional 처리
+}
+```
+
+`SdModalInfo<T, X>`: `X`는 inputs에서 제외할 추가 키 union (예: `SdSelectModalInfo`가 `selectMode|selectedKeys` 제외).
+
+### `SdModalOptions`
+
+`key`, `hideHeader`, `hideCloseButton`, `headerStyle`, `useCloseByBackdrop`, `useCloseByEscapeKey`, `float`, `fill`, `resizable`, `movable`, `position: "bottom-right"|"top-right"`, `minHeightPx`, `minWidthPx`, `heightPx`, `widthPx`, `noFirstControlFocusing`.
+
+## 선언형 `<sd-modal>`
+
+`open` model, `title`/`key`/`hideHeader`/`hideCloseButton`/`headerStyle`/`useCloseByBackdrop`/`useCloseByEscapeKey`/`float`/`fill`/`resizable`/`movable`/`position`/`minHeightPx`/`minWidthPx`/`heightPx`/`widthPx`/`actionTplRef` input. `closeRequest` output (배경 클릭/ESC/닫기 버튼).
+
+## 내부에서 모달 정보 사용
+
+```typescript
+const am = inject(SdActivatedModalProvider, { optional: true });
+am?.modalComponent();    // SdModal 인스턴스 (title() 등)
+am?.contentComponent();  // 컨텐츠 인스턴스
+am.canDeactivateFn = () => isClean();   // 닫기 차단 (false 반환 시)
+```
+
+## 내장 컨텐츠 컴포넌트
+
+- `SdPromptModal` (`SdModalContentDef<string>`): `message` input. Enter/확인 → `close.emit(value)` (빈 값이면 emit X), 취소 → `undefined`.
+- `SdConfirmModal` (`SdModalContentDef<boolean>`): `message` input. 확인 → `true`, 취소 → `undefined`.
+- `SdAddressSearchModal` (`SdModalContentDef<Address>`): Daum Postcode 스크립트 자동 로드. `Address = { postNumber, address, buildingName }`.
+
+## 주의
+
+- `SdModalContentDef` 의 `initialized` signal 은 컨텐츠 준비 후 `true` 로 (인쇄/모달 등이 대기).
+- 모달은 body에 직접 attach (z-index 자동 할당, 최상위로 끌어올림). focus trap 적용.
+- 닫힘 애니메이션 transition duration 대기 후 destroy.

package/claude/references/sd-simplysm14/apis/angular/routing.md

@@ -0,0 +1,45 @@
+# @simplysm/angular — routing
+
+Angular Router 위에 페이지 코드(`a.b.c` 형식)·뷰 타입·새창 네비게이션을 얹는 헬퍼.
+
+## `SdRouterLink` 디렉티브
+
+```html
+<a [sdRouterLink]="{ link: '/home/order/list', params: { id }, queryParams, outletName, window: { width, height } }">go</a>
+```
+
+- 일반 클릭 → `router.navigate`. Ctrl/Shift 클릭 또는 새창 모드(`isWindow`)일 때 → `SdNavigateWindowProvider.open` 으로 새 창. Alt+click 무시.
+- `outletName` 지정 시 named outlet 으로 navigate.
+
+## `SdNavigateWindowProvider`
+
+```typescript
+const nav = inject(SdNavigateWindowProvider);
+nav.open("/home/order/list", { id }, "width=800,height=600");
+nav.isWindow; // 현재 컨텍스트가 팝업 윈도우인지
+```
+
+URL hash 끝에 `;window=true` 가 있으면 `isWindow=true`. 부모 unload 시 자기가 연 창 자동 close.
+
+## Page Code Signal
+
+페이지 코드 = activated route URL segment 를 `.` 으로 join.
+
+- `injectCurrentPageCodeSignal()`: 현재 라우트의 segment 신호 (`undefined` if no ActivatedRoute).
+- `injectFullPageCodeSignal()`: router.url 기반 풀 코드.
+- `injectViewTitleSignal()`: 모달이면 `modalComponent.title()`, 아니면 `SdAppStructureProvider.getTitleByFullCode`.
+- `injectViewTypeSignal(): Signal<SdViewType>`. `SdViewType = "page" | "modal" | "control"`. 모달 컨텍스트면 `"modal"`, page-level route component면 `"page"`, 그 외 `"control"`.
+
+## `setupCanDeactivate(fn: () => boolean)`
+
+constructor 내 호출. 모달 컨텍스트면 `SdActivatedModalProvider.canDeactivateFn` 설정, 라우트 컨텍스트면 `route.routeConfig.canDeactivate` 에 push (destroy 시 제거).
+
+## 메뉴 유틸
+
+- `getMenuRouterLinkOption(menu: SdMenu)`: leaf 메뉴를 `SdRouterLink` 옵션(`{ link, queryParams }`)으로 변환. children/url 있으면 `undefined`.
+- `getIsMenuSelected(menu, fullPageCode, customFn?)`: 현재 페이지가 메뉴와 일치하는지.
+
+## 주의
+
+- 페이지 코드는 hash router 기준 `/home/<code>` 구조 가정.
+- `injectCurrentPageCodeSignal` 은 `pathFromRoot.slice(2)` 사용 — root + `home` 두 레벨 위 라우트 컴포넌트에서 의미 있음.

package/claude/references/sd-simplysm14/apis/angular/select-dropdown.md

@@ -0,0 +1,35 @@
+# @simplysm/angular — select-dropdown
+
+## `<sd-dropdown>` / `<sd-dropdown-popup>`
+
+```html
+<sd-dropdown [(open)]="open" [disabled]="false">
+  trigger 컨텐츠
+  <sd-dropdown-popup>팝업 컨텐츠</sd-dropdown-popup>
+</sd-dropdown>
+```
+
+- `open` 시 popup을 body로 이동(트리거 위치 기준 배치). 모바일(`max-width:520px`)이면 backdrop+bottom sheet.
+- 트리거 클릭/Enter/ArrowDown 으로 open.
+
+## `<sd-select<M extends "single"|"multi", T>>`
+
+```html
+<sd-select [items]="items" [(value)]="value" [selectMode]="'single'" [trackByFn]="byId">
+  <sd-select-item *ngFor="let it of items" [value]="it.id">{{ it.name }}</sd-select-item>
+</sd-select>
+```
+
+`SelectModeValue<T> = { single: T; multi: T[] }`. value type = `SelectModeValue<T>[M]`.
+
+주요 input: `selectMode`, `value` (model), `placeholder`, `disabled`, `inline`, `inset`, `size`, `required`, `hideSelectAll`, `multiSelectionDisplayDirection: "vertical"`, `items`, `trackByFn`, `getChildrenFn` (트리), `contentClass/Style`, `dropdownOpen` (model).
+
+`<ng-template #headerTpl>`, `<ng-template #beforeTpl>`, `<ng-template itemOf>` (`SdItemOfTemplate`) 으로 커스터마이즈.
+
+## `<sd-select-item<T> [value]>`
+
+projected content 가 옵션 라벨.
+
+## `<sd-select-button>`
+
+검색 트리거 버튼만 노출하는 경량 select (내부 사용용).

package/claude/references/sd-simplysm14/apis/angular/selection-managers.md

@@ -0,0 +1,50 @@
+# @simplysm/angular — selection-managers
+
+`<sd-sheet>`/`<sd-select>` 등이 내부에서 쓰는 선택·확장·정렬 로직을 외부 컴포넌트에서도 재사용할 수 있도록 추출된 함수 훅들. signal 바인딩.
+
+## `useSelectionManager<TItem, TKey>(options)`
+
+```typescript
+const sm = useSelectionManager({
+  displayItems,                                // Signal<TItem[]>
+  selectedKeys,                                // WritableSignal<TKey[]>
+  selectMode,                                  // Signal<"single"|"multi"|undefined>
+  getItemSelectableFn,                         // Signal<((item) => boolean|string) | undefined>
+  trackByFn,                                   // Signal<(item, idx) => TKey>
+});
+sm.hasSelectable; sm.isAllSelected;
+sm.getSelectable(item);    // true | string(reason) | undefined
+sm.select(item); sm.deselect(item); sm.toggle(item); sm.toggleAll();
+sm.isSelected(item); sm.getCanChangeFn(item);
+```
+
+- `single`이면 select 시 기존 키 대체. `multi` 면 추가.
+- 키 비교는 `obj.equal` (`@simplysm/core-common`).
+- `trackByFn` 반환이 `null`이면 선택 불가.
+
+## `useExpandingManager<T>(binding)`
+
+```typescript
+interface ExpandItemDef<T> { item; parentDef?; hasChildren; depth }
+const em = useExpandingManager({
+  items, expandedItems,
+  getChildrenFn,    // Signal<((item, idx) => T[] | undefined) | undefined>
+  sort,             // (items: T[]) => T[]
+});
+em.displayItems; em.hasExpandable; em.isAllExpanded;
+em.toggle(item); em.toggleAll(); em.isVisible(item); em.def(item);
+```
+
+부모가 collapsed면 자식은 `isVisible=false`.
+
+## `useSortingManager(options)`
+
+```typescript
+interface SortingDef { key: string; desc: boolean }
+const sm = useSortingManager({ sorts });
+sm.defMap;     // Signal<Map<key, { indexText?, desc }>>
+sm.toggle(key, multiple);  // multiple=true면 multi-key sort, 아니면 단일
+sm.sort(items);            // null < non-null, string localeCompare
+```
+
+`toggle` 토글 순서: 없음 → asc → desc → 제거.

package/claude/references/sd-simplysm14/apis/angular/shared-data.md

@@ -0,0 +1,42 @@
+# @simplysm/angular — shared-data
+
+서버에서 가져오는 코드성 데이터(부서, 거래처 등)를 키 기반으로 등록/구독, 변경 이벤트로 자동 부분 갱신.
+
+## `SdSharedDataProvider<T>` (abstract)
+
+```typescript
+@Injectable({ providedIn: "root" })
+class MySharedData extends SdSharedDataProvider<{ depts: DeptDto; vendors: VendorDto }> {
+  initialize(): void {
+    this.register("depts", {
+      serviceKey: "main",
+      getter: (changeKeys) => svc.depts.getList(changeKeys),
+      orderBy: (it) => it.name,
+    });
+  }
+}
+```
+
+- 각 아이템 타입은 `SharedDataBase<TKey>` 확장: `{ __valueKey: TKey, __searchText: string, __isHidden: boolean, __parentKey? }`.
+- `register(name, info)` 후 `getHandle(name)` → `SharedDataHandle<T> { items: Signal<T[]>; get(key) }`. 첫 호출 시 lazy load + 이벤트 리스너 등록.
+- `emitAsync(name, changeKeys?)` → 다른 클라이언트(또는 자기 자신)에 `SdSharedDataChangeEvent` 발행. `changeKeys` 없으면 전체 리로드, 있으면 해당 키들만 재조회 후 merge (orderBy 재적용).
+- `loadingCount = signal(0)`, `wait()` (loadingCount 0까지).
+- `SdSharedDataChangeEvent` = `defineEvent<{ name; filter }, (string|number)[] | undefined>("SdSharedDataChange")` — 동일 name+filter 매칭 리스너에 키 발행.
+
+## `<sd-shared-data-select<TItem, TMode, TModal>>`
+
+`SharedDataBase` 항목에서 키를 선택하는 셀렉트. `__isHidden`/`__searchText` 활용.
+
+inputs: `items` (required), `value` (model: 단일/배열 키), `selectMode`, `disabled`, `required`, `useUndefined`, `inset`, `inline`, `size`, `filterFn(item, index, ...params)`, `filterFnParams`, `modal: SdSelectModalInfo<TModal>` (검색 모달), `editModal: SdModalInfo<SdModalContentDef<boolean>>` (신규 등록), `selectClass`, `multiSelectionDisplayDirection: "vertical"`, `getIsHiddenFn` (default `__isHidden`), `getSearchTextFn` (default `__searchText`), `displayOrderKeyProp`.
+
+## `<sd-shared-data-select-button>`
+
+modal 강제(검색 모달 필수). value: 단일/배열 키.
+
+## `<sd-shared-data-select-list>`
+
+list 형태 단일 선택. inputs: `items` (req), `selectedItem` (model), `canChangeFn(item) => boolean | Promise<boolean>`, `selectedIcon`, `useUndefined`, `filterFn`, `modal`, `header`, `pageItemCount`.
+
+## `matchesSearchText(itemText, searchQuery)`
+
+공백 분리 AND 매칭(lowercase). 빈 쿼리는 true.

package/claude/references/sd-simplysm14/apis/angular/sheet.md

@@ -0,0 +1,52 @@
+# @simplysm/angular — sheet
+
+가상 스크롤 데이터 그리드. 컬럼·셀 템플릿·정렬·페이징·선택·확장 트리·설정 모달 내장.
+
+## 기본 사용
+
+```html
+<sd-sheet
+  [key]="'order-list'"
+  [items]="items"
+  [trackByFn]="byId"
+  [selectMode]="'multi'"
+  [(selectedKeys)]="selectedKeys"
+  [(sorts)]="sorts"
+  [(currentPage)]="page"
+  [totalPageCount]="totalPages"
+  [itemsPerPage]="50"
+  [useAutoSort]="false">
+
+  <sd-sheet-column [key]="'no'" [header]="'번호'" [width]="'80px'" [fixed]="true">
+    <ng-template cell let-item="item" let-index="index">{{ index + 1 }}</ng-template>
+  </sd-sheet-column>
+</sd-sheet>
+```
+
+## `<sd-sheet<TItem>>` 입력/출력
+
+- inputs: `key`, `items`, `trackByFn`, `selectMode`, `autoSelect: "click"|"focus"`, `getItemSelectableFn`, `getChildrenFn` (트리), `useAutoSort`, `visiblePageCount=10`, `totalPageCount`, `itemsPerPage`, `focusMode: "row"|"cell" = "cell"`, `inset`, `contentStyle`, `getItemCellClassFn`, `getItemCellStyleFn`, `hideConfigBar`, `columnControlsInput` (외부 정의된 컬럼 추가).
+- outputs: `itemKeydown: SdSheetItemKeydownEventParam<T> { item, event }`, `cellKeydown: SdSheetCellKeydownEventParam<T> { item, key, event }`.
+- models: `selectedKeys: unknown[]`, `expandedItems: TItem[]`, `sorts: SortingDef[]`, `currentPage: number`.
+- `key` 지정 시 설정 모달(`SdSheetConfigModal`)로 너비/숨김/고정/순서를 `SdSystemConfigProvider`에 영속화.
+
+## `<sd-sheet-column<T> [key] [header]>`
+
+inputs: `key`(required), `header: string|string[]` (배열은 다중 행 헤더), `headerStyle`, `tooltip`, `width`, `fixed`, `hidden`, `collapse`, `disableSorting`, `disableResizing`, `ordering`.
+
+자식 template:
+- `<ng-template cell let-item="item">` (필수, `SdSheetColumnCellTemplate`, ctx: `SdSheetCellContext<T> = { $implicit, item, index, depth, edit }`).
+- `<ng-template #headerTpl>` (선택, 커스텀 헤더).
+- `<ng-template #summaryTpl>` (선택, 합계 행).
+
+## 타입
+
+```typescript
+interface SdSheetColumnDef { key; header; headerStyle?; tooltip?; width?; fixed; hidden; collapse; disableSorting; disableResizing; ordering }
+interface SdSheetHeaderDef { text; colspan; rowspan; isLastRow; fixed; colDef?; colIndex }
+interface SdSheetConfig    { columnRecord: Record<string, { width?; hidden?; fixed?; ordering? }> }
+```
+
+## 설정 모달
+
+`SdSheetConfigModal` (`SdModalContentDef<SdSheetConfig | undefined>`): `sheetKey`, `controls: SdSheetColumn[]`, `config: SdSheetConfig | undefined` inputs. 사용자가 컬럼 너비/숨김/고정/순서 편집 후 저장 → `close.emit(config)`.

package/claude/references/sd-simplysm14/apis/angular/toast.md

@@ -0,0 +1,46 @@
+# @simplysm/angular — toast
+
+전역 토스트. `SdToastContainer`는 첫 호출 시 body에 자동 생성.
+
+## 기본 사용
+
+```typescript
+const toast = inject(SdToastProvider);
+toast.info("저장되었습니다.");
+toast.success("...");
+toast.warning("...");
+toast.danger("...");
+
+const progress = toast.info("업로드 중", true);   // WritableSignal<number>
+progress.set(50);   // 100 도달 시 1초 후 자동 dismiss
+
+await toast.try(async () => svc.save(), (e) => `저장 실패: ${e.message}`);
+// 에러 시 danger 토스트 + systemLog, 성공 시 결과 반환
+```
+
+- 일반 토스트: 3초 후 자동 해제(호버 중이면 leave 후 1초 지연).
+- progress 토스트: 100% 도달 후 1초.
+- `alertThemes = signal<SdToastSeverity[]>([])`: 포함된 severity는 토스트 대신 `window.alert`.
+- `overlap = signal(false)`: 새 토스트 표시 시 기존 토스트 모두 제거.
+- `beforeShowFn?: (theme) => void`: 표시 직전 후크 (예: 사운드).
+
+## 커스텀 컨텐츠 토스트
+
+```typescript
+interface SdToastContentDef<O> { close: OutputEmitterRef<O | undefined>; }
+interface SdToastInput<T>      { type: Type<T>; inputs: DirectiveInputSignals<T> 제외 close }
+
+const result = await toast.notify({ type: MyToastComp, inputs: { kind: "x" } });
+```
+
+`close.emit` 시 resolve. 5초 자동 dismiss (resolve undefined).
+
+## 타입
+
+- `SdToastSeverity = "info" | "success" | "warning" | "danger"`
+- `SdToastTheme = "primary" | "secondary" | SdToastSeverity | "gray" | "blue-gray"` (SdToast 컴포넌트의 theme input)
+
+## `SdToast` / `SdToastContainer` (직접 사용은 비권장)
+
+- `<sd-toast [open] [theme] [useProgress] [(progress)] [(message)]>` — aria-live 자동 (`polite` info/success, `assertive` warning/danger).
+- `<sd-toast-container [overlap]>` — 위치 컨테이너. `SdToastProvider`가 lazily 생성.

package/claude/references/sd-simplysm14/apis/angular/visual.md

@@ -0,0 +1,41 @@
+# @simplysm/angular — visual
+
+데이터 시각화/표시 전용 컴포넌트.
+
+## `<sd-label>`
+
+배지 형 라벨. `theme`(테마 컬러), `color` (커스텀), `clickable`. content projection.
+
+## `<sd-note>`
+
+알림 박스 형. `theme`, `size`, `inset`. content projection.
+
+## `<sd-progress>`
+
+```html
+<sd-progress [theme]="'primary'" [value]="60" [size]="'sm'" [inset]="false" />
+```
+
+`theme` (required), `value: number` (0-100, required), `size`, `inset`.
+
+## `<sd-calendar<T>>`
+
+월별 달력 렌더. 
+
+- 필수: `items: T[]`, `getItemDateFn: (item, idx) => DateOnly`.
+- `yearMonth = input(new DateOnly().setDay(1))` (해당 월).
+- `weekStartDay = 0`, `minDaysInFirstWeek = 1`.
+
+## `<sd-barcode>`
+
+`bwip-js` 래퍼. `type: BarcodeType` (required), `value: string`. `BarcodeType` 은 bwip-js 지원 심볼로지 union (`code128`, `qrcode`, `ean13`, ... — `sd-barcode.ts` 참조).
+
+## `<sd-echarts>`
+
+ECharts 5/6 래퍼.
+
+```html
+<sd-echarts [option]="option" [notMerge]="false" [loading]="false" />
+```
+
+`option: echarts.EChartsOption` (required).

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

@@ -0,0 +1,76 @@
+# @simplysm/capacitor-plugin-auto-update
+
+Android Capacitor 앱의 APK 자동 업데이트 플러그인 (서버 또는 외부 저장소 기반).
+
+## 사용 트리거 인덱스
+
+- **AutoUpdate** — 앱 부팅 시 최신 APK 확인·다운로드·설치 전 과정을 한 번에 실행할 때.
+- **ApkInstaller** — APK 설치 권한 체크/요청, 임의 APK 파일 설치, 현재 앱 버전 조회 등 저수준 단위 동작이 필요할 때.
+- **VersionInfo / ApkInstallerPlugin** — 위 두 API 호출 결과 타입을 참조할 때.
+
+## AutoUpdate
+
+`abstract class AutoUpdate` (static 메서드만). Android 전용. 호출 시 권한 확인 → 버전 비교 → 다운로드 → 설치 → 무한 대기(freeze)까지 자동 처리. 오류는 catch 후 `log` 로 메시지 노출 후 freeze.
+
+```ts
+AutoUpdate.run(opt: {
+  log: (messageHtml: string) => void;
+  serviceClient: ServiceClient;     // @simplysm/service-client
+}): Promise<void>
+```
+서버의 `AutoUpdateService` 에 `getLastVersion("android")` 호출 → `{ version, downloadPath }` 수신 → `serviceClient.hostUrl + downloadPath` 에서 APK 다운로드 → `appCache/latest.apk` 로 저장 후 설치. 다운로드 진행률은 `log` 로 갱신.
+
+```ts
+AutoUpdate.runByExternalStorage(opt: {
+  log: (messageHtml: string) => void;
+  dirPath: string;                  // external 스토리지 기준 상대 경로
+}): Promise<void>
+```
+외부 저장소 `external/<dirPath>` 폴더의 `<semver>.apk` 파일 중 가장 높은 버전을 골라 설치. 파일명이 semver 가 아니거나 없으면 조용히 반환.
+
+공통:
+- 현재 앱 버전(`ApkInstaller.getVersionInfo().versionName`) 보다 높은 버전만 설치.
+- semver 유효성 실패 시 업데이트 스킵.
+- 설치 권한이 없으면 설정 화면 이동 + "재시도" 버튼 HTML 을 `log` 로 표시하고 최대 5분 대기.
+- 설치 후 `_freezeApp()` 으로 무한 대기 — 호출측에서 별도 후속 처리 불필요.
+- `log` 인자에는 HTML 문자열이 전달됨 (innerHTML 로 렌더링하도록 구성할 것).
+
+## ApkInstaller
+
+`abstract class ApkInstaller` (static 메서드만). Capacitor 플러그인 `"ApkInstaller"` 래퍼. Web 환경에서는 알림만 표시 후 정상 반환.
+
+```ts
+ApkInstaller.checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>
+```
+`granted` = REQUEST_INSTALL_PACKAGES 승인 여부, `manifest` = AndroidManifest 에 권한 선언 여부. `manifest=false` 면 APK 재설치 필요.
+
+```ts
+ApkInstaller.requestPermissions(): Promise<void>
+```
+설정 화면으로 이동시켜 사용자에게 권한 요청. 사용자 응답을 await 하지 않으므로 호출측에서 polling 필요 (`checkPermissions` 반복).
+
+```ts
+ApkInstaller.install(apkUri: string): Promise<void>
+```
+`apkUri` 는 FileProvider 의 `content://` URI. `@simplysm/capacitor-plugin-file-system` 의 `FileSystem.getUri(path)` 로 변환해 전달.
+
+```ts
+ApkInstaller.getVersionInfo(): Promise<VersionInfo>
+```
+현재 설치된 앱 자체의 버전을 반환.
+
+## 타입
+
+```ts
+interface VersionInfo {
+  versionName: string;  // 예: "1.2.3"
+  versionCode: string;
+}
+
+interface ApkInstallerPlugin {
+  install(options: { uri: string }): Promise<void>;
+  checkPermissions(): Promise<{ granted: boolean; manifest: boolean }>;
+  requestPermissions(): Promise<void>;
+  getVersionInfo(): Promise<VersionInfo>;
+}
+```

package/claude/references/sd-simplysm14/apis/capacitor-plugin-file-system/README.md

@@ -0,0 +1,83 @@
+# @simplysm/capacitor-plugin-file-system
+
+Capacitor 기반 파일 시스템 접근 플러그인. Android(11+ MANAGE_EXTERNAL_STORAGE, 10- READ/WRITE_EXTERNAL_STORAGE) 네이티브, Web 은 IndexedDB 에뮬레이션.
+
+## 사용 트리거 인덱스
+
+- **`FileSystem`** — 모바일/웹에서 파일·디렉토리 읽기/쓰기/삭제, 저장소 경로·URI 조회, 권한 처리 필요 시.
+- **`FileInfo`, `StorageType`** — `readdir` 결과 처리, `getStoragePath` 호출 시 타입.
+- **`FileSystemPlugin`** — 저수준 Capacitor 플러그인 인터페이스 직접 호출 필요 시(정상적으론 `FileSystem` 정적 메서드 사용).
+
+## FileSystem
+
+`abstract class` — 정적 메서드만 호출.
+
+```ts
+// 권한
+await FileSystem.checkPermissions(): Promise<boolean>
+await FileSystem.requestPermissions(): Promise<void>   // Android 11+: 설정 화면 이동, 10-: 권한 대화상자
+
+// 경로/URI
+await FileSystem.getStoragePath(type: StorageType): Promise<string>
+await FileSystem.getUri(filePath: string): Promise<string>   // FileProvider URI
+
+// 디렉토리
+await FileSystem.readdir(dirPath: string): Promise<FileInfo[]>
+await FileSystem.mkdir(targetPath: string): Promise<void>    // 재귀
+
+// 파일
+await FileSystem.writeFile(filePath: string, data: string | Bytes): Promise<void>
+await FileSystem.readFile(filePath: string): Promise<Bytes>
+await FileSystem.readFile(filePath: string, encoding: "utf8"): Promise<string>
+
+// 공통
+await FileSystem.remove(targetPath: string): Promise<void>   // 파일/디렉토리 재귀 삭제
+await FileSystem.exists(targetPath: string): Promise<boolean>
+```
+
+`writeFile`: `string` 은 utf8, `Bytes`(=`Uint8Array`, `@simplysm/core-common`) 는 base64 로 전달. cross-realm 안전.
+`readFile`: encoding 미지정 시 `Bytes`, `"utf8"` 지정 시 `string`.
+
+사용 예:
+
+```ts
+if (!(await FileSystem.checkPermissions())) await FileSystem.requestPermissions();
+const root = await FileSystem.getStoragePath("externalFiles");
+await FileSystem.mkdir(`${root}/logs`);
+await FileSystem.writeFile(`${root}/logs/a.txt`, "hello");
+const files = await FileSystem.readdir(`${root}/logs`);
+```
+
+## FileInfo / StorageType
+
+```ts
+interface FileInfo { name: string; isDirectory: boolean; }
+
+type StorageType =
+  | "external"        // 외부 저장소 루트 (Environment.getExternalStorageDirectory)
+  | "externalFiles"   // 앱 전용 외부 파일
+  | "externalCache"   // 앱 전용 외부 캐시
+  | "externalMedia"   // 앱 전용 외부 미디어
+  | "appData"         // 앱 데이터
+  | "appFiles"        // 앱 파일
+  | "appCache";       // 앱 캐시
+```
+
+## FileSystemPlugin
+
+저수준 Capacitor 인터페이스. `FileSystem` 의 모든 정적 메서드가 위임 대상. 직접 사용 시 `writeFile`/`readFile` 의 `encoding` 은 `"utf8" | "base64"`, `data` 는 항상 `string`.
+
+```ts
+interface FileSystemPlugin {
+  checkPermissions(): Promise<{ granted: boolean }>;
+  requestPermissions(): Promise<void>;
+  readdir(options: { path: string }): Promise<{ files: FileInfo[] }>;
+  getStoragePath(options: { type: StorageType }): Promise<{ path: string }>;
+  getUri(options: { path: string }): Promise<{ uri: string }>;
+  writeFile(options: { path: string; data: string; encoding?: "utf8" | "base64" }): Promise<void>;
+  readFile(options: { path: string; encoding?: "utf8" | "base64" }): Promise<{ data: string }>;
+  remove(options: { path: string }): Promise<void>;
+  mkdir(options: { path: string }): Promise<void>;
+  exists(options: { path: string }): Promise<{ exists: boolean }>;
+}
+```

package/claude/references/sd-simplysm14/apis/capacitor-plugin-intent/README.md

@@ -0,0 +1,80 @@
+# @simplysm/capacitor-plugin-intent
+
+Android 인텐트(브로드캐스트 송수신, 실행 인텐트 조회, startActivityForResult) Capacitor 플러그인. 산업용 디바이스 연동(바코드 스캐너, PDA 등) 용도. 웹 환경에서는 no-op + 경고 로그.
+
+## 사용 트리거 인덱스
+- **`Intent.subscribe` / `Intent.unsubscribeAll`** — 특정 액션 브로드캐스트 수신.
+- **`Intent.send`** — 외부 앱에 브로드캐스트 송신(예: DataWedge 트리거).
+- **`Intent.getLaunchIntent`** — 앱이 인텐트로 기동될 때 초기 데이터 조회.
+- **`Intent.addListener("newIntent", ...)` / `Intent.removeAllListeners`** — 앱 실행 중 새 인텐트 수신.
+- **`Intent.startActivityForResult`** — 외부 Activity 실행 후 결과 수신(결제·인증 모듈 등).
+- **`IntentResult` / `StartActivityForResultOptions` / `StartActivityForResultResult`** — 타입 정의.
+
+## Intent (abstract class, static only)
+
+### `subscribe(filters, callback) → Promise<() => Promise<void>>`
+`filters`: 수신할 action 문자열 배열. `callback`: 매 수신마다 호출. 반환값은 구독 해제 함수.
+```ts
+const unsub = await Intent.subscribe(
+  ["com.symbol.datawedge.api.RESULT_ACTION"],
+  (result) => console.log(result.extras),
+);
+await unsub();
+```
+
+### `unsubscribeAll() → Promise<void>`
+프로세스 내 모든 `subscribe` 구독 해제.
+
+### `send({ action, extras? }) → Promise<void>`
+브로드캐스트 송신.
+```ts
+await Intent.send({
+  action: "com.symbol.datawedge.api.ACTION",
+  extras: { "com.symbol.datawedge.api.SOFT_SCAN_TRIGGER": "TOGGLE_SCANNING" },
+});
+```
+
+### `getLaunchIntent() → Promise<IntentResult>`
+현재 앱을 실행시킨 인텐트의 action/extras 조회. 웹은 `{}` 반환.
+
+### `addListener("newIntent", callback) → Promise<PluginListenerHandle>`
+앱 실행 중 수신되는 새 인텐트(`onNewIntent`)에 대한 리스너 등록. `handle.remove()` 로 개별 해제.
+
+### `removeAllListeners() → Promise<void>`
+`addListener` 로 등록된 모든 리스너 제거.
+
+### `startActivityForResult(options) → Promise<StartActivityForResultResult>`
+외부 Activity 실행 후 결과 수신. `resultCode === -1` 이 `RESULT_OK`.
+```ts
+const result = await Intent.startActivityForResult({
+  action: "com.example.PAY",
+  extras: { amount: 1000 },
+});
+if (result.resultCode === -1) { /* OK */ }
+```
+
+## 타입
+
+### `IntentResult`
+- `action?: string` — 브로드캐스트 액션.
+- `extras?: Record<string, unknown>` — 추가 데이터.
+
+### `StartActivityForResultOptions`
+- `action?: string`
+- `uri?: string`
+- `extras?: Record<string, unknown>`
+- `type?: string` — MIME type.
+- `packageName?: string` — 특정 앱 지정.
+- `className?: string` — 특정 Activity 지정.
+- `flags?: number` — Intent flags.
+
+### `StartActivityForResultResult`
+- `resultCode: number` — Android `RESULT_*` 코드 (`-1` = OK, `0` = CANCELED).
+- `data?: { action?: string; uri?: string; extras?: Record<string, unknown> }`
+
+### `IntentPlugin`
+저수준 Capacitor 플러그인 인터페이스. 일반적으로 직접 사용하지 않고 `Intent` static API 사용. 커스텀 래핑이 필요할 때만 참조.
+
+## 플랫폼 동작
+- Android: 네이티브 구현.
+- Web: 모든 변경 메서드(`subscribe`/`send`/`startActivityForResult`)는 `console.warn` 후 stub 값 반환. `getLaunchIntent`/`unsubscribe*` 는 조용히 no-op.

package/claude/references/sd-simplysm14/apis/capacitor-plugin-usb-storage/README.md

@@ -0,0 +1,39 @@
+# @simplysm/capacitor-plugin-usb-storage
+
+USB Mass Storage 접근용 Capacitor 플러그인 (Android: libaums, Browser: IndexedDB 가상 USB 에뮬레이션).
+
+## 사용 트리거 인덱스
+
+- **`UsbStorage`** — 정적 메서드로 장치 목록·권한·디렉토리·파일 읽기. USB 저장 장치에서 데이터를 가져올 때.
+- **`UsbDeviceInfo` / `UsbDeviceFilter` / `UsbFileInfo`** — 인자·반환 타입. 호출부 타입 선언에.
+- **`UsbStoragePlugin`** — 원시 Capacitor 플러그인 인터페이스. `UsbStorage` 래퍼로 충분하면 직접 사용 X.
+
+## UsbStorage
+
+모든 메서드 `static async`. 장치 식별은 `{ vendorId, productId }` (`UsbDeviceFilter`)로 한다.
+
+```ts
+import { UsbStorage } from "@simplysm/capacitor-plugin-usb-storage";
+
+const devices = await UsbStorage.getDevices();                 // UsbDeviceInfo[]
+const filter = { vendorId: devices[0].vendorId, productId: devices[0].productId };
+
+if (!(await UsbStorage.checkPermissions(filter))) {
+  if (!(await UsbStorage.requestPermissions(filter))) return;  // boolean
+}
+
+const files = await UsbStorage.readdir(filter, "/");           // UsbFileInfo[]
+const data = await UsbStorage.readFile(filter, "/a.txt");      // Bytes | undefined
+```
+
+- `getDevices()` — 연결된 USB 장치 전체 반환.
+- `requestPermissions(filter)` / `checkPermissions(filter)` — 권한 승인/보유 여부 `boolean`.
+- `readdir(filter, dirPath)` — 디렉토리 항목 목록 (`name`, `isDirectory`).
+- `readFile(filter, filePath)` — 파일 바이트. 없으면 `undefined`. 내부에서 base64 → `Bytes`(@simplysm/core-common) 변환.
+
+## 타입
+
+- `UsbDeviceInfo` — `deviceName`, `manufacturerName`, `productName`, `vendorId`, `productId`.
+- `UsbDeviceFilter` — `vendorId`, `productId`.
+- `UsbFileInfo` — `name`, `isDirectory`.
+- `UsbStoragePlugin` — Capacitor `registerPlugin` 원시 인터페이스. 메서드 반환이 `{ devices }`/`{ granted }`/`{ files }`/`{ data: string | null }` 형태의 base64 raw 응답.