Skip to content

Day Plan API Spec

wcorn edited this page Jun 27, 2026 · 3 revisions

API 설계: 주간 계획표 (Weekly Plan)

범위: 멤버의 단일 주간 템플릿 조회 + 전량 교체 두 엔드포인트. orino 내부 데이터라 Google 프록시·미러·펼침 엔드포인트가 없다.

상태: 구현 완료 (2026-06-27, WP0 #633 · WP1 #636). Planner API 위에 올라가며 인증·에러 규약을 상속한다. 결정 근거는 결정 기록.

Base URL: /api

모든 API는 인증 필요 (Authorization: Bearer {accessToken}). 시간대 헤더(X-Timezone) 불필요(블록은 벽시계 TIME, 외부로 안 나감). 응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.

1. 에러 코드

코드 HTTP 메시지
PLN-ERR-002 400 유효하지 않은 요청입니다 (블록 시간/요일 오류)
  • Google 관련 코드(PLN-ERR-003/004/005)는 이 모듈에서 사용하지 않는다(외부 호출 0).

2. 엔드포인트 목록

Method Path 설명
GET /api/planner/plan 주간 템플릿(요일별 블록) 조회
PUT /api/planner/plan 주간 템플릿 전량 교체(저장)

옛 설계의 /plans(복수 CRUD)·/plans/instances(펼침)·/plans/mirror(미러 토글)·google/status 확장은 전부 제거.


3. 주간 템플릿 조회

GET /api/planner/plan

Response 200:

{ "code": "SUCCESS", "data": { "blocks": [
  { "id": 11, "dayOfWeek": 1, "startTime": "08:00", "endTime": "09:00", "label": "기상",        "color": "violet" },
  { "id": 12, "dayOfWeek": 1, "startTime": "10:00", "endTime": "12:00", "label": "개인 프로젝트", "color": "sky"    },
  { "id": 13, "dayOfWeek": 1, "startTime": "12:00", "endTime": "13:00", "label": "점심",        "color": "amber"  },
  { "id": 14, "dayOfWeek": 6, "startTime": "10:00", "endTime": "11:00", "label": "운동",        "color": "emerald"}
] } }
필드 설명
dayOfWeek 요일 0=일 … 6=토
startTime/endTime 벽시계 HH:mm. 항상 endTime > startTime
label 블록 라벨
color 블록 색(토큰 키 또는 hex). null 허용
  • 블록이 없으면 blocks: [](빈 상태).
  • 정렬: dayOfWeek, startTime 오름차순(FE는 받은 순서를 신뢰).

4. 주간 템플릿 전량 교체 (저장)

PUT /api/planner/plan
{ "blocks": [
  { "dayOfWeek": 1, "startTime": "08:00", "endTime": "09:00", "label": "기상",        "color": "violet" },
  { "dayOfWeek": 1, "startTime": "10:00", "endTime": "12:00", "label": "개인 프로젝트", "color": "sky"    },
  { "dayOfWeek": 6, "startTime": "10:00", "endTime": "11:00", "label": "운동",        "color": "emerald"}
] } }
  • 전량 교체(declarative): 요청 blocks = 멤버의 최종 주간 상태. 서버가 기존 블록을 교체한다(블록별 id 불필요 — 보내도 무시 가능).
  • 검증(실패 시 400 PLN-ERR-002):
    • dayOfWeek ∈ 0..6
    • endTime > startTime(같은 요일 내 구간. 자정 넘김 불가 — 수면은 두 블록으로 분리)
    • label 비어있지 않음(공백 트림 후 1자 이상)
    • 같은 요일 블록 시간 겹침: 허용(의도 템플릿이므로 약한 검증. FE에서 경고만)
  • Response 200: 교체된 전체 블록(§3 형식, 새 id 포함).

5. 보안 / Security 설정

  • 신규 보안 설정 변경 없음. /api/planner/plan/**은 인증 필요(Planner와 동일 규칙).
  • 외부 API 호출이 없으므로 토큰 만료·재연동·Google 실패 경로가 존재하지 않는다.

Clone this wiki locally