Initial import: Music_Server, MusicFree, catalog-sync

2026-05-23 16:51:14 +08:00
commit 069af30dba
847 changed files with 179878 additions and 0 deletions
@@ -0,0 +1,70 @@
+# Catalog Sync 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:** Add an independent catalog-sync CLI that harvests playlist pools, persists playlist/song/artist relationships, and automates deduplicated downloads.
+
+**Architecture:** Implement a new `musicdl.catalogsync` package with a SQLite repository layer, per-source collectors, playlist-sync services, and a CLI wrapper that reuses existing `musicdl` source clients for parsing and downloading. Model downloaded media as logical file assets plus storage locations so local paths work now and cloud/object-storage locations fit later.
+
+**Tech Stack:** Python stdlib (`sqlite3`, `json`, `pathlib`, `hashlib`, `shutil`), `click`, existing `musicdl` source clients, `requests`, `unittest`
+
+---
+
+### Task 1: Add failing tests for schema and normalization helpers
+
+**Files:**
+- Create: `tests/catalogsync/test_db.py`
+- Create: `tests/catalogsync/test_models.py`
+- Create: `tests/catalogsync/fixtures/`
+
+- [ ] Write failing tests for schema creation and song dedupe helpers.
+- [ ] Run the focused unittest commands and verify they fail for missing modules.
+- [ ] Implement the minimal schema and helper modules to satisfy the tests.
+- [ ] Re-run the focused tests and verify they pass.
+
+### Task 2: Add failing tests for collector parsing helpers
+
+**Files:**
+- Create: `tests/catalogsync/test_collectors.py`
+- Create: `musicdl/catalogsync/collectors/`
+
+- [ ] Write fixture-driven failing tests for NetEase, QQ, and Kuwo collector parsing helpers.
+- [ ] Run the focused unittest commands and verify they fail.
+- [ ] Implement minimal collector modules and parsing helpers.
+- [ ] Re-run the focused tests and verify they pass.
+
+### Task 3: Implement repository, sync services, and download planner
+
+**Files:**
+- Create: `musicdl/catalogsync/db.py`
+- Create: `musicdl/catalogsync/repository.py`
+- Create: `musicdl/catalogsync/services.py`
+- Create: `musicdl/catalogsync/downloader.py`
+
+- [ ] Write failing service tests for playlist sync, derived artist sync, and download dedupe.
+- [ ] Run the focused unittest commands and verify they fail.
+- [ ] Implement the repository and service layer.
+- [ ] Re-run the focused tests and verify they pass.
+
+### Task 4: Implement CLI and package integration
+
+**Files:**
+- Create: `musicdl/catalogsync/cli.py`
+- Modify: `setup.py`
+- Modify: `musicdl/__init__.py`
+
+- [ ] Write failing CLI smoke tests around argument parsing and DB initialization.
+- [ ] Run the focused unittest commands and verify they fail.
+- [ ] Implement the CLI entrypoint and wire a new console script.
+- [ ] Re-run the focused tests and verify they pass.
+
+### Task 5: Verify end-to-end behavior and document usage
+
+**Files:**
+- Create: `docs/catalogsync.md`
+- Modify: `README.md`
+
+- [ ] Run the full focused unittest suite for `tests/catalogsync`.
+- [ ] Run a manual CLI smoke flow against a temporary SQLite DB.
+- [ ] Update user-facing docs with command examples and caveats.
+- [ ] Re-run final verification commands and capture results.