@dssp/integration-kiscon

KISCON (건설공사대장 통보시스템) 연계용 Things-Factory 통합 패키지.

개요

KISCON 은 공식 외부 API 를 제공하지 않으므로 시공사 회원 계정으로 사이트에 로그인해 화면에서 데이터를 추출한다. 본 패키지는 다음 3 가지 컴포넌트로 구성:

• Connector (kiscon-connector) — KISCON 사이트 URL/로그인 셀렉터를 내부 기본값으로 갖는 KISCON 전용 connector. 사용자는 Connection 생성 시 KISCON 시공사 ID/PW 만 입력. 내부적으로 HeadlessConnector 의 풀·세션· 쿠키 캐시 인프라를 재사용.
• Runner (withManagedPage) — 자원 누수 방지(자식 창 추적 force close, wall-clock 5분 타임아웃) + 프로젝트간 상태 격리(cookies/localStorage/ sessionStorage clear) wrapper. 모든 task 가 이 wrapper 안에서 실행.
• Task — KISCON 화면 navigation 과 데이터 추출만 책임.

제공 Connector

kiscon-connector

Connection params (사용자 입력):

• username (필수) — KISCON 시공사 회원 ID
• password (필수, secret) — 비밀번호
• 기타 셀렉터/path 는 사이트 업데이트 대응용 (고급, 평소 비워둠)

제공 태스크

kiscon-fetch-cnstwk — 건설공사대장 통보 정보 조회 (전체)

검색 기준 (searchBy):

• projectName (default) — KISCON 검색 폼의 '공사명' input 에 query 입력 후 조회. 부분 일치 (LIKE) 로 동작. 일반적인 사용 케이스.
• projectNumber — KISCON 폼은 관리번호 입력 필드를 제공하지 않음. 전체 조회 후 결과 그리드의 "발주자/관리번호" 셀에서 관리번호 텍스트 매칭. 관리번호는 유일값이라 가장 정확.

주소 직접 검색은 KISCON 이 미지원 + 결과 그리드에도 주소 컬럼이 없어 모드를 제공하지 않음. 주소로 시작해야 한다면 외부에서 시공명으로 해소 후 projectName 으로 호출.

KISCON "공사대장 → I.공사개요 / II.계약내용 [도급계약]" 화면에서 다음을 추출:

• 공사개요: projectName (공사명) / projectNumber (관리번호) / projectType (공사유형) / workCategory (공종) / siteAddress (현장소재지)
• 발주자: clientType (구분: 공공/민간) / client (기관명)
• 도급/계약: contractMethod (도급방법) / contractStatus (계약상태) / biddingMethod (입찰방법)
• 계약 [도급계약]: contractDate (계약체결일) / contractStart (착공(예정)일) / contractEnd (준공(예정)일) / contractAmount + contractAmountText (도급금액) / bidRate (낙찰률)
• 관리: buildingPermitNumber (건축허가/신고번호) / buildingPermitDate (건축허가/신고일)

날짜는 모두 YYYY-MM-DD. 도급금액은 원 단위 number + 원본 text 같이 반환.

KPI 등의 후속 계산은 시나리오의 후속 step (script task 등) 에서 위 필드를 조합해 처리한다.

사용 흐름

1. Connection 생성 — type kiscon-connector. params 에 KISCON 시공사 계정 (username/password) 만 입력. endpoint/로그인 셀렉터는 connector 가 자동 주입.
2. Scenario 에 step 추가 — task kiscon-fetch-cnstwk, params 에 searchBy/query.
3. step 결과는 다음 step 의 context.data 로 흘러가 KPI 등재에 사용.

자원 누수 / 상태 격리 (Runner)

모든 task 는 withManagedPage wrapper 안에서 실행되어 다음을 자동 처리:

• 자식 창 추적: browser.on('targetcreated') 로 작업 중 열리는 모든 page 를 추적, finally 에서 강제 close (참조 유실 대비).
• Wall-clock 타임아웃: 5분 초과 시 강제 종료 + 정리. 단일 task hang 으로 인한 풀 점유 방지.
• 상태 격리: task 종료 시점에 page 의 localStorage/sessionStorage/ cookies 를 모두 clear. 다음 task 가 다른 프로젝트 자격증명일 때 교차 오염 방지. (Connection.cookies in-memory 캐시는 영향 없음 — 같은 Connection 의 재호출은 그대로 세션 재사용)

사이트 DOM 검증 필요

KISCON 사이트의 메뉴 라벨, 검색 입력란 id/name, IBSheet 셀 클래스 등은 사이트 마이너 업데이트에 의해 변경될 수 있다. 본 태스크는 다층 fallback 셀렉터를 두었으나, 첫 도입 시 실제 사이트 흐름을 한 번 손으로 따라가며 다음 함수들의 셀렉터 우선순위를 조정해야 한다:

• navigateToCnstwkList — 공사대장 메뉴 진입 경로
• runSearch — 검색 입력란 / 조회 버튼
• openMatchingResultRow — 결과 행 더블클릭 (텍스트 매칭)
• selectPhase — 차수 선택 라디오
• openCnstwkTab — "건설공사대장" 탭 활성화
• extractByLabel — label → value 매핑 (현재는 th/dt/.label 기반 일반화)

약관 / 보안 주의

시공사 계정 자격증명으로 자동 로그인 + 화면 스크래핑은 KISCON 이용약관에 따라 운영자/시공사 사전 협의가 필요하다. 운영 도입 전 법무 검토 권장.

참조 자료

packages/dkpi/docs/KISCON 및 올바로 메뉴 접근 경로정리_0212_김다희.pdf — 실제 사이트의 메뉴 경로와 화면 캡쳐. 본 태스크가 따르는 흐름의 출처. 주요 흐름:

1. 상단 메뉴 "건설공사 대장관리"
2. 좌측 "건설공사 대장 조회 및 변경"
3. 바로가기 영역에서 원도급/하도급 의 [조회/변경통보] 클릭
4. "건설공사 대장 조회" 화면에서 검색 조건 입력 → 조회
5. 결과 그리드 행 더블클릭 → 차수선택 라디오 (1차/2차/3차/4차 변경통보)
6. "건설공사대장" 탭에서 필드 추출