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

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

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

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, "/api/v1/public/worker-links/**").permitAll()
+                        .requestMatchers(HttpMethod.POST, "/api/v1/public/worker-links/**").permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/**")
                         .hasAnyRole("ADMIN", "HR", "VIEWER")
                         .requestMatchers(HttpMethod.HEAD, "/api/v1/**")

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 = "/api/v1/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,38 @@
+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")
+    private final String workerUrl;
+
+    @JsonProperty("expires_at")
+    @Schema(name = "expires_at")
+    private final Instant expiresAt;
+
+    private WorkerLinkIssueResponse(String workerUrl, Instant expiresAt) {
+        this.workerUrl = workerUrl;
+        this.expiresAt = expiresAt;
+    }
+
+    public static WorkerLinkIssueResponse from(WorkerLinkIssueResult result) {
+        // TODO: workerUrl 조립 방식 확정 필요.
+        // 확인 후 실제 프론트 base URL + 경로로 조립해야 함.
+        // 지금은 원문 토큰만 그대로 노출한 상태(미완성).
+        return new WorkerLinkIssueResponse(result.rawToken(), result.expiresAt());
+    }
+
+    public String getWorkerUrl() {
+        return workerUrl;
+    }
+
+    public Instant getExpiresAt() {
+        return expiresAt;
+    }
+}

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

@@ -0,0 +1,57 @@
+package com.fowoco.server.workerlink.api;
+
+import com.fowoco.server.workerlink.application.WorkerLinkViewResult;
+import com.fowoco.server.workerlink.application.WorkerLinkViewService;
+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 org.springframework.http.CacheControl;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@Tag(name = "Worker Link (Public)", description = "근로자 공개 안내·제출")
+@RestController
+@RequestMapping("/api/v1/public/worker-links/{token}")
+public class WorkerLinkViewController {
+
+    private final WorkerLinkViewService workerLinkViewService;
+
+    public WorkerLinkViewController(WorkerLinkViewService workerLinkViewService) {
+        this.workerLinkViewService = workerLinkViewService;
+    }
+
+    @Operation(
+            operationId = "viewWorkerLink",
+            summary = "근로자 공개 안내 조회",
+            description = "로그인 없이 번역된 최소 안내와 허용 응답을 조회합니다."
+    )
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "조회 성공",
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            schema = @Schema(implementation = WorkerLinkViewResponse.class)
+                    )
+            ),
+            @ApiResponse(responseCode = "410", description = "링크를 찾을 수 없거나 더 이상 사용할 수 없음"),
+            @ApiResponse(responseCode = "429", description = "요청 과다")
+    })
+    @GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
+    public ResponseEntity<WorkerLinkViewResponse> view(
+            @Parameter(description = "근로자 링크 토큰") @PathVariable String token
+    ) {
+        WorkerLinkViewResult result = workerLinkViewService.view(token);
+        return ResponseEntity.ok()
+                .cacheControl(CacheControl.noStore())
+                .body(WorkerLinkViewResponse.from(result));
+    }
+}