증명서 발급 (전자증명서)

사용자 입력 → 프론트 암호화 → 서버 복호화 → 벤더 규격 재암호화 → 벤더 API

[1차 요청] 간편인증 요청
  프론트 → POST /v2/user/certificate/resident-certificate
           { vendor, birthDate, identityEnc, loginOrgCd, sido, sigg }
  서버   ← { stepData: "..." }            ← HYPHEN인 경우
           { twoWayInfo: { ... } }         ← CODEF인 경우

[사용자가 휴대폰에서 간편인증 승인]

[2차 요청] 증명서 발급
  프론트 → POST /v2/user/certificate/resident-certificate
           { ..., stepData: "..." }        ← HYPHEN인 경우
           { ..., twoWayInfo: { ... } }    ← CODEF인 경우
  서버   ← { preSignedUrl: "https://s3..." }

import {encryptCertificateField} from '@howmuchhome-web/utils-ts';
 
// 주민등록등본/초본: 주민번호 뒷자리만 암호화
const identityEnc = encryptCertificateField(birthPassword); // 7자리
 
// 가족관계증명서: 주민번호 뒷자리만 암호화
const rrn2Enc = encryptCertificateField(birthPassword); // 7자리

POST /v2/user/certificate/resident-certificate

POST /v2/user/certificate/resident-abstract

POST /v2/user/certificate/family-relations

type CreateResidentCertificateV2Request = {
  vendor: CertificateVendor;       // 'HYPHEN' | 'CODEF'
  loginOrgCd: string;              // 간편인증 서비스 코드 (예: 'kakao', 'toss')
  birthDate: string;               // 주민번호 앞 6자리 (평문)
  identityEnc: string;             // 주민번호 뒷 7자리 (AES-256 암호화)
  sido: string;                    // 시/도 (예: '서울특별시')
  sigg: string;                    // 시/군/구 (예: '강남구')
  stepData?: string | null;        // HYPHEN 2단계 인증 데이터 (2차 요청 시)
  twoWayInfo?: TwoWayInfo | null;  // CODEF 2단계 인증 데이터 (2차 요청 시)
  assignmentId?: string | null;    // 과제 ID (과제에서 진입 시)
};

type CreateFamilyRelationsV2Request = {
  vendor: CertificateVendor;
  loginOrgCd: string;
  rrn1: string;                    // 주민번호 앞 6자리 (평문)
  rrn2Enc: string;                 // 주민번호 뒷 7자리 (AES-256 암호화)
  fthrNm?: string | null;          // 부 성명
  mthrNm?: string | null;          // 모 성명
  sposNm?: string | null;          // 배우자 성명
  childNm?: string | null;         // 자녀 성명 (가족 관계 최소 1개 필수)
  stepData?: string | null;
  twoWayInfo?: TwoWayInfo | null;
  assignmentId?: string | null;
};

// 1차 응답: 간편인증 대기
{
  residentCertificate: {           // 또는 residentAbstract, familyRelationsCertificate
    preSignedUrl: null,
    stepData: "...",               // HYPHEN
    twoWayInfo: null,
  }
}
 
// 또는
{
  residentCertificate: {
    preSignedUrl: null,
    stepData: null,
    twoWayInfo: {                  // CODEF
      jobIndex: 0,
      threadIndex: 0,
      jti: "...",
      twoWayTimestamp: 1234567890
    },
  }
}
 
// 2차 응답: 발급 완료
{
  residentCertificate: {
    preSignedUrl: "https://s3...signed-url",
    stepData: null,
    twoWayInfo: null,
  }
}

enum CertificateVendor {
  HYPHEN = 'HYPHEN',
  CODEF = 'CODEF',
}

apps/app/src/app/(certified-user-only)/more/electronic-certificate/
├── page.tsx                          # 증명서 목록 (발급/제출 현황)
├── _components/
│   └── CertificateConsentBottomSheet.tsx
├── apply/
│   ├── page.tsx                      # 발급 퍼널 진입점
│   ├── funnel.ts                     # 퍼널 스텝 정의
│   ├── type.ts                       # 폼 타입 (BaseCertificateForm, ResidentRegistrationForm, FamilyRelationsForm)
│   ├── _component/
│   │   └── RegionSelect.tsx          # 시/도, 시/군/구 선택
│   └── section/
│       ├── ElectronicCertificateApplyPageIntro.tsx           # Step 1: 정보 입력
│       ├── ResidentRegistrationForm.tsx                      # 등본/초본 입력 폼
│       ├── FamilyRelationsForm.tsx                           # 가족관계 입력 폼
│       ├── ElectronicCertificateApplyPageSimpleVerification.tsx  # Step 2: 간편인증 선택 (1차 API)
│       └── ElectronicCertificateApplyPageConfirm.tsx         # Step 3: 인증 완료 (2차 API)

intro → simpleVerification → confirm

// 공통 필드
type BaseCertificateForm = {
  vendor: CertificateVendor;
  loginOrgCd: EasyLoginCode;
  preSignedUrl?: string | null;
  stepData?: string | null;          // HYPHEN 인증 데이터
  twoWayInfo?: TwoWayInfo | null;    // CODEF 인증 데이터
};
 
// 주민등록등본/초본
type ResidentRegistrationForm = BaseCertificateForm & {
  birthDate: string;      // 주민번호 앞 6자리 (평문)
  identityEnc: string;    // 주민번호 뒷 7자리 (암호화)
  sido: string;
  sigg: string;
};
 
// 가족관계증명서
type FamilyRelationsForm = BaseCertificateForm & {
  rrn1: string;           // 주민번호 앞 6자리 (평문)
  rrn2Enc: string;        // 주민번호 뒷 7자리 (암호화)
  fthrNm: string;
  mthrNm: string;
  sposNm: string;
  childNm: string;
};

// 1차 요청 (simpleVerification 스텝)
const res = await UserAPI.createMyResidentCertificateV2({
  vendor: form.vendor,
  loginOrgCd: selectedLogin,
  birthDate: form.birthDate,
  identityEnc: form.identityEnc,
  sido: form.sido,
  sigg: form.sigg,
});
// → res.stepData 또는 res.twoWayInfo를 폼에 저장
 
// 2차 요청 (confirm 스텝)
const res = await UserAPI.createMyResidentCertificateV2({
  vendor: form.vendor,
  loginOrgCd: form.loginOrgCd,
  birthDate: form.birthDate,
  identityEnc: form.identityEnc,
  sido: form.sido,
  sigg: form.sigg,
  stepData: form.stepData,        // HYPHEN이면 값이 있음
  twoWayInfo: form.twoWayInfo,    // CODEF이면 값이 있음
});
// → res.preSignedUrl로 PDF 다운로드 가능