개요

Nexumm VX는 MQTT·Kafka·TimescaleDB로 설비·센서 데이터를 수집하고, 본 API와 React 대시보드로 실시간 모니터링·알람·트렌드·CAD 뷰어를 제공합니다. 본 문서는 api-server의 REST 엔드포인트를 기준으로 정리했습니다.

Base URL (로컬)

http://localhost:8080

운영 환경에서는 리버스 프록시(Nginx 등) 뒤의 호스트를 사용합니다.

공통 응답 형식

성공 응답은 대부분 아래 래퍼를 사용합니다.

{
  "success": true,
  "data": { ... },
  "message": null
}

페이징 (`PageResponse`)

{
  "success": true,
  "data": {
    "content": [ ... ],
    "totalElements": 120,
    "page": 0,
    "size": 20
  }
}

목록 API는 페이지가 0부터 시작합니다.

오류

Spring Security·검증 실패 시 HTTP 상태(401, 403, 400 등)와 본문 메시지가 반환될 수 있습니다. 세부 필드는 컨트롤러·@ControllerAdvice 설정에 따릅니다.

인증

보호된 API는 Authorization: Bearer <access_token> 헤더가 필요합니다.

Authorization: Bearer <access_token>

토큰 갱신

POST /api/auth/refresh

{ "refreshToken": "..." }

응답 data.accessToken으로 새 액세스 토큰을 받습니다.

로그아웃

POST /api/auth/logout

감사 로그: AUTH_LOGOUT

사용자·계정

내 정보

메서드·경로	설명
`GET /api/users/me`	현재 로그인 사용자 프로필
`PATCH /api/users/me/password`	본인 비밀번호 변경

사용자 관리 (관리자)

권한: USER_ADMIN

메서드·경로	설명
`GET /api/users`	목록 — 쿼리: `page`, `size`, `q`(검색)
`POST /api/users`	생성 — 감사 `USER_CREATE`
`PUT /api/users/{id}`	수정 — `USER_UPDATE`
`PATCH /api/users/{id}/active`	활성/비활성 — `USER_ACTIVE`

역할·권한·메뉴

역할

/api/roles — GET, POST, PUT /{id}, GET /{id}/permissions, PUT /{id}/permissions

권한 코드 목록

GET /api/permissions

메뉴

경로	설명
`GET /api/menus`	전체 메뉴 트리(관리)
`GET /api/menus/my`	현재 사용자에게 보이는 메뉴
`PUT /api/menus`	일괄 저장
`POST /api/menus`	추가
`DELETE /api/menus/{id}`	삭제

주요 권한 예: DASHBOARD_VIEW, EQUIPMENT_READ, EQUIPMENT_WRITE, ALARM_READ, ALARM_ACK, USER_ADMIN 등 (실제 목록은 DB·시드 데이터 기준).

사이트·프로젝트

사이트 `/api/sites`

메서드	설명
`GET`	사이트 목록
`POST`	생성
`PUT /{id}`	수정

프로젝트 `/api/projects`

GET, GET /{id}, POST, PUT /{id}, DELETE /{id}

설비·유형·컴포넌트

설비 `/api/equipments`

메서드·경로	권한·설명
`GET /overview`	`DASHBOARD_VIEW` — 시설별 오버뷰 (`siteId`, 선택: `equipmentTypeId`, `healthStatus`, `structureOnly`)
`GET`	`EQUIPMENT_READ` — 목록·페이징·필터
`POST`	`EQUIPMENT_WRITE` — 생성
`GET /{id}`	`EQUIPMENT_READ` 또는 `DASHBOARD_VIEW`
`PUT /{id}`	`EQUIPMENT_WRITE`
`PATCH /{id}/receive`	입고 처리
`PATCH /{id}/ship`	출고 처리
`GET /{id}/attributes`	동적 속성 값
`PUT /{id}/attributes`	속성 값 일괄 저장
`DELETE /{id}`	삭제

설비 유형 `/api/equipment-types`

GET, POST, PUT /{id}, PATCH /{id}/active

유형별 속성 정의 `/api/equipment-types/{id}/attributes`

GET, POST, PUT /{attrId}, DELETE /{attrId}

컴포넌트

경로	설명
`GET /api/equipments/component-type-codes`	컴포넌트 타입 코드
`GET /api/equipments/{equipmentId}/components`	목록
`POST /api/equipments/{equipmentId}/components`	추가
`PUT /api/equipments/{equipmentId}/components/reorder`	순서
`PUT /api/components/{id}`	수정
`DELETE /api/components/{id}`	삭제

채널

메서드·경로	설명
`GET /api/equipments/{equipmentId}/channels`	설비별 채널
`POST /api/equipments/{equipmentId}/channels`	채널 생성
`GET /api/channels/{id}`	단건
`PUT /api/channels/{id}`	수정
`PATCH /api/channels/{id}/active`	활성 토글
`GET /api/channels/search`	검색
`GET /api/channels/by-ids`	ID 목록으로 일괄 조회
`POST /api/channels/import/preview`	파일 import 미리보기 (multipart)
`POST /api/channels/import`	import 확정
`GET /api/channels/export`	export

마이 채널 (즐겨찾기)

GET /api/my-channels, POST /api/my-channels, DELETE /api/my-channels/{channelId}, PUT /api/my-channels/reorder

센서·시계열 데이터

경로 접두사: /api/sensor-data. TimescaleDB sensor_data 하이퍼테이블을 조회합니다.

대부분 DASHBOARD_VIEW 권한이 필요합니다.

GET 경로	쿼리·설명
`/latest`	`equipmentIds`(쉼표) 선택 — 설비별 최신 샘플
`/summary`	`siteId` — 시설 요약
`/summaries`	`siteIds=1,2,3` — 다중 시설 요약
`/overview-snapshot`	오버뷰 폴링용 스냅샷
`/overview-bootstrap`	초기 로드: 스냅샷+롤링 (`windowSeconds` 기본 60, 10~600)
`/overview-rolling-stats`	전체 롤링 집계
`/overview-rolling-stats-by-site`	시설 카드용 롤링 집계

시계열 (Trend)

GET /api/sensor-data?channelIds=1,2,3&from=2026-01-01T00:00:00Z&to=2026-01-02T00:00:00Z&bucket=auto

bucket: auto(기본), raw, 1s, 10s, 1m, 5m, 15m, 1h. 응답은 채널별 시계열 포인트(시간, avg/min/max 등)입니다.

알람·규칙

알람 이벤트 `/api/alarms`

목록: GET — ALARM_READ 또는 DASHBOARD_VIEW. 쿼리: siteId, equipmentId, severity, status, channelIds(쉼표), from, to(ISO 8601), page, size.

Trend 마커용(페이징 없음): 동일 GET에 channelIds, from, to만 지정하면 별도 핸들러로 집계 목록이 반환됩니다.

GET /stats — groupBy: 생략/full, 또는 severity, equipment, channel

GET /{id} — 상세 · PATCH /{id}/ack — 확인(ALARM_ACK) · PATCH /{id}/resolve — 해제 · PATCH /ack-batch — 일괄 확인

알람 규칙 `/api/alarm-rules`

GET, POST, PUT /{id}, PATCH /{id}/active, DELETE /{id}

트렌드·프리셋·관심 구간

경로	설명
`GET /api/trend/presets`	프리셋 목록
`POST /api/trend/presets`	생성
`PUT /api/trend/presets/{id}`	수정
`DELETE /api/trend/presets/{id}`	삭제
`GET /api/trend/interest-ranges`	관심 시간 구간
`POST /api/trend/interest-ranges`	추가
`DELETE /api/trend/interest-ranges/{id}`	삭제
`POST /api/trend/export`	JSON 기반 트렌드 내보내기

리포트

템플릿 `/api/report-templates`

GET, GET /{id}, POST, PUT /{id}, DELETE /{id}

리포트 `/api/reports`

GET, POST, GET /{id}, PUT /{id}, DELETE /{id}, GET /{id}/export

CAD

접두사 /api/cad

메서드·경로	설명
`POST /upload`	multipart 업로드
`GET`	목록
`GET /{id}`	메타
`GET /{id}/model`	모델 파일 바이너리
`DELETE /{id}`	삭제
`GET /{cadFileId}/mappings`	설비·노드 매핑
`PUT /{cadFileId}/mappings`	매핑 저장

공통 코드·게시판·감사

코드 `/api/codes`

GET /groups, GET, POST, PUT /{id}, PATCH /{id}/active

게시판 `/api/boards`

GET, POST, GET /{id}, PUT /{id}, DELETE /{id}

감사 로그 `/api/audit-logs`

GET — 필터·페이징(서버 구현 기준)

시스템 상태

경로	설명
`GET /api/system/status`	Kafka lag, 커넥션 풀, 수집·WS 세션, DLQ, 디스크 등
`GET /api/system/health`	Actuator 래핑 헬스
`GET /actuator/health`	설정에 따라 인증 없이 접근 가능

WebSocket / STOMP

엔드포인트: SockJS /ws/sensor-data

브로커: 구독 접두사 /topic, /queue · 앱 목적지 접두사 /app · 사용자 접두사 /user

애플리케이션 핸들: /app/sensor-data/subscribe (@MessageMapping) — 실시간 푸시 구독 흐름에 사용됩니다. JWT는 STOMP 연결 시 StompSessionPrincipalInterceptor에서 검증합니다(구현 세부는 서버 코드 참고).

구현 세부·DTO 필드는 api-server/src/main/kotlin/com/rhistle/nexumm 하위 컨트롤러·dto 패키지를 참고하세요. 저장소 README: README.md (Nexumm VX 개요·실행 방법).

개요

Base URL (로컬)

http://localhost:8080

운영 환경에서는 리버스 프록시(Nginx 등) 뒤의 호스트를 사용합니다.

공통 응답 형식

성공 응답은 대부분 아래 래퍼를 사용합니다.

{
  "success": true,
  "data": { ... },
  "message": null
}

페이징 (`PageResponse`)

{
  "success": true,
  "data": {
    "content": [ ... ],
    "totalElements": 120,
    "page": 0,
    "size": 20
  }
}

목록 API는 페이지가 0부터 시작합니다.

오류

Spring Security·검증 실패 시 HTTP 상태(401, 403, 400 등)와 본문 메시지가 반환될 수 있습니다. 세부 필드는 컨트롤러·@ControllerAdvice 설정에 따릅니다.

인증

보호된 API는 Authorization: Bearer <access_token> 헤더가 필요합니다.

Authorization: Bearer <access_token>

토큰 갱신

POST /api/auth/refresh

{ "refreshToken": "..." }

응답 data.accessToken으로 새 액세스 토큰을 받습니다.

로그아웃

POST /api/auth/logout

감사 로그: AUTH_LOGOUT

사용자·계정

내 정보

메서드·경로	설명
`GET /api/users/me`	현재 로그인 사용자 프로필
`PATCH /api/users/me/password`	본인 비밀번호 변경

사용자 관리 (관리자)

권한: USER_ADMIN

메서드·경로	설명
`GET /api/users`	목록 — 쿼리: `page`, `size`, `q`(검색)
`POST /api/users`	생성 — 감사 `USER_CREATE`
`PUT /api/users/{id}`	수정 — `USER_UPDATE`
`PATCH /api/users/{id}/active`	활성/비활성 — `USER_ACTIVE`

역할·권한·메뉴

역할

/api/roles — GET, POST, PUT /{id}, GET /{id}/permissions, PUT /{id}/permissions

권한 코드 목록

GET /api/permissions

메뉴

경로	설명
`GET /api/menus`	전체 메뉴 트리(관리)
`GET /api/menus/my`	현재 사용자에게 보이는 메뉴
`PUT /api/menus`	일괄 저장
`POST /api/menus`	추가
`DELETE /api/menus/{id}`	삭제

주요 권한 예: DASHBOARD_VIEW, EQUIPMENT_READ, EQUIPMENT_WRITE, ALARM_READ, ALARM_ACK, USER_ADMIN 등 (실제 목록은 DB·시드 데이터 기준).

사이트·프로젝트

사이트 `/api/sites`

메서드	설명
`GET`	사이트 목록
`POST`	생성
`PUT /{id}`	수정

프로젝트 `/api/projects`

GET, GET /{id}, POST, PUT /{id}, DELETE /{id}

설비·유형·컴포넌트

설비 `/api/equipments`

메서드·경로	권한·설명
`GET /overview`	`DASHBOARD_VIEW` — 시설별 오버뷰 (`siteId`, 선택: `equipmentTypeId`, `healthStatus`, `structureOnly`)
`GET`	`EQUIPMENT_READ` — 목록·페이징·필터
`POST`	`EQUIPMENT_WRITE` — 생성
`GET /{id}`	`EQUIPMENT_READ` 또는 `DASHBOARD_VIEW`
`PUT /{id}`	`EQUIPMENT_WRITE`
`PATCH /{id}/receive`	입고 처리
`PATCH /{id}/ship`	출고 처리
`GET /{id}/attributes`	동적 속성 값
`PUT /{id}/attributes`	속성 값 일괄 저장
`DELETE /{id}`	삭제

설비 유형 `/api/equipment-types`

GET, POST, PUT /{id}, PATCH /{id}/active

유형별 속성 정의 `/api/equipment-types/{id}/attributes`

GET, POST, PUT /{attrId}, DELETE /{attrId}

컴포넌트

경로	설명
`GET /api/equipments/component-type-codes`	컴포넌트 타입 코드
`GET /api/equipments/{equipmentId}/components`	목록
`POST /api/equipments/{equipmentId}/components`	추가
`PUT /api/equipments/{equipmentId}/components/reorder`	순서
`PUT /api/components/{id}`	수정
`DELETE /api/components/{id}`	삭제

채널

메서드·경로	설명
`GET /api/equipments/{equipmentId}/channels`	설비별 채널
`POST /api/equipments/{equipmentId}/channels`	채널 생성
`GET /api/channels/{id}`	단건
`PUT /api/channels/{id}`	수정
`PATCH /api/channels/{id}/active`	활성 토글
`GET /api/channels/search`	검색
`GET /api/channels/by-ids`	ID 목록으로 일괄 조회
`POST /api/channels/import/preview`	파일 import 미리보기 (multipart)
`POST /api/channels/import`	import 확정
`GET /api/channels/export`	export

마이 채널 (즐겨찾기)

GET /api/my-channels, POST /api/my-channels, DELETE /api/my-channels/{channelId}, PUT /api/my-channels/reorder

센서·시계열 데이터

경로 접두사: /api/sensor-data. TimescaleDB sensor_data 하이퍼테이블을 조회합니다.

대부분 DASHBOARD_VIEW 권한이 필요합니다.

GET 경로	쿼리·설명
`/latest`	`equipmentIds`(쉼표) 선택 — 설비별 최신 샘플
`/summary`	`siteId` — 시설 요약
`/summaries`	`siteIds=1,2,3` — 다중 시설 요약
`/overview-snapshot`	오버뷰 폴링용 스냅샷
`/overview-bootstrap`	초기 로드: 스냅샷+롤링 (`windowSeconds` 기본 60, 10~600)
`/overview-rolling-stats`	전체 롤링 집계
`/overview-rolling-stats-by-site`	시설 카드용 롤링 집계

시계열 (Trend)

GET /api/sensor-data?channelIds=1,2,3&from=2026-01-01T00:00:00Z&to=2026-01-02T00:00:00Z&bucket=auto

bucket: auto(기본), raw, 1s, 10s, 1m, 5m, 15m, 1h. 응답은 채널별 시계열 포인트(시간, avg/min/max 등)입니다.

알람·규칙

알람 이벤트 `/api/alarms`

목록: GET — ALARM_READ 또는 DASHBOARD_VIEW. 쿼리: siteId, equipmentId, severity, status, channelIds(쉼표), from, to(ISO 8601), page, size.

Trend 마커용(페이징 없음): 동일 GET에 channelIds, from, to만 지정하면 별도 핸들러로 집계 목록이 반환됩니다.

GET /stats — groupBy: 생략/full, 또는 severity, equipment, channel

GET /{id} — 상세 · PATCH /{id}/ack — 확인(ALARM_ACK) · PATCH /{id}/resolve — 해제 · PATCH /ack-batch — 일괄 확인

알람 규칙 `/api/alarm-rules`

GET, POST, PUT /{id}, PATCH /{id}/active, DELETE /{id}

트렌드·프리셋·관심 구간

경로	설명
`GET /api/trend/presets`	프리셋 목록
`POST /api/trend/presets`	생성
`PUT /api/trend/presets/{id}`	수정
`DELETE /api/trend/presets/{id}`	삭제
`GET /api/trend/interest-ranges`	관심 시간 구간
`POST /api/trend/interest-ranges`	추가
`DELETE /api/trend/interest-ranges/{id}`	삭제
`POST /api/trend/export`	JSON 기반 트렌드 내보내기

리포트

템플릿 `/api/report-templates`

GET, GET /{id}, POST, PUT /{id}, DELETE /{id}

리포트 `/api/reports`

GET, POST, GET /{id}, PUT /{id}, DELETE /{id}, GET /{id}/export

CAD

접두사 /api/cad

메서드·경로	설명
`POST /upload`	multipart 업로드
`GET`	목록
`GET /{id}`	메타
`GET /{id}/model`	모델 파일 바이너리
`DELETE /{id}`	삭제
`GET /{cadFileId}/mappings`	설비·노드 매핑
`PUT /{cadFileId}/mappings`	매핑 저장

공통 코드·게시판·감사

코드 `/api/codes`

GET /groups, GET, POST, PUT /{id}, PATCH /{id}/active

게시판 `/api/boards`

GET, POST, GET /{id}, PUT /{id}, DELETE /{id}

감사 로그 `/api/audit-logs`

GET — 필터·페이징(서버 구현 기준)

시스템 상태

경로	설명
`GET /api/system/status`	Kafka lag, 커넥션 풀, 수집·WS 세션, DLQ, 디스크 등
`GET /api/system/health`	Actuator 래핑 헬스
`GET /actuator/health`	설정에 따라 인증 없이 접근 가능

WebSocket / STOMP

엔드포인트: SockJS /ws/sensor-data

브로커: 구독 접두사 /topic, /queue · 앱 목적지 접두사 /app · 사용자 접두사 /user

구현 세부·DTO 필드는 api-server/src/main/kotlin/com/rhistle/nexumm 하위 컨트롤러·dto 패키지를 참고하세요. 저장소 README: README.md (Nexumm VX 개요·실행 방법).

개요

Base URL (로컬)

공통 응답 형식

페이징 (PageResponse)

오류

인증

로그인

토큰 갱신

로그아웃

사용자·계정

내 정보

사용자 관리 (관리자)

역할·권한·메뉴

역할

권한 코드 목록

메뉴

사이트·프로젝트

사이트 /api/sites

프로젝트 /api/projects

설비·유형·컴포넌트

설비 /api/equipments

설비 유형 /api/equipment-types

유형별 속성 정의 /api/equipment-types/{id}/attributes

컴포넌트

채널

마이 채널 (즐겨찾기)

센서·시계열 데이터

시계열 (Trend)

알람·규칙

알람 이벤트 /api/alarms

알람 규칙 /api/alarm-rules

트렌드·프리셋·관심 구간

리포트

템플릿 /api/report-templates

리포트 /api/reports

CAD

공통 코드·게시판·감사

코드 /api/codes

게시판 /api/boards

감사 로그 /api/audit-logs

시스템 상태

WebSocket / STOMP

개요

Base URL (로컬)

공통 응답 형식

페이징 (PageResponse)

오류

인증

로그인

토큰 갱신

로그아웃

사용자·계정

내 정보

사용자 관리 (관리자)

역할·권한·메뉴

역할

권한 코드 목록

메뉴

사이트·프로젝트

사이트 /api/sites

프로젝트 /api/projects

설비·유형·컴포넌트

설비 /api/equipments

설비 유형 /api/equipment-types

유형별 속성 정의 /api/equipment-types/{id}/attributes

컴포넌트

채널

마이 채널 (즐겨찾기)

센서·시계열 데이터

시계열 (Trend)

알람·규칙

알람 이벤트 /api/alarms

알람 규칙 /api/alarm-rules

트렌드·프리셋·관심 구간

리포트

템플릿 /api/report-templates

리포트 /api/reports

CAD

공통 코드·게시판·감사

코드 /api/codes

페이징 (`PageResponse`)

사이트 `/api/sites`

프로젝트 `/api/projects`

설비 `/api/equipments`

설비 유형 `/api/equipment-types`

유형별 속성 정의 `/api/equipment-types/{id}/attributes`

알람 이벤트 `/api/alarms`

알람 규칙 `/api/alarm-rules`

템플릿 `/api/report-templates`

리포트 `/api/reports`

코드 `/api/codes`

게시판 `/api/boards`

감사 로그 `/api/audit-logs`

페이징 (`PageResponse`)

사이트 `/api/sites`

프로젝트 `/api/projects`

설비 `/api/equipments`

설비 유형 `/api/equipment-types`

유형별 속성 정의 `/api/equipment-types/{id}/attributes`

알람 이벤트 `/api/alarms`

알람 규칙 `/api/alarm-rules`

템플릿 `/api/report-templates`

리포트 `/api/reports`

코드 `/api/codes`

게시판 `/api/boards`

감사 로그 `/api/audit-logs`