PTC/db

Execution Budget DB

회사 실행예산 분석 시스템을 바로 시작할 수 있도록 만든 PostgreSQL 기본 스키마입니다.

현재 문서에는 2가지 데이터 흐름이 함께 있습니다.

• seed.sql: 구조 확인과 화면 테스트를 위한 샘플 데이터
• PTC(2023-2026.02).xlsx: 실제 적재 대상 원본 거래 데이터

즉, 지금 DB는 "데모용 샘플 데이터"로 바로 볼 수 있고, 실제 운영 데이터는 위 엑셀을 기준으로 다음 단계에서 적재해야 합니다.

기준 DB

• PostgreSQL 14 이상
• 스키마명: budget_app
• 파일: schema.sql
• 샘플 데이터: seed.sql
• 조회 예제: sample_queries.sql
• 실제 엑셀 파싱: import_ptc_xlsx.py
• 실제 엑셀 검증 쿼리: staging_queries.sql
• 로컬 실행: docker-compose.yml

현재 상태

• schema.sql: 실행예산 분석용 기본 스키마
• seed.sql: 브라우저에서 구조를 바로 확인하기 위한 예시 데이터
• PTC(2023-2026.02).xlsx: 실제 회사 거래내역 원본

중요:

• 현재 docker compose up -d로 보이는 데이터는 seed.sql 기준입니다
• 아직 PTC(2023-2026.02).xlsx 내용이 자동으로 DB에 들어가도록 연결되지는 않았습니다
• 이 엑셀은 성격상 예산 파일보다는 실적/거래 원장에 가깝습니다
• 따라서 실제 적재 시에는 먼저 staging 테이블을 만든 뒤 정제해서 actual_transactions로 넣는 방식이 적합합니다
• 현재는 staging_ptc_transactions 테이블과 CSV 생성 스크립트까지 준비된 상태입니다

바로 확인하는 방법

1. 터미널에서 /home/hyein/project로 이동
2. docker compose up -d
3. 브라우저에서 http://localhost:8080 접속
4. 아래 정보로 로그인

• System: PostgreSQL
• Server: postgres
• Username: budget
• Password: budget123
• Database: budgetdb

접속 후 왼쪽에서 budget_app 스키마 안의 테이블과 뷰를 볼 수 있습니다.

처음 데이터가 안 보이면 아래를 확인하세요.

• budget_app.companies
• budget_app.projects
• budget_app.vw_budget_vs_actual_monthly
• budget_app.vw_project_profit_summary
• budget_app.staging_ptc_transactions

기존에 같은 컨테이너를 띄운 적이 있으면 초기 SQL이 다시 실행되지 않을 수 있습니다.

• 초기화가 필요하면 docker compose down -v
• 다시 실행은 docker compose up -d

주의:

• 여기서 보이는 값은 현재 샘플 데이터입니다
• 실제 엑셀 원본과 동일한 숫자가 보이는 단계는 아직 아닙니다

핵심 테이블

• companies: 회사 기본 정보
• fiscal_years: 회계연도
• departments: 부서
• employees: 사용자/담당자
• business_units: 사업부
• clients: 발주처
• vendors: 거래처
• projects: 프로젝트/현장/사업
• account_categories, accounts: 예산/실적 계정 과목
• budget_versions: 예산 버전
• budget_items: 월별 예산 금액
• purchase_requests, purchase_orders: 집행 요청과 발주
• invoices: 매출/매입 세금계산서
• actual_transactions: 실제 실적 데이터
• cashflow_transactions: 현금 유입/유출
• file_import_logs: 엑셀 업로드 이력
• staging_ptc_transactions: PTC(2023-2026.02).xlsx 원본 적재용 임시 테이블

실제 원본 엑셀 헤더

PTC(2023-2026.02).xlsx 확인 결과 헤더는 아래 14개입니다.

• 거래일
• 입/출금
• 계정코드
• 구분
• 부서
• 거래처
• 프로젝트코드
• 프로젝트 구분(안)
• 프로젝트명
• 적요
• 공급가액
• 부가세
• 합계금액
• 비고

파일 특성 요약:

• 데이터 건수: 6,678건
• 기간: 2023-01-10 ~ 2026-02-28
• 출금 중심 거래 데이터이며 일부 입금 포함
• 운영상 actual_transactions 원본으로 보는 것이 가장 적절
• departments, accounts, projects, vendors 마스터 추출에도 활용 가능

주의할 점:

• 프로젝트코드 -> 프로젝트명 일부 불일치 존재
• 프로젝트코드 -> 프로젝트 구분(안) 일부 불일치 존재
• 누락값 소수 존재
• 음수 금액 존재

그래서 이 파일은 바로 본 테이블에 넣기보다 staging -> 정제 -> 최종 적재 흐름이 필요합니다.

실제 엑셀 적재 방법

1. 엑셀을 CSV로 변환

프로젝트 루트에서:

python3 db/import_ptc_xlsx.py \
  --input "PTC(2023-2026.02).xlsx" \
  --output "db/ptc_staging.csv" \
  --batch "ptc_20260323"

생성 결과:

• db/ptc_staging.csv

이 CSV는 budget_app.staging_ptc_transactions에 바로 넣을 수 있는 컬럼 구조입니다.

2. CSV를 Postgres 컨테이너 안으로 복사

docker cp db/ptc_staging.csv budget-postgres:/tmp/ptc_staging.csv

3. staging 테이블로 적재

docker exec -i budget-postgres psql -U budget -d budgetdb -c "
set search_path = budget_app, public;
truncate table staging_ptc_transactions;
copy staging_ptc_transactions (
  import_batch,
  source_file_name,
  source_sheet_name,
  source_row_no,
  transaction_date_raw,
  transaction_date,
  in_out,
  account_code_raw,
  account_name_raw,
  department_name_raw,
  vendor_name_raw,
  project_code_raw,
  project_type_raw,
  project_name_raw,
  description_raw,
  supply_amount_raw,
  vat_amount_raw,
  total_amount_raw,
  remarks_raw,
  supply_amount,
  vat_amount,
  total_amount,
  normalized_transaction_type,
  load_status,
  load_error
) from '/tmp/ptc_staging.csv' with (format csv, header true, encoding 'UTF8');
"

4. 적재 결과 확인

docker exec -it budget-postgres psql -U budget -d budgetdb

접속 후:

set search_path = budget_app, public;
select import_batch, count(*) from staging_ptc_transactions group by import_batch;
select * from staging_ptc_transactions order by source_row_no limit 20;

또는 staging_queries.sql을 기준으로 검증하면 됩니다.

먼저 넣어야 하는 데이터 순서

샘플 데이터 기준:

1. companies
2. fiscal_years
3. departments
4. employees
5. business_units
6. clients, vendors
7. account_categories
8. accounts
9. projects
10. budget_versions
11. budget_items
12. purchase_requests, purchase_orders, invoices
13. actual_transactions

실제 엑셀 적재 기준 권장 순서:

1. 원본 엑셀을 staging_ptc_transactions에 그대로 적재
2. departments 후보 추출
3. accounts 후보 추출
4. projects 후보 추출
5. vendors 후보 추출
6. 코드/명칭 불일치 정제
7. actual_transactions 적재

즉, 실제 운영은 샘플 순서보다 staging 단계가 먼저입니다.

가장 많이 쓰게 될 분석

• 프로젝트별 예산 대비 실적
• 부서별 월 집행률
• 계정과목별 초과 집행
• 프로젝트 손익
• 발주/세금계산서 기준 실적 반영

기본 뷰도 포함돼 있습니다.

• vw_budget_vs_actual_monthly
• vw_project_profit_summary

샘플 데이터 내용

• 회사 1개: 장헌건설
• 회계연도 1개: 2026
• 부서 4개
• 직원 5명
• 사업부 2개
• 발주처 2개
• 거래처 3개
• 프로젝트 2개
• 예산 버전 1개
• 월별 예산 데이터 다수
• 발주 요청/발주/세금계산서/실적 데이터 포함

즉, DB를 올리면 바로 "예산 대비 실적"과 "프로젝트 손익" 화면 구조를 테스트할 수 있습니다.

다만 이 샘플 데이터는 실제 엑셀 원본을 반영한 것이 아니라 데모용 예시입니다.

권장 운영 방식

• 예산은 budget_versions + budget_items로 버전 관리
• 실제 집행은 최종적으로 actual_transactions에 적재
• ERP, 엑셀, 수기 입력이 섞여도 source_type으로 출처 추적
• 프로젝트 단위와 부서 단위를 모두 지원
• 실제 엑셀 원본은 우선 staging 테이블에 저장 후 정제
• 공급가액, 부가세, 합계금액 중 어떤 금액을 실적으로 사용할지 회사 기준 확정 필요
• 입/출금과 계정코드를 함께 써서 revenue/cost/expense 분류 규칙 확정 필요
• staging_ptc_transactions.normalized_transaction_type은 현재 1차 추정값입니다
• 최종 적재 전 계정코드 기준 매핑표를 별도로 확정하는 것이 안전합니다

다음 추천 작업

1. staging_ptc_transactions로 실제 엑셀 적재 실행
2. 계정코드별 revenue/cost/expense 분류표 확정
3. 프로젝트코드/프로젝트명 불일치 정제 규칙 확정
4. staging -> actual_transactions 변환 SQL 작성
5. 필요하면 예산용 별도 엑셀 구조 추가
6. 화면에 필요한 조회 API 설계

쿼리로 확인하는 방법

웹 화면 대신 SQL로 먼저 보고 싶으면 아래처럼 접속해서 확인할 수 있습니다.

docker exec -it budget-postgres psql -U budget -d budgetdb

접속 후:

set search_path = budget_app, public;
select * from companies;
select * from projects;
select * from vw_project_profit_summary;

또는 sample_queries.sql에 준비된 조회문을 사용하면 됩니다.

예산 입력 예시

예를 들어 2026년 3월, 특정 프로젝트의 외주비 예산 5,000,000원을 넣으려면:

• budget_versions에 2026년 예산 버전 생성
• accounts에 외주비 계정 등록
• budget_items에 month_no = 3, planned_amount = 5000000 입력

실적 입력 예시

실제 외주비가 4,300,000원 집행되면:

• actual_transactions에 같은 프로젝트, 같은 계정, 같은 월로 입력
• 이후 vw_budget_vs_actual_monthly에서 차이와 집행률 조회 가능

현재 문서에서 꼭 구분할 점

• seed.sql은 데모 확인용
• 실제 운영 데이터는 PTC(2023-2026.02).xlsx
• 현재 README의 실행 방법은 "데모 DB 확인 방법"으로 이해하면 맞습니다
• 실제 엑셀 적재 절차는 다음 단계에서 추가 구현이 필요합니다