my_site/docs/superpowers/plans/2026-03-20-file-share-and-transfer-save.md

File Share And Transfer Save 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: Let users create URL-based netdisk share links that another logged-in user can import into their own netdisk, and let transfer receivers save received files directly into their netdisk.

Architecture: Add a small share-link domain under backend/src/main/java/com/yoyuzh/files so the backend can issue secret share tokens, expose share metadata, and import the shared file into the recipient’s storage without routing the payload through the browser. On the frontend, add share actions to the Files page, a public /share/:token import page, and a reusable netdisk-upload helper that Transfer receive actions can call to persist downloaded blobs into the current user’s storage.

Tech Stack: Spring Boot 3.3.8 + Java 17 + JPA, React 19 + Vite + TypeScript, existing file storage abstraction, existing frontend Node test runner and Maven tests.

---

Task 1: Define Backend Share-Link API Contract

Files:

• Modify: backend/src/test/java/com/yoyuzh/files/FileServiceTest.java

• Create: backend/src/test/java/com/yoyuzh/files/FileShareControllerIntegrationTest.java

• Step 1: Write failing tests for creating a share link, reading share metadata, and importing a shared file into another user’s netdisk

• Step 2: Run cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test to verify the new tests fail

• Step 3: Implement the minimal backend API surface to satisfy the tests

• Step 4: Re-run cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test

Task 2: Add Backend Share-Link Persistence And Import Logic

Files:

• Create: backend/src/main/java/com/yoyuzh/files/FileShareLink.java

• Create: backend/src/main/java/com/yoyuzh/files/FileShareLinkRepository.java

• Create: backend/src/main/java/com/yoyuzh/files/CreateFileShareLinkResponse.java

• Create: backend/src/main/java/com/yoyuzh/files/FileShareDetailsResponse.java

• Create: backend/src/main/java/com/yoyuzh/files/ImportSharedFileRequest.java

• Modify: backend/src/main/java/com/yoyuzh/files/FileController.java

• Modify: backend/src/main/java/com/yoyuzh/files/FileService.java

• Step 1: Add the share-link entity/repository and DTOs

• Step 2: Extend FileService with share creation, share lookup, and recipient import logic

• Step 3: Expose authenticated create/import endpoints and a public share-details endpoint in FileController

• Step 4: Keep directory handling explicit; only add behavior required by the tests

Task 3: Add Frontend Share-Link Helpers And Tests

Files:

• Create: front/src/lib/file-share.ts

• Create: front/src/lib/file-share.test.ts

• Modify: front/src/lib/types.ts

• Step 1: Write failing frontend helper tests for share-link building/parsing and import payload helpers

• Step 2: Run cd front && npm run test to verify failure

• Step 3: Implement minimal share helper wrappers against the backend API

• Step 4: Re-run cd front && npm run test

Task 4: Add Public Share Import Page

Files:

• Create: front/src/pages/FileShare.tsx

• Modify: front/src/App.tsx

• Modify: front/src/pages/Login.tsx

• Step 1: Add failing tests for any pure helper logic used by the share page and login redirect flow

• Step 2: Run cd front && npm run test to verify failure

• Step 3: Implement /share/:token, showing share metadata publicly and allowing authenticated users to import into their netdisk

• Step 4: Add login redirect-back handling only as needed for this route

Task 5: Add Share Actions To Netdisk And Save-To-Netdisk For Transfer

Files:

• Modify: front/src/pages/Files.tsx

• Create: front/src/lib/netdisk-upload.ts

• Create: front/src/lib/netdisk-upload.test.ts

• Modify: front/src/pages/TransferReceive.tsx

• Step 1: Write failing helper tests for saving a browser File into netdisk

• Step 2: Run cd front && npm run test to verify failure

• Step 3: Add a share action in the Files page that creates/copies a share URL

• Step 4: Add “存入网盘” actions in transfer receive for completed files

• Step 5: Re-run cd front && npm run test

Task 6: Full Verification

Files:

• Modify only if validation reveals defects

• Step 1: Run cd front && npm run test

• Step 2: Run cd front && npm run lint

• Step 3: Run cd front && npm run build

• Step 4: Run cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn test

• Step 5: Run cd backend && /Users/mac/.local/tools/apache-maven-3.9.11/bin/mvn package

• Step 6: Deploy frontend with node scripts/deploy-front-oss.mjs only after all checks pass