# Fleet Management - 전체 통합 문서

vexplor_fleet의 모든 기능이 Pipeline으로 통합되었습니다.

## 구조

```
Pipeline (단일 배포)
├─ 백엔드 (Node.js/Express)
│   ├─ Fleet API (/api/fleet/*)
│   ├─ 내장 MQTT 브로커 (aedes, port 1883)
│   ├─ 서비스 레이어
│   │   ├─ fleetDeviceService        - 디바이스 등록/관리
│   │   ├─ fleetCommandService       - 커맨드 실행 (9종)
│   │   ├─ fleetReleaseService       - 릴리즈 관리
│   │   ├─ fleetDeploymentService    - 배포 오케스트레이션 (카나리/롤링)
│   │   ├─ fleetHarborService        - Harbor Registry 조회
│   │   ├─ fleetTagTemplateService   - 태그 템플릿 + 일괄 적용
│   │   ├─ fleetAlertRuleService     - 알림 규칙 CRUD
│   │   ├─ fleetProvisionService     - DPS 프로비저닝
│   │   ├─ fleetV1MappingService     - 레거시 PLC 매핑
│   │   ├─ fleetPlcStatusService     - PLC 연결 실시간 상태
│   │   ├─ fleetAuditService         - 감사 로그
│   │   ├─ fleetMetricsService       - Prometheus 메트릭
│   │   ├─ fleetScriptService        - Python Hook 스크립트
│   │   ├─ fleetEdgeConfigService    - 엣지 설정 제공
│   │   └─ fleetDataService          - 실시간 수집 데이터
│   └─ MQTT 핸들러
│       ├─ vexplor/devices/+/status     → 디바이스 heartbeat
│       ├─ vexplor/devices/+/metrics    → 메트릭
│       ├─ vexplor/devices/+/responses  → 커맨드 응답
│       ├─ vexplor/devices/+/data       → 태그 데이터
│       └─ vexplor/devices/+/plc-status → PLC 연결 상태
│
└─ 프론트엔드 (Next.js, 시스템 관리 메뉴)
    ├─ 엣지 디바이스     (/admin/fleet/devices)
    ├─ Fleet 커맨드     (/admin/fleet/commands)
    ├─ Fleet 알림       (/admin/fleet/alerts)
    ├─ 실시간 수집      (/admin/fleet/data)
    ├─ Python Hook     (/admin/fleet/scripts)
    ├─ 배포 관리        (/admin/fleet/deployments)
    ├─ 릴리즈 관리      (/admin/fleet/releases)
    ├─ 알림 규칙        (/admin/fleet/rules)
    └─ 감사 로그        (/admin/fleet/audit)
```

## DB 스키마 (총 18개 Fleet 테이블)

| 테이블 | 용도 |
|---|---|
| fleet_devices | 엣지 디바이스 레지스트리 |
| fleet_heartbeats | 디바이스 상태 시계열 (30초마다) |
| fleet_commands / command_types | 9종 원격 커맨드 |
| fleet_releases | 릴리즈 버전 관리 |
| fleet_deployments / deployment_status | 배포 작업 + 디바이스별 상태 |
| fleet_alert_rules / alerts | 알림 규칙 + 발생 기록 |
| fleet_edge_raw_data | 실시간 수집 데이터 (시계열) |
| fleet_edge_scripts / script_versions / hook_types | Python Hook (5종, 버전 관리) |
| fleet_plc_connections | PLC 연결 실시간 상태 |
| fleet_tag_templates | 회사/장비별 태그 템플릿 |
| fleet_audit_logs | 전체 이벤트 감사 |
| fleet_users | Fleet 운영자 (SSO) |
| fleet_v1_plc_mapping | 레거시 v1 PLC 태그 매핑 |

## API 엔드포인트 (60+)

### 공개 (인증 없음)
```
POST /api/fleet/provision              - DPS 자동 등록
GET  /api/fleet/edge/:id/config        - 엣지 설정 (ETag 캐싱)
GET  /api/fleet/v1/edges/:id/config    - 호환 alias
```

### 디바이스 (12개)
```
GET    /api/fleet/devices
POST   /api/fleet/devices/register
GET    /api/fleet/devices/:id
PATCH  /api/fleet/devices/:id
DELETE /api/fleet/devices/:id
GET    /api/fleet/devices/:id/metrics
GET    /api/fleet/devices/:id/latest-values
GET    /api/fleet/devices/:id/tags/:tag/timeseries
GET    /api/fleet/data/stats
GET    /api/fleet/provision/pre-registered
POST   /api/fleet/provision/pre-register
GET    /api/fleet/stats
```

### 커맨드 (4개)
```
GET  /api/fleet/commands
GET  /api/fleet/commands/types
POST /api/fleet/commands
```

### Python Hook (10개)
```
GET    /api/fleet/scripts/hook-types
GET    /api/fleet/scripts
GET    /api/fleet/scripts/:id
POST   /api/fleet/scripts
PUT    /api/fleet/scripts/:id
DELETE /api/fleet/scripts/:id
POST   /api/fleet/scripts/dry-run
GET    /api/fleet/scripts/:id/versions
GET    /api/fleet/scripts/:id/versions/:v
POST   /api/fleet/scripts/:id/rollback/:v
```

### 릴리즈 (6개)
```
GET    /api/fleet/releases
GET    /api/fleet/releases/:id
POST   /api/fleet/releases
PUT    /api/fleet/releases/:id
DELETE /api/fleet/releases/:id
POST   /api/fleet/releases/:id/transition
```

### 배포 (8개)
```
GET  /api/fleet/deployments
GET  /api/fleet/deployments/:id
GET  /api/fleet/deployments/:id/status
POST /api/fleet/deployments
POST /api/fleet/deployments/:id/start
POST /api/fleet/deployments/:id/cancel
POST /api/fleet/deployments/:id/rollback
```

### Harbor (4개)
```
GET /api/fleet/harbor/projects
GET /api/fleet/harbor/projects/:project/repos
GET /api/fleet/harbor/projects/:project/repos/:repo/tags
GET /api/fleet/harbor/ping
```

### 태그 템플릿 (6개)
```
GET    /api/fleet/tag-templates
GET    /api/fleet/tag-templates/:id
POST   /api/fleet/tag-templates
PUT    /api/fleet/tag-templates/:id
DELETE /api/fleet/tag-templates/:id
POST   /api/fleet/tag-templates/:id/apply/:connectionId
```

### 알림 (7개)
```
GET    /api/fleet/alerts
POST   /api/fleet/alerts/:id/ack
POST   /api/fleet/alerts/:id/resolve
GET    /api/fleet/alert-rules
POST   /api/fleet/alert-rules
PUT    /api/fleet/alert-rules/:id
DELETE /api/fleet/alert-rules/:id
POST   /api/fleet/alert-rules/:id/toggle
```

### V1 PLC 매핑 (4개)
```
GET    /api/fleet/v1-mappings
POST   /api/fleet/v1-mappings
PUT    /api/fleet/v1-mappings/:id
DELETE /api/fleet/v1-mappings/:id
```

### PLC 상태, Audit, Metrics
```
GET /api/fleet/plc-status
GET /api/fleet/plc-status/summary
GET /api/fleet/audit-logs
GET /api/fleet/audit-logs/stats
GET /api/fleet/prometheus      - Prometheus text format
```

## Device Supervisor 포팅 (엣지 에이전트)

Python Data Collector는 **그대로 유지**하고, 추가로 Node.js Device Supervisor를 엣지에서 돌릴 때는 기존 `vexplor_fleet/device-supervisor/src/` 코드를 그대로 사용합니다. Pipeline 중앙이 MQTT 브로커 역할을 하므로 변경할 건 환경변수만:

```bash
# device-supervisor .env
FLEET_API_URL=http://pipeline.wace.me:8080/api/fleet
MQTT_BROKER_URL=mqtt://pipeline.wace.me:1883
DEVICE_ID=edge-001
COMPANY_CODE=spifox
HEARTBEAT_INTERVAL=30
```

## 환경변수

| 이름 | 기본값 | 설명 |
|---|---|---|
| MQTT_PORT | 1883 | 내장 MQTT TCP |
| MQTT_WS_PORT | 8083 | MQTT WebSocket |
| HARBOR_URL | https://harbor.wace.me | Harbor Registry |
| HARBOR_USER | - | Harbor 사용자 |
| HARBOR_PASSWORD | - | Harbor 비밀번호 |
| FLEET_API_URL | http://localhost:8080/api/fleet | Provisioning 응답용 |
| FLEET_MQTT_BROKER | mqtt://localhost:1883 | Provisioning 응답용 |

## 다음 단계 (선택)

- Grafana 임베드 (Metrics 탭)
- 프로비저닝 토큰 JWT 전환
- 배포 롤아웃 진행률 실시간 WebSocket
- Python 실행 RestrictedPython 적용 (보안 강화)
