feat(update): one-click in-app auto-update for the frozen build

The settings page could only link to the release zip for manual extract-and-
overwrite. Add a real self-update: the backend downloads the OS-matched release,
hands off to a detached OS-native helper that waits for this process to exit,
swaps the app files in place (leaving oasis.db/movies/ untouched), and relaunches
the backend; the UI polls /api/health and reconnects.

- backend/updater.py: download + generate/spawn sh/PowerShell helper, then exit
- POST /api/update/apply endpoint
- settings page "立即更新" button with download → restart → re-check flow,
  keeping a manual-download fallback for source checkouts / failures
- README: document both update paths

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fusion-labs-cc

README.md

@@ -86,6 +86,22 @@ chmod +x oasis-portal.sh
 
 ---
 
+## 🔄 軟體更新 (Updating)
+
+Oasis 有兩種更新方式，依你的安裝來源自動採用：
+
+- **原始碼版（`git clone` + 啟動腳本）**：`oasis-portal.sh` / `oasis-portal.ps1` 每次啟動時會自動 `git pull --ff-only` 拉取最新程式碼，無需手動操作（離線時會略過並沿用本機版本）。
+- **打包版（GitHub Releases 的 zip）**：到 **設定頁 → 關於與更新** 按「檢查更新」；若有新版本，按 **「立即更新」** 即可一鍵完成：
+  1. 後端下載對應你作業系統的最新 Release
+  2. 一支獨立的 helper 程序在後端關閉後就地抽換程式檔案
+  3. 後端自行重新啟動，網頁前端會自動重新連線
+
+  你的資料庫（`oasis.db`）與影片（`movies/`）不在更新包內，會**完整保留**。更新期間請避免有下載工作正在進行，以免檔案被占用。若一鍵更新失敗，仍可透過同區塊的「或手動下載」連結取得 zip，解壓縮覆蓋原資料夾即可。
+
+> 版本號來自 CI 建置時寫入的 `VERSION` 檔（發行的 git tag）；原始碼直接執行時會顯示為 `dev`，並被視為「永遠不落後」，因此不會被提示更新。
+
+---
+
 ## 🧩 站台 Adapter 設定 (Site Adapters)
 
 本工具是一個**通用的網頁讀取／下載引擎，本身不內建任何特定網站的定義**。要解析或下載某個網站，需由使用者自行提供一份該網站的「adapter」設定檔：

backend/api.py

@@ -163,6 +163,20 @@ def update_check():
     return version.check_for_update()
 
 
+@app.post('/api/update/apply')
+def update_apply():
+    """Download the latest release and swap it in, then relaunch the backend.
+
+    Sync `def` so FastAPI runs the (blocking) download in a threadpool. On
+    success the backend exits ~1.5s after responding while a detached helper
+    performs the file swap and relaunch, so the frontend should poll
+    /api/health and reconnect. Only meaningful for the frozen build; a source
+    checkout gets an error telling it to use git.
+    """
+    import updater
+    return updater.apply_update()
+
+
 @app.get('/api/supported-sites')
 def supported_sites():
     """List the sites the URL analyser currently supports (for the UI).

backend/updater.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Apply an in-app update for the frozen (PyInstaller onedir) build.
+
+The settings page can already *check* GitHub Releases (see version.py). This
+module performs the actual swap: download the new build's zip, then hand off to
+a small OS-native helper script that waits for this backend to exit, replaces
+the app files in place, and relaunches the new backend.
+
+Why a helper script and not plain Python:
+
+  * A running process cannot overwrite its own executable / loaded libraries
+    (hard error on Windows, and `_internal/` holds the frozen Python itself), so
+    the swap must happen *after* this process exits.
+  * The helper is OS-native (sh / PowerShell) so it can keep running once this
+    process is gone, and so extraction uses `ditto`/`unzip`/`Expand-Archive`,
+    which preserve the macOS bundle's symlinks and exec bits that Python's
+    zipfile would flatten.
+
+User data (oasis.db, movies/) lives next to the executable but is NOT part of
+the release zip, so the entry-by-entry swap leaves it untouched.
+
+Only meaningful for a frozen build; a source checkout updates via `git pull`
+(the portal launcher already does this) and returns an error here.
+"""
+
+import os
+import subprocess
+import sys
+import threading
+import urllib.request
+
+import version
+
+# Folder (next to the executable) that holds the downloaded zip, the generated
+# helper script, and its log. Kept out of the way with a leading dot.
+_WORK_DIRNAME = ".oasis-update"
+
+# Grace period after responding before this process exits, so the HTTP response
+# reaches the browser first. The helper is already spawned and blocks on our PID.
+_SHUTDOWN_DELAY_S = 1.5
+
+
+def _base_dir() -> str:
+    """Install folder holding the executable (and the user's data)."""
+    return os.path.dirname(sys.executable)
+
+
+def _download(url: str, dest: str) -> None:
+    """Stream the release asset to `dest`. Raises on any network/HTTP error."""
+    request = urllib.request.Request(url, headers={"User-Agent": "oasis-updater"})
+    with urllib.request.urlopen(request, timeout=30) as response, open(dest, "wb") as out:
+        while True:
+            chunk = response.read(1 << 16)
+            if not chunk:
+                break
+            out.write(chunk)
+    if os.path.getsize(dest) == 0:
+        raise OSError("下載的更新檔為空")
+
+
+def _write_helper(base: str, work: str, zip_path: str, exe: str) -> str:
+    """Write the OS-native updater script and return its path."""
+    if sys.platform == "win32":
+        return _write_helper_windows(base, work, zip_path, exe)
+    return _write_helper_posix(base, work, zip_path, exe)
+
+
+def _write_helper_posix(base: str, work: str, zip_path: str, exe: str) -> str:
+    script = f"""#!/bin/sh
+# Auto-generated by oasis updater.py — safe to delete.
+BASE='{base}'
+WORK='{work}'
+ZIP='{zip_path}'
+OLDPID={os.getpid()}
+EXENAME='{os.path.basename(exe)}'
+STAGING="$WORK/staging"
+LOG="$WORK/update.log"
+exec >>"$LOG" 2>&1
+echo "=== oasis update $(date) ==="
+
+# 1. Wait for the old backend to exit so its files unlock (cap ~120s).
+i=0
+while kill -0 "$OLDPID" 2>/dev/null; do
+  sleep 0.5; i=$((i+1)); [ "$i" -ge 240 ] && break
+done
+sleep 1
+
+# 2. Extract the fresh build (native tools preserve symlinks + exec bits).
+rm -rf "$STAGING"; mkdir -p "$STAGING"
+if command -v ditto >/dev/null 2>&1; then
+  ditto -x -k "$ZIP" "$STAGING"
+else
+  unzip -q -o "$ZIP" -d "$STAGING"
+fi
+
+# 3. Locate the app root (some zips wrap everything in a single folder).
+ROOT="$STAGING"
+if [ ! -e "$ROOT/$EXENAME" ]; then
+  inner=$(find "$STAGING" -maxdepth 2 -name "$EXENAME" -print 2>/dev/null | head -n 1)
+  [ -n "$inner" ] && ROOT=$(dirname "$inner")
+fi
+
+if [ ! -e "$ROOT/$EXENAME" ]; then
+  echo "ERROR: new build is missing $EXENAME — aborting swap, relaunching old build"
+else
+  # 4. Swap each top-level entry into the install dir. oasis.db / movies/ aren't
+  #    in the zip, so they're left in place.
+  for src in "$ROOT"/* "$ROOT"/.[!.]*; do
+    [ -e "$src" ] || continue
+    name=$(basename "$src")
+    rm -rf "$BASE/$name"
+    mv "$src" "$BASE/$name"
+  done
+  echo "swap complete"
+fi
+
+# 5. Clear the download quarantine + ensure the exec bit, then relaunch.
+xattr -dr com.apple.quarantine "$BASE" 2>/dev/null || true
+chmod +x "$BASE/$EXENAME" 2>/dev/null || true
+cd "$BASE"
+"$BASE/$EXENAME" >"$WORK/backend.log" 2>&1 &
+
+# 6. Cleanup.
+rm -rf "$STAGING" "$ZIP"
+echo "=== done ==="
+"""
+    path = os.path.join(work, "apply-update.sh")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(script)
+    os.chmod(path, 0o755)
+    return path
+
+
+def _write_helper_windows(base: str, work: str, zip_path: str, exe: str) -> str:
+    exe_name = os.path.basename(exe)
+    script = f"""# Auto-generated by oasis updater.py — safe to delete.
+$Base   = '{base}'
+$Work   = '{work}'
+$Zip    = '{zip_path}'
+$OldPid = {os.getpid()}
+$ExeName = '{exe_name}'
+$Staging = Join-Path $Work 'staging'
+$Log     = Join-Path $Work 'update.log'
+function Log($m) {{ Add-Content -LiteralPath $Log -Value ("{{0}} {{1}}" -f (Get-Date -Format o), $m) }}
+Log '=== oasis update ==='
+
+# 1. Wait for the old backend to exit so its files unlock (cap ~120s).
+$deadline = (Get-Date).AddSeconds(120)
+while ((Get-Process -Id $OldPid -ErrorAction SilentlyContinue) -and ((Get-Date) -lt $deadline)) {{
+  Start-Sleep -Milliseconds 500
+}}
+Start-Sleep -Seconds 1
+
+try {{
+  # 2. Extract the fresh build.
+  if (Test-Path -LiteralPath $Staging) {{ Remove-Item -LiteralPath $Staging -Recurse -Force }}
+  New-Item -ItemType Directory -Force -Path $Staging | Out-Null
+  Expand-Archive -LiteralPath $Zip -DestinationPath $Staging -Force
+
+  # 3. Locate the app root (some zips wrap everything in a single folder).
+  $Root = $Staging
+  if (-not (Test-Path -LiteralPath (Join-Path $Root $ExeName))) {{
+    $found = Get-ChildItem -LiteralPath $Staging -Recurse -Filter $ExeName -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($found) {{ $Root = $found.DirectoryName }}
+  }}
+
+  if (-not (Test-Path -LiteralPath (Join-Path $Root $ExeName))) {{
+    Log "ERROR: new build is missing $ExeName - aborting swap"
+  }} else {{
+    # 4. Swap each top-level entry into the install dir. oasis.db / movies\\
+    #    aren't in the zip, so they're left in place.
+    Get-ChildItem -LiteralPath $Root -Force | ForEach-Object {{
+      $dst = Join-Path $Base $_.Name
+      if (Test-Path -LiteralPath $dst) {{ Remove-Item -LiteralPath $dst -Recurse -Force }}
+      Move-Item -LiteralPath $_.FullName -Destination $dst -Force
+    }}
+    Log 'swap complete'
+  }}
+}} catch {{
+  Log ("EXCEPTION: " + $_.Exception.Message)
+}}
+
+# 5. Relaunch (new build if swapped, otherwise the old one is still in place).
+Start-Process -FilePath (Join-Path $Base $ExeName) -WorkingDirectory $Base
+
+# 6. Cleanup.
+if (Test-Path -LiteralPath $Staging) {{ Remove-Item -LiteralPath $Staging -Recurse -Force -ErrorAction SilentlyContinue }}
+Remove-Item -LiteralPath $Zip -Force -ErrorAction SilentlyContinue
+Log '=== done ==='
+"""
+    path = os.path.join(work, "apply-update.ps1")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(script)
+    return path
+
+
+def _spawn_detached(script: str) -> None:
+    """Launch the helper so it outlives this process."""
+    if sys.platform == "win32":
+        DETACHED_PROCESS = 0x00000008
+        CREATE_NEW_PROCESS_GROUP = 0x00000200
+        subprocess.Popen(
+            ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script],
+            creationflags=DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP,
+            close_fds=True,
+        )
+    else:
+        subprocess.Popen(
+            ["/bin/sh", script],
+            start_new_session=True,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+        )
+
+
+def apply_update(timeout: float = 6.0) -> dict:
+    """Download the latest release and hand off to the helper that swaps it in.
+
+    On success the response is `{"status": "updating", "latest": <tag>}` and this
+    process exits shortly after, so the frontend should poll /api/health and
+    reconnect once the relaunched backend answers. Failures return
+    `{"status": "error", "error": <msg>}` and leave the running backend intact.
+    """
+    if not getattr(sys, "frozen", False):
+        return {
+            "status": "error",
+            "error": "自動更新僅適用於打包版。原始碼版本請用 git pull（啟動腳本會自動更新）。",
+        }
+
+    info = version.check_for_update(timeout)
+    if info.get("error"):
+        return {"status": "error", "error": info["error"]}
+    if not info.get("update_available"):
+        return {"status": "error", "error": "已是最新版本，沒有可用的更新。"}
+
+    download_url = info.get("download_url")
+    if not download_url:
+        return {"status": "error", "error": "找不到適用於此系統的更新下載檔。"}
+
+    base = _base_dir()
+    work = os.path.join(base, _WORK_DIRNAME)
+    zip_path = os.path.join(work, "download.zip")
+    try:
+        os.makedirs(work, exist_ok=True)
+        _download(download_url, zip_path)
+        script = _write_helper(base, work, zip_path, sys.executable)
+        _spawn_detached(script)
+    except Exception as exc:  # download failed, disk full, spawn blocked, ...
+        return {"status": "error", "error": f"更新失敗：{exc}"}
+
+    # Give the response time to flush before we exit and unlock our files; the
+    # helper is already waiting on this PID and will swap + relaunch.
+    threading.Timer(_SHUTDOWN_DELAY_S, lambda: os._exit(0)).start()
+    return {"status": "updating", "latest": info.get("latest")}