gper/Gnuboard7
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cfc2caba1b87bc97b50986f09110e97ff947a694
Gnuboard7/modules/_bundled/sirsoft-board/docs/api/settings.md
T
HeuJung cfc2caba1b feat(ckeditor5,board,ecommerce,page,core,admin_basic): 미참조 에디터 업로드 이미지 정리 신설 + 업로드 고아 동종 결함 7건 전수 해소 
공개 (@Tuwasduliebst 제보) 대응.

- ckeditor5: 미참조 이미지 정리 엔진 신설 — 참조 판정(hash + 파일명 2토큰,
 filter_reference_sources 훅으로 확장 콘텐츠 등록) + 정리 커맨드(기본 꺼짐 옵트인,
 3중 게이트) + 업로드 관리 화면(권한 분리·참조 배지·개별/선택 삭제) + 기설치본
 설정 백필 upgrade step
- board: 임시 첨부 GC(상시) + 소프트삭제 첨부 영구 정리(옵트인) + 설정 UI,
 저장 payload 누락(F4)·빈 temp 디렉토리 잔존(F5) 수정
- ecommerce: 임시 상품 이미지 GC + 카테고리 삭제 시 이미지 파일 미삭제(S4) 수정
- page: 임시 첨부 GC
- 코어: 고아 첨부 정리 커맨드(옵트인, site_logo 보호) + 사이트 로고 교체 시
 구 로고 재편입 차단(S6) + DB 백업 미구현 501 정직화(B3) + 플러그인 관리자
 메뉴 설치·업데이트 자동 동기화(F1·F7)
- 동반: 플러그인 설정 검증 오류 필드명 라벨화(F3), Toggle 노드 type 정정
 수평 전개(marketing 1.0.2 bump·gdpr·ecommerce), ja 언어팩 4종, API 문서,
 hooks.md, 시나리오 매니페스트 8종, Playwright E2E 4종
2026-08-17 02:44:54 +09:00

43 KiB
Raw Blame History

Settings API 레퍼런스

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

TL;DR (5초 요약)

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

GET /api/modules/sirsoft-board/admin/settings

  • 라우트명: api.modules.sirsoft-board.admin.settings.index
  • 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\BoardSettingsController@index
  • 인증/권한: auth:sanctum + permission:sirsoft-board.settings.read

요청 파라미터

요청 파라미터 없음.

요청 예시

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

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
basic_defaults object {"type":"basic","per_page":20,"per_page_mobile":15,"order… 게시판 생성 시 적용되는 기본 설정 카테고리. 게시판 타입, 페이지당 글 수(PC/모바일), 정렬 기준/방향, 댓글·답글 사용 여부와 깊이, 제목·내용·댓글 길이 제한, 파일 업로드 허용/용량/개수/확장자, 새 글 표시 시간, 게시판 기본 권한(default_board_permissions) 등을 포함합니다.
report_policy object {"auto_hide_threshold":5,"auto_hide_target":"both","daily… 신고 정책 카테고리. 자동 숨김 임계치(auto_hide_threshold)와 대상(auto_hide_target: post/comment/both), 사용자별 일일 신고 한도, 신고 거부 누적 제한(횟수/기간), 관리자·작성자 신고 알림 발송 여부와 채널을 포함합니다.
spam_security object {"post_cooldown_seconds":0,"comment_cooldown_seconds":0,"… 스팸·보안 카테고리. 글·댓글·신고 작성 사이의 도배 방지 쿨다운 시간(초)과 조회수 캐시 TTL을 포함합니다.
display object {"date_display_format":"standard"} 표시 설정 카테고리. 날짜 표시 형식(date_display_format: standard 절대 표기 / relative 상대 표기)을 포함합니다.
seo object {"meta_boards_title":"{site_name}","meta_boards_descripti… SEO 메타 태그 설정 카테고리. 게시판 목록/개별 게시판/글 상세 페이지의 메타 제목·설명 템플릿과 각 페이지의 SEO 생성 활성화 여부(seo_boards, seo_board, seo_post_detail)를 포함합니다.
notifications object {"channels":[{"id":"mail","is_active":true,"sort_order":0… 알림 채널 설정 카테고리. 각 채널(mail, database 등)의 식별자, 활성화 여부(is_active), 정렬 순서(sort_order)를 담은 channels 배열을 포함합니다.
report_permissions object {"view_roles":["admin","manager"],"manage_roles":["admin"]} 신고 관리 권한 역할. 신고 내역을 조회할 수 있는 역할(view_roles)과 신고를 처리·관리할 수 있는 역할(manage_roles)의 식별자 배열이며, 설정값이 아닌 DB 권한 데이터로 관리됩니다.
abilities object {"can_update":true} 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반)
_meta object {"limits":{"per_page_min":5,"per_page_max":100,"min_title… 편집 UI 보조 메타데이터. limits에 config('sirsoft-board.limits') 기반 입력 제한값(페이지당 글 수·답글/댓글 깊이의 최소·최대 등)이 담겨 프론트 입력 검증 범위로 사용됩니다.

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.settings.fetch_success",
    "data": {
        "basic_defaults": {
            "type": "basic",
            "per_page": 20,
            "per_page_mobile": 15,
            "order_by": "created_at",
            "order_direction": "DESC",
            "secret_mode": "{MASKED}",
            "use_comment": true,
            "use_reply": true,
            "max_reply_depth": 5,
            "max_comment_depth": 10,
            "comment_order": "ASC",
            "show_view_count": true,
            "use_report": false,
            "min_title_length": 2,
            "max_title_length": 200,
            "min_content_length": 2,
            "max_content_length": 10000,
            "min_comment_length": 2,
            "max_comment_length": 1000,
            "use_file_upload": false,
            "max_file_size": 10,
            "max_file_count": 5,
            "allowed_extensions": [
                "jpg",
                "jpeg",
                "png",
                "gif",
                "webp",
                "pdf",
                "doc",
                "docx",
                "xls",
                "xlsx",
                "ppt",
                "pptx",
                "hwp",
                "txt",
                "zip"
            ],
            "notify_admin_on_post": true,
            "notify_author": true,
            "new_display_hours": 24,
            "blocked_keywords": [
                "시발",
                "씨발",
                "ㅅㅂ",
                "ㅆㅂ",
                "좆",
                "ㅈㄴ",
                "존나",
                "씹",
                "지랄",
                "ㅈㄹ",
                "개새끼",
                "새끼",
                "ㅅㄲ",
                "개자식",
                "병신",
                "ㅂㅅ",
                "미친놈",
                "미친년",
                "느금마",
                "니애미",
                "느금",
                "엠창",
                "엠뒤",
                "빡대가리",
                "개같은",
                "개년",
                "개놈",
                "개돼지",
                "개씹",
                "개쓰레기",
                "닥쳐",
                "꺼져",
                "죽어",
                "자살해",
                "뒤져",
                "저능아",
                "정신병자",
                "썅",
                "쌍놈",
                "쌍년",
                "쉬발",
                "쒸발",
                "시팔",
                "씨팔",
                "한남",
                "한녀",
                "김치녀",
                "된장녀",
                "맘충",
                "틀딱",
                "느개비",
                "장애인놈",
                "병신새끼",
                "흑형",
                "짱깨",
                "쪽바리",
                "왜놈",
                "튀기",
                "똥남아",
                "야동",
                "포르노",
                "섹스",
                "야사",
                "음란",
                "성인사이트",
                "조건만남",
                "원나잇",
                "섹파",
                "오피",
                "키스방",
                "매춘",
                "성매매",
                "몸파는"
            ],
            "default_board_permissions": {
                "admin.posts.read": [
                    "admin"
                ],
                "admin.posts.write": [
                    "admin"
                ],
                "admin.posts.read-secret": [
                    "admin"
                ],
                "admin.comments.read": [
                    "admin"
                ],
                "admin.comments.write": [
                    "admin"
                ],
                "admin.attachments.upload": [
                    "admin"
                ],
                "admin.attachments.download": [
                    "admin"
                ],
                "admin.manage": [
                    "admin"
                ],
                "posts.read": [
                    "admin",
                    "user",
                    "guest"
                ],
                "posts.write": [
                    "admin",
                    "user"
                ],
                "posts.read-secret": [
                    "admin"
                ],
                "comments.read": [
                    "admin",
                    "user",
                    "guest"
                ],
                "comments.write": [
                    "admin",
                    "user"
                ],
                "attachments.upload": [
                    "admin",
                    "user"
                ],
                "attachments.download": [
                    "admin",
                    "user",
                    "guest"
                ],
                "manager": [
                    "admin"
                ]
            }
        },
        "report_policy": {
            "auto_hide_threshold": 5,
            "auto_hide_target": "both",
            "daily_report_limit": 10,
            "rejection_limit_count": 5,
            "rejection_limit_days": 30,
            "notify_admin_on_report": true,
            "notify_admin_on_report_scope": "per_case",
            "notify_admin_on_report_channels": [
                "mail",
                "database"
            ],
            "notify_author_on_report_action": true,
            "notify_author_on_report_action_channels": [
                "mail",
                "database"
            ]
        },
        "spam_security": {
            "post_cooldown_seconds": 0,
            "comment_cooldown_seconds": 0,
            "report_cooldown_seconds": 60,
            "view_count_cache_ttl": 86400
        },
        "display": {
            "date_display_format": "standard"
        },
        "seo": {
            "meta_boards_title": "{site_name}",
            "meta_boards_description": "",
            "meta_board_title": "{board_name}",
            "meta_board_description": "{board_description}",
            "meta_post_title": "{board_name} - {post_title}",
            "meta_post_description": "",
            "seo_boards": true,
            "seo_board": true,
            "seo_post_detail": true
        },
        "notifications": {
            "channels": [
                {
                    "id": "mail",
                    "is_active": true,
                    "sort_order": 0
                },
                {
                    "id": "database",
                    "is_active": true,
                    "sort_order": 1
                }
            ]
        },
        "report_permissions": {
            "view_roles": [
                "admin",
                "apidoc-sample-role"
            ],
            "manage_roles": [
                "admin",
                "apidoc-sample-role"
            ]
        },
        "abilities": {
            "can_update": true
        },
        "_meta": {
            "limits": {
                "per_page_min": 5,
                "per_page_max": 100,
                "min_title_length_min": 0,
                "min_title_length_max": 200,
                "max_title_length_min": 1,
                "max_title_length_max": 1000,
                "min_content_length_min": 0,
                "min_content_length_max": 10000,
                "max_content_length_min": 1,
                "max_content_length_max": 100000,
                "min_comment_length_min": 0,
                "min_comment_length_max": 1000,
                "max_comment_length_min": 1,
                "max_comment_length_max": 10000,
                "max_file_size_min": 1,
                "max_file_size_max": 200,
                "max_file_count_min": 1,
                "max_file_count_max": 20,
                "category_max": 50,
                "max_reply_depth_min": 1,
                "max_reply_depth_max": 10,
                "max_comment_depth_min": 0,
                "max_comment_depth_max": 10
            }
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-board.settings.read)이 없는 경우

설명 게시판 모듈의 전체 환경설정을 조회합니다. auth:sanctum 인증과 sirsoft-board.settings.read 권한이 필요합니다. 기본값(basic_defaults)/신고정책(report_policy)/스팸·보안(spam_security)/표시(display)/SEO/알림(notifications) 등 모든 카테고리 설정과 신고 권한 역할(report_permissions)을 함께 반환하며, 현재 사용자의 수정 가능 여부(abilities)와 입력 제한값(_meta.limits, config('sirsoft-board.limits'))을 포함합니다.

PUT /api/modules/sirsoft-board/admin/settings

  • 라우트명: api.modules.sirsoft-board.admin.settings.store
  • 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\BoardSettingsController@store
  • 인증/권한: auth:sanctum + permission:sirsoft-board.settings.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
_tab body string 아니오 basic_defaults, report_policy, spam_security, general, seo, notifications, notification_definitions 현재 편집 중인 탭을 나타내는 메타 값. 탭 단위 부분 저장의 컨텍스트를 식별하는 용도이며 설정값으로는 저장되지 않습니다.
notifications body array 아니오 — 알림 채널 설정. channels 배열의 각 항목에 채널 식별자(id), 활성화 여부(is_active), 정렬 순서(sort_order)를 담아 저장합니다.
basic_defaults body array 아니오 — 기본 설정 카테고리 값. 게시판 타입·페이지당 글 수·정렬·댓글/답글·길이 제한·파일 업로드·기본 권한 등 basic_defaults 하위 키를 저장합니다. basic_defaults.allowed_extensions 는 basic_defaults.use_file_upload 가 true 일 때만 최소 1개가 필수이며, false/null 이면 검증에서 제외되어 빈 배열도 허용됩니다. min_title_length·min_comment_length·new_display_hours 의 하한은 config('sirsoft-board.limits') 선언을 따르며 0 을 허용합니다.
report_policy body array 아니오 — 신고 정책 카테고리 값. 자동 숨김 임계치/대상, 일일 신고 한도, 거부 누적 제한, 관리자·작성자 신고 알림 설정을 저장합니다.
report_policy.auto_hide_threshold body integer 아니오 min 0, max 100 자동 숨김 신고 수 (이 횟수 이상 신고되면 자동 숨김 처리)
report_policy.auto_hide_target body string 아니오 post, comment, both 자동 숨김 대상 (게시글 / 댓글 / 둘 다)
report_policy.daily_report_limit body integer 아니오 min 0, max 100 사용자별 일일 신고 한도
report_policy.rejection_limit_count body integer 아니오 min 0, max 50 신고 기각 한도 (누적 기각 횟수 제한)
report_policy.rejection_limit_days body integer 아니오 min 1, max 365 신고 기각 한도 산정 기간(일)
report_policy.notify_admin_on_report body boolean 아니오 — 신고 접수 시 관리자 알림 발송 여부
report_policy.notify_admin_on_report_scope body string 아니오 per_case, per_report 관리자 신고 알림 발송 단위 (신고 대상 건별 / 개별 신고마다)
report_policy.notify_admin_on_report_channels body array 아니오 — 관리자 신고 알림 발송 채널 목록
report_policy.notify_author_on_report_action body boolean 아니오 — 신고 처리 결과를 작성자에게 알릴지 여부
report_policy.notify_author_on_report_action_channels body array 아니오 — 작성자 신고 처리 알림 발송 채널 목록
report_permissions body array 아니오 — 신고 관리 권한 역할. view_roles(조회 역할)와 manage_roles(관리 역할)의 역할 식별자 배열이며, 포함 시 설정 저장과 별개로 DB 권한 역할이 동기화됩니다.
report_permissions.view_roles body array 아니오 min 1 신고 조회 권한 역할 목록 (report_permissions 포함 시 필수, 최소 1개)
report_permissions.manage_roles body array 아니오 min 1 신고 처리 권한 역할 목록 (report_permissions 포함 시 필수, 최소 1개)
display body array 아니오 — 표시 설정 카테고리 값. 날짜 표시 형식(date_display_format: standard/relative) 등을 저장합니다.
display.date_display_format body string 아니오 standard, relative 날짜 표시 형식 (standard: 절대 표기 / relative: "3분 전" 형태의 상대 표기)
spam_security body array 아니오 — 스팸·보안 카테고리 값. 글·댓글·신고 작성 쿨다운 시간(초)과 조회수 캐시 TTL을 저장합니다.
spam_security.post_cooldown_seconds body integer 아니오 min 0, max 3600 게시글 작성 쿨다운(초). 도배 방지를 위한 연속 작성 대기 시간 (0이면 제한 없음)
spam_security.comment_cooldown_seconds body integer 아니오 min 0, max 3600 댓글 작성 쿨다운(초)
spam_security.report_cooldown_seconds body integer 아니오 min 0, max 3600 신고 쿨다운(초)
spam_security.view_count_cache_ttl body integer 아니오 min 60, max 604800 조회수 캐시 유효시간(초). 동일 사용자의 중복 조회수 증가를 막는 기간
seo body array 아니오 — SEO 설정 카테고리 값. 게시판 목록/개별/글 상세 페이지의 메타 제목·설명 템플릿과 각 페이지 SEO 활성화 여부를 저장합니다.
seo.meta_boards_title body string 아니오 max 500 게시판 목록 페이지의 메타 제목 템플릿 (예: {site_name})
seo.meta_boards_description body string 아니오 max 1000 게시판 목록 페이지의 메타 설명 템플릿
seo.meta_board_title body string 아니오 max 500 개별 게시판 페이지의 메타 제목 템플릿 (예: {board_name})
seo.meta_board_description body string 아니오 max 1000 개별 게시판 페이지의 메타 설명 템플릿 (예: {board_description})
seo.meta_post_title body string 아니오 max 500 게시글 상세 페이지의 메타 제목 템플릿 (예: {board_name} - {post_title})
seo.meta_post_description body string 아니오 max 1000 게시글 상세 페이지의 메타 설명 템플릿
seo.seo_boards body boolean 아니오 — 게시판 목록 페이지의 SEO 페이지 생성 활성화 여부
seo.seo_board body boolean 아니오 — 개별 게시판 페이지의 SEO 페이지 생성 활성화 여부
seo.seo_post_detail body boolean 아니오 — 게시글 상세 페이지의 SEO 페이지 생성 활성화 여부
attachment_settings body array 아니오 — 첨부 정리 정책 카테고리 값. 삭제된 첨부의 물리 파일을 언제 파기할지 정합니다.
attachment_settings.purge_enabled body boolean 아니오 — 삭제 첨부 영구 정리 활성화 여부. 기본 false — 사용자 파일을 실제로 파기하므로 운영자가 직접 켜야 동작합니다. 예약 작업(sirsoft-board:prune-attachments --scheduled)이 이 값을 false 폴백으로 재확인합니다.
attachment_settings.purge_retention_days body integer 아니오 min 1, max 3650 삭제 첨부 보존기간(일, 기본 30). 게시글을 휴지통에서 복원하면 이 기간 안의 첨부는 함께 복원되므로, 휴지통 복원 가능 기간과 같게 유지해야 합니다. 하한·상한은 config('sirsoft-board.limits') 가 정하며 화면 입력도 같은 값을 읽습니다.

요청 예시

PUT /api/modules/sirsoft-board/admin/settings HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "_tab": "basic_defaults",
    "notifications": [
        "예시값"
    ],
    "notifications.channels": [
        "예시값"
    ],
    "basic_defaults": [
        "예시값"
    ],
    "basic_defaults.type": "예시값",
    "basic_defaults.per_page": 1,
    "basic_defaults.per_page_mobile": 1,
    "basic_defaults.order_by": "created_at",
    "basic_defaults.order_direction": "ASC",
    "basic_defaults.secret_mode": "disabled",
    "basic_defaults.use_comment": true,
    "basic_defaults.use_reply": true,
    "basic_defaults.max_reply_depth": 1,
    "basic_defaults.max_comment_depth": 1,
    "basic_defaults.comment_order": "ASC",
    "basic_defaults.show_view_count": true,
    "basic_defaults.use_report": true,
    "basic_defaults.min_title_length": 1,
    "basic_defaults.max_title_length": 1,
    "basic_defaults.min_content_length": 1,
    "basic_defaults.max_content_length": 1,
    "basic_defaults.min_comment_length": 1,
    "basic_defaults.max_comment_length": 1,
    "basic_defaults.use_file_upload": true,
    "basic_defaults.max_file_size": 1,
    "basic_defaults.max_file_count": 1,
    "basic_defaults.blocked_keywords": [
        "예시값"
    ],
    "basic_defaults.allowed_extensions": [
        "예시값"
    ],
    "basic_defaults.notify_admin_on_post": true,
    "basic_defaults.notify_author": true,
    "basic_defaults.new_display_hours": 1,
    "basic_defaults.default_board_permissions": [
        "예시값"
    ],
    "report_policy": [
        "예시값"
    ],
    "report_policy.auto_hide_threshold": 1,
    "report_policy.auto_hide_target": "post",
    "report_policy.daily_report_limit": 1,
    "report_policy.rejection_limit_count": 1,
    "report_policy.rejection_limit_days": 1,
    "report_policy.notify_admin_on_report": true,
    "report_policy.notify_admin_on_report_scope": "per_case",
    "report_policy.notify_admin_on_report_channels": [
        "예시값"
    ],
    "report_policy.notify_author_on_report_action": true,
    "report_policy.notify_author_on_report_action_channels": [
        "예시값"
    ],
    "report_permissions": [
        "예시값"
    ],
    "report_permissions.view_roles": [
        "예시값"
    ],
    "report_permissions.manage_roles": [
        "예시값"
    ],
    "display": [
        "예시값"
    ],
    "display.date_display_format": "standard",
    "spam_security": [
        "예시값"
    ],
    "spam_security.post_cooldown_seconds": 1,
    "spam_security.comment_cooldown_seconds": 1,
    "spam_security.report_cooldown_seconds": 1,
    "spam_security.view_count_cache_ttl": 1,
    "seo": [
        "예시값"
    ],
    "seo.meta_boards_title": "예시 제목",
    "seo.meta_boards_description": "예시 내용입니다.",
    "seo.meta_board_title": "예시 제목",
    "seo.meta_board_description": "예시 내용입니다.",
    "seo.meta_post_title": "예시 제목",
    "seo.meta_post_description": "예시 내용입니다.",
    "seo.seo_boards": true,
    "seo.seo_board": true,
    "seo.seo_post_detail": true
}

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
basic_defaults object {"type":"basic","per_page":20,"per_page_mobile":15,"order… 저장 후 갱신된 기본 설정 카테고리. 게시판 타입, 페이지당 글 수(PC/모바일), 정렬 기준/방향, 댓글·답글 사용 여부와 깊이, 제목·내용·댓글 길이 제한, 파일 업로드 허용/용량/개수/확장자, 새 글 표시 시간, 게시판 기본 권한(default_board_permissions) 등을 포함합니다.
report_policy object {"auto_hide_threshold":5,"auto_hide_target":"both","daily… 저장 후 갱신된 신고 정책 카테고리. 자동 숨김 임계치(auto_hide_threshold)와 대상(auto_hide_target: post/comment/both), 사용자별 일일 신고 한도, 신고 거부 누적 제한(횟수/기간), 관리자·작성자 신고 알림 발송 여부와 채널을 포함합니다.
spam_security object {"post_cooldown_seconds":0,"comment_cooldown_seconds":0,"… 저장 후 갱신된 스팸·보안 카테고리. 글·댓글·신고 작성 사이의 도배 방지 쿨다운 시간(초)과 조회수 캐시 TTL을 포함합니다.
display object {"date_display_format":"standard"} 저장 후 갱신된 표시 설정 카테고리. 날짜 표시 형식(date_display_format: standard 절대 표기 / relative 상대 표기)을 포함합니다.
seo object {"meta_boards_title":"{site_name}","meta_boards_descripti… 저장 후 갱신된 SEO 메타 태그 설정 카테고리. 게시판 목록/개별 게시판/글 상세 페이지의 메타 제목·설명 템플릿과 각 페이지의 SEO 생성 활성화 여부(seo_boards, seo_board, seo_post_detail)를 포함합니다.
notifications object {"channels":[{"id":"mail","is_active":true,"sort_order":0… 저장 후 갱신된 알림 채널 설정 카테고리. 각 채널(mail, database 등)의 식별자, 활성화 여부(is_active), 정렬 순서(sort_order)를 담은 channels 배열을 포함합니다.
report_permissions object {"view_roles":[],"manage_roles":[]} 저장 후 동기화된 신고 관리 권한 역할. 신고 내역을 조회할 수 있는 역할(view_roles)과 신고를 처리·관리할 수 있는 역할(manage_roles)의 식별자 배열이며, 요청에 포함된 경우 DB 권한 역할로 동기화되어 반환됩니다.

응답 예시

HTTP/1.1 200

{
    "success": true,
    "message": "sirsoft-board::messages.settings.save_success",
    "data": {
        "basic_defaults": {
            "type": "basic",
            "per_page": 20,
            "per_page_mobile": 15,
            "order_by": "created_at",
            "order_direction": "DESC",
            "secret_mode": "{MASKED}",
            "use_comment": true,
            "use_reply": true,
            "max_reply_depth": 5,
            "max_comment_depth": 10,
            "comment_order": "ASC",
            "show_view_count": true,
            "use_report": false,
            "min_title_length": 2,
            "max_title_length": 200,
            "min_content_length": 2,
            "max_content_length": 10000,
            "min_comment_length": 2,
            "max_comment_length": 1000,
            "use_file_upload": false,
            "max_file_size": 10,
            "max_file_count": 5,
            "allowed_extensions": [
                "jpg",
                "jpeg",
                "png",
                "gif",
                "webp",
                "pdf",
                "doc",
                "docx",
                "xls",
                "xlsx",
                "ppt",
                "pptx",
                "hwp",
                "txt",
                "zip"
            ],
            "notify_admin_on_post": true,
            "notify_author": true,
            "new_display_hours": 24,
            "blocked_keywords": [
                "시발",
                "씨발",
                "ㅅㅂ",
                "ㅆㅂ",
                "좆",
                "ㅈㄴ",
                "존나",
                "씹",
                "지랄",
                "ㅈㄹ",
                "개새끼",
                "새끼",
                "ㅅㄲ",
                "개자식",
                "병신",
                "ㅂㅅ",
                "미친놈",
                "미친년",
                "느금마",
                "니애미",
                "느금",
                "엠창",
                "엠뒤",
                "빡대가리",
                "개같은",
                "개년",
                "개놈",
                "개돼지",
                "개씹",
                "개쓰레기",
                "닥쳐",
                "꺼져",
                "죽어",
                "자살해",
                "뒤져",
                "저능아",
                "정신병자",
                "썅",
                "쌍놈",
                "쌍년",
                "쉬발",
                "쒸발",
                "시팔",
                "씨팔",
                "한남",
                "한녀",
                "김치녀",
                "된장녀",
                "맘충",
                "틀딱",
                "느개비",
                "장애인놈",
                "병신새끼",
                "흑형",
                "짱깨",
                "쪽바리",
                "왜놈",
                "튀기",
                "똥남아",
                "야동",
                "포르노",
                "섹스",
                "야사",
                "음란",
                "성인사이트",
                "조건만남",
                "원나잇",
                "섹파",
                "오피",
                "키스방",
                "매춘",
                "성매매",
                "몸파는"
            ],
            "default_board_permissions": {
                "admin.posts.read": [
                    "admin"
                ],
                "admin.posts.write": [
                    "admin"
                ],
                "admin.posts.read-secret": [
                    "admin"
                ],
                "admin.comments.read": [
                    "admin"
                ],
                "admin.comments.write": [
                    "admin"
                ],
                "admin.attachments.upload": [
                    "admin"
                ],
                "admin.attachments.download": [
                    "admin"
                ],
                "admin.manage": [
                    "admin"
                ],
                "posts.read": [
                    "admin",
                    "user",
                    "guest"
                ],
                "posts.write": [
                    "admin",
                    "user"
                ],
                "posts.read-secret": [
                    "admin"
                ],
                "comments.read": [
                    "admin",
                    "user",
                    "guest"
                ],
                "comments.write": [
                    "admin",
                    "user"
                ],
                "attachments.upload": [
                    "admin",
                    "user"
                ],
                "attachments.download": [
                    "admin",
                    "user",
                    "guest"
                ],
                "manager": [
                    "admin"
                ]
            }
        },
        "report_policy": {
            "auto_hide_threshold": 5,
            "auto_hide_target": "both",
            "daily_report_limit": 10,
            "rejection_limit_count": 5,
            "rejection_limit_days": 30,
            "notify_admin_on_report": true,
            "notify_admin_on_report_scope": "per_case",
            "notify_admin_on_report_channels": [
                "mail",
                "database"
            ],
            "notify_author_on_report_action": true,
            "notify_author_on_report_action_channels": [
                "mail",
                "database"
            ]
        },
        "spam_security": {
            "post_cooldown_seconds": 0,
            "comment_cooldown_seconds": 0,
            "report_cooldown_seconds": 60,
            "view_count_cache_ttl": 86400
        },
        "display": {
            "date_display_format": "standard"
        },
        "seo": {
            "meta_boards_title": "{site_name}",
            "meta_boards_description": "",
            "meta_board_title": "{board_name}",
            "meta_board_description": "{board_description}",
            "meta_post_title": "{board_name} - {post_title}",
            "meta_post_description": "",
            "seo_boards": true,
            "seo_board": true,
            "seo_post_detail": true
        },
        "notifications": {
            "channels": [
                {
                    "id": "mail",
                    "is_active": true,
                    "sort_order": 0
                },
                {
                    "id": "database",
                    "is_active": true,
                    "sort_order": 1
                }
            ]
        },
        "report_permissions": {
            "view_roles": [],
            "manage_roles": []
        }
    }
}

에러 응답

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

설명 게시판 모듈의 환경설정을 저장합니다. auth:sanctum 인증과 sirsoft-board.settings.update 권한이 필요합니다. _tab으로 지정한 탭 단위로 검증된 설정을 저장하며, report_permissions가 포함된 경우 신고 권한 역할도 함께 동기화합니다. 저장 성공 시 갱신된 전체 설정과 신고 권한 역할을 반환합니다.

저장이 성공하면 코어 모듈 설정 저장 훅(core.module_settings.after_save)이 ('sirsoft-board', 저장한 카테고리 배열, true) 페이로드로 발화합니다. 이 훅을 구독하는 리스너가 게시판 SEO 미리 생성 캐시를 무효화하고 설정 변경을 활동 로그에 남기므로, 확장도 같은 훅으로 저장 완료 시점에 개입할 수 있습니다. 검증 실패(422)나 저장 실패 시에는 발화하지 않습니다.

POST /api/modules/sirsoft-board/admin/settings/bulk-apply

  • 라우트명: api.modules.sirsoft-board.admin.settings.bulk-apply
  • 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\BoardSettingsController@bulkApply
  • 인증/권한: auth:sanctum + permission:sirsoft-board.settings.update

요청 파라미터

이름 위치 타입 필수 허용값 용도
fields body array 예 min 1 대상 게시판에 일괄 적용할 필드 목록(최소 1개). boards 테이블 컬럼(type, per_page, use_comment, allowed_extensions 등)이나 권한 필드(default_board_permissions, manager), 점(.)을 포함한 개별 권한 키(예: posts.read)를 허용합니다.
apply_all body boolean 예 — 전체 게시판 적용 여부. true면 모든 게시판에 적용하고, false면 board_ids로 지정한 게시판에만 적용합니다(false 시 board_ids 필수).
board_ids body array 아니오 — board 식별자 배열
override_values body array 아니오 — 환경설정 기본값 대신 사용할 재정의 값 맵. 지정한 필드에 대해 기본값이 아닌 임의의 값으로 일괄 적용할 때 사용합니다.

요청 예시

POST /api/modules/sirsoft-board/admin/settings/bulk-apply HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json

{
    "fields": [
        "예시값"
    ],
    "apply_all": true,
    "board_ids": [
        "예시값"
    ],
    "override_values": [
        "예시값"
    ]
}

응답 필드 (data 내부)

단건 응답: data 객체의 필드. 성공(전체 적용 완료) 시와 중단(전체 롤백) 시의 필드 구성이 다릅니다 — 두 경우 모두 HTTP 200 입니다.

성공 시 (rolled_back: false)

필드 타입 실측 예시값 용도/설명
updated_count integer 3 실제로 설정이 적용된 게시판 수 (BoardService::bulkApplySettings() 반환값)
rolled_back boolean false 롤백 발생 여부. 성공 시 항상 false

중단·롤백 시 (rolled_back: true, BulkApplyAbortedException)

필드 타입 실측 예시값 용도/설명
rolled_back boolean true 적용 도중 실패해 전체 변경이 롤백되었음을 나타냅니다
board object|null {"board_id":12,"slug":"notice","name":"공지사항"} 실패한 게시판 정보(board_id, slug, name). 컬럼 일괄 업데이트(단일 쿼리) 실패 시 게시판 특정이 불가하므로 null
board.board_id integer 12 실패한 게시판 ID
board.slug string notice 실패한 게시판 슬러그
board.name string 공지사항 실패한 게시판의 현재 로케일 이름
failed_at integer|null 2 실패 순번(1-base). 컬럼 업데이트 실패 시 null
total integer 5 일괄 적용 대상 게시판 총 수

응답 예시

성공 시

{
    "success": true,
    "message": "sirsoft-board::messages.settings.bulk_apply_success",
    "data": {
        "updated_count": 3,
        "rolled_back": false
    }
}

중단·롤백 시 (HTTP 200)

{
    "success": true,
    "message": "sirsoft-board::messages.settings.bulk_apply_aborted",
    "data": {
        "rolled_back": true,
        "board": {
            "board_id": 12,
            "slug": "notice",
            "name": "공지사항"
        },
        "failed_at": 2,
        "total": 5
    }
}

message 는 컨트롤러가 넘기는 다국어 키(sirsoft-board::messages.settings.*)이며, 현재 모듈 lang/ko/messages.php 에 settings 그룹이 정의되어 있지 않아 키 문자열이 그대로 노출됩니다(다른 엔드포인트 실측 응답과 동일).

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-board.settings.update)이 없는 경우
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지). fields 누락/빈 배열, 허용되지 않은 필드명, apply_all=false 인데 board_ids 미지정, 존재하지 않는 board_ids 항목 등
500 Internal Server Error 일괄 적용 처리 중 롤백 예외 외의 오류가 발생한 경우 (messages.settings.bulk_apply_failed)

설명 환경설정의 기본값을 기존 게시판들에 일괄 적용합니다. auth:sanctum 인증과 sirsoft-board.settings.update 권한이 필요합니다. fields(적용할 필드, 최소 1개)와 apply_all(전체 적용 여부)을 받으며, apply_all이 false이면 board_ids로 대상을 지정하고 override_values로 값을 재정의할 수 있습니다. 적용 도중 실패하면 전체가 롤백되며, 이 경우에도 HTTP 200으로 rolled_back: true와 실패 지점 정보를 반환하여 프론트에서 안내 처리합니다.

POST /api/modules/sirsoft-board/admin/settings/clear-cache

  • 라우트명: api.modules.sirsoft-board.admin.settings.clear-cache
  • 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\BoardSettingsController@clearCache
  • 인증/권한: auth:sanctum + permission:sirsoft-board.settings.update

요청 파라미터

요청 파라미터 없음.

요청 예시

POST /api/modules/sirsoft-board/admin/settings/clear-cache HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
cleared boolean true 캐시 초기화 수행 여부. 성공 시 항상 true (ModuleSettings 캐시 + 게시판 캐시 전체 초기화)

응답 예시

{
    "success": true,
    "message": "sirsoft-board::messages.settings.clear_cache_success",
    "data": {
        "cleared": true
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-board.settings.update)이 없는 경우
500 Internal Server Error 캐시 초기화 중 오류가 발생한 경우 (messages.settings.clear_cache_error)

설명 게시판 모듈 설정 캐시를 초기화합니다. auth:sanctum 인증과 sirsoft-board.settings.update 권한이 필요합니다. ModuleSettings 캐시와 게시판 캐시를 모두 초기화하며, 응답으로 cleared: true를 반환합니다.

GET /api/modules/sirsoft-board/admin/settings/{category}

  • 라우트명: api.modules.sirsoft-board.admin.settings.show
  • 컨트롤러: Modules\Sirsoft\Board\Http\Controllers\Admin\BoardSettingsController@show
  • 인증/권한: auth:sanctum + permission:sirsoft-board.settings.read

요청 파라미터

이름 위치 타입 필수 허용값 용도
category path string 예 — 분류 필터 (해당 분류의 항목만 조회)

요청 예시

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

응답 필드 (data 내부)

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

필드 타입 실측 예시값 용도/설명
category string spam_security 요청 경로에서 전달된 카테고리명 (그대로 반환)
settings object {"post_cooldown_seconds":0,"comment_cooldown_seconds":0,"report_cooldown_seconds":60,"view_count_cache_ttl":86400} 해당 카테고리의 설정값 맵 (기본값 + 저장값 병합 결과). 정의되지 않은 카테고리명이면 빈 객체 {}
abilities object {"can_update":true} 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update — sirsoft-board.settings.update 권한 보유 여부)

응답 예시

{
    "success": true,
    "message": "sirsoft-board::messages.settings.fetch_success",
    "data": {
        "category": "spam_security",
        "settings": {
            "post_cooldown_seconds": 0,
            "comment_cooldown_seconds": 0,
            "report_cooldown_seconds": 60,
            "view_count_cache_ttl": 86400
        },
        "abilities": {
            "can_update": true
        }
    }
}

에러 응답

상태코드 의미 발생 조건
401 Unauthenticated 유효한 Bearer 토큰이 없거나 만료된 경우
403 Forbidden 요구 권한(sirsoft-board.settings.read)이 없는 경우
404 Not Found path 파라미터에 해당하는 리소스가 없는 경우
500 Internal Server Error 설정 조회 중 오류가 발생한 경우 (messages.settings.fetch_failed)

설명 특정 카테고리의 설정만 조회합니다. auth:sanctum 인증과 sirsoft-board.settings.read 권한이 필요합니다. 경로의 category에 해당하는 설정만 반환하며, 응답에는 카테고리명(category), 설정값(settings), 현재 사용자의 수정 가능 여부(abilities)가 포함됩니다.

Reference in new issue View Git Blame Copy Permalink