[python/development] project xelloss m2 개발

Project Xelloss M2 — 다국가·다언어 매뉴얼 Validation 및 배포 자동화 Desktop Application

Project Xelloss M2는 기존에 사용하던 업무용 매뉴얼 검수 프로그램을 현재 업무 환경에 맞게 전면 리뉴얼한 Python 기반 Desktop Validation Application이다.

기존 검사 기능을 단순 이전하는 것이 아니라 국가·언어별 데이터의 병렬 검사, XML·HTML·File System을 연계한 Validation, 검사 결과 및 진행 상태 관리, 실행 파일 패키징과 자동 업데이트까지 전체 구조를 다시 설계했다.

개발 기간 : 2024.11.27 ~ 2025.03.27

Project Summary

프로젝트 배경

Xelloss M2는 약 4년 전에 인수인계 받아 유지보수하던 기존 업무용 검수 프로그램을 기반으로 시작했다.

기존 프로그램은 오래된 Python 개발 환경과 PyQt5 기반 UI를 사용하고 있었으며, 업무 범위가 확대되면서 단일 대상 중심의 검사 방식만으로는 여러 국가와 언어의 데이터를 효율적으로 처리하기 어려워졌다.

이에 기존 코드를 단순히 최신 환경에서 실행되도록 변경하는 수준이 아니라, 실제 운영 과정에서 누적된 요구사항을 다시 분석해 Application 구조, 검사 항목, 병렬 처리, UI, Logging, 배포 및 업데이트 방식까지 함께 개선하는 방향으로 리뉴얼했다.

기존 Xelloss
 ├─ 오래된 Python 환경
 ├─ PyQt5 기반 UI
 ├─ 단일 검사 중심
 ├─ 검사 항목 및 예외 처리 제한
 └─ 신규 Version 수동 재배포
          ↓
       전면 개선
          ↓
Xelloss M2
 ├─ Python 실행 환경 Upgrade
 ├─ CustomTkinter 기반 UI
 ├─ 검사 기능 Module 분리
 ├─ 국가 / 언어별 병렬 검사
 ├─ XML / HTML / 실제 파일 연계 Validation
 ├─ Progress / Error / Log 관리
 └─ EXE 자동 업데이트

개발 전 구조 설계

리뉴얼을 시작하면서 기존 프로그램에 기능을 계속 추가하는 방식보다, 검사 기능과 공통 기능을 역할별로 나누는 방향으로 Application 구조를 먼저 정리했다.

Validation 기능은 검사 종류별 Checker로 나누고, 언어별 병렬 처리, Database 생성, Progress 관리, File 처리, UI, Update 기능은 별도의 Module과 Utility로 분리하는 구조를 설계했다.

Application
 ├─ main
 │
 ├─ validation_manager
 │    ├─ f1_checker
 │    ├─ link_checker
 │    ├─ image_checker
 │    ├─ heading1_checker
 │    └─ filename_checker
 │
 ├─ db_manager
 │    └─ Search DB 생성
 │
 ├─ thread_utils
 │    └─ 언어별 병렬 검사
 │
 ├─ progress_utils
 │    └─ 검사 진행 상태 관리
 │
 ├─ update_manager
 │    └─ Version / Auto Update 관리
 │
 ├─ file_utils
 ├─ ui_utils
 ├─ update_utils
 └─ log
      ├─ 검사별 결과 Log
      └─ Update Log

검사 기능과 공통 기능을 분리함으로써 특정 검사 규칙을 수정하거나 새로운 검사 항목을 추가할 때 다른 기능에 미치는 영향을 줄이고, 병렬 처리와 UI 상태 관리도 각각 독립적인 역할로 다룰 수 있도록 했다.

개발 목표

검수 대상은 실제 납품 폴더에 포함된 HTML, XML, Image, CSS, JavaScript, Font 등 다양한 파일이기 때문에 Web Application보다 사용자의 작업 폴더에 직접 접근할 수 있는 Desktop Application 형태로 개발했다.

리뉴얼에서 중요하게 잡은 목표는 단순히 오류를 더 많이 찾는 것이 아니라, 여러 언어의 대량 데이터를 빠르게 검사하면서 사용자가 오류의 위치와 원인을 쉽게 확인하고 결과를 업무에 활용할 수 있도록 만드는 것이었다.

• 단일 언어와 다국가·다언어 데이터를 동일한 프로그램에서 처리
• 언어별 병렬 처리를 통한 검사 시간 단축
• HTML뿐 아니라 XML 데이터와 실제 File System까지 연계해 검사
• 검사 진행 상태 및 오류 내용을 UI에서 즉시 확인
• 검사 종류별 결과와 Log 분리
• 최근 검사 경로 등 반복 사용 Workflow 개선
• 새 Version 배포 시 사용자의 수동 설치 과정 최소화

개발 환경

검수 프로그램은 실제 폴더와 파일에 직접 접근해야 하기 때문에 Python Desktop Application으로 구성했다.

초기에는 기본 Tkinter를 검토했지만 UI 구성과 디자인 자유도를 고려해 CustomTkinter로 변경했다. 기존 Version에서 사용하던 PyQt5와 달리 UI와 기능을 Python 코드 안에서 직접 관리할 수 있도록 구성했다.

가상환경 구성

D:\Python\python311\python.exe -m venv vMobis
D:\Develop\D_mobis\vMobis\Scripts\activate

주요 Library

pip install customtkinter
pip install pillow requests
pip install pyinstaller==6.11.1

pip install pandas
pip install openpyxl

pip install beautifulsoup4
pip install lxml

pip install addict
pip install netifaces
pip install pefile
pip install python-dateutil
pip install psutil

pip install auto-py-to-exe

# 전체 환경 재설치
pip install -r requirements.txt

HTML 분석에는 BeautifulSoup, XML 처리에는 lxml을 사용했으며, Excel 데이터를 활용하는 기능에는 Pandas와 openpyxl을 사용했다.

배포 및 자동 업데이트 과정에서는 PyInstaller, requests, pefile, psutil 등의 Library를 함께 활용했다.

전체 Validation 흐름

사용자가 작업 폴더를 선택하면 바로 개별 HTML 검사부터 시작하는 것이 아니라, 먼저 작업 환경과 기본 데이터가 유효한지 확인한 뒤 검사에 필요한 데이터를 구성하도록 설계했다.

작업 폴더 선택
      ↓
사전 Validation
 ├─ Template 확인
 ├─ 지역 코드 확인
 ├─ 언어 정보 확인
 ├─ 언어 개수 확인
 ├─ 실행 환경 확인
 └─ 다른 언어 데이터 혼입 여부 확인
      ↓
검사 데이터 구성
 ├─ toc1.html 분석
 ├─ cross2.xml 분석
 └─ Search DB 생성
      ↓
언어별 병렬 Validation
 ├─ 기본 파일 검사
 ├─ Chapter Icon
 ├─ C_Option
 ├─ Cross Reference / C_URL
 ├─ Image / GIF
 ├─ Heading1
 └─ Filename / Extension
      ↓
검사 결과 수집
      ↓
Tab별 상태 표시
      ↓
Progress / Error Message / Log

단일 언어 프로젝트와 여러 언어가 포함된 프로젝트를 모두 처리할 수 있도록 했으며, 지역 코드나 폴더명에 지나치게 의존하던 기존 조건도 실제 업무 데이터에 맞게 개선했다.

검사 데이터 구성

여러 Validation 기능에서 동일한 데이터를 반복적으로 분석하지 않도록, 검사에 필요한 정보를 HTML과 XML에서 먼저 추출해 공통 데이터로 구성했다.

toc1.html 기반 Search DB 생성

toc1.html을 분석해 검사 대상 HTML 파일 목록을 가져오고, 각 문서의 Chapter, Heading, 관련 Text, 본문 정보 등을 정리해 Search DB로 활용하도록 구성했다.

toc1.html
    ↓
HTML File List
    ↓
각 HTML 분석
    ↓
Search Data 구성

{
  toc_id
  chapter
  chapter_order
  title
  title2
  mmi
  body
}

cross2.xml 기반 구조 데이터

cross2.xml에서는 Chapter Order, Icon, C_Option, Cross Reference 관련 정보를 추출해 HTML 데이터와 비교하는 Validation에 활용했다.

cross2.xml
    ↓
구조 데이터 추출
 ├─ Chapter Order
 ├─ Icon
 ├─ C_Option
 └─ Cross Reference
    ↓
HTML 데이터와 비교
    ↓
업무 규칙 불일치 탐지

주요 Validation 기능

1. 기본 검사

본격적인 검사를 시작하기 전에 Template과 언어 데이터가 올바르게 구성되어 있는지 확인한다.

• 지정된 Template인지 확인
• 지역 코드가 올바른지 확인
• 언어 정보 및 언어 수 확인
• 다른 지역 또는 언어 데이터가 혼입되어 있는지 확인
• 필수 폴더 및 파일 구조 확인

2. 필수 파일 및 HTML 누락 검사

작업에 필요한 필수 파일이 존재하는지 확인하고, 목차 데이터와 실제 파일을 비교해 필요한 HTML 파일이 누락되지 않았는지 검사한다.

3. Chapter Icon 및 GIF 검사

XML과 HTML에서 사용되는 Chapter Icon과 GIF 정보를 추출한 뒤 실제 Image File이 작업 폴더에 존재하는지 확인하도록 기능을 추가했다.

4. C_Option 검사

XML에서 C_Option 데이터를 추출해 지역별 기준 데이터와 비교하고, 필요한 위치에서 C_Option 관련 Text가 올바르게 처리되었는지 확인하도록 구성했다.

5. Cross Reference / Link 구조 검사

단순히 Link가 존재하는지만 확인하는 것이 아니라, HTML 구조와 XML의 Cross Reference 데이터가 업무 규칙에 맞게 연결되어 있는지를 검사하도록 설계했다.

• href 속성이 비어 있는 Link 탐지
• Cross Reference 내부 Anchor 구조 확인
• Link의 부모 요소가 허용된 구조인지 확인
• Cross Reference Text가 XML Key에 존재하는지 비교
• 동일 Reference가 여러 Heading에 존재하는 경우 위치 관계 확인
• C_URL 유형과 값에 대한 구조 Validation

문서 내부의 Text와 Link만 보는 것이 아니라 HTML과 XML의 데이터를 서로 비교해 누락되거나 잘못 연결된 Cross Reference를 탐지하는 것이 핵심이다.

6. Image Validation

HTML 내부의 img 요소와 src 정보를 분석해 Image 경로가 정상적으로 존재하는지 확인하고, 실제 파일이 작업 폴더에 존재하는지도 함께 검사한다.

일반 Image뿐 아니라 GIF, Chapter Icon 등 별도 규칙이 필요한 Image도 검사 대상으로 확대했다.

7. Heading1 검사

각 HTML 문서에 필요한 h1 요소가 존재하는지 확인하고, 요소가 있더라도 실제 Text가 비어 있는 경우 오류로 처리하도록 했다.

8. 파일명 및 확장자 검사

파일명이 업무 규칙에 맞는지 확인하고 허용되지 않은 확장자가 포함되어 있는지도 검사한다.

Validation
 ├─ Template / Region / Language
 ├─ 필수 File
 ├─ HTML 누락
 ├─ Chapter Icon
 ├─ C_Option
 ├─ Cross Reference
 ├─ C_URL 구조
 ├─ Image src
 ├─ 실제 Image / GIF File
 ├─ Heading1
 ├─ Filename
 └─ Extension

다국가·다언어 병렬 처리

Xelloss M2에서 중요한 개선 사항 중 하나는 언어별 검사 작업을 병렬로 처리하는 구조였다.

여러 국가와 언어가 포함된 프로젝트를 순차적으로 검사하면 대상 언어가 증가할수록 전체 검사 시간이 크게 늘어나기 때문에, 언어 단위로 독립적인 검사 Task를 구성하고 Multi-thread 방식으로 처리하도록 변경했다.

검사 프로젝트
      ↓
언어 목록 구성
      ↓
 ┌────┼────┬────┐
 │    │    │    │
KO   EN   FR   ES ...
 │    │    │    │
Validation Thread
 │    │    │    │
 └────┼────┴────┘
      ↓
검사 결과 수집
      ↓
Tab / Status 통합 표시

검사 데이터와 결과를 언어별로 독립 처리하면서 여러 언어가 포함된 작업에서도 하나의 Application으로 검수를 진행할 수 있도록 했다.

검사 결과와 UI 상태 관리

Validation Tool에서는 오류를 찾는 것만큼 사용자가 현재 상태를 빠르게 이해할 수 있도록 만드는 것이 중요했다.

각 검사 Tab의 Header에 검사 결과에 따른 상태를 표시하고, 화면 하단에는 진행 상황과 오류 메시지를 제공하도록 했다.

검사 시작
    ↓
Tab별 Validation
    ↓
결과 상태 표시
 ├─ 정상
 ├─ 확인 필요
 └─ 오류
    ↓
하단 Progress / Message
    ↓
검사별 Log 저장

검사 결과에 오류가 지나치게 많이 발생하는 경우에는 화면에 모든 결과를 한 번에 출력하지 않고 최대 1,000건까지만 표시한 뒤 이후 결과는 축약하도록 처리해 대량 오류 상황에서의 화면 가독성을 고려했다.

사용성 개선

검사 로직뿐 아니라 실제 업무에서 반복적으로 사용하면서 불편했던 Workflow도 함께 개선했다.

• 최근 검사 경로 저장 및 삭제
• 검사 결과에 따라 Tab Header 상태 변경
• 하단 Progress 및 Error Message 추가
• 검사 결과 Text의 빠른 복사
• 특정 지역 폴더명에 의존하던 검사 조건 개선
• 단일 언어 프로젝트 처리 개선
• HTML 누락 검사 강화
• Chapter Icon 및 GIF 실제 파일 검사 추가
• Cross Reference Key 오류 메시지 개선
• 자동 업데이트

오류를 탐지하는 기능에 그치지 않고 어느 검사에서 문제가 발생했는지, 현재 어디까지 진행됐는지, 결과를 어떻게 다시 사용할 수 있는지까지 고려해 실제 반복 업무에 사용할 수 있는 도구로 개선했다.

가장 어려웠던 부분 — EXE 자동 업데이트

전체 프로젝트에서 가장 많은 시행착오와 개발 시간이 필요했던 기능은 배포된 Desktop Application의 자동 업데이트였다.

Web Application과 달리 EXE 형태로 배포된 프로그램은 실행 파일뿐 아니라 JSON, Image, DLL 등 여러 리소스를 함께 관리해야 하고, 실행 중인 프로그램 자체를 교체해야 하는 문제도 있다.

한 가지 방식을 바로 적용하기보다 실제 배포 환경에서 여러 방법을 직접 구현하고 비교했다.

Application 실행
      ↓
현재 Version 확인
      ↓
신규 Version 존재 여부 확인
   ├─ 없음 → 기존 Version 실행
   │
   └─ 있음
        ↓
     Update Process 실행
        ↓
     기존 Application 종료
        ↓
     신규 Version 반영
        ↓
     최신 Application 실행

최종적으로 Portable EXE 형태를 유지하면서 새로운 Version을 자동으로 적용할 수 있는 구조를 구현했다.

이를 통해 신규 Version이 배포될 때마다 사용자에게 새 실행 파일을 전달하고 직접 다시 설치하도록 요청하는 과정을 줄일 수 있었다.

실행 파일 최적화 — UPX

PyInstaller 기반 Application을 배포하면서 실행 파일의 용량을 줄이기 위해 UPX (Ultimate Packer for eXecutables)도 적용했다.

UPX : https://github.com/upx/upx/releases

Windows 환경 변수에 UPX 실행 경로를 추가하고 정상적으로 실행되는지 확인했다.

upx --version

가상환경에서도 동일하게 사용할 수 있도록 시스템 환경 변수 설정을 추가했다.

Build 과정에 UPX 적용

def compress_with_upx():
    upx_exe = r"D:\Python\upx-5.0.0-win64\upx.exe"

    exe_path = os.path.join(
        dist_folder,
        "Xelloss_M2.exe"
    )

    subprocess.run([
        upx_exe,
        '--best',
        '--lzma',
        '--force',
        exe_path
    ])

    dll_folder = os.path.join(
        dist_folder,
        "_internal"
    )

    subprocess.run([
        upx_exe,
        '--best',
        '--lzma',
        '--force',
        f"{dll_folder}\\*.dll",
        '--exclude=api-ms-*',
        '--exclude=python*.dll'
    ])


compress_with_upx()

후속 검토 항목

Cross Reference와 C_URL 관련 구조 검사는 기존 Link Checker 안에서 구현했으며, 일반 URL을 별도 기준으로 검사하는 독립 URL Checker Tab은 당시 후속 개발 항목으로 남겨두었다.

현재 구현된 범위와 이후 확장할 기능을 구분해 관리하면서 기존 Validation에 영향을 주지 않고 새로운 검사 기능을 추가할 수 있도록 구조를 준비했다.

Project Xelloss M2 결과

Xelloss M2에서는 기존 검수 기능을 유지하면서 실제 운영 과정에서 필요했던 Validation 항목을 추가하고, 여러 국가와 언어의 검사를 병렬로 처리할 수 있도록 구조를 개선했다.

단순히 오류 목록을 출력하는 것에서 그치지 않고 검사 결과에 따른 Tab 상태, 진행 메시지, 오류 내용, 최근 경로, 결과 복사 등 반복적인 업무 사용에 필요한 기능도 함께 개선했다.

또한 가장 큰 과제였던 자동 업데이트 기능을 구현하면서 신규 Version 배포 시 사용자가 매번 실행 파일을 직접 내려받아 교체해야 하는 불편을 줄였다.

프로젝트를 통해 얻은 경험

Xelloss M2는 기존 프로그램을 새로운 Python 환경으로 옮기는 단순 Migration이 아니라, 실제 운영 과정에서 축적된 업무 규칙을 분석하고 이를 검증 가능한 Application 구조로 다시 설계한 프로젝트였다.

HTML이나 XML 파일을 개별적으로 검사하는 것보다 더 어려웠던 부분은 서로 다른 데이터의 관계를 이해하고 이를 하나의 Validation 규칙으로 연결하는 것이었다.

예를 들어 XML의 Cross Reference와 Chapter 정보를 HTML의 Link와 비교하고, HTML의 Image 경로를 실제 File System과 다시 비교하는 것처럼 여러 데이터 소스를 함께 검증해야 실제 업무에서 의미 있는 오류를 찾을 수 있었다.

또한 검사 로직 자체뿐 아니라 대량 데이터를 어떻게 처리할지, 검사 상태를 UI에서 어떻게 전달할지, 검사 기능을 이후 어떻게 추가할지, 배포된 Application을 어떻게 업데이트할지까지 함께 고려해야 했다.

기존 Application 분석
       ↓
업무 Validation 규칙 정리
       ↓
Module Architecture 설계
       ↓
XML / HTML / File 데이터 연결
       ↓
검사 기능별 Checker 구현
       ↓
언어별 병렬 처리
       ↓
Progress / Error / Log 관리
       ↓
Desktop UI 개선
       ↓
EXE Packaging
       ↓
여러 Update 방식 검증
       ↓
Auto Update 구현
       ↓
실제 업무 배포

Project Xelloss M2는 Legacy Application 분석 → 요구사항 및 Validation Rule 정의 → Application Architecture 설계 → XML/HTML/File Validation → 병렬 처리 → Desktop UI → Packaging → 자동 업데이트 → 실제 배포까지 하나의 업무용 Desktop Application을 운영 가능한 형태로 다시 구축한 프로젝트라는 점에서 의미가 있다.

기타 프로젝트 : Project 전체 보기