Repository navigation
Day Plan API Spec
wcorn edited this page Jun 27, 2026
·
3 revisions
범위: 멤버의 단일 주간 템플릿 조회 + 전량 교체 두 엔드포인트. orino 내부 데이터라 Google 프록시·미러·펼침 엔드포인트가 없다.
상태: 구현 완료 (2026-06-27, WP0 #633 · WP1 #636). Planner API 위에 올라가며 인증·에러 규약을 상속한다. 결정 근거는 결정 기록.
Base URL: /api
모든 API는 인증 필요 (Authorization: Bearer {accessToken}). 시간대 헤더(X-Timezone) 불필요(블록은 벽시계 TIME, 외부로 안 나감). 응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.
| 코드 | HTTP | 메시지 |
|---|---|---|
| PLN-ERR-002 | 400 | 유효하지 않은 요청입니다 (블록 시간/요일 오류) |
- Google 관련 코드(PLN-ERR-003/004/005)는 이 모듈에서 사용하지 않는다(외부 호출 0).
| Method | Path | 설명 |
|---|---|---|
| GET | /api/planner/plan |
주간 템플릿(요일별 블록) 조회 |
| PUT | /api/planner/plan |
주간 템플릿 전량 교체(저장) |
옛 설계의
/plans(복수 CRUD)·/plans/instances(펼침)·/plans/mirror(미러 토글)·google/status확장은 전부 제거.
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는 받은 순서를 신뢰).
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포함).
- 신규 보안 설정 변경 없음.
/api/planner/plan/**은 인증 필요(Planner와 동일 규칙). - 외부 API 호출이 없으므로 토큰 만료·재연동·Google 실패 경로가 존재하지 않는다.