# 維護 API 契約

資料庫/deploy 模組輸出 `rg_maintenance_routes(string $method, string $path, array $data): bool`。父代理的 front controller 先載入 `bootstrap.php`，再把相對於 `/api/garage` 的 path 交給各模組；不符合本文件兩個 path 時回傳 `false`。

## `GET /admin/backup`

此端點要求 owner 管理員與 `rg_require_origin()`。成功回傳一個 JSON object：

```json
{
  "format": "ruiou-garage-business-backup",
  "version": 1,
  "exportedAt": "2026-11-19T00:00:00+00:00",
  "tables": {
    "garage_settings": [],
    "garage_services": [],
    "garage_vehicles": [],
    "garage_vehicle_photos": [],
    "garage_appointments": [],
    "garage_valuations": [],
    "garage_valuation_photos": [],
    "garage_inquiries": [],
    "garage_telegram_notifications": [],
    "garage_telegram_control": []
  },
  "storage": {
    "databaseBytes": 0,
    "databaseLimitBytes": 20971520,
    "databaseUsagePercent": 0
  }
}
```

`tables` 內每個列的欄位與 `database/schema.sql` 相同。照片只包含 URL 或 private relative `filePath` metadata，不包含 data URI、base64、BLOB 或檔案內容。管理員、session、CSRF、owner binding、rate limit、audit、DB credentials 和 Telegram secrets 不會進入 backup。

## `POST /admin/restore`

此端點要求 owner、`rg_require_origin()` 和 `rg_require_csrf()`。request 必須符合：

```json
{
  "confirm": "RESTORE",
  "backup": {
    "format": "ruiou-garage-business-backup",
    "version": 1,
    "tables": {
      "garage_settings": [],
      "garage_services": [],
      "garage_vehicles": [],
      "garage_vehicle_photos": [],
      "garage_appointments": [],
      "garage_valuations": [],
      "garage_valuation_photos": [],
      "garage_inquiries": [],
      "garage_telegram_notifications": [],
      "garage_telegram_control": []
    }
  }
}
```

`tables` 必須完整包含上述十個表，不能混入帳號、session、CSRF 或任意表名。模組會檢查列數、欄位集合、ID 長度、日期、照片 URL、private path、MIME、JSON payload、車輛 `sourceCategory`/`status` 一致性和 data URI；不符合時回傳 422，不執行刪除。restore 只替換業務表，使用 PDO prepared statements 和 transaction；帳號/秘密表不會被覆蓋。`confirm` 只是第二道明確確認，不取代 owner、origin 或 CSRF。

restore 不會依照任何 payload URL 發出 HTTP request，也不會把輸入 path 傳給 include、require 或檔案寫入函式，因此不提供 SSRF 或任意檔案覆蓋能力。估價照片檔案不在 JSON backup 中；FTP/File Manager 備份和還原 `private/storage/private-photos/` 是獨立的操作。若資料庫 payload 仍含 inline image，backup/restore 會拒絕，必須先透過私有照片上傳流程完成磁碟化。

## 前端相容性說明

現有 `BackupPanel` 的下載請求不需要 body，restore 送 `{ backup, confirm: "RESTORE" }`，與本契約一致。前端可繼續把 backup JSON 當成下載檔。restore 是「以檔案內容取代業務資料」而非 merge；UI 必須保留勾選和輸入 `RESTORE` 的雙重確認。由於 credentials 明確排除，還原後管理員登入資料仍是目前資料庫中的 PHP owner/account。

父代理目前的 `rg_body()` 對 JSON request body 使用 20 MiB 上限；前端檔案選擇器或提示文字不得把 45 MB 視為實際可接受的上限。容量接近 20 MiB 時，資料庫本身還會先由 `rg_capacity()` 以整個 cPanel database（包含既有 WordPress 表）計算後拒絕寫入。
