Files
dbx-main/docs/ASSET_MODULE.md
king e9be17faab fix(asset): allow registering a monitor of an already-registered model
Registration was blocked whenever same-model candidates existed, so a
second monitor of the same model (e.g. dual monitors) could not be added.
Now only an existing asset with the same serial blocks a new one; the
UI tells serial and model candidates apart and hides 'register' only
for serial matches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 15:14:22 +09:00

12 KiB

자산관리

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

수퍼 관리자(SUPER_ADMIN_EMAIL)만 자산을 삭제할 수 있다. 일반 관리자는 삭제할 수 없다. 삭제 창에서 자산번호와 사유를 확인하며 API도 권한·CSRF·수정 버전을 확인한다. 삭제한 자산은 대장·현황·엑셀·상세·첨부 다운로드에서 제외한다. 사진·보고서·이력과 기존 자산번호는 보존한다.

사진과 모니터 자산

  • 자산 상세의 기본 정보에서 사진을 등록하고 갤러리로 조회한다. 자산당 10장, 파일당 8 MB 입력 제한.
  • JPG/PNG/WebP만 실제 이미지로 검사하며 최대 2천만 화소, 2400px로 축소한다. EXIF/GPS 등 메타데이터를 제거한 JPEG/PNG를 DB에 보관한다(저장 파일당 5 MB 이하).
  • 컴퓨터 주요 사양 상단에 보고서의 모니터 목록을 표시한다. 등록된 모니터는 자산번호·이름·상태·사용자·위치·구매금액·보증 개요와 상세 이동을 제공한다.
  • 시리얼이 유효하고 기존 모니터 한 대와 식별 정보가 일치하면 자동으로 찾는다. 시리얼이 없거나 중복·제조사/모델 불일치인 경우 자동 확정하지 않고 후보를 직접 연결한다.
  • 미등록 모니터는 보고서의 이름/제조사/모델/시리얼과 컴퓨터의 위치/부서를 채운 등록 창을 연다. 생성과 컴퓨터 연결은 한 트랜잭션으로 저장한다. 동시 등록은 컴퓨터 행 잠금과 시리얼 잠금으로 보호한다.
  • 새 등록을 막는 것은 같은 시리얼의 모니터 자산이 이미 있을 때뿐이다(같은 실물 — 기존 자산에 연결). 같은 모델·이름의 자산은 참고 후보로만 보여 주고(candidate_by = "model"), 시리얼이 다르거나 없으면 새 자산으로 등록된다 (듀얼 모니터처럼 같은 모델 여러 대 — 2026-10-07 수정, 예전엔 같은 모델 후보만 있어도 막혔다).
  • 등록·연결은 최신 보고서에서만 가능하다. 이전 보고서도 모니터와 자산 개요를 조회할 수 있다. 기존에 업로드한 보고서도 재업로드 없이 지원한다.

업무 흐름

  • 현황 카드: 전체·사용 중·사용 가능·수리 중·30일 이내 보증 만료. 분류 구성·최근 활동·보유 구매금액(폐기 제외).
  • 자산대장: 검색/분류/상태/위치/사용자 필터, 정렬, 25개씩 페이지 이동. 엑셀은 현재 필터 전체(최대 10,000개).
  • 상세: 기본 정보/컴퓨터 사양/보고서/활동 이력. 구매일·금액·구매처·보증·부서·위치·메모.
  • 자산 선택 시 상세 패널은 오른쪽에서 들어온다. 바깥 영역 클릭·X·Esc로 오른쪽으로 나가며 닫힌다. 패널 안에서 시작한 드래그는 닫지 않으며 사진/편집 창이 열린 동안 부모 패널을 유지한다. 시스템의 모션 줄이기 설정에서는 즉시 열고 닫는다.
  • 등록: 번호를 비우면 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_photos 검증·재인코딩한 사진, MIME/크기/처리자/시각
asset_monitor_links 컴퓨터의 보고서 장비 식별키와 모니터 자산 연결

자산/보고서/이력은 한 트랜잭션에서 변경한다. 원본과 분석 결과도 함께 저장하므로 별도 첨부 경로가 없다. 앱 계정 asset_app은 자산 SELECT/INSERT/UPDATE, 보고서/이력 SELECT/INSERT, sequence USAGE/SELECT. 소유자는 postgres. 최신 보고서의 복합 FK는 다른 자산의 보고서 연결을 막는다. assets.deleted_at/deleted_by로 삭제를 표시한다. DB 계정에 DELETE 권한은 부여하지 않는다. 사진 SELECT/INSERT, 모니터 연결 SELECT/INSERT/UPDATE 권한을 사용한다.

기존 설치에 사진·모니터·삭제 기능 적용

asset_db / postgres-db / 컨테이너 포트 5432. 운영자는 현재 상태와 백업을 확인한 뒤 scripts/sql/asset_db_002_photos_monitors.sql을 적용한다. 열과 테이블을 추가하는 멱등 SQL이다. 새 환경변수는 필요 없다. 전체 초기화 SQL을 다시 실행하지 않는다.

(
set -euo pipefail
cd /opt/www/main
docker compose ps
git status --short
git pull --ff-only origin master
docker exec postgres-db psql -U postgres -d asset_db -c 'SELECT current_database(),current_user;'
sudo mkdir -p /var/backups/postgres
ASSET_BACKUP="/var/backups/postgres/asset_db_before_002_$(date +%Y%m%d_%H%M%S).dump"
sudo test ! -e "$ASSET_BACKUP"
sudo install -m 600 /dev/null "$ASSET_BACKUP"
docker exec postgres-db pg_dump -U postgres -F c -d asset_db | sudo tee "$ASSET_BACKUP" >/dev/null
sudo cat "$ASSET_BACKUP" | docker exec -i postgres-db pg_restore --list >/dev/null
echo "백업 확인: $ASSET_BACKUP"
docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d asset_db < scripts/sql/asset_db_002_photos_monitors.sql
docker compose up -d --build web
docker compose exec -T web python -c 'from app.main import app; s=app.state.asset_store; s is not None or exit("ASSET_DB_URL 설정 필요"); s.health(); print("asset_db 연결 및 스키마 정상")'
docker compose ps
docker compose logs --tail=50 web
)

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을 사용한다. 실물 파일이 없으면 그 검증만 건너뛰고 합성 보고서 테스트는 실행한다.