Gnuboard7/modules/_bundled/sirsoft-board/docs/api/dashboard.md

Dashboard API 레퍼런스

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

---

TL;DR (5초 요약)

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

---

GET /api/modules/sirsoft-board/admin/dashboard/overview

• 라우트명: api.modules.sirsoft-board.admin.dashboard.overview
• 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\DashboardController@overview
• 인증/권한: auth:sanctum

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/modules/sirsoft-board/admin/dashboard/overview HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
today_posts	integer	0	오늘 등록된 새 게시글 수입니다. board_stats 집계 테이블의 오늘 행에서 읽으며, 행이 없으면 0 을 반환합니다(최대 1시간 지연).
today_comments	integer	0	오늘 등록된 새 댓글 수입니다. board_stats 집계 테이블의 오늘 행에서 읽으며, 행이 없으면 0 을 반환합니다(최대 1시간 지연).

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.dashboard.fetch_success",
    "data": {
        "today_posts": 0,
        "today_comments": 0
    }
}

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우

설명 관리자 대시보드 위젯에 표시할 오늘의 게시판 현황을 반환합니다. auth:sanctum 인증이 필요하며(대시보드 진입은 코어 core.dashboard.read 가드로 보호), 오늘 등록된 새 글 수(today_posts)와 새 댓글 수(today_comments)를 집계하여 반환합니다.

GET /api/modules/sirsoft-board/admin/dashboard/pending-reports

• 라우트명: api.modules.sirsoft-board.admin.dashboard.pending-reports
• 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\DashboardController@pendingReports
• 인증/권한: auth:sanctum

요청 파라미터

이름	위치	타입	필수	허용값	용도
limit	query	integer	아니오	min 1, max 50	반환할 최대 항목 수

요청 예시

GET /api/modules/sirsoft-board/admin/dashboard/pending-reports?limit=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
items	array	[{"id":7,"board_slug":"qna","board_name":"Q&A","target_ty…	전체 게시판을 가로질러 조회한 미처리 신고 항목 목록입니다. 각 항목은 신고 대상 게시판(board_slug/board_name), 대상 종류(target_type), 대상 제목/발췌(target_title/target_excerpt), 상태, 신고 시각을 포함합니다. limit 개까지 반환됩니다.
total	integer	16	전체 개수 (집계)

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.dashboard.fetch_success",
    "data": {
        "items": [
            {
                "id": 1,
                "board_slug": "apidoc-sample-board",
                "board_name": "API 문서 샘플 게시판",
                "target_type": "post",
                "target_type_label": "게시글",
                "target_post_id": 1,
                "target_title": "API 문서 샘플 게시글",
                "target_excerpt": null,
                "status": "pending",
                "status_label": "접수",
                "author_name": "API 문서 샘플 사용자",
                "last_reported_at": "4시간 전"
            }
        ],
        "total": 1
    }
}

에러 응답

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

설명 전체 게시판의 미처리 신고 목록과 총 건수를 대시보드 위젯에 표시하기 위해 반환합니다. auth:sanctum 인증이 필요하며(대시보드 진입은 코어 core.dashboard.read 가드로 보호), limit(1~50, 기본 5)으로 표시 건수를 제어합니다. 응답은 미처리 신고 항목(items)과 전체 미처리 건수(total)를 포함합니다.

GET /api/modules/sirsoft-board/admin/dashboard/post-graph

• 라우트명: api.modules.sirsoft-board.admin.dashboard.post-graph
• 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\DashboardController@postGraph
• 인증/권한: auth:sanctum

요청 파라미터

요청 파라미터 없음.

요청 예시

GET /api/modules/sirsoft-board/admin/dashboard/post-graph HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드	타입	실측 예시값	용도/설명
days	array	[{"date":"2026-07-01","post_count":0,"comment_count":0},{…	최근 7일간 일자별 집계 막대 배열입니다. 각 원소는 날짜(date)와 해당 일의 게시글 수(post_count)/댓글 수(comment_count)를 담으며, 집계 행이 없는 날은 0 으로 채워집니다.
total_posts	integer	0	이번 7일 기간의 게시글 합계입니다. days 의 post_count 를 합산한 값입니다.
total_comments	integer	0	이번 7일 기간의 댓글 합계입니다. days 의 comment_count 를 합산한 값입니다.
posts_change	null	null	직전 동일 7일 기간 대비 게시글 증감율(%)입니다. 소수점 첫째 자리까지 계산하며, 직전 기간 합이 0 이면 비교 기준이 없으므로 null 을 반환합니다(화면에서 '—' 폴백).
comments_change	null	null	직전 동일 7일 기간 대비 댓글 증감율(%)입니다. 소수점 첫째 자리까지 계산하며, 직전 기간 합이 0 이면 비교 기준이 없으므로 null 을 반환합니다(화면에서 '—' 폴백).
updated_at	null	null	최종 수정 일시
updated_at_display	string	``	집계 행의 최종 갱신 시각(updated_at)을 모듈 날짜 표시 형식(display.date_display_format 설정)으로 포맷한 표시용 문자열입니다. 집계 행이 없으면 빈 문자열입니다.

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.dashboard.fetch_success",
    "data": {
        "days": [
            {
                "date": "2026-07-02",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-03",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-04",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-05",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-06",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-07",
                "post_count": 0,
                "comment_count": 0
            },
            {
                "date": "2026-07-08",
                "post_count": 0,
                "comment_count": 0
            }
        ],
        "total_posts": 0,
        "total_comments": 0,
        "posts_change": null,
        "comments_change": null,
        "updated_at": null,
        "updated_at_display": ""
    }
}

에러 응답

상태코드	의미	발생 조건
401	Unauthenticated	유효한 Bearer 토큰이 없거나 만료된 경우

설명 대시보드 위젯의 추세 그래프에 표시할 최근 7일간 게시글/댓글 추이를 반환합니다. auth:sanctum 인증이 필요하며(대시보드 진입은 코어 core.dashboard.read 가드로 보호), 일자별 막대(days), 기간 합계(total_posts/total_comments), 이전 기간 대비 변화율(posts_change/comments_change), 갱신 시각(updated_at)을 포함합니다.

GET /api/modules/sirsoft-board/admin/dashboard/recent-posts

• 라우트명: api.modules.sirsoft-board.admin.dashboard.recent-posts
• 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\DashboardController@recentPosts
• 인증/권한: auth:sanctum

요청 파라미터

이름	위치	타입	필수	허용값	용도
limit	query	integer	아니오	min 1, max 50	반환할 최대 항목 수

요청 예시

GET /api/modules/sirsoft-board/admin/dashboard/recent-posts?limit=1 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

필드	타입	실측 예시값	용도/설명
id	integer	237	기본 키 (내부 식별자)
board_slug	string	apidoc-sample-board	게시글이 속한 게시판의 슬러그입니다. 대시보드에서 해당 게시판으로 이동할 때 식별자로 사용됩니다.
board_name	string	API 문서 샘플 게시판	게시글이 속한 게시판의 현재 로케일 표시명입니다(getLocalizedName).
title	string	API 문서 샘플 게시글	제목
author_name	string	API 문서 샘플 사용자	작성자 이름입니다. 회원 게시글은 연결된 사용자 이름을, 비회원 게시글은 작성 시 입력한 이름(author_name)을 사용합니다.
comments_count	integer	0	comments 개수 (집계)
created_at	string	4시간 전	생성 일시

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.dashboard.fetch_success",
    "data": [
        {
            "id": 1,
            "board_slug": "apidoc-sample-board",
            "board_name": "API 문서 샘플 게시판",
            "title": "API 문서 샘플 게시글",
            "author_name": "API 문서 샘플 사용자",
            "comments_count": 0,
            "created_at": "4시간 전"
        }
    ]
}

에러 응답

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

설명 전체 게시판에서 최신 게시글을 대시보드 위젯에 표시하기 위해 반환합니다. auth:sanctum 인증이 필요하며(대시보드 진입은 코어 core.dashboard.read 가드로 보호), limit(1~50, 기본 5)으로 표시 건수를 제어합니다. 각 항목은 게시판(board_slug/board_name), 제목, 작성자, 댓글 수, 작성 시각(상대 시간 표기)을 포함합니다.