Korean Formats

---
name: korean-formats
description: Use when validating or formatting Korean user input — 주소 address forms with 도로명주소 road-name vs 지번 lot-number, 우편번호 5-digit postal codes, 전화번호 phone numbers with variable-length area codes, 이름 Korean name assumptions, 성명 분리. Explains why fixed-length regex validation rejects valid Korean phone numbers and addresses.
---
<!-- kimchi-ignore-file 나쁜 예를 그대로 인용한다 -->

# 주소, 전화번호, 이름

예제 파일을 열 수 있으면 Read 로 열고, 권한 때문에 막히면 아래 코드를 그대로 쓰십시오.

## 전화번호는 자리수가 고정이 아닙니다

`\d{3}-\d{4}-\d{4}` 로 검증하면 **정상 번호를 거부합니다.**

| 종류 | 형태 | 주의 |
|---|---|---|
| 서울 유선 | `02-1234-5678` | 지역번호가 **두 자리**입니다 |
| 그 밖 유선 | `031-123-4567` | 지역번호 세 자리, 국번은 3자리나 4자리 |
| 휴대전화 | `010-1234-5678` | 011·016·017·018·019 도 아직 쓰는 번호가 있습니다 |
| 대표번호 | `1588-1234` | 지역번호가 **없습니다**. 8자리입니다 |
| 인터넷전화 | `070-1234-5678` | |
| 평생번호 | `0505-1234-5678` | 050 대역은 0502~0507 이 모두 쓰입니다 |
| 안심번호 | `0504-1234-5678` | 오픈마켓 주문에 들어옵니다. **유효 기간이 있습니다** |

동작하는 구현: `examples/phone.mjs`

```js
import { parsePhone, formatPhone, toInternational } from "./examples/phone.mjs";

formatPhone("0212345678"); // "02-1234-5678"
toInternational("010-1234-5678"); // "+821012345678", 앞의 0 을 뗀다
```

입력 검증은 관대하게, 저장은 숫자만, 표시는 형식을 붙여서 하십시오. 사용자가 하이픈을
넣든 안 넣든 받아야 합니다.

**안심번호를 회원 정보에 저장하지 마십시오.** 오픈마켓 주문에는 구매자의 실제 번호 대신
안심번호가 들어오는데 유효 기간이 있습니다. 영구 보관하면 나중에 연락이 닿지 않고, 다른
사람에게 재배정될 수도 있습니다. 주문 단위로만 쓰십시오. `isSafeNumber()` 로 가릅니다.

**번호 종류를 분류해 두십시오.** 유선과 대표번호에는 배송 알림 문자를 보낼 수 없습니다.
검증 통과와 문자 발송 가능 여부는 다른 판정입니다.

## 주소는 한 칸에 담지 마십시오

법정 주소는 **도로명주소**입니다. 지번주소는 병행 표기로 남아 있고 옛 자료에는 지번만
있습니다. 우편번호는 2015년 8월에 여섯 자리에서 **다섯 자리**로 바뀌었습니다.
여섯 자리로 검증하는 코드는 틀립니다.

세 칸으로 나눕니다.

| 칸 | 내용 | 입력 방법 |
|---|---|---|
| 우편번호 | 5자리, 앞 두 자리 01~63 | 주소 검색 결과 |
| 기본주소 | 도로명 + 건물번호 | 주소 검색 결과. **읽기 전용** |
| 상세주소 | 동·호수 | 사용자가 직접 입력 |

**기본주소를 사용자가 고칠 수 있게 두면 배송이 실패합니다.** 주소 검색 API(도로명주소
안내시스템, 카카오 우편번호 서비스)의 결과를 그대로 저장하십시오.

주소 검색 결과에는 괄호로 참고항목이 붙습니다. `서울 강남구 테헤란로 123 (역삼동, 아무빌딩)`
에서 괄호 안은 **주소의 일부가 아닙니다.** 화면에 보여 줄 때만 쓰고 배송이나 주소 비교에
쓰지 마십시오.

동작하는 구현: `examples/address.mjs`

```js
import { splitReference, sameAddress, isValidPostalCode } from "./examples/address.mjs";

splitReference(result.address); // { base, reference }
sameAddress(a, b); // 참고항목과 정규화 형태를 무시하고 견준다
```

주소를 비교할 때 NFC 정규화가 필요합니다. macOS 에서 입력한 주소와 서버에 저장된 주소가
자모 분리 때문에 다를 수 있습니다. `korean-encoding` 스킬을 참고하십시오.

**시도 이름은 출처마다 다르게 옵니다.** 도로명주소 안내시스템은 `서울특별시`, 카카오 주소 검색은
`서울`로 돌려줍니다. 이름도 바뀌었습니다. `강원도`는 2023년 6월에 `강원특별자치도`로,
`전라북도`는 2024년 1월에 `전북특별자치도`로 바뀌었고 옛 자료에는 옛 이름이 남아 있습니다.
`sameAddress`는 시도 이름을 하나로 모아 견줍니다.

**그래도 문자열 비교는 차선입니다.** 시군구와 도로명도 바뀝니다(인천 남구 → 미추홀구, 군위군의
대구 편입). 주소 검색 API가 돌려주는 **건물관리번호를 함께 저장하고** 같은 곳인지는 그 번호로
가리십시오. 문자열 비교는 번호가 없는 옛 자료에만 씁니다.

형식을 판정할 때는 공식 표기에 섞여 오는 것을 받아야 합니다. `테헤란로 123, 101동 1203호`처럼
쉼표 뒤에 상세주소가 붙고, 지하 건물은 `을지로 지하 12`, 임야 지번은 `봉천동 산 101`로 씁니다.

**화면·로그에 내보낼 때 주소를 마스킹하는 것은 이 스킬의 일이 아닙니다.** 동·호수를 가리는
`maskAddress()`와 그 실패 시 닫는 규칙(도로명·지번을 알아볼 수 없으면 시/도까지만 남기고
나머지는 가림)은 `korean-identifiers` 스킬의 `masking.mjs`에 있습니다. 도로명주소든 지번주소든
함께 처리합니다.

## 이름에 대한 가정

- **성과 이름을 분리하지 마십시오.** 성이 두 글자인 경우(남궁, 황보, 선우)를 자동으로
  알 수 없습니다. `firstName`·`lastName` 두 칸으로 받으면 사용자가 잘못 채웁니다
- 한 칸으로 받으십시오. 정렬이나 호칭이 필요하면 별도 칸을 두십시오
- 길이 제한을 두 글자로 잡지 마십시오. 한 글자 이름과 다섯 글자 이상 이름이 있습니다
- 한글만 허용하지 마십시오. 외국인 이용자와 영문 표기가 필요한 자리가 있습니다
- 여권·항공권 연동이 필요하면 영문 성명을 따로 받으십시오. 로마자 표기는 자동 변환으로
  맞출 수 없습니다

## 자주 틀리는 것

- 전화번호를 고정 자리수로 검증하기 — 서울 번호와 대표번호를 거부합니다
- 050 대역에서 0505 만 받기 — 오픈마켓 안심번호(0504 등)가 떨어집니다
- 안심번호를 회원 정보에 영구 보관하기 — 유효 기간이 지나면 연락이 닿지 않습니다
- 우편번호를 여섯 자리로 검증하기 — 2015년 이전 형식입니다
- 주소를 한 칸에 담기 — 상세주소를 분리할 수 없어 배송 자동화가 막힙니다
- 기본주소를 사용자가 고치게 두기
- 참고항목(괄호 안)을 주소의 일부로 저장하기
- 주소 문자열로 같은 곳인지 가리기 — `서울특별시`와 `서울`, `강원도`와 `강원특별자치도`가 어긋납니다. 건물관리번호로 가리십시오
- 성명을 두 칸으로 받기
- 이름 길이를 두세 글자로 제한하기