feat: add configurable default music source (#126)

Make the default playback source a user-configurable setting so servers
that mostly play e.g. Bilibili no longer need to type `-b` on every
`!play`. Previously defaultPlatform() always picked the first enabled
provider by a fixed priority order, with no way to override it.

- config: add optional `defaultPlatform: GateableProvider | null`.
  loadConfig sanitizes it — kept only when it names a known provider that
  is also currently enabled, else null. defaultPlatform() returns the
  preference when enabled, otherwise falls back to the fixed priority order.
- POST /api/bot/settings accepts `defaultPlatform` (validated against the
  possibly-updated enabledProviders; null/"" clears it), and reconciles a
  stored default that a new enabledProviders list no longer allows. GET and
  POST responses expose the field.
- WebUI: new "默认音源" section with a source picker; saving refreshes the
  store's default source so it takes effect immediately without a restart.
- Tests: extend config defaultPlatform priority tests and add coverage for
  the settings endpoint and /providers routing.
- README: document `defaultPlatform` in the enabledProviders section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/web/api/bot.test.ts

@@ -647,4 +647,54 @@ describe("bot router /settings jellyfin block + enabledProviders", () => {
     // No jellyfin block in the request → no reconfigure call.
     expect(configureCalls).toHaveLength(0);
   });
+
+  // --- #126: operator-chosen default source ---
+
+  it("GET /settings exposes defaultPlatform (null by default)", async () => {
+    const res = await request(mountBot()).get("/api/bot/settings");
+    expect(res.status).toBe(200);
+    expect(res.body.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings sets an enabled defaultPlatform and persists it", async () => {
+    const res = await request(mountBot()).post("/api/bot/settings").send({
+      defaultPlatform: "bilibili",
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.defaultPlatform).toBe("bilibili");
+    expect(config.defaultPlatform).toBe("bilibili");
+    const onDisk = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(onDisk.defaultPlatform).toBe("bilibili");
+  });
+
+  it("POST /settings ignores an unknown or disabled defaultPlatform", async () => {
+    const app = mountBot();
+    // jellyfin is opt-in and not enabled in the default config → rejected.
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "jellyfin" });
+    expect(config.defaultPlatform).toBeNull();
+    // Unknown value → rejected.
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "bogus" });
+    expect(config.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings clears defaultPlatform with null", async () => {
+    const app = mountBot();
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "qq" });
+    expect(config.defaultPlatform).toBe("qq");
+    const res = await request(app).post("/api/bot/settings").send({ defaultPlatform: null });
+    expect(res.body.defaultPlatform).toBeNull();
+    expect(config.defaultPlatform).toBeNull();
+  });
+
+  it("POST /settings drops a default whose source gets disabled in the same request", async () => {
+    const app = mountBot();
+    await request(app).post("/api/bot/settings").send({ defaultPlatform: "qq" });
+    expect(config.defaultPlatform).toBe("qq");
+    // Disabling qq via enabledProviders clears the now-invalid default.
+    const res = await request(app).post("/api/bot/settings").send({
+      enabledProviders: ["netease", "bilibili"],
+    });
+    expect(res.body.defaultPlatform).toBeNull();
+    expect(config.defaultPlatform).toBeNull();
+  });
 });

src/web/api/bot.ts

@@ -77,6 +77,7 @@ export function createBotRouter(
       spotify: maskedSpotify(),
       jellyfin: maskedJellyfin(),
       enabledProviders: config.enabledProviders,
+      defaultPlatform: config.defaultPlatform,
     });
   });
 
@@ -175,6 +176,29 @@ export function createBotRouter(
       );
     }
 
+    // defaultPlatform (issue #126): the operator-chosen default source for
+    // platform-less commands/REST/WebUI calls. Reconciled AFTER enabledProviders
+    // so both are validated against the same (possibly updated) enabled list:
+    //   1) Drop a stored default that the new enabledProviders no longer allows,
+    //      keeping the persisted config consistent with loadConfig's invariant.
+    //   2) Apply an explicit change — `null`/`""` clears it (back to priority
+    //      order); a known+enabled provider sets it; anything else is ignored.
+    if (config.defaultPlatform && !config.enabledProviders.includes(config.defaultPlatform)) {
+      config.defaultPlatform = null;
+    }
+    if ("defaultPlatform" in req.body) {
+      const dp = req.body.defaultPlatform;
+      if (dp === null || dp === "") {
+        config.defaultPlatform = null;
+      } else if (
+        typeof dp === "string" &&
+        (GATEABLE_PROVIDERS as readonly string[]).includes(dp) &&
+        config.enabledProviders.includes(dp as GateableProvider)
+      ) {
+        config.defaultPlatform = dp as GateableProvider;
+      }
+    }
+
     saveConfig(configPath, config);
 
     // Hot-apply the (possibly re-pointed) Jellyfin connection to the live
@@ -219,6 +243,7 @@ export function createBotRouter(
       spotify: maskedSpotify(),
       jellyfin: maskedJellyfin(),
       enabledProviders: config.enabledProviders,
+      defaultPlatform: config.defaultPlatform,
     });
   });
 

src/web/api/music.test.ts

@@ -118,6 +118,25 @@ describe("music router provider gating (enabledProviders) + jellyfin endpoints",
     expect(res.body.enabled).not.toContain("spotify"); // spotify.enabled defaults off
   });
 
+  it("GET /providers reports a configured defaultPlatform override (#126)", async () => {
+    const config = getDefaultConfig();
+    config.defaultPlatform = "qq"; // operator prefers QQ over the priority order
+    const { app } = mount(config);
+    const res = await request(app).get("/api/music/providers");
+    expect(res.status).toBe(200);
+    expect(res.body.default).toBe("qq");
+  });
+
+  it("routes a platform-less /search to the configured defaultPlatform (#126)", async () => {
+    const config = getDefaultConfig();
+    config.defaultPlatform = "bilibili";
+    const { app, netease } = mount(config);
+    const res = await request(app).get("/api/music/search?q=hello");
+    expect(res.status).toBe(200);
+    // Default is now bilibili, so the netease provider must NOT be hit.
+    expect(netease.search).not.toHaveBeenCalled();
+  });
+
   /** Default config plus the opt-in jellyfin source enabled. */
   function configWithJellyfin() {
     const config = getDefaultConfig();