dianshang-houduan/docs/superpowers/plans/2026-08-01-absolute-upload-url.md

Absolute Upload URL 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: Return an environment-configured absolute file URL from the common upload endpoint so deployed case-material links do not depend on frontend proxy routing.

Architecture: CommonUploadController already receives the relative path from IFileUtil. It will combine that path with the existing file.url configuration after removing a trailing slash from the configured public base. This preserves local storage and all existing upload mechanics.

Tech Stack: Spring Boot 2.7, JUnit 5, Spring Test mock multipart files.

Global Constraints

• Use the existing file.url property as the public file base; do not hard-code a server host.
• Preserve the empty-file response contract and existing stored relative URLs.
• Build only the backend behavior needed for upload responses.

---

Task 1: Return the configured public file URL

Files:

• Create: src/test/java/com/sztzjy/linkCommerce/controller/common/CommonUploadControllerTest.java
• Modify: src/main/java/com/sztzjy/linkCommerce/controller/common/CommonUploadController.java

Interfaces:

• Consumes: IFileUtil.upload(MultipartFile) returning a relative path such as /2026/8/1/example.docx.

• Produces: upload result map with url and fileName equal to <file.url>/2026/8/1/example.docx.

• Step 1: Write the failing test

@Test
void uploadReturnsAbsoluteConfiguredFileUrl() {
    IFileUtil fileUtil = mock(IFileUtil.class);
    when(fileUtil.upload(any(MultipartFile.class))).thenReturn("/2026/8/1/example.docx");
    CommonUploadController controller = new CommonUploadController();
    ReflectionTestUtils.setField(controller, "fileUtil", fileUtil);
    ReflectionTestUtils.setField(controller, "fileUrl", "https://files.example.com/file/");

    Map<String, Object> result = controller.upload(new MockMultipartFile("file", "case.docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "case".getBytes()));

    assertEquals("https://files.example.com/file/2026/8/1/example.docx", result.get("url"));
    assertEquals(result.get("url"), result.get("fileName"));
}

• Step 2: Run test to verify it fails

Run: mvn -Dtest=CommonUploadControllerTest test

Expected: FAIL because the controller currently returns /file/2026/8/1/example.docx.

• Step 3: Write minimal implementation

@Value("${file.url}")
private String fileUrl;

private String publicFileUrl(String relativePath) {
    return StringUtils.removeEnd(StringUtils.trimToEmpty(fileUrl), "/") + relativePath;
}

Use publicFileUrl(filePath) for both url and fileName in the successful upload response.

• Step 4: Run test to verify it passes

Run: mvn -Dtest=CommonUploadControllerTest test

Expected: PASS.

• Step 5: Commit

git add src/main/java/com/sztzjy/linkCommerce/controller/common/CommonUploadController.java src/test/java/com/sztzjy/linkCommerce/controller/common/CommonUploadControllerTest.java
git commit -m "fix: return absolute upload file urls"