gper/Gnuboard7
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b587d71196aec76e2d4d53caa9f437de3e7fc34
Gnuboard7/docs/backend/api/notifications.md
T
HeuJung b5c0ec1178 fix(core,ecommerce,board,page,admin_basic,basic): 목록 응답의 하위 컬렉션 전량 직렬화 해소 
관리자 상품목록을 한 페이지 여는 것만으로 그 페이지 모든 상품의 옵션이 응답에 실렸다.
같은 패턴을 저장소 전역에서 찾아 14개 목록 엔드포인트를 함께 정리했다.

근본 원인은 둘이다. Resource 가 whenLoaded 로 방어하는데 Repository 가 목록 쿼리에서
관계를 무조건 로드해 가드가 항상 참이 되는 가짜 가드, 그리고 toListArray 경량 표현을
정의해 두고도 컬렉션이 toArray 를 부르는 목록/상세 미분리다. 둘 다 응답만 보면
정상이라 오류도 경고도 없이 페이로드만 불어난다.

목록은 화면이 실제로 그리는 것만 싣는다. 개수·합계는 PHP 컬렉션 연산이 아니라 DB
집계로, 대표 1건이 필요한 곳은 관계 자체를 oldestOfMany 로 좁힌다. eager load 의
limit(1) 은 부모별이 아니라 배치 쿼리 전체에 걸려 첫 행만 값을 갖게 되므로 쓸 수 없다.

뺀 값에는 대체 경로를 먼저 만들었다. 상품 옵션은 행을 펼칠 때 배치로 불러오고(상품 수와
무관하게 쿼리 상수), 종전 동작이 필요한 호출자를 위해 ?with_options=1 등 opt-in 을 남겼다.
배송정책 국가설정과 리뷰 첨부 이미지는 소비처를 실측한 결과 화면이 실제로 그리고 있어
제거하지 않았다 — 그 소비 사실을 회귀 테스트로 고정했다.

재발 방지로 정적 검사 룰 4종과 규정 문서 항목을 함께 넣었다.
2026-08-05 21:20:05 +09:00

34 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.delete)이 없는 경우

설명

인증된 관리자 본인의 모든 사이트내 알림(읽음·미읽음 무관)을 삭제합니다. 삭제 대상은 요청 사용자 본인의 알림으로만 한정되며, 응답 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.update)이 없는 경우

설명

인증된 관리자 본인의 미읽음 알림을 모두 읽음 처리합니다. 처리 대상 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.update)이 없는 경우
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)이 없는 경우

설명

인증된 관리자 본인의 미읽음 알림 개수를 집계해 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.delete)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명

경로의 {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.update)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명

경로의 {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
        }
    }
}

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-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
    }
}

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.delete)이 없는 경우

설명

인증된 사용자 본인의 모든 사이트내 알림(읽음·미읽음 무관)을 삭제합니다. 삭제 대상은 요청 사용자 본인의 알림으로만 한정되며, 응답 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
    }
}

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.update)이 없는 경우

설명

인증된 사용자 본인의 미읽음 알림을 모두 읽음 처리합니다. 처리 대상 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 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.update)이 없는 경우
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
    }
}

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.read)이 없는 경우

설명

인증된 사용자 본인의 미읽음 알림 개수를 집계해 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 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.delete)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명

경로의 {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 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
403 Forbidden 요구 권한(core.user-notifications.update)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우

설명

경로의 {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