[CHORE] 백엔드 응답 스펙 수정 반영 및 orval 재생성

.agents/skills/api/timo-api-integration/SKILL.md

@@ -0,0 +1,77 @@
+# timo-api-integration
+
+## 트리거
+
+- "API 연동해줘 / 연동 세팅하자"
+- "orval / 제너레이터 나온 거 붙여줘"
+- mock 데이터를 실제 API 호출로 교체하는 작업
+
+## 참조
+
+- `docs/architecture/state.md` → 서버 상태는 React Query가 단일 출처
+- `docs/architecture/structure.md` → `_queries/` 위치 규칙
+- `apps/timo-web/api/generated/` → orval이 생성한 훅·zod 스키마·모델 (직접 수정 금지)
+- `apps/timo-web/api/client/custom-instance.ts`, `apps/timo-web/api/client/axios.ts` → axios 인스턴스, 에러 인터셉터
+- `apps/timo-web/api/error/api-error.ts` → `ApiError`, `parseApiError`
+
+## 배경
+
+- `api/generated/endpoints/{domain}/{domain}.ts` — orval이 생성한 react-query 훅(`useGetXxx`)과 순수 fetcher 함수, `queryKey` 헬퍼, `getXxxQueryOptions` 팩토리
+- `logout`/`withdraw`/`deleteTodo`/`deleteTag`/`completeOnboarding`처럼 실제로 반환 데이터가 없는 엔드포인트는 백엔드가 `data`를 Java `Object`(빈 스키마)로 선언해서 여전히 `data: zod.unknown().optional()`로 생성된다 — 이건 버그가 아니라 정상이다(정말로 shape이 없는 값이므로).
+- `api/generated/models/*.ts` — 응답 DTO 타입. 실제로 항상 오는 필드는 이제 `?` 없이 생성된다. 다만 gen 스키마는 백엔드가 스펙을 바꿀 때마다 사람 리뷰 없이 재생성되므로 100% 맹신하지는 않는다.
+- 그래도 도메인 로컬 zod 스키마(`app/(domain)/_types/*.ts`)로 한 번 더 검증한다 — 로컬 스키마의 `.parse()`가 "백엔드가 계약을 조용히 느슨하게 바꿨는지"를 잡아내는 방어선 역할을 한다. 로컬 스키마 작성 시 gen 응답 스키마를 기반 초안으로 그대로 가져다 쓰고, UI가 추가로 좁혀야 하는 부분(더 좁은 enum, 파생 필드 등)만 수정한다.
+
+## 워크플로우
+
+### Phase 1 — 대상 엔드포인트 확인
+
+- `/v3/api-docs`에서 대상 성공 응답의 `application/json` content type과 필드별 `required`를 확인한다.
+- 확인 결과를 반영하도록 `pnpm gen:api`를 실행한 뒤 생성된 모델·Zod 스키마를 검토한다.
+- `api/generated/endpoints/{domain}/{domain}.ts`에서 필요한 fetcher 함수(예: `getHome`)와 `getGetXxxQueryKey` 헬퍼를 찾는다.
+- 응답이 `BaseResponseXxx { status, message, data }` 형태로 감싸져 있는지 `api/generated/models/`에서 확인한다 — 실제 필요한 값은 `.data`에 있다.
+
+### Phase 2 — 로컬 zod 스키마로 응답 검증
+
+- 도메인 `_types/*.ts`에 이미 손으로 작성한 zod 스키마가 있는지 확인한다. 없으면 생성된 응답 zod 스키마(`api/generated/endpoints/{domain}/{domain}.zod.ts`)를 기반 초안으로 가져와 작성한다 — 이제 실제 shape을 담고 있으므로 신뢰할 수 있다.
+- gen 스키마와 UI가 실제로 필요로 하는 shape이 다르면(더 좁은 enum, 파생 필드 등) 로컬 스키마에서 추가로 좁힌다.
+- `select`에서 로컬 스키마의 `.parse()`/`.safeParse()`로 최종 검증한다 — gen 스키마를 UI까지 직접 노출하지 않고 반드시 로컬 스키마를 한 번 거친다. 백엔드가 스펙을 다시 느슨하게 바꿔도 이 단계가 조용히 깨지지 않고 파싱 실패로 드러나게 하는 방어선이다.
+
+### Phase 3 — `_queries/` 훅 작성
+
+- 위치: `app/(domain)/_queries/use-xxx.ts`
+- `useSuspenseQuery`를 쓸지 `useQuery`를 쓸지는 컴포넌트가 `AsyncBoundary`(Suspense) 안에 있는지로 결정한다. `AsyncBoundary`로 감싸져 있으면 `useSuspenseQuery`를 쓴다.
+- **주의**: 생성된 `getGetXxxQueryOptions()` 팩토리를 그대로 `useSuspenseQuery`에 스프레드하면 `UseQueryOptions`가 허용하는 `skipToken`과 `UseSuspenseQueryOptions`가 타입 충돌을 일으킨다. `queryKey`/`queryFn`은 생성된 `getGetXxxQueryKey` + 원본 fetcher 함수로 직접 조립한다.
+- `select`에서 `BaseResponse.data`를 언랩하고 로컬 zod 스키마로 `.parse()`해서 반환한다.
+
+```ts
+"use client";
+
+import { useSuspenseQuery } from "@tanstack/react-query";
+
+import {
+  getGetHomeQueryKey,
+  getHome,
+} from "@/api/generated/endpoints/home/home";
+import { homeViewDataSchema } from "@/app/[locale]/(main)/(with-time-sidebar)/home/_types/home-view-type";
+
+export const useHomeView = ({ filter, baseDate }: GetHomeViewParams) =>
+  useSuspenseQuery({
+    queryKey: getGetHomeQueryKey({ filter, baseDate }),
+    queryFn: ({ signal }) => getHome({ filter, baseDate }, undefined, signal),
+    select: ({ data }) => homeViewDataSchema.parse(data),
+  });
+```
+
+### Phase 4 — 컨테이너 연결
+
+- mock 함수 import를 제거하고 새 훅으로 교체한다.
+- 다른 도메인이 같은 mock을 참조하고 있는지 확인(`Grep`)하고, 참조 중이면 mock 파일 자체는 지우지 않는다.
+- 로그인 연동 전이라 요청이 401/네트워크 에러로 실패할 수 있다 — `useSuspenseQuery`가 던지는 에러는 상위 `error.tsx`(라우트 레벨) 또는 `AsyncBoundary`의 `errorFallback`이 잡는지 확인한다. 둘 다 없으면 최소한 라우트 레벨 `error.tsx` 존재 여부를 확인해 화면이 완전히 깨지지 않게 한다.
+
+### Phase 5 — 자가 검토
+
+- [ ] `api/generated/` 내부 파일을 직접 수정하지 않았는가 (재생성 시 사라짐)
+- [ ] 응답을 로컬 zod 스키마로 `.parse()`해서 검증했는가 (gen 응답 스키마를 그대로 UI까지 노출하지 않았는가)
+- [ ] `useSuspenseQuery` 사용 시 `queryKey`/`queryFn`을 직접 조립해 타입 충돌을 피했는가
+- [ ] `tsc --noEmit`, `eslint` 통과
+- [ ] 다른 도메인이 참조하는 mock을 실수로 지우지 않았는가

AGENTS.md

@@ -44,6 +44,12 @@ Claude Code / Codex 공통 진입점입니다.
 | 스토리북, storybook              | `.agents/skills/ui/timo-storybook/SKILL.md` |
 | 피그마, figma                    | `.agents/skills/ui/timo-figma/SKILL.md`     |
 
+### API
+
+| 트리거                                                                                    | Read 할 파일                                       |
+| ----------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| API 연동, 연동 세팅, mock 데이터를 실제 API 호출로 교체, orval, 제너레이터 나온 거 붙여줘 | `.agents/skills/api/timo-api-integration/SKILL.md` |
+
 ### Quality
 
 | 트리거               | Read 할 파일                                    |

apps/timo-web/api/generated/endpoints/ai/ai.zod.ts

@@ -31,4 +31,12 @@ export const RecommendDurationBody = zod.object({
   tagId: zod.number().nullish().describe("투두 태그 ID"),
 });
 
-export const RecommendDurationResponse = zod.unknown();
+export const RecommendDurationResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      recommendedMinutes: zod.number().describe("추천 예상 소요 시간(분)"),
+    })
+    .optional(),
+});

apps/timo-web/api/generated/endpoints/auth/auth.zod.ts

@@ -21,24 +21,56 @@ export const TokenBody = zod.object({
     ),
 });
 
-export const TokenResponse = zod.unknown();
+export const TokenResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      accessToken: zod.string(),
+      user: zod.object({
+        id: zod.number(),
+        name: zod.string(),
+        email: zod.string(),
+        profileImageUrl: zod.string().optional(),
+        onboardingCompleted: zod.boolean(),
+      }),
+      isNewUser: zod.boolean(),
+    })
+    .optional(),
+});
 
 /**
  * 쿠키로 전달된 RefreshToken과 sessionId를 검증하여 AccessToken 재발급합니다.<br>
  * 재발급 성공 시 RefreshToken과 sessionId 쿠키를 갱신합니다.
  * @summary AccessToken 재발급
  */
-export const ReissueResponse = zod.unknown();
+export const ReissueResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      accessToken: zod.string().describe("새로 발급된 AccessToken"),
+    })
+    .optional(),
+});
 
 /**
  * 현재 세션을 로그아웃하고 RefreshToken 및 sessionId 쿠키를 만료시킵니다.
  * @summary 로그아웃
  */
-export const LogoutResponse = zod.unknown();
+export const LogoutResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod.unknown().optional(),
+});
 
 /**
  * 회원 탈퇴를 진행하며, 사용자와 관련된 모든 데이터를 영구 삭제합니다.<br>
  * 이 작업은 되돌릴 수 없습니다.
  * @summary 회원 탈퇴
  */
-export const WithdrawResponse = zod.unknown();
+export const WithdrawResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod.unknown().optional(),
+});

apps/timo-web/api/generated/endpoints/focus/focus.zod.ts

@@ -14,4 +14,38 @@ import * as zod from "zod";
  * 두 경우 모두 hasTodo는 false, todo는 null입니다.
  * @summary 집중 모드 TODO 조회
  */
-export const GetFocusTodoResponse = zod.unknown();
+export const GetFocusTodoResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      date: zod.iso.date(),
+      dayOfWeek: zod.enum(["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"]),
+      hasTodo: zod.boolean(),
+      todo: zod
+        .object({
+          todoId: zod.number(),
+          icon: zod.string().optional(),
+          title: zod.string(),
+          completed: zod.boolean(),
+          durationSeconds: zod.number().optional(),
+          priority: zod.string().optional(),
+          tag: zod
+            .object({
+              tagId: zod.number(),
+              name: zod.string(),
+            })
+            .optional(),
+          isRepeated: zod.boolean(),
+          subtasks: zod.array(
+            zod.object({
+              subtaskId: zod.number(),
+              content: zod.string(),
+              completed: zod.boolean(),
+            }),
+          ),
+        })
+        .optional(),
+    })
+    .optional(),
+});

apps/timo-web/api/generated/endpoints/home/home.zod.ts

@@ -21,11 +21,104 @@ export const GetHomeQueryParams = zod.object({
     .describe("기준 날짜(yyyy-MM-dd), 미입력 시 오늘"),
 });
 
-export const GetHomeResponse = zod.unknown();
+export const GetHomeResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      filter: zod.enum(["DEFAULT", "WEEK"]),
+      baseDate: zod.iso.date(),
+      days: zod.array(
+        zod.object({
+          date: zod.iso.date(),
+          dayOfWeek: zod.enum([
+            "MON",
+            "TUE",
+            "WED",
+            "THU",
+            "FRI",
+            "SAT",
+            "SUN",
+          ]),
+          isHoliday: zod.boolean(),
+          isToday: zod.boolean(),
+          totalCount: zod.number(),
+          completedCount: zod.number(),
+          todos: zod.array(
+            zod.object({
+              todoId: zod.number(),
+              icon: zod.string().optional(),
+              title: zod.string(),
+              completed: zod.boolean(),
+              durationSeconds: zod.number().optional(),
+              priority: zod.string().optional(),
+              tag: zod
+                .object({
+                  tagId: zod.number(),
+                  name: zod.string(),
+                })
+                .optional(),
+              hasMemo: zod.boolean(),
+              isRepeated: zod.boolean(),
+              timerStatus: zod.enum(["STOPPED", "RUNNING", "PAUSED"]),
+              sortOrder: zod.number().optional(),
+              subtasks: zod.array(
+                zod.object({
+                  subtaskId: zod.number(),
+                  content: zod.string(),
+                  completed: zod.boolean(),
+                }),
+              ),
+            }),
+          ),
+        }),
+      ),
+    })
+    .optional(),
+});
 
 /**
  * 오늘 하루의 TODO 목록을 하위 태스크 상세 정보까지 포함해 단일 객체로 조회합니다.
  * TODO는 미완료 먼저, 같은 완료 그룹 안에서는 sortOrder 오름차순으로 정렬됩니다.
  * @summary 오늘 뷰 TODO 목록 조회
  */
-export const GetTodayResponse = zod.unknown();
+export const GetTodayResponse = zod.object({
+  status: zod.number().optional(),
+  message: zod.string().optional(),
+  data: zod
+    .object({
+      date: zod.iso.date(),
+      dayOfWeek: zod.enum(["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"]),
+      totalCount: zod.number(),
+      completedCount: zod.number(),
+      todos: zod.array(
+        zod.object({
+          todoId: zod.number(),
+          icon: zod.string().optional(),
+          title: zod.string(),
+          completed: zod.boolean(),
+          date: zod.iso.date(),
+          durationSeconds: zod.number().optional(),
+          priority: zod.string().optional(),
+          tag: zod
+            .object({
+              tagId: zod.number(),
+              name: zod.string(),
+            })
+            .optional(),
+          isRepeated: zod.boolean(),
+          hasMemo: zod.boolean(),
+          timerStatus: zod.enum(["STOPPED", "RUNNING", "PAUSED"]),
+          sortOrder: zod.number().optional(),
+          subtasks: zod.array(
+            zod.object({
+              subtaskId: zod.number(),
+              content: zod.string(),
+              completed: zod.boolean(),
+            }),
+          ),
+        }),
+      ),
+    })
+    .optional(),
+});