🐰 [flowbit] #3. 조회 API 고도화 - 흐름을 보여주기 시작했다

☘️ 1. 오늘 목표

어제는 TaskEvent를 도입해서
상태 변화를 기록하는 구조를 만들었다.

오늘은 그 다음 단계다.

기록한 데이터를 어떻게 보여줄 것인가

단순히 저장하는 걸 넘어서
이제는 조회 구조를 제대로 만드는 날이었다.

예를 들어,

작업은 계속 쌓이는데
막상 어떤 흐름으로 진행되고 있는지는
한눈에 보기 어려운 상태였다.

한눈에 보기 어려운 상태였다.

그래서

단순 조회가 아니라
흐름을 보여주는 방식이 필요했다

---

☘️ 2. 상태만 조회하는 건 부족했다

기존에는 이런 조회만 가능했다.

GET /tasks

이건 단순히 전체 목록을 가져오는 수준이다.

근데 실제로 필요한 건 이런 조회다.

GET /tasks?status=TODO
GET /tasks?status=IN_PROGRESS

→ 지금 해야 할 작업만 보고 싶다
→ 진행 중인 작업만 보고 싶다

그래서 상태 기반 조회를 추가했다.

status 파라미터를 이용해 IN_PROGRESS 상태의 작업만 필터링하여 조회할 수 있다.

---

☘️ 3. 프로젝트 기준 조회까지 확장

Task에는 이미 projectId가 있다.

그렇다면 자연스럽게 이런 조회가 가능해야 한다.

GET /tasks?projectId=1
GET /tasks?projectId=1&status=TODO

이건 단순한 필터 추가가 아니라,

프로젝트 단위로 작업 흐름을 조회하는 구조를 만든 것이다.

여러 작업을 묶어서
같은 흐름 안에서 볼 수 있는 기반이 만들어진 셈이다

아직 Project 도메인은 없지만,
조회 구조는 이미 그걸 기준으로 동작한다.

projectId를 기준으로 작업을 필터링하여,
특정 프로젝트 단위로 작업 목록을 조회할 수 있다.

---

☘️ 4. 응답 구조를 바꿨다 ⭐

기존 응답은 이랬다.

{
  "id": 1,
  "title": "...",
  "status": "TODO"
}

근데 이건 현재 상태만 보여준다.

그래서 응답을 이렇게 확장했다.

{
  "id": 1,
  "projectId": 1,
  "status": "IN_PROGRESS",
  "createdAt": "...",
  "startedAt": "...",
  "completedAt": null
}

이제는 단순 목록이 아니라

이 작업이 언제 만들어졌고 언제 시작됐고
지금 어디까지 왔는지를 같이 보여준다.

→ 조회 API 자체가 흐름 정보를 포함하게 됐다.

※ 이 부분은 위에 첨부된 Task 조회 응답 이미지를 통해 확인할 수 있다.

---

☘️ 5. 이벤트 조회 안정성 보강

기존에는 이런 문제가 있었다.

GET /tasks/999/events

→ 존재하지 않는 Task인데도 그냥 빈 배열 반환

이건 애매하다.

Task가 없는 건지
이벤트가 없는 건지

구분이 안 된다.

그래서 이벤트 조회 전에
Task 존재 여부를 먼저 검증하도록 수정했다.

→ 이제는 없는 Task는 명확하게 에러로 처리된다.

---

☘️ 6. 타임라인 API 🌟

여기서부터가 진짜다.

이벤트를 조회하는 것과
보여주는 것은 다르다.

그래서 만든 API:

GET /tasks/{id}/timeline

이 API는 단순 이벤트 리스트가 아니라

작업의 상태 변화 흐름을 시간 순으로 보여준다

이 흐름에 시간 정보를 더하면,
작업이 얼마나 빠르게 진행됐는지까지 파악할 수 있다

즉,

단순히 상태가 바뀌었다가 아니라
어느 구간에서 오래 머물렀는지까지 볼 수 있게 된다

---

☘️ 7. 이벤트 로그와 타임라인은 다르다

같은 데이터를 써도 목적이 다르다.

/events → 원본 로그
/timeline → 사용자에게 보여줄 흐름

그래서 DTO도 분리했다.

TaskEventResponse → 로그용
TaskTimelineResponse → 타임라인용

→ 이건 단순 구조가 아니라 역할 분리 설계다.

---

☘️ 8. 이벤트 간 시간까지 계산

타임라인에서 한 단계 더 갔다.

각 이벤트가 이전 이벤트 이후 얼마나 걸렸는지 계산

예를 들면:

CREATED → STARTED (10분 후)
STARTED → BLOCKED (20분 후)

이걸 응답에 포함시켰다.

{
  "eventType": "STARTED",
  "minutesFromPreviousEvent": 10
}

단순히 이벤트 흐름만 보여주는 것이 아니라,

각 상태 변화 사이의 시간 간격까지 함께 확인할 수 있게 되었다.

실제 응답은 다음과 같다.

이를 통해

작업이 어느 구간에서 오래 머물렀는지
진행 속도가 어떤지까지 파악할 수 있다

---

☘️ 9. 오늘 정리

오늘 한 일을 한 줄로 정리하면 이거다.

이벤트를 단순 조회하는 것을 넘어서
시간 흐름까지 포함한 작업 흐름으로 재구성했다

---

☘️ 10. 현재 상태

CREATE ✔️
READ ✔️
STATUS FILTER ✔️
PROJECT FILTER ✔️
EVENT LOGGING ✔️
TIMELINE ✔️
DURATION ✔️

이제 단순 CRUD가 아니라

흐름 기반 조회 시스템의 형태를 갖추기 시작했다

---

☘️ 11. 다음 목표

다음 단계는 이거다.

Project 도메인 추가
타임라인을 프로젝트 단위로 확장

이제 Task 하나가 아니라
프로젝트 전체 흐름으로 확장할 차례다.