Files
dbx-main/docs/ASSET_MODULE.md
T
king bd0c47e6fc feat(asset): add inventory and HWiNFO reports
Requires asset_db initialized with scripts/sql/asset_db_init.sql and ASSET_DB_URL configured before enabling storage.
2026-10-06 02:09:10 +09:00

7.4 KiB

자산관리

진입 /asset/, 권한키 asset. 사무집기와 전산장비를 개별 자산번호로 등록한다. 권한이 있는 사용자는 조회·등록·수정·배정·반납·상태 변경·보고서 다운로드가 가능하다. 관리자 페이지의 기존 권한 토글로 접근을 부여한다.

업무 흐름

  • 현황 카드: 전체·사용 중·사용 가능·수리 중·30일 이내 보증 만료. 분류 구성·최근 활동·보유 구매금액(폐기 제외).
  • 자산대장: 검색/분류/상태/위치/사용자 필터, 정렬, 25개씩 페이지 이동. 엑셀은 현재 필터 전체(최대 10,000개).
  • 상세: 기본 정보/컴퓨터 사양/보고서/활동 이력. 구매일·금액·구매처·보증·부서·위치·메모.
  • 등록: 번호를 비우면 AST-000001 형식으로 자동 발급. 대소문자 무관 고유. 같은 모델도 물건마다 하나씩 등록.
  • 배정: 사용 가능 → 사용 중. 등록된 회사 사용자만 배정. 반납 시 사용자 배정을 해제한다.
  • 수리: 사용 가능 → 수리 중 → 사용 가능. 배정된 자산은 먼저 반납한다.
  • 분실: 사용 가능/사용 중/수리 중 → 분실. 기존 사용자를 유지. 발견 후 사용 가능으로 복구하면 배정 해제.
  • 폐기: 사용 가능/수리 중/분실 → 폐기. 오처리는 사용 가능으로 복구. 이력·보고서는 보존한다.
  • 분실·폐기는 사유 필수. 모든 변경은 처리자·시각·변경 전/후 값을 기록한다.
  • 동시 수정은 행 잠금 + version 검사. 409 발생 시 입력을 보존하고 상세를 다시 확인하도록 안내한다.

HWiNFO XML

HWiNFO → 보고서 저장 → XML. 한 파일에 컴퓨터 한 대, 최대 10 MB. 실제 KING-DESKTOP.XML 구조를 확인했다. 한국어/영어 항목명 및 언어 독립 PropertyType을 사용한다. 실물 보고서는 시리얼·MAC·사용자 정보가 있어 Git에 포함하지 않는다.

  1. 업로드 시 저장하지 않고 핵심 사양을 미리 분석한다.
  2. 이름과 위치를 확인한 뒤 신규 컴퓨터로 등록한다. 제조사와 유효한 시스템 시리얼은 초기값으로 사용한다.
  3. 기존 컴퓨터에서 업로드하면 보고서만 새 버전으로 연결한다. 자산명·구매정보·배정·위치를 덮어쓰지 않는다.
  4. CPU/RAM/GPU/저장장치 요약과 부품별 펼침 목록, 항목명·값·부품명 검색을 제공한다.
  5. 이전 버전 사양 조회와 원본 다운로드. 같은 자산의 동일 SHA-256 보고서는 중복 저장하지 않는다. 기존 보고서와 컴퓨터 이름이 다르면 확인 안내를 표시한다.

모든 Property를 계층 경로와 함께 보존한다. SPD 메모리 모듈과 시스템 전체 메모리를 중복 합산하지 않는다. 같은 모델의 서로 다른 디스크/모니터도 개별 노드로 유지한다. 드라이브 수는 외장 장치도 포함한다. ScanTime은 보고서에 있는 시각 그대로이고 시간대는 추정하지 않는다. 업로드/활동 시각은 KST로 표시한다. BIOS의 기본 문자열 System Serial Number는 실제 시스템 시리얼로 사용하지 않는다.

defusedxml로 엔티티/외부 엔티티를 차단한다. HWiNFO 외부 DTD 선언은 허용하지만 DTD를 읽거나 내려받지 않는다. 크기·계층 제한과 HTML 이스케이프를 적용한다. 원본 XML은 첨부로 내려받는다. 엑셀의 사용자 텍스트는 수식으로 실행하지 않는다. 모든 API는 권한, 변경 API는 세션 CSRF 토큰을 확인한다.

저장소와 설치

app/modules/asset/의 router/store/db/hwinfo/templates, 공통 메뉴/권한에 등록. 전용 PostgreSQL asset_db, ASSET_DB_URL. JSON 폴백 없음. 미설정 시 저장 버튼 비활성 + 안내. XML 분석 미리보기는 DB 없이 가능. 앱 시작 시 DB/테이블을 생성하지 않는다.

테이블 용도
assets 자산·상태·사용자·위치·현재 보고서·수정 버전
asset_reports 원본 XML(BYTEA)·분석 JSONB·SHA-256·처리자/시각. 이전 버전 보존
asset_events 등록·수정·배정·반납·상태·보고서 이력. 변경 전/후 값

자산/보고서/이력은 한 트랜잭션에서 변경한다. 원본과 분석 결과도 함께 저장하므로 별도 첨부 경로가 없다. 앱 계정 asset_app은 자산 SELECT/INSERT/UPDATE, 보고서/이력 SELECT/INSERT, sequence USAGE/SELECT. 소유자는 postgres. 최신 보고서의 복합 FK는 다른 자산의 보고서 연결을 막는다.

DB 생성은 서버 실행 명령을 제공하고 사용자가 직접 진행한다 (2026-10-06). scripts/sql/asset_db_init.sql은 재실행 시 기존 데이터·비밀번호를 변경하지 않는다. 운영 /opt/www/main, PostgreSQL postgres-db, 컨테이너 포트 5432. 현재 상태·DB 목록·기존 백업 위치 확인 후 진행한다. 권장 백업은 매일, /var/backups/postgres/asset_db_YYYY-MM-DD.dump(운영자가 준비; 자동 스케줄은 추가하지 않음). 원본 XML도 pg_dump에 포함되므로 보고서가 늘면 백업 용량도 증가한다.

cd /opt/www/main
docker compose ps
docker exec postgres-db psql -U postgres -c '\l'
# 신규 설치 시 사용자가 대상 서버·현재 DB·기존 백업 위치 확인 후 실행:
read -r -s -p 'asset_app password: ' ASSET_APP_PWD; echo
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres \
  -v app_password="$ASSET_APP_PWD" < scripts/sql/asset_db_init.sql
unset ASSET_APP_PWD
# .env: ASSET_DB_URL=postgresql://asset_app:<URL-encoded-password>@postgres-db:5432/asset_db
docker exec postgres-db psql -U postgres -d asset_db -c '\dt'
docker compose up -d --build web
docker compose ps
docker compose logs --tail=50 web
# 로그인 후 /asset/health와 등록·배정·반납·보고서 확인

DB·테이블·.env의 ASSET_DB_URL을 이미 준비했다면 초기화 SQL은 생략한다. 코드를 반영한 뒤 웹 컨테이너를 재빌드하고 앱 계정의 DB 연결을 확인한다. 아래 확인은 데이터를 추가하거나 수정하지 않는다. 일반 직원은 관리자 페이지에서 asset 권한을 부여한다.

cd /opt/www/main
docker compose ps
git status --short
git pull --ff-only origin master
docker compose up -d --build web
docker compose ps
docker compose exec -T web python -c 'from app.main import app; store=app.state.asset_store; store is not None or exit("ASSET_DB_URL 설정이 필요합니다."); store.health(); print("asset_db 연결 정상")'
docker compose logs --tail=50 web

참고한 업무 패턴

기존 ERP의 단색 화면·사이드바·상태 배지·다이얼로그에 맞춰 재구성했다.

검증

python -m unittest discover -s tests -p 'test_asset*.py'
python tests/js/render_asset.py
node tests/js/asset.browser.test.js

Chrome 검증은 실제 템플릿과 가짜 API를 사용해 운영 DB에 쓰지 않는다. 실물 보고서는 ASSET_SAMPLE_XML 경로 또는 프로젝트 루트 KING-DESKTOP.XML을 사용한다. 실물 파일이 없으면 그 검증만 건너뛰고 합성 보고서 테스트는 실행한다.