1. 해결하려는 업무문제

• 5개 이상 해외 현장(Peaking Unit, Rumah, Nairyah, PP12, Turkistan)의 커미셔닝 인력 배치 현황이 프로젝트별 개별 엑셀로 관리되어, 전사 차원에서 "지금 KR/GE 인력이 어디에 몇 명, 언제 투입 예정인지"를 한눈에 파악하기 어려움
• 담당자가 바뀌거나 파일이 이메일·공유폴더로 흩어지면서 어느 버전이 최신인지 혼선이 발생하기 쉬움
• 조직도·마일스톤·인력 배치 현황을 보려면 매번 엑셀을 열고 수작업으로 보고자료를 다시 만들어야 함
• 사내 보안 정책상 엑셀 파일 자체의 웹 업로드가 차단되어 있어, 일반적인 방식의 웹 대시보드 구축이 불가능했던 상황
• 단기 출장(1개월 미만)과 장기 파견이 구분 없이 섞여 있어 인원수 집계에 혼선
• 인력 한두 명만 바뀌어도 엑셀 전체를 열어 수정하고 다시 업로드해야 해서, 사소한 변경에도 작업 부담이 컸음

2. 해결방안 / 업무 적용 시나리오

• 기존에 쓰던 엑셀 양식을 그대로 유지 (사용자 워크플로우 변경 없음) — 담당자는 늘 하던 대로 엑셀만 채우면 됨
• 그 엑셀을 대시보드에 업로드만 하면 조직도·월별 투입현황 차트·마일스톤 타임라인·KPI가 자동으로 갱신
• 링크 하나로 사내 누구나 실시간 열람 가능 — PIN을 가진 담당자만 업데이트 권한
• 적용 시나리오: 현장 담당자가 인력 변경사항을 반영한 엑셀을 업로드 → 그 즉시 서버에 반영 → 본사 담당자·경영진이 같은 링크에서 새로고침만 눌러 최신 배치 현황 확인 → 이메일로 파일을 주고받거나 별도 보고자료를 만들 필요 없음
• 출장자와 파견 인력을 구조적으로 분리해서 관리, 주간/월간 단위로 "이번 주 현장에 갈 사람" 명단까지 바로 확인 가능
• 필요 시 현재 시스템 데이터를 다시 엑셀로 추출해 오프라인 보고·타 시스템 연동에도 활용 가능
• 신규: 인력 1~2명만 추가/삭제하면 되는 경우, 엑셀을 열 필요 없이 조직도 화면에서 클릭 몇 번으로 바로 처리 — 삭제는 확인 팝업 + 관리자 PIN, 추가는 확인 팝업만 거쳐 즉시 반영

3. AI 활용방법

• 요구사항을 대화로 설명하면 AI가 이를 구조화된 설계 명세서로 정리 → 승인 후 구현 → 검증하는 사이클을 반복하며 전 과정 진행
• 기존에 존재하던 레거시 Excel 변환 스크립트(update_data.py)를 AI가 직접 분석해서, 처음부터 새로 만들지 않고 기존 로직을 최대한 재사용하며 확장
• 사내 보안 정책으로 업로드가 막혔을 때, AI가 원인을 진단(웹 트래픽 정책이 xlsx 파일 자체를 차단)하고 브라우저 안에서 변환을 마친 뒤 JSON만 전송하는 우회 아키텍처를 직접 설계·구현
• 신규 기능(출장자 관리, 대량 Excel 추출, 주간/월간 현황 패널) 요청 시, 실 서비스에 반영하기 전 격리된 복제 환경에서 실제 데이터로 자동 테스트(파일 파싱·왕복 검증·화면 렌더링)를 수행한 뒤에만 실제 폴더에 반영
• 발생한 버그(팝업이 안 닫힘, 날짜가 하루씩 밀림, 실행 파일이 안 열림 등)를 AI가 직접 재현 스크립트를 만들어 근본 원인을 추적하고 수정
• 신규: 조직도 인라인 편집 기능은 "설계 → 예상 문제점 검토 → 해결방안까지 포함한 재설계"를 두 차례 반복한 뒤에만 구현에 착수 — 동시편집·삭제 시 하위조직 처리·PIN 마찰 같은 이슈를 코드 작성 전에 먼저 식별하고 해결책을 못박음
• 구현 후에는 AI가 직접 서버를 띄우고 실제 브라우저로 편집 버튼을 클릭하며 종단간 검증 — 그 과정에서 실제 버그 3건(아래 11번 항목 BUG-06~08)을 발견해 그 자리에서 원인 추적 후 수정, 테스트로 변경했던 데이터는 원상 복구
• 이 설계 문서 자체도 매 단계마다 AI가 최신 상태로 정리해 축적 — 이번 개정판부터는 14번 항목(개정 이력)을 두어 앞으로도 계속 이어서 관리

4. 기대효과 / 정량효과

• 인력 현황 갱신 반영 시간: 기존 방식(파일 공유 → 수작업 취합) 대비 대폭 단축 — 업로드 후 수 초 내 전사 반영
• 보고자료 재작성 공수 절감 — 별도 보고서 없이 대시보드 링크 공유로 대체
• 데이터 버전 불일치 리스크 제거 — 단일 데이터(data.json) 기준으로 항상 최신 상태 하나만 존재
• 확장성 — 신규 현장·프로젝트 추가 시 코드 수정 없이 엑셀 업로드만으로 새 탭 자동 생성, 추가 개발 비용 사실상 0
• 정확도 향상 — 자동 검증 규칙(중복 ID, 필수 데이터 누락, 30일 이상 출장 등)으로 수작업 대비 입력 오류 조기 발견
• 인력 1~2명 변경 시 "엑셀 열기 → 수정 → 저장 → 재업로드" 왕복 과정을 생략 — 조직도 화면에서 바로 처리

※ 위 수치는 별도 실측(도입 전후 비교) 데이터가 아니라, 프로세스 변화의 방향성에 근거한 추정치입니다. 실 도입 후 정확한 수치 측정이 필요합니다.

5. 차별점 및 실무 적용성

• 다른 사내 시스템 도입과 달리 IT 인프라 투자나 서버 신청 절차 없이 로컬 PC 한 대로 즉시 운영 가능
• 보안 정책 위반이나 예외 승인 요청 없이, 아키텍처 설계만으로 제약을 우회 — 정책 준수와 실용성을 동시에 확보
• 사용자가 기존에 쓰던 엑셀 양식을 그대로 사용 — 별도 교육이나 워크플로우 변경 불필요, 도입 저항 최소화
• 조직도·마일스톤·인력현황을 동시에 아우르는 통합 대시보드는 개별 엑셀 관리 방식으로는 얻기 어려운 시각화
• 이 패턴(기존 엑셀 워크플로우 + 브라우저 내 변환 + 실시간 대시보드)은 인력관리 외에 자재관리·품질검사 현황·공정 진도관리 등 유사한 현장 데이터를 다루는 다른 업무 영역에도 그대로 적용 가능한 재사용 가능한 구조
• 대량 갱신(엑셀 업로드)과 소량 갱신(조직도 클릭 편집)을 용도에 맞게 둘 다 지원 — 상황에 맞는 가장 가벼운 방법을 선택 가능

6. 구현 계획

현재 남은 백로그는 SHEET 15 — 다음 작업 예정 참고. 앞으로의 진행 상황은 SHEET 14 — 개정 이력에 계속 누적 기록합니다.

Doosan Enerbility 현장 커미셔닝 인력 배치 현황을 보여주는 대시보드. 관리자가 프로젝트별 Excel(고정 양식)을 업로드하면 즉시 대시보드에 반영된다. 원래 Flask 백엔드로 시작했으나, 사내 보안 정책이 xlsx 파일의 웹 업로드 자체를 차단한다는 사실이 확인되어 최종적으로 아래 구조로 전환했다.

• 백엔드를 Streamlit으로 전환 (Flask는 더 이상 사용하지 않음, 파일은 남겨둠)
• Excel → JSON 변환을 서버가 아니라 사용자 브라우저 안에서 수행 — 네트워크로는 변환된 JSON만 나가므로 xlsx 업로드 차단 정책에 걸리지 않음
• 반대로 JSON → Excel(추출/다운로드)은 서버(Python)에서 생성 — 다운로드 방향은 업로드 차단 정책과 무관하다고 보고 서버 생성 방식으로 설계
• 사용자 경험은 "그냥 Excel 파일을 업로드/다운로드하는 것"과 동일하게 유지
• 대시보드 화면 자체도 정적 표시가 아니라 Streamlit과 클릭 이벤트를 주고받는 양방향 컴포넌트로 동작 — 조직도에서 바로 인력을 추가/삭제할 수 있는 기반이 됨 (09번 항목)

구성 요소

project: {
  key, id, name, active, display_order, config, gm, pcod,
  stats: { total, named, tbd },
  manpower: [ manpower record, ... ],
  milestones: [ milestone record, ... ],
  business_trips: [ business trip record, ... ]
}
manpower record: {
  id, pid, part, role, name, nat, ps, pe, as_, ae, note, count_yn
}
milestone record: {
  id, phase, name, planned, forecast, actual, status
}
business trip record: {
  id, name, nat, dept, purpose, start, end, note
}

Excel 원본 시트 매핑: 05_BUSINESS_TRIP — Trip_ID, Name, Nationality, Department, Purpose, Trip_Start, Trip_End, Note. 조직도 계층 정보(Parent_Org_ID 등)는 없음 — 출장자는 현장 조직도에 속하지 않는 본사 소속 인원이기 때문.

manpower record의 id(Org_ID)는 <Project_ID>-<4자리 숫자> 형식(예: PU-0313)을 따르며, 조직도 인라인 편집으로 새로 추가되는 인력도 같은 프로젝트 안에서 가장 큰 번호+1로 자동 채번된다 (09번 항목).

흐름

날짜 처리

JSON엔 "2026-12-15" 형태 문자열로 저장되어 있는데, 추출 시 진짜 Excel 날짜 셀로 복원(TBD/빈값은 텍스트 그대로)하여, 재업로드해도 문제없게 함. Python(openpyxl)만 사용한 순수 서버 사이드 왕복이라 브라우저 변환에서 발생했던 부동소수점 오차 문제(11번 항목 참고) 없음 — 실제 재파싱 테스트로 모든 필드 100% 일치 확인.

한계

시트 구조·컬럼·데이터 값은 원본과 완전히 동일하지만, 셀 서식(글꼴/색상/테두리/열너비), 원본에 있었을 수 있는 메모나 수식은 애초에 JSON 변환 단계에서 값만 추출했기 때문에 복원되지 않음 — 기본 스타일의 Excel 파일로 생성됨.

왜 인력(파견) 데이터와 분리했나

02_MANPOWER_ORG는 조직도 한 자리를 차지하는 장기 배치 포지션이 기본 단위인데, 출장자는:

• 한 사람이 같은 현장에 여러 번(예: 2주씩 여러 번) 다녀올 수 있어 "한 사람 = 한 자리" 가정이 안 맞음
• 본사 소속이라 현장 조직도상 자리(Part/Role/상위 리더) 자체가 없음
• 기간이 항상 1개월 미만으로 짧아 장기 파견과 성격이 다름

그래서 완전히 독립된 데이터(business_trips / 05_BUSINESS_TRIP 시트)로 설계했고, 기존 인원수 KPI(예상 투입/현재 근무 인력)에는 포함시키지 않음.

검증 규칙

출장 기간이 30일 이상이면 warning — "파견으로 등록해야 하는 건 아닌지 확인" 안내 (막지는 않음). 실제 50일짜리 테스트 데이터로 정상적으로 경고가 뜨는 것 확인, 3일·5일짜리는 경고 없이 정상 통과하는 것도 확인.

화면 반영

실제 테스트: 이번 주 걸친 출장(진행중), 다음 달 출장(주간·월간 패널 모두 제외), 과거 50일 출장(제외 + 경고)까지 프로젝트 페이지 테이블에서 전부 정확히 표시되는 것을 실제 데이터로 확인함.

배치 순서 (기존 화면 요소는 그대로, 추가만)

1. 예상 투입 인력 KPI
2. 현재 근무 인력 KPI
3. 월별 현장 인력 투입 현황 (기존 차트)
4. 주간 인력 파견 현황 (신규)
5. 월간 투입인력 현황 (신규)
6. 주간 출장 현황 (신규)
7. 월간 출장 현황 (신규)
8. Project Overview 카드
9. 인력 상세 현황 테이블

포함 기준

상태는 오늘 날짜 기준 자동 판정(예정/진행중/종료). 실제 데이터(기존 Turkistan TBD 인원 포함)로 월간 파견 패널에 교차 검증까지 완료.

배경

기존에는 인력을 한두 명만 바꾸려 해도 엑셀 파일을 열어 수정한 뒤 다시 업로드해야 했다. 그 정도 사소한 변경에는 과한 작업이라, 조직도 화면에서 바로 추가/삭제할 수 있게 만들었다.

화면 UI

추가 팝업 입력 항목: 이름(비우면 TBD), 국적(KR/GE), 직책(Engineer/Manager), 파견 시작일, 파견 종료일(비우면 TBD), 비고. 삭제 팝업: "OOO님을 삭제하시겠습니까?" + (세션 최초 1회만) 관리자 PIN.

핵심 아키텍처 결정 — 대시보드를 진짜 양방향 컴포넌트로 전환

기존 대시보드는 st.iframe(완성된_HTML_문자열)로 그냥 정적 화면을 넣는 방식이라, 조직도 안 버튼 클릭을 서버로 전달할 통로가 없었다. Excel 업로드에 쓰던 excel_uploader와 같은 방식 — Streamlit Components 통신 프로토콜(componentReady / setComponentValue / setFrameHeight)을 수동 구현 — 을 대시보드 전체에 적용해 dashboard_view라는 진짜 컴포넌트로 바꿨다.

• 컴포넌트는 최초 1회만 로드되고 이후 화면 갱신은 args로만 전달된다는 Streamlit 제약 때문에, 데이터를 파일에 구워 넣는 대신 매 rerun마다 data(현재 데이터)와 feedback(직전 처리 결과)을 컴포넌트 인자로 전달
• templates/index.html 원본은 그대로 두고, 실행할 때마다 통신 브릿지 스크립트를 덧붙여 components/dashboard_view/index.html을 자동 생성 (원본 템플릿을 고치면 자동으로 반영됨)
• 오프라인 배포용 단일 HTML(manpower_board.html)은 이 브릿지에 응답이 없으므로 편집 버튼이 아예 생성되지 않음 — 배포판엔 편집 UI가 섞여 나가지 않음

삭제 처리 — 하위 인력이 있어도 트리가 안 끊어지는 이유

삭제 대상에 하위 인력이 있으면, 그 하위 인력들의 상위(pid)를 삭제 대상의 상위로 한 칸 끌어올린다(연결 리스트에서 중간 노드를 빼는 것과 같은 원리). 기존 조직도 렌더링 로직은 전혀 손대지 않아도 된다.

동시 편집 안전장치

• 파일 잠금: 프로젝트별로 uploads/.lock_<Project_ID> 락(10초 타임아웃) — 두 명이 같은 프로젝트를 거의 동시에 편집해도 순서대로 처리, 서로 덮어쓰지 않음
• 죽은 락 자동 해제: 세션이 중간에 끊겨 락이 안 풀리는 경우를 대비해, 타임아웃 시 강제로 해제 후 한 번 더 시도
• fresh-read: 락을 잡은 직후 항상 파일을 디스크에서 다시 읽음 — 화면에 떠 있던 오래된 상태가 아니라 최신 상태 기준으로 처리. 삭제 대상이 이미 없으면 "이미 변경된 항목입니다"로 안내하고 화면을 자동 새로고침
• 원자적 쓰기: 임시 파일에 쓴 뒤 교체(os.replace) — 저장 중간에 파일이 깨지는 일을 방지
• 저장 전 무결성 검사: 최상위 노드가 정확히 1개인지, 모든 pid가 실존하는지, 순환 참조가 없는지 확인 후 실패하면 저장 자체를 중단

PIN 및 감사 로그

• 삭제만 관리자 PIN 필요, 추가는 불필요(되돌리기 쉬운 작업이라 마찰 최소화)
• 같은 브라우저 세션에서 PIN을 한 번 맞히면 이후 삭제는 재확인 없이 진행(새로고침/새 세션이면 다시 물어봄)
• 삭제 직전 상태를 uploads/_archive/deleted_log.jsonl에 한 줄씩 남김 — 되돌리기 UI는 없지만 실수했을 때 수동 복구 근거가 됨

실제 검증 내역

구현 후 서버를 직접 띄우고 실제 브라우저로 아래 전부 확인 완료 (테스트에 사용한 데이터는 원상 복구):

• 하위 인력(GE Engineers 그룹)이 있는 Manager 삭제 → 그 하위 인력들이 상위 Leader로 정상 승격되는 것을 화면에서 직접 확인
• 직무 끝단 "+ 인력 추가"로 신규 Engineer 추가 → TBD~TBD 기간으로 정상 반영
• 세션 내 두 번째 삭제부터 PIN을 다시 안 물어보는 것 확인, 새 세션에서는 다시 PIN을 요구하는 것도 확인
• 추가 성공 후 곧바로 삭제 시도 시 PIN을 정상적으로 요구하는지(추가 성공이 PIN 확인으로 잘못 캐싱되지 않는지) 확인 — 최초 구현엔 이 부분에 버그가 있어 발견 즉시 수정(11번 항목 BUG-07)
• 편집 중 인력을 추가/삭제해도 보고 있던 탭과 "편집중" 상태가 그대로 유지되는지 확인 — 최초 구현엔 이 부분도 버그가 있어 수정(11번 항목 BUG-08)

이 문서는 매번 처음부터 다시 쓰지 않고, 여기에 이어서 계속 누적 기록합니다. 새 기능/변경이 생기면 이 표에 한 줄 추가하고 관련 SHEET을 갱신하는 방식입니다.

• 인력 정보 수정 — 지금은 조직도에서 추가/삭제만 가능하고, 이름·기간 등 기존 인력의 값을 바로 고치는 기능은 없음 (현재는 삭제 후 재추가로 우회 필요)
• 실시간 반영 — 조직도 편집은 동시에 해도 안전하지만(잠금 처리), 다른 사람 화면에 편집 결과가 즉시 뜨진 않고 그 사람이 새로고침/재편집할 때 반영됨. 필요하면 실시간 push 방식 검토
• Excel 업로드 동시성 — 조직도 편집엔 파일 잠금을 적용했지만, Excel 업로드 자체엔 아직 적용 안 됨(10번 항목)
• 삭제 되돌리기 UI — 지금은 감사 로그 파일만 남고, 화면에서 바로 복구하는 기능은 없음

진행 상황은 이 문서를 계속 갱신하면서 14번 항목(개정 이력)에 이어서 기록합니다.