11 KiB
11 KiB
PTC Manage (manage 브랜치)
PTC 실행 원장 기반의 사내 프로젝트 관리/원가 분석 웹앱입니다.
manage 브랜치는 프로젝트 관리 + 프로젝트 생애주기 원가 + 관리 대시보드 운영 기능을 중심으로 유지됩니다.
- 기본 실행 주소:
http://localhost:4000/PTC/ - 관리 실험 화면:
http://localhost:4000/PTC-lab-manage/ - 단일 Python 서버가 API + 프론트를 함께 제공합니다.
1. 현재 브랜치 핵심 기능
- 프로젝트 마스터 관리
- 프로젝트명/구분/공법/기간/메모 수정
- 프로젝트 간 연관 코드 관리
- 프로젝트 관리 탭에서는 거래내역 표를 제거하고, 거래는
거래내역확인탭에서만 조회
- 프로젝트 생애주기 원가
- 연관 프로젝트(영업/설계/시공) 흐름을 3열 고정 레이아웃으로 조회
- 영업/설계 카드 클릭 시 배분 팝업에서
해당프로젝트/총프로젝트저장 - 배분값 저장/삭제 후 반영 매출 자동 재계산
- 시공 컬럼에 공정률 표시(숫자 강조)
- 영업/설계 연결 프로젝트가 없을 때 톤다운된 비어있음 상태 표시
- 계정별 금액/항목 목록을 박스형 카드가 아닌 라인형 리스트로 표시
- 프로젝트 생애주기 원가 분해
시공비/인건비/관리비상세 모달 제공- 인건비/관리비에
직접분/공통배분분분리 표시 - 현재는 연결 프로젝트 비용을 직접분으로 처리(공통배분분은 향후 공통배분 기능 추가 시 반영)
- 배분 로직
- 예: 설계 프로젝트에
1/3저장 시, 생애주기 화면 반영금액은 해당 프로젝트 금액의1/3 - 저장은
project_lifecycle_allocations테이블에 영구 반영
- 예: 설계 프로젝트에
- 계정 표시 정책(프로젝트 화면)
기타 수지/자산계정(예:194 전도금)은 프로젝트/생애주기 집계 및 상세에서 숨김
- 계정 재매핑
- 프로젝트별 계정코드 재분류(허용 계정 범위 검증 포함)
2. 기술 스택
- Backend: Python 3 표준 라이브러리 (
http.server,sqlite3등) - DB: SQLite (
db/ptc_local.sqlite3) - Frontend: 정적 HTML 대시보드 페이지 (
PTC/*.html) - 운영 보조: Windows 배치 스크립트 (
windows/*.bat)
별도 백엔드 프레임워크(FastAPI/Flask) 없이 단일 서버 스크립트로 동작합니다.
3. 디렉터리 구조
/home/hyein/project
├─ PTC/
│ ├─ index.html # 메인 화면
│ ├─ dashboard_preview.html # 실험 대시보드
│ ├─ admin_dashboard.html # 관리자 화면
│ └─ management_dashboard_preview.html # 관리/생애주기 핵심 화면
├─ server/
│ ├─ ptc_api_server.py # API + 프론트 서빙 서버
│ └─ ptc_source_path.txt # 사용할 원본 xlsx 경로 설정값
├─ db/
│ ├─ ptc_local.sqlite3 # 로컬 DB 파일
│ ├─ import_ptc_xlsx.py # xlsx -> staging csv 변환 스크립트
│ ├─ schema.sql / seed.sql # (별도 Postgres 실험용)
│ └─ README.md
├─ windows/
│ ├─ start_ptc_share.bat # 사내 공유 실행
│ ├─ set_ptc_source.bat # 원본 xlsx 선택/저장
│ └─ README.txt
└─ README.md
4. 빠른 시작
4.1 요구사항
- Python 3.10+ 권장
- 로컬 파일 접근 권한
- 원본 엑셀 파일 존재
- 기본:
PTC 입출금내역(2015~).xlsx
- 기본:
4.2 서버 실행
프로젝트 루트에서:
python3 server/ptc_api_server.py
실행 후:
- API Health:
http://localhost:4000/api/health - 메인 UI:
http://localhost:4000/PTC/ - 관리 UI:
http://localhost:4000/PTC-lab-manage/
5. 데이터 로딩 방식
서버 시작 시 init_db()가 아래 순서로 동작합니다.
- SQLite 스키마/인덱스/마이그레이션 보정
- 원본 xlsx 경로 확인
server/ptc_source_path.txt값이 있으면 우선 사용- 없으면 기본 파일(
PTC 입출금내역(2015~).xlsx) 사용
xlsx_source_signature(경로+mtime)비교- 원본이 바뀐 경우
ptc_transactions전체 재적재 project_master초기값(프로젝트코드 기준) 자동 보강
즉, 원본 파일 갱신 시 서버 재시작만으로 로컬 DB가 다시 동기화됩니다.
6. 화면별 URL
/PTC/: 메인 대시보드/PTC-lab/: 대시보드 실험 화면/PTC-admin/: 관리자 화면/PTC-lab-manage/: 프로젝트 관리/생애주기 원가 화면
7. 프로젝트 생애주기 배분(중요)
7.1 사용 방법
/PTC-lab-manage/접속- 대상 시공 프로젝트 선택
관련 프로젝트 흐름에서 영업/설계 카드 클릭- 팝업에서
해당 프로젝트수와총 프로젝트수입력- 예:
1 / 3
- 예:
- 저장 시 반영금액 = 원금액 ×
(1/3)
7.2 저장/삭제 API
- 저장:
POST /api/lifecycle-allocation/upsert - 삭제:
POST /api/lifecycle-allocation/delete
저장 데이터는 project_lifecycle_allocations 테이블에 유지되며, 페이지 재진입 후에도 반영됩니다.
7.3 관련 프로젝트 흐름(영업/설계/시공)
- 컬럼은 항상
영업/설계/시공3개를 고정 표시합니다. - 영업/설계가 없으면
연결 프로젝트 없음을 톤다운 텍스트로 보여줍니다. - 시공 컬럼은 현재 프로젝트 기준으로 표시되며, 공정률(
x.x%)이 헤더에 노출됩니다. - 영업/설계만 배분 팝업 클릭 대상이고, 시공은 읽기 전용입니다.
7.4 프로젝트 생애주기 원가(분해 기준)
- 상단 요약:
총 입금 / 총 지출 / 총 수익 / 수익률. - 하단 분해:
시공비 / 인건비 / 관리비클릭 시 상세 모달. - 인건비/관리비 상세는
직접분 / 공통배분분을 함께 보여줍니다. - 현재 구현 기준:
- 연결 프로젝트에 귀속된 비용은 직접분으로 집계
- 공통배분분은 0원(향후 공통비 배분 로직 추가 예정)
8. 프로젝트 화면 숨김 계정 정책
프로젝트/생애주기 관점에서는 특정 계정을 집계에서 완전히 제외합니다.
- 기준 상수:
PROJECT_VIEW_EXCLUDED_ACCOUNT_CODES - 포함 예시:
194(전도금),191(출자금),259(선수금),901~904,961,962,999등
의도:
- 프로젝트 실적(입금/지출/수익) 화면에 불필요한 자산/영업외 항목 노출 방지
- 카드 합계와 상세 내역의 해석 일관성 유지
9. 주요 DB 테이블
ptc_transactions- 원본 거래 행(정규화 포함) 저장
project_master- 프로젝트 마스터(명칭/구분/공법/기간/메모)
project_relations- 프로젝트 간 연관 관계
project_lifecycle_allocations- 생애주기 배분값(
분자/분모) 저장
- 생애주기 배분값(
project_budget_lines,project_budget_account_lines- 프로젝트 예산 라인
project_progress,project_pile_progress_entries- 공정/말뚝 진행 데이터
meta- 원본 시그니처 등 시스템 메타
10. 주요 API
10.1 GET
GET /api/health: 서버/적재건수GET /api/summary: 전체 요약GET /api/project-types: 프로젝트 구분 목록GET /api/projects: 프로젝트 목록/검색GET /api/project-detail: 프로젝트 상세GET /api/project-budget-actual-detail: 예산 vs 실적 상세GET /api/lifecycle-account-detail: 생애주기 계정 상세GET /api/management-overview: 관리 화면 요약GET /api/management-overview-accounts: 관리 화면 계정집계GET /api/transactions: 원장 행 미리보기
GET /api/project-detail 응답의 related_projects 항목에는 시공 공정률(progress_rate)이 포함됩니다.
10.2 POST
POST /api/project-master/upsert: 프로젝트 마스터 저장POST /api/lifecycle-allocation/upsert: 생애주기 배분 저장POST /api/lifecycle-allocation/delete: 생애주기 배분 삭제POST /api/project-master/batch-update-method: 공법 일괄 업데이트POST /api/project-account-remap: 프로젝트 계정 재매핑POST /api/project-account-remap-rows: 행 단위 재매핑POST /api/project-budget/upsert: 프로젝트 예산 저장POST /api/project-pile-progress/upsert: 말뚝 진행 저장
11. 운영 스크립트 (Windows)
windows/README.txt 기준 요약:
set_ptc_source.bat: 사용할 원본.xlsx선택 + 서버 재시작start_ptc_share.bat: WSL 서버 시작/방화벽/공유 주소 안내check_ptc_share.bat: 공유 상태 확인stop_ptc_share.bat: 공유 중지install_ptc_share_autostart.bat: 로그인 시 자동 실행 등록
12. 트러블슈팅
12.1 화면에 "PTC 화면을 준비하는 중입니다"만 보일 때
- 프론트 스크립트 에러 가능성이 큽니다.
- 최근 이슈 예: nullish 연산자(
??) + 논리연산자 혼용 시 괄호 누락 - 대응:
- 브라우저 새로고침(강력 새로고침)
- 서버 재시작
- 콘솔 에러 라인 확인 후
PTC/management_dashboard_preview.html수정
12.2 배분값 저장 후 다시 1/1로 보일 때
- 저장 API 호출 실패 또는 validation 실패 가능성
- 확인:
allocation_numerator <= allocation_denominatorallocation_denominator > 0base_project_code,source_project_code누락 여부
12.3 카드 금액과 상세 내역이 다르게 느껴질 때
- 프로젝트 화면에서는 숨김 계정 정책이 적용됩니다.
기타 수지/자산계정은 의도적으로 상세/집계에서 제외됩니다.
12.4 코드 수정 후 화면이 이전 동작으로 보일 때
- 서버 프로세스가 이전 코드를 계속 실행 중일 수 있습니다.
server/ptc_api_server.py수정 후에는 서버를 재시작해 최신 로직(배분/공정률/직접분-공통배분분 집계)이 반영되었는지 확인하세요.
13. 개발 시 참고
- 현재 서버는 단일 파일(
server/ptc_api_server.py) 중심 구조입니다. - 스키마 변경 시
init_db()의pragma table_info기반 보정 로직을 같이 업데이트하세요. - UI 변경 시 관리 화면 파일:
PTC/management_dashboard_preview.html
14. 커밋/브랜치 운영 권장
- 운영 브랜치:
manage - 기능 단위로 커밋 분리
- 예:
feat(lifecycle): ...,fix(project-view): ...
- 예:
- 데이터 파일(
.xlsx,.sqlite3)은 가급적 직접 커밋하지 않고 경로/절차 중심으로 관리
문의/개선 시에는 **재현 경로(화면 URL + 프로젝트코드 + 계정코드 + 날짜 범위)**를 함께 남기면 원인 분석이 훨씬 빨라집니다.