Leysys Docs

공통 입력 정보 ​

상태: 공통 표준 — 2026-10-10 KST 사용자 결정

적용 대상: company-wide — Leysys의 모든 제품·서비스(ERP, 콘솔, 포털, 앱)가 사람·법인·단체·사업자·조직의 정보와 연락처·주소를 받거나 저장하는 곳(화면 라벨, HTML autocomplete, 코드 식별자, API 필드, DB 컬럼)과 문서·데모·테스트의 예시 값

정본 분류: 이 페이지와 아래 다섯 쪽이 회사 공통 표준의 정본입니다. 결정 근거·검토·제품 현황·이행 단계는 leysys-design의 결정 기록 COMMON-FIELDS-2026-10-10에 있습니다. 규칙을 바꿀 때는 정본과 결정 기록을 함께 고칩니다. 입력 화면의 구현은 leysys-design이, 각 제품의 채택 현황·데이터 이행·의도적 편차는 해당 제품 저장소가 소유합니다. 문서 변경은 런타임 채택을 증명하지 않습니다.

ERP든 앱이든 보편적으로 입력하는 정보를 국제 표준에 맞춘 한 벌의 이름과 규칙으로 다룹니다. 이 쪽은 공통 규칙이고, 분야별 필드는 다음 다섯 쪽에 있습니다.

쪽다루는 것
당사자개인·법인·법인 아닌 단체, 세법상 구분, 식별번호, 법적 대표자
사업자사업자등록·고유번호, 사업장, 세금계산서 항목
조직회사·단체의 프로필, 부서, 소속(직함)
연락처전화번호·이메일주소·웹·SNS, 담당자 묶음
주소주소 필드, 주소 종류, 한국 주소 저장

원칙 ​

  • 의미를 먼저 정합니다. 법적·세무상 의미는 법령과 공식 등록 체계(법원 등기, 국세청)가 정합니다. 이름은 그 의미가 정해진 뒤에 고릅니다.

  • 이름은 국제 표준에서 고릅니다. 같은 의미의 후보가 여럿이면 다음 순서입니다.

    1. WHATWG HTML 자동완성 토큰
    2. schema.org 속성
    3. vCard(RFC 6350·9554)

    국제 대응이 없는 한국 제도는 법령 용어를 영어로 옮긴 이름을 씁니다(예: businessRegistrationNumber).

  • HTML 자동완성 토큰은 입력 목적을 정의할 뿐 데이터 이름을 정하지 않습니다. Leysys는 회사 결정으로 그 어휘를 데이터 이름에도 씁니다.

  • 토큰·코드·DB가 같은 단어를 씁니다.

    • autocomplete에는 토큰 그대로, 코드·API에는 단어를 camelCase로 붙이고, DB에는 snake_case로 씁니다.
    • 예: mobile tel → mobileTel / mobile_tel, bday → bday, given-name → givenName / given_name.
    • schema.org 속성은 대소문자까지 그대로 씁니다(taxID → DB tax_id).

  • 임의로 줄이지 않습니다. businessRegNum·mgmtCode 같은 줄임 이름은 쓰지 않습니다. 표준 토큰(tel·bday)과 공인된 약어(ISO, KSIC, URL, E.164 등)는 그대로 씁니다.

  • 필요한 필드만 둡니다. 모든 레코드에 모든 필드를 만들지 않습니다(레코드 식별 필드의 「있으면 이 규칙으로」와 같습니다).

저장 구조 ​

  • 여럿일 수 있는 정보는 목록과 관계로 저장합니다. 식별번호(identifiers), 주소(addresses), 담당자(contacts), 법적 대표자(legalRepresentatives), 업종 분류(industryClassifications), SNS(socialProfiles)가 해당합니다. 목록 이름은 복수형입니다.
  • 한 칸 이름 필드는 입력·출력 계약입니다. residentRegistrationNumber, businessAddressLine1 같은 필드는 화면·법정 서식·연동의 입력·출력에서 씁니다. 같은 값을 목록과 한 칸 필드에 두 번 저장하지 않습니다.
  • API는 중첩 객체로 냅니다. 예: legalAddress: { postalCode, addressLine1, … }, primaryContact: { name, mobileTel, … }. 접두어를 이어 붙인 평면 이름(businessLegalRepresentativeName)은 만들지 않습니다. 평면 접두어 필드 (businessAddressLine1)는 평면 입력·내보내기(CSV 등)에서만 씁니다.
  • 발행한 문서는 발행 당시 값을 그대로 둡니다. 계약서·세금계산서·영수증에 찍힌 이름·주소·번호는 이후 레코드가 바뀌어도 고치지 않습니다. 같은 값을 두 번 두지 않는다는 원칙의 예외입니다.

값 형식 ​

값저장 형식표준
날짜YYYY-MM-DDISO 8601
날짜·시각시간대 오프셋을 포함한 ISO 8601. 시간대 이름이 필요하면 IANA 이름(Asia/Seoul)ISO 8601, IANA tz
나라두 글자 대문자(KR)ISO 3166-1 alpha-2
나라 아래 1단계 행정구역 코드KR-11ISO 3166-2
통화세 글자(KRW). 금액의 소수 자릿수는 통화를 따름(KRW 0)ISO 4217
언어ko, ko-KR, en-USBCP 47
전화번호+821012345678ITU-T E.164
이메일주소입력 그대로 저장(앞뒤 공백만 제거). 같은 주소인지 비교할 때 도메인(@ 뒤)만 대소문자를 무시하고, @ 앞은 그대로 비교WHATWG 유효 이메일주소, RFC 5321
웹 주소유효 URLWHATWG URL
글자UTF-8. 사람에게 보이는 글자(이름·상호·주소)는 NFC로 정규화해 저장. URL·이메일·식별번호는 정규화하지 않음Unicode
  • 금액의 반올림과 확정 시점은 각 업무(청구·회계)가 정합니다. 중간 계산의 정밀도와 확정 금액을 구분합니다.

라벨 ​

  • 끝을 맞춥니다. 전화 계열은 「번호 / number」, 이메일은 「주소 / address」로 끝냅니다(「휴대전화번호」, 「이메일주소」). 오류 문구 같은 문장도 같은 명사를 씁니다.
  • 짧게 줄이지 않습니다. 모바일이나 좁은 칸에서도 「휴대전화」·「전화」·「이메일」·「배송」처럼 끝을 빼지 않고, 화면 폭에 따라 라벨을 바꾸지 않습니다. 좁으면 배치(가로 스크롤·열 폭·라벨과 값을 위아래로)로 풉니다.
  • 라벨은 저장되는 필드의 뜻을 따릅니다. 휴대전화 전용 필드에 저장되는 칸은 「전화번호」가 아니라 「휴대전화번호」입니다 (예: 법인 리드의 「담당자 휴대전화번호」). 필드를 대상으로 하는 버튼·시트 제목·배지도 같은 명사를 씁니다 (「이메일주소 변경」).
  • 사람 이름은 「이름」, 법인·사업자의 이름은 「상호」(민법 법인·단체는 「명칭」)입니다.
  • 「일반전화」·「휴대폰」·「핸드폰」·「이동전화」·「성명」·General phone·First name·Last name은 일반 화면 라벨로 쓰지 않습니다.
  • 법정 서식은 서식의 칸 이름을 그대로 씁니다. 세금계산서의 「성명(대표자)」·「상호(법인명)」처럼 법령이 정한 서식을 그리거나 출력할 때가 해당합니다.

입력 안내 ​

  • leysys-design의 입력 필드 규칙(PATTERN-INFO-HINT-PROGRESSIVE-DISCLOSURE, 2026-10-08 KST 개정)을 따릅니다.
  • 입력 칸 아래 정적 보조 설명은 두지 않습니다. 바꿀 수 없음·단위·입력값 제한(예: 「휴대전화번호만 받습니다」)만 라벨 옆 ⓘ로 알립니다.
  • 검증 오류와 동적 상태 문구는 그대로 보여 줍니다.

autocomplete ​

  • 본인 정보를 입력하는 화면(가입, 내 정보, 결제·배송)은 표준 토큰을 씁니다.
  • 다른 사람의 정보를 입력하는 화면(직원이 고객·파트너·멤버를 등록하는 콘솔 등)은 autocomplete="off"입니다.
    • off는 브라우저에 대한 요청이지 보장이 아닙니다. 브라우저나 사용자 설정이 무시할 수 있습니다.
    • 한 화면에 두 종류가 섞이면 필드마다 정합니다.
  • 같은 입력 묶음이 반복되면 section-*로 나눕니다(예: section-legal address-line1). section-*은 묶음을 구분할 뿐 뜻이 없습니다.
  • 표준 토큰의 뜻과 저장값이 다르면 토큰을 쓰지 않습니다. 예를 들어 HTML sex는 자유 입력 성별 정체성이라, 코드로 받는 성별 칸에는 쓰지 않습니다.

확인 기록 ​

  • 휴대전화번호·이메일주소·사업자등록 상태처럼 확인하는 값은 확인 기록을 따로 둡니다.
    • 한 번만 남기면 사건 필드 쌍 {필드}VerifiedAt·{필드}VerifiedBy를 둡니다(예: mobileTelVerifiedAt·mobileTelVerifiedBy). 접근 역할 체계의 {동사}edAt·{동사}edBy 규칙과 같습니다.
    • 여러 번 확인한 이력이 필요하면 확인 사건 레코드를 둡니다.
  • 확인은 확인한 값에 묶입니다. 값이 바뀌면 확인을 해제합니다.
  • 외부 기관 확인(국세청 진위확인 등)은 다음을 남깁니다.
    • 확인 시각, 확인 출처, 확인에 쓴 값
    • 결과: 일치 · 불일치 · 아직 반영 안 됨 · 확인 실패(통신 오류 등). 이 넷을 구분합니다.
    • 등록 정보가 일치한다는 확인일 뿐이며, 본인 확인이나 대표권 확인과는 다릅니다.

예시 값 ​

항목한국어 화면영어 화면
사람 이름홍길동John Doe
휴대전화번호010-1234-5678한국 번호면 그대로(+82 10-1234-5678)
전화번호(유선·인터넷전화)·팩스번호전화 070-1234-5678 · 팩스 070-1234-5679한국 번호면 그대로(+82 70-1234-5678)
미국 전화번호—202-555-0123
인증번호123456123456
이메일주소user@example.comuser@example.com
상호주식회사 예시(가상)Example Inc. (fictitious)
사업자등록번호123-00-45678123-00-45678
주민등록번호·외국인등록번호·법인등록번호******-*************-*******
  • 전화번호
    • 예시는 화면 언어가 아니라 번호가 속한 나라를 따릅니다.
    • 010 이동전화의 부여 범위는 010-2XXX–010-9XXX입니다. 예시 번호가 여러 개 필요하면 범위 밖인 010-1XXX-XXXX 안에서 바꿉니다(예: 010-1234-0001). 영구히 연결되지 않는다는 보장은 아니므로 실제 문자 발송 차단은 따로 유지합니다.
    • 전화번호(유선·인터넷전화)·팩스번호 예시는 070-1234-5678(전화)·070-1234-5679(팩스)입니다. 070 다음 자리가 0·1인 번호(0700·0701)는 부여되지 않아 휴대전화 예시(010-1234-5678)와 같은 원리이고 모양도 같습니다. 여러 개가 필요하면 끝 4자리만 바꿉니다(예: 070-1234-0001).
    • 지역번호(02·031 등) 예시는 쓰지 않습니다. 02-1234-5678처럼 예시로 흔히 쓰던 번호가 실제 번호인 사례가 있습니다.
    • 실제 가입자 대역 번호는 문서·데모·테스트에 쓰지 않습니다.
    • 미국 번호는 북미 번호 계획이 가상 용도로 남긴 555-0100–555-0199만 씁니다.
  • 사업자등록번호: 가운데 00은 국세청이 공개한 부여 범위 밖입니다. 화면 표시용 가상값으로만 쓰고, 검증식 테스트나 국세청 진위확인 API에는 쓰지 않습니다.
    • 사업자 유형(개인사업자·법인사업자)을 보여야 하는 샘플 레코드는 앞 세 자리를 100으로 씁니다(2026-10-17 KST 사용자 결정). 국세청 일련번호 범위(101–999) 밖이라 부여되지 않는 번호입니다. 가운데 두 자리는 보이려는 구분 코드(개인 과세 01, 영리법인 본점 81, 비영리 단체 80 등)이고, 마지막 자리는 업계 검증식에 맞춰 경고가 나지 않게 합니다(예: 100-01-00011 · 100-81-00013). 여러 개가 필요하면 일련번호 4자리를 바꾸고 검증번호를 다시 맞춥니다.
    • 입력 칸 예시(placeholder)는 그대로 123-00-45678입니다. 100-XX-XXXXX도 국세청 진위확인 API에는 쓰지 않습니다.
  • 13자리 등록번호: 예시도 모두 가립니다. 실제 번호와 겹칠 수 있는 13자리 예시를 쓰지 않습니다.
  • 해외 세무번호: 발급국이 부여하지 않는 범위나 발급국 검증 규칙에 어긋나는 값을 씁니다. 예: 미국 EIN은 부여되지 않는 앞자리 00(00-0000001), 독일 부가가치세 번호는 검증 숫자가 맞지 않는 값. 확인할 수 없는 나라는 예시를 가립니다.
  • 상호: 「(가상)」을 붙입니다. 같은 이름의 실제 업체가 없다고 보장하지는 않습니다.
  • 이메일: RFC 2606 예약 도메인(example.com)을 씁니다. 해석되지 않는 주소가 필요하면 user@example.invalid를 씁니다. 예약 도메인도 발송 차단 장치는 아니므로 외부 발송은 따로 막습니다.
  • 법정 지정값은 예시가 아닙니다. 국세청이 정한 현금영수증 자진발급 번호 010-000-1234가 그 예입니다.
  • placeholder와 인증번호 칸
    • placeholder는 선택입니다. 쓰면 대표 값과 같게 씁니다.
    • 인증번호 칸은 비워 두고 붙여넣기와 one-time-code 자동완성을 지원합니다. 123456으로 통과하는 고정 인증은 문서와 격리된 모의 환경에만 둡니다.
  • 테스트 데이터
    • 목적별로 둡니다(형식 오류 거부, 앞자리 0, 만료 등).
    • 예시 값을 통과시키려고 검증을 느슨하게 하지 않습니다.
    • 여러 사람이 나오는 예시는 이름의 문화·길이를 다양하게 씁니다.

채택 ​

  1. 의미 확인: 필드마다 실제로 무엇을 받는지 먼저 확인합니다(종류 무관·휴대·유선·대표, 개인·법인 등).
  2. A. 화면: 의미가 그대로인 변경만 합니다. 라벨, autocomplete, 예시 값, 실제 가입자 대역 번호 교체가 해당합니다. 의미가 바뀌는 필드는 라벨·검증·데이터 계약을 B에서 함께 바꿉니다.
  3. B. 데이터 계약: 코드·API·DB 이름 변경, 목록 구조로의 이전, 값 변환(E.164 등)입니다.
    • 최종 상태에 별칭이나 이전 이름 호환 계층을 두지 않습니다.
    • 전환은 다음 중 하나로 합니다: 한 번에 전환(원자적 cutover), 유지보수 창, API 버전 전환.
    • 전환에 반드시 포함합니다: 기존 데이터 이전(backfill), 접근 규칙·view·trigger·RPC·생성 타입 수정, 되돌리기 검증.
    • 운영 데이터가 있는 원격 DB에 적용하는 일은 저장소마다 승인을 받습니다.
  4. 채택 전 편차는 alert입니다. 이 표준을 이유로 commit·PR·병합을 자동으로 막지 않습니다.

관련 문서 ​

© 2026 Leysys. 무단 복제·배포·판매를 금지합니다.