연말정산
테이블 (8)
국세청 간소화자료 일괄제공 PDF 원본/파싱 메타(원문 보관) (yea_nts_bulk_file)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 사업체 FK (business_id) — BIGINT — NOT NULL — 사업체 FK
- 귀속연도 (tax_year) — INT — NOT NULL — 귀속연도(YYYY)
- 업로드 원본 파일명 (original_name) — VARCHAR(500) — NOT NULL — 업로드 원본 파일명
- 서버 저장 파일명 (saved_name) — VARCHAR(500) — NOT NULL — 서버 저장 파일명
- 파일 저장 경로 (path) — VARCHAR(500) — NOT NULL — 파일 저장 경로
- MIME 타입 (mime_type) — VARCHAR(50) — NOT NULL — MIME 타입
- 총 페이지 수(선택) (pages_count) — INT — 총 페이지 수(선택)
- 파일 무결성 (sha256_hash) — VARCHAR(100) — 파일 무결성 SHA-256 해시
- 파싱 상태 (parse_status) — VARCHAR(20) — NOT NULL — 파싱 상태(UPLOADED/PARSED/FAILED)
- 파싱 완료 일시 (parsed_at) — TIMESTAMP — 파싱 완료 일시
- 파싱 로그/오류 메시지 (parse_log) — VARCHAR(2000) — 파싱 로그/오류 메시지
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
부양가족 (관계/연령/소득/동거/장애 등 판정 결과 저장) (yea_dependents)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 연말정산 세션 FK (yea_settlement_id) — BIGSERIAL — 외래 키 → 연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관.PK — NOT NULL — 연말정산 세션 FK
- 관계 코드 (relation_code) — VARCHAR(20) — NOT NULL — 관계 코드(배우자/부/모/자/손자녀/형제자매 등)
- 성명 (name) — VARCHAR(100) — NOT NULL — 성명(증빙과 일치)
- 주민등록번호 (jumin_hash) — VARCHAR(128) — 주민등록번호 해시(원문 미저장 보안처리)
- 생년월일 (birth_date) — DATE — 생년월일
- 동거 여부 (cohabitation_yn) — VARCHAR(1) — 동거 여부(Y/N)
- 장애인 여부 (is_disabled_yn) — VARCHAR(1) — 장애인 여부(Y/N)
- 경로우대(만70세이상) 여부 (is_senior_yn) — VARCHAR(1) — 경로우대(만70세↑) 여부(Y/N)
- 한부모 여부 (is_single_parent_yn) — VARCHAR(1) — 한부모 여부(Y/N)
- 소득금액 (income_amount) — NUMERIC(19,0) — 소득금액(요건 판정 참고용)
- 적격여부 (eligibility) — VARCHAR(20) — NOT NULL — 적격여부(ELIGIBLE/INELIGIBLE/PENDING)
- 미인정 사유 (ineligibility_reason) — TEXT — 미인정 사유(룰/근거 요약)
- 증빙 파일 FK (evidence_file_id) — BIGINT — 증빙 파일 FK
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
세액감면/세액공제 내역(자녀·결혼·연금계좌·보험/의료/교육/기부·월세 등) (yea_tax_credit_item)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 연말정산 세션 FK (yea_settlement_id) — BIGSERIAL — 외래 키 → 연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관.PK — NOT NULL — 연말정산 세션 FK
- 카테고리 코드 (category_code) — VARCHAR(50) — NOT NULL — 카테고리 코드(YEA_CATEGORY, 예: CHILD_TAX, MARRIAGE_TAX, RENT_TAX 등)
- 공제 / 감면 기초금액 (base_amount) — NUMERIC(19,0) — NOT NULL — 공제(감면) 기초금액(원)
- 세액공제율/감면율 (rate_percent) — NUMERIC(5,2) — 세액공제율/감면율(%)
- 세액공제/감면 한도 (limit_amount) — NUMERIC(19,0) — 세액공제/감면 한도(원)
- 실제 반영된 세액공제/감면 금액 (amount_credited) — NUMERIC(19,0) — NOT NULL — 실제 반영된 세액공제/감면 금액(원)
- 부가정보 JSON (metadata_json) — JSONB — 부가정보 JSON(증빙 특성/유형별 세부값)
- 데이터 출처 (source_type) — VARCHAR(20) — NOT NULL — 데이터 출처(NTS_PDF/MANUAL/SYSTEM)
- 출처 식별자 (source_reference) — VARCHAR(200) — 출처 식별자(파일명/문서번호 등)
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
소득공제/기타공제 내역(예: 주택임차차입금, 장기주택저당, 주택마련저축, 신용카드 등) (yea_deduction_item)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 연말정산 세션 FK (yea_settlement_id) — BIGSERIAL — 외래 키 → 연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관.PK — NOT NULL — 연말정산 세션 FK
- 카테고리 코드 (category_code) — VARCHAR(50) — NOT NULL — 카테고리 코드(YEA_CATEGORY, 예: HOUSING_RENT, HOUSING_MORTGAGE 등)
- 하위 카테고리/세부유형 코드 (subcategory_code) — VARCHAR(50) — 하위 카테고리/세부유형 코드(선택)
- 원액 (amount_original) — NUMERIC(19,0) — NOT NULL — 원액(간소화/PDF/영수증 기준 원자료 금액)
- 공제율 (rate_percent) — NUMERIC(5,2) — 공제율(%)
- 공제 한도 (limit_amount) — NUMERIC(19,0) — 공제 한도(원)
- 실제 반영된 소득공제 금액 (amount_deducted) — NUMERIC(19,0) — NOT NULL — 실제 반영된 소득공제 금액(원)
- 대상기간시작일 (period_from) — DATE — 대상기간(시작일)
- 대상기간종료일 (period_to) — DATE — 대상기간(종료일)
- 발급/수취 기관명 (institution_name) — VARCHAR(200) — 발급/수취 기관명
- 상대방 명칭 (counterparty_name) — VARCHAR(200) — 상대방(임대인/교육기관 등) 명칭
- 데이터 출처 (source_type) — VARCHAR(20) — NOT NULL — 데이터 출처(NTS_PDF/MANUAL/SYSTEM)
- 출처 식별자 (source_reference) — VARCHAR(200) — 출처 식별자(파일명/문서번호 등)
- 부가정보 JSON (metadata_json) — JSONB — 부가정보 JSON(계약/계좌/주소 등 세부속성)
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
소득정보(현재/전근무지/기타, 월별 과세·비과세·원천세) (yea_incomes)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 연말정산 세션 FK (yea_settlement_id) — BIGSERIAL — 외래 키 → 연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관.PK — NOT NULL — 연말정산 세션 FK
- 소득 출처 (source_type) — VARCHAR(20) — NOT NULL — 소득 출처(CURRENT/ PREVIOUS/ OTHER)
- 귀속월 (pay_month) — CHAR(6) — 귀속월(YYYYMM)
- 지급유형 (pay_type) — VARCHAR(20) — 지급유형(SALARY/BONUS/ETC)
- 전근무지/지급자 명칭 (employer_name) — VARCHAR(200) — 전근무지/지급자 명칭
- 전근무지 사업자등록번호 (employer_biz_no) — VARCHAR(20) — 전근무지 사업자등록번호
- 과세소득 합계 (taxable_income_amount) — NUMERIC(19,0) — NOT NULL — 과세소득 합계
- 비과세소득 합계 (nontaxable_income_amount) — NUMERIC(19,0) — NOT NULL — 비과세소득 합계
- 원천징수 소득세 합계 (withholding_tax_amount) — NUMERIC(19,0) — NOT NULL — 원천징수 소득세 합계
- 지방소득세 합계 (local_income_tax_amount) — NUMERIC(19,0) — NOT NULL — 지방소득세 합계
- 비고/특이사항 (memo_text) — VARCHAR(2000) — 비고/특이사항
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관 (yea_settlement)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 사업체 FK (business_id) — BIGINT — NOT NULL — 사업체 FK(관할세무서/홈택스ID 등 기존 company 정보 연계)
- 사원-사업체 매핑 FK (employee_member_business_id) — BIGINT — NOT NULL — 사원-사업체 매핑 FK(근로자 소속 기준점)
- 정산 귀속연도 (tax_year) — INT — NOT NULL — 정산 귀속연도(YYYY)
- 정산 상태 (status) — VARCHAR(20) — NOT NULL — 정산 상태(COLLECTING/REVIEWED/FINALIZED/REPORTED)
- 결정세액 (decision_tax_amount) — NUMERIC(19,0) — NOT NULL — 결정세액(산출세액-감면/공제 후)
- 기납부세액 (prepaid_tax_amount) — NUMERIC(19,0) — NOT NULL — 기납부세액(주/전 근무지 합산 원천징수분)
- 차감징수세액 (final_settlement_amount) — NUMERIC(19,0) — NOT NULL — 차감징수세액(=결정세액-기납부세액, 환급/추가납부)
- 계산엔진 버전 (calc_engine_version) — VARCHAR(50) — 계산엔진 버전(산식/규정 버전 식별)
- 검증 룰셋 버전 (rule_set_version) — VARCHAR(50) — 검증 룰셋 버전
- 산출 근거/중간계산 로그 (calc_log_json) — JSONB — 산출 근거/중간계산 로그 JSON(재현용)
- 신고/제출 결과 FK (nts_submission_id) — BIGINT — 신고/제출 결과 FK(선택, yea_submission.id)
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
연말정산 신고/지급명세서 제출 결과(접수번호/상태/메시지) (yea_submission)
- PK (id) — BIGSERIAL — 기본 키 — NOT NULL — PK
- 사업체 FK (business_id) — BIGINT — NOT NULL — 사업체 FK
- 귀속연도 (tax_year) — INT — NOT NULL — 귀속연도(YYYY)
- 제출 구분 (submission_kind) — VARCHAR(20) — NOT NULL — 제출 구분(WITHHOLDING: 원천세, PAYSLIP: 지급명세서)
- 제출 채널 (channel) — VARCHAR(20) — NOT NULL — 제출 채널(HOMETAX/TAX_AGENT/PAPER)
- 접수번호 (receipt_no) — VARCHAR(50) — 접수번호(홈택스 등)
- 제출 일시 (submitted_at) — TIMESTAMP — 제출 일시
- 제출 결과 상태 (result_status) — VARCHAR(20) — 제출 결과 상태(SUBMITTED/ACCEPTED/REJECTED)
- 결과 메시지/사유 (result_message) — VARCHAR(1000) — 결과 메시지/사유(오류 내역 등)
- 제출파일 FK (file_id) — BIGINT — 제출파일 FK(선택, 파일 테이블 연계)
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자
정산 행위/검증 이력(룰코드/주체/메시지/변경 전후) (yea_audit_log)
- PK (id) — BIGSERIAL — 기본 키 — PK
- 연말정산 세션 FK (yea_settlement_id) — BIGSERIAL — 외래 키 → 연말정산 세션 : 연도별 1인 1건 고유, 계산/상태/로그 스냅샷 보관.PK — 연말정산 세션 FK
- 검증룰 코드 (rule_code) — VARCHAR(50) — 검증룰 코드(YEA_RULE_CODE, 경고/차단 근거)
- 행위 유형 (action_type) — VARCHAR(30) — NOT NULL — 행위 유형(CREATE/UPDATE/DELETE/VALIDATE/CALCULATE/STATUS_CHANGE)
- 주체 유형 (actor_type) — VARCHAR(20) — NOT NULL — 주체 유형(ADMIN/EMPLOYEE/SYSTEM)
- 주체 식별자 (actor_id) — VARCHAR(50) — 주체 식별자(ID/사번 등, 선택)
- 요약 메시지 (message) — VARCHAR(2000) — 요약 메시지(사용자 가독용)
- 변경 전 데이터 (before_json) — JSONB — 변경 전 데이터 스냅샷 JSON
- 변경 후 데이터 (after_json) — JSONB — 변경 후 데이터 스냅샷 JSON
- 작성일 (created_at) — TIMESTAMP — NOT NULL — 작성일
- 작성자 (created_by) — VARCHAR(50) — NOT NULL — 작성자
- 수정일 (modified_at) — TIMESTAMP — NOT NULL — 수정일
- 수정자 (modified_by) — VARCHAR(50) — NOT NULL — 수정자