S1 클라우드 API 연동: 레거시 그룹웨어를 위한 실시간 통합 근태 대시보드 개발

최근에 진행했던 S1 클라우드 API 연동 프로젝트가 성공적으로 마무리되어, 그 과정에서 얻은 경험과 기술적인 결정들을 공유하고자 합니다. 이 프로젝트는 단순한 기능 개발을 넘어, 어떻게 구형 시스템과 신형 시스템을 안정적으로 연결하고, 흩어져 있던 데이터를 하나로 모아 가치를 만들어내는가에 대한 고민이 담겨 있습니다.

시작: 문제는 '사옥 이전'으로부터

모든 것은 회사가 신사옥으로 이전하면서 시작되었습니다. 기존에 사용하던 세콤 매니저 시스템이 최신 S1 클라우드 매니저로 전면 교체되었고, 이는 기존 그룹웨어와의 연동 방식이 완전히 달라짐을 의미했습니다. 이전의 연동 코드는 더 이상 무용지물이었습니다.

여기에 또 다른 과제가 있었습니다.

"이왕 새로 만드는 김에, 지금껏 수동으로 취합하던 광주와 천안 공장의 근태 데이터도 이번 기회에 통합할 수 없을까?"

이 한마디에 프로젝트의 목표는 명확해졌습니다.

1. 신규 시스템(S1 Cloud) 연동: 새로운 API 방식에 맞춰 데이터를 가져오는 기능.
2. 데이터 통합: 본사, 광주, 천안 등 전 사업장의 근태 데이터를 단일 시스템으로 통합.
3. 프로세스 자동화: 데이터 동기화, 누락 데이터 보정 등 모든 과정을 자동화.
4. 직관적인 모니터링: 이 모든 과정이 잘 돌아가고 있는지 한눈에 볼 수 있는 관리자용 대시보드 제작.

아키텍처 설계: '문지기'를 세우자

가장 먼저 고민한 것은 '어떻게 안정적으로 서비스를 배포할 것인가'였습니다. 기존 그룹웨어 웹 서버(IIS)가 이미 80 포트를 사용 중이었고, 보안상 새로운 포트를 외부에 여는 것은 부담스러웠습니다.

그래서 **IIS의 리버스 프록시(Reverse Proxy)**를 '문지기'로 활용하는 아키텍처를 채택했습니다.

[사용자/외부] <--> [IIS (gw.vessel21.com)] <--> [Node.js 에이전트 (localhost:3000)]

• Node.js 에이전트: 데이터 동기화, API 제공 등 모든 핵심 로직을 처리하며 localhost:3000에서만 실행됩니다. 외부에서는 직접 접근할 수 없습니다.
• IIS 서버: 기존 웹 서버 역할을 그대로 수행하면서, http://127.0.0.1/S1_agent/ 경로로 들어오는 요청만 정확히 내부의 Node.js 에이전트로 전달합니다.

이 방식은 기존 시스템에 전혀 영향을 주지 않으면서, 보안적으로 안전하게 신규 서비스를 추가할 수 있는 최적의 솔루션이었습니다.

[web.config에 추가된 리버스 프록시 규칙 코드 스니펫 삽입 위치]

Generated xml

<rule name="ReverseProxy_S1_Agent" stopProcessing="true">
    <match url="^S1_agent/(.*)" />
    <action type="Rewrite" url="http://localhost:3000/S1_agent/{R:1}" />
</rule>

핵심 기능 개발기

1. 실시간 통합 대시보드: "지금 무슨 일이 일어나고 있는가?"

관리자가 가장 원하는 것은 '현재 상황'을 직관적으로 보는 것이었습니다. 이를 위해 실시간성을 극대화한 웹 대시보드를 개발했습니다.

[스크린샷 1: 완성된 대시보드 메인 화면]

• 통합 로그 뷰: 광주, 천안, 본사의 출입/출퇴근 로그가 하나의 타임라인에 최신순으로 표시됩니다. 데이터가 많아져도 화면이 깨지지 않도록 로그 창 내부에 자체 스크롤을 적용했습니다.
• 시스템 상태 HUD(Head-Up Display): 헤더에는 서비스 상태, 다음 동기화까지 남은 시간을 보여주는 카운트다운 타이머, 서버 메모리 사용량, 마지막 동기화 시간 등 핵심 지표를 배치하여 시스템의 건강 상태를 한눈에 파악할 수 있게 했습니다.
• 실시간 기술: 서버와의 통신은 **SSE(Server-Sent Events)**를 사용하여, 서버에서 이벤트가 발생할 때마다 UI가 즉시 업데이트되도록 구현했습니다.

2. 똑똑한 자동화: "사람의 실수를 기계가 보완하다"

가장 빈번하게 발생하던 관리 이슈는 '퇴근 카드 미태깅'이었습니다. 이를 해결하기 위해 퇴근 기록 자동 보정 기능을 추가했습니다.

• 작동 방식: 매일 새벽 4시, node-cron 스케줄러가 동작합니다.
• 처리 로직: 전날의 근태 기록 중 퇴근 시간이 비어있는 직원을 모두 찾습니다.
• 보정: 해당 직원의 그날 마지막 출입 기록(예: 건물 최종 퇴문 시간)을 찾아 퇴근 시간으로 자동으로 업데이트합니다.

이 기능 하나로 근태 데이터 누락으로 인한 월말 정산의 번거로움이 크게 줄었습니다.

3. 디버깅의 혁신: "깜깜이 서버는 이제 그만"

백그라운드에서 동작하는 서비스의 가장 큰 어려움은 '문제 추적'입니다. SSH로 접속해서 로그 파일을 열어보는 것은 비효율적입니다. 그래서 웹 대시보드에 실시간 서버 콘솔 모니터링 탭을 만들었습니다.

[스크린샷 2: 서버 실시간 모니터링 탭 화면]

• 실시간 로그 스트리밍: 서버에서 발생하는 모든 로그(console.log, console.error)가 실시간으로 웹 화면에 전송됩니다.
• 동적 로그 필터링: [Agent], [Heartbeat], [Correction Service] 등 로그 앞에 붙은 키워드를 자동으로 인식하여 필터 체크박스를 만들어줍니다. 관리자는 보고 싶은 로그만 선택해서 볼 수 있어, 문제의 원인을 훨씬 빠르게 파악할 수 있습니다.

기술 스택

• Backend: Node.js, Express.js
• Database: MS-SQL
• Process Manager: PM2
• Web Server: IIS (with Application Request Routing)
• Frontend: Vanilla JavaScript (ESM), HTML5, CSS3, SSE

프로젝트를 마치며

이번 프로젝트는 단순히 오래된 시스템을 새로운 시스템으로 교체하는 것을 넘어, 흩어져 있던 데이터를 통합하고 관리 프로세스를 자동화하여 실질적인 업무 효율성 향상을 이뤄냈다는 점에서 큰 의미가 있었습니다. 특히, IIS 리버스 프록시를 활용해 기존 인프라에 미치는 영향을 최소화하면서 안정적인 서비스를 구축한 경험은 앞으로의 다른 프로젝트에도 좋은 밑거름이 될 것 같습니다.

긴 글 읽어주셔서 감사합니다. 프로젝트에 대해 궁금한 점이 있으시면 언제든지 댓글 남겨주세요