🐰 [flowbit] #6. Project Analysis - 이벤트를 해석하여 프로젝트 상태를 도출하다

☘️ 1. 오늘 목표

어제는

Project Timeline을 만들어서
프로젝트 단위의 흐름을 볼 수 있게 만들었다.

이제는 흐름이 보인다.

근데 여기서 또 하나 부족한 게 있었다.

→ 흐름은 보이는데, 해석은 안된다

지금은 이벤트를 나열하는 단계다.
그래서 오늘 목표는 이거였다.

→ 흐름을 요약해서 보여주자

예를 들어,

프로젝트를 진행하다 보면
작업은 계속 추가되고 상태도 바뀌는데,

막상 지금 이 프로젝트가 어느 단계에 있는지
한 번에 파악하기는 어렵다.

이걸 확인하려면
여러 Task를 하나씩 보거나,
Timeline을 직접 해석해야 한다.

그래서

→ 이벤트를 그대로 보여주는 게 아니라
→ 흐름을 해석해서 보여주는 구조가 필요했다.

→ 결국, 데이터를 보는 것이 아니라
→ 상태를 ‘판단’할 수 있는 형태로 바꾸는 것이었다.

---

☘️ 2. Timeline의 한계

이미 이런 API가 있다.

GET /api/projects/{id}/timeline

이건 프로젝트 안에서 발생한 이벤트를
시간순으로 나열해준다.

하지만 실제로 궁금한 건 이거다.

→ 지금 이 프로젝트는 어느 정도 진행됐는가?
→ 작업은 몇 개고, 상태는 어떻게 분포되어 있는가?
→ 최근에 언제 활동이 있었는가?

단순 나열만으로는
이걸 바로 알기 어렵다.

그래서 필요한 건

→ 흐름을 해석한 결과

단순히 이벤트를 보는 것이 아니라
이 프로젝트가 지금 건강하게 진행되고 있는지 판단할 수 있어야 한다.

즉,

→ 흐름을 나열하는 것이 아니라
→ 흐름을 기반으로 상태를 해석해야 한다.

---

☘️ 3. Project Analysis API

이걸 해결하기 위해 만든 API가 이거다.

GET /api/projects/{id}/analysis

이 API는

프로젝트에 속한 Task를 조회하고
TaskEvent를 기반으로
상태 분포와 흐름 정보를 계산해서 반환한다

이제는

→ 무슨 일이 있었는지가 아니라
→ 지금 어떤 상태인지가 보인다

이 API는 단순 조회가 아니라,

→ 여러 이벤트를 종합해서
→ 프로젝트의 현재 상태를 한 번에 판단할 수 있도록 만든 API다.

---

☘️ 4. 분석 흐름

구조는 그대로 유지한다.

Project → Task → TaskEvent

코드 흐름은 이렇다.

List<Task> tasks = taskRepository.findByProject_IdAndStatusNot(projectId, TaskStatus.DELETED);

List<Long> taskIds = tasks.stream()
        .map(Task::getId)
        .toList();

List<TaskEvent> events = taskIds.isEmpty()
        ? List.of()
        : taskEventRepository.findByTaskIdInOrderByCreatedAtAsc(taskIds);

핵심은 이거다.

→ Task는 현재 상태
→ TaskEvent는 상태 변화 이력

이 둘을 합쳐야

→ 흐름 해석이 가능하다

---

☘️ 5. 상태 기반 통계

단순 조회를 넘어서
상태를 기반으로 통계를 만든다.

int todoCount = countByStatus(tasks, TaskStatus.TODO);
int inProgressCount = countByStatus(tasks, TaskStatus.IN_PROGRESS);
int blockedCount = countByStatus(tasks, TaskStatus.BLOCKED);
int doneCount = countByStatus(tasks, TaskStatus.DONE);

→ TODO / IN_PROGRESS / DONE 비율 확인

예를 들어,

IN_PROGRESS가 많고 DONE이 적다면
→ 작업이 시작은 되었지만 완료되지 않고 쌓이고 있는 상태다.

즉,

병목 구간을 한눈에 파악할 수 있다

→ 단순 개수가 아니라
→ 상태 흐름의 문제를 드러내는 지표가 된다

---

☘️ 6. 마지막 활동 시점

LocalDateTime lastEventAt = events.isEmpty()
        ? null
        : events.get(events.size() - 1).getCreatedAt();

→ 가장 최근 이벤트 시간
→ 이 프로젝트가 마지막으로 움직인 시간

최근 활동 시점이 오래됐다면

→ 이 프로젝트는 사실상 멈춰있는 상태다.

즉, 최근 이벤트 시간 하나로
프로젝트의 ‘활성도’를 판단할 수 있다

---

☘️ 7. 생성 API 개선

기존에는

POST /tasks

void 상태였다.

이걸 바꿨다.

→ 생성하면 바로 결과 반환

→ 생성 후 id 포함된 JSON 반환

이제는

생성 → 바로 조회/사용 가능

---

☘️ 8. 예외 처리 통일

기존에는

→ 예외를 던지기만 했다

이걸 바꿨다.

→ JSON 형태로 통일

이제는

→ 성공/실패 모두 같은 구조

---

☘️ 9. 캐싱 적용 (그리고 문제 발생)

분석 API는 계산 비용이 있다.

프로젝트에 속한 Task를 조회하고
각 Task의 이벤트를 다시 조회한 뒤
상태별 개수와 마지막 이벤트 시점을 계산해야 한다.

그래서 분석 API에 캐싱을 붙였다.

@Cacheable(value = "projectAnalysis", key = "#projectId")

그리고 Task 상태가 변경되면
분석 결과도 바뀌어야 하므로 캐시를 제거하도록 했다.

@CacheEvict(value = "projectAnalysis", key = "#result.projectId")

첫 요청은 1751ms가 걸렸다.

이 요청에서는 실제로 분석 로직이 실행되고,
Task 조회와 Event 조회, 상태별 집계가 수행된다.

같은 요청을 다시 보내자 응답 시간이 95ms로 줄었다.

즉,

→ 첫 요청: 1751ms
→ 두 번째 요청: 95ms

약 18배 정도 빨라진 것을 확인할 수 있었다.

단순히 로직을 빠르게 만든 것이 아니라,
동일한 요청에 대해서는 분석 로직 자체를 다시 실행하지 않고
캐시에 저장된 결과를 바로 반환한 것이다.

캐싱은 어노테이션만 붙이면 끝나는 줄 알았는데,
실제로는 무엇을 저장할 수 있는가까지 같이 고려해야 한다는 걸 알게 됐다.

근데 여기서 문제가 발생했다.

GET http://localhost:8080/api/projects/1/analysis

HTTP/1.1 400 
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Type: application/json
Transfer-Encoding: chunked
Date: Fri, 01 May 2026 12:47:22 GMT
Connection: close

{
  "code": "BAD_REQUEST",
  "message": "DefaultSerializer requires a Serializable payload but received an object of type [com.ahyeon.flowbit.domain.project.dto.ProjectAnalysisResponse]",
  "timestamp": "2026-05-01T21:47:22.185627213"
}
응답 파일이 저장되었습니다.
> 2026-05-01T214722.400.json

Response code: 400; Time: 87ms (87 ms); Content length: 223 bytes (223 B)

캐시에 저장하려는 객체가
직렬화가 안 되어 있어서 에러가 터졌다.

---

☘️ 10. 트러블슈팅 (Serializable)

문제 원인:

→ 캐시에 저장하려는 DTO가 직렬화 불가

해결:

public class ProjectAnalysisResponse implements Serializable

→ 캐싱 정상 동작

이걸 통해 알게 된 점:

캐싱은 단순 어노테이션이 아니라
저장 방식까지 고려해야 한다

---

☘️ 11. API 구조 개선 (/api prefix)

기존:

/projects
/tasks

변경:

/api/projects
/api/tasks

→ 프론트 / 백엔드 명확히 분리

---

☘️ 12. 오늘 정리

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

→ 흐름을 보는 단계에서
→ 흐름을 해석하고 판단하는 단계로 넘어갔다

이제는 단순히 데이터를 나열하는 것이 아니라

→ 프로젝트의 상태를 해석하고
→ 문제가 발생하는 지점을 파악할 수 있는 구조가 되었다

또한 분석 API에 캐싱을 적용하면서
→ 성능 개선과 직렬화 문제까지 함께 경험했다.

---

☘️ 13. 현재 상태

Project ✔️
Task ✔️
TaskEvent ✔️
Timeline ✔️
Analysis ✔️
Exception Handling ✔️
Caching ✔️
API 구조 ✔️

이제는

→ 단순 CRUD가 아니라
→ 흐름 기반 시스템

---

☘️ 14. 다음 목표

이제 백엔드는 충분히 준비됐다.

다음 단계는

→ React로 프론트 붙이기

Timeline + Analysis를
화면으로 보여주는 단계

그리고 Redis는

→ 구조만 잡아두고
→ 실제 적용은 이후 단계에서 진행할 예정