# Backup Manager

> Quan ly danh muc backup cua cac plugin, luu qua file-storage.

| | |
|---|---|
| Version | 1.0.1 |
| Category | Productivity |
| Permissions | network.localhost |
| Depends on | file-storage, ai-chat |

# Backup Manager

Quản lý danh mục backup của các plugin, lưu blob **qua plugin `file-storage`**. Backup
là kho lưu trữ / nguồn knowledge — KHÔNG restore ngược vào máy đang chạy.

**Type:** `backend`

## Cách hoạt động

- Backup 1 plugin = snapshot **settings** của nó (đọc qua `ctx.modules.pluginControl.getPluginSettingsFor`)
  + tùy chọn **extra files** trên đĩa do plugin nguồn cung cấp qua registry global
  `__kazuoPluginServices` (xem `references/plugin-runtime-api.md` mục 4d).
- Blob JSON: `{ formatVersion:1, sourcePluginId, createdAt, settings, extraFiles:[{relPath, contentBase64}] }`
  — base64, KHÔNG nén (MVP).
- Blob lưu **bắt buộc** qua file-storage: đọc `port`+`apiKey` từ settings file-storage (cross-plugin)
  rồi POST/GET/DELETE `http://127.0.0.1:<port>/files`. file-storage tắt/thiếu key → báo lỗi (fail-closed).
- **Retention**: sau mỗi backup giữ `maxBackupsPerPlugin` bản mới nhất mỗi `sourcePluginId` (mặc định 10),
  xóa bản cũ (cả blob + catalog).
- **Headless**: `globalThis.__kazuoPluginServices['backup-manager'].runBackup(spec)` = cùng lõi với IPC
  `create`, để cron-job (action `service`) chạy backup theo lịch mà không cần mở widget.

## IPC channels (`plugin:backup-manager:*`) — KHÔNG self-scope

Arg đầu luôn là `callerPluginId` (attribution). Plugin khác (ai-chat) gọi được.

| Channel | Args | Mô tả |
|---|---|---|
| `list` | `(caller, filter?{sourcePluginId})` | Danh mục backup (lọc theo plugin nguồn nếu có), mới nhất trước |
| `create` | `(caller, spec)` | Tạo backup ngay. `spec = { sourcePluginId, title?, desc?, includeSettings?, extraProvider?{pluginId,method} }` |
| `get` | `(caller, id)` | 1 entry hoặc null |
| `update` | `(caller, id, {title?,desc?})` | Sửa metadata |
| `delete` | `(caller, id)` | Xóa entry + blob trên file-storage |
| `get-content` | `(caller, id)` | Tải blob (object JSON) để dùng làm knowledge |

Broadcast `plugin:backup-manager:event` `{type:'backups-changed'}` sau mọi thay đổi.

## Default settings

- `backups` — default: `[]`
- `maxBackupsPerPlugin` — default: `10`

## Dependencies

`file-storage` (bắt buộc bật để lưu blob). Khai báo trong `manifest.json.dependencies` (chỉ kiểm ở cài đặt).

## Files

- `main/index.ts` — activate/deactivate, IPC CRUD, `performBackup`, registry global service
- `main/storage.ts` — upload/download/delete blob qua HTTP file-storage
- `widget.html` / `js/widget.js` / `css/widget.css` — danh mục backup (xem/sửa/xóa/xem nội dung)
- `settings.html` / `js/settings.js` — chỉnh `maxBackupsPerPlugin`
- `locales/en.json5` / `locales/vi.json5`

## Test

Plugin Manager → Install → Enable (cần bật cả `file-storage`). Sau khi sửa `main/*.ts`:
`npx tsc -p tsconfig.plugins.json` (từ project root).