feat(search): server-side offset pagination through providers + /search route (#115 backend)

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

src/web/api/music.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import express from "express";
+import request from "supertest";
+import pino from "pino";
+import type { MusicProvider, SearchResult } from "../../music/provider.js";
+import { createMusicRouter } from "./music.js";
+
+function fakeProvider(platform: MusicProvider["platform"]): MusicProvider {
+  const empty: SearchResult = { songs: [], albums: [], playlists: [] };
+  return {
+    platform,
+    search: vi.fn().mockResolvedValue(empty),
+  } as unknown as MusicProvider;
+}
+
+describe("music router GET /search offset pagination", () => {
+  let app: express.Express;
+  let netease: MusicProvider;
+
+  beforeEach(() => {
+    netease = fakeProvider("netease");
+    const router = createMusicRouter(
+      netease,
+      fakeProvider("qq"),
+      fakeProvider("bilibili"),
+      pino({ level: "silent" })
+    );
+    app = express();
+    app.use("/api/music", router);
+  });
+
+  it("parses offset and passes it as the 3rd arg to provider.search", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20&offset=20");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 20);
+  });
+
+  it("defaults a missing offset to 0", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+  });
+
+  it("clamps a negative offset to 0", async () => {
+    const res = await request(app).get("/api/music/search?q=hello&limit=20&offset=-5");
+    expect(res.status).toBe(200);
+    expect(netease.search).toHaveBeenCalledWith("hello", 20, 0);
+  });
+});

src/web/api/music.ts

@@ -84,7 +84,7 @@ export function createMusicRouter(
 
   router.get("/search", async (req, res) => {
     try {
-      const { q, platform, limit } = req.query;
+      const { q, platform, limit, offset } = req.query;
       if (!q) {
         res.status(400).json({ error: "q (query) is required" });
         return;
@@ -94,9 +94,13 @@ export function createMusicRouter(
         return;
       }
       const provider = getProvider(platform as string);
+      // Server-side pagination: offset lets the web load past the first page.
+      // Clamp to >= 0 so a bad/negative value falls back to the first page.
+      const parsedOffset = Math.max(0, parseInt(offset as string) || 0);
       const result = await provider.search(
         q as string,
-        parseInt(limit as string) || 20
+        parseInt(limit as string) || 20,
+        parsedOffset
       );
       res.json(result);
     } catch (err) {