Record Repository

[Next.js] Claude Code CLI를 활용한 리팩토링

seungjunn100 — Fri, 6 Mar 2026 16:25:14 +0900

VSCode 터미널에서 Claude Code CLI를 사용하여 로그인과 회원가입에 대한 리팩토링을 진행해보았다.

우선 UX, 접근성, 기능 구현, 에러 처리, 보안쪽으로 개선 사항을 부탁했다.

내가 생각했던 부분과 생각하지 못한 부분을 다방면으로 생각하여 수정을 해주었다.

하지만, 팀프로젝트가 끝난 상황에서 진행한 상태여서 정확한 정보를 제공해주지 않은 측면에서는 Claude가 가정해서 수정을 진행한 부분도 있었다.

로그인 기능 개선 사항 정리

하드코딩된 테스트 자격증명 제거

파일 : components/auth/LoginForm.tsx
이유 : 프로덕션 코드에 개발용 계정이 그대로 노출되어 있어, 누구나 소스코드를 통해 테스트 계정을 알 수 있는 보안 위험이 있었음.

// ❌ 이전 코드
const [email, setEmail] = useState('wx010622@naver.com');
const [password, setPassword] = useState('1111');

// ✅ 개선 코드
const [email, setEmail] = useState('');
const [password, setPassword] = useState('');

이 부분은 팀프로젝트 발표 당시 빠른 진행을 위해 초기값을 세팅해 둔 상태였는데, 이 부분을 빈 문자열로 다시 세팅해 주었다.

로그인 성공 시 alert() 제거

파일 : components/auth/LoginForm.tsx, components/auth/KakaoLoginCallback.tsx
이유 : alert()은 브라우저 기본 다이얼로그로 UI를 차단하고, 스타일링이 불가능하며 구식 UX. 어차피 router.replace('/')로 페이지가 전환되므로 alert 자체가 불필요함.

// ❌ 이전 코드
alert(`안녕하세요, ${userState.item.name}님!\n로그인이 완료되었습니다!`);
router.replace('/');

// ✅ 개선 코드
router.replace('/');  // alert 없이 바로 이동

나중에 alert()를 토스트 UI를 활용해서 추가하려고 했지만, 로그인이 된 상태라면 router.replace('/')에 의해 Home으로 이동하고 로그인이 된 상태면 헤더 메뉴까지 바뀌게 되어 굳이 필요하지 않아도 될 것 같다.

비밀번호 표시/숨김 토글 추가

파일 : components/auth/LoginForm.tsx, components/auth/AuthInput.tsx, types/auth.ts
이유 : 비밀번호 입력창에 표시/숨김 기능이 없어 오타 확인이 불가했고, 접근성도 떨어졌음. suffix prop을 AuthInput에 추가해 입력창 우측에 버튼을 삽입할 수 있도록 확장함.

// ❌ 이전 코드 (AuthInput — suffix 미지원)
<input id={name} name={name} {...props} className={...} />

// ✅ 개선 코드 (AuthInput — suffix prop으로 절대위치 요소 렌더링)
<div className={suffix ? 'relative' : undefined}>
  <input ... />
  {suffix}
</div>

// ✅ LoginForm에서 눈 아이콘 버튼 주입
const [showPassword, setShowPassword] = useState(false);

<AuthInput
  type={showPassword ? 'text' : 'password'}
  suffix={
    <button
      type="button"
      aria-label={showPassword ? '비밀번호 숨기기' : '비밀번호 표시'}
      onClick={() => setShowPassword((prev) => !prev)}
      className="absolute right-4 top-1/2 -translate-y-1/2 ..."
    >
      {/* SVG 눈 아이콘 */}
    </button>
  }
/>

작성한 비밀번호를 확인하기 위해 표시/숨김 기능이 굳이 필요할까 라는 생각이 들었지만,

저시력 사용자들이 화면을 확대해서 비밀번호를 확인할 수도 있고,
손떨림이 있거나 미세한 조작이 어려운 사용자들도 눈으로 확인하며 오타가 발생하지 않게 작성할 수 있어 신체적 피로를 덜어주고,
방금 입력한 내용을 시각적으로 즉시 확인시켜 줄 수도 있고,
모바일의 좁은 자판이나 확인 칸이 없는 환경에서 입력의 정확성과 확신을 높여줄 수도 있어

시각적으로 확신을 주어 서비스를 보다 수월하게 사용할 수 있어 사용자들의 접근성을 높여줄 수도 있다는 생각을 하지 못했다. 그리고 버튼의 대체 텍스트까지 추가하여 접근성을 높일 수 있도록 개선해주었다.

비밀번호 찾기 링크 오류 수정

파일 : app/(auth)/login/page.tsx
이유 : 비밀번호 찾기가 / signup(회원가입)으로 연결되어 있어 명백한 버그였음. 해당 기능이 아직 미구현이므로 클릭 불가한 비활성 상태로 표시해 사용자 혼란을 방지함.

// ❌ 이전 코드 (회원가입 페이지로 잘못 연결)
<Link href="/signup" className="font-medium text-[14px] text-yg-primary md:text-base">
  비밀번호 찾기
</Link>

// ✅ 개선 코드 (비활성화 + 툴팁)
<span
  className="font-medium text-[14px] text-yg-gray cursor-not-allowed md:text-base"
  title="서비스 준비 중입니다."
>
  비밀번호 찾기
</span>

이 기능은 아직 구현하지 못하여 회원가입 링크로 적용한 상태였는데, 서비스 준비 중이라는 타이틀과 함께 클릭 불가한 비활성 상태로 표시해주어 사용자 입장을 생각해서 개선 해준게 좋았다.

카카오 로그인 실패 에러 처리

파일 : components/auth/KakaoLoginCallback.tsx
이유 : 카카오 로그인 실패 시 아무 처리 없이 로딩 스피너가 무한히 표시되었음. 실패하면 /login?error=kakao로 리다이렉트해 LoginForm에서 인라인 에러 메시지를 보여주도록 함.

// ❌ 이전 코드 (실패 처리 없음 → 무한 로딩)
if (response?.ok) {
  setUser({ ... });
  alert('로그인이 완료되었습니다!');
  router.replace('/');
}
// 실패 시: 아무것도 안 함

// ✅ 개선 코드
if (response?.ok) {
  setUser({ ... });
  router.replace('/');
} else {
  router.replace('/login?error=kakao');  // 실패 시 에러 메시지와 함께 리다이렉트
}

// ✅ LoginForm에서 에러 파라미터 감지
const kakaoError = searchParams.get('error') === 'kakao';

{kakaoError && (
  <p className="... text-yg-warning">카카오 로그인에 실패했습니다. 다시 시도해 주세요.</p>
)}

단순하게 카카오 서버에서만 로그인이 완료되면, 에러가 발생할 일이 없을 것 같았다.

하지만,

사용자가 카카오 동의 화면에서 취소하여 code값 없이 리다이렉트되거나,
네트워크 오류로 인해 code값이 만료되거나,
카카오 서버 장애로 인해 백엔드에서 API 호출 실패하거나,

등등 생각하지 못했던 부분이 있었는데 위와 같이 에러 처리를 해주어 개선해주었다.

카카오 콜백 — code 없을 때 무한 로딩 방지

파일 : components/auth/KakaoLoginCallback.tsx
이유 : URL에 code 파라미터가 없는 경우(직접 접근, OAuth 오류 등) if (code) 블록을 건너뛰어 로딩 화면이 영원히 유지되는 문제가 있었음.

// ❌ 이전 코드 (code 없으면 조용히 무한 로딩)
if (code) {
  const response = await loginKakao(code);
  // ...
}

// ✅ 개선 코드 (code 없으면 즉시 에러 페이지로)
if (!code) {
  router.replace('/login?error=kakao');
  return;
}
const response = await loginKakao(code);

위와 같은 문제로 카카오 서버에서 카카오 로그인만 성공하면 code는 무조건 넘어올 줄 알았다.

하지만 code가 없을 때도 있으므로 코드가 없으면 로그인 페이지로 이동하여 다시 로그인할 수 있도록 개선해주었다.

카카오 로그인 사용자 정보 누락 수정

파일 : components/auth/KakaoLoginCallback.tsx
이유 : 일반 로그인은 email, phone까지 저장하는데 카카오 로그인은 _id, name만 저장해 마이페이지에서 이메일/전화번호가 표시되지 않는 정보 불일치 문제가 있었음.

// ❌ 이전 코드 (name, _id만 저장)
setUser({
  _id: response.item._id,
  name: response.item.name,
});

// ✅ 개선 코드 (일반 로그인과 동일하게 email, phone 포함)
setUser({
  _id: response.item._id,
  name: response.item.name,
  email: response.item.email,
  phone: response.item.phone,
});

원래는 동일하게 사용자 정보를 저장하는게 맞다.

하지만 카카오 콘솔에서 앱을 생성할 때 테스트용으로 만든 앱이여서 이름만 데이터를 가져올 수 있어서 이름만 저장한 상태였다.

그래서 이 부분은 정확한 정보를 제공하지 않아 다시 정보를 제공한 후에 이름만 저장하도록 복구하였다.

로그아웃 — 백엔드 API 호출 추가

파일 : actions/auth.ts
이유 : 프론트에서 쿠키만 삭제하고 백엔드에 로그아웃을 알리지 않아 서버 측 토큰이 만료 전까지 유효한 상태로 남아있는 보안 문제가 있었음. 백엔드 로그아웃 API를 호출해 서버에서도 토큰을 무효화하도록 함. API 호출 실패 시에도 쿠키 삭제는 반드시 실행되도록 처리.

// ❌ 이전 코드 (쿠키만 삭제, 백엔드 미호출)
export async function logout() {
  const cookieStore = await cookies();
  cookieStore.set('accessToken', '', { path: '/', maxAge: 0 });
  cookieStore.set('refreshToken', '', { path: '/', maxAge: 0 });
}

// ✅ 개선 코드 (백엔드 토큰 무효화 후 쿠키 삭제)
export async function logout() {
  const cookieStore = await cookies();
  const accessToken = cookieStore.get('accessToken')?.value;

  if (accessToken) {
    try {
      await fetch(`${API_URL}/users/logout`, {
        method: 'GET',
        headers: {
          'Client-Id': CLIENT_ID,
          Authorization: `Bearer ${accessToken}`,
        },
      });
    } catch (err) {
      console.error('백엔드 로그아웃 실패:', err);
    }
  }

  cookieStore.set('accessToken', '', { path: '/', maxAge: 0 });
  cookieStore.set('refreshToken', '', { path: '/', maxAge: 0 });
}

프로젝트에서 사용하는 API 서버에는 로그아웃 엔드포인트가 따로 존재하지 않는다.

로그인하면 JWT 기반의 토큰을 발급해주는데, 이 방식은 서버가 토큰을 기억하지 않으므로 백엔드에서 로그아웃을 하지 않고 삭제만 해주어도 로그아웃된 상태가 된다.

단, 쿠키를 삭제하기 전에 토큰을 탈취했다면 만료 시간까지는 유효할 수 있다는 단점이 있다.

그래서 토큰을 쿠키에 httpOnly로 저장하여 자바스크립트로 접근하지 못하며 XSS로 탈취하지 못하게 설정을 하였다.

그래서 위의 개선코드는 해당 사항이 없어 원복하였다.

로그인 폼 클라이언트 유효성 검사

파일 : components/auth/LoginForm.tsx
이유 : 이메일/비밀번호가 비어있어도 서버 요청이 전송되어 불필요한 API 호출이 발생했음. HTML required 속성을 추가해 브라우저 레벨에서 빈 값 제출을 차단함.

// ❌ 이전 코드 (빈 값 제출 가능)
<AuthInput name="email" type="email" ... />
<AuthInput name="password" type="password" ... />

// ✅ 개선 코드 (브라우저 기본 유효성 검사)
<AuthInput name="email" type="email" ... required />
<AuthInput name="password" type="password" ... required />

비어있으면 로그인을 시도할 생각이 없을 것 같았지만 혹시나 하는 상황을 대비해서 API 호출을 예방하도록 개선한 부분이 좋았다.

회원가입 기능 개선 사항 정리

'use client' + metadata 충돌 버그 수정

파일 : app/(auth)/signup/page.tsx
이유 : Next.js App Router에서 metadata export는 Server Component에서만 동작합니다. 'use client'가 붙어 있으면 metadata가 완전히 무시되어 브라우저 탭 타이틀, SEO, OG 태그가 모두 적용되지 않습니다. SignupForm 자체가 이미 'use client'이므로 page.tsx에서는 제거해도 됩니다.

// ❌ 이전 코드 (metadata 무시됨)
'use client';
export const metadata: Metadata = { title: '회원가입', ... };  // 동작 안 함

// ✅ 개선 코드 ('use client' 제거 → Server Component)
export const metadata: Metadata = { title: '회원가입', ... };  // 정상 동작

이 문제는 잘못된 분석으로 자기가 'use client' 선언 문구를 제거했다고 착각한 부분이 있었다.

애초에 해당 문구는 존재하지 않았으며, 정상적으로 동작하는 Server Component였다..

회원가입 성공 시 alert() 제거

파일 : components/auth/SignupForm.tsx
이유 : router.replace('/login')으로 바로 이동하므로 alert가 불필요하고, 브라우저 기본 다이얼로그는 스타일링 불가 + UI 차단 문제가 있습니다.

// ❌ 이전 코드
if (userState?.ok) {
  alert('회원가입이 완료되었습니다!');
  router.replace('/login');
}

// ✅ 개선 코드
if (userState?.ok) {
  router.replace('/login');
}

로그인과 동일하게 회원가입 성공 시 router에 의해 로그인 페이지로 이동하므로 alert를 제거해주었다.

본인인증 버튼 disabled 로직 버그 수정

파일 : components/auth/SignupForm.tsx
이유 : isCertified === null && isCertified === false는 하나의 변수가 동시에 두 다른 값을 가질 수 없으므로 항상 false입니다. 결과적으로 인증 완료 후에도 버튼이 비활성화되지 않아 중복 인증 요청이 가능한 버그였습니다.

// ❌ 이전 코드 (항상 false → 항상 클릭 가능)
disabled={isCertified === null && isCertified === false}

// ✅ 개선 코드 (인증 완료 시 실제로 비활성화)
disabled={isCertified === true}

해당 기존 코드는 수정 과정에서 미쳐 발견하지 못했던 부분 같다.

버튼의 컬러나 문구는 isCertified === true일 때 동작하지 못하도록 UI를 구현하였는데, UI가 마치 안눌리는 것처럼 보이게 되어 클릭이 안되는줄 알았는데 다시 인증을 할 수 있는 상태였다.

미처 발견하지 못한 부분을 발견하여 비활성화 상태로 개선해주었다.

비밀번호 표시/숨김 토글 추가

파일 : components/auth/SignupForm.tsx
이유 : 비밀번호, 비밀번호 확인 두 필드 모두 적용. 이미 구현된 AuthInput의 suffix prop을 재사용했습니다.

// ❌ 이전 코드
<AuthInput name="password" type="password" ... />
<AuthInput name="passwordCheck" type="password" ... />

// ✅ 개선 코드
const [showPwd, setShowPwd] = useState(false);
const [showPwdCheck, setShowPwdCheck] = useState(false);

<AuthInput
  name="password"
  type={showPwd ? 'text' : 'password'}
  suffix={<button aria-label="비밀번호 표시/숨기기" ...> </button>}
/>
<AuthInput
  name="passwordCheck"
  type={showPwdCheck ? 'text' : 'password'}
  suffix={<button aria-label="비밀번호 확인 표시/숨기기" ...> </button>}
/>

로그인 폼에서 추가했던 것과 동일하게 UX 일관성을 지키기 위해 비밀번호와 비밀번호 확인 필드까지 적용해주었다.

본인인증 catch 블록 사용자 에러 메시지 추가

파일 : components/auth/SignupForm.tsx
이유 : 본인인증 중 예외(네트워크 오류, PortOne SDK 오류 등)가 발생하면 console.error만 호출하고 사용자에게 아무 피드백이 없었습니다. 사용자 입장에서는 버튼을 눌렀는데 아무 반응이 없는 것처럼 보입니다.

// ❌ 이전 코드 (사용자에게 피드백 없음)
} catch (err) {
  console.error('본인인증 오류:', err);
}

// ✅ 개선 코드 (인라인 에러 메시지 표시)
} catch (err) {
  console.error('본인인증 오류:', err);
  setCertifyMsg('본인인증 중 오류가 발생했습니다. 다시 시도해 주세요.');
}

try 블록에서 SDK의 응답에 따른 에러 처리, 우리가 사용하는 서버에서 검증 실패에 대한 에러 처리만 진행하였다.

하지만 try 내부 처리만으로는 네트워크 단절, SDK 오류, JSON 파싱 실패 같은 예외 상황에서 catch가 아무 메시지도 안 보여주어 사용자는 아무 반응 없는 화면을 보게 되었다.

catch의 setCertifyMsg 추가하여 개선해주었다.

PortOne 하드코딩 값 환경변수로 분리

파일 : components/auth/SignupForm.tsx, .env
이유 : storeId, channelKey가 소스코드에 직접 노출되어 있어 GitHub 등에 올라갈 경우 외부에 공개됩니다. 환경변수로 분리하면 값 변경 시 코드 수정 없이 .env만 바꿔도 되고, 환경별(개발/프로덕션) 설정도 용이합니다.

// ❌ 이전 코드 (값 하드코딩)
await PortOne.requestIdentityVerification({
  storeId: 'store-d1ae51ff-3845-45e1-8c36-533945dd9929',
  channelKey: 'channel-key-10ef6a4b-a90d-4bec-88cd-8591a7903ff4',
});

// ✅ 개선 코드 (환경변수 참조)
await PortOne.requestIdentityVerification({
  storeId: process.env.NEXT_PUBLIC_PORTONE_STORE_ID!,
  channelKey: process.env.NEXT_PUBLIC_PORTONE_CHANNEL_KEY!,
});

# .env에 추가
NEXT_PUBLIC_PORTONE_STORE_ID=store-d1ae51ff-3845-45e1-8c36-533945dd9929
NEXT_PUBLIC_PORTONE_CHANNEL_KEY=channel-key-10ef6a4b-a90d-4bec-88cd-8591a7903ff4

이 부분은 해당 페이지에서만 storeId, channelKey의 값들을 고정으로 사용하고 환경별로 달라질 일이 없을 것 같아서 하드코딩으로 작업해두었다.

하지만 .env 파일에서 관리하면 값이 바뀔 때 코드를 수정하지 않고 .env만 수정하면 되므로 재배포 범위를 줄일 수 있고, 지금은 테스트용이라 환경별 차이가 없지만 테스트용 채널키와 운영용 채널키를 분리해야 하는 상황이 생길 수도 있어 .env 파일에서 관리하면 좋다.

각 input 요소마다 여러 개의 상태 변수 사용

각 input 요소마다 여러 개의 상태 변수를 사용하고 있어 코드가 길어지는 문제를 고민하였다.

이 부분을 리팩토링 하면 코드의 가독성은 개선되지만 성능에는 거의 영향이 없다고 한다.

하지만, React 18부터 이벤트 핸들러 내의 여러 setState 호출은 자동으로 하나의 리렌더로 묶인다고 한다.

// 아래 3개의 setState가 실행돼도 리렌더는 1번
setNameIsValid(true);
setNameError('');
setNameTouched(true);

진짜 성능 문제는 controlled input 자체에 있다.

타이핑할 때마다 컴포넌트 전체가 리렌더되는 것이 실제 성능 이슈다. 이는 상태 변수 개수와 무관하며, useState를 몇 개로 합쳐도 해결되지 않는다.

실질적 성능 개선 방법은 react-hook-form을 사용하는 것이다.

react-hook-form은 ref 기반의 비제어 입력(uncontrolled input)을 사용해 타이핑 시 리렌더를 최소화한다. 유효성 검사 상태가 바뀔 때만 리렌더가 발생한다.

단, 현재 SignupForm의 커스텀 검증 로직(이메일 중복 확인, 본인인증 연동 등)을 전부 마이그레이션해야 하므로 리팩토링 비용이 크다. SignupForm 규모에서 사용자가 체감할 성능 저하도 없으므로 지금 당장 도입할 필요는 없다.

그래서 다음 프로젝트때는 react-hook-form을 이용해보려고 한다.

느낀점

Claude Code CLI를 통해 리팩토링을 진행해 보았는데, 확실히 코드의 품질이 올라가는 걸 느꼈다.

다만 사용할 때 원하는 목표가 있을 때 정확한 정보를 제공해야 하며, AI가 짜준 코드를 그대로 쓴느게 아니라 직접 읽어보고 프로젝트에 적합한지 확인하는 과정도 필요하다는걸 느꼈다.

하지만 내가 생각하지 못했던 부분을 좀 더 보안하여 코드의 품질을 높여주며 확인하는 과정에서 자연스럽게 배워가는 부분도 많았다.

AI를 무턱대고 사용하는건 지양하는게 좋지만, 잘 활용만 한다면 개발 실력을 향상시키는데도 도움이 되는 것 같다.

[Next.js] 회원가입 시 PortOne API로 휴대폰 본인인증 구현하기

seungjunn100 — Wed, 4 Mar 2026 23:48:14 +0900

PortOne 본인인증 연동

PortOne API를 활용하여 회원가입 시 휴대폰 본인인증 기능을 구현하기 위해 위의 공식 문서를 참고하였다.

PortOne SDK 설치

우선 PortOne 본인인증을 사용하려면 브라우저 SDK를 먼저 설치해야 한다.

npm i @portone/browser-sdk

설치 후에는 컴포넌트에서 import해서 사용할 수 있다.

import * as PortOne from '@portone/browser-sdk/v2';

PortOne 관리자 콘솔 연동

PortOne 관리자 콘솔에서 회원가입을 진행한 후에 테스트 채널을 생성하면 Store ID와 Channel Key를 발급받을 수 있다.

이후 서버에서 PortOne REST API를 사용하기 위해 API Secret Key를 발급받으면 사전 준비가 완료된다.

Store ID는 어떤 서비스에서 요청한 인증인지 구분하기 위한 식별자이며, Channel Key는 어떤 인증 채널(KG이니시스, NICE 등)을 사용할지 구분하기 위한 키로서 노출되어도 상관없다.

API Secret Key는 민감 정보라 브라우저에 절대 노출되면 안 되고 서버에서만 사용해야 한다.

브라우저 구현 (본인인증 요청)

// components/auth/SignupForm.tsx
const handleCertify = async () => {
  try {
    const res: CertifyActionState = await PortOne.requestIdentityVerification({
      storeId: 'store-...',
      channelKey: 'channel-key-...',
      identityVerificationId: `identity-verification-${crypto.randomUUID()}`,
    });

    // 1) 응답 자체가 없는 경우
    if (!res) {
      setCertifyMsg('응답 없음');
      return;
    }

    // 2) code가 존재하면 인증 과정 중 오류
    if (res?.code) {
      setCertifyMsg(`본인인증 실패: ${res.message}`);
      return;
    }

    // 3) 성공하면 identityVerificationId를 서버로 전달
    const certifyRes = await fetch('/api/certify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ identityVerificationId: res.identityVerificationId }),
    });

    const certifyResData = await certifyRes.json();

    if (!certifyResData.success) {
      setCertifyMsg(certifyResData.message);
      return;
    }

    // 4) 최종 성공 UI 처리
    setIsCertified(true);
    setPhoneNumber(certifyResData.phoneNumber);
    setCertifyMsg('본인인증 완료되었습니다.');
  } catch (err) {
    console.error('본인인증 오류:', err);
  }
};

PortOne.requestIdentityVerification()로 본인인증 창을 띄운다.
- 이 때, identityVerificationId는 인증 건을 구분하는 ID라서 요청/조회에 계속 쓰인다.
  - crypto.randomUUID()는 브라우저 Web Crypto API가 제공하는 함수로서 충돌 가능성이 거의 없는 고유 ID를 생성한다.
응답에 code가 포함되어 있으면 인증 에러가 발생하여 메세지와 함께 에러 처리를 해주었다.
성공하면 identityVerificationId를 서버로 보내 서버에서 완료 처리를 한다.
서버에서 성공 시 응답받은 데이터로 UI를 처리한다.

브라우저에서는 본인인증 절차를 수행하고 identityVerificationId를 전달받는다.

클라이언트는 사용자가 조작할 수 있는 환경이기 때문에 인증 결과 검증은 서버에서 PortOne REST API를 호출하여 최종 확인한다.

서버 구현 (REST API로 인증 검증/정보 획득)

// app/api/certify/route.ts
import { NextRequest, NextResponse } from 'next/server';

const PORTONE_API_SECRET = process.env.PORTONE_API_SECRET;

export async function POST(request: NextRequest) {
  try {
    const { identityVerificationId } = await request.json();

    const res = await fetch(`https://api.portone.io/identity-verifications/${identityVerificationId}`, {
      headers: {
        Authorization: `PortOne ${PORTONE_API_SECRET}`,
      },
    });

    if (!res.ok) throw new Error('본인인증 정보 조회 실패');

    const resData = await res.json();

    if (resData.status === 'VERIFIED') {
      return NextResponse.json({
        success: true,
        phoneNumber: resData.verifiedCustomer.phoneNumber,
      });
    }

    return NextResponse.json({
      success: false,
      message: '본인인증이 완료되지 않았습니다. 다시 시도해주세요.',
    });
  } catch (err) {
    console.error(err);
    return NextResponse.json({
      success: false,
      message: '본인인증 검증 중 오류가 발생했습니다. 다시 시도해주세요.',
    });
  }
}

브라우저에서 받은 identityVerificationId를 포함하여 /identity-verifications/{identityVerificationId} 엔드포인트에 헤더의 인증 키에 API Secret Key를 포함하여 요청을 보낸다.

응답 데이터의 status 값은 "READY" | "VERIFIED" | "FAILED"중 하나이며, 이 중 "VERIFIED" 상태일 경우 본인인증이 정상적으로 완료된 상태로서 사용자의 데이터를 받아서 브라우저로 전달하여 UI로 보여줄 수 있게 된다.

`Route Handler`에서 처리한 이유

API Secret Key는 API 서버에 요청을 보낼 때 헤더에 인증 키로 포함하여 보내는 민감 정보이기 때문에 브라우저에 절대 노출하면 안 되며 인증 결과 조회는 반드시 서버에서 처리하는게 좋다.

`verifiedCustomer`에서 얻을 수 있는 정보

verifiedCustomer 객체에는 본인인증을 통해 확인된 사용자 정보가 포함되어 있으며, 서비스 로직에서 필요에 따라 활용할 수 있다.

ci : 연계 정보(Connecting Information)
di : 중복 가입 확인 정보(Duplication Information)
name : 이름
gender : 성별
birthDate : 생년월일 (YYYY-MM-DD)
operator : 통신사
phoneNumber : 숫자로만 구성된 전화번호 (UI에서 포맷팅이 필요)
isForeigner : 외국인 여부

[Next.js] 회원가입 기능 구현

seungjunn100 — Wed, 4 Mar 2026 23:36:22 +0900

프로젝트의 회원가입 기능을 구현하며 왜 그런지 이해하며 전반적인 흐름을 정리해 보았다.

회원가입 서버 / 클라이언트 컴포넌트 분리

회원가입 페이지도 로그인 페이지와 같이 페이지의 레이아웃과 metadata는 서버에서 렌더링하고, 입력 상태 관리(useState), 폼 제출(useActionState), 페이지 이동(useRouter)이 필요한 폼 영역만 Client Component로 분리하여 작업하였다.

회원가입 인증 흐름 설계

클라이언트 입력 검증 UX 설계

브라우저에서 사용자가 인풋에 데이터를 입력 시 정해놓은 형식에 맞게 작성할 수 있도록 UI를 설계하였다.

export default function SignupForm() {
  const [name, setName] = useState('');
  const [nameError, setNameError] = useState('');
  const [nameTouched, setNameTouched] = useState(false);
  const [nameIsValid, setNameIsValid] = useState<boolean | null>(null);

  ...

  // 이름 입력시 형식 검증 (onChange)
  const handleNameChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    const newName = event.target.value;
    setName(newName);

    if (nameTouched) {
      if (newName.trim() === '' || newName.length <= 1) {
        setNameIsValid(false);
        setNameError('이름은 2글자 이상 입력해주세요.');
      } else if (newName.length > 1) {
        setNameIsValid(true);
        setNameError('');
      }
    }
  };

  // 이름 입력시 형식 검증 (onBlur)
  const handleNameBlur = () => {
    setNameTouched(true);

    if (name.trim() === '' || name.length <= 1) {
      setNameIsValid(false);
      setNameError('이름은 2글자 이상 입력해주세요.');
    } else if (name.length > 1) {
      setNameIsValid(true);
    }
  };

  ...

  return (
    <AuthInput label="이름" name="name" type="text" placeholder="이름을 입력하세요." value={name} onChange={handleNameChange} onBlur={handleNameBlur} message={nameError} isValid={nameIsValid} />

    ...
  );
}

하나의 인풋에 총 4개의 상태를 관리하도록 하였다.

데이터를 입력하기 위해 인풋을 클릭했을 때, nameTouched의 상태를 true로 설정
- 처음 입력 시에는 onBlure로 포커스가 이동했을 때 형식 검증
- 다음 입력 시에는 nameTouched의 상태가 true라면 onChange로 실시간으로 형식 검증
이름이 입력될 때 인풋에 입력되고 있는 값을 새로운 이름으로 지정하기 위해 setName(newName)로 이름 상태를 설정
형식 검증 시 일치하지 않는다면, nameIsValid의 상태를 false로 설정
nameIsValid의 상태가 false일 때, 에러 메세지를 띄우기 위해 setNameError('이름은 2글자 이상 입력해주세요.')로 메세지 상태를 설정

이렇게 4개의 상태를 관리하여 처음 입력시에 onBlure로 포커스가 이동했을 때 검증을 하고 형식이 일치한다면 바로 다음으로 넘어가고, 일치하지 않는다면 다음 입력 시에는 onChange로 실시간으로 검증을 하여 사용자가 입력을 빠르고 정확하게 완료할 수 있도록 하였다.

서버 액션 구현

회원가입은 단순 조회가 아니라 계정을 생성하여 서버 데이터의 상태를 변경하는 요청이므로, 서버에서 처리하는 편이 구조적으로 안정적이다.

또한 서버 액션을 사용하면 브라우저가 직접 외부 API를 호출하는 구조를 피할 수 있어 운영/보안 측면에서 유리하다.

'use server';

import { ErrorRes, LoginActionState, UserActionState } from '@/types/auth';
import { cookies } from 'next/headers';

const API_URL = process.env.NEXT_PUBLIC_API_URL;
const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID || '';

export async function signup(state: UserActionState, formData: FormData): Promise<UserActionState> {
  ...

이메일 정규 표현식 및 중복 확인

정규 표현식

// 영어/숫자/._%+- 로 이루어진 문자 1개 이상
// + @
// + 영어/숫자/.- 로 이루어진 문자 1개 이상
// + .
// + 영어 2글자 이상
const emailExp = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

// 이메일 형식 검증
if (!emailExp.test(email)) {
  setEmailIsValid(false);
  setEmailError('올바른 이메일 형식이 아닙니다.');
} else {
  setEmailIsValid(true);
}

이메일은 해당 정규 표현식을 통과해야만 중복 확인 버튼이 활성화 되어 중복 확인을 할 수 있다.

중복 확인

// components/auth/SignupForm.tsx

...

// 이메일 중복확인
const handleEmailCheck = async () => {
  const res = await emailCheck(email);

  if (!res.ok) {
    setEmailChecked(false);
    setEmailCheckedMsg(res.message);
  } else {
    setEmailChecked(true);
    setEmailCheckedMsg('사용 가능한 이메일입니다.');
  }
};

...

// lib/api/auth.ts
import { EmailCheckRes } from '@/types/auth';

const API_URL = process.env.NEXT_PUBLIC_API_URL || '';
const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID || '';

export async function emailCheck(email: string): Promise<EmailCheckRes> {
  try {
    const res = await fetch(`${API_URL}/users/email?email=${encodeURIComponent(email)}`, {
      headers: {
        'Client-Id': CLIENT_ID,
      },
    });

    const resJson = await res.json();

    return resJson;
  } catch (err) {
    console.error(err);
    return { ok: 0, message: '네트워크 오류로 이메일 중복 확인에 실패했습니다.' };
  }
}

이메일은 URL 쿼리로 전달되므로, 특수문자를 안전하게 인코딩하기 위해 encodeURIComponent를 적용했다.

응답 성공 시 emailChecked 상태를 true로 만들어, 중복 확인이 완료된 이메일이라는 상태를 보장했다.

회원가입 요청

클라이언트에서 폼 입력 데이터가 모두 true가 되었을 때 회원가입 요청 버튼이 활성화될 수 있도록 설정하였다.

// 폼 입력 데이터 모두 true 시
const isFormValid = nameIsValid && emailChecked && pwdCheckIsValid && pwdIsValid && isCertified;

...

<BaseButton type="submit" size="xl" variant={!isFormValid || isPending ? 'disabled' : 'primary'} disabled={!isFormValid || isPending} className="mt-4 md:mt-6">
  {isPending ? <BeatLoader size={10} color="#fff" /> : '회원가입'}
</BaseButton>

로그인 요청에서 body를 구성하는 방법과 회원가입 요청에서 body를 구성하는 방법이 다르다.

// 로그인 요청
const body = Object.fromEntries(formdata.entries());

// 회원가입 요청
const body = {
  type: formData.get('type') || 'user',
  name: formData.get('name'),
  email: formData.get('email'),
  password: formData.get('password'),
  phone: formData.get('phone'),
};

이렇게 다른 이유는 회원가입에서 비밀번호 확인같은 필드는 클라이언트에서만 확인하기 위해 설정했던 부분이고, 서버에서 필요로하는 필드만 선택해서 보내기 위해 명시적으로 값을 꺼내는 방식을 사용하였다.

const body = {
  type: formData.get('type') || 'user',
  name: formData.get('name'),
  email: formData.get('email'),
  password: formData.get('password'),
  phone: formData.get('phone'),
};

...

res = await fetch(`${API_URL}/users`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Client-Id': CLIENT_ID,
  },
  body: JSON.stringify(body),
});

로그인 요청과 마찬가지로 데이터를 서버에서 읽을 수 있게 객체로 만들어서 JSON 형태로 바꾸어 전달해주어야 한다.

  useEffect(() => {
    if (userState?.ok) {
      alert(`회원가입이 완료되었습니다!`);
      router.replace('/login');
    }
  }, [userState, router]);

응답에 성공하여 회원가입이 완료되면 로그인 페이지로 이동하도록 하였다.

[Next.js] 카카오 소셜 로그인 기능 구현

seungjunn100 — Wed, 4 Mar 2026 00:07:56 +0900

Kakao Developers 문서

카카오 로그인을 사용하기 위해 위의 공식 문서를 참고하였다.

우선 카카오 로그인 과정에 대해서 쉽게 이해할 수 있는 이미지를 확인할 수 있었다.

간단하게 설명하자면,

사용자가 카카오 로그인 버튼을 누르면, 카카오 인증 서버로 이동한다.
로그인 및 동의를 완료하면, 카카오는 인가 코드를 포함한 Redirect URI로 다시 돌려보낸다.
서비스 서버는 이 인가 코드로 카카오에 토큰 발급을 요청한다.
발급받은 토큰으로 사용자 정보를 조회한 뒤, 기존 회원 여부를 확인한다.
회원 가입 또는 로그인 처리를 완료하고, 서비스 세션을 생성한다.

즉, 클라이언트는 인가 코드만 받고 실제 로그인 완료 처리는 서버에서 진행된다.

카카오 개발자 콘솔에서 앱 설정

우선 카카오 로그인을 사용하기 위해서는 카카오 개발자 콘솔에서 앱 설정부터 진행해야 한다.

이렇게 앱의 기본 정보들을 입력하고 앱을 생성해야 아래와 같이 기본 정보들이 사용자에게 노출되어 제공된다.

그리고 카카오 로그인 시 사이트에서 제공받을 수 있는 정보들을 아래와 같이 동의 항목을 통해 설정할 수 있다.

그러면 카카오 로그인 동의 화면에서 동의 항목을 체크하여 사이트에서 정보들을 활용할 수 있게 된다.

권한은 앱의 용도에 따라서 권한이 달라진다.

그리고 운영중인 사이트의 도메인 주소를 등록하고 카카오 로그인 시 리다이렉트될 URI까지 설정 해준다.

마지막으로 프로젝트에서 자바스크립트 키와 리다이렉트 URI를 .env 파일에 선언해주면 설정은 마무리 된다.

참고로, 프론트엔드에서는 JavaScript 키를 사용해 SDK를 초기화하고, 인가 코드로 토큰을 요청하는 작업은 서버에서 REST API 키를 사용하여 수행해야 한다.

REST API 키는 서버 전용 키이므로 브라우저에 노출되면 안 된다.

기능 구현 흐름

Kakao Developers 문서 - JavaScript SDK에서 제공하는 기능

KakaoLogin 버튼

export default function KakaoLogin() {
  function loginWithKakao() {
    window.Kakao.Auth.authorize({
      redirectUri: process.env.NEXT_PUBLIC_KAKAO_REDIRECT_URI!, // 앱에 등록된 카카오 로그인에서 사용할 Redirect URI 설정
    });
  }

  return (
    <>
      <Script
        src="https://t1.kakaocdn.net/kakao_js_sdk/2.7.7/kakao.min.js"
        strategy="afterInteractive"
        onLoad={() => {
          if (!window.Kakao.isInitialized()) {
            window.Kakao.init(process.env.NEXT_PUBLIC_KAKAO_JS_KEY!); // 앱에 등록된 카카오 로그인에서 사용할 JavaScript 키 설정
          }
        }}
      />

      <button type="button" onClick={loginWithKakao} className="flex justify-center items-center gap-2 w-full h-11.5 mt-6 font-medium text-[16px] shadow-[0_0_15px_rgba(0,0,0,0.2)] rounded-full cursor-pointer md:h-13 md:text-[18px] text-[#3C1E1E] bg-[#FFEB00]">
        <Image width={25} height={25} src="/images/kakao_symbol.png" alt="카카오 로고" />
        카카오 로그인
      </button>
    </>
  );
}

해당 컴포넌트가 렌더링 되면서 카카오가 제공하는 JavaScript SDK 파일을 브라우저에 로드하게 된다.

이 <Script>가 로드되면 브라우저 전역 객체에 Kakao 네임스페이스가 추가되어 window.Kakao를 통해 SDK 기능을 사용할 수 있게 된다.

하지만 Window 타입에는 Kakao가 없어서 아래와 같은 에러가 발생한다.

Property 'Kakao' does not exist on type 'Window & typeof globalThis'

이 문제를 해결하기 위해 Window에 Kakao가 있다는걸 인식 시켜주도록 타입을 설정하면 해결할 수 있다.

// 전역 스코프에 타입을 확장
declare global {
  // 기존 Window 인터페이스에 Kakao 속성 추가
  interface Window {
    // 실제로 쓰는 함수들만 최소한으로 타입 정의
    Kakao: {
      init: (apiKey: string) => void;
      isInitialized: () => boolean;
      Auth: {
        authorize: (options: { redirectUri: string }) => void;
      };
    };
  }
}

export {};

그리고 <Script>가 로드될 때 자바스크립트 키로 초기화되지 않았다면, 자바스크립트 키로 초기화된 상태로 로드될 수 있도록 설정해주어야 해당 앱으로 요청을 할 수 있게 된다.

그 다음 카카오 로그인 버튼을 클릭하게되면 loginWithKakao 함수가 실행되면서 카카오 인증 서버로 이동해서 로그인 + 동의 받고, 성공하면 설정한 Redirect URI로 인가 코드가 포함된 상태로 리다이렉트된다.

http://localhost:3000/login/kakao?code=VAp6kZ7cRXr6wJ9r2U0xkwiKoRa8v-exXJlUHDkbf-7nhj9uMjTBvwAAAAQKFxAvAAABnLOsBnQq17LwdM8QAg

Kakao Login 페이지

export default function KakaoLoginCallback() {
  const setUser = useUserStore((state) => state.setUser);
  const searchParams = useSearchParams();
  const code = searchParams.get('code');
  const router = useRouter();

  useEffect(() => {
    async function login() {
      if (code) {
        const response = await loginKakao(code);

        if (response?.ok) {
          setUser({
            _id: response.item._id,
            name: response.item.name,
          });
          alert(`안녕하세요, ${response.item.name}님!\n로그인이 완료되었습니다!`);
          router.replace('/');
        }
      }
    }
    login();
  }, [code, setUser, router]);

  return (
    <>
      <div className="flex items-center justify-center h-screen">
        <div className="flex flex-col justify-center items-center w-xs h-50 px-4 bg-[#FFEB00] rounded-2xl">
          <Image width={40} height={40} src="/images/kakao_symbol.png" alt="카카오 로고" className="mb-4" />
          <p className="text-[#3C1E1E] font-medium text-[18px] mb-3">카카오 로그인 중</p>
          <BeatLoader size={12} color="#3C1E1E" />
        </div>
      </div>
    </>
  );
}

그러면 /login/kakao 페이지에서는 Redirect URI로 받은 인가 코드를 추출하고 컴포넌트가 마운트되면, loginKakao 함수에 인가 코드를 매개변수로 담아 API 서버에 요청하게 된다.

응답에 성공하면, API 서버가 카카오에 토큰 발급 요청을 수행하고 accessToken과 refreshToken을 발급받는다.

이후 API 서버에서는 해당 토큰으로 사용자 정보 조회 API를 호출하여, 앱 설정에서 지정한 동의 항목에 해당하는 사용자 정보를 전달받아 세팅할 수 있다.

loginKakao 서버 액션

export async function loginKakao(code: string): Promise<LoginActionState> {
  let res: Response;
  let data: LoginActionState;

  const body = {
    code,
    redirect_uri: process.env.NEXT_PUBLIC_KAKAO_REDIRECT_URI,
  };

  try {
    res = await fetch(`${API_URL}/users/login/kakao`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Client-Id': CLIENT_ID,
      },
      body: JSON.stringify(body),
    });

    data = await res.json();

  if (data?.ok) {
    // accessToken/refreshToken을 httpOnly cookie로 저장
    ...
  }

  ...
}

클라이언트에서 토큰을 직접 요청할 경우 REST API 키가 노출될 수 있으므로, 인가 코드까지만 클라이언트에서 받고 토큰 교환은 서버에서 수행하도록 설계하였다.

인가 코드를 받은 loginKakao 함수는 인가 코드와 Redirect URI를 포함하여 API 요청을 보내 응답에 성공하여 토큰을 받으면 쿠키로 저장하도록 카카오 로그인 기능을 구현하였다.

[Next.js] 로그인 상태에 따른 헤더 메뉴 깜빡임 문제 해결 (feat. Hydration)

seungjunn100 — Tue, 3 Mar 2026 23:17:11 +0900

프로젝트의 헤더에 네비게이션을 로그인 상태에 따라 다르게 설정하였다.

로그인 되지 않은 상태라면 : "로그인 / 회원가입"

로그인 된 상태라면 : "마이페이지 / 구독하기"

하지만 로그인이 된 상태일 때, 새로고침을 하면 아주 짧은 순간 "로그인 / 회원가입" UI가 먼저 렌더링 되고 잠시 후에 "마이페이지 / 구독하기" UI로 바뀌는 현상이 발생했다.

이 현상은 Hydration 과정에서 발생한 문제이다.

Hydration이란

서버에서 미리 생성된 HTML에, 브라우저에서 내려받은 JS가 실행되며 이벤트 리스너와 상태를 연결해 인터랙션 가능한 리액트 애플리케이션으로 완성하는 과정이다.

동작 과정

빌드 시

작성한 JSX(TSX) 코드는 SWC에 의해 JS로 변환된다.

이후 서버에서 실행될 코드와 브라우저에서 실행될 코드가 각각 번들링된다.

서버

리액트 컴포넌트가 실행되어 HTML을 생성하고 완성된 HTML을 브라우저로 전송한다.

브라우저

브라우저가 서버로 부터 받은 HTML을 파싱하면서 사용자가 화면을 볼 수 있게 된다.
HTML 파싱과 병렬로 JS 번들 다운로드가 진행된다.
다운로드된 JS 번들이 실행된다.
리액트 런타임이 실행되고, 컴포넌트 함수들이 실행되어 가상 DOM 트리를 생성한다.
생성된 가상 DOM을 기존 서버 DOM과 매칭하여 새로 그리지 않고 재사용하며, 각 노드에 리액트 내부 구조를 연결한다.
각 DOM 요소에 이벤트 리스너를 등록하여 완전한 리액트 앱이 동작하게 된다.

이 과정에서 클라이언트 상태(persist)가 아직 준비되지 않은 경우, 서버에서 렌더링된 HTML과 클라이언트 상태가 일시적으로 불일치하여 UI 깜빡임이 발생할 수 있다.

새로고침 시 UI가 깜빡인 이유

헤더 컴포넌트에서 user의 로그인 상태 여부에 따라 메뉴를 다르게 설정하기 위해 전역 상태 관리인 Zustand의 스토어를 생성해 사용하였다.

// 유저 스토어
// 사용자 정보 스토어의 초기값과 액션(함수) 정의
const UserStore: StateCreator<UserStoreState> = (set) => ({
  user: null,
  setUser: (user: User | null) => set({ user }),
  resetUser: () => set({ user: null }),
});

// 사용자 정보를 세션스토리지에 저장
const useUserStore = create<UserStoreState>()(
  persist(UserStore, {
    name: 'user',
    storage: createJSONStorage(() => sessionStorage),
  })
);

// 헤더 컴포넌트
export default function HeaderInner() {
  const user = useUserStore((state) => state.user);
  ...

  return (
    <ul>
      <li><Link href="/survey">AI 추천받기</Link></li>
      <li><Link href="/products">영양제 정보</Link></li>
      {user ? (
        <>
          <li><Link href="/mypage">마이페이지</Link></li>
          <li><Link href="/subscription">구독하기</Link></li>
        </>
      ) : (
        <>
          <li><Link href="/login">로그인</Link></li>
          <li><Link href="/signup">회원가입</Link></li>
        </>
      )}
    </ul>
  );
  ...

하지만 여기서 문제가 발생했다.

새로고침 직후에는 persist가 스토리지에 저장된 user 값을 아직 가져오기 전이라, 초기값(null)으로 먼저 렌더링된다. 이후 스토리지에서 저장된 값이 적용되면서 상태가 변경되고, 그로 인해 UI가 한 번 더 렌더링되어 깜빡임이 발생했다.

상태 적용 완료 이후에만 렌더링하도록 개선

이를 해결하기 위해, 스토리지에 저장된 user 값이 아직 적용되기 전에는 헤더 메뉴를 렌더링하지 않고, 저장된 값이 적용된 이후에만 렌더링하도록 hydrated 상태를 추가하였다.

const UserStore = (set) => ({
  user: null,
  hydrated: false,
  setUser: (user) => set({ user }),
  resetUser: () => set({ user: null }),
  setHydrated: () => set({ hydrated: true }),
});

const useUserStore = create<UserStoreState>()(
  persist(UserStore, {
    name: 'user',
    storage: createJSONStorage(() => sessionStorage),
    onRehydrateStorage: () => (state) => {
      state?.setHydrated();
    },
  })
);

persist는 페이지가 새로고침되면 다음 순서로 동작한다.

컴포넌트가 먼저 마운트되고 초기 상태(user: null)로 렌더링된다.
이후 sessionStorage에 저장된 값을 읽어온다.
읽어온 값을 스토어에 적용한다.
적용이 완료되면 onRehydrateStorage의 내부 함수가 실행된다.

이 시점에 setHydrated()를 호출하여 hydrated를 true로 변경한다.

// 헤더 컴포넌트
export default function HeaderInner() {
  const user = useUserStore((state) => state.user);
  const hydrated = useUserStore((state) => state.hydrated);
  ...

  return (
    <>
      {hydrated ? (
        <ul>
          <li><Link href="/survey">AI 추천받기</Link></li>
          <li><Link href="/products">영양제 정보</Link></li>
          {user ? (
            <>
              <li><Link href="/mypage">마이페이지</Link></li>
              <li><Link href="/subscription">구독하기</Link></li>
            </>
          ) : (
            <>
              <li><Link href="/login">로그인</Link></li>
              <li><Link href="/signup">회원가입</Link></li>
            </>
          )}
        </ul>
      ) : null}
    </>
  );
  ...

그래서 헤더의 메뉴도 onRehydrateStorage가 실행되어 hydrated를 true로 변경되기 전까지 메뉴를 보여주지 않고, true로 변경되면 전체 메뉴를 보여주는 식으로 수정하였다.

[Next.js] 로그인 기능 구현

seungjunn100 — Tue, 3 Mar 2026 23:12:37 +0900

프로젝트의 로그인 기능을 구현하며 왜 그런지 이해하며 전반적인 흐름을 정리해 보았다.

로그인 서버 / 클라이언트 컴포넌트 분리

App Router 환경에서 기본은 Server Component이다.

로그인 페이지의 레이아웃과 metadata는 서버에서 렌더링하고, 입력 상태 관리(useState), 폼 제출(useActionState), 페이지 이동(useRouter)이 필요한 로그인 폼 영역만 Client Component로 분리하였다.

그리고 Server Component는 Client Component를 import해서 사용할 수 있다. 하지만 반대의 상황은 허용되지 않는다.

로그인 인증 흐름 설계

서버 액션 구현

로그인 기능은 단순히 API 요청을 보내는 문제가 아니라, 인증 정보(토큰)를 안전하게 저장하는 과정까지 포함한다.

Client Component에서 직접 로그인 요청을 처리하면 토큰 저장/관리 로직이 브라우저로 내려가게 되어 공격 표면이 커질 수 있다. 특히 cookies() 같은 서버 전용 API로 httpOnly 쿠키를 설정할 수 없기 때문에, 인증 처리는 서버에서 수행하는 구조가 더 안전하다.

그래서 App Router에서는 'use server'를 선언해 함수가 서버에서만 실행되도록 만들 수 있다(Server Action). 이를 통해 로그인 처리와 httpOnly 쿠키 설정을 서버에서 안전하게 수행할 수 있다.

'use server';

import { ErrorRes, LoginActionState, UserActionState } from '@/types/auth';
import { cookies } from 'next/headers';

const API_URL = process.env.NEXT_PUBLIC_API_URL;
const CLIENT_ID = process.env.NEXT_PUBLIC_CLIENT_ID || '';

export async function login(state: LoginActionState, formdata: FormData): Promise<LoginActionState> {
  ...

이렇게 구현하면 폼 제출은 클라이언트에서 발생하지만, 실제 로그인 처리 및 쿠키 저장은 서버에서 실행하여 보안이 좋아진다.

로그인 요청

폼에서 제출된 데이터는 FormData 형태로 서버 액션에 전달된다.

그리고 데이터를 서버에서 읽을 수 있게 객체로 만들어서 JSON 형태로 바꾸어 전달해주어야 한다.

const body = Object.fromEntries(formdata.entries());

...

res = await fetch(`${API_URL}/users/login`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Client-Id': CLIENT_ID,
  },
  body: JSON.stringify(body),
});

로그인 성공 시 서버는 accessToken과 refreshToken을 응답하며, 인증이 필요한 요청에 사용된다.

토큰 저장 방법

토큰은 localStorage, sessionStorage, cookie에 저장하는 방법들이 있다.

하지만 localStorage와 sessionStorage에 저장하게되면, 브라우저에서 실행되는 자바스크립트는 토큰에 접근할 수 있게 되어 XSS 공격이 발생하면 탈취될 가능성이 생긴다.

cookieStore.set('accessToken', accessToken, {
  httpOnly: true, // 클라이언트 JS에서 접근 불가, XSS 공격으로부터 토큰 보호
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax', // CSRF 방어, 일반적인 링크 이동은 허용
  path: '/',
  maxAge: 60 * 30,
});

XSS (Cross-Site Scripting)

악성 스크립트를 웹 페이지에 삽입해 사용자의 브라우저에서 실행시키고, 토큰이나 민감 정보를 탈취하는 공격 방식

CSRF(Cross-Site Request Forgery)

사용자가 의도하지 않은 요청을 다른 사이트를 통해 강제로 보내게 만들어, 인증된 상태를 악용하는 공격 방식

그래서 인증 토큰은 스토리지 대신 서버가 설정하는 httpOnly 쿠키로 관리하는 것이 XSS 관점에서 더 안전하다.

로그인 이후, `user` 상태 관리

로그인 성공 시 토큰이 httpOnly 쿠키에 저장이 된다고 해서 리액트 컴포넌트가 자동으로 로그인 여부를 알 수 있는 것은 아니다.

예를 들어, 헤더 메뉴를 "로그인 / 회원가입" → "마이페이지 / 로그아웃"으로 변경하거나 로그인 여부에 따른 조건부 렌더링은 인증이 아니라 UI 상태의 문제이다.

그래서 전역 상태로 user를 관리하도록 설계했다.

로그인 상태가 여러 컴포넌트에서 사용되어 Prop drilling없이 어디서든 접근하여 사용하기 위해 전역 상태 관리가 필요했다.

Zustand는 하나의 store를 생성해서 사용하는 구조이며, 사용이 직관적이고 설정이 간단하여 선택하게 되었다.

`store` 설계

// 사용자 정보 스토어의 초기값과 액션(함수)을 정의
const UserStore: StateCreator<UserStoreState> = (set) => ({
  user: null,
  setUser: (user: User | null) => set({ user }),
  resetUser: () => set({ user: null }),
});

// 사용자 정보를 세션스토리지에 저장
const useUserStore = create<UserStoreState>()(
  persist(UserStore, {
    name: 'user',
    storage: createJSONStorage(() => sessionStorage),
  })
);

[Web] 웹접근성을 위한 WAI-ARIA

seungjunn100 — Mon, 23 Feb 2026 16:13:39 +0900

WAI-ARIA

WAI-ARIA(Web Accessibility Initiative - Accessible Rich Internet Applications)는 웹 콘텐츠의 접근성을 높이기 위해 W3C WAI에서 개발한 기술이다. 웹이 단순한 문서 연결을 넘어 복잡한 사용자 경험(UX)을 제공하는 리치 인터넷 애플리케이션(RIA) 시대로 발전하면서 등장했다.

초기 웹은 정적이었으나, JavaScript와 Ajax 같은 기술로 웹 페이지가 동적으로 변하고 다양한 UI 컴포넌트가 등장하면서 기존 HTML만으로는 그 의미를 보조 기술(스크린 리더 등)에 정확히 전달하기 어려워졌다. 예를 들어, <div>나 <span> 태그로 만든 컴포넌트의 기능과 상태를 보조 기술이 파악할 수 없는 문제가 발생했다.

WAI-ARIA는 이러한 문제를 해결하기 위해 역할(Role), 속성(Property), 상태(State) 정보를 마크업에 추가하여 웹의 동적인 콘텐츠와 복잡한 UI를 보조 기술이 인식하고 올바르게 전달할 수 있도록 돕는 역할을 한다.

유저 에이전트와 접근성 API 및 보조 기술 간의 관계

WAI-ARIA는 유저 에이전트(웹 브라우저)와 보조 기술 사이의 커뮤니케이션을 중재하는 핵심적인 역할을 수행한다.

DOM에 ARIA 속성 추가
- 개발자는 HTML 요소에 role, property, state와 같은 ARIA 속성을 추가한다.
유저 에이전트의 역할
- 웹 브라우저는 HTML 문서와 ARIA 속성을 해석하여 접근성 트리(Accessibility Tree)를 생성한다. 이 접근성 트리는 웹 콘텐츠의 구조, 역할, 상태에 대한 정보를 담고 있다.
접근성 API의 역할
- 웹 브라우저는 운영체제(OS)에서 제공하는 접근성 API를 통해 이 접근성 트리를 노출한다.
보조 기술의 역할
- 스크린 리더와 같은 보조 기술은 접근성 API를 통해 접근성 트리의 정보를 읽어 들인다. 이 정보를 바탕으로 사용자에게 웹 콘텐츠를 전달하며 웹 페이지를 탐색하고 상호작용할 수 있도록 돕는다.

WAI-ARIA의 세 가지 구성 요소

역할(Role)

요소의 역할을 정의한다. 이는 해당 요소가 어떤 종류의 UI 컴포넌트인지 또는 페이지의 어느 영역인지 나타낸다.

role="button"은 해당 요소가 버튼 기능을 수행
role="navigation"은 내비게이션 영역

속성(Property)

요소의 특성을 정의한다. 이는 콘텐츠의 상태나 특성을 보조 기술에 전달하는데 사용된다.

aria-label="메뉴 열기"는 해당 요소에 대한 설명 텍스트 제공
aria-required="true"는 해당 요소가 필수 항목임을 알수 있도록 제공

상태(State)

요소의 현재 상태를 나타낸다. 속성과 유사하지만 상태는 사용자의 상호작용에 따라 동적으로 변하는 값이다.

aria-expanded="true"는 확장 가능한 영역이 현재 펼쳐져 있음
aria-checked="true"는 체크박스가 선택되어 있음

WAI-ARIA 작성 규칙

HTML의 시맨틱 요소 사용

시맨틱 요소들은 기본적으로 의미와 기능을 제공할 수 있어 접근성을 가지고 있다. 굳이 ARIA를 사용할 필요가 없다.

<header> = role="banner"
<nav> = role="navigation"
<button> = role="button"

<span role="button" tabindex="0">버튼</span>

// role="button"
var roleButton = document.querySelector('[role="button"]');

// keyup 이벤트 핸들러 함수
function keyUpHandler(event) {
  if (event.key === 'Enter' || event.key == 'Space' || event.key == 'Spacebar' ||event.keyCode === 13 || event.keyCode === 32) {
  // Enter 키 또는 Spacebar 키가 눌렸을 때 실행할 작업
  }
}

// role="button"으로 지정된 요소에 keyup 이벤트 리스너 추가
roleButton.addEventListener('keyup', keyUpHandler);

<button> 요소를 사용했다면, 위와 같은 불필요한 스크립트를 작성할 필요가 없게된다.

HTML 요소의 기능 변경 제한

모든 HTML 요소에 ARIA 속성을 추가하거나 기존의 의미를 변강하는건 좋지 않다.

<!-- 이미지 이면서 버튼 역할을 할 수 없다. -->
<img src="./src/images/photo.jpg" alt="photo" role="button" />

요소의 의미론적 충돌로 인해 보조 기술 사용자들은 혼란스러울 수 있다.

키보드 사용 보장

사용자와 상호 작용이 필요한 대화형 UI의 경우 키보드로도 접근 및 사용이 가능하도록 제공해야 한다. 기본적으로 키보드로 접근할 수 없는 HTML 요소의 경우 tabindex="" 속성을 사용하여 키보드로 접근이 가능하도록 할 수 있다.

<!-- 키보드로 접근 가능 -->
<span role="button" tabindex="0">버튼</span>

<!-- 키보드로 접근 불가능 -->
<span role="button" tabindex="-1">버튼</span>

숨김 콘텐츠

ARIA를 사용하거나 CSS를 사용해서 숨김 처리를 하면 접근성이 차단될 수 있다.

display: none 또는 visibility: hidden 스타일 속성을 사용하면, 보조 기술뿐만 아니라 모든 사용자에게서 숨겨진다.
aria-hidden="true", role="presentation", role="none"는 사용자에게 보여지지만 보조 기술에 노출되지 않도록 한다.
- aria-hidden="true" : 보조 기술에서 해당 요소를 완전히 숨김
- role="presentation"/"none" : 요소의 시맨틱 의미만 제거하고 콘텐츠는 노출

모든 상호작용 요소에 접근 가능한 이름을 부여

상호작용 가능한 모든 요소는 접근 가능한 이름을 가져야 한다.

<!-- 레이블 요소를 사용한 경우 -->
<div class="container">
  <label for="user-name">이름</label>
  <input type="text" id="user-name" />
</div>

<!-- aria-label, aria-labelledby 속성을 사용한 경우 -->
<div>
  <div id="user-name">이름</div>
  <input type="text" aria-labelledby="user-name" />
</div>

<button type="button" aria-label="닫기"> X </button>

더 다양한 WAI-ARIA 작성 방법

https://mulder21c.github.io/aria-practices/

[Web] 웹표준과 웹접근성

seungjunn100 — Mon, 23 Feb 2026 16:13:19 +0900

웹표준(Web Standards)

웹사이트를 제작할 때 지켜야 하는 국제적인 기술 규약이다. W3C(World Wide Web Consortium) 라는 국제 기구가 주도하며, 웹 개발의 기본 언어인 HTML, CSS, JavaScript의 기술과 규칙을 정의한다.

웹 표준이 중요한 이유

호환성

사용자가 어떤 운영체제, 브라우저를 이용하든지 웹페이지를 동일하게 보이도록 만들 수 있다.

효율적인 유지보수

표준화된 코드는 다른 개발자들이 쉽게 이해할 수 있으며 협업이 수월해진다.

검색 엔진 최적화(SEO)

구글, 네이버 같은 검색 엔진은 웹 표준을 지킨 웹사이트의 콘텐츠를 더 잘 이해하고 분석할 수 있다. 이는 검색 결과에서 웹사이트가 더 높은 순위로 노출될 가능성을 높여준다.

HTML, CSS, JavaScript와 웹 표준의 관계

HTML

HTML은 웹페이지의 구조와 의미를 담당한다. <h1> 태그는 제목을, <p> 태그는 문단을 나타내는 것처럼 각 태그는 고유한 의미를 가진다. 웹 표준에서는 이처럼 의미에 맞게 태그를 올바르게 사용하는 것을 권장한다.

CSS

CSS는 웹페이지의 시각적인 표현(디자인)을 담당한다. 웹 표준은 HTML이 구조만을 담당하고 CSS가 디자인을 담당하도록 역할을 분리하는 것을 권장한다. 이 덕분에 구조와 디자인을 독립적으로 관리할 수 있어 유지보수가 용이해진다.

JavaScript

JavaScript는 웹페이지의 동적인 기능을 담당한다. 사용자의 행동에 반응하여 콘텐츠를 변경하거나 애니메이션을 추가하는 등 상호작용을 구현한다. 웹 표준은 JavaScript가 웹페이지의 구조(HTML)나 디자인(CSS)을 비표준적으로 조작하는 것을 지양하고 오직 동적인 기능에만 집중하도록 권장한다.

// 구조의 비표준적인 방식 - 의미를 가지지 않는 태그를 사용
const newElement = document.createElement('div');
newElement.innerHTML = '<b>Hello World</b>';
document.body.appendChild(newElement);

// 구조의 표준적인 방식 - 내용의 의미에 맞는 태그를 사용
const newElement = document.createElement('strong');
newElement.textContent = 'Hello World';
document.body.appendChild(newElement);

// 디자인의 비표준적인 방식 - HTML 요소에 직접 스타일 정보를 삽입
const myButton = document.getElementById('my-button');
myButton.style.color = 'red';
myButton.style.fontSize = '20px';

// 디자인의 표준적인 방식 - CSS 클래스 추가하고 실제 스타일 정보는 CSS 파일에 따로 저장
const myButton = document.getElementById('my-button');
myButton.classList.add('active-button');

웹접근성(Web Accessibility)

웹 접근성은 장애인이나 고령자 등 신체적, 환경적 조건에 관계없이 모든 사용자가 웹에 접근하고 이용할 수 있도록 보장하는 것을 의미한다.

신체적 조건이란 장애인, 고령자 등을 포함한 모든 사용자를 의미
환경적 조건이란 다양한 기기, 운영체제, 웹 브라우저, 네트워크 환경 등을 포함하는 것을 의미

웹 접근성이 중요한 이유

모두가 사용할 수 있는 웹

웹이 가진 본질적인 가치는 누구나 어디서나 접근할 수 있는 공간을 설계하는 것이다. 장애인이나 고령자 등 신체적, 환경적 조건에 관계없이 모든 사용자가 웹에 접근하고 이용할 수 있도록 보장하는 것이다. 마치 건물에 엘리베이터나 경사로를 설치해 누구나 쉽게 드나들 수 있게 하는 것과 같다.

법률적 준수

많은 국가에서 웹 접근성 준수를 법적으로 의무화하고 있다. 한국도 지능정보화기본법, 장애인차별금지법 등 법적 의무사항이 있다. 미국에서는 시각 장애인 연맹(NFB)이 대형 유통업체인 타겟(Target)을 상대로 웹 접근성 미달로 고소한 사례도 있다. 관련링크

사용자층 확대

웹 접근성을 개선하면 장애인이나 고령자 등 신체적·환경적 제약이 있는 사람은 물론, 모바일 사용자까지 더 폭넓은 이용자가 편리하게 웹사이트를 사용할 수 있다. 이는 곧 잠재 고객 확대와 비즈니스 기회 창출로 이어진다.

웹 콘텐츠 접근성 가이드라인

웹 콘텐츠 접근성 가이드라인(WCAG - Web Content Accessibility Guidelines)은 웹 콘텐츠의 접근성을 확보하기 위해 W3C에서 제공한 권고안이다. 이 지침의 목적은 장애인과 고령자를 포함한 모든 사용자가 웹 콘텐츠를 인식하고 이해하며, 원활히 상호작용할 수 있도록 보장하는 것이다.

WCAG는 4가지 주요 원칙을 바탕으로 구성되어 있다. 이 4가지 원칙은 접근 가능한 웹사이트를 만들기 위한 필수적인 조건이다.

인지 가능(Perceivable)

정보와 UI 컴포넌트는 사용자가 인지할 수 있는 방식으로 제공되어야 한다.

이미지 대체 텍스트 제공
비디오 자막 지원
색상(명도) 대비

운용 가능(Operable)

UI 컴포넌트와 내비게이션은 사용자가 운용할 수 있는 방식으로 제공되어야 한다.

마우스 없이 키보드만으로 조작 가능
콘텐츠를 읽거나 기능을 사용하기 위한 충분한 시간
탐색을 쉽게 하기 위한 명확한 내비게이션

이해 가능(Understandable)

정보와 UI 조작 방식은 사용자가 이해할 수 있는 방식으로 제공되어야 한다.

읽고 이해하기 쉬운 텍스트 콘텐츠
일관되고 예측 가능한 웹페이지의 반응
오류 발생시 오류를 명확하게 알려주고 수정 방법 제공

견고성(Robust)

콘텐츠는 다양한 기술 환경에서도 안정적으로 작동해야 한다.

다양한 브라우저, 보조 기술, 장치에서도 안정적으로 작동
HTML, CSS 등 웹 기술의 문법적 규칙을 준수

[Final Project] 브루노, 데이터 (feat. Schema, MongoDB)

seungjunn100 — Thu, 22 Jan 2026 16:33:02 +0900

브루노

프로젝트를 시작하기전에 API 요청을 재현할 수 있도록 테스트하기 위해 브루노를 사용하였다.

팀에게 필요한 대략적인 API 요청을 페이지별로 분리하여 Collection을 설계하였다.

설계한 폴더와 참고사항을 팀원에게 공유하고 각자의 로컬에서 테스트해 볼 수 있도록 하였다.

먼저 환경변수로 API 서버 URL과 API를 사용할 수 있게 허가된 ID를 설정하였다.

API 요청을 보낼 때 어디서 보냈는지 확인할 수 있게 헤더에 Client-Id를 설정하였다.

로그인 API 요청 시 성공하면 응답으로 토큰을 발급받아 환경 변수에 토큰을 저장하도록 설정하였다.

이렇게 스크립트를 작성해두면 다른 사용자들이 로그인을해도 각자의 토큰이 환경 변수에 저장된다.

발급받은 토큰은 로그인한 사용자의 고유의 값으로 Baerer Token의 값으로 설정해준다.

그러면 아래와 같이 마이페이지나 결제같은 개인적인 작업을 할 때 Baerer Token에 의해 권한을 확인한 후 작업을 수행할 수 있다.

데이터 (feat. Schema, MongoDB)

스키마

Schema(스키마)란 데이터가 어떤 모양과 규칙을 가져야 하는지에 대한 데이터 설계도이다.

- 스키마는 어떤 필드가 존재해야 하는지
- 필수인지, 선택인지
- 각 필드명은 무엇인지
- 각 필드의 타입이 무엇인지
- ... 등등

스키마가 있는 경우

Product {
  _id: number (필수)
  name: string (필수)
  price: number (필수)
  quantity: number (필수)
  extra?: object
}

타입스크립트와 같이 값을 엄격하게 받아 데이터의 품질을 유지할 수 있다.

스키마가 없는 경우

{
  "prcie": 3000,
  "categoryId": "diet",
  "name": "가르시니아 캄보지아",
  "content": "영양제를 드셔보세요!",
}

자유롭게 작성이 가능하여 전부 데이터로 저장되어 관리가 복잡해지고 관리 비용이 커진다.

DB 유형

DB마다 스키마 성격이 다르다.

관계형 DB (MySQL)

- 스키마 강제
- 테이블 구조 먼저 정의
- 안정적, 정형 데이터에 강함

NoSQL (MongoDB)

- 기본은 스키마 없음
- 문서마다 구조 달라도 저장됨
- 대신 애플리케이션 단에서 스키마를 걸어주는 게 일반적

현재 프로젝트에서는 MongoDB를 활용하고 있는데 테스트 해본 결과 필수인 스키마만 지키면 자유자제로 데이터 필드를 설계하여 사용할 수 있었다.

[
  {
    "mainId": "diet_garcinia",
    "categoryId": "diet",
    "name": "가르시니아 캄보지아",
    "content": "영양제를 드셔보세요!",
    "mainNutrients": ["HCA"],
    "mainFunctions": ["탄수화물의 지방 전환 억제", "체지방 감소"],
    "intakeGuide": "식사 30분 전 섭취",
    "precautions": ["위장 장애 주의", "임산부 섭취 금지"],
    "storage": "서늘하고 건조한 곳",
    "nutritionInfoExample": {
      "servingSize": "750mg",
      "nutrients": [{ "name": "HCA", "amount": "750mg", "dailyValue": "100%" }]
    },
    "quantity": 600,    // 필수
    "show": true,       // 필수
    "active": true      // 필수
  }, 
  .
  .
]

그래서 예제로 위와 같은 JSON 형태의 데이터를 설계하여 브루노를 통해 DB 초기화를 진행했다.

아래와 같이 MongoDB에 임시로 설계한 데이터로 초기화 된 것을 볼 수 있었다.

브루노에서도 조회가 되는 것을 확인하였다.

[Final Project] 프로젝트 구조와 기능 흐름 정리

seungjunn100 — Thu, 22 Jan 2026 16:32:33 +0900

프로젝트 구조

  final-team-project/
│
├──   app/                               # App 라우트 그룹
│   ├──   (auth)/                        ## 인증 관련 라우트 그룹
│   │   ├──   login/
│   │   │   └──   page.tsx               ### 로그인 페이지
│   │   ├──   signup/
│   │   │   └──   page.tsx               ### 회원가입 페이지
│   │   └──   layout.tsx                 ### 로그인/회원가입 전용 레이아웃 (헤터/푸터 X) (로고 홈 링크)
│   │
│   ├──   mypage/                        ## 마이페이지 라우트 그룹
│   │   └──   page.tsx                   ### 마이페이지
│   │
│   ├──   survey/                        ## AI 설문조사 라우트 그룹
│   │   ├──   result/
│   │   │   └──   page.tsx               ### AI 설문조사 결과 페이지
│   │   └──   layout.tsx                 ### AI 설문조사 전용 레이아웃 (헤터/푸터 X) (뒤로가기/설문종료)
│   │
│   ├──   products/                      ## 상품 목록 라우트 그룹
│   │   ├──   [id]/
│   │   │   └──   page.tsx               ### 상품 상세 페이지
│   │   └──   page.tsx                   ### 상품 목록 페이지
│   │
│   └──   subscription/                  ## 결제(구독) 라우트 그룹
│       └──   page.tsx                   ### 결제(구독) 페이지
│
├──   components/                        # 컴포넌트
│   └──   common/                        ## 공통 컴포넌트
│       ├──   Header.tsx                 ### 헤더 (예제)
│       ├──   Footer.tsx                 ### 푸터 (예제)
│       └──   ErrorBoundary.tsx          ### 에러 처리 로직 (예제)
│
├──   lib/                               # API 요청 로직
│   └──   auth.ts                        ### 인증 관련 API 요청 함수 정의 (예제)
│
├──   actions/                           # Server Actions
│   └──   auth.ts                        ### 인증 관련 서버 액션 (예제)
│
├──   types/                             # 타입 정의
│   ├──   index.ts                       ### 공통으로 사용하는 응답 타입 export
│   └──   auth.ts                        ### 인증 관련 API 요청/응답 타입 정의 (예제)
│
├──   store/                             # 상태 관리 (Zustand)
│   └──   authStore.ts                   ### 인증 상태 전역 관리 (예제)
│
├──   hooks/                             # 커스텀 훅
│   └──   useAuth.ts                     ### 인증 관련 로직을 추상화한 커스텀 훅 (예제)
│
├──   public/                            # 정적 파일
│       ├──   images/                    ## 이미지 파일
│       └──   icons/                     ## 아이콘 파일
│
├──   page.tsx
├──   layout.tsx
├──   error.tsx
├──   not-found.tsx
│
.
.

프로젝트를 들어가기에 앞서 전체 구조와 각자의 담당 범위를 먼저 정하고, 이를 기준으로 폴더 구조만 설계했다.

공통으로 사용하는 타입이나 API 요청 로직까지 미리 구현하여 제공하면 좋았을 것 같았지만,
한정된 개발 기간과 현재 숙련도를 고려했을 때 공통 로직을 완성도 있게 작성하기는 어렵다고 판단했다.

그리고 이번 프로젝트의 목적이 단순히 완성된 결과물이 아니라 과정에 따른 학습이었기에,
최소한의 공통 규칙만 정한 뒤, 각자가 필요한 타입과 로직들은 직접 구현하며 경험해보는 방식을 선택했다.

기능 정의서

각자 담당하는 페이지별로 구체적으로 어떤 기능을 개발할 것인지 기능 정의서를 작성하였다.

아래에는 내가 담당한 부분의 한 부분을 작성한 것이다. 한정된 기간 내에 작업을 하기 위해 필수적인 기능을 [1순위]로 두고 [2순위]부터는 선택 사항으로 작업 하도록 방향을 잡았다.

로그인 페이지

- [1순위] 이메일, 비밀번호 입력시 형식 검증
- [1순위] 로그인 성공 시 이전 페이지로 이동
- [1순위] 로그인 실패 시 에러 사유 렌더링
- [2순위] 소셜 계정을 통한 로그인
- [2순위] 비밀번호 재설정
- [3순위] 로그인 상태 유지 기능

한정된 기간이라도 최대한 할 수 있는 부분은 해보려고 한다.

와이어 프레임

와이어프레임이라 레이아웃을 간단하게 작업해서 보여줄 수도 있었지만, 로그인 페이지의 대략적인 시안이 잡혀있어 시안을 통해 정리했다.

기능정의서에 정의한 것을 토대로 화면 구조에 따라서 사용자의 흐름은 어떻게 흘러가는지 자세히 적어, 팀원 간 기획 의도를 명확하게 알 수 있도록 작업하였다.

Record Repository

[Next.js] Claude Code CLI를 활용한 리팩토링

로그인 기능 개선 사항 정리

하드코딩된 테스트 자격증명 제거

로그인 성공 시 alert() 제거

비밀번호 표시/숨김 토글 추가

비밀번호 찾기 링크 오류 수정

카카오 로그인 실패 에러 처리

카카오 콜백 — code 없을 때 무한 로딩 방지

카카오 로그인 사용자 정보 누락 수정

로그아웃 — 백엔드 API 호출 추가

로그인 폼 클라이언트 유효성 검사

회원가입 기능 개선 사항 정리

'use client' + metadata 충돌 버그 수정

회원가입 성공 시 alert() 제거

본인인증 버튼 disabled 로직 버그 수정

비밀번호 표시/숨김 토글 추가

본인인증 catch 블록 사용자 에러 메시지 추가

PortOne 하드코딩 값 환경변수로 분리

각 input 요소마다 여러 개의 상태 변수 사용

느낀점

[Next.js] 회원가입 시 PortOne API로 휴대폰 본인인증 구현하기

PortOne SDK 설치

PortOne 관리자 콘솔 연동

브라우저 구현 (본인인증 요청)

서버 구현 (REST API로 인증 검증/정보 획득)

Route Handler에서 처리한 이유

verifiedCustomer에서 얻을 수 있는 정보

[Next.js] 회원가입 기능 구현

회원가입 서버 / 클라이언트 컴포넌트 분리

회원가입 인증 흐름 설계

클라이언트 입력 검증 UX 설계

서버 액션 구현

이메일 정규 표현식 및 중복 확인

정규 표현식

중복 확인

회원가입 요청

[Next.js] 카카오 소셜 로그인 기능 구현

카카오 개발자 콘솔에서 앱 설정

기능 구현 흐름

KakaoLogin 버튼

Kakao Login 페이지

loginKakao 서버 액션

[Next.js] 로그인 상태에 따른 헤더 메뉴 깜빡임 문제 해결 (feat. Hydration)

Hydration이란

동작 과정

빌드 시

서버

브라우저

새로고침 시 UI가 깜빡인 이유

상태 적용 완료 이후에만 렌더링하도록 개선

[Next.js] 로그인 기능 구현

로그인 서버 / 클라이언트 컴포넌트 분리

로그인 인증 흐름 설계

서버 액션 구현

로그인 요청

토큰 저장 방법

로그인 이후, user 상태 관리

store 설계

[Web] 웹접근성을 위한 WAI-ARIA

WAI-ARIA

유저 에이전트와 접근성 API 및 보조 기술 간의 관계

WAI-ARIA의 세 가지 구성 요소

역할(Role)

속성(Property)

상태(State)

WAI-ARIA 작성 규칙

HTML의 시맨틱 요소 사용

HTML 요소의 기능 변경 제한

키보드 사용 보장

숨김 콘텐츠

모든 상호작용 요소에 접근 가능한 이름을 부여

더 다양한 WAI-ARIA 작성 방법

[Web] 웹표준과 웹접근성

웹표준(Web Standards)

웹 표준이 중요한 이유

호환성

효율적인 유지보수

검색 엔진 최적화(SEO)

HTML, CSS, JavaScript와 웹 표준의 관계

`Route Handler`에서 처리한 이유

`verifiedCustomer`에서 얻을 수 있는 정보

로그인 이후, `user` 상태 관리

`store` 설계