228 lines
8.6 KiB
Markdown
228 lines
8.6 KiB
Markdown
# PTC Manage (manage 브랜치)
|
||
|
||
PTC 실행 원장 기반의 사내 프로젝트 관리/원가 분석 웹앱입니다.
|
||
`manage` 브랜치는 **프로젝트 관리 + 프로젝트 생애주기 원가 + 관리 대시보드** 운영 기능을 중심으로 유지됩니다.
|
||
|
||
- 기본 실행 주소: `http://localhost:4000/PTC/`
|
||
- 관리 실험 화면: `http://localhost:4000/PTC-lab-manage/`
|
||
- 단일 Python 서버가 API + 프론트를 함께 제공합니다.
|
||
|
||
## 1. 현재 브랜치 핵심 기능
|
||
|
||
- 프로젝트 마스터 관리
|
||
- 프로젝트명/구분/공법/기간/메모 수정
|
||
- 프로젝트 간 연관 코드 관리
|
||
- 프로젝트 생애주기 원가
|
||
- 연관 프로젝트(영업/설계/시공) 흐름 카드 조회
|
||
- 영업/설계 카드 클릭 시 배분 팝업에서 `해당프로젝트/총프로젝트` 저장
|
||
- 배분값 저장/삭제 후 반영 매출 자동 재계산
|
||
- 배분 로직
|
||
- 예: 설계 프로젝트에 `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. 디렉터리 구조
|
||
|
||
```text
|
||
/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 서버 실행
|
||
|
||
프로젝트 루트에서:
|
||
|
||
```bash
|
||
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()`가 아래 순서로 동작합니다.
|
||
|
||
1. SQLite 스키마/인덱스/마이그레이션 보정
|
||
2. 원본 xlsx 경로 확인
|
||
- `server/ptc_source_path.txt` 값이 있으면 우선 사용
|
||
- 없으면 기본 파일(`PTC 입출금내역(2015~).xlsx`) 사용
|
||
3. `xlsx_source_signature(경로+mtime)` 비교
|
||
4. 원본이 바뀐 경우 `ptc_transactions` 전체 재적재
|
||
5. `project_master` 초기값(프로젝트코드 기준) 자동 보강
|
||
|
||
즉, 원본 파일 갱신 시 서버 재시작만으로 로컬 DB가 다시 동기화됩니다.
|
||
|
||
## 6. 화면별 URL
|
||
|
||
- `/PTC/` : 메인 대시보드
|
||
- `/PTC-lab/` : 대시보드 실험 화면
|
||
- `/PTC-admin/` : 관리자 화면
|
||
- `/PTC-lab-manage/` : 프로젝트 관리/생애주기 원가 화면
|
||
|
||
## 7. 프로젝트 생애주기 배분(중요)
|
||
|
||
### 7.1 사용 방법
|
||
|
||
1. `/PTC-lab-manage/` 접속
|
||
2. 대상 시공 프로젝트 선택
|
||
3. `관련 프로젝트 흐름`에서 영업/설계 카드 클릭
|
||
4. 팝업에서 `해당 프로젝트수`와 `총 프로젝트수` 입력
|
||
- 예: `1 / 3`
|
||
5. 저장 시 반영금액 = 원금액 × `(1/3)`
|
||
|
||
### 7.2 저장/삭제 API
|
||
|
||
- 저장: `POST /api/lifecycle-allocation/upsert`
|
||
- 삭제: `POST /api/lifecycle-allocation/delete`
|
||
|
||
저장 데이터는 `project_lifecycle_allocations` 테이블에 유지되며, 페이지 재진입 후에도 반영됩니다.
|
||
|
||
## 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` : 원장 행 미리보기
|
||
|
||
### 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 연산자(`??`) + 논리연산자 혼용 시 괄호 누락
|
||
- 대응:
|
||
1. 브라우저 새로고침(강력 새로고침)
|
||
2. 서버 재시작
|
||
3. 콘솔 에러 라인 확인 후 `PTC/management_dashboard_preview.html` 수정
|
||
|
||
### 12.2 배분값 저장 후 다시 1/1로 보일 때
|
||
|
||
- 저장 API 호출 실패 또는 validation 실패 가능성
|
||
- 확인:
|
||
- `allocation_numerator <= allocation_denominator`
|
||
- `allocation_denominator > 0`
|
||
- `base_project_code`, `source_project_code` 누락 여부
|
||
|
||
### 12.3 카드 금액과 상세 내역이 다르게 느껴질 때
|
||
|
||
- 프로젝트 화면에서는 숨김 계정 정책이 적용됩니다.
|
||
- `기타 수지/자산` 계정은 의도적으로 상세/집계에서 제외됩니다.
|
||
|
||
## 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 + 프로젝트코드 + 계정코드 + 날짜 범위)**를 함께 남기면 원인 분석이 훨씬 빨라집니다.
|