From 90042a003a8ed05d9f6554bae9103add6026b82e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=ED=98=9C=EC=9D=B8?= Date: Wed, 22 Apr 2026 17:22:44 +0900 Subject: [PATCH] docs: rewrite manage branch README with detailed setup and lifecycle flow --- README.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 217 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 6a3ef74..44cb539 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,227 @@ -# PTC Project Management System +# PTC Manage (manage 브랜치) -이 프로젝트는 `PTC(2023-2026.02).xlsx` 데이터를 기반으로 한 프로젝트 관리 및 집행 분석 시스템입니다. +PTC 실행 원장 기반의 사내 프로젝트 관리/원가 분석 웹앱입니다. +`manage` 브랜치는 **프로젝트 관리 + 프로젝트 생애주기 원가 + 관리 대시보드** 운영 기능을 중심으로 유지됩니다. -## 주요 구성 +- 기본 실행 주소: `http://localhost:4000/PTC/` +- 관리 실험 화면: `http://localhost:4000/PTC-lab-manage/` +- 단일 Python 서버가 API + 프론트를 함께 제공합니다. -- **Frontend (`/PTC/index.html`)**: React 기반의 단일 페이지 애플리케이션 (SPA)으로 프로젝트 대시보드 및 예산 관리를 담당합니다. -- **Backend (`/server/ptc_api_server.py`)**: Python 기반의 API 서버로 SQLite DB를 통해 데이터를 제공합니다. -- **Database (`/db/`)**: PostgreSQL 스키마 및 로컬 SQLite DB 관련 스크립트가 포함되어 있습니다. -- **Windows Scripts (`/windows/`)**: 로컬 환경에서 서버를 실행하고 공유하기 위한 배치 파일들입니다. +## 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 서버 실행 + +프로젝트 루트에서: -### 1. 서버 실행 ```bash python3 server/ptc_api_server.py ``` -서버는 기본적으로 4000 포트에서 실행되며, API와 프론트엔드(`/PTC/`)를 함께 제공합니다. -### 2. 프론트엔드 접속 -브라우저에서 `http://localhost:4000/PTC/` 로 접속합니다. -필요하면 `index.html`의 `apiBase` 쿼리 파라미터로 API 주소를 덮어쓸 수 있습니다. +실행 후: -## 데이터 업데이트 -`db/import_ptc_xlsx.py` 스크립트를 사용하여 엑셀 데이터를 DB로 변환할 수 있습니다. 자세한 내용은 `db/README.md`를 참조하세요. +- 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 + 프로젝트코드 + 계정코드 + 날짜 범위)**를 함께 남기면 원인 분석이 훨씬 빨라집니다.