feat: 근로자 보안 링크(Worker Link) 발급, 안내, 문서제출, 응답제출 구현

src/main/java/com/fowoco/server/audit/domain/AuditAction.java

@@ -14,5 +14,7 @@ public enum AuditAction {
     TASK_COMPLETED,
     FILE_UPLOADED,
     WORKER_DOCUMENT_FILE_LINKED,
-    DOCUMENT_REQUEST_DRAFT_SAVED
+    DOCUMENT_REQUEST_DRAFT_SAVED,
+    WORKER_LINK_RESPONSE_SUBMITTED,
+    WORKER_LINK_ACCESSED
 }

src/main/java/com/fowoco/server/common/config/CorsConfig.java

@@ -18,7 +18,7 @@ public CorsConfigurationSource corsConfigurationSource(
         CorsConfiguration configuration = new CorsConfiguration();
         configuration.setAllowedOrigins(allowedOrigins);
         configuration.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"));
-        configuration.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Request-Id"));
+        configuration.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-Request-Id", "Idempotency-Key"));
         configuration.setExposedHeaders(List.of("X-Request-Id"));
         configuration.setAllowCredentials(true);
         configuration.setMaxAge(3600L);

src/main/java/com/fowoco/server/common/config/SecurityConfig.java

@@ -91,6 +91,8 @@ public SecurityFilterChain applicationSecurityFilterChain(
                                 "/api/v1/auth/logout"
                         ).permitAll()
                         .requestMatchers("/error").permitAll()
+                        .requestMatchers(HttpMethod.GET, "/public/worker-links/**").permitAll()
+                        .requestMatchers(HttpMethod.POST, "/public/worker-links/**").permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/**")
                         .hasAnyRole("ADMIN", "HR", "VIEWER")
                         .requestMatchers(HttpMethod.HEAD, "/api/v1/**")

src/main/java/com/fowoco/server/file/domain/StoredFile.java

@@ -88,6 +88,27 @@ public static StoredFile create(
         );
     }
 
+    /**
+     * 검증을 통과한 파일임을 표시한 새 StoredFile을 반환한다.
+     * #7(Worker Link)의 "격리 저장 → 검증 → 검증된 ID만 연결" 흐름에서 사용한다.
+     */
+    public StoredFile verify() {
+        return new StoredFile(
+                storedFileId,
+                companyId,
+                name,
+                mimeType,
+                size,
+                purpose,
+                taskId,
+                workerId,
+                storageKey,
+                scanStatus,
+                true,
+                createdAt
+        );
+    }
+
     private static String requireBounded(String value, int maxLength, String fieldName) {
         if (value == null || value.isBlank()) {
             throw new IllegalArgumentException(fieldName + " must not be blank");

src/main/java/com/fowoco/server/workerlink/api/WorkerLinkController.java

@@ -0,0 +1,88 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fowoco.server.auth.application.ActorContext;
+import com.fowoco.server.auth.application.port.ActorContextProvider;
+import com.fowoco.server.workerlink.application.WorkerLinkIssueCommand;
+import com.fowoco.server.workerlink.application.WorkerLinkIssueResult;
+import com.fowoco.server.workerlink.application.WorkerLinkService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import java.util.UUID;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@Tag(name = "Worker Link", description = "근로자 보안 링크 발급")
+@RestController
+@RequestMapping("/api/v1/tasks/{taskId}/worker-link")
+@SecurityRequirement(name = "bearerAuth")
+public class WorkerLinkController {
+
+    private final WorkerLinkService workerLinkService;
+    private final ActorContextProvider actorContextProvider;
+
+    public WorkerLinkController(
+            WorkerLinkService workerLinkService,
+            ActorContextProvider actorContextProvider
+    ) {
+        this.workerLinkService = workerLinkService;
+        this.actorContextProvider = actorContextProvider;
+    }
+
+    @Operation(
+            operationId = "issueWorkerLink",
+            summary = "근로자 보안 링크 발급",
+            description = "승인된 현재 업무카드 version에서만 발급 가능합니다. "
+                    + "rotate_existing=true면 기존 활성 링크를 즉시 폐기하고 재발급합니다."
+    )
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "201",
+                    description = "발급 성공",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = WorkerLinkIssueResponse.class)
+                    )
+            ),
+            @ApiResponse(responseCode = "400", ref = "#/components/responses/BadRequest"),
+            @ApiResponse(responseCode = "401", ref = "#/components/responses/Unauthorized"),
+            @ApiResponse(responseCode = "403", ref = "#/components/responses/Forbidden"),
+            @ApiResponse(responseCode = "404", ref = "#/components/responses/NotFound"),
+            @ApiResponse(responseCode = "409", description = "이미 유효한 링크가 있어 rotate_existing 필요"),
+            @ApiResponse(responseCode = "422", description = "승인되지 않은 업무카드")
+    })
+    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE)
+    @PreAuthorize("hasAnyRole('ADMIN', 'HR')")
+    public ResponseEntity<WorkerLinkIssueResponse> issue(
+            @Parameter(description = "업무 ID") @PathVariable UUID taskId,
+            @Valid @RequestBody WorkerLinkIssueRequest request,
+            //: 나중에 확인 필요
+            @RequestHeader(value = "Idempotency-Key", required = false) String idempotencyKey
+    ) {
+        ActorContext actor = actorContextProvider.requireCurrentActor();
+        WorkerLinkIssueCommand command = new WorkerLinkIssueCommand(
+                taskId,
+                actor.companyId(),
+                request.getExpiresInHours(),
+                request.isRotateExisting(),
+                actor.actorId(),
+                idempotencyKey
+        );
+        WorkerLinkIssueResult result = workerLinkService.issue(command);
+        return ResponseEntity.status(HttpStatus.CREATED).body(WorkerLinkIssueResponse.from(result));
+    }
+}

src/main/java/com/fowoco/server/workerlink/api/WorkerLinkDocumentController.java

@@ -0,0 +1,96 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fowoco.server.common.error.ApiException;
+import com.fowoco.server.common.error.ErrorCode;
+import com.fowoco.server.common.web.RequestMetadata;
+import com.fowoco.server.workerlink.application.WorkerLinkDocumentService;
+import com.fowoco.server.workerlink.application.WorkerLinkDocumentUploadCommand;
+import com.fowoco.server.workerlink.application.WorkerLinkDocumentUploadResult;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.multipart.MultipartFile;
+
+@Tag(name = "Worker Link (Public)", description = "근로자 공개 안내·제출")
+@RestController
+public class WorkerLinkDocumentController {
+
+    private final WorkerLinkDocumentService workerLinkDocumentService;
+
+    public WorkerLinkDocumentController(WorkerLinkDocumentService workerLinkDocumentService) {
+        this.workerLinkDocumentService = workerLinkDocumentService;
+    }
+
+    @Operation(
+            operationId = "uploadWorkerLinkDocument",
+            summary = "근로자 링크 문서 제출",
+            description = "만료·폐기된 token은 거절합니다. 확장자·MIME·크기·악성파일 검사 후 격리 저장합니다."
+    )
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "201",
+                    description = "업로드 성공",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = WorkerLinkDocumentUploadResponse.class)
+                    )
+            ),
+            @ApiResponse(responseCode = "400", ref = "#/components/responses/BadRequest"),
+            @ApiResponse(responseCode = "410", description = "링크를 찾을 수 없거나 더 이상 사용할 수 없음"),
+            @ApiResponse(responseCode = "413", description = "파일 크기 초과"),
+            @ApiResponse(responseCode = "415", ref = "#/components/responses/UnsupportedMediaType"),
+            @ApiResponse(responseCode = "422", ref = "#/components/responses/UnprocessableEntity"),
+            @ApiResponse(responseCode = "429", description = "요청 과다")
+    })
+    @PostMapping(
+            path = "/public/worker-links/{token}/documents",
+            consumes = MediaType.MULTIPART_FORM_DATA_VALUE,
+            produces = MediaType.APPLICATION_JSON_VALUE
+    )
+    public ResponseEntity<WorkerLinkDocumentUploadResponse> upload(
+            @Parameter(description = "근로자 링크 토큰") @PathVariable String token,
+            @Parameter(description = "업로드할 파일") @RequestParam("file") MultipartFile file,
+            @Parameter(description = "문서 유형") @RequestParam(value = "documentType", required = false) String documentType,
+            @Parameter(description = "클라이언트 중복 방지 키") @RequestParam("clientRequestId") String clientRequestId,
+            @RequestHeader(value = "Idempotency-Key", required = false) String idempotencyKey,
+            HttpServletRequest servletRequest
+    ) {
+        if (file.isEmpty() || file.getOriginalFilename() == null || file.getOriginalFilename().isBlank()) {
+            throw new ApiException(ErrorCode.VALIDATION_FAILED, "업로드할 파일과 파일명이 필요합니다.");
+        }
+        try {
+            WorkerLinkDocumentUploadCommand command = new WorkerLinkDocumentUploadCommand(
+                    token,
+                    file.getOriginalFilename(),
+                    file.getContentType(),
+                    file.getSize(),
+                    documentType,
+                    clientRequestId,
+                    file.getInputStream()
+            );
+            WorkerLinkDocumentUploadResult result = workerLinkDocumentService.upload(
+                    command,
+                    RequestMetadata.from(servletRequest)
+            );
+            return ResponseEntity.status(HttpStatus.CREATED)
+                    .body(WorkerLinkDocumentUploadResponse.from(result.storedFile(), result.linkExpiresAt()));
+        } catch (IOException exception) {
+            throw new UncheckedIOException("failed to read uploaded file", exception);
+        }
+    }
+}

src/main/java/com/fowoco/server/workerlink/api/WorkerLinkDocumentUploadResponse.java

@@ -0,0 +1,58 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fowoco.server.file.domain.StoredFile;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.Instant;
+import java.util.UUID;
+
+@Schema(name = "WorkerLinkDocumentUploadResponse", description = "근로자 링크 문서 업로드 결과")
+public final class WorkerLinkDocumentUploadResponse {
+
+    @JsonProperty("upload_id")
+    @Schema(name = "upload_id")
+    private final UUID uploadId;
+
+    @JsonProperty("file_name")
+    @Schema(name = "file_name")
+    private final String fileName;
+
+    @JsonProperty("size")
+    private final long size;
+
+    @JsonProperty("expires_at")
+    @Schema(name = "expires_at")
+    private final Instant expiresAt;
+
+    private WorkerLinkDocumentUploadResponse(UUID uploadId, String fileName, long size, Instant expiresAt) {
+        this.uploadId = uploadId;
+        this.fileName = fileName;
+        this.size = size;
+        this.expiresAt = expiresAt;
+    }
+
+    public static WorkerLinkDocumentUploadResponse from(StoredFile storedFile, Instant linkExpiresAt) {
+        return new WorkerLinkDocumentUploadResponse(
+                storedFile.storedFileId(),
+                storedFile.name(),
+                storedFile.size(),
+                linkExpiresAt
+        );
+    }
+
+    public UUID getUploadId() {
+        return uploadId;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public long getSize() {
+        return size;
+    }
+
+    public Instant getExpiresAt() {
+        return expiresAt;
+    }
+}

src/main/java/com/fowoco/server/workerlink/api/WorkerLinkIssueRequest.java

@@ -0,0 +1,32 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(name = "WorkerLinkIssueRequest", description = "근로자 보안 링크 발급 요청")
+public final class WorkerLinkIssueRequest {
+
+    @Schema(name = "expires_in_hours", description = "링크 유효 시간(시간 단위)", example = "72")
+    private final Long expiresInHours;
+
+    @Schema(name = "rotate_existing", description = "기존 활성 링크를 폐기하고 재발급할지 여부")
+    private final boolean rotateExisting;
+
+    @JsonCreator
+    public WorkerLinkIssueRequest(
+            @JsonProperty("expires_in_hours") Long expiresInHours,
+            @JsonProperty("rotate_existing") Boolean rotateExisting
+    ) {
+        this.expiresInHours = expiresInHours;
+        this.rotateExisting = rotateExisting != null && rotateExisting;
+    }
+
+    public Long getExpiresInHours() {
+        return expiresInHours;
+    }
+
+    public boolean isRotateExisting() {
+        return rotateExisting;
+    }
+}

src/main/java/com/fowoco/server/workerlink/api/WorkerLinkIssueResponse.java

@@ -0,0 +1,48 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fowoco.server.workerlink.application.WorkerLinkIssueResult;
+import io.swagger.v3.oas.annotations.media.Schema;
+import java.time.Instant;
+
+@Schema(name = "WorkerLinkIssueResponse", description = "근로자 보안 링크 발급 결과")
+public final class WorkerLinkIssueResponse {
+
+    @JsonProperty("worker_url")
+    @Schema(name = "worker_url", description = "근로자에게 전달할 링크 URL. 같은 idempotency key로 재요청한 경우 null")
+    private final String workerUrl;
+
+    @JsonProperty("expires_at")
+    @Schema(name = "expires_at")
+    private final Instant expiresAt;
+
+    @JsonProperty("already_issued")
+    @Schema(name = "already_issued", description = "같은 idempotency key로 이미 발급된 적이 있어 재사용된 응답인지 여부")
+    private final boolean alreadyIssued;
+
+    private WorkerLinkIssueResponse(String workerUrl, Instant expiresAt, boolean alreadyIssued) {
+        this.workerUrl = workerUrl;
+        this.expiresAt = expiresAt;
+        this.alreadyIssued = alreadyIssued;
+    }
+
+    public static WorkerLinkIssueResponse from(WorkerLinkIssueResult result) {
+        // TODO: workerUrl 조립 방식 확정 필요.
+        // 확인 후 실제 프론트 base URL + 경로로 조립해야 함.
+        // 지금은 원문 토큰만 그대로 노출한 상태(미완성).
+        // 재시도 worker_url을 null로 반환함.
+        return new WorkerLinkIssueResponse(result.rawToken(), result.expiresAt(), result.alreadyIssued());
+    }
+
+    public String getWorkerUrl() {
+        return workerUrl;
+    }
+
+    public Instant getExpiresAt() {
+        return expiresAt;
+    }
+
+    public boolean isAlreadyIssued() {
+        return alreadyIssued;
+    }
+}