PinIt Backend

AI와 통계로 사용자의 하루를 설계하는 일정 관리 서비스 PinIt 의 백엔드 서버

---

🌟 Product Vision

PinIt 이 추구하는 핵심 목적은 다음 세 가지입니다.

1. 사용자의 통계 기록 및 피드백

   • 사용자의 일정/집중 시간/업무 시간을 지속적으로 기록
   • 주간·월간 단위의 리포트와 피드백을 제공하여 “시간 쓰는 습관”을 개선

2. AI와 상호작용하며 복잡한 일정을 구체화

   • “이 프로젝트 2주 안에 끝내고 싶은데, 어떻게 쪼개야 하지?” 같은 의문에 대해
   • AI가 작업을 쪼개고, 각 작업을 캘린더 상의 슬롯에 구체적인 계획으로 배치하는 것을 목표

이 저장소는 위 목적을 달성하기 위한 백엔드 도메인·API·비즈니스 로직을 담당합니다.

---

🧱 Tech Stack

• Language: Java
• Framework
  • Spring Boot (Web, Validation 등)
  • Spring Data JPA
• Persistence
  • JPA(Hibernate)
  • Querydsl (타입 세이프한 조회용)
• Database: MySQL (로컬/운영 환경에서 사용)
• Build: Gradle (Gradle Wrapper 포함)
• Test: JUnit 5, Spring Test 등

정확한 의존성 버전 및 설정은 build.gradle, src/main/resources 설정 파일을 참고하세요.

---

🧩 Domain Overview

1. Task (작업 도메인)

• 특정 시점 이전에 끝내야 하는 “일” 자체를 관리
• 마감일, 중요도, 난이도(피보나치: 1, 2, 3, 5, 8, 13, 21)
• Task 간 의존/우선순위, 작업 쪼개기 대상
• 상태는 완료/미완료 중심 (시간대 실행 상태는 관리하지 않음)

2. Schedule (일정 도메인)

• 특정 시간대에 실행되는 “일정/약속” 관리 (회의·약속 등 Task 없이도 생성 가능)
• 지정 시작 시각, 상태(시작/일시정지/중지/완료), 실행 히스토리(누적 소요 시간)
• 필요 시 기존 Task를 일정으로 복사해 시간 슬롯에 배치, 일정 완료/취소 시 연결된 Task 완료/미완료와 연동

3. Dependency (작업 관계 도메인)

Task 간 “선후 관계”를 관리합니다.

• from Task가 먼저 끝나야 to Task를 시작할 수 있음
• Task 그래프를 기반으로 사이클 검사 수행
• Task 삭제/연결 해제 시 연관된 의존 관계를 정리

복잡한 의존관계/사이클 검사는 “복잡한 일정(프로젝트)”을 AI와 함께 구체화할 때 핵심이 되는 도메인입니다.

4. Member / User (사용자 도메인)

사용자의 시간 사용 패턴 및 환경을 담는 도메인입니다.

• 계정 정보 (아이디, 닉네임 등)
• 생활 패턴 (수면 시간, 식사 시간, 쉬는 날 등)
• 이번 주 집중 시간, 업무 시간 등의 집계 정보

이 정보들을 기반으로, **AI 추천 시 “그 사람에게 맞는 플랜”**을 만들 수 있도록 설계합니다.

API 버전 정책 (Task/Schedule 분리)

• V0: 기존 호환용. 일정 생성/수정 시 Task를 함께 생성하거나 수정하며, 요청/응답에 작업 속성(마감일, 중요도/난이도[Fibonacci: 1,2,3,5,8,13,21])이 포함됩니다.
• V1: 분리 권장. 일정 단독 CRUD/상태 전환을 중심으로 하되, 일정 응답에 연결된 작업의 기본 정보(ID: taskId, 완료 여부: taskCompleted)를 포함합니다. 추가로 다음 엔드포인트를 제공합니다.
  • GET /v1/schedules/week 주간 일정 조회
  • GET /v1/members/now 현재 진행 중인 일정 ID
  • GET /v1/statistics 주간 통계 조회
  • Task 응답에 의존성 메타(previousTaskIds,nextTaskIds) 포함
  • Task 의존성 페이로드: 생성 시 각 의존 관계마다 fromId 또는 toId 중 하나는 반드시 0(새로 생성될 자기 자신)이어야 하며, removeDependencies는 비워두어야 합니다. 수정 시에는 0을 사용할 수 없습니다.
• 작업 → 일정 복사: POST /v1/tasks/{taskId}/schedules로 기존 작업을 지정 시각에 일정으로 등록할 수 있습니다.
• 삭제 플래그: DELETE /v1/tasks/{taskId}?deleteSchedules= 혹은 DELETE /v0|v1/schedules/{scheduleId}?deleteTaskAlso= 로 연관 삭제 여부를 선택합니다(미설정 시 연관만 해제).

---

🔧 주요 기능 (백엔드 기준)

1. 작업(Task) 관리 API

• 작업 생성: 제목/설명/마감일/중요도/난이도[Fibonacci]/의존 관계 입력
• 작업 조회·상세: 회원별 작업 목록 및 단건 조회
• 작업 수정 (PATCH): 변경 필드만 부분 업데이트(패치 객체로 null 덮어쓰기 방지)
• 작업 완료/되돌리기: 완료 ↔ 미완료 상태 전환
• 작업 삭제: 의존 관계 함께 삭제, 옵션으로 연관 일정 삭제 또는 분리
• 작업 → 일정 복사: 기존 작업을 지정 시각의 일정으로 등록

2. 일정(Schedule) 관리 API

• 일정 생성: V1은 제목/설명/지정 시작 시각만으로 일정 생성(작업 없이 가능), V0 레거시는 Task 속성까지 포함해 일정+작업 동시 생성
• 일정 조회·상세: 특정 날짜/주간 목록 조회, 단건 조회
• 일정 수정 (PATCH): 제목/설명/지정 시작 시각 등 변경 필드만 부분 업데이트
• 일정 상태 전환: 시작, 일시중지, 재시작, 완료, 취소
• 일정 삭제: 상태 규칙을 준수해 삭제, 필요 시 연관 Task 상태 연동

3. 의존관계 관리

• Task 간 선행/후행 관계 등록
• 사이클 검사로 잘못된 의존 그래프 방지
• Task 삭제/분리 시 연관 의존관계 정리

4. 통계 및 피드백을 위한 데이터 수집

(구현/설계 범위에 맞추어 점진적으로 확장)

• 일/주 단위 집중 작업 시간 집계
• 일/주 단위 일반 업무 시간 집계
• 통계 API를 통해 프론트에서 시각화 및 피드백 화면 구성

---

🤖 AI 연동 방향성 (Roadmap)

이 백엔드는 AI와 상호작용하기 위한 도메인/데이터 기반을 제공하는 것을 목표로 합니다.

1. 간단한 일정 추천

   • 3시간 정도 걸릴 것 같은 일정이 있을 때,
   • 사용자의 남은 시간/우선순위/집중 시간 통계 등을
   • 강화학습 모델에 전달하여 일정을 수행할 시점을 추천받는 기능
   • RLHF 기반으로 사용자의 시간 관리 성향을 반영하는 AI

2. 복잡한 일정 쪼개기

   • “TOEIC 900점, 2개월 안에” 같은 일정을 등록하려 할 때
     • LLM에게 일정 검토 요청
     • 목표를 달성 가능한 단위 작업으로 분해
     • 각 작업들 간 선후관계(Dependency) 생성
     • 각 작업을 캘린더 상의 슬롯으로 배치하는 로직/AI 연동

현재 저장소는 도메인/데이터/트랜잭션 레이어를 먼저 단단하게 다지는 것에 초점을 두고 있으며, AI 연동은 별도 서비스(OpenAI 등)와 HTTP 또는 메시지 큐로 연동하는 형태를 염두에 두고 있습니다.

---

📡 API 문서

API 문서

---

📝 설계 하이라이트

• DDD 지향 설계

  • 일정, 의존관계, 사용자 통계를 각각의 도메인으로 바라보고, 도메인 규칙(사이클 검사, 선행 완료 조건 등)을 도메인 레이어에 집중

• 명령형보다 선언형에 가까운 Patch 설계

  • HTTP PATCH에서 필드별 조건문/switch-case 대신 “Patch 객체 → 도메인 메소드” 형태로 적용하여 가독성과 유지보수성 향상

• 트랜잭션 경계 분리

  • 일정과 의존관계를 별도 애그리거트로 바라보고
  • UX 관점에서 “일정 삭제 실패/롤백” 같은 문제를 최소화하도록 설계

---