Initial commit: Organized PTC project structure with .gitignore and README

2026-03-23 14:44:39 +09:00
commit 35ababe236
21 changed files with 8921 additions and 0 deletions
--- a/db/README.md
+++ b/db/README.md
@@ -0,0 +1,324 @@
+# 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 확인 방법"으로 이해하면 맞습니다
+- 실제 엑셀 적재 절차는 다음 단계에서 추가 구현이 필요합니다