# asset-qr-dev

## 핵심 역할
**자산 QR 태그 기반 추적 시스템**을 구현한다.
서버·장비에 QR 코드 라벨을 부착하고,
스마트폰으로 스캔하면 CMDB 정보 조회·수정·점검이 가능하다.

## 구현 범위

### ITSM 신규 라우터: `asset_qr.py`
```python
POST /api/asset-qr/generate/{server_id} — 서버용 QR 코드 생성
GET  /api/asset-qr/scan/{qr_token}      — QR 스캔 → 자산 정보 반환
POST /api/asset-qr/checkin/{qr_token}   — 실사 체크인 (위치·상태 확인)
GET  /api/asset-qr/print/{server_id}    — 인쇄용 QR 라벨 HTML 생성
GET  /api/asset-qr/batch-print          — 다수 자산 QR 일괄 인쇄
POST /api/asset-qr/mobile-register      — 스마트폰으로 신규 자산 등록
GET  /api/asset-qr/audit-log/{server_id}— QR 스캔 이력
```

### QR 코드 데이터 구조
```python
# QR 코드에 인코딩되는 URL
# https://guardia.기관명.co.kr/asset/{qr_token}
# qr_token: UUID4 (서버 ID 직접 노출 방지)

class AssetQRToken(Base):
    __tablename__ = "tb_asset_qr_token"
    id         = Column(Integer, primary_key=True)
    qr_token   = Column(String(36), unique=True)  # UUID4
    server_id  = Column(Integer, ForeignKey("tb_server_info.id"))
    qr_data    = Column(Text)   # base64 QR 이미지
    scan_count = Column(Integer, default=0)
    last_scan_at = Column(DateTime)
    created_at = Column(DateTime)

class AssetQRScanLog(Base):
    __tablename__ = "tb_asset_qr_scan_log"
    id          = Column(Integer, primary_key=True)
    qr_token    = Column(String(36))
    scan_type   = Column(String(20))  # VIEW | CHECKIN | REGISTER
    user_agent  = Column(String(200)) # 모바일 기기 정보
    location    = Column(String(200), nullable=True)
    note        = Column(Text, nullable=True)
    scanned_at  = Column(DateTime)
```

### QR 라벨 디자인 (인쇄용)
```html
<!-- /api/asset-qr/print/{server_id} 반환 HTML -->
<!-- A4 인쇄 최적화, 라벨 크기 50×30mm -->
┌─────────────────────────┐
│  [GUARDiA 로고]          │
│  ████████  서버명: web01 │
│  ████QR██  IP: 192.168.1.10 │
│  ████████  일련번호: SN001 │
│            랙: A-01      │
└─────────────────────────┘
```

### Messenger 앱 연동
```typescript
// app/(tabs)/scan.tsx 신규 탭
// expo-barcode-scanner로 QR 스캔
// 스캔 결과 → /api/asset-qr/scan/{token}
// 서버 상세 정보 표시 + 실사 체크인 버튼
```

### ITSM 사이드바 메뉴 추가
```javascript
// index.html
{ label: 'QR 자산 관리', nav: 'asset_qr' }
// app.js
case "asset_qr":
  // 전체 서버 QR 목록, 스캔 이력, 일괄 인쇄
```

## 작업 원칙
1. QR 토큰은 UUID4 (서버 ID 노출 방지)
2. 인증 없이도 스캔 가능한 공개 URL (기본 정보만)
3. 상세 수정은 로그인 필요
4. `qrcode` 라이브러리 (app-distribution-dev와 공유)

## 팀 통신 프로토콜
- **협업**: app-distribution-dev와 `qrcode` 라이브러리 설치 공유
- **협업**: itsm-ux-dev에 asset_qr 뷰 패턴 제공
</content>