Core ‐ 세부기능 - nhnacademy-aiot3-4iren/4iren-wiki GitHub Wiki

Core 기능 요구사항

0. 공통 권한 및 검증

기능

모든 조회, 생성, 수정, 삭제 요청에 대해 권한을 검증한다.

요구사항

사용자가 해당 팀의 구성원인지 확인한다.
요청한 건물, 공간, 기기, 센서가 해당 팀에 속하는지 확인한다.
요청한 공간에 접근 권한이 있는지 확인한다.
기능별 필요한 역할(OWNER, ADMIN, MEMBER)을 검증한다.
검증 실패 시 요청을 거부한다.

1. 건물 관리

기능

건물을 생성, 수정, 삭제 및 조회할 수 있다.

요구사항

생성

팀에 건물을 등록할 수 있다. (건물은 반드시 하나의 팀에 소속되며, 미배정 건물은 지원하지 않는다)

수정

건물명을 변경할 수 있다. (건물의 소속 팀은 변경할 수 없다)

삭제

건물을 삭제할 수 있다.

조회

특정 팀이 관리하는 건물 목록을 조회할 수 있다. (페이징 지원)
건물 상세 정보를 조회할 수 있다.
건물 상세 응답에 해당 건물의 공간·기기·센서 개수가 포함된다. (별도의 개수 전용 API는 없다)

2. 공간 관리

기능

공간을 생성, 수정, 삭제 및 조회할 수 있다.

요구사항

생성

건물에 공간을 등록할 수 있다.

수정

공간명을 변경할 수 있다.
공간 설명을 변경할 수 있다.

삭제

공간을 삭제할 수 있다.

조회

건물의 전체 공간을 조회할 수 있다.
공간 상세 정보를 조회할 수 있다.

3. 기기 관리

기능

기기를 생성, 수정, 삭제 및 조회할 수 있다.

요구사항

생성

공간에 기기를 등록할 수 있다.

수정

기기를 다른 공간으로 이동할 수 있다.
기기명을 변경할 수 있다.

삭제

기기를 삭제할 수 있다.

조회

공간에 등록된 기기 목록을 조회할 수 있다.

4. 센서 관리

기능

센서를 생성, 수정, 삭제 및 조회할 수 있다.

요구사항

생성

공간에 센서를 등록할 수 있다.
센서의 EUI는 시스템 내에서 유일해야 한다.

수정

센서를 다른 공간으로 이동할 수 있다.

삭제

센서를 삭제할 수 있다.

조회

공간에 등록된 센서 목록을 조회할 수 있다.
센서 장치의 상세 정보를 조회할 수 있다.

5. 공간 구독 관리

기능

사용자는 공간을 구독하고 관리할 수 있다.

요구사항

구독은 관리자 승인이 없는 셀프 등록 방식이다. 구독 요청·승인 상태(pending/approved) 개념은 존재하지 않으며, 팀 구성원이면 즉시 구독이 생성된다.

생성

팀 구성원만 공간을 구독할 수 있다.
사용자와 공간 정보를 이용하여 구독을 즉시 생성한다. (승인 절차 없음)
동일한 공간은 중복 구독할 수 없다. (이미 구독 중이면 기존 구독을 반환하는 멱등 동작)
신규 관리자(ADMIN)가 팀에 자동 편입될 때, 해당 팀의 모든 기존 공간이 자동으로 구독된다.

수정

알림 수신 여부(notificationEnabled)를 변경할 수 있다.

삭제

공간 구독을 취소할 수 있다.

조회

사용자가 구독한 공간 목록을 조회할 수 있다. (전체 / 팀 단위)
공간을 구독한 사용자 목록을 내부 API로 조회할 수 있다. 이때 비활성 계정은 제외된다.
알림 발송 자체는 Core가 수행하지 않는다. Core는 구독자 목록만 제공하고, 실제 발송은 Notification 서비스가 담당한다.

6. 팀 관리

기능

팀을 생성, 수정, 삭제 및 조회할 수 있다.

요구사항

생성

팀을 생성할 수 있다.

수정

팀명을 변경할 수 있다.

삭제

OWNER 권한을 가진 사용자만 팀을 삭제할 수 있다.
단, 팀이 ARCHIVED 상태이고 소속 건물이 하나도 없어야 삭제할 수 있다. (건물이 남아 있으면 삭제 불가)

상태 관리

팀 상태를 변경할 수 있다. (활성 / 일시정지 / 보관)
Account 서비스의 역할 변경 이벤트를 수신하여, OWNER → NORMAL 강등 시 해당 사용자의 팀을 자동 일시정지하고 OWNER 승격 시 복구한다.

조회

초대 코드를 이용하여 팀 정보를 조회할 수 있다.

7. 팀 구성원 관리

기능

팀 구성원을 관리할 수 있다.

요구사항

생성

초대 코드를 이용하여 팀에 가입할 수 있다.
동일한 사용자는 같은 팀에 중복 가입할 수 없다.

삭제

구성원을 삭제할 수 있다. 단, 자기 자신은 삭제할 수 없다.
삭제 권한은 역할에 따라 제한된다. OWNER는 ADMIN·NORMAL을, ADMIN은 NORMAL만 삭제할 수 있다. 따라서 OWNER는 누구도 삭제할 수 없다.
팀 탈퇴는 NORMAL 역할만 가능하다.

조회

팀 구성원 목록을 조회할 수 있다. (페이징 지원)
팀 구성원의 역할(OWNER, ADMIN, NORMAL)을 조회할 수 있다.

구성원의 역할을 Core에서 직접 변경하는 API는 없다. 역할은 Account 서비스가 소유하며, 변경 사항은 RabbitMQ 이벤트로 전달된다.

8. 팀 초대 코드 관리

기능

팀 초대 코드를 관리할 수 있다.

요구사항

생성

팀별로 고유한 초대 코드를 생성한다.
초대 코드의 만료 시간을 설정할 수 있다.

조회

팀의 초대 코드 및 만료 시간을 조회할 수 있다.
초대 코드의 유효 여부를 확인할 수 있다.

비활성화

초대 코드를 수동으로 비활성화할 수 있다. (active=false 처리이며 행 삭제는 아니다)
만료된 코드는 검증 단계에서 무효 처리될 뿐, 자동으로 삭제하는 스케줄러는 없다.

9. 기상청 API 연동

기능

기상청 데이터를 조회하여 내부 서비스 및 LLM Service에서 사용할 수 있도록 제공한다.

요구사항

초단기 실황 조회 API를 제공한다.
초단기 예보 조회 API를 제공한다.
내부 서비스용 원본 응답 API와, LLM이 바로 쓰기 좋은 단순화 응답 API를 각각 제공한다.
공간 위치를 기준으로 해당 지역 날씨를 조회할 수 있다. (주소 → 좌표 변환은 Kakao 지오코딩, 좌표 → 기상청 격자 변환 포함)
특정 날짜의 시간대별 과거 날씨를 재구성해 조회할 수 있다.
기상청 코드 데이터를 서비스에서 사용할 수 있는 형태로 변환한다.
외부 API 호출 실패 시 적절한 오류를 반환한다.

Core는 날씨 데이터만 제공하며, 실내 센서값과 실외 날씨를 결합한 "실내외 비교" 결과는 생성하지 않는다. 비교·해석은 Recommendation 서비스(일일 요약·브리핑)가 담당한다.

10. InfluxDB 센서 데이터

기능

InfluxDB에 저장된 센서 데이터를 조회한다.

요구사항

센서의 시계열 데이터를 조회할 수 있다.
기간별 센서 데이터를 조회할 수 있다.
최신 센서 데이터를 조회할 수 있다. (최근 24시간 범위에서 탐색)
집계 간격은 고정값이 아니라 요청 시 임의의 간격(interval)으로 지정한다. 최소 간격·최대 조회 범위·최대 버킷 수는 설정으로 제한하며, 조회 범위는 간격으로 나누어떨어져야 한다.

11. 센서 지표 실시간 스트리밍 (SSE)

기능

강의실 센서 지표 변화를 Server-Sent Events로 실시간 전송한다.

요구사항

강의실 단위로 SSE 구독을 생성한다. (text/event-stream)
구독 시 접근 권한과 활성 지표를 검증하고, 유효한 지표가 없으면 구독을 거부한다.
재연결 시 Last-Event-ID 헤더 또는 since 파라미터로 놓친 이벤트를 재생한다. 재생 이력은 Redis에 커서와 함께 보관한다.
재생 이력이 만료되었거나 커서가 유효하지 않으면 재동기화 이벤트를 내려보낸다.
연결 유지를 위한 하트비트를 주기적으로 전송하며, 연결별 백프레셔 큐와 메트릭을 관리한다.
Processing 서비스가 RabbitMQ로 발행한 센서 메시지를 수신해 구독자에게 전달한다.

12. 대시보드 API

기능

대시보드에서 사용하는 통계 데이터를 제공한다.

요구사항

공간별 센서 요약을 조회할 수 있다. 요약 구간은 조회 시점 기준 최근 15분 평균이다.
공간별 최신 센서 데이터를 조회할 수 있다.
공간에서 사용 가능한 지표 목록(카탈로그)을 조회할 수 있다.
반복 조회 부하를 줄이기 위해 요약·최신값 스냅샷은 Caffeine(L1) + Redis(L2) 계층 캐시로 제공한다.

13. 기기 동작 이력

기능

기기의 동작 기록을 남기고 조회한다.

요구사항

기기의 동작을 이력으로 기록할 수 있으며, 기록 시 기기의 현재 동작 상태도 함께 갱신된다.
요일 및 기간 조건으로 이력을 조회할 수 있다. 기본 조회 범위는 최근 1년이며 최대 1년까지 허용한다.
요일 값은 기록 시각으로부터 자동 계산되어 저장된다.

14. 내부 서비스 전용 API

기능

다른 마이크로서비스가 사용하는 내부 API를 제공한다. (사용자 인증 없이 서비스 간 호출)

요구사항

공간 상세·지역 좌표·기기 목록·관리 권한 여부를 조회할 수 있다.
센서 devEUI로 해당 센서의 공간·팀 컨텍스트를 조회할 수 있다. (Processing 수집 파이프라인용)
공간 지표 요약·시계열을 조회할 수 있다. (Recommendation·ML 배치용)
사용자의 구독 공간 목록과 공간 구독자 목록을 조회할 수 있다. (Notification 발송 대상 선정용)
사용자가 속한 활성 팀 목록을 조회할 수 있다.