[RELEASE] v0.0.2

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

@@ -38,11 +38,14 @@
 
 ### Phase 3 — `_queries/` 훅 작성
 
-- 위치: `app/(domain)/_queries/use-xxx.ts`
+- 위치: `app/(domain)/_queries/use-xxx-query.ts` (조회) / `use-xxx-mutation.ts` (변경)
+- 네이밍: 파일명은 `-query.ts`/`-mutation.ts`로, export하는 함수명은 `~Query`/`~Mutation`으로 끝낸다. 파일당 훅 1개가 기본이다. → `docs/conventions/naming.md` 참조
 - `useSuspenseQuery`를 쓸지 `useQuery`를 쓸지는 컴포넌트가 `AsyncBoundary`(Suspense) 안에 있는지로 결정한다. `AsyncBoundary`로 감싸져 있으면 `useSuspenseQuery`를 쓴다.
 - **주의**: 생성된 `getGetXxxQueryOptions()` 팩토리를 그대로 `useSuspenseQuery`에 스프레드하면 `UseQueryOptions`가 허용하는 `skipToken`과 `UseSuspenseQueryOptions`가 타입 충돌을 일으킨다. `queryKey`/`queryFn`은 생성된 `getGetXxxQueryKey` + 원본 fetcher 함수로 직접 조립한다.
 - `select`에서 `BaseResponse.data`를 언랩하고 로컬 zod 스키마로 `.parse()`해서 반환한다.
 
+조회 훅 예시 (`_queries/use-home-view-query.ts`):
+
 ```ts
 "use client";
 
@@ -54,14 +57,36 @@ import {
 } 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) =>
+export const useHomeViewQuery = ({ filter, baseDate }: GetHomeViewParams) =>
   useSuspenseQuery({
     queryKey: getGetHomeQueryKey({ filter, baseDate }),
     queryFn: ({ signal }) => getHome({ filter, baseDate }, undefined, signal),
     select: ({ data }) => homeViewDataSchema.parse(data),
   });
 ```
 
+변경 훅 예시 (`_queries/use-withdraw-mutation.ts`):
+
+```ts
+"use client";
+
+import { useMutation } from "@tanstack/react-query";
+
+import { withdraw } from "@/api/generated/endpoints/auth/auth";
+import { useClearSession } from "@/app/[locale]/(main)/settings/_hooks/use-clear-session";
+
+export const useWithdrawMutation = () => {
+  const clearSession = useClearSession();
+
+  return useMutation({
+    mutationFn: () => withdraw(),
+    onSuccess: () => {
+      clearSession();
+    },
+  });
+};
+```
+
 ### Phase 4 — 컨테이너 연결
 
 - mock 함수 import를 제거하고 새 훅으로 교체한다.
@@ -70,6 +95,7 @@ export const useHomeView = ({ filter, baseDate }: GetHomeViewParams) =>
 
 ### Phase 5 — 자가 검토
 
+- [ ] 훅 파일명/함수명이 `-query`/`~Query`, `-mutation`/`~Mutation` 컨벤션을 따르는가
 - [ ] `api/generated/` 내부 파일을 직접 수정하지 않았는가 (재생성 시 사라짐)
 - [ ] 응답을 로컬 zod 스키마로 `.parse()`해서 검증했는가 (gen 응답 스키마를 그대로 UI까지 노출하지 않았는가)
 - [ ] `useSuspenseQuery` 사용 시 `queryKey`/`queryFn`을 직접 조립해 타입 충돌을 피했는가

apps/timo-web/api/generated/endpoints/terms/terms.ts

@@ -11,9 +11,9 @@ import { customInstance } from "../../../client/custom-instance";
 
 import type { ErrorType } from "../../../client/custom-instance";
 import type {
-  BaseResponseTermsListResponse,
+  BaseResponseTermsDetailResponse,
   ErrorDto,
-  GetTermsParams,
+  GetTermsByConditionParams,
 } from "../../models";
 import type {
   DataTag,
@@ -48,71 +48,81 @@ const withQueryKey = <T extends object, K>(
 };
 
 /**
- * 서비스 이용약관 및 개인정보 처리방침을 조회합니다.
- * type을 지정하지 않으면 전체 약관을 조회하고, SERVICE 또는 PRIVACY를 지정하면 해당 약관만 조회합니다.
- * @summary 약관 내용 조회
+ * 약관 타입과 언어 기준으로 최신 약관 1건을 조회합니다.
+ * @summary 약관 조건 조회
  */
-export const getTerms = (
-  params?: GetTermsParams,
+export const getTermsByCondition = (
+  params: GetTermsByConditionParams,
   options?: SecondParameter<typeof customInstance>,
   signal?: AbortSignal,
 ) => {
-  return customInstance<BaseResponseTermsListResponse>(
+  return customInstance<BaseResponseTermsDetailResponse>(
     { url: `/api/v1/terms`, method: "GET", params, signal },
     options,
   );
 };
 
-export const getGetTermsQueryKey = (params?: GetTermsParams) => {
+export const getGetTermsByConditionQueryKey = (
+  params?: GetTermsByConditionParams,
+) => {
   return [`/api/v1/terms`, ...(params ? [params] : [])] as const;
 };
 
-export const getGetTermsQueryOptions = <
-  TData = Awaited<ReturnType<typeof getTerms>>,
+export const getGetTermsByConditionQueryOptions = <
+  TData = Awaited<ReturnType<typeof getTermsByCondition>>,
   TError = ErrorType<ErrorDto>,
 >(
-  params?: GetTermsParams,
+  params: GetTermsByConditionParams,
   options?: {
     query?: Partial<
-      UseQueryOptions<Awaited<ReturnType<typeof getTerms>>, TError, TData>
+      UseQueryOptions<
+        Awaited<ReturnType<typeof getTermsByCondition>>,
+        TError,
+        TData
+      >
     >;
     request?: SecondParameter<typeof customInstance>;
   },
 ) => {
   const { query: queryOptions, request: requestOptions } = options ?? {};
 
-  const queryKey = queryOptions?.queryKey ?? getGetTermsQueryKey(params);
+  const queryKey =
+    queryOptions?.queryKey ?? getGetTermsByConditionQueryKey(params);
 
-  const queryFn: QueryFunction<Awaited<ReturnType<typeof getTerms>>> = ({
-    signal,
-  }) => getTerms(params, requestOptions, signal);
+  const queryFn: QueryFunction<
+    Awaited<ReturnType<typeof getTermsByCondition>>
+  > = ({ signal }) => getTermsByCondition(params, requestOptions, signal);
 
   return { queryKey, queryFn, ...queryOptions } as UseQueryOptions<
-    Awaited<ReturnType<typeof getTerms>>,
+    Awaited<ReturnType<typeof getTermsByCondition>>,
     TError,
     TData
   > & { queryKey: DataTag<QueryKey, TData, TError> };
 };
 
-export type GetTermsQueryResult = NonNullable<
-  Awaited<ReturnType<typeof getTerms>>
+export type GetTermsByConditionQueryResult = NonNullable<
+  Awaited<ReturnType<typeof getTermsByCondition>>
 >;
-export type GetTermsQueryError = ErrorType<ErrorDto>;
+export type GetTermsByConditionQueryError = ErrorType<ErrorDto>;
 
-export function useGetTerms<
-  TData = Awaited<ReturnType<typeof getTerms>>,
+export function useGetTermsByCondition<
+  TData = Awaited<ReturnType<typeof getTermsByCondition>>,
   TError = ErrorType<ErrorDto>,
 >(
-  params: undefined | GetTermsParams,
+  params: GetTermsByConditionParams,
   options: {
     query: Partial<
-      UseQueryOptions<Awaited<ReturnType<typeof getTerms>>, TError, TData>
+      UseQueryOptions<
+        Awaited<ReturnType<typeof getTermsByCondition>>,
+        TError,
+        TData
+      >
     > &
       Pick<
         DefinedInitialDataOptions<
-          Awaited<ReturnType<typeof getTerms>>,
+          Awaited<ReturnType<typeof getTermsByCondition>>,
           TError,
-          Awaited<ReturnType<typeof getTerms>>
+          Awaited<ReturnType<typeof getTermsByCondition>>
         >,
         "initialData"
       >;
@@ -122,20 +132,24 @@ export function useGetTerms<
 ): DefinedUseQueryResult<TData, TError> & {
   queryKey: DataTag<QueryKey, TData, TError>;
 };
-export function useGetTerms<
-  TData = Awaited<ReturnType<typeof getTerms>>,
+export function useGetTermsByCondition<
+  TData = Awaited<ReturnType<typeof getTermsByCondition>>,
   TError = ErrorType<ErrorDto>,
 >(
-  params?: GetTermsParams,
+  params: GetTermsByConditionParams,
   options?: {
     query?: Partial<
-      UseQueryOptions<Awaited<ReturnType<typeof getTerms>>, TError, TData>
+      UseQueryOptions<
+        Awaited<ReturnType<typeof getTermsByCondition>>,
+        TError,
+        TData
+      >
     > &
       Pick<
         UndefinedInitialDataOptions<
-          Awaited<ReturnType<typeof getTerms>>,
+          Awaited<ReturnType<typeof getTermsByCondition>>,
           TError,
-          Awaited<ReturnType<typeof getTerms>>
+          Awaited<ReturnType<typeof getTermsByCondition>>
         >,
         "initialData"
       >;
@@ -145,14 +159,18 @@ export function useGetTerms<
 ): UseQueryResult<TData, TError> & {
   queryKey: DataTag<QueryKey, TData, TError>;
 };
-export function useGetTerms<
-  TData = Awaited<ReturnType<typeof getTerms>>,
+export function useGetTermsByCondition<
+  TData = Awaited<ReturnType<typeof getTermsByCondition>>,
   TError = ErrorType<ErrorDto>,
 >(
-  params?: GetTermsParams,
+  params: GetTermsByConditionParams,
   options?: {
     query?: Partial<
-      UseQueryOptions<Awaited<ReturnType<typeof getTerms>>, TError, TData>
+      UseQueryOptions<
+        Awaited<ReturnType<typeof getTermsByCondition>>,
+        TError,
+        TData
+      >
     >;
     request?: SecondParameter<typeof customInstance>;
   },
@@ -161,25 +179,29 @@ export function useGetTerms<
   queryKey: DataTag<QueryKey, TData, TError>;
 };
 /**
- * @summary 약관 내용 조회
+ * @summary 약관 조건 조회
  */
 
-export function useGetTerms<
-  TData = Awaited<ReturnType<typeof getTerms>>,
+export function useGetTermsByCondition<
+  TData = Awaited<ReturnType<typeof getTermsByCondition>>,
   TError = ErrorType<ErrorDto>,
 >(
-  params?: GetTermsParams,
+  params: GetTermsByConditionParams,
   options?: {
     query?: Partial<
-      UseQueryOptions<Awaited<ReturnType<typeof getTerms>>, TError, TData>
+      UseQueryOptions<
+        Awaited<ReturnType<typeof getTermsByCondition>>,
+        TError,
+        TData
+      >
     >;
     request?: SecondParameter<typeof customInstance>;
   },
   queryClient?: QueryClient,
 ): UseQueryResult<TData, TError> & {
   queryKey: DataTag<QueryKey, TData, TError>;
 } {
-  const queryOptions = getGetTermsQueryOptions(params, options);
+  const queryOptions = getGetTermsByConditionQueryOptions(params, options);
 
   const query = useQuery(queryOptions, queryClient) as UseQueryResult<
     TData,

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

@@ -8,29 +8,24 @@
 import * as zod from "zod";
 
 /**
- * 서비스 이용약관 및 개인정보 처리방침을 조회합니다.
- * type을 지정하지 않으면 전체 약관을 조회하고, SERVICE 또는 PRIVACY를 지정하면 해당 약관만 조회합니다.
- * @summary 약관 내용 조회
+ * 약관 타입과 언어 기준으로 최신 약관 1건을 조회합니다.
+ * @summary 약관 조건 조회
  */
-export const GetTermsQueryParams = zod.object({
-  type: zod.string().optional().describe("약관 타입(SERVICE, PRIVACY)"),
+export const GetTermsByConditionQueryParams = zod.object({
+  type: zod.string().describe("약관 타입"),
+  language: zod.string().describe("약관 언어"),
 });
 
-export const GetTermsResponse = zod.object({
+export const GetTermsByConditionResponse = zod.object({
   status: zod.number().optional(),
   message: zod.string().optional(),
   data: zod
     .object({
-      terms: zod
-        .array(
-          zod.object({
-            termsId: zod.number().describe("약관 ID"),
-            type: zod.string().describe("약관 타입"),
-            title: zod.string().describe("약관 제목"),
-            content: zod.string().describe("약관 전문"),
-          }),
-        )
-        .describe("약관 목록"),
+      type: zod.string().optional().describe("약관 타입"),
+      language: zod.string().optional().describe("약관 언어"),
+      version: zod.string().optional().describe("약관 버전"),
+      title: zod.string().optional().describe("약관 제목"),
+      content: zod.string().optional().describe("약관 전문"),
     })
     .optional(),
 });

apps/timo-web/api/generated/models/baseResponseTermsListResponse.ts → apps/timo-web/api/generated/models/baseResponseTermsDetailResponse.ts

@@ -5,10 +5,10 @@
  * Timo 서버 API 명세서
  * OpenAPI spec version: v1
  */
-import type { TermsListResponse } from "./termsListResponse";
+import type { TermsDetailResponse } from "./termsDetailResponse";
 
-export interface BaseResponseTermsListResponse {
+export interface BaseResponseTermsDetailResponse {
   status?: number;
   message?: string;
-  data?: TermsListResponse;
+  data?: TermsDetailResponse;
 }

apps/timo-web/api/generated/models/getTermsParams.ts → apps/timo-web/api/generated/models/getTermsByConditionParams.ts

@@ -6,9 +6,13 @@
  * OpenAPI spec version: v1
  */
 
-export interface GetTermsParams {
+export interface GetTermsByConditionParams {
   /**
-   * 약관 타입(SERVICE, PRIVACY)
+   * 약관 타입
    */
-  type?: string;
+  type: string;
+  /**
+   * 약관 언어
+   */
+  language: string;
 }

apps/timo-web/api/generated/models/index.ts

@@ -23,7 +23,7 @@ export * from "./baseResponseStatisticsSummaryResponse";
 export * from "./baseResponseSubtaskStatusChangeResponse";
 export * from "./baseResponseTagCreateResponse";
 export * from "./baseResponseTagListResponse";
-export * from "./baseResponseTermsListResponse";
+export * from "./baseResponseTermsDetailResponse";
 export * from "./baseResponseTimerActiveResponse";
 export * from "./baseResponseTimerExtendResponse";
 export * from "./baseResponseTimerFinishResponse";
@@ -50,7 +50,7 @@ export * from "./getCalendarParams";
 export * from "./getDailyParams";
 export * from "./getHomeParams";
 export * from "./getSummaryParams";
-export * from "./getTermsParams";
+export * from "./getTermsByConditionParams";
 export * from "./getTimeBoxesParams";
 export * from "./getTodoDetailParams";
 export * from "./homeResponse";
@@ -71,8 +71,7 @@ export * from "./tagCreateRequest";
 export * from "./tagCreateResponse";
 export * from "./tagListResponse";
 export * from "./tagResponse";
-export * from "./termsListResponse";
-export * from "./termsResponse";
+export * from "./termsDetailResponse";
 export * from "./timeBoxResponse";
 export * from "./timeBoxResponseEndAction";
 export * from "./timeBoxResponseStartAction";

apps/timo-web/api/generated/models/termsResponse.ts → apps/timo-web/api/generated/models/termsDetailResponse.ts

@@ -6,13 +6,15 @@
  * OpenAPI spec version: v1
  */
 
-export interface TermsResponse {
-  /** 약관 ID */
-  termsId: number;
+export interface TermsDetailResponse {
   /** 약관 타입 */
-  type: string;
+  type?: string;
+  /** 약관 언어 */
+  language?: string;
+  /** 약관 버전 */
+  version?: string;
   /** 약관 제목 */
-  title: string;
+  title?: string;
   /** 약관 전문 */
-  content: string;
+  content?: string;
 }