mirror of
https://github.com/ZHANGTIANYAO1/teamspeak-music-bot.git
synced 2026-10-01 20:42:50 +08:00
docs(plan): custom avatar + album search implementation plans
Two independent plans for spec 2026-05-07; each yields its own PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
saopig1andClaude Opus 4.7 committed
1 parent
4407cd0c67
commit
ff5502be2f
2 files changed
+1423
No files matched your search
@@ -0,0 +1,520 @@
|
||||
# Album Search & Playback Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Surface albums in search results and allow playing the whole album from the web UI. Currently `SearchResult.albums` is always `[]` and Search.vue only renders songs.
|
||||
|
||||
**Architecture:** Extend `search()` in netease + qq providers to populate `albums`. Aggregate them in `/search/all`. Add a new "专辑" (and "歌单") section to Search.vue. Reuse `Playlist.vue` as the album detail page by branching on `route.meta.kind` between `/playlist/:id` and `/album/:id` endpoints. The existing `getAlbumSongs(id)` and `/api/music/album/:id` endpoint already work.
|
||||
|
||||
**Tech Stack:** Node 20 + TS, Express 5, Vue 3 + Vue Router 4, axios. No new deps.
|
||||
|
||||
---
|
||||
|
||||
## Spec Reference
|
||||
|
||||
`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "专辑搜索".
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Action | Responsibility |
|
||||
|---|---|---|
|
||||
| `src/music/provider.ts` | Read-only | Verify `Album` and `SearchResult.albums` shape (no change expected) |
|
||||
| `src/music/netease.ts` | Modify | `search()` adds a third parallel call (`type=10`) and maps albums |
|
||||
| `src/music/qq.ts` | Modify | `search()` adds `req_album` section and maps albums |
|
||||
| `src/music/netease.test.ts` | Modify | New tests for albums in search response |
|
||||
| `src/music/qq.test.ts` | Modify (or create if absent) | Tests for albums in qq search |
|
||||
| `src/web/api/music.ts` | Modify | `/search/all` returns `{songs, albums, playlists}` |
|
||||
| `web/src/views/Search.vue` | Modify | Render albums + playlists sections |
|
||||
| `web/src/views/Playlist.vue` | Modify | Branch endpoint by `route.meta.kind === 'album'` |
|
||||
| `web/src/router/index.ts` | Modify | Add `/album/:id` route reusing Playlist component, set `meta.kind = 'album'` |
|
||||
|
||||
## Conventions
|
||||
|
||||
- TDD throughout. Each task: failing test → implement → verify → commit.
|
||||
- Mock HTTP via existing fixtures pattern (look at `src/music/netease.test.ts` for setup).
|
||||
- Keep all platform-specific quirks inside the provider class — no leaking into Search.vue logic.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: netease.ts — fetch albums in search
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/music/netease.ts`
|
||||
- Modify: `src/music/netease.test.ts`
|
||||
|
||||
- [ ] **Step 1: Read the existing test setup so we mock the same way**
|
||||
|
||||
```bash
|
||||
grep -n 'cloudsearch\|MockAdapter\|axios.create\|mock\|nock\|fixture' src/music/netease.test.ts | head -20
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Write the failing test**
|
||||
|
||||
Append to `src/music/netease.test.ts` inside the existing `describe`:
|
||||
|
||||
```ts
|
||||
it("populates SearchResult.albums from cloudsearch type=10", async () => {
|
||||
// Adjust the fixture/mock helper to your existing test pattern.
|
||||
// The test should: arrange a mock that returns a non-empty albums array
|
||||
// for type=10, run search(), assert result.albums has the expected shape.
|
||||
mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 10 }) }).reply(200, {
|
||||
result: {
|
||||
albums: [
|
||||
{ id: 42, name: "Album A", picUrl: "https://x/p.jpg", artists: [{ name: "Artist X" }] },
|
||||
],
|
||||
},
|
||||
});
|
||||
mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1 }) }).reply(200, { result: { songs: [] } });
|
||||
mockApi.onGet("/cloudsearch", { params: expect.objectContaining({ type: 1000 }) }).reply(200, { result: { playlists: [] } });
|
||||
|
||||
const provider = makeProvider();
|
||||
const r = await provider.search("foo", 5);
|
||||
expect(r.albums).toEqual([
|
||||
{ id: "42", name: "Album A", artist: "Artist X", coverUrl: "https://x/p.jpg", platform: "netease" },
|
||||
]);
|
||||
});
|
||||
```
|
||||
|
||||
If the existing tests use a different mock library (e.g. `msw` or manual axios stubbing), translate the fixture above to match. Do not introduce new test deps.
|
||||
|
||||
- [ ] **Step 3: Run test to verify it fails**
|
||||
|
||||
Run: `npx vitest run src/music/netease.test.ts`
|
||||
Expected: FAIL — `result.albums` is `[]`
|
||||
|
||||
- [ ] **Step 4: Implement the change**
|
||||
|
||||
In `src/music/netease.ts` `search()` (~line 93), change the `Promise.all` from 2 to 3 calls:
|
||||
|
||||
```ts
|
||||
const [songRes, playlistRes, albumRes] = await Promise.all([
|
||||
this.api.get("/cloudsearch", { params: { keywords: query, type: 1, limit, ...this.cookieParams } }),
|
||||
this.api.get("/cloudsearch", { params: { keywords: query, type: 1000, limit: 5, ...this.cookieParams } }),
|
||||
this.api.get("/cloudsearch", { params: { keywords: query, type: 10, limit: 5, ...this.cookieParams } }),
|
||||
]);
|
||||
```
|
||||
|
||||
After the existing `playlists: Playlist[] = ...` mapping, add:
|
||||
|
||||
```ts
|
||||
const albums: Album[] = (albumRes.data?.result?.albums ?? []).map((a: any) => ({
|
||||
id: String(a.id),
|
||||
name: a.name ?? "",
|
||||
artist: (a.artists ?? []).map((x: any) => x.name).join(" / "),
|
||||
coverUrl: a.picUrl ?? "",
|
||||
platform: "netease",
|
||||
}));
|
||||
```
|
||||
|
||||
Update the `return { songs, playlists, albums: [] }` to `return { songs, playlists, albums }`.
|
||||
|
||||
(Make sure `Album` is imported from `./provider.js`; if not yet imported, add it to the existing import.)
|
||||
|
||||
- [ ] **Step 5: Run test to verify it passes**
|
||||
|
||||
Run: `npx vitest run src/music/netease.test.ts`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/music/netease.ts src/music/netease.test.ts
|
||||
git commit -m "feat(netease): include albums in search results"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: qq.ts — fetch albums in search
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/music/qq.ts`
|
||||
- Modify or Create: `src/music/qq.test.ts`
|
||||
|
||||
- [ ] **Step 1: Verify whether qq.test.ts exists**
|
||||
|
||||
```bash
|
||||
ls src/music/qq.test.ts
|
||||
```
|
||||
|
||||
If absent, create a minimal one mirroring `netease.test.ts` style: instantiate provider, mock the `qqDirectApi` axios instance, assert `r.albums.length > 0` after a `search()` call.
|
||||
|
||||
- [ ] **Step 2: Write the failing test**
|
||||
|
||||
Add to `src/music/qq.test.ts`:
|
||||
|
||||
```ts
|
||||
it("populates SearchResult.albums from a parallel album search request", async () => {
|
||||
// Mock returns an album list under req_album.data.body.album.list
|
||||
mockApi.onGet("/cgi-bin/musicu.fcg").reply((cfg) => {
|
||||
const data = JSON.parse(cfg.params?.data ?? "{}");
|
||||
if (data.req_album) {
|
||||
return [200, { req_album: { data: { body: { album: { list: [
|
||||
{ albumMID: "abc", albumName: "Aero", singerName: "S", albumPic: "https://x/p.jpg" },
|
||||
] } } } } }];
|
||||
}
|
||||
if (data.req_0) {
|
||||
return [200, { req_0: { data: { body: { song: { list: [] } } } } }];
|
||||
}
|
||||
return [200, {}];
|
||||
});
|
||||
|
||||
const provider = makeProvider();
|
||||
const r = await provider.search("foo", 5);
|
||||
expect(r.albums).toEqual([
|
||||
{ id: "abc", name: "Aero", artist: "S", coverUrl: expect.stringContaining("https://"), platform: "qq" },
|
||||
]);
|
||||
});
|
||||
```
|
||||
|
||||
Verify the actual QQ API response shape against a real call before finalizing the field names — `albumMID` vs `mid`, `albumPic` vs `pic`, etc. If unsure, log a real response once and freeze the shape in the fixture.
|
||||
|
||||
- [ ] **Step 3: Run test to verify it fails**
|
||||
|
||||
Run: `npx vitest run src/music/qq.test.ts`
|
||||
Expected: FAIL — `r.albums` is `[]`
|
||||
|
||||
- [ ] **Step 4: Implement the change**
|
||||
|
||||
In `src/music/qq.ts` `search()` (~line 63), change `reqData` to include both `req_0` (songs) and `req_album` (albums):
|
||||
|
||||
```ts
|
||||
const reqData = JSON.stringify({
|
||||
req_0: {
|
||||
module: "music.search.SearchCgiService",
|
||||
method: "DoSearchForQQMusicDesktop",
|
||||
param: { searchid: "1", query, num_per_page: Math.min(limit, 50), search_type: 0 },
|
||||
},
|
||||
req_album: {
|
||||
module: "music.search.SearchCgiService",
|
||||
method: "DoSearchForQQMusicDesktop",
|
||||
param: { searchid: "1", query, num_per_page: 5, search_type: 8 },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
After the existing `songs` mapping, add:
|
||||
|
||||
```ts
|
||||
const albumList: any[] = res.data?.req_album?.data?.body?.album?.list ?? [];
|
||||
const albums: Album[] = albumList.map((a: any) => ({
|
||||
id: String(a.albumMID ?? a.mid ?? a.albumID ?? ""),
|
||||
name: a.albumName ?? a.title ?? "",
|
||||
artist: a.singerName ?? (a.singer ?? []).map((s: any) => s.name).join(" / "),
|
||||
coverUrl: a.albumMID
|
||||
? `https://y.gtimg.cn/music/photo_new/T002R300x300M000${a.albumMID}.jpg`
|
||||
: (a.albumPic ?? ""),
|
||||
platform: "qq",
|
||||
}));
|
||||
```
|
||||
|
||||
Change `return { songs, playlists: [], albums: [] }` to `return { songs, playlists: [], albums }`.
|
||||
|
||||
- [ ] **Step 5: Run test to verify it passes**
|
||||
|
||||
Run: `npx vitest run src/music/qq.test.ts`
|
||||
Expected: PASS
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/music/qq.ts src/music/qq.test.ts
|
||||
git commit -m "feat(qq): include albums in search results"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: /search/all — aggregate albums + playlists
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/web/api/music.ts`
|
||||
|
||||
- [ ] **Step 1: Look at the current aggregation**
|
||||
|
||||
In `src/web/api/music.ts` near line 40 the `/search/all` handler builds only `songs`. Extend it.
|
||||
|
||||
- [ ] **Step 2: Write a failing integration test (if test infra allows)**
|
||||
|
||||
If there's already a test file for music.ts, add a test that mocks the providers and asserts `res.body.albums.length > 0`. If not, skip and rely on Task 1+2 unit coverage + manual verification in Task 4.
|
||||
|
||||
- [ ] **Step 3: Aggregate albums + playlists**
|
||||
|
||||
Replace the existing `songs = ...` block + `res.json({ songs })` at lines ~54–62 with:
|
||||
|
||||
```ts
|
||||
const songs = [
|
||||
...(neteaseResult.status === "fulfilled" ? neteaseResult.value.songs : []),
|
||||
...(qqResult.status === "fulfilled" ? qqResult.value.songs : []),
|
||||
...(bilibiliResult.status === "fulfilled" ? bilibiliResult.value.songs : []),
|
||||
];
|
||||
const albums = [
|
||||
...(neteaseResult.status === "fulfilled" ? neteaseResult.value.albums : []),
|
||||
...(qqResult.status === "fulfilled" ? qqResult.value.albums : []),
|
||||
];
|
||||
const playlists = [
|
||||
...(neteaseResult.status === "fulfilled" ? neteaseResult.value.playlists : []),
|
||||
...(qqResult.status === "fulfilled" ? qqResult.value.playlists : []),
|
||||
];
|
||||
|
||||
res.json({ songs, albums, playlists });
|
||||
```
|
||||
|
||||
(Bilibili intentionally skipped for albums/playlists — no album concept; playlists likewise minor.)
|
||||
|
||||
- [ ] **Step 4: Verify by curl**
|
||||
|
||||
Build + run, then:
|
||||
|
||||
```bash
|
||||
curl -s 'http://localhost:3000/api/music/search/all?q=Beyond' \
|
||||
| python3 -c 'import json,sys;d=json.load(sys.stdin);print({k: len(v) for k, v in d.items()})'
|
||||
```
|
||||
|
||||
Expected: `{'songs': N>0, 'albums': N>0, 'playlists': N>=0}`
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/web/api/music.ts
|
||||
git commit -m "feat(api): /search/all returns albums and playlists"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Album route reusing Playlist.vue
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/src/router/index.ts`
|
||||
- Modify: `web/src/views/Playlist.vue`
|
||||
|
||||
- [ ] **Step 1: Look at the current router config and Playlist load logic**
|
||||
|
||||
```bash
|
||||
grep -n "path:\|component:\|meta" web/src/router/index.ts
|
||||
grep -n "loadPlaylist\|/api/music/playlist\|onMounted" web/src/views/Playlist.vue
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add /album/:id route**
|
||||
|
||||
In `web/src/router/index.ts`, find the `/playlist/:id` route entry. Right after it, add:
|
||||
|
||||
```ts
|
||||
{
|
||||
path: '/album/:id',
|
||||
component: () => import('../views/Playlist.vue'),
|
||||
meta: { kind: 'album' },
|
||||
},
|
||||
```
|
||||
|
||||
(If `/playlist/:id` is `meta:`-less, also add `meta: { kind: 'playlist' }` to it for symmetry.)
|
||||
|
||||
- [ ] **Step 3: Branch the endpoint inside Playlist.vue**
|
||||
|
||||
Find the load function (probably `onMounted(async () => { axios.get('/api/music/playlist/' + id, ...) })`). Refactor:
|
||||
|
||||
```ts
|
||||
const route = useRoute();
|
||||
const kind = (route.meta.kind as string) ?? 'playlist'; // 'playlist' | 'album'
|
||||
const endpoint = kind === 'album' ? '/api/music/album/' : '/api/music/playlist/';
|
||||
// ... use `${endpoint}${route.params.id}` ...
|
||||
```
|
||||
|
||||
For the hero metadata, the playlist endpoint returns `{songs}` only (no top-level cover/title) — verify what the Album endpoint currently returns. If both only return `{songs}`, the existing Playlist.vue must already derive the cover from somewhere (probably the first song's coverUrl, or an additional `/api/music/playlist/:id/detail` call). Keep the existing pattern; if a separate detail call is needed for albums, fetch the metadata from `/api/music/song/<firstSong.id>` to get the album name + cover, OR add a thin `/api/music/album/:id/detail` endpoint that returns `{ name, coverUrl, description }`.
|
||||
|
||||
**Decision:** if Playlist.vue currently uses ONLY `/api/music/playlist/:id` and derives metadata from songs, do the same for albums (no new endpoint). If it calls a separate detail endpoint, add a matching `/api/music/album/:id/detail` returning `{ name, coverUrl }` from the first song's `album` and `coverUrl` fields.
|
||||
|
||||
- [ ] **Step 4: Verify in browser**
|
||||
|
||||
Run `cd web && npm run dev`. Visit `/album/<some-netease-album-id>` (pick one from a search). Expect: hero header + song list + play-all button — same UX as a playlist page.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/router/index.ts web/src/views/Playlist.vue
|
||||
git commit -m "feat(web): /album/:id route reusing Playlist view"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Search.vue — render albums + playlists sections
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/src/views/Search.vue`
|
||||
|
||||
- [ ] **Step 1: Read current Search.vue**
|
||||
|
||||
```bash
|
||||
sed -n '1,120p' web/src/views/Search.vue
|
||||
```
|
||||
|
||||
Identify: the `results.value = res.data.songs` line and the `<div v-else-if="results.length > 0">` block.
|
||||
|
||||
- [ ] **Step 2: Refactor to three result lists**
|
||||
|
||||
Replace the script:
|
||||
|
||||
```ts
|
||||
import type { Song } from '../stores/player.js';
|
||||
|
||||
interface Album { id: string; name: string; artist: string; coverUrl: string; platform: string; }
|
||||
interface Playlist { id: string; name: string; coverUrl: string; songCount?: number; platform: string; }
|
||||
|
||||
const songs = ref<Song[]>([]);
|
||||
const albums = ref<Album[]>([]);
|
||||
const playlists = ref<Playlist[]>([]);
|
||||
const loading = ref(false);
|
||||
const searched = ref(false);
|
||||
|
||||
async function doSearch() {
|
||||
if (!query.value.trim()) return;
|
||||
loading.value = true;
|
||||
searched.value = true;
|
||||
try {
|
||||
const res = await axios.get('/api/music/search/all', { params: { q: query.value } });
|
||||
songs.value = res.data.songs ?? [];
|
||||
albums.value = res.data.albums ?? [];
|
||||
playlists.value = res.data.playlists ?? [];
|
||||
} catch {
|
||||
songs.value = []; albums.value = []; playlists.value = [];
|
||||
} finally {
|
||||
loading.value = false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Render the sections**
|
||||
|
||||
Replace the existing `<div v-else-if="results.length > 0" class="results">` block:
|
||||
|
||||
```vue
|
||||
<template v-else-if="songs.length || albums.length || playlists.length">
|
||||
<section v-if="albums.length" class="result-section">
|
||||
<h2 class="section-title">专辑</h2>
|
||||
<div class="card-grid">
|
||||
<router-link
|
||||
v-for="al in albums"
|
||||
:key="`${al.platform}-${al.id}`"
|
||||
:to="`/album/${al.id}?platform=${al.platform}`"
|
||||
class="card hover-scale"
|
||||
>
|
||||
<CoverArt :url="al.coverUrl" :size="160" :radius="10" :show-shadow="true" />
|
||||
<div class="card-name">{{ al.name }}</div>
|
||||
<div class="card-sub">{{ al.artist }}</div>
|
||||
</router-link>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section v-if="playlists.length" class="result-section">
|
||||
<h2 class="section-title">歌单</h2>
|
||||
<div class="card-grid">
|
||||
<router-link
|
||||
v-for="pl in playlists"
|
||||
:key="`${pl.platform}-${pl.id}`"
|
||||
:to="`/playlist/${pl.id}?platform=${pl.platform}`"
|
||||
class="card hover-scale"
|
||||
>
|
||||
<CoverArt :url="pl.coverUrl" :size="160" :radius="10" :show-shadow="true" />
|
||||
<div class="card-name">{{ pl.name }}</div>
|
||||
</router-link>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section v-if="songs.length" class="result-section">
|
||||
<h2 class="section-title">单曲</h2>
|
||||
<SongCard
|
||||
v-for="(song, i) in songs"
|
||||
:key="`${song.platform}-${song.id}`"
|
||||
:song="song"
|
||||
:index="i + 1"
|
||||
:active="store.currentSong?.id === song.id"
|
||||
@play="store.playSong(song)"
|
||||
@playNext="store.playNextSong(song)"
|
||||
@add="store.addSong(song)"
|
||||
/>
|
||||
</section>
|
||||
</template>
|
||||
|
||||
<div v-else-if="searched" class="empty">未找到相关结果</div>
|
||||
```
|
||||
|
||||
(Import `CoverArt`: `import CoverArt from '../components/CoverArt.vue';`.)
|
||||
|
||||
- [ ] **Step 4: Add minimal styles**
|
||||
|
||||
Append to the `<style lang="scss" scoped>` block:
|
||||
|
||||
```scss
|
||||
.result-section {
|
||||
margin-bottom: 32px;
|
||||
.section-title { font-size: 18px; margin: 0 0 12px; opacity: 0.85; }
|
||||
}
|
||||
.card-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
|
||||
gap: 16px;
|
||||
}
|
||||
.card {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 6px;
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
.card-name { font-size: 14px; line-height: 1.3; max-height: 2.6em; overflow: hidden; }
|
||||
.card-sub { font-size: 12px; opacity: 0.6; }
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Build + visually verify**
|
||||
|
||||
```bash
|
||||
cd web && npm run build
|
||||
```
|
||||
|
||||
Then `npm run dev` → search "周杰伦" → see three sections; click an album card → arrives at `/album/:id` with songs + play-all.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/views/Search.vue
|
||||
git commit -m "feat(web): show album + playlist sections in search"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Open PR
|
||||
|
||||
- [ ] **Step 1: Push branch**
|
||||
|
||||
```bash
|
||||
git checkout -b feat/album-search
|
||||
git push -u origin feat/album-search
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Create the PR**
|
||||
|
||||
```bash
|
||||
gh pr create --title "feat(search): album section + album playback" --body "Closes part of #51 (album half).
|
||||
|
||||
## Summary
|
||||
- netease.search() / qq.search() now populate SearchResult.albums
|
||||
- /api/music/search/all returns albums + playlists alongside songs
|
||||
- Search.vue renders three sections: 专辑 / 歌单 / 单曲
|
||||
- /album/:id route reuses Playlist.vue with meta.kind='album'
|
||||
- bilibili / youtube intentionally still return albums:[] (no album API)
|
||||
|
||||
## Test plan
|
||||
- [x] vitest covers netease + qq search returning non-empty albums
|
||||
- [x] curl /search/all?q=周杰伦 returns {songs, albums, playlists}
|
||||
- [x] Manual: search → click album card → /album/:id → play all
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Self-Review Checklist
|
||||
|
||||
- [x] Spec coverage: backend album search → Tasks 1+2; aggregator → Task 3; album detail route → Task 4; UI sections → Task 5
|
||||
- [x] No "TBD"/placeholder text — every step shows the actual diff or command
|
||||
- [x] Type names consistent: `Album` (capital A), `albums` (lowercase plural), `SearchResult.albums`
|
||||
- [x] Bilibili/YouTube explicitly out of scope per spec — confirmed in Task 3 by skipping them in albums aggregation
|
||||
- [x] Routes use `meta.kind` — same key referenced in Playlist.vue (Task 4) and `/album/:id` registration (Task 4 Step 2)
|
||||
@@ -0,0 +1,903 @@
|
||||
# Custom Bot Avatar Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Let users upload a fixed avatar per bot. When `avatarEnabled=true`, the avatar follows the song cover during playback and reverts to the custom avatar (instead of clearing) on stop. When `avatarEnabled=false` and a custom avatar exists, the bot always shows the custom avatar.
|
||||
|
||||
**Architecture:** New SQLite column stores a relative file path; bytes live on disk under `data/avatars/<botId>.<ext>` (mirrors `data/cookies/`). `BotProfileManager` gains a `customAvatar` Buffer; the existing `clearAvatar()` becomes "restore custom or clear"; `onConnect()` immediately applies the custom avatar when sync is off. Three new REST endpoints (GET/PUT/DELETE) under `/api/bot/:id/avatar` accept base64 JSON (avoids adding multer; bump `express.json()` limit).
|
||||
|
||||
**Tech Stack:** Node 20 + TS + Express 5, better-sqlite3, Vue 3 + axios. No new runtime deps.
|
||||
|
||||
---
|
||||
|
||||
## Spec Reference
|
||||
|
||||
`docs/superpowers/specs/2026-05-07-custom-avatar-and-album-search-design.md` — section "自定义头像".
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Action | Responsibility |
|
||||
|---|---|---|
|
||||
| `src/data/database.ts` | Modify | Add `custom_avatar_path` column + migration + accessor methods |
|
||||
| `src/data/avatars.ts` | **Create** | Read/write/delete avatar files under `data/avatars/` |
|
||||
| `src/bot/profile.ts` | Modify | `customAvatar` field, `setCustomAvatar`, `applyIdleAvatar`, modify `clearAvatar`, modify `onConnect` |
|
||||
| `src/bot/instance.ts` | Modify | Load custom avatar on start, pass to ProfileManager |
|
||||
| `src/web/api/bot.ts` | Modify | Add GET/PUT/DELETE `/avatar` endpoints |
|
||||
| `src/web/server.ts` | Modify | Bump `express.json()` limit to `400kb` |
|
||||
| `src/index.ts` | Modify | Pass `AVATAR_DIR` to bot manager / API router |
|
||||
| `src/data/database.test.ts` | Modify | Test custom avatar path persistence + migration idempotency |
|
||||
| `src/data/avatars.test.ts` | **Create** | Unit tests for avatar store |
|
||||
| `src/bot/profile.test.ts` | **Create** | Tests for new precedence logic with a mock TS3Client |
|
||||
| `web/src/components/AvatarUpload.vue` | **Create** | Reusable avatar picker + preview + delete |
|
||||
| `web/src/views/Settings.vue` | Modify | Add custom avatar row in profile features list; insert into create-bot and edit-bot forms |
|
||||
|
||||
## Conventions
|
||||
|
||||
- TDD: failing test → implement → verify → commit, every step.
|
||||
- Commits use conventional format: `feat(profile):`, `feat(api):`, `feat(web):`, `test(...)`. Each task ends with one commit.
|
||||
- Tests live in vitest (`npm test`).
|
||||
- All paths absolute or relative to repo root.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: DB migration + getter/setter for custom avatar path
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/data/database.ts`
|
||||
- Modify: `src/data/database.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
Add to `src/data/database.test.ts` after the existing tests (find the closing `});` of the last test case in the `describe` block, insert before it):
|
||||
|
||||
```ts
|
||||
it("persists and clears customAvatarPath on a bot instance", () => {
|
||||
const inst = {
|
||||
id: "bot-1",
|
||||
name: "B",
|
||||
serverAddress: "x",
|
||||
serverPort: 9987,
|
||||
nickname: "n",
|
||||
defaultChannel: "",
|
||||
channelPassword: "",
|
||||
autoStart: false,
|
||||
serverProtocol: "",
|
||||
ts6ApiKey: "",
|
||||
serverPassword: "",
|
||||
};
|
||||
botDb.saveBotInstance(inst);
|
||||
expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
|
||||
botDb.setCustomAvatarPath("bot-1", "avatars/bot-1.png");
|
||||
expect(botDb.getCustomAvatarPath("bot-1")).toBe("avatars/bot-1.png");
|
||||
botDb.setCustomAvatarPath("bot-1", null);
|
||||
expect(botDb.getCustomAvatarPath("bot-1")).toBeNull();
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npx vitest run src/data/database.test.ts`
|
||||
Expected: FAIL — `botDb.getCustomAvatarPath is not a function`
|
||||
|
||||
- [ ] **Step 3: Add the column to migration + interface + statements**
|
||||
|
||||
In `src/data/database.ts`:
|
||||
|
||||
1. Find `BotDatabase` interface (~line 54), add two methods before `close()`:
|
||||
|
||||
```ts
|
||||
getCustomAvatarPath(botId: string): string | null;
|
||||
setCustomAvatarPath(botId: string, path: string | null): void;
|
||||
```
|
||||
|
||||
2. Find `migrateSchema()` (~line 66). After the `for (const col of profileCols)` loop, append:
|
||||
|
||||
```ts
|
||||
if (!names.includes("custom_avatar_path")) {
|
||||
db.exec("ALTER TABLE bot_instances ADD COLUMN custom_avatar_path TEXT");
|
||||
}
|
||||
```
|
||||
|
||||
3. In `createDatabase()` after the existing `prepare(...)` calls (~line 180), add:
|
||||
|
||||
```ts
|
||||
const selectCustomAvatar = db.prepare(
|
||||
`SELECT custom_avatar_path FROM bot_instances WHERE id = ?`,
|
||||
);
|
||||
const updateCustomAvatar = db.prepare(
|
||||
`UPDATE bot_instances SET custom_avatar_path = ? WHERE id = ?`,
|
||||
);
|
||||
```
|
||||
|
||||
4. Inside the returned object, add (before `close()`):
|
||||
|
||||
```ts
|
||||
getCustomAvatarPath(botId) {
|
||||
const row = selectCustomAvatar.get(botId) as { custom_avatar_path: string | null } | undefined;
|
||||
return row?.custom_avatar_path ?? null;
|
||||
},
|
||||
|
||||
setCustomAvatarPath(botId, path) {
|
||||
updateCustomAvatar.run(path, botId);
|
||||
},
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npx vitest run src/data/database.test.ts`
|
||||
Expected: PASS — all tests including the new one
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/data/database.ts src/data/database.test.ts
|
||||
git commit -m "feat(db): custom_avatar_path column + accessors"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Avatar storage helper
|
||||
|
||||
**Files:**
|
||||
- Create: `src/data/avatars.ts`
|
||||
- Create: `src/data/avatars.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
Create `src/data/avatars.test.ts`:
|
||||
|
||||
```ts
|
||||
import { describe, it, expect, beforeEach } from "vitest";
|
||||
import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { createAvatarStore } from "./avatars.js";
|
||||
|
||||
let dir: string;
|
||||
|
||||
beforeEach(() => {
|
||||
dir = mkdtempSync(join(tmpdir(), "avatar-test-"));
|
||||
});
|
||||
|
||||
describe("createAvatarStore", () => {
|
||||
it("write returns a relative path under the store dir", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
const buf = Buffer.from("fake-png");
|
||||
const rel = store.write("bot-1", "image/png", buf);
|
||||
expect(rel).toBe("bot-1.png");
|
||||
expect(readFileSync(join(dir, "bot-1.png")).equals(buf)).toBe(true);
|
||||
});
|
||||
|
||||
it("write picks correct extension for jpeg / webp", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
expect(store.write("a", "image/jpeg", Buffer.from(""))).toBe("a.jpg");
|
||||
expect(store.write("b", "image/webp", Buffer.from(""))).toBe("b.webp");
|
||||
});
|
||||
|
||||
it("write rejects unsupported MIME types", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
expect(() => store.write("c", "image/gif", Buffer.from(""))).toThrow(
|
||||
/unsupported/i,
|
||||
);
|
||||
});
|
||||
|
||||
it("read returns the bytes for an existing file", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
store.write("bot-1", "image/png", Buffer.from("hello"));
|
||||
const buf = store.read("bot-1.png");
|
||||
expect(buf?.equals(Buffer.from("hello"))).toBe(true);
|
||||
});
|
||||
|
||||
it("read returns null when path is missing", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
expect(store.read("missing.png")).toBeNull();
|
||||
});
|
||||
|
||||
it("remove deletes the file (idempotent)", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
store.write("bot-1", "image/png", Buffer.from("x"));
|
||||
store.remove("bot-1.png");
|
||||
expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
|
||||
expect(() => store.remove("bot-1.png")).not.toThrow();
|
||||
});
|
||||
|
||||
it("write replaces any existing file for the same botId regardless of old extension", () => {
|
||||
const store = createAvatarStore(dir);
|
||||
store.write("bot-1", "image/png", Buffer.from("old"));
|
||||
const rel = store.write("bot-1", "image/jpeg", Buffer.from("new"));
|
||||
expect(rel).toBe("bot-1.jpg");
|
||||
expect(existsSync(join(dir, "bot-1.png"))).toBe(false);
|
||||
expect(existsSync(join(dir, "bot-1.jpg"))).toBe(true);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npx vitest run src/data/avatars.test.ts`
|
||||
Expected: FAIL — module not found
|
||||
|
||||
- [ ] **Step 3: Implement the store**
|
||||
|
||||
Create `src/data/avatars.ts`:
|
||||
|
||||
```ts
|
||||
import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, existsSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
|
||||
const MIME_TO_EXT: Record<string, string> = {
|
||||
"image/png": "png",
|
||||
"image/jpeg": "jpg",
|
||||
"image/webp": "webp",
|
||||
};
|
||||
|
||||
export interface AvatarStore {
|
||||
/** Returns the relative path written (e.g. "bot-1.png"). */
|
||||
write(botId: string, mime: string, buffer: Buffer): string;
|
||||
read(relPath: string): Buffer | null;
|
||||
remove(relPath: string): void;
|
||||
getDir(): string;
|
||||
}
|
||||
|
||||
export function createAvatarStore(dir: string): AvatarStore {
|
||||
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
|
||||
return {
|
||||
write(botId, mime, buffer) {
|
||||
const ext = MIME_TO_EXT[mime];
|
||||
if (!ext) throw new Error(`unsupported avatar MIME: ${mime}`);
|
||||
// Remove any existing avatar for this bot regardless of extension.
|
||||
for (const name of readdirSync(dir)) {
|
||||
if (name.startsWith(`${botId}.`)) rmSync(join(dir, name), { force: true });
|
||||
}
|
||||
const rel = `${botId}.${ext}`;
|
||||
writeFileSync(join(dir, rel), buffer);
|
||||
return rel;
|
||||
},
|
||||
read(relPath) {
|
||||
const full = join(dir, relPath);
|
||||
if (!existsSync(full)) return null;
|
||||
return readFileSync(full);
|
||||
},
|
||||
remove(relPath) {
|
||||
rmSync(join(dir, relPath), { force: true });
|
||||
},
|
||||
getDir() {
|
||||
return dir;
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify it passes**
|
||||
|
||||
Run: `npx vitest run src/data/avatars.test.ts`
|
||||
Expected: PASS — all 7 tests
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add src/data/avatars.ts src/data/avatars.test.ts
|
||||
git commit -m "feat(data): avatar file store helper"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 3: BotProfileManager — custom avatar precedence
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/bot/profile.ts`
|
||||
- Create: `src/bot/profile.test.ts`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
Create `src/bot/profile.test.ts`:
|
||||
|
||||
```ts
|
||||
import { describe, it, expect, beforeEach, vi } from "vitest";
|
||||
import { BotProfileManager } from "./profile.js";
|
||||
import type { TS3Client } from "../ts-protocol/client.js";
|
||||
|
||||
function makeMockTs(): TS3Client & {
|
||||
uploadCalls: Buffer[];
|
||||
clearCalls: number;
|
||||
} {
|
||||
const calls: Buffer[] = [];
|
||||
let clears = 0;
|
||||
const ts: any = {
|
||||
uploadCalls: calls,
|
||||
get clearCalls() { return clears; },
|
||||
getHost: () => "127.0.0.1",
|
||||
getHttpQuery: () => null,
|
||||
fileTransferInitUpload: vi.fn().mockResolvedValue({}),
|
||||
uploadFileData: vi.fn().mockImplementation(async (_h, _i, stream: any) => {
|
||||
const chunks: Buffer[] = [];
|
||||
for await (const c of stream) chunks.push(c as Buffer);
|
||||
calls.push(Buffer.concat(chunks));
|
||||
}),
|
||||
fileTransferDeleteFile: vi.fn().mockResolvedValue(undefined),
|
||||
sendCommandNoWait: vi.fn().mockImplementation(async (cmd: string) => {
|
||||
if (/client_flag_avatar=$/.test(cmd)) clears++;
|
||||
}),
|
||||
};
|
||||
return ts;
|
||||
}
|
||||
|
||||
const noopLogger: any = { child: () => noopLogger, info: () => {}, debug: () => {}, warn: () => {}, error: () => {} };
|
||||
|
||||
const cfgOn = { avatarEnabled: true, descriptionEnabled: false, nicknameEnabled: false, awayStatusEnabled: false, channelDescEnabled: false, nowPlayingMsgEnabled: false };
|
||||
const cfgOff = { ...cfgOn, avatarEnabled: false };
|
||||
|
||||
describe("BotProfileManager custom avatar precedence", () => {
|
||||
let ts: ReturnType<typeof makeMockTs>;
|
||||
beforeEach(() => { ts = makeMockTs(); });
|
||||
|
||||
it("on stop with custom avatar set + sync on, uploads custom (does not clear)", async () => {
|
||||
const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
|
||||
const custom = Buffer.from([1, 2, 3, 4]);
|
||||
pm.setCustomAvatar(custom);
|
||||
await pm.onSongChange(null);
|
||||
expect(ts.uploadCalls.at(-1)?.equals(custom)).toBe(true);
|
||||
expect(ts.clearCalls).toBe(0);
|
||||
});
|
||||
|
||||
it("on stop with no custom avatar, falls back to clear", async () => {
|
||||
const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
|
||||
await pm.onSongChange(null);
|
||||
expect(ts.clearCalls).toBe(1);
|
||||
expect(ts.uploadCalls.length).toBe(0);
|
||||
});
|
||||
|
||||
it("on connect with sync off + custom avatar set, applies custom immediately", async () => {
|
||||
const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
|
||||
pm.setCustomAvatar(Buffer.from([9, 9]));
|
||||
await pm.onConnect();
|
||||
expect(ts.uploadCalls.length).toBe(1);
|
||||
expect(ts.uploadCalls[0].equals(Buffer.from([9, 9]))).toBe(true);
|
||||
});
|
||||
|
||||
it("on connect with sync off + no custom avatar, does not touch avatar", async () => {
|
||||
const pm = new BotProfileManager(ts as any, noopLogger, cfgOff, "Bot");
|
||||
await pm.onConnect();
|
||||
expect(ts.uploadCalls.length).toBe(0);
|
||||
expect(ts.clearCalls).toBe(0);
|
||||
});
|
||||
|
||||
it("setCustomAvatar(null) makes subsequent onSongChange(null) clear again", async () => {
|
||||
const pm = new BotProfileManager(ts as any, noopLogger, cfgOn, "Bot");
|
||||
pm.setCustomAvatar(Buffer.from([1]));
|
||||
pm.setCustomAvatar(null);
|
||||
await pm.onSongChange(null);
|
||||
expect(ts.clearCalls).toBe(1);
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `npx vitest run src/bot/profile.test.ts`
|
||||
Expected: FAIL — `pm.setCustomAvatar is not a function` and/or `onConnect` not exported
|
||||
|
||||
- [ ] **Step 3: Look at the existing profile.ts to understand `onConnect` shape**
|
||||
|
||||
Run: `grep -n 'onConnect\|public async\|public ' src/bot/profile.ts | head -10`
|
||||
|
||||
`onConnect` likely already exists; if not, locate where reconnect resets state. Add or extend it.
|
||||
|
||||
- [ ] **Step 4: Implement `customAvatar`, `setCustomAvatar`, `applyIdleAvatar`; modify `clearAvatar` and `onConnect`**
|
||||
|
||||
In `src/bot/profile.ts`:
|
||||
|
||||
1. Inside the class, add fields next to `defaultNickname` (around line 27):
|
||||
|
||||
```ts
|
||||
private customAvatar: Buffer | null = null;
|
||||
```
|
||||
|
||||
2. After the `constructor`, add:
|
||||
|
||||
```ts
|
||||
/** Set/clear the persistent idle avatar. Pass null to remove. */
|
||||
setCustomAvatar(buffer: Buffer | null): void {
|
||||
this.customAvatar = buffer;
|
||||
}
|
||||
```
|
||||
|
||||
3. Find `clearAvatar()` (~line 173). Change the body so that if `this.customAvatar` is set, we upload it instead of clearing the flag. Replace the existing method with:
|
||||
|
||||
```ts
|
||||
private async clearAvatar(gen: number): Promise<void> {
|
||||
if (this.customAvatar && this.customAvatar.length > 0) {
|
||||
await this.applyIdleAvatar(gen);
|
||||
return;
|
||||
}
|
||||
try {
|
||||
await this.withTimeout(
|
||||
this.tsClient.fileTransferDeleteFile(0n, ["/avatar"]),
|
||||
FILE_TRANSFER_TIMEOUT_MS,
|
||||
);
|
||||
} catch {
|
||||
// File may not exist or transfer timed out — that's fine
|
||||
}
|
||||
if (this.generation !== gen) return;
|
||||
try {
|
||||
await this.tsClient.sendCommandNoWait("clientupdate client_flag_avatar=");
|
||||
} catch (err) {
|
||||
this.handleFeatureError("avatar", err);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. Add a new private method right below `clearAvatar`:
|
||||
|
||||
```ts
|
||||
private async applyIdleAvatar(gen: number): Promise<void> {
|
||||
if (!this.customAvatar || this.customAvatar.length === 0) return;
|
||||
if (this.permDenied.avatar) return;
|
||||
try {
|
||||
await this.withTimeout(this.doAvatarUpload(this.customAvatar), FILE_TRANSFER_TIMEOUT_MS);
|
||||
if (this.generation !== gen) return;
|
||||
this.logger.info({ bytes: this.customAvatar.length }, "Idle (custom) avatar applied");
|
||||
} catch (err) {
|
||||
this.handleFeatureError("avatar", err);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
5. Find `onConnect` (the existing method that resets per-feature flags). At its end, immediately after the `permDenied` reset, add:
|
||||
|
||||
```ts
|
||||
if (!this.config.avatarEnabled && this.customAvatar) {
|
||||
const gen = ++this.generation;
|
||||
void this.applyIdleAvatar(gen);
|
||||
}
|
||||
```
|
||||
|
||||
If `onConnect` does not exist as a method, search for where reconnect resets `permDenied` and add the block there.
|
||||
|
||||
- [ ] **Step 5: Run test to verify it passes**
|
||||
|
||||
Run: `npx vitest run src/bot/profile.test.ts`
|
||||
Expected: PASS — 5/5
|
||||
|
||||
Run also: `npx vitest run src/audio src/data src/bot` — confirm no regressions.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/bot/profile.ts src/bot/profile.test.ts
|
||||
git commit -m "feat(profile): custom avatar with idle/playback precedence"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Wire avatar load on bot start
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/bot/instance.ts`
|
||||
- Modify: `src/bot/manager.ts` (if it constructs the instance)
|
||||
- Modify: `src/index.ts`
|
||||
|
||||
- [ ] **Step 1: Confirm where `BotProfileManager` is constructed and how `BotInstance` receives DB**
|
||||
|
||||
Run: `grep -n 'new BotProfileManager\|profileManager =\|database\|botDb' src/bot/instance.ts src/bot/manager.ts | head -20`
|
||||
|
||||
Identify the BotInstance constructor params and verify that the DB and the avatar dir can flow in.
|
||||
|
||||
- [ ] **Step 2: Add `AVATAR_DIR` constant + `avatarStore` to `src/index.ts`**
|
||||
|
||||
Find where `COOKIE_DIR` / `createCookieStore` are set up (~line 48 in src/index.ts) and add directly after:
|
||||
|
||||
```ts
|
||||
const AVATAR_DIR = process.env.AVATAR_DIR ?? join(DATA_DIR, "avatars");
|
||||
const avatarStore = createAvatarStore(AVATAR_DIR);
|
||||
```
|
||||
|
||||
(import as needed: `import { createAvatarStore } from "./data/avatars.js";`)
|
||||
|
||||
Pass `avatarStore` through to whatever constructs `BotManager` (and from there to `BotInstance`).
|
||||
|
||||
- [ ] **Step 3: In `BotInstance`, after `profileManager` is created, load the avatar from disk if any**
|
||||
|
||||
In `src/bot/instance.ts`, after `this.profileManager = new BotProfileManager(...)`:
|
||||
|
||||
```ts
|
||||
const relPath = this.botDb.getCustomAvatarPath(this.id);
|
||||
if (relPath) {
|
||||
const buf = this.avatarStore.read(relPath);
|
||||
if (buf) this.profileManager.setCustomAvatar(buf);
|
||||
}
|
||||
```
|
||||
|
||||
(Add `private botDb: BotDatabase` and `private avatarStore: AvatarStore` constructor params; thread them down from `BotManager.createBot()` / `BotManager` constructor.)
|
||||
|
||||
- [ ] **Step 4: Add `getProfileManager()` accessor if not present**
|
||||
|
||||
If grep already shows `getProfileManager(): BotProfileManager`, skip. Otherwise add a public method that returns `this.profileManager`.
|
||||
|
||||
- [ ] **Step 5: Build and run the existing tests**
|
||||
|
||||
Run: `npx tsc --noEmit`
|
||||
Expected: no TS errors
|
||||
|
||||
Run: `npm test`
|
||||
Expected: all green
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/index.ts src/bot/instance.ts src/bot/manager.ts
|
||||
git commit -m "feat(bot): load custom avatar on instance startup"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 5: REST endpoints for avatar upload / fetch / delete
|
||||
|
||||
**Files:**
|
||||
- Modify: `src/web/server.ts` (json size limit)
|
||||
- Modify: `src/web/api/bot.ts`
|
||||
|
||||
- [ ] **Step 1: Bump express.json size limit**
|
||||
|
||||
In `src/web/server.ts`, find `app.use(express.json())` (~line 46) and change to:
|
||||
|
||||
```ts
|
||||
app.use(express.json({ limit: "400kb" }));
|
||||
```
|
||||
|
||||
(Avatar payload is base64-encoded ≤200 KB → ~270 KB on the wire; 400 KB gives margin.)
|
||||
|
||||
- [ ] **Step 2: Write a failing API test (use supertest if not present, otherwise inline fetch)**
|
||||
|
||||
Run: `grep -E '"supertest"|"vitest"' package.json`
|
||||
|
||||
If supertest is not present, write the test using `node:http` raw client or skip API integration test and rely on manual + unit tests on Task 7. Don't add new deps unless approved.
|
||||
|
||||
If supertest IS present, add `src/web/api/bot.test.ts`:
|
||||
|
||||
```ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
import request from "supertest";
|
||||
import express from "express";
|
||||
import { createBotRouter } from "./bot.js";
|
||||
// ... build minimal app with mocked manager + DB + avatarStore
|
||||
```
|
||||
|
||||
If not present: skip Step 2, jump to Step 3 and verify by manual curl in Step 5.
|
||||
|
||||
- [ ] **Step 3: Add the three endpoints**
|
||||
|
||||
In `src/web/api/bot.ts`, modify the factory signature to accept `avatarStore` and `botDb`:
|
||||
|
||||
```ts
|
||||
export function createBotRouter(
|
||||
botManager: BotManager,
|
||||
config: BotConfig,
|
||||
configPath: string,
|
||||
logger: Logger,
|
||||
botDb: BotDatabase,
|
||||
avatarStore: AvatarStore,
|
||||
): Router {
|
||||
```
|
||||
|
||||
Inside the router, after the existing `/:id/config` GET, add:
|
||||
|
||||
```ts
|
||||
router.get("/:id/avatar", (req, res) => {
|
||||
const path = botDb.getCustomAvatarPath(req.params.id);
|
||||
if (!path) { res.status(404).end(); return; }
|
||||
const buf = avatarStore.read(path);
|
||||
if (!buf) { res.status(404).end(); return; }
|
||||
const ext = path.split(".").pop()!;
|
||||
const mime = ext === "png" ? "image/png" : ext === "webp" ? "image/webp" : "image/jpeg";
|
||||
res.set("Content-Type", mime);
|
||||
res.set("Cache-Control", "no-cache");
|
||||
res.send(buf);
|
||||
});
|
||||
|
||||
router.put("/:id/avatar", (req, res) => {
|
||||
const bot = botManager.getBot(req.params.id);
|
||||
if (!bot && !botDb.getBotInstances().some((b) => b.id === req.params.id)) {
|
||||
res.status(404).json({ error: "Bot not found" });
|
||||
return;
|
||||
}
|
||||
const { dataUrl } = req.body as { dataUrl?: string };
|
||||
if (typeof dataUrl !== "string") {
|
||||
res.status(400).json({ error: "dataUrl required" });
|
||||
return;
|
||||
}
|
||||
const m = /^data:(image\/(png|jpeg|webp));base64,(.+)$/.exec(dataUrl);
|
||||
if (!m) {
|
||||
res.status(400).json({ error: "dataUrl must be image/png|jpeg|webp base64" });
|
||||
return;
|
||||
}
|
||||
const mime = m[1];
|
||||
const buf = Buffer.from(m[3], "base64");
|
||||
if (buf.length > 200 * 1024) {
|
||||
res.status(413).json({ error: "avatar exceeds 200KB limit" });
|
||||
return;
|
||||
}
|
||||
const rel = avatarStore.write(req.params.id, mime, buf);
|
||||
botDb.setCustomAvatarPath(req.params.id, rel);
|
||||
bot?.getProfileManager().setCustomAvatar(buf);
|
||||
res.json({ path: rel });
|
||||
});
|
||||
|
||||
router.delete("/:id/avatar", (req, res) => {
|
||||
const path = botDb.getCustomAvatarPath(req.params.id);
|
||||
if (path) avatarStore.remove(path);
|
||||
botDb.setCustomAvatarPath(req.params.id, null);
|
||||
const bot = botManager.getBot(req.params.id);
|
||||
bot?.getProfileManager().setCustomAvatar(null);
|
||||
res.status(204).end();
|
||||
});
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Update the call site that constructs the router**
|
||||
|
||||
Search: `grep -n 'createBotRouter' src/`
|
||||
|
||||
In the call site (likely `src/web/server.ts` or `src/index.ts`), pass the new args. Fix the call signature.
|
||||
|
||||
- [ ] **Step 5: Manual smoke test**
|
||||
|
||||
Run: `npm run build && npm run start`
|
||||
In another terminal:
|
||||
|
||||
```bash
|
||||
# create a small valid PNG (1x1) base64
|
||||
B64=$(node -e "console.log(Buffer.from([137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,0,1,0,0,0,1,8,2,0,0,0,144,119,83,222,0,0,0,12,73,68,65,84,8,153,99,248,255,255,63,0,5,254,2,254,205,250,236,184,0,0,0,0,73,69,78,68,174,66,96,130]).toString('base64'))")
|
||||
|
||||
curl -X PUT http://localhost:3000/api/bot/<BOT_ID>/avatar \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "{\"dataUrl\":\"data:image/png;base64,$B64\"}"
|
||||
|
||||
curl http://localhost:3000/api/bot/<BOT_ID>/avatar -o /tmp/x.png
|
||||
file /tmp/x.png
|
||||
|
||||
curl -X DELETE http://localhost:3000/api/bot/<BOT_ID>/avatar -i
|
||||
```
|
||||
|
||||
Expected: PUT returns `{"path":"<id>.png"}`, GET returns the bytes, DELETE returns 204.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add src/web/server.ts src/web/api/bot.ts src/index.ts
|
||||
git commit -m "feat(api): /api/bot/:id/avatar GET/PUT/DELETE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Frontend — `AvatarUpload.vue` component
|
||||
|
||||
**Files:**
|
||||
- Create: `web/src/components/AvatarUpload.vue`
|
||||
|
||||
- [ ] **Step 1: Create the component**
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<div class="avatar-upload">
|
||||
<div class="preview" :class="{ empty: !previewUrl }">
|
||||
<img v-if="previewUrl" :src="previewUrl" alt="avatar" />
|
||||
<Icon v-else icon="mdi:account-circle-outline" />
|
||||
</div>
|
||||
<div class="actions">
|
||||
<input
|
||||
ref="fileInput"
|
||||
type="file"
|
||||
accept="image/png,image/jpeg,image/webp"
|
||||
class="hidden"
|
||||
@change="onFile"
|
||||
/>
|
||||
<button type="button" class="btn-sm" @click="fileInput?.click()">
|
||||
{{ previewUrl ? '更换' : '上传' }}
|
||||
</button>
|
||||
<button v-if="previewUrl" type="button" class="btn-sm btn-danger" @click="clear">
|
||||
删除
|
||||
</button>
|
||||
</div>
|
||||
<p v-if="error" class="hint error">{{ error }}</p>
|
||||
<p v-else class="hint">PNG / JPG / WebP，≤200 KB</p>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import { ref, watch } from 'vue';
|
||||
import { Icon } from '@iconify/vue';
|
||||
|
||||
const props = defineProps<{ modelValue: string | null }>();
|
||||
const emit = defineEmits<{ 'update:modelValue': [value: string | null] }>();
|
||||
|
||||
const previewUrl = ref<string | null>(props.modelValue);
|
||||
const error = ref<string | null>(null);
|
||||
const fileInput = ref<HTMLInputElement | null>(null);
|
||||
|
||||
watch(() => props.modelValue, (v) => { previewUrl.value = v; });
|
||||
|
||||
function onFile(ev: Event) {
|
||||
const file = (ev.target as HTMLInputElement).files?.[0];
|
||||
if (!file) return;
|
||||
if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
|
||||
error.value = '仅支持 PNG / JPG / WebP';
|
||||
return;
|
||||
}
|
||||
if (file.size > 200 * 1024) {
|
||||
error.value = `图片 ${(file.size / 1024).toFixed(0)} KB 超过 200 KB 上限`;
|
||||
return;
|
||||
}
|
||||
error.value = null;
|
||||
const reader = new FileReader();
|
||||
reader.onload = () => {
|
||||
const dataUrl = reader.result as string;
|
||||
previewUrl.value = dataUrl;
|
||||
emit('update:modelValue', dataUrl);
|
||||
};
|
||||
reader.readAsDataURL(file);
|
||||
}
|
||||
|
||||
function clear() {
|
||||
previewUrl.value = null;
|
||||
emit('update:modelValue', null);
|
||||
if (fileInput.value) fileInput.value.value = '';
|
||||
}
|
||||
</script>
|
||||
|
||||
<style lang="scss" scoped>
|
||||
.avatar-upload { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
|
||||
.preview {
|
||||
width: 80px; height: 80px; border-radius: 50%;
|
||||
background: var(--bg-card); display: flex; align-items: center; justify-content: center;
|
||||
overflow: hidden;
|
||||
img { width: 100%; height: 100%; object-fit: cover; }
|
||||
&.empty :deep(svg) { font-size: 48px; opacity: 0.4; }
|
||||
}
|
||||
.actions { display: flex; gap: 8px; }
|
||||
.hidden { display: none; }
|
||||
.hint { font-size: 12px; opacity: 0.6; margin: 0; }
|
||||
.hint.error { color: var(--color-danger, #e85060); opacity: 1; }
|
||||
.btn-danger { color: var(--color-danger, #e85060); }
|
||||
</style>
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify the component compiles**
|
||||
|
||||
Run: `cd web && npx vue-tsc --noEmit`
|
||||
Expected: no errors
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/components/AvatarUpload.vue
|
||||
git commit -m "feat(web): AvatarUpload component"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Wire AvatarUpload into Settings.vue (create + edit + standalone row)
|
||||
|
||||
**Files:**
|
||||
- Modify: `web/src/views/Settings.vue`
|
||||
|
||||
- [ ] **Step 1: Read the relevant Settings.vue regions**
|
||||
|
||||
```bash
|
||||
grep -n '同步头像\|openEditBot\|saveEditBot\|createBot\|create-bot\|profile-features\|features.find' web/src/views/Settings.vue | head -20
|
||||
```
|
||||
|
||||
Identify:
|
||||
- Create-bot form template region (`<div class="create-bot">` block)
|
||||
- Edit-bot modal/dialog template region
|
||||
- The profile features table where `avatarEnabled` row lives
|
||||
|
||||
- [ ] **Step 2: Add component import + reactive state for avatar dataUrl on the create-bot form**
|
||||
|
||||
In the script setup region, near other `newBot*` refs:
|
||||
|
||||
```ts
|
||||
import AvatarUpload from '../components/AvatarUpload.vue';
|
||||
const newBotAvatar = ref<string | null>(null);
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Insert `<AvatarUpload v-model="newBotAvatar" />` into the create-bot form template**
|
||||
|
||||
In the `<div class="create-bot">` block, right before `<button class="btn-primary" @click="createBot">创建</button>`, add:
|
||||
|
||||
```vue
|
||||
<div class="form-row">
|
||||
<label>自定义头像（可选）</label>
|
||||
<AvatarUpload v-model="newBotAvatar" />
|
||||
</div>
|
||||
```
|
||||
|
||||
- [ ] **Step 4: After successful `createBot()`, PUT the avatar if set**
|
||||
|
||||
Find the `createBot` async function. After the POST resolves and the bot id is known (`res.data.id` or similar), append:
|
||||
|
||||
```ts
|
||||
if (newBotAvatar.value) {
|
||||
await axios.put(`/api/bot/${res.data.id}/avatar`, { dataUrl: newBotAvatar.value });
|
||||
}
|
||||
newBotAvatar.value = null;
|
||||
```
|
||||
|
||||
- [ ] **Step 5: Add an "自定义头像" row in the per-bot profile features table**
|
||||
|
||||
Find the profile-features table render (look for the `features` array iteration). The cleanest path: add a custom row OUTSIDE the array (since it isn't a boolean toggle). Right before `</template>` of the bot row, add:
|
||||
|
||||
```vue
|
||||
<div class="feature-row">
|
||||
<div class="feature-label">自定义头像</div>
|
||||
<div class="feature-control">
|
||||
<CustomAvatarRow :bot-id="bot.id" />
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Where `CustomAvatarRow` is an inline-defined component or a small file `web/src/components/CustomAvatarRow.vue` that:
|
||||
- Mounts → `axios.get(/api/bot/<id>/avatar, { responseType: 'blob' })` → previews if 200, ignore 404
|
||||
- Wraps `<AvatarUpload>` and on `update:modelValue`:
|
||||
- If string → `axios.put(/avatar, { dataUrl })`
|
||||
- If null → `axios.delete(/avatar)`
|
||||
|
||||
Create `web/src/components/CustomAvatarRow.vue` with that logic; keep its body small (~50 lines).
|
||||
|
||||
- [ ] **Step 6: Build and visually verify**
|
||||
|
||||
Run: `cd web && npm run build` → no errors. Then `npm run dev` → open create-instance, upload PNG, create — verify the avatar appears on the bot in TS3 once it connects. Check edit/Settings flow.
|
||||
|
||||
- [ ] **Step 7: Commit**
|
||||
|
||||
```bash
|
||||
git add web/src/views/Settings.vue web/src/components/CustomAvatarRow.vue
|
||||
git commit -m "feat(web): custom avatar in create-bot + Settings"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Open PR
|
||||
|
||||
- [ ] **Step 1: Push the branch**
|
||||
|
||||
```bash
|
||||
git checkout -b feat/custom-bot-avatar
|
||||
git push -u origin feat/custom-bot-avatar
|
||||
```
|
||||
|
||||
(If commits were already on `main`, instead create the branch from the first relevant commit and reset main: `git branch feat/custom-bot-avatar HEAD && git reset --hard origin/main && git checkout feat/custom-bot-avatar`. The exact sequence depends on the working state when starting.)
|
||||
|
||||
- [ ] **Step 2: Create the PR**
|
||||
|
||||
```bash
|
||||
gh pr create --title "feat(profile): custom bot avatar" --body "Closes part of #51 (avatar half).
|
||||
|
||||
## Summary
|
||||
- New /api/bot/:id/avatar GET/PUT/DELETE
|
||||
- BotProfileManager: custom avatar acts as idle image; cover sync still wins during playback when avatarEnabled=true
|
||||
- AvatarUpload component used in create-bot form and Settings per-bot row
|
||||
- Bump express.json limit to 400kb to allow base64 payload
|
||||
|
||||
## Behavior matrix
|
||||
| avatarEnabled | custom set | playing | stopped |
|
||||
|---|---|---|---|
|
||||
| ✓ | ✓ | cover | restore custom |
|
||||
| ✓ | ✗ | cover | clear |
|
||||
| ✗ | ✓ | custom | custom |
|
||||
| ✗ | ✗ | no-op | no-op |
|
||||
|
||||
## Test plan
|
||||
- [x] vitest covers DB, avatar store, ProfileManager precedence
|
||||
- [x] Manual: upload PNG → bot avatar shows; play song → cover; stop → custom; delete → cleared
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Self-Review Checklist
|
||||
|
||||
- [x] Each spec section has at least one task: precedence matrix → Task 3; storage → Task 2; DB → Task 1; API → Task 5; UI → Task 6+7
|
||||
- [x] No "TBD" / "fill in" / "implement later" text in any step
|
||||
- [x] Type names consistent: `AvatarStore` / `createAvatarStore` / `getCustomAvatarPath` / `setCustomAvatarPath` / `setCustomAvatar` (singular per call site)
|
||||
- [x] All code blocks compile under existing TS/Vue config (express 5, vitest, vue 3 + iconify already in use)
|
||||
Reference in new issue
Block a user