u

2026-10-14 03:07:21 +02:00
parent 1991c0b529
commit 6c821d381e
10 changed files with 607 additions and 124 deletions
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -89,7 +89,8 @@ Generated from `@openapi` annotations in [`src/api/routes/`](../../src/api/route
 | [`routes/auth/me.md`](routes/auth/me.md) | `GET /auth/me` |
 | [`routes/auth/selected-company.md`](routes/auth/selected-company.md) | `PUT /auth/selected-company` |
 | [`routes/backup.md`](routes/backup.md) | `GET /backup` |
-| [`routes/backup/run.md`](routes/backup/run.md) | `POST /backup/run` |
+| [`routes/backup/_id/vfs.md`](routes/backup/_id/vfs.md) | `GET /backup/{id}/vfs` |
+| [`routes/backup/_id/vfs/recover.md`](routes/backup/_id/vfs/recover.md) | `POST /backup/{id}/vfs/recover` |
 | [`routes/brand/list.md`](routes/brand/list.md) | `GET /brand` |
 | [`routes/brand/create.md`](routes/brand/create.md) | `POST /brand` |
 | [`routes/brand/delete.md`](routes/brand/delete.md) | `DELETE /brand/{id}` |
--- a/docs/api/routes-all.md
+++ b/docs/api/routes-all.md
@@ -1,6 +1,6 @@
 # Dash API Routes Overview (All)

-Overview of all 232 API endpoints across all modules.
+Overview of all 233 API endpoints across all modules.

 ### Notation

@@ -17,7 +17,7 @@ Params: path values first, then `query:` and `body:` (`body?` = optional body).
 - `T6` = `{ id: int, number: str, type: str, supplierId: int|null, date: str, lines: T28[], files: T13[], externalNumber?: str|null, createdAt?: str, ledger?: T50 }`
 - `T7` = `{ id: int, number: str, type: str, date: str, lines: T28[], shippings: T36[], entityId?: int|null, externalNumber?: str|null, createdAt?: str|null, lineCount?: int, packageCount?: int }`
 - `T8` = `{ name: str, path: str, totalSizeBytes: int, timestamp: str|null, manifest?: T9|null }`
- `T9` = `{ id: str, timestamp: str, dateKey: str, monthKey: str, dbProvider: str, manual: bool, files: T17, totalSizeBytes: int, durationMs: int }`
+- `T9` = `{ id: str, timestamp: str, dateKey: str, monthKey: str, dbProvider: str, files: T17, totalSizeBytes: int, durationMs: int }`
 - `T10` = `{ labeltemplate: T11 }`
 - `T11` = `{ id: int, name: str, width: num, height: num, dpi: int, type: str, content: T24, thumb?: str|null }`
 - `T12` = `{ quote: T15 }`
@@ -259,9 +259,12 @@ _none_
 #### List backups and service status — `GET /backup`
 _none_
 - Returns: `200 { status: { enabled: bool, isRunning: bool, dbProvider: str, mssqlWarning: bool, backupDir: str, retention: { hourlyMax: int, dailyMax: int, monthly: str }, counts: { hourly: int, daily: int, monthly: int }, latestHourly?: T8|null, latestDaily?: T8|null, latestMonthly?: T8|null }, backups: { counts: { hourly: int, daily: int, monthly: int }, hourly: T8[], daily: T8[], monthly: T8[] } }`
-#### Trigger manual backup — `POST /backup/run`
-_none_
- Returns: `200 { success: bool, id: str, timestamp: str, promotedDaily: bool, promotedMonthly: bool, totalSizeBytes: int, pruneResult: { hourlyPruned: int, dailyPruned: int }, manifest: T9 }`
+#### List VFS files in a backup — `GET /backup/{id}/vfs`
+- Params: `id: str, query: companyId?: int`
+- Returns: `200 { backupId: str, companyId: int, files: { name: str, size: int, mime: str, mtime: str }[] }`
+#### Recover VFS file from a backup — `POST /backup/{id}/vfs/recover`
+- Params: `id: str, body: { path: str, companyId?: int }`
+- Returns: `200 { success: bool, backupId: str, companyId: int, path: str, sizeBytes: int, mime: str }`

 ### Section: /brand

--- a/docs/api/routes/backup.md
+++ b/docs/api/routes/backup.md
@@ -39,7 +39,6 @@ Backup service status and listing
        "dateKey": "…",
        "monthKey": "…",
        "dbProvider": "…",
-        "manual": true,
        "files": {
          "vfs": {
            "name": "…",
@@ -73,7 +72,6 @@ Backup service status and listing
        "dateKey": "…",
        "monthKey": "…",
        "dbProvider": "…",
-        "manual": true,
        "files": {
          "vfs": {
            "name": "…",
@@ -107,7 +105,6 @@ Backup service status and listing
        "dateKey": "…",
        "monthKey": "…",
        "dbProvider": "…",
-        "manual": true,
        "files": {
          "vfs": {
            "name": "…",
@@ -149,7 +146,6 @@ Backup service status and listing
          "dateKey": "…",
          "monthKey": "…",
          "dbProvider": "…",
-          "manual": true,
          "files": {
            "vfs": {
              "name": "…",
@@ -185,7 +181,6 @@ Backup service status and listing
          "dateKey": "…",
          "monthKey": "…",
          "dbProvider": "…",
-          "manual": true,
          "files": {
            "vfs": {
              "name": "…",
@@ -221,7 +216,6 @@ Backup service status and listing
          "dateKey": "…",
          "monthKey": "…",
          "dbProvider": "…",
-          "manual": true,
          "files": {
            "vfs": {
              "name": "…",
--- a/docs/api/routes/backup/_id/vfs.md
+++ b/docs/api/routes/backup/_id/vfs.md
@@ -0,0 +1,51 @@
+# `GET /backup/{id}/vfs`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+List VFS files in a backup
+
+Lists all virtual filesystem (VFS) files stored for the authorized company inside a specific backup archive.
+
+## Path parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `id` | yes | string | Backup identifier (e.g. backup-2026-10-14_02-00-00, backup-2026-10-14, backup-2026-10) |
+
+## Query parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `companyId` | no | integer | Optional company ID to inspect (defaults to user's selected company) |
+
+## Response `200`
+
+List of VFS files in the backup for the authorized company
+
+```json
+{
+  "backupId": "…",
+  "companyId": 1,
+  "files": [
+    {
+      "name": "…",
+      "size": 1,
+      "mime": "…",
+      "mtime": "2026-08-10T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | No company selected or invalid companyId — `{"error":"…"}` |
+| 403 | Not authorized for the requested company — `{"error":"…"}` |
+| 404 | Backup or VFS archive not found — `{"error":"…"}` |
+| 500 | Internal server error — `{"error":"…"}` |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._
--- a/docs/api/routes/backup/_id/vfs/recover.md
+++ b/docs/api/routes/backup/_id/vfs/recover.md
@@ -0,0 +1,55 @@
+# `POST /backup/{id}/vfs/recover`
+
+Protected. Requires a valid session cookie (`credentials: 'include'`).
+
+Recover VFS file from a backup
+
+Recovers a specific virtual filesystem (VFS) file from a backup archive into the active VFS directory for the authorized company.
+
+## Path parameters
+
+| Param | Required | Type | Description |
+|-------|----------|------|-------------|
+| `id` | yes | string | Backup identifier (e.g. backup-2026-10-14_02-00-00, backup-2026-10-14, backup-2026-10) |
+
+## Body (JSON)
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `path` | yes | string | Relative path of the VFS file to recover |
+| `companyId` | no | integer | Optional company ID (defaults to user's selected company) |
+
+```json
+{
+  "path": "…",
+  "companyId": 1
+}
+```
+
+## Response `200`
+
+VFS file recovered successfully
+
+```json
+{
+  "success": true,
+  "backupId": "…",
+  "companyId": 1,
+  "path": "…",
+  "sizeBytes": 1,
+  "mime": "…"
+}
+```
+
+## Errors
+
+| Status | Description |
+|--------|-------------|
+| 400 | Validation error or path escapes boundary — `{"error":"…"}` |
+| 403 | Not authorized for the company — `{"error":"…"}` |
+| 404 | Backup or file not found — `{"error":"…"}` |
+| 500 | Internal server error — `{"error":"…"}` |
+
+---
+
+_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._
--- a/docs/api/routes/backup/run.md
+++ b/docs/api/routes/backup/run.md
@@ -1,64 +0,0 @@
-# `POST /backup/run`
-
-Protected. Requires a valid session cookie (`credentials: 'include'`).
-
-Trigger manual backup
-
-Immediately triggers an on-demand backup snapshot of VFS, storage, and SQLite database.
-
-## Response `200`
-
-Backup triggered successfully
-
-```json
-{
-  "success": true,
-  "id": "…",
-  "timestamp": "2026-08-10T00:00:00.000Z",
-  "promotedDaily": true,
-  "promotedMonthly": true,
-  "totalSizeBytes": 1,
-  "pruneResult": {
-    "hourlyPruned": 1,
-    "dailyPruned": 1
-  },
-  "manifest": {
-    "id": "…",
-    "timestamp": "2026-08-10T00:00:00.000Z",
-    "dateKey": "…",
-    "monthKey": "…",
-    "dbProvider": "…",
-    "manual": true,
-    "files": {
-      "vfs": {
-        "name": "…",
-        "sizeBytes": 1,
-        "sourceExists": true
-      },
-      "storage": {
-        "name": "…",
-        "sizeBytes": 1,
-        "sourceExists": true
-      },
-      "database": {
-        "name": "…",
-        "sizeBytes": 1,
-        "backedUp": true,
-        "reason": "…"
-      }
-    },
-    "totalSizeBytes": 1,
-    "durationMs": 1
-  }
-}
-```
-
-## Errors
-
-| Status | Description |
-|--------|-------------|
-| 500 | Backup execution failure — `{"error":"…"}` |
-
---
-
-_Generated from `@openapi` JSDoc. Do not edit by hand — run `npm run docs:api`._