create-web-0to1 0.1.0

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/04-API/354/231/200-/353/215/260/354/235/264/355/204/260.md

@@ -0,0 +1,199 @@
+# API와 데이터
+
+## 원칙
+
+- 공통 request 계층과 feature API 계층을 분리합니다.
+- 컴포넌트는 `fetch` 구현이 아니라 도메인 API 함수만 호출하게 만듭니다.
+- 공통 request는 공통 처리까지만 맡고, 비즈니스 로직은 맡지 않습니다.
+
+## Why?
+
+- 공통 request가 너무 똑똑해지면 재사용성과 테스트성이 같이 떨어집니다.
+- 컴포넌트에서 `fetch`를 직접 길게 쓰기 시작하면 도메인 의도가 흐려집니다.
+- feature API가 있으면 Query, Server Component, Action 어디서든 같은 함수를 재사용하기 쉬워집니다.
+
+## 공통 request가 맡는 일
+
+- base URL 관리
+- 공통 헤더 처리
+- 인증 토큰 주입
+- 요청 취소 처리
+- 에러 정규화
+
+## 공통 request가 맡지 않는 일
+
+- 모달 열기
+- 토스트 띄우기
+- 화면 이동
+- 특정 기능 전용 분기
+
+## API layer 원칙
+
+- feature별 API 함수는 feature 안에 둡니다.
+- 필요하면 DTO, 폼 타입, 도메인 타입을 분리합니다.
+- 응답은 실사용 데이터 형태로 정리하되, 서버 원본이 꼭 필요하면 명시적으로 구분합니다.
+- 템플릿 기준으로 공통 요청은 `src/shared/api/request.server.ts`, `src/shared/api/request.client.ts`를 재사용합니다.
+- 인증이 필요한 요청은 `requestServerAuth`, `requestClientAuth`를 우선 검토합니다.
+
+## TanStack Query 기준
+
+- Query key는 feature의 `hooks/query-keys.ts`처럼 hook 계층 가까이에서 관리합니다.
+- Query와 Mutation은 역할을 분리합니다.
+- Query 함수는 재사용 가능한 API 함수에 연결하기 쉽게 만듭니다.
+- Mutation은 요청만 보내지 말고, 성공 후 어떤 query를 갱신할지도 같이 정합니다.
+
+## Mutation 후 갱신 기준
+
+- 생성, 수정, 삭제가 끝나면 어떤 목록과 상세 데이터가 영향을 받는지 같이 봅니다.
+- 성공 후 `invalidateQueries`를 할지, 응답으로 바로 cache를 갱신할지 기준을 미리 정합니다.
+- 변경 범위가 단순하면 invalidate로 시작하고, 정말 필요할 때만 직접 cache update를 검토합니다.
+- mutation 훅 안에서 갱신 기준이 보이게 두는 편이 유지보수에 유리합니다.
+
+## 심화 패턴: `prefetch + hydration`
+
+- 기본 예시는 서버에서 바로 데이터를 가져오는 정도로도 충분합니다.
+- 다만 서버에서 먼저 채운 Query 캐시를 클라이언트에서도 그대로 이어서 쓰고 싶다면 `prefetch + hydration` 패턴을 씁니다.
+- 이 패턴은 초기 로딩을 줄이면서, 클라이언트에서 같은 query를 이어서 사용할 수 있다는 장점이 있습니다.
+
+## 언제 쓰는가
+
+- 서버에서 먼저 데이터를 준비하고
+- 클라이언트에서도 같은 데이터를 `useQuery`로 계속 사용할 때
+- 첫 렌더와 이후 클라이언트 갱신 흐름을 하나로 이어가고 싶을 때
+
+## 언제 굳이 안 써도 되는가
+
+- 서버 컴포넌트에서 한 번만 가져와서 바로 렌더하면 끝나는 화면
+- 클라이언트에서 같은 query를 다시 쓸 필요가 없는 화면
+- 기본 설명 문서나 단순 예시
+
+## 심화 예시 코드
+
+```tsx
+// src/app/posts/page.tsx
+import { getPostListServer } from '@/features/posts/api/get-post-list.server';
+import { PostListClient } from '@/features/posts/components/post-list-client';
+import { postQueryKeys } from '@/features/posts/hooks/query-keys';
+import { QueryHydration } from '@/shared/query/hydration';
+
+export default async function PostsPage() {
+  return (
+    <QueryHydration
+      prefetch={(queryClient) =>
+        queryClient.prefetchQuery({
+          queryKey: postQueryKeys.list(),
+          queryFn: getPostListServer,
+        })
+      }
+    >
+      <PostListClient />
+    </QueryHydration>
+  );
+}
+```
+
+```tsx
+// src/features/posts/components/post-list-client.tsx
+'use client';
+
+import { PostList } from '@/features/posts/components/post-list';
+import { usePostListQuery } from '@/features/posts/hooks/use-post-list-query';
+
+export function PostListClient() {
+  const { data = [] } = usePostListQuery();
+
+  return <PostList posts={data} />;
+}
+```
+
+이 패턴은 "서버에서 먼저 채우고, 클라이언트가 같은 query를 이어받는다"는 흐름이 핵심입니다.
+
+## 기본 예시 코드
+
+```ts
+// src/features/posts/api/get-post-list.server.ts
+import { requestServer } from '@/shared/api/request.server';
+
+type GetPostListResponse = {
+  items: { id: string; title: string }[];
+};
+
+export async function getPostListServer() {
+  const response = await requestServer<GetPostListResponse>({
+    method: 'GET',
+    url: '/posts',
+  });
+
+  return response.items;
+}
+```
+
+```ts
+// src/features/posts/api/get-post-list.client.ts
+import { requestClient } from '@/shared/api/request.client';
+
+type GetPostListResponse = {
+  items: { id: string; title: string }[];
+};
+
+export async function getPostListClient() {
+  const response = await requestClient<GetPostListResponse>({
+    method: 'GET',
+    url: '/posts',
+  });
+
+  return response.items;
+}
+```
+
+```ts
+// src/features/posts/hooks/query-keys.ts
+export const postQueryKeys = {
+  all: ['posts'] as const,
+  list: () => [...postQueryKeys.all, 'list'] as const,
+};
+```
+
+```tsx
+// src/features/posts/hooks/use-post-list-query.ts
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+
+import { getPostListClient } from '@/features/posts/api/get-post-list.client';
+import { postQueryKeys } from '@/features/posts/hooks/query-keys';
+
+export function usePostListQuery() {
+  return useQuery({
+    queryKey: postQueryKeys.list(),
+    queryFn: getPostListClient,
+  });
+}
+```
+
+```tsx
+// src/features/posts/hooks/use-create-post-mutation.ts
+'use client';
+
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import { createPostClient } from '@/features/posts/api/create-post.client';
+import { postQueryKeys } from '@/features/posts/hooks/query-keys';
+
+export function useCreatePostMutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createPostClient,
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: postQueryKeys.all,
+      });
+    },
+  });
+}
+```
+
+## 한 줄 요약
+
+공통 request는 네트워크 공통 처리만 맡고, 실제 도메인 의미는 feature API가 담당합니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/05-/354/227/220/353/237/254/354/231/200-UI-/354/203/201/355/203/234.md

@@ -0,0 +1,159 @@
+# 에러와 UI 상태
+
+## 원칙
+
+- 에러는 전역 에러와 로컬 에러를 구분합니다.
+- 인증 만료, 네트워크 장애, 서비스 장애처럼 앱 전체에 영향이 큰 것은 전역에서 다룹니다.
+- 특정 목록 실패, 특정 액션 실패, 폼 제출 실패는 로컬에서 다룹니다.
+
+## Why?
+
+- 모든 에러를 전역에서 처리하면 사용자 맥락이 사라집니다.
+- 반대로 모든 에러를 각 화면에서 처리하면 공통 대응이 깨집니다.
+- 로딩도 범위에 맞춰 보여줘야 사용자가 무엇이 기다리는 중인지 이해할 수 있습니다.
+
+## 로딩과 화면 상태
+
+- 로딩 UI는 범위에 맞게 보여줍니다.
+- 페이지 전체 대기면 페이지 로딩
+- 일부 목록만 대기면 섹션 로딩
+- 버튼만 진행 중이면 버튼 pending
+
+화면 상태는 최소한 아래를 구분합니다.
+
+- `loading`
+- `error`
+- `empty`
+- `success`
+
+## 모달 원칙
+
+- 공통 모달은 전역 UI 계층에서 렌더링합니다.
+- 필요한 화면이나 상위 계층이 모달을 열도록 구성합니다.
+- fetch나 low-level 유틸이 모달을 직접 제어하지 않게 합니다.
+
+## 전역 에러 핸들러 원칙
+
+- 전역 에러 핸들러는 인증 만료, 네트워크 오류처럼 앱 공통 반응까지만 맡깁니다.
+- 실제 화면별 fallback UI와 문구는 feature 가까이에서 처리합니다.
+- 인증 이동은 이벤트 리스너, 공통 알림은 modal store 같은 전역 UI 계층에서 받게 구성합니다.
+- 요청 취소나 abort는 전역 에러로 취급하지 않고 조용히 무시합니다.
+
+## 예시 코드
+
+```tsx
+// src/features/posts/components/post-list-section.tsx
+'use client';
+
+import { normalizeAppError } from '@/shared/api/app-error';
+import { PostList } from '@/features/posts/components/post-list';
+import { usePostListQuery } from '@/features/posts/hooks/use-post-list-query';
+
+export function PostListSection() {
+  const { data = [], isPending, isError, error } = usePostListQuery();
+
+  if (isPending) {
+    return <p>불러오는 중...</p>;
+  }
+
+  if (isError) {
+    return <p>{normalizeAppError(error).message}</p>;
+  }
+
+  if (data.length === 0) {
+    return <p>등록된 게시글이 없습니다.</p>;
+  }
+
+  return <PostList posts={data} />;
+}
+```
+
+```tsx
+// src/app/providers.tsx
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { QueryProviders } from '@/shared/query/providers';
+import { handleClientQueryError } from '@/shared/query/query-error-handler.client';
+
+type AppProvidersProps = {
+  children: ReactNode;
+};
+
+export function AppProviders({ children }: AppProvidersProps) {
+  return <QueryProviders onGlobalError={handleClientQueryError}>{children}</QueryProviders>;
+}
+```
+
+```ts
+// src/shared/query/query-error-handler.client.ts
+'use client';
+
+import { APP_ERROR_CODES, normalizeAppError } from '@/shared/api/app-error';
+import { dispatchUnauthorizedEvent } from '@/shared/auth/auth-events';
+import { useModalStore } from '@/shared/ui/modal-store';
+
+export function handleClientQueryError(error: unknown) {
+  const appError = normalizeAppError(error);
+
+  if (appError.code === APP_ERROR_CODES.REQUEST_ABORTED) return;
+
+  if (appError.code === APP_ERROR_CODES.UNAUTHORIZED) {
+    dispatchUnauthorizedEvent();
+    return;
+  }
+
+  if (appError.code === APP_ERROR_CODES.NETWORK_ERROR) {
+    useModalStore.getState().openModal({
+      title: '네트워크 오류',
+      description: '잠시 후 다시 시도해주세요.',
+    });
+    return;
+  }
+
+  if (appError.code === APP_ERROR_CODES.FORBIDDEN) {
+    useModalStore.getState().openModal({
+      title: '접근 권한 없음',
+      description: '이 작업을 수행할 권한이 없습니다.',
+    });
+  }
+}
+```
+
+취소된 요청은 사용자가 직접 중단한 흐름이거나 화면 전환 과정에서 자연스럽게 생길 수 있어서, 보통 모달이나 토스트로 다시 보여주지 않습니다.
+
+```tsx
+// src/shared/auth/auth-error-listener.tsx
+'use client';
+
+import { usePathname, useRouter } from 'next/navigation';
+import { useEffect } from 'react';
+
+import { AUTH_UNAUTHORIZED_EVENT } from '@/shared/auth/auth-events';
+
+export function AuthErrorListener() {
+  const pathname = usePathname();
+  const router = useRouter();
+
+  useEffect(() => {
+    function handleUnauthorized() {
+      if (pathname === '/login') return;
+
+      router.replace('/login');
+    }
+
+    window.addEventListener(AUTH_UNAUTHORIZED_EVENT, handleUnauthorized);
+
+    return () => {
+      window.removeEventListener(AUTH_UNAUTHORIZED_EVENT, handleUnauthorized);
+    };
+  }, [pathname, router]);
+
+  return null;
+}
+```
+
+## 한 줄 요약
+
+에러는 범위에 따라 나누고, 로딩은 범위에 맞게 보여주고, 전역 처리는 최대한 얇게 유지합니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/06-/355/217/274.md

@@ -0,0 +1,116 @@
+# 폼
+
+## 원칙
+
+- 검증은 `zod`, 폼 상태 관리는 `react-hook-form`이 맡도록 역할을 나눕니다.
+- 생성 폼과 수정 폼은 책임이 다르면 분리합니다.
+- 공통 `Form`/`Field` 컴포넌트는 반복 패턴이 충분히 생겼을 때만 만듭니다.
+
+## Why?
+
+- 검증 로직과 입력 상태를 분리하면 재사용과 테스트가 쉬워집니다.
+- 생성과 수정은 비슷해 보여도 초기값, 제출 API, 검증 규칙이 달라지기 쉽습니다.
+- 폼 제출 UX가 약하면 사용자는 지금 저장 중인지, 실패했는지 알기 어렵습니다.
+
+## 제출 UX
+
+- 제출 중 상태를 명확히 보여줍니다.
+- 중복 제출을 막습니다.
+- 실패 시 사용자가 이해할 수 있는 에러를 보여줍니다.
+
+## 체크 기준
+
+- 이 필드 패턴이 여러 폼에서 반복되는가
+- 생성과 수정이 초기값, 검증, 제출 흐름이 같은가
+- 에러 메시지가 입력 위치와 충분히 가깝게 보이는가
+
+## 예시 코드
+
+```ts
+// src/features/posts/hooks/use-create-post-mutation.ts
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+
+import { createPostClient } from '@/features/posts/api/create-post.client';
+
+export function useCreatePostMutation() {
+  return useMutation({
+    mutationFn: createPostClient,
+  });
+}
+```
+
+```tsx
+// src/features/posts/components/create-post-form.tsx
+'use client';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+
+import { useCreatePostMutation } from '@/features/posts/hooks/use-create-post-mutation';
+import { TextInputField } from '@/shared/ui/text-input-field';
+
+const createPostSchema = z.object({
+  title: z.string().min(1, '제목을 입력해주세요.'),
+  content: z.string().min(10, '내용은 10자 이상 입력해주세요.'),
+});
+
+type CreatePostFormValues = z.infer<typeof createPostSchema>;
+
+export function CreatePostForm() {
+  const mutation = useCreatePostMutation();
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+  } = useForm<CreatePostFormValues>({
+    resolver: zodResolver(createPostSchema),
+    defaultValues: {
+      title: '',
+      content: '',
+    },
+  });
+
+  const onSubmit = handleSubmit(async (values) => {
+    await mutation.mutateAsync(values);
+  });
+
+  return (
+    <form className="flex flex-col gap-4" onSubmit={onSubmit}>
+      <TextInputField
+        label="제목"
+        required
+        error={errors.title?.message}
+        placeholder="제목을 입력하세요"
+        {...register('title')}
+      />
+
+      <div className="flex flex-col gap-2">
+        <label htmlFor="content" className="text-sm font-semibold text-zinc-900">
+          내용
+        </label>
+        <textarea
+          id="content"
+          className="min-h-40 rounded-xl border border-zinc-300 px-4 py-3 text-sm text-zinc-950 outline-none transition focus:border-zinc-950"
+          {...register('content')}
+        />
+        {errors.content ? <p className="text-sm text-rose-600">{errors.content.message}</p> : null}
+      </div>
+
+      <button
+        type="submit"
+        disabled={mutation.isPending}
+        className="rounded-xl bg-zinc-950 px-4 py-3 text-sm font-medium text-white disabled:opacity-50"
+      >
+        {mutation.isPending ? '저장 중...' : '저장'}
+      </button>
+    </form>
+  );
+}
+```
+
+## 한 줄 요약
+
+폼은 검증과 상태 관리를 분리하고, 제출 중·실패 상태를 사용자가 분명히 알 수 있게 만듭니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/07-/354/212/244/355/203/200/354/235/274/353/247/201/352/263/274-/354/240/221/352/267/274/354/204/261.md

@@ -0,0 +1,73 @@
+# 스타일링과 접근성
+
+## 원칙
+
+- 공통 스타일은 공통 UI 컴포넌트에서 관리합니다.
+- 기능 전용 스타일은 feature 가까이에 둡니다.
+- spacing, color, typography는 반복 가능한 기준을 정해 사용합니다.
+- 상태별 스타일도 일관되게 관리합니다.
+
+## Why?
+
+- 공통 스타일 기준이 없으면 화면마다 간격과 톤이 달라집니다.
+- 스타일을 지나치게 전역화하면 feature 고유 UI까지 묶여버립니다.
+- 접근성은 나중에 덧붙이기보다 기본 마크업에서부터 지키는 편이 훨씬 쉽습니다.
+
+## 접근성 원칙
+
+- 의미에 맞는 HTML 태그를 사용합니다.
+- `input`은 항상 `label`과 연결합니다.
+- 키보드만으로도 조작 가능해야 합니다.
+- focus 스타일을 없애지 않습니다.
+
+## 빠른 체크
+
+- 이 UI가 마우스 없이도 조작 가능한가
+- label 없이 입력 요소가 놓여 있지 않은가
+- 성공/에러/비활성 상태가 스타일만 달라지는 것이 아니라 의미도 전달되는가
+
+## 예시 코드
+
+```tsx
+// src/shared/ui/text-input-field.tsx
+import type { InputHTMLAttributes } from 'react';
+
+type TextInputFieldProps = {
+  label: string;
+  required?: boolean;
+  error?: string;
+  helperText?: string;
+} & InputHTMLAttributes<HTMLInputElement>;
+
+export function TextInputField({
+  label,
+  required,
+  error,
+  helperText,
+  id,
+  className = '',
+  ...props
+}: TextInputFieldProps) {
+  const inputId = id ?? props.name;
+
+  return (
+    <div className="flex flex-col gap-2">
+      <label htmlFor={inputId} className="text-sm font-semibold text-zinc-900">
+        {label}
+        {required ? <span className="ml-1 text-rose-600">*</span> : null}
+      </label>
+      <input
+        id={inputId}
+        className={`rounded-xl border px-4 py-3 text-sm text-zinc-950 outline-none ring-0 transition placeholder:text-zinc-400 focus:border-zinc-950 ${error ? 'border-rose-500' : 'border-zinc-300'} ${className}`}
+        {...props}
+      />
+      {error ? <p className="text-sm text-rose-600">{error}</p> : null}
+      {!error && helperText ? <p className="text-sm text-zinc-500">{helperText}</p> : null}
+    </div>
+  );
+}
+```
+
+## 한 줄 요약
+
+스타일은 일관된 기준으로 관리하고, 접근성은 기본 동작이 자연스럽게 되도록 설계합니다.

package/templates/shared/docs//352/260/234/353/260/234/354/233/220/354/271/231/08-/353/204/244/354/235/264/353/260/215-/354/204/244/354/240/225-/355/217/254/353/247/267/355/214/205.md

@@ -0,0 +1,98 @@
+# 네이밍, 설정, 포맷팅
+
+## 원칙
+
+- 이름만 봐도 역할이 보이게 짓습니다.
+- 설정은 한 곳에서 읽고 검증합니다.
+- 포맷팅은 공통 함수로 관리합니다.
+
+## Why?
+
+- 이름이 모호하면 코드 탐색 비용이 계속 쌓입니다.
+- 환경변수를 여기저기서 직접 읽으면 누락과 오타를 찾기 어렵습니다.
+- 날짜와 숫자 포맷팅을 컴포넌트마다 직접 처리하면 표현이 금방 깨집니다.
+
+## 네이밍
+
+- 파일명은 `kebab-case`
+- 컴포넌트명은 `PascalCase`
+- 훅은 `useXxx`
+- boolean은 `is`, `has`, `can`
+- 함수명은 동사 + 대상이 보이게 짓습니다.
+- 애매한 이름보다 도메인 이름을 직접 사용합니다.
+
+## 상수와 설정
+
+- 반복되고 의미 있는 값만 상수로 분리합니다.
+- 도메인 상수는 feature 내부에 둡니다.
+- 진짜 전역 공통 상수만 `shared`에 둡니다.
+- 환경변수와 설정값은 공통 config 계층에서 읽습니다.
+- 필수 환경변수는 초기에 검증해서 조용히 누락되지 않게 합니다.
+
+## 포맷팅
+
+- 날짜, 숫자, 텍스트 포맷팅은 컴포넌트마다 직접 처리하지 않습니다.
+- locale, timezone, 표현 형식은 공통 함수에서 일관되게 관리합니다.
+- 절대 날짜와 상대 시간을 구분합니다.
+- 포맷팅은 표시 책임만 갖고, 비즈니스 판단까지 맡기지 않습니다.
+
+## 예시 코드
+
+```ts
+// src/shared/config/env.server.ts
+import 'server-only';
+
+import {
+  getOptionalUrlEnv,
+  getRequiredUrlEnv,
+} from '@/shared/config/env-utils';
+
+const publicApiBaseUrl = getRequiredUrlEnv('NEXT_PUBLIC_API_BASE_URL');
+
+export const env = {
+  apiBaseUrl: getOptionalUrlEnv('API_BASE_URL') ?? publicApiBaseUrl,
+  publicApiBaseUrl,
+};
+```
+
+```ts
+// src/shared/utils/format/date.ts
+import type { ConfigType } from 'dayjs';
+
+import { appDayjs } from '@/shared/lib/dayjs';
+
+export type DateValue = ConfigType | null | undefined;
+
+const EMPTY_FORMAT_VALUE = '-';
+
+function formatDateValue(value: DateValue, pattern: string, fallback = EMPTY_FORMAT_VALUE) {
+  if (value === null || value === undefined) return fallback;
+
+  const date = appDayjs(value);
+
+  if (!date.isValid()) return fallback;
+
+  return date.format(pattern);
+}
+
+export function formatDate(value: DateValue) {
+  return formatDateValue(value, 'YYYY-MM-DD');
+}
+
+export function formatDateTime(value: DateValue) {
+  return formatDateValue(value, 'YYYY-MM-DD HH:mm');
+}
+```
+
+```ts
+// 좋은 이름 예시
+const isPending = true;
+const hasPermission = false;
+
+function getPostListClient() {}
+function useCreatePostMutation() {}
+```
+
+## 한 줄 요약
+
+이름은 역할이 바로 보여야 하고, 설정은 한 곳에서 읽어야 하며, 포맷팅은 공통 함수로 통일합니다.