[BackEnd] 알람 비즈니스 로직 설계

[sooah-0208]

확정안

API 명세서

---

1. 알림 목록 조회 (POST)

Description: 현재 로그인 사용자의 알림 목록을 조회한다. (알림 payload의 companyId 기준으로 현재 선택 회사와 매칭)

항목	내용
Method	POST
URL	/alarm
Auth	Bearer Token 필요

Request Parameters

1. Query Parameters

Model명	형식	필수여부	설명
type	str	Optional	단일 알림 유형 필터 (예: USER)
types	str	Optional	복수 알림 유형 필터 (예: CHART,LEAF,CUBE)
isRead	bool	Optional	읽음 여부
page	int	Optional	페이지 번호
size	int	Optional	페이지 크기

2. Header Parameters

Model명	형식	필수여부	설명
Authorization	str	Required	Bearer {access_token} 형식의 인증 토큰
Company_Id	nu,	Required	현재 선택된 회사 ID

Response Body (JSON)

성공

{
  "status": true,
  "message": "알림 목록 조회에 성공했습니다.",
  "data": {
    "notifications": [
      {
        "id": 1,
        "type": "USER",
        "title": "신규 팀원 초대",
        "content": "신규 팀원 초대 요청이 승인되었습니다.",
        "isRead": false,
        "createdAt": "2026-04-29T10:00:00Z",
        "time": "10분 전",
        "path": "/manager/invite",
        "meta": { "inviteId": 15, "companyId": 1 }
      },
      {
        "id": 2,
        "type": "CHECK",
        "title": "데이터 승인 반려",
        "content": "ESG 데이터 1분기 실적 승인이 반려되었습니다.",
        "isRead": false,
        "createdAt": "2026-04-29T09:10:00Z",
        "time": "1시간 전",
        "path": "/onboarding",
        "meta": { "datasetId": 30, "companyId": 1 }
      }
    ],
    "unreadCount": 2,
    "typeCounts": { "USER": 1, "CHECK": 1, "CHART": 0, "LEAF": 0, "CUBE": 0 }
  }
}

실패

{
  "status": False,
  "data":{}
}

---

2. 알림 읽음 처리 (PATCH)

Description: 알림을 전체 또는 유형별로 읽음 처리한다.

항목	내용
Method	PATCH
URL	/alarm
Auth	Bearer Token 필요

Request Parameters

1. Request Body

Model명	형식	필수여부	설명
types	Array<str> 또는 null	Optional	읽음 처리할 알림 유형 리스트. null 또는 빈 배열이면 전체 읽음 처리

2. Header Parameters

Model명	형식	필수여부	설명
Authorization	str	Required	Bearer {access_token}
Company_Id	int	Required	현재 선택된 회사 ID

Response Body (JSON)

성공

{
  "status": true,
  "message": "알림 읽음 처리가 완료되었습니다.",
  "data": {
    "uuid": "7efdca5d-585c-4e79-b2c2-04a9082aa7d3",
    "updatedCount": 2,
    "unreadCount": 0,
    "typeCounts": { "USER": 1, "CHECK": 1, "CHART": 0, "LEAF": 0, "CUBE": 0 }
  }
}

실패

{
  "status": False,
  "data":{}
}

---

3. 알림 삭제 (DELETE)

Description: 알림을 개별/전체 삭제한다. 삭제 후 최신 알림 목록을 반환한다.

항목	내용
Method	DELETE
URL	/alarm
Auth	Bearer Token 필요

Request Parameters

1. Path Parameters

Model명	형식	필수여부	설명
id	int 또는 str	Required	삭제할 알림의 고유 ID

2. Header Parameters

Model명	형식	필수여부	설명
Authorization	str	Required	Bearer {access_token}
Company_Id	int	Required	현재 선택된 회사 ID

Response Body (JSON)

성공

{
  "status": true,
  "message": "알림이 삭제되었습니다.",
  "data": {
    "notifications": [],
    "deletedCount": 1,
    "unreadCount": 0,
    "deletedId": 1
  }
}

실패

{
  "status": False,
  "data":{}
}

---

4. 실시간 알림 (WebSocket / STOMP)

Description: 새로운 알림 발생 시 백엔드가 프론트로 실시간 알림을 전송한다.

항목	내용
Protocol	실시간 알림 WebSocket / STOMP
URL	/alarm
Auth	Bearer Token 필요

Request Parameters

1. Header Parameters

Model명	형식	필수여부	설명
Authorization	str	Required	Bearer {access_token}
Company_Id	int	Required	현재 선택된 회사 ID

Response Body (JSON)

성공

{
  "id": 100,
  "companyId": 1,
  "type": "CHART",
  "title": "보고서 생성 완료",
  "content": "2026년 ESG 보고서 생성이 완료되었습니다.",
  "isRead": false,
  "createdAt": "2026-04-29T10:30:00Z",
  "time": "방금 전",
  "path": "/dashboard/reports/100",
  "meta": { "reportId": 100 }
}

실패

{
  "status": False,
  "data":{}
}

---

영향 범위

FE @x2bjvhmmwg-gif / BE / 문서 @frankie516c

담당자

@mpsddd-commits , @choiyc05, @sooah-0208, @HorieZA , @choegayoung

결정일

2026-05-03