4.8 KiB
Transfer Module Refactor Implementation Plan
For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Refactor the fast-transfer module so the website has one coherent transfer flow, with cleaner frontend boundaries, a cleaner backend session model, and route generation that matches the site router mode.
Architecture: Keep the current product behavior of “authenticated sender page + public receiver page + backend signaling only”, but split protocol/state concerns away from route UI. On the frontend, centralize transfer URL building, protocol message helpers, and sender/receiver session orchestration so the pages become thinner. On the backend, split the current monolithic in-memory service into small transfer domain objects while preserving the same HTTP API.
Tech Stack: Vite 6, React 19, TypeScript, Spring Boot 3.3, Java 17, node:test, JUnit 5, MockMvc.
Task 1: Lock down route-aware transfer URLs
Files:
-
Modify:
front/src/pages/transfer-state.test.ts -
Modify:
front/src/pages/transfer-state.ts -
Modify:
front/src/App.tsx -
Step 1: Write the failing test
Add tests asserting:
-
browser mode share URL =>
https://host/t?session=abc -
hash mode share URL =>
https://host/#/t?session=abc -
Step 2: Run test to verify it fails
Run: cd front && npm run test
- Step 3: Write minimal implementation
Introduce a router-mode-aware URL builder and update the app router to respect VITE_ROUTER_MODE.
- Step 4: Run test to verify it passes
Run: cd front && npm run test
Task 2: Extract shared frontend transfer protocol and session helpers
Files:
-
Create:
front/src/lib/transfer-protocol.ts -
Create:
front/src/lib/transfer-runtime.ts -
Modify:
front/src/lib/transfer.ts -
Modify:
front/src/pages/Transfer.tsx -
Modify:
front/src/pages/TransferReceive.tsx -
Step 1: Write the failing test
Add tests for pure protocol helpers:
-
sender meta message encoding
-
receiver payload parsing
-
progress/URL helpers that no longer live inside page components
-
Step 2: Run test to verify it fails
Run: cd front && npm run test
- Step 3: Write minimal implementation
Move WebRTC protocol constants, message parsing/encoding, and repeated session setup logic out of page components. Keep pages focused on route UI and user actions.
- Step 4: Run test to verify it passes
Run: cd front && npm run test
Task 3: Thin down backend transfer service
Files:
-
Create:
backend/src/main/java/com/yoyuzh/transfer/TransferRole.java -
Create:
backend/src/main/java/com/yoyuzh/transfer/TransferSession.java -
Create:
backend/src/main/java/com/yoyuzh/transfer/TransferSessionStore.java -
Modify:
backend/src/main/java/com/yoyuzh/transfer/TransferService.java -
Add/Modify Test:
backend/src/test/java/com/yoyuzh/transfer/TransferControllerIntegrationTest.java -
Step 1: Write the failing test
Add focused tests that lock current session behavior:
-
pickup code validation
-
receiver join only emits one
peer-joined -
signals route to the opposite queue
-
Step 2: Run test to verify it fails
Run: cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test
- Step 3: Write minimal implementation
Extract session state and store responsibilities from TransferService, leaving TransferService as orchestration only.
- Step 4: Run test to verify it passes
Run: cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test
Task 4: Reconnect the module cleanly to the site
Files:
-
Modify:
front/src/pages/Overview.tsx -
Modify:
front/src/components/layout/Layout.tsx -
Modify:
scripts/oss-deploy-lib.mjs -
Modify:
scripts/oss-deploy-lib.test.mjs -
Step 1: Verify transfer entry points still match the refactored routes
Confirm overview CTA, sidebar nav, and public receiver route all align on the same URL helpers.
- Step 2: Verify the deployment aliases still cover the public transfer route
Run: node scripts/oss-deploy-lib.test.mjs
- Step 3: Apply any minimal cleanup
Remove duplicated hardcoded route strings if they remain.
Task 5: Full verification
Files:
-
No code changes required unless failures appear
-
Step 1: Run frontend tests
Run: cd front && npm run test
- Step 2: Run frontend typecheck
Run: cd front && npm run lint
- Step 3: Run frontend build
Run: cd front && npm run build
- Step 4: Run backend tests
Run: cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test
- Step 5: Run backend package
Run: cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn package