@simplysm/sd-claude 14.0.50 → 14.0.52

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/README.md

@@ -0,0 +1,38 @@
+# @simplysm/capacitor-plugin-auto-update
+
+> Android APK 자동 업데이트 플러그인. 서버 버전 비교 후 APK 다운로드·설치를 처리하며, 외부 저장소(USB 등)에서도 업데이트할 수 있다. Capacitor 7 기반이며 `@capacitor/core`가 peerDependency다.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-auto-update
+```
+
+피어 의존성으로 `@capacitor/core ^7`이 필요하다. Android 네이티브 플러그인이 포함되어 있으므로 `npx cap sync` 후 사용한다.
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 서버에서 최신 APK 자동 업데이트 | [auto-update.md](./auto-update/auto-update.md) |
+| 외부 저장소(USB)에서 APK 업데이트 | [auto-update.md](./auto-update/auto-update.md) |
+| APK 설치 권한 관리 및 직접 설치 | [apk-installer.md](./apk-installer/apk-installer.md) |
+
+## API Overview
+
+### APK 설치
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`ApkInstaller`](./apk-installer/apk-installer.md) | abstract class | `AutoUpdate` 없이 APK 설치 권한·설치를 직접 제어할 때 |
+
+### 자동 업데이트
+
+| Entry | Kind | 언제 쓰나 |
+|-------|------|-----------|
+| [`AutoUpdate`](./auto-update/auto-update.md) | abstract class | 앱 부트스트랩 시 서버 또는 외부 저장소에서 최신 버전을 확인하고 APK를 설치할 때 |
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- iOS 앱 업데이트 → App Store 메커니즘을 사용한다. 이 플러그인은 Android APK 전용이다.
+- 웹 앱 업데이트 → 서버 배포로 처리한다. 브라우저 폴백은 알림만 표시하고 실제 설치를 수행하지 않는다.

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/apk-installer/apk-installer.md

@@ -0,0 +1,115 @@
+# `ApkInstaller`
+
+APK 설치 플러그인 정적 파사드 클래스. Android에서 APK 설치 권한 확인·요청, APK 설치 인텐트 실행, 앱 버전 정보 조회를 제공한다.
+
+## When to use
+
+- ✅ `AutoUpdate`를 사용하지 않고 APK 설치 흐름을 직접 제어할 때
+- ✅ 앱의 현재 버전 정보(`versionName`, `versionCode`)를 조회할 때
+- ❌ 서버 또는 외부 저장소에서 자동 업데이트 → [`AutoUpdate`](../auto-update/auto-update.md) — 버전 비교·다운로드·설치를 모두 처리한다
+
+## Signature
+
+```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>;
+}
+```
+
+## Members
+
+| Member | Kind | Return | Description |
+|--------|------|--------|-------------|
+| `checkPermissions` | static method | `Promise<{ granted: boolean; manifest: boolean }>` | 설치 권한 승인 여부(`granted`)와 AndroidManifest 선언 여부(`manifest`) 동시 확인. `manifest: false`이면 APK를 재설치해야 한다. |
+| `requestPermissions` | static method | `Promise<void>` | `REQUEST_INSTALL_PACKAGES` 권한 요청. 시스템 설정 화면으로 이동하므로 이후 `checkPermissions`로 결과를 폴링해야 한다. |
+| `install` | static method | `Promise<void>` | `content://` URI(FileProvider URI)로 APK 설치 인텐트 실행. `FileSystem.getUri(filePath)`로 URI를 얻는다. |
+| `getVersionInfo` | static method | `Promise<VersionInfo>` | 현재 설치된 앱의 버전 정보 조회. 브라우저 환경에서는 `env("__VER__") ?? "0.0.0"`을 `versionName`으로 반환한다. |
+
+**브라우저 폴백 동작:**
+- `install()` — `alert()` 메시지 표시 후 반환
+- `checkPermissions()` — 항상 `{ granted: true, manifest: true }` 반환
+- `requestPermissions()` — 무동작
+- `getVersionInfo()` — `versionName: env("__VER__") ?? "0.0.0"`, `versionCode: "0"` 반환
+
+## Usage
+
+### 최소 예제
+
+```typescript
+import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
+
+const versionInfo = await ApkInstaller.getVersionInfo();
+// versionInfo.versionName → "1.2.3"
+// versionInfo.versionCode → "42"
+```
+
+### 전형 예제
+
+```typescript
+import { ApkInstaller } from "@simplysm/capacitor-plugin-auto-update";
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+// 1. 권한 확인
+const { granted, manifest } = await ApkInstaller.checkPermissions();
+if (!manifest) {
+  // AndroidManifest.xml에 REQUEST_INSTALL_PACKAGES 미선언 → APK 재설치 필요
+  throw new Error("앱을 재설치해야 합니다.");
+}
+if (!granted) {
+  await ApkInstaller.requestPermissions();
+  // 시스템 설정 화면으로 이동하므로, 복귀 후 다시 checkPermissions()로 확인해야 한다
+}
+
+// 2. APK 설치 (filePath는 FileSystem으로 저장한 경로)
+const apkUri = await FileSystem.getUri("/path/to/latest.apk");
+await ApkInstaller.install(apkUri);
+```
+
+## 🚫 Anti-patterns
+
+### `install()`에 파일 경로를 직접 전달
+
+```typescript
+// ❌ 파일 시스템 경로를 직접 전달
+await ApkInstaller.install("/path/to/latest.apk");
+
+// ✅ FileSystem.getUri()로 content:// URI를 얻어서 전달
+const uri = await FileSystem.getUri("/path/to/latest.apk");
+await ApkInstaller.install(uri);
+```
+
+**근거**: Android에서 APK 설치 인텐트는 `content://` URI(FileProvider)를 요구한다. 파일 경로를 직접 전달하면 보안 예외가 발생한다.
+
+## Related Types
+
+### `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>;
+}
+```

package/claude/references/sd-simplysm-v14/capacitor-plugin-auto-update/auto-update/auto-update.md

@@ -0,0 +1,113 @@
+# `AutoUpdate`
+
+자동 업데이트 오케스트레이터. 서버 또는 외부 저장소에서 최신 APK를 확인하고 설치한다. 모든 메서드가 `static`이며 인스턴스화하지 않는다.
+
+## When to use
+
+- ✅ 앱 부트스트랩 시 서버에서 최신 APK를 자동 다운로드·설치할 때 → `run()`
+- ✅ 네트워크 없이 외부 저장소(USB 등)에서 APK를 업데이트할 때 → `runByExternalStorage()`
+- ❌ APK 설치 권한만 확인하거나 설치만 직접 수행 → [`ApkInstaller`](../apk-installer/apk-installer.md)
+
+## Signature
+
+```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>;
+}
+```
+
+## Members
+
+| Member | Kind | Description |
+|--------|------|-------------|
+| `run` | static method | `AutoUpdateService.getLastVersion("android")`로 서버에서 최신 버전 정보를 조회한 뒤, 현재 버전보다 높으면 APK를 다운로드하여 설치한다. 업데이트 후 앱을 무한 대기 상태로 전환한다. |
+| `runByExternalStorage` | static method | 외부 저장소의 `opt.dirPath` 디렉토리에서 숫자와 점으로만 구성된 이름의 `.apk` 파일(예: `1.2.3.apk`) 중 최신 semver 버전을 찾아 설치한다. |
+
+## Parameters
+
+### `run` opt
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `log` | `(messageHtml: string) => void` | 진행 상황 HTML을 받아 사용자에게 표시하는 콜백. 버튼 등 인터랙티브 HTML이 포함될 수 있다. |
+| `serviceClient` | `ServiceClient` | `@simplysm/service-client`의 `ServiceClient` 인스턴스. 서버에서 버전 정보를 조회하는 데 사용된다. |
+
+### `runByExternalStorage` opt
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `log` | `(messageHtml: string) => void` | 진행 상황 HTML을 받아 사용자에게 표시하는 콜백. |
+| `dirPath` | `string` | 외부 저장소 루트(`FileSystem.getStoragePath("external")`) 기준 상대 경로. 해당 경로에 `1.2.3.apk` 형식 파일이 있어야 한다. |
+
+## 동작 설명
+
+**권한 처리**: 두 메서드 모두 내부적으로 `ApkInstaller.checkPermissions()`를 호출한다.
+- `manifest: false` → 재설치 에러를 throw하고 앱을 무한 대기로 전환한다.
+- `granted: false` → 권한 요청 후 최대 300초(1초 간격)간 승인을 폴링한다.
+
+**버전 비교**: `semver` 라이브러리를 사용한다. `versionName`이 유효한 semver 형식이 아니면 업데이트 확인을 건너뛴다.
+
+**업데이트 후 동작**: 업데이트가 실행되면 `new Promise(() => {})` 무한 대기로 전환된다. 사용자가 앱을 재시작해야 새 버전이 적용된다. 업데이트가 필요 없을 때만 정상 반환한다.
+
+**에러 처리**: `try/catch`로 전체를 감싸며, 에러 발생 시 `opt.log()`로 HTML 에러 메시지를 표시한 뒤 무한 대기로 전환한다.
+
+**`run` APK 저장 경로**: `FileSystem.getStoragePath("appCache")`에 `latest.apk`로 저장한다.
+
+## Usage
+
+### 최소 예제 — 서버 기반 자동 업데이트
+
+앱 부트스트랩 시 호출한다. 업데이트가 없으면 정상 반환, 업데이트가 있으면 무한 대기로 전환된다.
+
+```typescript
+import { AutoUpdate } from "@simplysm/capacitor-plugin-auto-update";
+import type { ServiceClient } from "@simplysm/service-client";
+
+await AutoUpdate.run({
+  log: (messageHtml) => {
+    document.getElementById("status")!.innerHTML = messageHtml;
+  },
+  serviceClient, // 이미 연결된 ServiceClient 인스턴스
+});
+// 이 줄에 도달하면 업데이트가 불필요한 것이다.
+```
+
+### 전형 예제 — 외부 저장소(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", // 외부 저장소 루트 기준 상대 경로
+});
+```
+
+## 🚫 Anti-patterns
+
+### `run()` 반환 후 업데이트 완료를 기대
+
+```typescript
+// ❌ run() 반환 후 "업데이트 완료" 처리
+await AutoUpdate.run({ log, serviceClient });
+showMessage("업데이트 완료!"); // 업데이트 시에는 이 줄에 도달하지 않음
+
+// ✅ run()이 반환하면 업데이트가 불필요한 것
+await AutoUpdate.run({ log, serviceClient });
+// 정상적으로 앱 초기화 계속
+initApp();
+```
+
+**근거**: 업데이트가 실행되면 APK 설치 후 `_freezeApp()`으로 무한 대기에 진입한다. `run()`이 정상 반환하는 경우는 업데이트가 필요 없을 때뿐이다.

package/claude/references/sd-simplysm-v14/capacitor-plugin-file-system/README.md

@@ -0,0 +1,197 @@
+# @simplysm/capacitor-plugin-file-system
+
+> Capacitor 파일 시스템 접근 플러그인. Android에서 외부 저장소 전체 접근 및 앱 전용 디렉토리 접근을 제공하며, 브라우저 환경에서는 IndexedDB 기반 가상 파일 시스템으로 에뮬레이션한다. `@capacitor/core ^7` peerDependency.
+
+## Installation
+
+```bash
+npm install @simplysm/capacitor-plugin-file-system
+```
+
+## 하려는 작업 → 먼저 읽을 파일
+
+| 작업 | 먼저 읽을 파일 |
+|------|----------------|
+| 파일 읽기/쓰기/삭제 | 이 문서의 `FileSystem` 섹션 |
+| 저장소 경로 조회 | 이 문서의 `StorageType` 섹션 |
+| APK 자동 업데이트에서 파일 저장 | [`capacitor-plugin-auto-update`](../capacitor-plugin-auto-update/README.md) |
+
+## API Overview
+
+### `FileSystem`
+
+파일 시스템 접근 파사드 클래스. 모든 API는 정적 메서드로 제공된다.
+
+#### When to use
+
+- ✅ Android 앱에서 파일 읽기/쓰기/삭제, 디렉토리 탐색이 필요할 때
+- ✅ `content://` URI(FileProvider)를 얻어 다른 앱에 파일을 전달할 때
+- ❌ USB 저장 장치 접근 → [`@simplysm/capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md)
+
+#### Signature
+
+```typescript
+export abstract class FileSystem {
+  static async checkPermissions(): Promise<boolean>;
+  static async requestPermissions(): Promise<void>;
+  static async readdir(dirPath: string): Promise<FileInfo[]>;
+  static async getStoragePath(type: StorageType): Promise<string>;
+  static async getUri(filePath: string): Promise<string>;
+  static async writeFile(filePath: string, data: string | Bytes): Promise<void>;
+  static async readFile(filePath: string): Promise<Bytes>;
+  static async readFile(filePath: string, encoding: "utf8"): Promise<string>;
+  static async remove(targetPath: string): Promise<void>;
+  static async mkdir(targetPath: string): Promise<void>;
+  static async exists(targetPath: string): Promise<boolean>;
+}
+```
+
+#### Members
+
+| Member | Kind | Signature | Description |
+|--------|------|-----------|-------------|
+| `checkPermissions` | static method | `() => Promise<boolean>` | 파일 시스템 접근 권한 확인. 웹에서는 항상 `true` |
+| `requestPermissions` | static method | `() => Promise<void>` | 파일 시스템 접근 권한 요청. Android 11+: 설정 화면 이동, Android 10-: 권한 대화상자 |
+| `readdir` | static method | `(dirPath: string) => Promise<FileInfo[]>` | 디렉토리 파일/폴더 목록 조회 |
+| `getStoragePath` | static method | `(type: StorageType) => Promise<string>` | 저장소 유형별 절대 경로 조회 |
+| `getUri` | static method | `(filePath: string) => Promise<string>` | 파일 URI 조회. Android: `content://` FileProvider URI, 웹: `blob:` URL |
+| `writeFile` | static method | `(filePath: string, data: string \| Bytes) => Promise<void>` | 파일 쓰기. `string`이면 UTF-8, `Bytes`이면 Base64 중간 포맷으로 전달 |
+| `readFile` | static method | 오버로드 2개 | 파일 읽기. `encoding` 생략 시 `Bytes` 반환, `"utf8"` 지정 시 `string` 반환 |
+| `remove` | static method | `(targetPath: string) => Promise<void>` | 파일/디렉토리 재귀 삭제 |
+| `mkdir` | static method | `(targetPath: string) => Promise<void>` | 디렉토리 재귀 생성. 이미 존재하면 무동작 |
+| `exists` | static method | `(targetPath: string) => Promise<boolean>` | 파일/디렉토리 존재 여부 확인 |
+
+#### Usage
+
+##### 최소 예제
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const appFilesPath = await FileSystem.getStoragePath("appFiles");
+await FileSystem.writeFile(appFilesPath + "/hello.txt", "Hello!");
+const content = await FileSystem.readFile(appFilesPath + "/hello.txt", "utf8");
+```
+
+##### 전형 예제 — 권한 확인 후 파일 읽기
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const hasPermission = await FileSystem.checkPermissions();
+if (!hasPermission) {
+  await FileSystem.requestPermissions();
+  // Android 11+에서는 설정 화면으로 이동하므로, 복귀 후 다시 확인해야 한다
+}
+
+const appFilesPath = await FileSystem.getStoragePath("appFiles");
+const exists = await FileSystem.exists(appFilesPath + "/config.json");
+if (exists) {
+  const content = await FileSystem.readFile(appFilesPath + "/config.json", "utf8");
+}
+```
+
+##### 전형 예제 — Bytes 데이터 쓰기/읽기
+
+```typescript
+import { FileSystem } from "@simplysm/capacitor-plugin-file-system";
+
+const appCachePath = await FileSystem.getStoragePath("appCache");
+const data = new Uint8Array([0x89, 0x50, 0x4e, 0x47]); // PNG header 예시
+await FileSystem.writeFile(appCachePath + "/image.png", data);
+
+// Bytes(Uint8Array)로 반환
+const readData = await FileSystem.readFile(appCachePath + "/image.png");
+```
+
+#### 🚫 Anti-patterns
+
+##### 웹에서 `getUri()` 반환값을 해제하지 않음
+
+```typescript
+// ❌ Blob URL 미해제 → 메모리 누수
+const uri = await FileSystem.getUri(filePath);
+img.src = uri;
+
+// ✅ 사용 후 반드시 해제
+const uri = await FileSystem.getUri(filePath);
+img.src = uri;
+img.onload = () => {
+  URL.revokeObjectURL(uri);
+};
+```
+
+**근거**: 웹 환경에서 `getUri()`는 `blob:` URL을 생성한다. `URL.revokeObjectURL()`로 해제하지 않으면 페이지가 살아있는 동안 메모리에 남는다.
+
+---
+
+### `StorageType`
+
+저장소 유형을 나타내는 union type.
+
+```typescript
+export type StorageType =
+  | "external"
+  | "externalFiles"
+  | "externalCache"
+  | "externalMedia"
+  | "appData"
+  | "appFiles"
+  | "appCache";
+```
+
+**선택 가이드:**
+
+| Type | Android 경로 | 웹 경로 | 설명 |
+|------|--------------|---------|------|
+| `external` | `Environment.getExternalStorageDirectory()` | `/webfs/external` | 외부 저장소 루트 (공유 저장소, 권한 필요) |
+| `externalFiles` | `getExternalFilesDir(null)` | `/webfs/externalFiles` | 앱 전용 외부 파일 |
+| `externalCache` | `externalCacheDir` | `/webfs/externalCache` | 앱 전용 외부 캐시 |
+| `externalMedia` | `externalMediaDirs[0]` | `/webfs/externalMedia` | 앱 전용 외부 미디어 |
+| `appData` | `applicationInfo.dataDir` | `/webfs/appData` | 앱 데이터 (내부, 자동 백업 대상) |
+| `appFiles` | `filesDir` | `/webfs/appFiles` | 앱 파일 (내부) |
+| `appCache` | `cacheDir` | `/webfs/appCache` | 앱 캐시 (내부, 시스템이 삭제 가능) |
+
+---
+
+### `FileInfo`
+
+파일 또는 디렉토리 정보 인터페이스. `FileSystem.readdir()`의 반환 타입 요소이다.
+
+```typescript
+export interface FileInfo {
+  name: string;
+  isDirectory: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | 파일 또는 디렉토리 이름 (경로 제외, 확장자 포함) |
+| `isDirectory` | `boolean` | `true`이면 디렉토리, `false`이면 파일 |
+
+---
+
+### `FileSystemPlugin`
+
+Capacitor 네이티브 플러그인 인터페이스. 직접 사용하지 않고 `FileSystem` 파사드를 통해 접근한다. 타입 참조 목적으로만 export된다.
+
+```typescript
+export 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 }>;
+}
+```
+
+## 이 패키지를 쓰지 말아야 할 때
+
+- USB Mass Storage 장치 접근 → [`@simplysm/capacitor-plugin-usb-storage`](../capacitor-plugin-usb-storage/README.md)
+- 웹 전용 파일 다운로드 → 브라우저 `fetch()` + `Blob` 사용