backend: GET /api/tasks/{id} 4 層実装(UseCase + Controller + DTO + 例外) (N4 / B-2)

[win2cot]

B-1 (#273) で整えた基盤(Task POJO + TaskRepository ポート + TaskJpaEntity)を使って、GET /api/tasks/{id} endpoint を 4 層構造で実装する。

N4 (#86) を 7 分割した B-2 スコープ:

• A-1 (backend: feature 内クリーンアーキ 4 層パッケージ雛形 + shared Open module 新設 (N4 / A-1) #86) / A-2 (backend: 既存クラス(Controller / Repository / Entity)を 4 層パッケージへ移動 (N4 / A-2) #272) merged / B-1 (backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273)
• B-2 (本 Issue): GET /tasks/{id} 4 層実装 ~9 ファイル
• B-3 (backend: DB migration created_by/updated_by + 統合 IT + AuthZ test 更新 (N4 / B-3) #279): DB migration + 統合 IT + AuthZ test 更新
• C (docs(dev): 新 feature 追加時のテンプレ手順書 docs/dev/feature-template.md 整備 (N4 / C) #274)

規約準拠の前提

規約 / ADR	内容
コーディング規約 §11 (v1.2、PR #255)	@Transactional 境界明示、readOnly 属性必須
ADR-0005	visibility / admin bypass

やること

1. task/usecase/GetTaskUseCase.java 新規

@Service
@Transactional(readOnly = true)
public class GetTaskUseCase {
  private final TaskRepository taskRepository;
  private final TaskAuthorizationDomainService taskAuthorizationDomainService;

  public Task execute(Long taskId, Long tenantId, Long userId, Role role) {
    Task task = taskRepository.findByIdAndTenantId(taskId, tenantId)
        .orElseThrow(() -> new TaskNotFoundException(taskId));
    if (!taskAuthorizationDomainService.canView(task, userId, role)) {
      throw new TaskNotViewableException(taskId);
    }
    return task;
  }
}

@Transactional(readOnly = true) をクラスレベルに明示(規約 §11.1)。visibility チェックは TaskAuthorizationDomainService.canView に委譲(既存利用、無ければ B-2 で追加)。

2. task/domain/TaskNotFoundException.java 新規

public class TaskNotFoundException extends DomainException {
  public TaskNotFoundException(Long taskId) {
    super("Task not found: " + taskId);
  }
}

DomainException(B-1 で導入)継承、@ResponseStatus 不使用(TaskExceptionHandler で 404 マッピング)。

3. task/domain/TaskNotViewableException.java 新規

TaskNotFoundException と同じ構造、メッセージのみ違う(404 として返す、情報漏洩防止のため Visibility 違反でも 404 統一)。

4. task/adapter/web/TaskController.java 新規

@RestController
@RequestMapping("/api/tasks")
public class TaskController {
  private final GetTaskUseCase getTaskUseCase;

  @GetMapping("/{id}")
  public TaskResponse get(@PathVariable Long id, TasksAuthenticationToken token) {
    Task task = getTaskUseCase.execute(id, token.getTenantId(), token.getUserId(), token.getRole());
    return TaskResponse.from(task);
  }
}

TasksAuthenticationToken(A-2 で security/adapter/web/ に移動済)から tenantId / userId / role を取得。

5. task/adapter/web/TaskExceptionHandler.java 新規

@RestControllerAdvice(assignableTypes = TaskController.class)
public class TaskExceptionHandler {
  @ExceptionHandler({TaskNotFoundException.class, TaskNotViewableException.class})
  @ResponseStatus(HttpStatus.NOT_FOUND)
  public Map<String, String> handleNotFound(DomainException ex) {
    return Map.of("error", ex.getMessage());
  }
}

assignableTypes = TaskController.class で scope を絞る。404 マッピング、Body は {"error": "..."} 形式。

6. task/adapter/web/dto/TaskResponse.java + package-info.java 新規

• record TaskResponse(Long id, Long tenantId, String title, String description, Priority priority, TaskStatus status, Visibility visibility, Long assigneeId, LocalDate dueDate, OffsetDateTime createdAt, OffsetDateTime updatedAt)
• static factory from(Task domain) で Domain → Response 変換、LocalDateTime → OffsetDateTime は JST 統一(2026-05-26 確定方針)に従う
• package-info.java は @NullMarked

7. テスト

GetTaskUseCaseTest (単体、新規):

• TaskRepository + TaskAuthorizationDomainService を @Mock、@ExtendWith(MockitoExtension.class)
• ケース: (a) 正常取得、(b) findByIdAndTenantId empty → TaskNotFoundException、(c) canView false → TaskNotViewableException、(d) PRIVATE visibility で本人(assignee)アクセス OK

TaskControllerWebMvcTest (WebMvc slice、新規):

• @WebMvcTest(TaskController.class) + @Import(TaskExceptionHandler.class)
• GetTaskUseCase を @MockBean、TasksAuthenticationToken の mock は security/adapter/web/SecurityConfigTest を参考
• ケース: (a) 200 OK + JSON、(b) TaskNotFoundException throw → 404、(c) TaskNotViewableException throw → 404

やらないこと

• DB migration created_by/updated_by 列追加 → B-3 (backend: DB migration created_by/updated_by + 統合 IT + AuthZ test 更新 (N4 / B-3) #279)
• 統合 IT TaskCrossTenantIT → B-3 (backend: DB migration created_by/updated_by + 統合 IT + AuthZ test 更新 (N4 / B-3) #279)
• TaskAuthorizationDomainServiceTest admin bypass 更新 → B-3 (backend: DB migration created_by/updated_by + 統合 IT + AuthZ test 更新 (N4 / B-3) #279)

受け入れ条件

• GetTaskUseCase @Transactional(readOnly = true) クラスレベル明示
• TaskController + TaskExceptionHandler + TaskResponse + dto/package-info.java 配置
• TaskNotFoundException + TaskNotViewableException は DomainException 継承
• GetTaskUseCaseTest 全 4 ケース green
• TaskControllerWebMvcTest 全 3 ケース green
• ./gradlew :webapi:test green、ApplicationModules.verify() green
• CI green、UT カバレッジ 80%+

参照

• 前提: backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273 (B-1) merge 済
• 規約: 設計規約 §1.1 / コーディング規約 §11 / ADR-0005
• 関連 Issue: backend: 基盤(shared/exception + Task POJO/JPA Entity 分離 + Repository ポート) (N4 / B-1) #273 (blocks 本) / backend: DB migration created_by/updated_by + 統合 IT + AuthZ test 更新 (N4 / B-3) #279 (B-3、blocked-by 本) / docs(dev): 新 feature 追加時のテンプレ手順書 docs/dev/feature-template.md 整備 (N4 / C) #274 (C)
• Sub-tracker: [Phase 1 Sprint 0] scaffold ↔ 設計書 v1.4.x 整合実装(2 週間、2026-06-14 〜 06-27) #121 Phase 1 Sprint 0

[win2cot]

実装完了 — PR #298

B-2 スコープの実装が完了しました。

実装したファイル

メインソース (9ファイル)

• task/domain/TaskNotFoundException — DomainException 継承、404 マッピング用
• task/domain/TaskNotViewableException — 同上（visibility 違反も 404 で統一、情報漏洩防止）
• task/usecase/GetTaskUseCase — @Transactional(readOnly = true) クラスレベル明示
• task/infra/TaskInfraConfig — TaskAuthorizationDomainService を @Bean 登録（domain 層は Spring 非依存を維持）
• task/infra/package-info.java — @NullMarked
• task/adapter/web/TaskController — GET /api/tasks/{id}
• task/adapter/web/TaskExceptionHandler — assignableTypes = TaskController.class でスコープ限定
• task/adapter/web/dto/TaskResponse — record、LocalDateTime → OffsetDateTime (JST)
• task/adapter/web/dto/package-info.java — @NullMarked

変更ファイル (2ファイル)

• security/adapter/web/package-info.java — @NamedInterface 追加
• security/domain/package-info.java — @NamedInterface 追加

→ TaskController が TasksAuthenticationToken / TasksPrincipal を参照するため、Spring Modulith の境界として正式公開。ModularityTests.verifyModularity() green を維持。

テストソース (2ファイル)

• GetTaskUseCaseTest — 4ケース全 PASSED
• TaskControllerWebMvcTest — 3ケース全 PASSED

Issue 擬似コードとの差異

Issue 擬似コード	実際の実装	理由
findByIdAndTenantId(taskId, tenantId)	findById(taskId)	Hibernate Filter がテナント分離を担保するため tenantId パラメータ不要
canView(task, userId, role)	canBeViewedBy(task, userId, List.of())	既存メソッドに合わせる。stakeholder lookup は B-3 (#279) スコープのため暫定で空リスト
token.getTenantId() / token.getUserId()	token.getPrincipal().getId()	TasksAuthenticationToken の実際の API に合わせる

テスト結果

GetTaskUseCaseTest        4/4 PASSED
TaskControllerWebMvcTest  3/3 PASSED
ModularityTests.verifyModularity()  PASSED
Spotless check  PASSED

PR: #298