PTC/db/README.md

# Execution Budget DB

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

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

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

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

## 기준 DB

- PostgreSQL 14 이상
- 스키마명: `budget_app`
- 파일: [`schema.sql`](/home/hyein/project/db/schema.sql)
- 샘플 데이터: [`seed.sql`](/home/hyein/project/db/seed.sql)
- 조회 예제: [`sample_queries.sql`](/home/hyein/project/db/sample_queries.sql)
- 실제 엑셀 파싱: [`import_ptc_xlsx.py`](/home/hyein/project/db/import_ptc_xlsx.py)
- 실제 엑셀 검증 쿼리: [`staging_queries.sql`](/home/hyein/project/db/staging_queries.sql)
- 로컬 실행: [`docker-compose.yml`](/home/hyein/project/docker-compose.yml)

## 현재 상태

- [`schema.sql`](/home/hyein/project/db/schema.sql): 실행예산 분석용 기본 스키마
- [`seed.sql`](/home/hyein/project/db/seed.sql): 브라우저에서 구조를 바로 확인하기 위한 예시 데이터
- [`PTC(2023-2026.02).xlsx`](/home/hyein/project/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`](/home/hyein/project/PTC(2023-2026.02).xlsx) 확인 결과 헤더는 아래 14개입니다.

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

파일 특성 요약:

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

주의할 점:

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

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

## 실제 엑셀 적재 방법

### 1. 엑셀을 CSV로 변환

프로젝트 루트에서:

```bash
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 컨테이너 안으로 복사

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

### 3. staging 테이블로 적재

```bash
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. 적재 결과 확인

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

접속 후:

```sql
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`](/home/hyein/project/db/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로 먼저 보고 싶으면 아래처럼 접속해서 확인할 수 있습니다.

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

접속 후:

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

또는 [`sample_queries.sql`](/home/hyein/project/db/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`](/home/hyein/project/PTC(2023-2026.02).xlsx)
- 현재 README의 실행 방법은 "데모 DB 확인 방법"으로 이해하면 맞습니다
- 실제 엑셀 적재 절차는 다음 단계에서 추가 구현이 필요합니다