sam-sales/etax/README_DB.md

전자세금계산서 데이터베이스 스키마

테이블 구조

1. etax_tenants (테넌트 관리)

멀티테넌시 환경에서 각 고객사(테넌트)의 기본 정보를 저장합니다.

주요 필드:

• id: 테넌트 고유 ID
• name: 기업명
• bizno: 사업자번호 (UNIQUE)
• barobill_api_key: 바로빌 API 키
• barobill_cert_id: 바로빌 인증서 ID
• status: 활성 상태 (active/inactive/suspended)

2. etax_certificates (인증서 관리)

각 테넌트의 공동인증서 또는 금융인증서 정보를 관리합니다.

주요 필드:

• id: 인증서 고유 ID
• tenant_id: 테넌트 ID (FK)
• type: 인증서 유형 (public/financial)
• valid_from, valid_to: 인증서 유효기간
• barobill_cert_id: 바로빌 인증서 ID

3. etax_tax_invoices (세금계산서 메인)

전자세금계산서의 기본 정보를 저장합니다.

주요 필드:

• id: 세금계산서 고유 ID
• tenant_id: 테넌트 ID (FK)
• issue_key: 바로빌 발행 키 (UNIQUE)
• supply_amt, vat, total: 금액 정보
• write_date, supply_date: 작성일자, 공급일자
• state: 상태 (draft/issued/sent/cancelled)
• nts_receipt_no: 국세청 접수번호

4. etax_parties (공급자/수취자 정보)

세금계산서의 공급자와 수취자 정보를 저장합니다.

주요 필드:

• id: 고유 ID
• invoice_id: 세금계산서 ID (FK)
• role: 역할 (supplier/recipient/trustee)
• bizno, corp_name, ceo: 사업자 정보
• addr, email, tel: 연락처 정보

5. etax_line_items (품목 상세)

세금계산서의 품목별 상세 정보를 저장합니다.

주요 필드:

• id: 고유 ID
• invoice_id: 세금계산서 ID (FK)
• item_name: 품목명
• qty, unit_price: 수량, 단가
• supply_amt, vat: 공급가액, 부가세
• vat_type: 부가세 유형 (vat/zero/exempt)

6. etax_transmission_logs (전송 로그)

바로빌 API 호출 및 국세청 전송 로그를 기록합니다.

주요 필드:

• id: 로그 고유 ID
• invoice_id: 세금계산서 ID (FK)
• transmission_type: 전송 유형 (issue/cancel/nts_send)
• status: 상태 (success/failed/pending)
• response_data: API 응답 데이터
• error_message: 에러 메시지

설치 방법

1. 데이터베이스 생성 (선택사항)

CREATE DATABASE IF NOT EXISTS `chandj` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE `chandj`;

2. 스키마 실행

# MySQL/MariaDB 접속
mysql -u chandj -p chandj < etax/db_schema.sql

또는 phpMyAdmin이나 다른 DB 관리 도구에서 etax/db_schema.sql 파일을 실행하세요.

3. 권한 확인

테이블이 정상적으로 생성되었는지 확인:

SHOW TABLES LIKE 'etax_%';

사용 방법

PHP에서 데이터베이스 연결

require_once($_SERVER['DOCUMENT_ROOT'] . "/lib/mydb.php");
$pdo = db_connect();

// 테넌트 조회 예시
$stmt = $pdo->prepare("SELECT * FROM etax_tenants WHERE id = ?");
$stmt->execute([$tenant_id]);
$tenant = $stmt->fetch(PDO::FETCH_ASSOC);

멀티테넌시 쿼리 예시

// 항상 tenant_id로 필터링
$stmt = $pdo->prepare("
    SELECT * FROM etax_tax_invoices 
    WHERE tenant_id = ? AND state = 'issued'
    ORDER BY created_at DESC
");
$stmt->execute([$tenant_id]);
$invoices = $stmt->fetchAll(PDO::FETCH_ASSOC);

주의사항

1. 외래키 제약조건: 모든 외래키는 CASCADE 삭제로 설정되어 있어, 부모 레코드 삭제 시 자식 레코드도 자동 삭제됩니다.

2. 인덱스: 자주 조회되는 필드에 인덱스를 설정했습니다. 추가 인덱스가 필요하면 성능 모니터링 후 추가하세요.

3. 문자셋: utf8mb4를 사용하여 이모지 등 모든 유니코드 문자를 지원합니다.

4. 보안:

   • barobill_api_key는 암호화하여 저장하는 것을 권장합니다.
   • kms_key_ref는 암호화된 인증서 참조를 저장합니다.

마이그레이션

기존 JSON 파일(invoices_data.json)에서 데이터를 마이그레이션하려면 별도의 마이그레이션 스크립트를 작성해야 합니다.