gper/Gnuboard7
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9131ee6bb71bda4635673d46f147b339626dcb6f
Gnuboard7/modules/_bundled/sirsoft-page/docs/api/pages.md
T
HeuJung 6c8381f164 fix(core,board,ecommerce,plugins): API 문서 미채움 마커 전수 채움 + 미해석 lang 키 정정 + IDV 조회 시도횟수 비노출 
이슈 본연: API 레퍼런스의 미채움 마커 5종(실측 제외/TODO/필드 없음/대표 에러 없음)
1,194건을 코드에서 읽어 전수 채우고(0건), api:docgen 재생성이 사람이 채운 내용을
손실·열화시키던 멱등성 결함 4종(CRLF, 표 파이프 이스케이프, 에러 서술 보존, 중복
라우트명 키)을 근본 수정. --check 를 실측 제외와 드리프트가 구분되도록 재정의.
ParameterDescriber/ResourceFieldDescriber 에 leaf 폴백·SEO 스코프·공통 사전 확장.

파생 결함(문서 실측 중 발견): ResponseHelper 기본 메시지 키 6종이 존재하지 않는
messages.* 를 가리켜 응답 message 가 번역문 대신 키 문자열로 노출되던 문제를 common.*
으로 정정하고, 코어 7 + gdpr/marketing/pay_kginicis/verification/ecommerce 확장의
호출부와 누락 lang 키(게시판 10키 + 이커머스 category_images 4키 포함)를 ko/en/ja
전수 정정. 중복 그룹 키 2건은 기존 키로 호출부 통합.

보안: GET /api/identity/challenges/{id} 는 권한 가드 없는 공개 폴링 엔드포인트인데
Service::getStatus 가 attempts/max_attempts 를 응답에 담아 남은 시도 횟수를 추론할 수
있었다. 두 필드를 제거하고, 챌린지 화면(admin_basic/basic)의 서버 attempts 참조를
제거(남은 횟수 UI 는 query fallback + verify 실패 시 로컬 증가로 유지).

부수 정리(변경셋에 들어온 board 컨트롤러의 audit 사전 결함): FormRequest 4개 신설로
base Request 주입 제거, CommentController 의 Board 직접 호출을 BoardService 위임으로
전환, PHPDoc @return 보강. board 스위트에서 발견한 stale test 3건(seed SSoT 불일치,
admin 계정 user 역할 누락)도 같은 세션에서 정정.

버전 정렬(공개 release 기준): 코어 7.0.3→7.0.4, sirsoft-board 1.0.1→1.0.2,
verification_kginicis 1.0.0→1.0.1, admin_basic 1.0.1→1.0.4.
2026-08-06 14:16:40 +09:00

1318 lines
59 KiB
Markdown
Raw Blame History

# Pages API 레퍼런스
> **소유**: module `sirsoft-page` · **생성**: `php artisan api:docgen` (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
---
## TL;DR (5초 요약)
```text
1. 이 문서는 실제 API 호출로 실측한 Pages 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
```
---
### GET /api/modules/sirsoft-page/admin/pages
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.index -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.index`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@index`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| published | query | boolean | 아니오 | — | 발행 여부 (발행된 항목만 필터) |
| search | query | string | 아니오 | max 100 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
| search_field | query | string | 아니오 | `all`, `title`, `slug` | 검색 대상 필드명 (검색어를 적용할 컬럼) |
| filters | query | array | 아니오 | — | 추가 필터 조건 맵 (필드별 조건) |
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
| sort_by | query | string | 아니오 | `created_at`, `published_at` | 정렬 기준 필드명 |
| sort_order | query | string | 아니오 | `asc`, `desc` | 정렬 방향 (asc 오름차순 / desc 내림차순) |
**요청 예시**
```http
GET /api/modules/sirsoft-page/admin/pages?published=1&search=%EC%98%88%EC%8B%9C%EA%B0%92&search_field=all&filters=%EC%98%88%EC%8B%9C%EA%B0%92&per_page=1&page=1&sort_by=created_at&sort_order=asc HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_목록 응답: `data.data[]` 배열 항목의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `29` | 기본 키 (내부 식별자) |
| slug | string | `apidoc-sample-page` | URL 슬러그 (고유) |
| title | string | `API 문서 샘플 페이지` | 페이지 제목 (다국어 JSON) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string | `2026-07-06 23:57:18` | published 일시 |
| current_version | integer | `2` | 현재 버전 번호 |
| creator | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| created_at | string | `2026-07-06 23:57:18` | 생성 일시 |
| updated_at | string | `2026-07-06 23:57:18` | 최종 수정 일시 |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 정보를 조회했습니다.",
"data": {
"data": [
{
"id": 10,
"slug": "apidoc-sample-page",
"title": "API 문서 샘플 페이지",
"published": true,
"published_at": "2026-07-08 10:51:59",
"current_version": 2,
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 10:51:59",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
{
"id": 4,
"slug": "terms",
"title": "이용약관",
"published": true,
"published_at": "2026-07-08 10:44:43",
"current_version": 1,
"creator": null,
"created_at": "2026-07-08 10:44:43",
"updated_at": "2026-07-08 10:44:43",
"is_owner": false,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
},
"... (총 7건 중 2건 표시)"
],
"meta": {
"current_page": 1,
"last_page": 1,
"per_page": 25,
"total": 7
},
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.read`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
<!-- @generated:end -->
**설명** 관리자 페이지 목록을 조회합니다. `published`, `search`/`search_field`(제목·슬러그), `filters` 로 필터링하고 `sort_by`(created_at, published_at)·`sort_order` 로 정렬하며 `per_page`·`page` 로 페이지네이션합니다. `PageService::getPages()` 가 반환하는 `PageCollection` 으로 래핑되어 목록 항목마다 `is_owner`·`abilities` 권한 메타가 함께 내려갑니다. 관리자 페이지 관리 화면(목록 그리드)의 데이터 소스입니다.
### POST /api/modules/sirsoft-page/admin/pages
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.store -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.store`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@store`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.create`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| slug | body | string | 예 | max 255 | URL 친화 식별자 (slug) |
| title | body | array | 예 | — | 제목 |
| content | body | string | 아니오 | — | 본문 내용 |
| content_mode | body | string | 아니오 | `html`, `text` | 본문 편집 모드. `html` 은 리치 에디터 HTML, `text` 는 평문으로 저장·렌더링됩니다 (미지정 시 `html`) |
| published | body | boolean | 아니오 | — | 발행 여부 (발행된 항목만 필터) |
| seo_meta | body | array | 아니오 | — | SEO 메타 정보 맵. 하위 키 `title`(max 255)·`description`(max 500)·`keywords`(max 500)를 담습니다 |
| seo_meta.title | body | string | 아니오 | max 255 | SEO 메타 제목 (검색엔진/소셜 공유 표시 제목) |
| seo_meta.description | body | string | 아니오 | max 500 | SEO 메타 설명 (검색엔진/소셜 공유 표시 요약) |
| seo_meta.keywords | body | string | 아니오 | max 500 | SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분) |
| temp_key | body | string | 아니오 | max 64 | 저장 전 첨부 업로드 시 발급받은 임시 키. 생성된 페이지에 임시 첨부를 귀속시키는 데 사용합니다 |
**요청 예시**
```http
POST /api/modules/sirsoft-page/admin/pages HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"slug": "example-key",
"title": [
"예시 제목"
],
"content": "예시 내용입니다.",
"content_mode": "html",
"published": true,
"seo_meta": [
"예시값"
],
"seo_meta.title": "예시 제목",
"seo_meta.description": "예시 내용입니다.",
"seo_meta.keywords": "예시값",
"temp_key": "예시값"
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드 (`PageResource`, HTTP 201)._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `11` | 기본 키 (내부 식별자) |
| slug | string | `example-key` | URL 슬러그 (고유, 소문자·숫자·하이픈) |
| title | object | `{"ko":"예시 제목","en":"Example Title"}` | 페이지 제목 (다국어 JSON) |
| content | object | `{"ko":"<p>예시 내용입니다.</p>"}` | 페이지 본문 (다국어 JSON, 미입력 시 null) |
| content_mode | string | `html` | 본문 형식 (`html`, `text` — 미지정 시 `html`) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string\|null | `2026-07-08 10:51:59` | 발행 일시 (미발행 시 null) |
| seo_meta | object\|null | `{"title":"...","description":"...","keywords":"..."}` | SEO 메타 정보 (title, description, keywords) |
| current_version | integer | `1` | 현재 버전 번호 |
| creator | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 생성자 정보 (uuid/name — creator 관계 eager load) |
| updater | object\|null | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 최종 수정자 정보 (uuid/name — updater 관계 eager load) |
| attachments | array | `[]` | 페이지에 귀속된 첨부파일 목록 (`temp_key` 로 귀속된 임시 첨부 포함) |
| created_at | string | `2026-07-08 10:51:59` | 생성 일시 |
| updated_at | string | `2026-07-08 10:51:59` | 최종 수정 일시 |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자(`created_by`)인지 여부 |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
**응답 예시**
```http
HTTP/1.1 201
```
```json
{
"success": true,
"message": "페이지가 생성되었습니다.",
"data": {
"id": 11,
"slug": "example-key",
"title": {
"ko": "예시 제목",
"en": "Example Title"
},
"content": {
"ko": "<p>예시 내용입니다.</p>",
"en": "<p>Example body.</p>"
},
"content_mode": "html",
"published": true,
"published_at": "2026-07-08 10:51:59",
"seo_meta": {
"title": "예시 제목",
"description": "예시 내용입니다.",
"keywords": "예시,키워드"
},
"current_version": 1,
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"updater": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"attachments": [],
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 10:51:59",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.create`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 대표 케이스: `slug` 중복/형식 위반(소문자·숫자·하이픈만), `title` 누락 또는 기본 로케일 값 누락, `content_mode` 가 html/text 이외 |
| 500 | Internal Server Error | 생성 처리 중 예외 (`페이지 생성에 실패했습니다.`) |
<!-- @generated:end -->
**설명** 새 페이지를 생성합니다. `slug`(고유 필수)·`title`(다국어 배열 필수)·`content`·`content_mode`(html/text)·`published`·`seo_meta` 를 받아 `PageService::createPage()` 로 저장하고, `creator`/`updater`/`attachments` 를 eager load 한 `PageResource` 를 201 로 반환합니다. `temp_key` 는 페이지 저장 전 임시 업로드한 첨부(첨부 업로드 시 발급받은 키)를 생성된 페이지에 귀속시키는 데 씁니다.
### PATCH /api/modules/sirsoft-page/admin/pages/bulk-publish
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.bulk-publish -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.bulk-publish`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@bulkPublish`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| ids | body | array | 예 | min 1 | 대상 리소스 식별자 배열 (대량 작업 대상) |
| published | body | boolean | 예 | — | 발행 여부 (발행된 항목만 필터) |
**요청 예시**
```http
PATCH /api/modules/sirsoft-page/admin/pages/bulk-publish HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"ids": [
"예시값"
],
"published": true
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| count | integer | `3` | 실제로 발행 상태가 변경된 페이지 건수 (메시지의 `:count` 에도 동일 값이 치환됨) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "3개 페이지의 발행 상태가 변경되었습니다.",
"data": {
"count": 3
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 대표 케이스: `ids` 누락/빈 배열, `ids.*` 가 존재하지 않는 페이지 ID, `published` 누락 또는 boolean 아님 |
| 500 | Internal Server Error | 일괄 처리 중 예외 (`일괄 발행 상태 변경에 실패했습니다.`) |
<!-- @generated:end -->
**설명** 여러 페이지의 발행 상태를 한 번에 변경합니다. `ids`(대상 페이지 ID 배열, 최소 1개)와 `published`(true=발행, false=미발행)를 받아 `PageService::bulkChangePublishStatus()` 로 일괄 적용하고, 실제 변경된 건수를 `count` 로 반환합니다. 목록 화면의 다중 선택 후 일괄 발행/미발행 액션에 사용합니다.
### POST /api/modules/sirsoft-page/admin/pages/check-slug
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.check-slug -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.check-slug`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@checkSlug`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.create`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| slug | body | string | 예 | max 255 | URL 친화 식별자 (slug) |
| exclude_id | body | integer | 아니오 | min 1 | exclude 식별자 |
**요청 예시**
```http
POST /api/modules/sirsoft-page/admin/pages/check-slug HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"slug": "example-key",
"exclude_id": 1
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| exists | boolean | `false` | 해당 슬러그가 이미 사용 중인지 여부 (true: 중복 — 사용 불가, false: 사용 가능). `exclude_id` 를 넘기면 그 페이지는 중복 검사에서 제외 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "슬러그 중복 확인이 완료되었습니다.",
"data": {
"exists": false
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.create`)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 대표 케이스: `slug` 누락, `exclude_id` 가 정수가 아님 |
<!-- @generated:end -->
**설명** 슬러그 중복 여부를 확인합니다. `slug`(필수)와 선택 `exclude_id`(수정 화면에서 자기 자신을 중복 검사에서 제외)를 받아 `{ "exists": true|false }` 를 반환합니다. 페이지 생성/수정 폼에서 슬러그 입력 시 실시간 중복 검증에 사용합니다. 권한은 `pages.create` 를 요구합니다.
### DELETE /api/modules/sirsoft-page/admin/pages/{page}
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.destroy -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.destroy`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@destroy`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.delete`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
**요청 예시**
```http
DELETE /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지가 삭제되었습니다.",
"data": null
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.delete`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
<!-- @generated:end -->
**설명** 페이지를 소프트 삭제합니다. `{page}` 는 페이지 ID 입니다(라우트-모델 바인딩이 아닌 `int $id` 로 서비스에서 조회). 존재하지 않으면 404, 스코프 권한 밖이면 403 을 반환합니다. 삭제는 DB CASCADE 가 아니라 `PageService::deletePage()` 를 통해 수행되어 관련 훅·정리 로직이 보장됩니다. 권한은 `pages.delete` 를 요구합니다.
### GET /api/modules/sirsoft-page/admin/pages/{page}
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.show -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.show`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@show`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
**요청 예시**
```http
GET /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `29` | 기본 키 (내부 식별자) |
| slug | string | `apidoc-sample-page` | URL 슬러그 (고유) |
| title | object | `{"ko":"API 문서 샘플 페이지","en":"API Doc Sample Page"}` | 페이지 제목 (다국어 JSON) |
| content | object | `{"ko":"<p>API 레퍼런스 실측용 완전 샘플 페이지 본문입니다.<\/p>","en":"<p>Co…` | 페이지 본문 (다국어 JSON) |
| content_mode | string | `html` | 본문 형식 (html, text) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string | `2026-07-06 23:57:18` | published 일시 |
| seo_meta | object | `{"title":"Et qui sapiente veritatis.","description":"Et m…` | SEO 메타 정보 (title, description, keywords) |
| current_version | integer | `2` | 현재 버전 번호 |
| creator | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| updater | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 최종 수정자 정보 객체 (uuid/name — updater 관계 파생, 로드된 경우에만 포함) |
| attachments | array | `[{"id":9,"hash":"xtfalwomchas","original_filename":"deser…` | 페이지에 귀속된 첨부파일 목록 (PageAttachmentResource 배열 — id/hash/원본파일명/URL 등, 로드된 경우에만 포함) |
| created_at | string | `2026-07-06 23:57:18` | 생성 일시 |
| updated_at | string | `2026-07-06 23:57:18` | 최종 수정 일시 |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 정보를 조회했습니다.",
"data": {
"id": 10,
"slug": "apidoc-sample-page",
"title": {
"ko": "API 문서 샘플 페이지",
"en": "API Doc Sample Page"
},
"content": {
"ko": "<p>API 레퍼런스 실측용 완전 샘플 페이지 본문입니다.</p>",
"en": "<p>Complete sample page body for API reference probing.</p>"
},
"content_mode": "html",
"published": true,
"published_at": "2026-07-08 10:51:59",
"seo_meta": {
"title": "Dolorum et aut officia ipsam doloribus inventore.",
"description": "Sint ipsa impedit enim natus tempore quasi dignissimos praesentium numquam rerum tempore nam.",
"keywords": "illo,pariatur,quis,necessitatibus,aperiam"
},
"current_version": 2,
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"updater": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"attachments": [
{
"id": 4,
"hash": "ninrdtsmhhta",
"original_filename": "nesciunt.jpg",
"mime_type": "image/jpeg",
"size": 7124557,
"collection": "attachments",
"order": 0,
"is_image": true,
"download_url": "/api/modules/sirsoft-page/pages/attachment/ninrdtsmhhta",
"preview_url": "/api/modules/sirsoft-page/pages/attachment/ninrdtsmhhta/preview",
"created_at": "2026-07-08 10:51:59"
}
],
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 10:51:59",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.read`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
<!-- @generated:end -->
**설명** 관리자용 페이지 상세를 조회합니다. `{page}` 는 페이지 ID 입니다. `creator`·`updater`·`attachments` 관계를 eager load 한 `PageResource` 를 반환하며, 목록과 달리 `content`(다국어 본문)·`seo_meta` 전체를 포함합니다. 페이지 편집 화면 진입 시 폼 초기값 로딩에 사용합니다. 미존재 404, 스코프 밖 403.
### PUT /api/modules/sirsoft-page/admin/pages/{page}
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.update -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.update`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@update`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
| slug | body | string | 아니오 | max 255 | URL 친화 식별자 (slug) |
| title | body | array | 예 | — | 제목 |
| content | body | string | 아니오 | — | 본문 내용 |
| content_mode | body | string | 아니오 | `html`, `text` | 본문 편집 모드. `html` 은 리치 에디터 HTML, `text` 는 평문으로 저장·렌더링됩니다 (미지정 시 `html`) |
| published | body | boolean | 아니오 | — | 발행 여부 (발행된 항목만 필터) |
| seo_meta | body | array | 아니오 | — | SEO 메타 정보 맵. 하위 키 `title`(max 255)·`description`(max 500)·`keywords`(max 500)를 담습니다 |
| seo_meta.title | body | string | 아니오 | max 255 | SEO 메타 제목 (검색엔진/소셜 공유 표시 제목) |
| seo_meta.description | body | string | 아니오 | max 500 | SEO 메타 설명 (검색엔진/소셜 공유 표시 요약) |
| seo_meta.keywords | body | string | 아니오 | max 500 | SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분) |
| temp_key | body | string | 아니오 | max 64 | 저장 전 첨부 업로드 시 발급받은 임시 키. 새로 업로드한 첨부를 이 페이지에 귀속시키는 데 사용합니다 |
**요청 예시**
```http
PUT /api/modules/sirsoft-page/admin/pages/{page} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"slug": "example-key",
"title": [
"예시 제목"
],
"content": "예시 내용입니다.",
"content_mode": "html",
"published": true,
"seo_meta": [
"예시값"
],
"seo_meta.title": "예시 제목",
"seo_meta.description": "예시 내용입니다.",
"seo_meta.keywords": "예시값",
"temp_key": "예시값"
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드 (`PageResource` — `show` 와 동일 shape)._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `10` | 기본 키 (내부 식별자) |
| slug | string | `apidoc-sample-page` | URL 슬러그 (고유) |
| title | object | `{"ko":"API 문서 샘플 페이지","en":"API Doc Sample Page"}` | 페이지 제목 (다국어 JSON) |
| content | object | `{"ko":"<p>수정된 본문.</p>"}` | 페이지 본문 (다국어 JSON) |
| content_mode | string | `html` | 본문 형식 (`html`, `text`) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string\|null | `2026-07-08 10:51:59` | 발행 일시 (미발행 시 null) |
| seo_meta | object\|null | `{"title":"...","description":"...","keywords":"..."}` | SEO 메타 정보 (title, description, keywords) |
| current_version | integer | `3` | 현재 버전 번호 (수정 시 이전 상태가 버전 이력으로 적재되며 증가) |
| creator | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 생성자 정보 (uuid/name — creator 관계 eager load) |
| updater | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 최종 수정자 정보 (uuid/name — updater 관계 eager load) |
| attachments | array | `[{"id":4,"hash":"ninrdtsmhhta","original_filename":"nesciunt.jpg", ...}]` | 페이지에 귀속된 첨부파일 목록 (`PageAttachmentResource` 배열) |
| created_at | string | `2026-07-08 10:51:59` | 생성 일시 |
| updated_at | string | `2026-07-08 15:03:15` | 최종 수정 일시 |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자(`created_by`)인지 여부 |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지가 수정되었습니다.",
"data": {
"id": 10,
"slug": "apidoc-sample-page",
"title": {
"ko": "API 문서 샘플 페이지",
"en": "API Doc Sample Page"
},
"content": {
"ko": "<p>수정된 본문.</p>",
"en": "<p>Revised body.</p>"
},
"content_mode": "html",
"published": true,
"published_at": "2026-07-08 10:51:59",
"seo_meta": {
"title": "Dolorum et aut officia ipsam doloribus inventore.",
"description": "Sint ipsa impedit enim natus tempore quasi dignissimos praesentium numquam rerum tempore nam.",
"keywords": "illo,pariatur,quis,necessitatibus,aperiam"
},
"current_version": 3,
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"updater": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"attachments": [],
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 15:03:15",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없거나, 스코프 밖 리소스인 경우 (`auth.scope_denied`) |
| 404 | Not Found | `{page}` ID 에 해당하는 페이지가 없는 경우 (`페이지를 찾을 수 없습니다.`) |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 대표 케이스: `title` 누락, `slug` 중복(자기 자신은 제외)/형식 위반, `content_mode` 가 html/text 이외 |
| 500 | Internal Server Error | 수정 처리 중 예외 (`페이지 수정에 실패했습니다.`) |
<!-- @generated:end -->
**설명** 페이지를 수정합니다. `{page}` 는 페이지 ID 입니다. `title`(필수)·`slug`·`content`·`content_mode`·`published`·`seo_meta` 를 받아 `PageService::updatePage()` 로 반영하고, 수정 시 이전 상태가 버전 이력으로 적재됩니다(`current_version` 증가). `creator`/`updater`/`attachments` 를 eager load 한 `PageResource` 를 반환합니다. 미존재 404, 스코프 밖 403.
### PATCH /api/modules/sirsoft-page/admin/pages/{page}/publish
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.publish -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.publish`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@publish`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
| published | body | boolean | 예 | — | 발행 여부 (발행된 항목만 필터) |
**요청 예시**
```http
PATCH /api/modules/sirsoft-page/admin/pages/{page}/publish HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
Content-Type: application/json
{
"published": true
}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `10` | 기본 키 (내부 식별자) |
| slug | string | `apidoc-sample-page` | URL 친화 식별자 (slug) |
| title | object | `{"ko":"API 문서 샘플 페이지","en":"API Doc Sample Page"}` | 제목 |
| content | object | `{"ko":"<p>API 레퍼런스 실측용 완전 샘플 페이지 본문입니다.<\/p>","en":"<p>Co…` | 본문 내용 |
| content_mode | string | `html` | 본문 형식 (html, text) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string | `2026-07-08 15:03:15` | published 일시 |
| seo_meta | object | `{"title":"Dolorum et aut officia ipsam doloribus inventor…` | SEO 메타 정보 (title, description, keywords) |
| current_version | integer | `2` | 현재 버전 번호 |
| created_at | string | `2026-07-08 10:51:59` | 생성 일시 |
| updated_at | string | `2026-07-08 15:03:15` | 최종 수정 일시 |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 발행 상태가 변경되었습니다.",
"data": {
"id": 10,
"slug": "apidoc-sample-page",
"title": {
"ko": "API 문서 샘플 페이지",
"en": "API Doc Sample Page"
},
"content": {
"ko": "<p>API 레퍼런스 실측용 완전 샘플 페이지 본문입니다.</p>",
"en": "<p>Complete sample page body for API reference probing.</p>"
},
"content_mode": "html",
"published": true,
"published_at": "2026-07-08 15:03:15",
"seo_meta": {
"title": "Dolorum et aut officia ipsam doloribus inventore.",
"description": "Sint ipsa impedit enim natus tempore quasi dignissimos praesentium numquam rerum tempore nam.",
"keywords": "illo,pariatur,quis,necessitatibus,aperiam"
},
"current_version": 2,
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 15:03:15",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
<!-- @generated:end -->
**설명** 단일 페이지의 발행 상태만 토글합니다. `{page}` 는 페이지 ID, `published`(필수 boolean)로 발행/미발행을 전환합니다. 본문·슬러그 등 다른 필드는 건드리지 않으며 변경된 `PageResource` 를 반환합니다. 목록/상세 화면의 발행 토글 스위치에 사용합니다. 미존재 404, 스코프 밖 403.
### GET /api/modules/sirsoft-page/admin/pages/{page}/versions
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.versions.index -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.versions.index`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@versions`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
**요청 예시**
```http
GET /api/modules/sirsoft-page/admin/pages/{page}/versions HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `40` | 기본 키 (내부 식별자) |
| page_id | integer | `29` | page 식별자 (연관 리소스 참조) |
| version | integer | `2` | 버전 순번 (1부터 증가, 페이지 수정 시마다 채번) |
| title | object | `{"ko":"API 문서 샘플 페이지 (v2)","en":"API Doc Sample Page (v2)"}` | 페이지 제목 (다국어 JSON) |
| content | object | `{"ko":"<p>수정 버전 본문.<\/p>","en":"<p>Revised version body.<…` | 페이지 본문 (다국어 JSON) |
| content_mode | string | `html` | 본문 형식 (html, text) |
| seo_meta | null | `null` | SEO 메타 정보 (title, description, keywords) |
| changes_summary | string | `본문 보강` | 이 버전에서 무엇이 바뀌었는지 요약한 변경 설명 (버전 생성 시 기록, 없으면 null) |
| creator | object | `{"uuid":"a231747f-e82e-4cf2-9ae1-a261849dce40","name":"AP…` | 생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
| created_at | string | `2026-07-06 23:57:18` | 생성 일시 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 정보를 조회했습니다.",
"data": [
{
"id": 14,
"page_id": 10,
"version": 2,
"title": {
"ko": "API 문서 샘플 페이지 (v2)",
"en": "API Doc Sample Page (v2)"
},
"content": {
"ko": "<p>수정 버전 본문.</p>",
"en": "<p>Revised version body.</p>"
},
"content_mode": "html",
"seo_meta": null,
"changes_summary": "본문 보강",
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"created_at": "2026-07-08 10:51:59"
},
{
"id": 13,
"page_id": 10,
"version": 1,
"title": {
"ko": "API 문서 샘플 페이지 (v1)",
"en": "API Doc Sample Page (v1)"
},
"content": {
"ko": "<p>초기 버전 본문.</p>",
"en": "<p>Initial version body.</p>"
},
"content_mode": "html",
"seo_meta": null,
"changes_summary": "최초 작성",
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"created_at": "2026-07-08 10:51:59"
}
]
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.read`)이 없는 경우 |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
<!-- @generated:end -->
**설명** 페이지의 버전 이력 목록을 조회합니다. `{page}` 는 페이지 ID 입니다. 각 항목은 그 시점의 `title`·`content`·`content_mode`·`seo_meta` 스냅샷과 `version` 번호·`changes_summary`(변경 요약)·`creator`(작성자)를 담습니다. 편집 화면의 버전 이력 패널에서 과거 버전 목록을 보여 주는 데이터 소스입니다. 미존재 404, 스코프 밖 403.
### GET /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId}
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.versions.show -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.versions.show`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@showVersion`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.read`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
| versionId | path | string | 예 | — | 대상 version의 식별자 |
**요청 예시**
```http
GET /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드 (`PageVersionResource` — `versions.index` 항목과 동일 shape)._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `14` | 버전 레코드의 기본 키 (내부 식별자) |
| page_id | integer | `10` | 이 버전이 속한 페이지의 ID |
| version | integer | `2` | 버전 순번 (1부터 증가, 페이지 수정 시마다 채번) |
| title | object | `{"ko":"API 문서 샘플 페이지 (v2)","en":"API Doc Sample Page (v2)"}` | 그 시점의 페이지 제목 스냅샷 (다국어 JSON) |
| content | object | `{"ko":"<p>수정 버전 본문.</p>"}` | 그 시점의 페이지 본문 스냅샷 (다국어 JSON) |
| content_mode | string | `html` | 그 시점의 본문 형식 (`html`, `text` — 미지정 시 `html`) |
| seo_meta | object\|null | `null` | 그 시점의 SEO 메타 스냅샷 (title, description, keywords) |
| changes_summary | string\|null | `본문 보강` | 이 버전에서 무엇이 바뀌었는지 요약한 변경 설명 (없으면 null) |
| creator | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 이 버전을 만든 사용자 정보 (uuid/name — creator 관계 eager load) |
| created_at | string | `2026-07-08 10:51:59` | 버전 생성 일시 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 정보를 조회했습니다.",
"data": {
"id": 14,
"page_id": 10,
"version": 2,
"title": {
"ko": "API 문서 샘플 페이지 (v2)",
"en": "API Doc Sample Page (v2)"
},
"content": {
"ko": "<p>수정 버전 본문.</p>",
"en": "<p>Revised version body.</p>"
},
"content_mode": "html",
"seo_meta": null,
"changes_summary": "본문 보강",
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"created_at": "2026-07-08 10:51:59"
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.read`)이 없거나, 스코프 밖 리소스인 경우 (`auth.scope_denied`) |
| 404 | Not Found | `{page}` 페이지 또는 `{versionId}` 버전이 없는 경우 (`페이지를 찾을 수 없습니다.`) |
| 500 | Internal Server Error | 조회 처리 중 예외 (`페이지 정보 조회에 실패했습니다.`) |
<!-- @generated:end -->
**설명** 특정 버전의 상세 스냅샷을 조회합니다. `{page}` 는 페이지 ID, `{versionId}` 는 버전 ID 입니다. 해당 버전의 전체 본문(`content`)과 메타를 담은 `PageVersionResource` 를 반환하며, 복원 전 미리보기·버전 간 비교에 사용합니다. `{versionId}` 는 라우트-모델 바인딩이 아니어서 문서 생성 시 자동 실측에서 제외되며, 응답 shape 은 `versions.index` 항목과 동일합니다. 미존재 404, 스코프 밖 403. `{versionId}`는 경로의 `{page}`에 속한 버전이어야 합니다 — 다른 페이지의 버전 ID를 지정하면 404를 반환합니다.
### POST /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId}/restore
<!-- @generated:start:api.modules.sirsoft-page.admin.pages.versions.restore -->
- **라우트명**: `api.modules.sirsoft-page.admin.pages.versions.restore`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\Admin\PageController@restoreVersion`
- **인증/권한**: `auth:sanctum` + `permission:sirsoft-page.pages.update`
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| page | path | string | 예 | — | 조회할 페이지 번호 (1부터 시작) |
| versionId | path | string | 예 | — | 대상 version의 식별자 |
**요청 예시**
```http
POST /api/modules/sirsoft-page/admin/pages/{page}/versions/{versionId}/restore HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN}
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드 (복원된 페이지의 `PageResource` — `show` 와 동일 shape)._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `10` | 기본 키 (내부 식별자) |
| slug | string | `apidoc-sample-page` | URL 슬러그 (고유) |
| title | object | `{"ko":"API 문서 샘플 페이지 (v1)","en":"API Doc Sample Page (v1)"}` | 복원된 페이지 제목 (다국어 JSON — 대상 버전의 스냅샷) |
| content | object | `{"ko":"<p>초기 버전 본문.</p>"}` | 복원된 페이지 본문 (다국어 JSON — 대상 버전의 스냅샷) |
| content_mode | string | `html` | 본문 형식 (`html`, `text`) |
| published | boolean | `true` | 발행 여부 (true: 발행, false: 미발행) |
| published_at | string\|null | `2026-07-08 10:51:59` | 발행 일시 (미발행 시 null) |
| seo_meta | object\|null | `null` | SEO 메타 정보 (title, description, keywords — 대상 버전의 스냅샷) |
| current_version | integer | `3` | 현재 버전 번호 (복원 자체도 새 버전으로 적재되어 증가) |
| creator | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 생성자 정보 (uuid/name — creator 관계 eager load) |
| updater | object | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 최종 수정자(복원 수행자) 정보 (uuid/name — updater 관계 eager load) |
| attachments | array | `[]` | 페이지에 귀속된 첨부파일 목록 (`PageAttachmentResource` 배열) |
| created_at | string | `2026-07-08 10:51:59` | 생성 일시 |
| updated_at | string | `2026-07-08 15:10:02` | 최종 수정 일시 (복원 시각) |
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자(`created_by`)인지 여부 |
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "이전 버전으로 복원되었습니다.",
"data": {
"id": 10,
"slug": "apidoc-sample-page",
"title": {
"ko": "API 문서 샘플 페이지 (v1)",
"en": "API Doc Sample Page (v1)"
},
"content": {
"ko": "<p>초기 버전 본문.</p>",
"en": "<p>Initial version body.</p>"
},
"content_mode": "html",
"published": true,
"published_at": "2026-07-08 10:51:59",
"seo_meta": null,
"current_version": 3,
"creator": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"updater": {
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
"name": "API 문서 샘플 사용자"
},
"attachments": [],
"created_at": "2026-07-08 10:51:59",
"updated_at": "2026-07-08 15:10:02",
"is_owner": true,
"abilities": {
"can_create": true,
"can_update": true,
"can_delete": true
}
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(`sirsoft-page.pages.update`)이 없거나, 스코프 밖 리소스인 경우 (`auth.scope_denied`) |
| 404 | Not Found | `{page}` 페이지 또는 `{versionId}` 버전이 없는 경우 (`페이지를 찾을 수 없습니다.`) |
| 500 | Internal Server Error | 복원 처리 중 예외 — 지정된 버전이 해당 페이지에 속하지 않는 경우 포함 (`버전 복원에 실패했습니다.`) |
<!-- @generated:end -->
**설명** 페이지를 특정 버전 시점으로 복원합니다. `{page}` 는 페이지 ID, `{versionId}` 는 복원 대상 버전 ID 입니다. `PageService::restoreVersion()` 이 그 버전의 내용을 현재 페이지에 반영하고(복원 자체도 새 버전으로 적재), 복원된 `PageResource` 를 반환합니다. 편집 화면 버전 이력 패널의 "이 버전으로 복원" 액션에 사용합니다. 미존재 404, 스코프 밖 403. `{versionId}`는 경로의 `{page}`에 속한 버전이어야 합니다 — 다른 페이지의 버전 ID를 지정하면 `versions.show` 와 동일하게 404를 반환합니다.
### GET /api/modules/sirsoft-page/pages/attachment/{hash}
<!-- @generated:start:api.modules.sirsoft-page.pages.attachment.download -->
- **라우트명**: `api.modules.sirsoft-page.pages.attachment.download`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\User\PublicPageAttachmentController@download`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| hash | path | string | 예 | — | 대상 리소스의 해시 식별자 |
**요청 예시**
```http
GET /api/modules/sirsoft-page/pages/attachment/{hash} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
_이 엔드포인트는 JSON 봉투를 반환하지 않습니다. 성공 시 원본 파일 바이트를 그대로 내려주는 파일 스트리밍 응답(`StreamedResponse`, `Content-Disposition: attachment`)이며, 실패 시에만 JSON 오류 봉투를 반환합니다._
**응답 예시**
```http
HTTP/1.1 200
Content-Type: image/jpeg
Content-Disposition: attachment; filename="nesciunt.jpg"
(파일 바이너리 스트림)
```
실패 시(첨부 미존재 · 미발행 페이지의 첨부를 권한 없이 요청 · 스토리지에 파일 없음):
```json
{
"success": false,
"message": "첨부파일을 찾을 수 없습니다.",
"errors": null
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 404 | Not Found | 해시에 해당하는 첨부가 없거나(`첨부파일을 찾을 수 없습니다.`), 미발행 페이지의 첨부를 `sirsoft-page.pages.read` 권한 없이 요청한 경우(존재를 숨기기 위해 동일하게 404), 또는 DB 레코드는 있으나 스토리지에 실제 파일이 없는 경우(`첨부파일이 스토리지에 존재하지 않습니다.`) |
<!-- @generated:end -->
**설명** 공개 첨부파일을 다운로드합니다(해시 기반, 12자). 실제 미들웨어는 `optional.sanctum` 으로, 비로그인 사용자도 접근할 수 있습니다(위 표의 `auth:sanctum` 은 생성기가 sanctum 미들웨어를 인식한 표기이며, 실제로는 토큰이 없어도 통과). 발행된 페이지의 첨부는 누구나, 미발행 페이지의 첨부는 `sirsoft-page.pages.read` 관리자만 다운로드할 수 있고, 그 외에는 404 로 존재를 숨깁니다. 브라우저 직접 GET(토큰 미탑재)을 위해 해시 라우트로 단일화되었습니다. 파일 스트리밍 응답이므로 실측 대상이 아닙니다.
### GET /api/modules/sirsoft-page/pages/attachment/{hash}/preview
<!-- @generated:start:api.modules.sirsoft-page.pages.attachment.preview -->
- **라우트명**: `api.modules.sirsoft-page.pages.attachment.preview`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\User\PublicPageAttachmentController@preview`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| hash | path | string | 예 | — | 대상 리소스의 해시 식별자 |
**요청 예시**
```http
GET /api/modules/sirsoft-page/pages/attachment/{hash}/preview HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
_이 엔드포인트는 JSON 봉투를 반환하지 않습니다. 성공 시 이미지 바이트를 인라인으로 내려주는 스트리밍 응답(`StreamedResponse`, `Content-Disposition: inline`)이며, 실패 시에만 JSON 오류 봉투를 반환합니다._
**응답 예시**
```http
HTTP/1.1 200
Content-Type: image/jpeg
Content-Disposition: inline
(이미지 바이너리 스트림)
```
실패 시(첨부 미존재 · 이미지가 아닌 첨부 · 스토리지에 파일 없음):
```json
{
"success": false,
"message": "첨부파일이 스토리지에 존재하지 않습니다.",
"errors": null
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 404 | Not Found | 해시에 해당하는 첨부가 없는 경우(`첨부파일을 찾을 수 없습니다.`), 첨부가 이미지가 아니거나 스토리지에 실제 파일이 없는 경우(`첨부파일이 스토리지에 존재하지 않습니다.`). 미리보기는 발행/미발행과 무관하게 공개 서빙되므로 권한에 의한 404 는 없습니다 |
<!-- @generated:end -->
**설명** 이미지 첨부 썸네일을 인라인으로 미리봅니다(해시 기반, 12자). 썸네일 `<img>` 는 토큰을 실을 수 없으므로 발행/미발행과 무관하게 공개 서빙합니다. 미발행 콘텐츠의 썸네일은 해시를 보유해야만 조회 가능(비추측성)하며, 실제 파일 다운로드는 `download` 의 권한 게이트로 보호됩니다. 이미지 스트리밍 응답이므로 실측 대상이 아닙니다.
### GET /api/modules/sirsoft-page/pages/{slug}
<!-- @generated:start:api.modules.sirsoft-page.pages.show -->
- **라우트명**: `api.modules.sirsoft-page.pages.show`
- **컨트롤러**: `Modules\Sirsoft\Page\Http\Controllers\User\PublicPageController@show`
- **인증/권한**: `optional.sanctum` (선택적 인증: 회원/비회원 모두 접근)
**요청 파라미터**
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
| --- | --- | --- | --- | --- | --- |
| slug | path | string | 예 | — | 대상 리소스의 slug (URL 친화 식별자) |
**요청 예시**
```http
GET /api/modules/sirsoft-page/pages/{slug} HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
```
**응답 필드** (`data` 내부)
_단건 응답: `data` 객체의 필드._
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
| --- | --- | --- | --- |
| id | integer | `4` | 기본 키 (내부 식별자) |
| slug | string | `terms` | URL 친화 식별자 (slug) |
| title | string | `이용약관` | 제목 |
| content | string | `<h2 style="font-size: 1.25rem; font-w…` | 본문 내용 |
| content_mode | string | `html` | 본문 형식 (html, text) |
| is_preview | boolean | `false` | preview 여부 |
| published_at | string | `2026-07-08 10:44:43` | published 일시 |
| seo_meta | null | `null` | SEO 메타 정보 (title, description, keywords) |
| current_version | integer | `1` | 현재 버전 번호 |
| attachments | array | `[]` | 페이지에 귀속된 첨부파일 목록 (PageAttachmentResource 배열 — id/hash/원본파일명/URL 등, 로드된 경우에만 포함) |
| created_at | string | `2026-07-08 10:44:43` | 생성 일시 |
| updated_at | string | `2026-07-08 10:44:43` | 최종 수정 일시 |
**응답 예시**
```http
HTTP/1.1 200
```
```json
{
"success": true,
"message": "페이지 정보를 조회했습니다.",
"data": {
"id": 4,
"slug": "terms",
"title": "이용약관",
"content": "<h2 style=\"font-size: 1.25rem; font-weight: 700; margin-top: 0; margin-bottom: 1rem;\">제1조 (목적)</h2>\n<p style=\"font-size: 1rem; line-height: 1.75; margin-bottom: 1rem;\">[이용약관의 목적을 입력하세요.]</p>\n\n<h2 style=\"font-size: 1.25rem; font-weight: 700; margin-top: 2rem; margin-bottom: 1rem;\">제2조 (정의)</h2>\n<p style=\"font-size: 1rem; line-height: 1.75; margin-bottom: 1rem;\">[주요 용어의 정의를 입력하세요.]</p>\n\n<h2 style=\"font-size: 1.25rem; font-weight: 700; margin-top: 2rem; margin-bottom: 1rem;\">제3조 (약관의 효력 및 변경)</h2>\n<p style=\"font-size: 1rem; line-height: 1.75; margin-bottom: 1rem;\">[약관의 효력 및 변경에 관한 내용을 입력하세요.]</p>\n\n<h2 style=\"font-size: 1.25rem; font-weight: 700; margin-top: 2rem; margin-bottom: 1rem;\">제4조 (서비스의 제공 및 변경)</h2>\n<p style=\"font-size: 1rem; line-height: 1.75; margin-bottom: 1rem;\">[서비스 제공 및 변경에 관한 내용을 입력하세요.]</p>\n\n<h2 style=\"font-size: 1.25rem; font-weight: 700; margin-top: 2rem; margin-bottom: 1rem;\">제5조 (회원의 의무)</h2>\n<p style=\"font-size: 1rem; line-height: 1.75; margin-bottom: 1rem;\">[회원의 의무에 관한 내용을 입력하세요.]</p>",
"content_mode": "html",
"is_preview": false,
"published_at": "2026-07-08 10:44:43",
"seo_meta": null,
"current_version": 1,
"attachments": [],
"created_at": "2026-07-08 10:44:43",
"updated_at": "2026-07-08 10:44:43"
}
}
```
**에러 응답**
| 상태코드 | 의미 | 발생 조건 |
| --- | --- | --- |
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
<!-- @generated:end -->
**설명** 발행된 페이지를 슬러그로 조회하는 공개 엔드포인트입니다. 실제 미들웨어는 `optional.sanctum` 으로 비로그인 사용자도 발행 페이지를 볼 수 있습니다(위 표의 `auth:sanctum` 은 생성기 표기이며 토큰 없이도 통과). `sirsoft-page.pages.read` 권한을 가진 관리자는 미발행 페이지도 사용자 화면에서 미리볼 수 있으며(이때 응답에 preview 표시가 실림), 비로그인·일반 회원은 미발행 시 404 를 받습니다. `PublicPageResource` 는 관리자용 상세보다 축소된 공개 표면을 노출하고 `attachments` 를 포함합니다. `{slug}` 는 문자열 라우트 파라미터라 문서 생성 시 자동 실측에서 제외됩니다.
Reference in new issue View Git Blame Copy Permalink