gper/Gnuboard7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38a5cbe550de49277f1bcfeaf8f8a180afbc72f0
Gnuboard7/docs/backend/api/notifications.md
T
HeuJung 403154167a fix(core): api:docgen 재생성이 문서를 손실·열화시키는 결함 수정 
재생성이 사람이 채운 서술과 이전 실측 결과를 지우고, 코드가 바뀌지 않은
문서까지 매 실행마다 흔들던 결함 5건을 고쳤다.

- 중첩 객체 파라미터가 문서에서 통째로 누락되던 문제: 배열 요소(items.*.id)를
 상위로 대표시키려던 스킵 조건이 점(.) 포함 여부만 봐서, 와일드카드가 없는
 중첩 객체 필드(refund_bank.*, general.*, content.* 등 17개 엔드포인트 수백 개)
 까지 함께 버렸다. 와일드카드가 있을 때만 스킵하도록 좁혔다.
- 사람이 보강한 에러 응답 표가 자동 추론 초안에 덮여 사라지던 문제:
 상태코드 키 단위로 병합한다.
- 실측 실패가 이전에 관측해 둔 응답 예시를 지우던 문제: 실측 성패는 호출 시점
 데이터 유무에 좌우되므로(DELETE /checkout 은 대상이 없으면 404), 실패는
 "새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
- 실측 예시값·응답 예시 JSON 이 DB 상태를 그대로 반영해 비멱등하던 문제:
 값이 아니라 스펙(필드 집합·타입)이 바뀐 경우에만 갱신한다. nullable 이
 null 로 관측된 것은 타입 변경이 아니므로 기존 값을 유지한다.
- 요청 예시 path 파라미터가 실측 성패에 따라 흔들리던 문제: placeholder 로 고정.

결과: 문서 63개 전수 대조에서 손실 0(서술·표 셀·응답 예시), 전 scope 연속
재생성 시 diff 0(멱등).
2026-08-06 13:54:35 +09:00

36 KiB
Raw Blame History

Notifications API 레퍼런스

소유: 코어 · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.

TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Notifications 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

GET /api/admin/notifications

  • 라우트명: api.admin.notifications.index
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@index
  • 인증/권한: auth:sanctum + permission:core.notifications.read

요청 파라미터

이름 위치 타입 필수 허용값 용도
read query string 아니오 unread, read, all 읽음 상태 필터 (unread: 미읽음(read_at null)만, read: 읽음(read_at not null)만, all: 전체). 미지정 시 전체
per_page query integer 아니오 min 1, max 100 페이지당 항목 수
page query integer 아니오 min 1 조회할 페이지 번호 (1부터 시작)
sort_order query string 아니오 asc, desc 정렬 방향 (asc 오름차순 / desc 내림차순)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.notification.index_validation_rules).

요청 예시

GET /api/admin/notifications?read=unread&per_page=1&page=1&sort_order=asc HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

목록 응답: data.data[] 배열 항목의 필드 + data.pagination.

필드 타입 실측 예시값 용도/설명
number integer 23 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생)
id string 518b9c94-5853-4b68-8193-83af1851bbc6 기본 키 (내부 식별자)
type string inquiry_received
type_label string 상품 문의 접수 type 값의 사람이 읽는 라벨 (현지화/Enum 파생)
subject string 새로운 상품 문의가 접수되었습니다
body string 옥혜진님이 "면 손수건 3매입 #1" 상품에 문의를 남겼습니다.
url string https://g7_2.dev/admin/ecommerce/prod…
data object {"type":"inquiry_received","subject":"새로운 상품 문의가 접수되었습니다"…
read_at string 2026-07-31 22:06:53 read 일시
created_at string 2026-07-31 21:41:58 생성 일시

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "알림 목록을 조회했습니다.",
    "data": {
        "data": [
            {
                "number": 23,
                "id": "518b9c94-5853-4b68-8193-83af1851bbc6",
                "type": "inquiry_received",
                "type_label": "상품 문의 접수",
                "subject": "새로운 상품 문의가 접수되었습니다",
                "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                "url": "https://api.example.com/admin/ecommerce/product-inquiries",
                "data": {
                    "type": "inquiry_received",
                    "subject": "새로운 상품 문의가 접수되었습니다",
                    "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                    "click_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                    "data": {
                        "name": "최고관리자",
                        "app_name": "그누보드7",
                        "product_name": "면 손수건 3매입 #1",
                        "customer_name": "옥혜진",
                        "inquiry_content": "타인 계정 문의 3 입니다. 스코프 격리 검증용.",
                        "inquiry_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                        "site_url": "https://api.example.com"
                    }
                },
                "read_at": null,
                "created_at": "2026-07-31 21:41:58"
            },
            {
                "number": 22,
                "id": "75da60b8-3ec9-457f-ad8c-b52652f7adcf",
                "type": "inquiry_received",
                "type_label": "상품 문의 접수",
                "subject": "새로운 상품 문의가 접수되었습니다",
                "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                "url": "https://api.example.com/admin/ecommerce/product-inquiries",
                "data": {
                    "type": "inquiry_received",
                    "subject": "새로운 상품 문의가 접수되었습니다",
                    "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                    "click_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                    "data": {
                        "name": "최고관리자",
                        "app_name": "그누보드7",
                        "product_name": "면 손수건 3매입 #1",
                        "customer_name": "옥혜진",
                        "inquiry_content": "타인 계정 문의 2 입니다. 스코프 격리 검증용.",
                        "inquiry_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                        "site_url": "https://api.example.com"
                    }
                },
                "read_at": null,
                "created_at": "2026-07-31 21:41:55"
            },
            "... (총 23건 중 2건 표시)"
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 1,
            "per_page": 25,
            "total": 23,
            "from": 1,
            "to": 23,
            "has_more_pages": false
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 관리자 본인의 사이트내 알림 목록을 최신순(created_at desc)으로 페이지네이션해 반환합니다. read 파라미터로 미읽음(unread)·읽음(read)·전체(all, 기본)를 필터링하고, per_page 미지정 시 15건 단위로 반환합니다. 조회 대상은 항상 요청 사용자 본인의 알림으로 한정되며, 다른 사용자의 알림은 조회되지 않습니다. _admin_base.json 헤더의 알림 벨이 이 엔드포인트를 auto_fetch 로 소비하며 WebSocket 알림 수신 시 갱신됩니다. 항목 필드는 id, type, type_label, subject, body, url, read_at, created_at 로 구성됩니다.

DELETE /api/admin/notifications/all

  • 라우트명: api.admin.notifications.destroy-all
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@destroyAll
  • 인증/권한: auth:sanctum + permission:core.notifications.delete

요청 파라미터

요청 파라미터 없음.

요청 예시

DELETE /api/admin/notifications/all HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
deleted_count integer 23 deleted 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "모든 알림이 삭제되었습니다.",
    "data": {
        "deleted_count": 23
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 관리자 본인의 모든 사이트내 알림(읽음·미읽음 무관)을 삭제합니다. 삭제 대상은 요청 사용자 본인의 알림으로만 한정되며, 응답 data.deleted_count 에 삭제된 건수를 반환합니다. 되돌릴 수 없는 작업이므로 UI 에서 확인 절차를 거친 뒤 호출합니다.

POST /api/admin/notifications/read-all

  • 라우트명: api.admin.notifications.read-all
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@markAllAsRead
  • 인증/권한: auth:sanctum + permission:core.notifications.update

요청 파라미터

요청 파라미터 없음.

요청 예시

POST /api/admin/notifications/read-all HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
marked_count integer 7 marked 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "모든 알림을 읽음 처리했습니다.",
    "data": {
        "marked_count": 7
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 관리자 본인의 미읽음 알림을 모두 읽음 처리합니다. 처리 대상 read_at 을 현재 시각으로 갱신하며, 응답 data.marked_count 에 읽음 처리된 건수를 반환합니다. 이미 읽음 상태인 알림은 대상에서 제외됩니다.

POST /api/admin/notifications/read-batch

  • 라우트명: api.admin.notifications.read-batch
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@markBatchAsRead
  • 인증/권한: auth:sanctum + permission:core.notifications.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
ids body array 예 min 1, max 100 대상 리소스 식별자 배열 (대량 작업 대상)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.notification.batch_read_validation_rules).

요청 예시

POST /api/admin/notifications/read-batch HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "ids": [
        "예시값"
    ]
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

ids 배열로 지정한 알림들을 일괄 읽음 처리합니다. 처리 대상은 요청 사용자 본인의 미읽음 알림 중 지정된 ID 에 해당하는 것으로 한정되며, 이미 읽음 상태이거나 본인 소유가 아닌 ID 는 무시됩니다. 응답 data.marked_count 에 실제 읽음 처리된 건수를 반환합니다. ids 는 최소 1개, 최대 100개까지 전달할 수 있습니다.

GET /api/admin/notifications/unread-count

  • 라우트명: api.admin.notifications.unread-count
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@unreadCount
  • 인증/권한: auth:sanctum + permission:core.notifications.read

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/admin/notifications/unread-count HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
unread_count integer 7 unread 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "미읽음 알림 수를 조회했습니다.",
    "data": {
        "unread_count": 7
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 관리자 본인의 미읽음 알림 개수를 집계해 data.unread_count 로 반환합니다. _admin_base.json 헤더 알림 벨의 미읽음 배지에 사용되며, WebSocket 으로 새 알림이 수신되면 이 값을 재조회해 갱신합니다.

DELETE /api/admin/notifications/{notification}

  • 라우트명: api.admin.notifications.destroy
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@destroy
  • 인증/권한: auth:sanctum + permission:core.notifications.delete

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification path string 예 — 대상 notification의 식별자

요청 예시

DELETE /api/admin/notifications/{notification} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

경로의 {notification} ID 에 해당하는 알림 1건을 삭제합니다. 대상은 요청 사용자 본인의 알림으로 한정되며, 해당 ID 가 본인 소유로 존재하지 않으면 404(notification.user.not_found)를 반환합니다.

PATCH /api/admin/notifications/{notification}/read

  • 라우트명: api.admin.notifications.read
  • 컨트롤러: App\Http\Controllers\Api\Admin\NotificationController@markAsRead
  • 인증/권한: auth:sanctum + permission:core.notifications.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification path string 예 — 대상 notification의 식별자

요청 예시

PATCH /api/admin/notifications/{notification}/read HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

경로의 {notification} ID 에 해당하는 알림 1건을 읽음 처리하고, 갱신된 알림 리소스를 data 로 반환합니다. 대상은 요청 사용자(관리자) 본인의 알림으로 한정되며, 본인 소유로 존재하지 않으면 404(notification.user.not_found)를 반환합니다. 반환 리소스에는 id, type, type_label, subject, body, url, read_at, created_at 가 포함됩니다.

GET /api/user/notifications

  • 라우트명: api.user.notifications.index
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@index
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.read

요청 파라미터

이름 위치 타입 필수 허용값 용도
read query string 아니오 unread, read, all 읽음 상태 필터 (unread: 미읽음(read_at null)만, read: 읽음(read_at not null)만, all: 전체). 미지정 시 전체
per_page query integer 아니오 min 1, max 100 페이지당 항목 수
page query integer 아니오 min 1 조회할 페이지 번호 (1부터 시작)
sort_order query string 아니오 asc, desc 정렬 방향 (asc 오름차순 / desc 내림차순)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.notification.index_validation_rules).

요청 예시

GET /api/user/notifications?read=unread&per_page=1&page=1&sort_order=asc HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

목록 응답: data.data[] 배열 항목의 필드 + data.pagination.

필드 타입 실측 예시값 용도/설명
number integer 23 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생)
id string 518b9c94-5853-4b68-8193-83af1851bbc6 기본 키 (내부 식별자)
type string inquiry_received
type_label string 상품 문의 접수 type 값의 사람이 읽는 라벨 (현지화/Enum 파생)
subject string 새로운 상품 문의가 접수되었습니다
body string 옥혜진님이 "면 손수건 3매입 #1" 상품에 문의를 남겼습니다.
url string https://g7_2.dev/admin/ecommerce/prod…
data object {"type":"inquiry_received","subject":"새로운 상품 문의가 접수되었습니다"…
read_at string 2026-07-31 22:06:53 read 일시
created_at string 2026-07-31 21:41:58 생성 일시

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "알림 목록을 조회했습니다.",
    "data": {
        "data": [
            {
                "number": 23,
                "id": "518b9c94-5853-4b68-8193-83af1851bbc6",
                "type": "inquiry_received",
                "type_label": "상품 문의 접수",
                "subject": "새로운 상품 문의가 접수되었습니다",
                "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                "url": "https://api.example.com/admin/ecommerce/product-inquiries",
                "data": {
                    "type": "inquiry_received",
                    "subject": "새로운 상품 문의가 접수되었습니다",
                    "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                    "click_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                    "data": {
                        "name": "최고관리자",
                        "app_name": "그누보드7",
                        "product_name": "면 손수건 3매입 #1",
                        "customer_name": "옥혜진",
                        "inquiry_content": "타인 계정 문의 3 입니다. 스코프 격리 검증용.",
                        "inquiry_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                        "site_url": "https://api.example.com"
                    }
                },
                "read_at": null,
                "created_at": "2026-07-31 21:41:58"
            },
            {
                "number": 22,
                "id": "75da60b8-3ec9-457f-ad8c-b52652f7adcf",
                "type": "inquiry_received",
                "type_label": "상품 문의 접수",
                "subject": "새로운 상품 문의가 접수되었습니다",
                "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                "url": "https://api.example.com/admin/ecommerce/product-inquiries",
                "data": {
                    "type": "inquiry_received",
                    "subject": "새로운 상품 문의가 접수되었습니다",
                    "body": "옥혜진님이 \"면 손수건 3매입 #1\" 상품에 문의를 남겼습니다.",
                    "click_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                    "data": {
                        "name": "최고관리자",
                        "app_name": "그누보드7",
                        "product_name": "면 손수건 3매입 #1",
                        "customer_name": "옥혜진",
                        "inquiry_content": "타인 계정 문의 2 입니다. 스코프 격리 검증용.",
                        "inquiry_url": "https://api.example.com/admin/ecommerce/product-inquiries",
                        "site_url": "https://api.example.com"
                    }
                },
                "read_at": null,
                "created_at": "2026-07-31 21:41:55"
            },
            "... (총 23건 중 2건 표시)"
        ],
        "pagination": {
            "current_page": 1,
            "last_page": 1,
            "per_page": 25,
            "total": 23,
            "from": 1,
            "to": 23,
            "has_more_pages": false
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 사용자 본인의 사이트내 알림 목록을 최신순(created_at desc)으로 페이지네이션해 반환합니다. read 파라미터로 미읽음(unread)·읽음(read)·전체(all, 기본)를 필터링하고, per_page 미지정 시 20건 단위로 반환합니다. 조회 대상은 항상 요청 사용자 본인의 알림으로 한정됩니다. _user_base.json 이 이 엔드포인트를 소비하며 WebSocket 알림 수신 시 갱신됩니다. 관리자 스코프(/api/admin/notifications)와 동일한 서비스·리소스를 사용하되 권한(core.user-notifications.*)과 기본 페이지 크기(20건)가 다릅니다.

DELETE /api/user/notifications/all

  • 라우트명: api.user.notifications.destroy-all
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@destroyAll
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.delete

요청 파라미터

요청 파라미터 없음.

요청 예시

DELETE /api/user/notifications/all HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
deleted_count integer 23 deleted 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "모든 알림이 삭제되었습니다.",
    "data": {
        "deleted_count": 23
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 사용자 본인의 모든 사이트내 알림(읽음·미읽음 무관)을 삭제합니다. 삭제 대상은 요청 사용자 본인의 알림으로만 한정되며, 응답 data.deleted_count 에 삭제된 건수를 반환합니다. 되돌릴 수 없는 작업입니다.

POST /api/user/notifications/read-all

  • 라우트명: api.user.notifications.read-all
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@markAllAsRead
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.update

요청 파라미터

요청 파라미터 없음.

요청 예시

POST /api/user/notifications/read-all HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
marked_count integer 7 marked 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "모든 알림을 읽음 처리했습니다.",
    "data": {
        "marked_count": 7
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 사용자 본인의 미읽음 알림을 모두 읽음 처리합니다. 처리 대상 read_at 을 현재 시각으로 갱신하며, 응답 data.marked_count 에 읽음 처리된 건수를 반환합니다. 이미 읽음 상태인 알림은 대상에서 제외됩니다.

POST /api/user/notifications/read-batch

  • 라우트명: api.user.notifications.read-batch
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@markBatchAsRead
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
ids body array 예 min 1, max 100 대상 리소스 식별자 배열 (대량 작업 대상)

이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (core.notification.batch_read_validation_rules).

요청 예시

POST /api/user/notifications/read-batch HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)
Content-Type: application/json

{
    "ids": [
        "예시값"
    ]
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

ids 배열로 지정한 알림들을 일괄 읽음 처리합니다. 처리 대상은 요청 사용자 본인의 미읽음 알림 중 지정된 ID 에 해당하는 것으로 한정되며, 이미 읽음 상태이거나 본인 소유가 아닌 ID 는 무시됩니다. 응답 data.marked_count 에 실제 읽음 처리된 건수를 반환합니다. ids 는 최소 1개, 최대 100개까지 전달할 수 있습니다.

GET /api/user/notifications/unread-count

  • 라우트명: api.user.notifications.unread-count
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@unreadCount
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.read

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/user/notifications/unread-count HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

단건 응답: data 객체의 필드.

필드 타입 실측 예시값 용도/설명
unread_count integer 7 unread 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "미읽음 알림 수를 조회했습니다.",
    "data": {
        "unread_count": 7
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

인증된 사용자 본인의 미읽음 알림 개수를 집계해 data.unread_count 로 반환합니다. _user_base.json 의 알림 미읽음 배지에 사용되며, WebSocket 으로 새 알림이 수신되면 이 값을 재조회해 갱신합니다.

DELETE /api/user/notifications/{notification}

  • 라우트명: api.user.notifications.destroy
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@destroy
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.delete

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification path string 예 — 대상 notification의 식별자

요청 예시

DELETE /api/user/notifications/{notification} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

경로의 {notification} ID 에 해당하는 알림 1건을 삭제합니다. 대상은 요청 사용자 본인의 알림으로 한정되며, 해당 ID 가 본인 소유로 존재하지 않으면 404(notification.user.not_found)를 반환합니다.

PATCH /api/user/notifications/{notification}/read

  • 라우트명: api.user.notifications.read
  • 컨트롤러: App\Http\Controllers\Api\Auth\NotificationController@markAsRead
  • 인증/권한: optional.sanctum (선택적 인증: 회원/비회원 모두 접근) + permission:core.user-notifications.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
notification path string 예 — 대상 notification의 식별자

요청 예시

PATCH /api/user/notifications/{notification}/read HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}   (optional.sanctum: 비회원은 헤더 생략 가능)

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(core.notifications.read)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

경로의 {notification} ID 에 해당하는 알림 1건을 읽음 처리하고, 갱신된 알림 리소스를 data 로 반환합니다. 대상은 요청 사용자 본인의 알림으로 한정되며, 본인 소유로 존재하지 않으면 404(notification.user.not_found)를 반환합니다. 반환 리소스에는 id, type, type_label, subject, body, url, read_at, created_at 가 포함됩니다.

Reference in New Issue View Git Blame Copy Permalink