Merge pull request from gnuboard:HeuJung/issue454
fix(ecommerce,tosspayments,pay_kginicis,core): 리베이스 접합부 payment_method string 계약 미전파 회귀 수정
This commit is contained in:
commit
e80be1d924
484 files changed
+237099
-3400
No files matched your search
@@ -155,7 +155,7 @@
|
||||
| 코어 | [docs/backend/api/README.md](docs/backend/api/README.md) | 36 / 319 |
|
||||
|
||||
|
||||
### 확장 API 레퍼런스 (13개 확장, 자동 스캔)
|
||||
### 확장 API 레퍼런스 (14개 확장, 자동 스캔)
|
||||
|
||||
> 각 확장이 소유하는 API 문서 목차. `php artisan api:docgen` 이 생성하며, 이 표는 `{modules,plugins}/_bundled/*/docs/api/README.md` 를 패턴 스캔해 자동 편입된다(확장명 하드코딩 없음).
|
||||
|
||||
@@ -163,15 +163,16 @@
|
||||
|------|------|--------------|----------------|
|
||||
| `gnuboard7-hello_module` | 모듈 | [docs/api/](modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 7 |
|
||||
| `sirsoft-board` | 모듈 | [docs/api/](modules/_bundled/sirsoft-board/docs/api/README.md) | 10 / 80 |
|
||||
| `sirsoft-ecommerce` | 모듈 | [docs/api/](modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 232 |
|
||||
| `sirsoft-ecommerce` | 모듈 | [docs/api/](modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 239 |
|
||||
| `sirsoft-page` | 모듈 | [docs/api/](modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
|
||||
| `sirsoft-ckeditor5` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-ckeditor5/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-gdpr` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-gdpr/docs/api/README.md) | 4 / 15 |
|
||||
| `sirsoft-marketing` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-marketing/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-message_bizppurio` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-message_bizppurio/docs/api/README.md) | 6 / 12 |
|
||||
| `sirsoft-message_bizppurio` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-message_bizppurio/docs/api/README.md) | 7 / 13 |
|
||||
| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 22 |
|
||||
| `sirsoft-pay_nhnkcp` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_nhnkcp/docs/api/README.md) | 0 / 0 |
|
||||
| `sirsoft-pay_nicepayments` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-pay_nicepayments/docs/api/README.md) | 0 / 0 |
|
||||
| `sirsoft-tosspayments` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-tosspayments/docs/api/README.md) | 2 / 4 |
|
||||
| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 1 / 1 |
|
||||
| `sirsoft-verification_nhnkcp` | 플러그인 | [docs/api/](plugins/_bundled/sirsoft-verification_nhnkcp/docs/api/README.md) | 1 / 1 |
|
||||
|
||||
|
||||
@@ -189,6 +189,7 @@
|
||||
#### 안내 문구·주소 처리
|
||||
|
||||
- 일부 안내가 실제 문장 대신 내부 식별자(`messages.auth.unauthenticated` 같은 문자열)로 표시되던 문제를 수정했습니다. 로그인하지 않았거나 역할 권한이 없어 요청이 거절될 때, 메뉴에 역할을 지정할 때, 확장 식별자를 잘못 입력했을 때, 활동 로그를 기간·유형으로 검색할 때가 해당됩니다.
|
||||
- 회원 정보 수정, 권한·메뉴 설정, 본인인증, 알림 설정 등 여러 화면에서 처리를 마친 뒤 표시되는 안내 문구가 번역된 문장 대신 내부 식별자가 그대로 보이던 문제를 수정했습니다. 이제 성공·실패·권한 없음 등 모든 안내가 사용 중인 언어에 맞는 문장으로 표시됩니다.
|
||||
- 환경설정 저장이 실패했을 때 안내 문구에 항목 이름이 `security.password min length` 같은 내부 식별자로 표시되던 문제를 수정했습니다. 보안·업로드·SEO·고급·드라이버·메일 등 모든 설정 항목이 화면에 보이는 한글 항목명으로 안내됩니다.
|
||||
- 플러그인을 GitHub 주소나 ZIP 파일로 설치할 때의 입력 안내가 내부 식별자로 표시되던 문제를 수정했습니다. 주소 형식이 잘못됐거나, ZIP이 아닌 파일을 올렸거나, 파일 용량을 초과했을 때 정상 문장으로 안내합니다.
|
||||
- 목록의 열 제목을 눌러 정렬할 때, 이미 다른 열로 정렬 중이었다면 화살표는 새로 누른 열에 표시되면서 실제 정렬은 이전 열 기준으로 바뀌던 문제를 수정했습니다. 표시와 실제 정렬 기준이 어긋나 결과를 신뢰할 수 없었으며, 이제 누른 열 기준으로 한 번에 정렬됩니다.
|
||||
@@ -244,6 +245,7 @@
|
||||
- 화면 구성 파일이 목록을 만들어 내는 과정에서 다국어 이름을 골라 쓸 때, 사이트를 어떤 언어로 보고 있든 항상 한국어 이름이 선택되던 문제를 수정했습니다. 이제 보고 있는 언어의 이름이 표시됩니다. 헤더의 배송국가 선택처럼 화면이 처음 열릴 때 목록을 만들어 두는 곳이 여기에 해당합니다.
|
||||
- 메뉴를 눌러 화면을 이동했을 때, 필요한 정보를 여러 갈래로 나눠 받아오는 화면에서 먼저 도착한 정보가 뒤늦게 도착한 정보에 덮여 사라지는 경우가 있었습니다. 그 탓에 목록이 있어야 할 자리가 간헐적으로 비어 보이고 새로고침하면 정상으로 돌아오곤 했습니다. 이제 어느 정보가 먼저 도착하든 모두 반영됩니다. 이커머스 환경설정의 배송설정 탭에서 배송가능 국가 목록이 비어 보이던 것이 여기에 해당합니다.
|
||||
- 이미 설치를 마친 환경의 설정 파일(`.env`)을 새 서버로 복사해, 데이터베이스가 아직 비어 있는 상태에서 설치를 이어가려 할 때 `php artisan migrate`로 테이블을 만들기도 전에 부팅 단계에서 오류가 나며 중단되던 문제를 수정했습니다. 이제 데이터베이스 작업 명령이 실행되는 동안에는 테이블 존재 여부를 실제로 확인하므로, 기존 서버의 설정을 재사용하는 신규 배포에서도 설치가 정상적으로 진행됩니다. (#41 @GyusoonKim 님께서 제보해주셨습니다.)
|
||||
- 활동 로그 기록에 실패했을 때 그 기록을 유발한 요청까지 함께 실패하던 문제를 수정했습니다. 결제 입금통보 같은 외부 콜백이 활동 로그 문제로 오류를 반환하는 일이 없어집니다.
|
||||
|
||||
## [7.0.2] - 2026-07-08
|
||||
|
||||
|
||||
@@ -390,6 +390,7 @@ cp .env.example .env
|
||||
| **sirsoft-pay_kginicis** | KG이니시스 결제 연동 |
|
||||
| **sirsoft-pay_nicepayments** | 나이스페이먼츠 결제 연동 (통합결제창) |
|
||||
| **sirsoft-pay_nhnkcp** | NHN KCP 결제 연동 (Standard Pay) |
|
||||
| **sirsoft-tosspayments** | 토스페이먼츠 결제 연동 |
|
||||
| **sirsoft-verification_kginicis** | KG이니시스 본인인증 |
|
||||
| **sirsoft-daum_postcode** | 다음 우편번호 검색 |
|
||||
| **sirsoft-marketing** | 마케팅 도구 |
|
||||
@@ -420,6 +421,7 @@ cp .env.example .env
|
||||
| **g7-plugin-sirsoft-pay_kginicis-ja** | KG이니시스 결제 플러그인 일본어 |
|
||||
| **g7-plugin-sirsoft-pay_nicepayments-ja** | 나이스페이먼츠 결제 플러그인 일본어 |
|
||||
| **g7-plugin-sirsoft-pay_nhnkcp-ja** | NHN KCP 결제 플러그인 일본어 |
|
||||
| **g7-plugin-sirsoft-tosspayments-ja** | 토스페이먼츠 플러그인 일본어 |
|
||||
| **g7-plugin-sirsoft-verification_kginicis-ja** | KG이니시스 본인인증 플러그인 일본어 |
|
||||
| **g7-template-sirsoft-admin_basic-ja** | 관리자 기본 템플릿 일본어 |
|
||||
| **g7-template-sirsoft-basic-ja** | 사용자 기본 템플릿 일본어 |
|
||||
|
||||
@@ -44,8 +44,8 @@ trait ResolvesActivityLogType
|
||||
* properties.extension_origin 에 자동 주입합니다 (loggable 미지정 케이스의
|
||||
* action 라벨 namespace fallback 용).
|
||||
*
|
||||
* @param string $action 액션명 (예: 'user.create')
|
||||
* @param array $context Monolog context 배열
|
||||
* @param string $action 액션명 (예: 'user.create')
|
||||
* @param array $context Monolog context 배열
|
||||
*/
|
||||
protected function logActivity(string $action, array $context): void
|
||||
{
|
||||
@@ -58,9 +58,13 @@ trait ResolvesActivityLogType
|
||||
$context['properties'] = $properties;
|
||||
}
|
||||
|
||||
// 활동 로그는 부수 기록이다 — 실패해도 그것을 유발한 요청(결제 콜백 등)까지
|
||||
// 죽여서는 안 된다. 채널 해석 실패는 Exception 이 아니라 Error 로 오므로
|
||||
// (\Log::channel() 이 null 을 반환하면 "->info() on null" = \Error)
|
||||
// Throwable 로 받아야 가드가 실제로 동작한다.
|
||||
try {
|
||||
Log::channel('activity')->info($action, $context);
|
||||
} catch (\Exception $e) {
|
||||
} catch (\Throwable $e) {
|
||||
Log::error('Failed to record activity log', [
|
||||
'action' => $action,
|
||||
'error' => $e->getMessage(),
|
||||
|
||||
@@ -126,6 +126,7 @@ class ApiDocgenCommand extends Command
|
||||
|
||||
$stats = ['files' => 0, 'endpoints' => 0, 'probed' => 0, 'skipped' => 0, 'examples' => 0];
|
||||
$checkFindings = [];
|
||||
$skippedProbes = [];
|
||||
$examplesOnly = (bool) $this->option('examples-only');
|
||||
|
||||
// 대상(코어/확장)별 README 목차 항목 누적: readmeKey => ['label' => ..., 'entries' => [...]]
|
||||
@@ -136,6 +137,17 @@ class ApiDocgenCommand extends Command
|
||||
$sectionKeys = [];
|
||||
$exampleBlocks = [];
|
||||
|
||||
// `Route::match(['get','post'], ...)->name('x')` 는 하나의 라우트명으로 두 엔드포인트를
|
||||
// 등록한다. 생성 블록 키가 라우트명뿐이면 한 문서에 같은 키가 둘 생겨, 블록 조회(strpos)가
|
||||
// 언제나 첫 블록만 잡아 두 번째 블록의 사람 서술이 재생성마다 유실된다.
|
||||
// 문서 안에서 중복되는 라우트명만 골라 키에 메서드를 붙인다 (나머지 키는 그대로 — 전 문서의
|
||||
// 키를 바꾸면 기존 블록과 대조가 어긋나 사람 서술이 통째로 사라진다).
|
||||
$nameCounts = array_count_values(array_map(
|
||||
static fn (array $r): string => $r['name'] ?: $r['uri'],
|
||||
$items,
|
||||
));
|
||||
$duplicatedNames = array_keys(array_filter($nameCounts, static fn (int $n): bool => $n > 1));
|
||||
|
||||
// 목차용 도메인 파일 항목 (소유별). 예시-only/check 모드에서도 목차는 최신화한다.
|
||||
$owner = $items[0]['owner'];
|
||||
$readmeKey = $this->readmeFile($owner);
|
||||
@@ -156,10 +168,14 @@ class ApiDocgenCommand extends Command
|
||||
$stats['probed']++;
|
||||
} else {
|
||||
$stats['skipped']++;
|
||||
$checkFindings[] = "{$route['method']} {$route['uri']} — {$probeMeta['skipped_reason']}";
|
||||
// 실측 제외는 설계상 정상이다 — 부수효과 쓰기·미치환 path·검증 실패는 의도적으로
|
||||
// 호출하지 않고, 그 자리는 사람이 코드 근거로 채운다. drift 로 세면 문서가 완전해도
|
||||
// --check 가 통과할 수 없어 기준이 무의미해진다. 정보로만 남긴다.
|
||||
$skippedProbes[] = "{$route['method']} {$route['uri']} — {$probeMeta['skipped_reason']}";
|
||||
}
|
||||
|
||||
$key = $route['name'] ?: $route['uri'];
|
||||
$methodScopedKey = in_array($route['name'] ?: $route['uri'], $duplicatedNames, true);
|
||||
$key = $scaffolder->generatedKey($route, $methodScopedKey);
|
||||
|
||||
if ($examplesOnly) {
|
||||
// 표·서술을 건드리지 않고 예시 2블록만 산출 (SSoT=스캐폴더 예시 메서드).
|
||||
@@ -179,7 +195,7 @@ class ApiDocgenCommand extends Command
|
||||
}
|
||||
|
||||
$commentMap = $this->columnComments($route, $commentResolver, $sampleMap);
|
||||
$sections[] = $scaffolder->endpointSection($route, $request, $schema, $probeMeta, $commentMap);
|
||||
$sections[] = $scaffolder->endpointSection($route, $request, $schema, $probeMeta, $commentMap, $methodScopedKey);
|
||||
$sectionKeys[] = $key;
|
||||
$stats['endpoints']++;
|
||||
}
|
||||
@@ -187,6 +203,12 @@ class ApiDocgenCommand extends Command
|
||||
if ($this->option('check')) {
|
||||
if (! File::exists($file)) {
|
||||
$checkFindings[] = "문서 파일 없음: {$file}";
|
||||
} else {
|
||||
// 실측 불가 자리를 사람이 채우지 않고 마커로 남겨 두면 문서가 미완이다.
|
||||
// (규정: docs/backend/api-documentation.md "미채움 마커 5종")
|
||||
foreach ($this->unfilledMarkers(File::get($file)) as $marker) {
|
||||
$checkFindings[] = "미채움 마커: {$file} — {$marker}";
|
||||
}
|
||||
}
|
||||
|
||||
continue;
|
||||
@@ -216,6 +238,15 @@ class ApiDocgenCommand extends Command
|
||||
|
||||
$header = $this->documentHeader($file, $items[0]);
|
||||
$existing = File::exists($file) ? File::get($file) : null;
|
||||
|
||||
// 기존 문서는 중복 라우트명 블록을 구 키(라우트명만)로 갖고 있다. 그대로 두면 새 키
|
||||
// (라우트명::메서드)와 대조되지 않아 이번 재생성에서 그 블록의 사람 서술이 유실된다.
|
||||
// 병합 전에 구 키를 등장 순서대로 새 키로 승격한다 — 문서 내 블록 순서는 $items 순서와
|
||||
// 같으므로(같은 그룹을 같은 순서로 순회) 메서드 대응이 어긋나지 않는다.
|
||||
if ($existing !== null && $duplicatedNames !== []) {
|
||||
$existing = $this->migrateDuplicateBlockKeys($existing, $items, $duplicatedNames, $scaffolder);
|
||||
}
|
||||
|
||||
$content = $scaffolder->mergeDocument($existing, $header, $sections, $sectionKeys);
|
||||
|
||||
File::ensureDirectoryExists(dirname($file));
|
||||
@@ -253,8 +284,20 @@ class ApiDocgenCommand extends Command
|
||||
}
|
||||
|
||||
if ($this->option('check')) {
|
||||
// 실측 제외는 정상 동작이므로 참고 정보로만 표시한다 (drift 아님).
|
||||
if ($skippedProbes !== []) {
|
||||
$this->line('실측 제외 '.count($skippedProbes).'건 (정상 — 해당 자리는 사람이 작성):');
|
||||
foreach (array_slice($skippedProbes, 0, 10) as $s) {
|
||||
$this->line(' · '.$s);
|
||||
}
|
||||
if (count($skippedProbes) > 10) {
|
||||
$this->line(' · ... 외 '.(count($skippedProbes) - 10).'건');
|
||||
}
|
||||
$this->newLine();
|
||||
}
|
||||
|
||||
if ($checkFindings !== []) {
|
||||
$this->warn('실측 제외/문서 누락 '.count($checkFindings).'건:');
|
||||
$this->warn('drift '.count($checkFindings).'건:');
|
||||
foreach (array_slice($checkFindings, 0, 50) as $f) {
|
||||
$this->line(' - '.$f);
|
||||
}
|
||||
@@ -899,6 +942,92 @@ class ApiDocgenCommand extends Command
|
||||
return base_path("{$base}/_bundled/{$owner['id']}/docs/api/README.md");
|
||||
}
|
||||
|
||||
/**
|
||||
* 문서에 남아 있는 미채움 마커를 수집합니다.
|
||||
*
|
||||
* `api:docgen` 은 실측 불가한 자리에 "사람이 작성하세요" 마커를 남긴다. 실측 불가는 그 자리를
|
||||
* 비워둘 사유가 아니며, 컨트롤러/Resource/FormRequest/Enum/lang 을 읽어 채우는 것이 규정이다
|
||||
* (docs/backend/api-documentation.md "미채움 마커 5종"). 마커가 남아 있으면 문서는 미완이다.
|
||||
*
|
||||
* 잔량 전수 집계는 `check-api-doc-unfilled.cjs` 가 담당하고, 여기서는 `--check` 가 자기 scope
|
||||
* 문서의 미완을 drift 로 잡기 위해 마커 종류만 요약한다.
|
||||
*
|
||||
* @param string $content 문서 내용
|
||||
* @return array<int, string> 발견된 마커 요약 (종류 => 건수)
|
||||
*/
|
||||
private function unfilledMarkers(string $content): array
|
||||
{
|
||||
$markers = [
|
||||
'실측 제외:' => '실측 제외 (응답 필드 표 / 응답 예시)',
|
||||
'TODO: 용도' => '요청 파라미터 설명',
|
||||
'TODO: 설명' => '응답 필드 설명',
|
||||
'실측 응답에 필드 없음' => '빈 목록 관측 (응답 필드 표)',
|
||||
'대표 에러 없음' => '도메인 특이 에러',
|
||||
];
|
||||
|
||||
$found = [];
|
||||
|
||||
foreach ($markers as $needle => $label) {
|
||||
$count = substr_count($content, $needle);
|
||||
|
||||
if ($count > 0) {
|
||||
$found[] = "{$label} {$count}건";
|
||||
}
|
||||
}
|
||||
|
||||
return $found;
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서의 중복 생성 블록 키를 메서드 스코프 키로 승격합니다.
|
||||
*
|
||||
* `Route::match(['get','post'], ...)->name('x')` 로 등록된 라우트는 한 문서에 같은
|
||||
* `@generated:start:x` 블록을 둘 만든다. 새 키(`x::get` / `x::post`)로 재생성하면 구 키를
|
||||
* 가진 기존 블록과 대조되지 않아 그 블록의 사람 서술이 유실되므로, 병합 전에 구 키를
|
||||
* 등장 순서대로 새 키로 바꿔 준다.
|
||||
*
|
||||
* 문서 내 블록 순서는 `$items` 순서와 같다(같은 그룹을 같은 순서로 순회해 생성했다).
|
||||
* 따라서 n 번째 구 키 블록에는 그 라우트명을 가진 n 번째 라우트의 메서드를 붙인다.
|
||||
*
|
||||
* @param string $existing 기존 문서 내용
|
||||
* @param array<int, array<string, mixed>> $items 이 문서의 라우트 목록 (문서 순서)
|
||||
* @param array<int, string> $duplicatedNames 문서 안에서 중복되는 라우트명
|
||||
* @param ApiDocScaffolder $scaffolder 키 생성기
|
||||
* @return string 키가 승격된 문서 내용
|
||||
*/
|
||||
private function migrateDuplicateBlockKeys(
|
||||
string $existing,
|
||||
array $items,
|
||||
array $duplicatedNames,
|
||||
ApiDocScaffolder $scaffolder
|
||||
): string {
|
||||
foreach ($duplicatedNames as $name) {
|
||||
$methods = array_values(array_map(
|
||||
static fn (array $r): string => $r['method'],
|
||||
array_filter($items, static fn (array $r): bool => ($r['name'] ?: $r['uri']) === $name),
|
||||
));
|
||||
|
||||
$marker = '<!-- @generated:start:'.$name.' -->';
|
||||
$offset = 0;
|
||||
|
||||
foreach ($methods as $method) {
|
||||
$pos = strpos($existing, $marker, $offset);
|
||||
|
||||
if ($pos === false) {
|
||||
break;
|
||||
}
|
||||
|
||||
$newKey = $scaffolder->generatedKey(['name' => $name, 'uri' => $name, 'method' => $method], true);
|
||||
$newMarker = '<!-- @generated:start:'.$newKey.' -->';
|
||||
|
||||
$existing = substr_replace($existing, $newMarker, $pos, strlen($marker));
|
||||
$offset = $pos + strlen($newMarker);
|
||||
}
|
||||
}
|
||||
|
||||
return $existing;
|
||||
}
|
||||
|
||||
/**
|
||||
* 문서 헤더(제목 + TL;DR)를 생성합니다.
|
||||
*
|
||||
@@ -923,7 +1052,7 @@ class ApiDocgenCommand extends Command
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 {$domain} 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
|
||||
@@ -21,7 +21,7 @@ class ResponseHelper
|
||||
/**
|
||||
* 성공 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 메시지 키 (기본값: 'messages.success')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.success')
|
||||
* @param mixed $data 응답 데이터
|
||||
* @param int $statusCode HTTP 상태 코드 (기본값: 200)
|
||||
* @param array $messageParams 메시지 매개변수
|
||||
@@ -29,7 +29,7 @@ class ResponseHelper
|
||||
* @return JsonResponse JSON 응답
|
||||
*/
|
||||
public static function success(
|
||||
string $messageKey = 'messages.success',
|
||||
string $messageKey = 'common.success',
|
||||
mixed $data = null,
|
||||
int $statusCode = 200,
|
||||
array $messageParams = [],
|
||||
@@ -45,7 +45,7 @@ class ResponseHelper
|
||||
/**
|
||||
* 실패 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 메시지 키 (기본값: 'messages.failed')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.failed')
|
||||
* @param int $statusCode HTTP 상태 코드 (기본값: 400)
|
||||
* @param mixed $errors 오류 정보
|
||||
* @param array $messageParams 메시지 매개변수
|
||||
@@ -53,7 +53,7 @@ class ResponseHelper
|
||||
* @return JsonResponse JSON 응답
|
||||
*/
|
||||
public static function error(
|
||||
string $messageKey = 'messages.failed',
|
||||
string $messageKey = 'common.failed',
|
||||
int $statusCode = 400,
|
||||
mixed $errors = null,
|
||||
array $messageParams = [],
|
||||
@@ -87,14 +87,14 @@ class ResponseHelper
|
||||
* 입력 검증 실패 응답을 생성합니다.
|
||||
*
|
||||
* @param mixed $errors 검증 오류 정보
|
||||
* @param string $messageKey 메시지 키 (기본값: 'messages.validation_failed')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.validation_failed')
|
||||
* @param array $messageParams 메시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 422 상태 코드를 가진 JSON 응답
|
||||
*/
|
||||
public static function validationError(
|
||||
mixed $errors,
|
||||
string $messageKey = 'messages.validation_failed',
|
||||
string $messageKey = 'common.validation_failed',
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
): JsonResponse {
|
||||
@@ -108,13 +108,13 @@ class ResponseHelper
|
||||
/**
|
||||
* 인증 실패 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 메시지 키 (기본값: 'messages.unauthorized')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.unauthorized')
|
||||
* @param array $messageParams 메시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 401 상태 코드를 가진 JSON 응답
|
||||
*/
|
||||
public static function unauthorized(
|
||||
string $messageKey = 'messages.unauthorized',
|
||||
string $messageKey = 'common.unauthorized',
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
): JsonResponse {
|
||||
@@ -127,13 +127,13 @@ class ResponseHelper
|
||||
/**
|
||||
* 권한 부족 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.forbidden')
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'common.forbidden')
|
||||
* @param array $messageParams 멤시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 403 상태 코드를 가진 JSON 응답
|
||||
*/
|
||||
public static function forbidden(
|
||||
string $messageKey = 'messages.forbidden',
|
||||
string $messageKey = 'common.forbidden',
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
): JsonResponse {
|
||||
@@ -146,13 +146,13 @@ class ResponseHelper
|
||||
/**
|
||||
* 리소스를 찾을 수 없음 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.not_found')
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'common.not_found')
|
||||
* @param array $messageParams 멤시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 404 상태 코드를 가진 JSON 응답
|
||||
*/
|
||||
public static function notFound(
|
||||
string $messageKey = 'messages.not_found',
|
||||
string $messageKey = 'common.not_found',
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
): JsonResponse {
|
||||
@@ -165,14 +165,14 @@ class ResponseHelper
|
||||
/**
|
||||
* 서버 내부 오류 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.error_occurred')
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'common.error_occurred')
|
||||
* @param mixed $error 오류 정보 (디버그 모드에서만 표시)
|
||||
* @param array $messageParams 멤시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 500 상태 코드를 가진 JSON 응답
|
||||
*/
|
||||
public static function serverError(
|
||||
string $messageKey = 'messages.error_occurred',
|
||||
string $messageKey = 'common.error_occurred',
|
||||
mixed $error = null,
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
@@ -341,7 +341,7 @@ class ResponseHelper
|
||||
* (색인 누락 안내)가 사라지면 검색이 0건을 돌려주는 사실을 운영자가 알 방법이 없습니다.
|
||||
* `success`/`message`/`data` 키는 부가 데이터로 덮어쓰지 않습니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.success')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.success')
|
||||
* @param JsonResource|ResourceCollection|null $resource JSON 리소스
|
||||
* @param int $statusCode HTTP 상태 코드 (기본값: 200)
|
||||
* @param array $messageParams 멤시지 매개변수
|
||||
@@ -349,7 +349,7 @@ class ResponseHelper
|
||||
* @return JsonResponse JSON 응답
|
||||
*/
|
||||
public static function successWithResource(
|
||||
string $messageKey = 'messages.success',
|
||||
string $messageKey = 'common.success',
|
||||
JsonResource|ResourceCollection|null $resource = null,
|
||||
int $statusCode = 200,
|
||||
array $messageParams = [],
|
||||
@@ -415,14 +415,14 @@ class ResponseHelper
|
||||
/**
|
||||
* 페이지네이션된 리소스 응답을 생성합니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.success')
|
||||
* @param string $messageKey 메시지 키 (기본값: 'common.success')
|
||||
* @param ResourceCollection|null $collection 페이지네이션된 리소스 컬렉션
|
||||
* @param array $messageParams 멤시지 매개변수
|
||||
* @param string $domain 번역 도메인 (기본값: 'core')
|
||||
* @return JsonResponse 페이지네이션 메타 데이터를 포함한 JSON 응답
|
||||
*/
|
||||
public static function successWithPagination(
|
||||
string $messageKey = 'messages.success',
|
||||
string $messageKey = 'common.success',
|
||||
?ResourceCollection $collection = null,
|
||||
array $messageParams = [],
|
||||
string $domain = 'core'
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
namespace App\Http\Controllers\Api\Admin\Identity;
|
||||
|
||||
use App\Enums\PermissionType;
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use App\Http\Requests\Identity\AdminIdentityLogIndexRequest;
|
||||
use App\Http\Requests\Identity\AdminIdentityLogPurgeRequest;
|
||||
@@ -45,7 +46,7 @@ class AdminIdentityLogController extends AdminBaseController
|
||||
|
||||
$paginated = $this->logService->search($filters, (int) ($validated['per_page'] ?? 20));
|
||||
|
||||
return $this->success('messages.success', [
|
||||
return $this->success('common.success', [
|
||||
'data' => IdentityLogResource::collection(collect($paginated->items()))->resolve(),
|
||||
'pagination' => [
|
||||
'current_page' => $paginated->currentPage(),
|
||||
@@ -59,7 +60,7 @@ class AdminIdentityLogController extends AdminBaseController
|
||||
'abilities' => [
|
||||
'can_purge' => $request->user()?->hasPermission(
|
||||
'core.admin.identity.logs.purge',
|
||||
\App\Enums\PermissionType::Admin,
|
||||
PermissionType::Admin,
|
||||
) ?? false,
|
||||
],
|
||||
]);
|
||||
@@ -76,7 +77,7 @@ class AdminIdentityLogController extends AdminBaseController
|
||||
$days = (int) ($request->validated()['older_than_days'] ?? 180);
|
||||
$count = $this->logService->purge($days);
|
||||
|
||||
return $this->success('messages.success', [
|
||||
return $this->success('common.success', [
|
||||
'purged_count' => $count,
|
||||
'older_than_days' => $days,
|
||||
]);
|
||||
|
||||
@@ -60,7 +60,7 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
$paginated = $this->policyService->search($filters, $perPage);
|
||||
$collection = (new PolicyCollection($paginated))->toArray($request);
|
||||
|
||||
return $this->success('messages.success', [
|
||||
return $this->success('common.success', [
|
||||
'data' => $collection['data'],
|
||||
'abilities' => $collection['abilities'] ?? [],
|
||||
'meta' => [
|
||||
@@ -83,7 +83,7 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
$policy = $this->policyService->createAdminPolicy($request->validated());
|
||||
|
||||
return $this->success(
|
||||
'messages.created',
|
||||
'common.created',
|
||||
(new PolicyResource($policy))->toArray($request),
|
||||
201,
|
||||
);
|
||||
@@ -101,7 +101,7 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
$policy = $this->policyService->findById($id);
|
||||
|
||||
if (! $policy) {
|
||||
return $this->error('messages.not_found', 404);
|
||||
return $this->error('common.not_found', 404);
|
||||
}
|
||||
|
||||
$validated = $request->validated();
|
||||
@@ -119,13 +119,13 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
}
|
||||
|
||||
if (! $this->policyService->updatePolicy($policy, $validated)) {
|
||||
return $this->error('messages.failed', 500);
|
||||
return $this->error('common.failed', 500);
|
||||
}
|
||||
|
||||
$policy->refresh();
|
||||
|
||||
return $this->success(
|
||||
'messages.updated',
|
||||
'common.updated',
|
||||
(new PolicyResource($policy))->toArray($request),
|
||||
);
|
||||
}
|
||||
@@ -142,16 +142,16 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
$policy = $this->policyService->findById($id);
|
||||
|
||||
if (! $policy) {
|
||||
return $this->error('messages.not_found', 404);
|
||||
return $this->error('common.not_found', 404);
|
||||
}
|
||||
|
||||
if ($policy->source_type !== IdentityPolicySourceType::Admin) {
|
||||
return $this->forbidden('messages.cannot_delete_system_resource');
|
||||
return $this->forbidden('identity.errors.cannot_delete_system_policy');
|
||||
}
|
||||
|
||||
return $this->policyService->deleteAdminPolicy($policy)
|
||||
? $this->success('messages.deleted')
|
||||
: $this->error('messages.failed', 500);
|
||||
? $this->success('common.deleted')
|
||||
: $this->error('common.failed', 500);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -170,7 +170,7 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
$policy = $this->policyService->findById($id);
|
||||
|
||||
if (! $policy) {
|
||||
return $this->error('messages.not_found', 404);
|
||||
return $this->error('common.not_found', 404);
|
||||
}
|
||||
|
||||
if ($policy->source_type === IdentityPolicySourceType::Admin) {
|
||||
@@ -184,6 +184,6 @@ class AdminIdentityPolicyController extends AdminBaseController
|
||||
return $this->error('identity.errors.reset_field_failed', 422);
|
||||
}
|
||||
|
||||
return $this->successWithResource('messages.success', new PolicyResource($policy->fresh()));
|
||||
return $this->successWithResource('common.success', new PolicyResource($policy->fresh()));
|
||||
}
|
||||
}
|
||||
@@ -5,9 +5,9 @@ namespace App\Http\Controllers\Api\Admin\Identity;
|
||||
use App\Extension\HookManager;
|
||||
use App\Extension\IdentityVerification\IdentityVerificationManager;
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use App\Http\Requests\Identity\AdminIdentityProviderIndexRequest;
|
||||
use App\Http\Resources\Identity\ProviderResource;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
|
||||
/**
|
||||
* 관리자 — IDV 프로바이더 조회 + 설정 스키마 수집 컨트롤러.
|
||||
@@ -28,10 +28,10 @@ class AdminIdentityProviderController extends AdminBaseController
|
||||
/**
|
||||
* 등록된 프로바이더 목록과 각 프로바이더의 설정 스키마를 반환합니다.
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param AdminIdentityProviderIndexRequest $request 검증된 요청 (파라미터 없음)
|
||||
* @return JsonResponse 프로바이더 목록 (settings_schema 포함)
|
||||
*/
|
||||
public function index(Request $request): JsonResponse
|
||||
public function index(AdminIdentityProviderIndexRequest $request): JsonResponse
|
||||
{
|
||||
$providers = array_values($this->manager->all());
|
||||
|
||||
@@ -48,6 +48,6 @@ class AdminIdentityProviderController extends AdminBaseController
|
||||
return $resource + ['settings_schema' => is_array($schema) ? $schema : []];
|
||||
}, $providers);
|
||||
|
||||
return $this->success('messages.success', $rows);
|
||||
return $this->success('common.success', $rows);
|
||||
}
|
||||
}
|
||||
@@ -63,7 +63,7 @@ class PluginSettingsController extends AdminBaseController
|
||||
return $this->notFound('plugins.not_found');
|
||||
}
|
||||
|
||||
return $this->success('messages.success', $this->maskSensitive($identifier, $settings));
|
||||
return $this->success('common.success', $this->maskSensitive($identifier, $settings));
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -109,6 +109,6 @@ class PluginSettingsController extends AdminBaseController
|
||||
return $this->notFound('plugins.not_found');
|
||||
}
|
||||
|
||||
return $this->success('messages.success', $layout);
|
||||
return $this->success('common.success', $layout);
|
||||
}
|
||||
}
|
||||
@@ -48,9 +48,9 @@ class SeoCacheController extends AdminBaseController
|
||||
'by_module' => $this->statsService->getStatsByModule($since),
|
||||
];
|
||||
|
||||
return $this->success('messages.success', $data);
|
||||
return $this->success('common.success', $data);
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('messages.error_occurred', 500, $e->getMessage());
|
||||
return $this->error('common.error_occurred', 500, $e->getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -70,14 +70,14 @@ class SeoCacheController extends AdminBaseController
|
||||
if ($layout) {
|
||||
$count = $this->cacheManager->invalidateByLayout($layout);
|
||||
|
||||
return $this->success('messages.success', ['cleared' => $count]);
|
||||
return $this->success('common.success', ['cleared' => $count]);
|
||||
}
|
||||
|
||||
$this->cacheManager->clearAll();
|
||||
|
||||
return $this->success('messages.success', ['cleared' => 'all']);
|
||||
return $this->success('common.success', ['cleared' => 'all']);
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('messages.error_occurred', 500, $e->getMessage());
|
||||
return $this->error('common.error_occurred', 500, $e->getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -92,12 +92,12 @@ class SeoCacheController extends AdminBaseController
|
||||
{
|
||||
try {
|
||||
// Phase 5의 SeoDeclarationCollector 구현 후 실제 워밍업 로직 추가 예정
|
||||
return $this->success('messages.success', [
|
||||
return $this->success('common.success', [
|
||||
'status' => 'dispatched',
|
||||
'message' => __('seo.warmup_dispatched'),
|
||||
]);
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('messages.error_occurred', 500, $e->getMessage());
|
||||
return $this->error('common.error_occurred', 500, $e->getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -149,9 +149,9 @@ class SeoCacheController extends AdminBaseController
|
||||
try {
|
||||
$urls = $this->cacheManager->getCachedUrls();
|
||||
|
||||
return $this->success('messages.success', ['urls' => $urls, 'count' => count($urls)]);
|
||||
return $this->success('common.success', ['urls' => $urls, 'count' => count($urls)]);
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('messages.error_occurred', 500, $e->getMessage());
|
||||
return $this->error('common.error_occurred', 500, $e->getMessage());
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
namespace App\Http\Controllers\Api\Identity;
|
||||
|
||||
use App\Enums\IdentityOriginType;
|
||||
use App\Extension\IdentityVerification\IdentityVerificationManager;
|
||||
use App\Http\Controllers\Api\Base\PublicBaseController;
|
||||
use App\Http\Requests\Identity\CancelChallengeRequest;
|
||||
@@ -15,6 +16,7 @@ use App\Http\Requests\Identity\VerifyChallengeRequest;
|
||||
use App\Http\Resources\Identity\ChallengeResource;
|
||||
use App\Http\Resources\Identity\ProviderResource;
|
||||
use App\Models\IdentityVerificationLog;
|
||||
use App\Models\User;
|
||||
use App\Services\IdentityPolicyService;
|
||||
use App\Services\IdentityVerificationService;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
@@ -53,7 +55,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
$user = $request->user();
|
||||
|
||||
$target = $user ?: ($validated['target'] ?? []);
|
||||
if (! ($user instanceof \App\Models\User) && empty($target['email']) && empty($target['phone'])) {
|
||||
if (! ($user instanceof User) && empty($target['email']) && empty($target['phone'])) {
|
||||
return $this->error('identity.errors.missing_target', 422);
|
||||
}
|
||||
|
||||
@@ -68,7 +70,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
context: [
|
||||
'ip_address' => $request->ip(),
|
||||
'user_agent' => substr((string) $request->userAgent(), 0, 512),
|
||||
'origin_type' => \App\Enums\IdentityOriginType::Api->value,
|
||||
'origin_type' => IdentityOriginType::Api->value,
|
||||
'origin_identifier' => '/api/identity/challenges',
|
||||
],
|
||||
providerId: $providerId,
|
||||
@@ -136,7 +138,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
*
|
||||
* @param CancelChallengeRequest $request 검증된 요청
|
||||
* @param IdentityVerificationLog $challenge 라우트 모델 바인딩으로 resolve 된 challenge 로그
|
||||
* @return JsonResponse
|
||||
* @return JsonResponse 취소 결과
|
||||
*/
|
||||
public function cancel(CancelChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
|
||||
{
|
||||
@@ -159,7 +161,8 @@ class IdentityVerificationController extends PublicBaseController
|
||||
*
|
||||
* @param ShowChallengeRequest $request 검증된 요청
|
||||
* @param IdentityVerificationLog $challenge 라우트 모델 바인딩으로 resolve 된 challenge 로그
|
||||
* @return JsonResponse
|
||||
* @return JsonResponse 공개 안전 상태 필드
|
||||
*
|
||||
* @since engine-v1.46.0
|
||||
*/
|
||||
public function show(ShowChallengeRequest $request, IdentityVerificationLog $challenge): JsonResponse
|
||||
@@ -170,7 +173,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
return $this->error('identity.errors.challenge_not_found', 404);
|
||||
}
|
||||
|
||||
return $this->success('messages.success', $status);
|
||||
return $this->success('common.success', $status);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -188,6 +191,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
* @param IdentityCallbackRequest $request 검증된 요청
|
||||
* @param string $providerId 콜백을 보낸 provider 식별자
|
||||
* @return JsonResponse|RedirectResponse
|
||||
*
|
||||
* @since engine-v1.46.0
|
||||
*/
|
||||
public function callback(IdentityCallbackRequest $request, string $providerId)
|
||||
@@ -271,7 +275,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
$providers,
|
||||
);
|
||||
|
||||
return $this->success('messages.success', $data);
|
||||
return $this->success('common.success', $data);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -300,7 +304,7 @@ class IdentityVerificationController extends PublicBaseController
|
||||
];
|
||||
}
|
||||
|
||||
return $this->success('messages.success', $data);
|
||||
return $this->success('common.success', $data);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -353,11 +357,11 @@ class IdentityVerificationController extends PublicBaseController
|
||||
|
||||
$policy = $this->policyService->resolve($scope, $target);
|
||||
if (! $policy || ! $policy->enabled) {
|
||||
return $this->success('messages.success', null);
|
||||
return $this->success('common.success', null);
|
||||
}
|
||||
|
||||
// 민감 필드는 노출하지 않고 UI 힌트에 필요한 최소 필드만 반환
|
||||
return $this->success('messages.success', [
|
||||
return $this->success('common.success', [
|
||||
'policy_key' => $policy->key,
|
||||
'scope' => $policy->scope,
|
||||
'target' => $policy->target,
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
<?php
|
||||
|
||||
namespace App\Http\Requests\Identity;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
* 관리자 IDV 프로바이더 목록 조회 검증.
|
||||
*
|
||||
* 등록된 프로바이더 전체를 설정 스키마와 함께 반환하는 엔드포인트로, 필터/페이지네이션
|
||||
* 파라미터를 받지 않습니다. 검증 규칙은 비어 있지만, 컨트롤러가 base `Illuminate\Http\Request`
|
||||
* 를 주입받지 않도록 전용 FormRequest 를 둡니다 (규정: docs/backend/validation.md).
|
||||
*
|
||||
* 공개용 `ProvidersIndexRequest`(인증 없는 메타데이터 조회)와 달리 이쪽은 관리자 전용이며,
|
||||
* 인증/권한은 라우트의 permission 미들웨어가 담당합니다.
|
||||
*/
|
||||
class AdminIdentityProviderIndexRequest extends FormRequest
|
||||
{
|
||||
/**
|
||||
* 요청 권한 — 라우트 permission 미들웨어가 담당하므로 true 고정.
|
||||
*
|
||||
* @return bool 항상 true (권한은 미들웨어 체인에서 처리)
|
||||
*/
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 검증 규칙을 반환합니다.
|
||||
*
|
||||
* @return array<string, array<int, mixed>> 검증 규칙 (요청 파라미터 없음)
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
return [];
|
||||
}
|
||||
}
|
||||
@@ -199,6 +199,10 @@ class IdentityVerificationService
|
||||
$publicPayload = $log->properties['public_payload'];
|
||||
}
|
||||
|
||||
// 누적 시도 횟수(attempts) 는 노출하지 않는다.
|
||||
// 이 엔드포인트는 권한 가드 없는 공개 폴링용이라 challenge id 만 알면 누구나 조회할 수 있고,
|
||||
// 남의 인증 시도 실패 횟수가 드러나면 잠금 직전까지 시도 횟수를 맞춰 보는 데 쓰일 수 있다.
|
||||
// 상한(max_attempts) 은 정책 상수라 노출해도 무방하다 — 아래 반환 배열의 주석 참조.
|
||||
return [
|
||||
'id' => $log->id,
|
||||
'status' => $log->status->value,
|
||||
|
||||
@@ -22,6 +22,14 @@ class ApiDocScaffolder
|
||||
*/
|
||||
private const GEN_END = '<!-- @generated:end -->';
|
||||
|
||||
/**
|
||||
* @var string 응답 본문이 실측 산출물임을 표시하는 출처 마커
|
||||
*
|
||||
* 이 마커가 없는 응답 본문은 사람이 작성한 것으로 간주해 재생성 시 보존한다.
|
||||
* 실측 표본 1회는 사람이 아는 사실(성공·엣지 케이스)보다 좁으므로 덮어쓸 권한이 없다.
|
||||
*/
|
||||
private const PROBED_BODY_MARKER = '<!-- @probed -->';
|
||||
|
||||
/**
|
||||
* @var int 응답 예시의 목록(`data.data[]`) 최대 표시 항목 수
|
||||
*
|
||||
@@ -61,6 +69,28 @@ class ApiDocScaffolder
|
||||
private readonly ParameterDescriber $paramDescriber = new ParameterDescriber
|
||||
) {}
|
||||
|
||||
/**
|
||||
* 엔드포인트의 `@generated` 블록 키를 만듭니다.
|
||||
*
|
||||
* 기본은 라우트명이다. 다만 `Route::match(['get','post'], ...)->name('x')` 처럼 **하나의
|
||||
* 라우트명이 여러 메서드**를 등록하면(KG이니시스 CBT/모바일 콜백), 한 문서에 같은 키의
|
||||
* 생성 블록이 둘 생긴다. 블록 조회는 `strpos` 로 첫 출현을 잡으므로 두 번째 블록의 사람
|
||||
* 서술이 재생성마다 유실된다. 그런 라우트에 한해 메서드를 접미로 붙여 키를 고유화한다.
|
||||
*
|
||||
* 중복이 아닌 절대다수의 라우트는 키를 그대로 둔다 — 전 문서의 키를 바꾸면 기존 블록과
|
||||
* 대조가 어긋나 사람 서술이 통째로 유실되기 때문이다.
|
||||
*
|
||||
* @param array<string, mixed> $route 라우트 메타데이터
|
||||
* @param bool $methodScoped 라우트명이 문서 안에서 중복되는가 (메서드 접미 필요)
|
||||
* @return string 생성 블록 키
|
||||
*/
|
||||
public function generatedKey(array $route, bool $methodScoped = false): string
|
||||
{
|
||||
$name = $route['name'] ?: $route['uri'];
|
||||
|
||||
return $methodScoped ? $name.'::'.strtolower((string) $route['method']) : $name;
|
||||
}
|
||||
|
||||
/**
|
||||
* 단일 엔드포인트의 마크다운 섹션을 생성합니다.
|
||||
*
|
||||
@@ -69,13 +99,14 @@ class ApiDocScaffolder
|
||||
* @param array<string, mixed>|null $schema 실측 응답 스키마 (null=실측 안 됨)
|
||||
* @param array<string, mixed> $probeMeta 실측 메타 (status, skipped_reason, base_url, resolved_uri, body)
|
||||
* @param array<string, string> $commentMap 컬럼명 => 주석 (필드 설명 기본값)
|
||||
* @param bool $methodScopedKey 라우트명이 문서 안에서 중복되어 메서드 접미가 필요한가
|
||||
* @return string 마크다운 섹션
|
||||
*/
|
||||
public function endpointSection(array $route, array $request, ?array $schema, array $probeMeta, array $commentMap = []): string
|
||||
public function endpointSection(array $route, array $request, ?array $schema, array $probeMeta, array $commentMap = [], bool $methodScopedKey = false): string
|
||||
{
|
||||
$name = $route['name'] ?: '(unnamed)';
|
||||
$heading = "### {$route['method']} {$route['uri']}";
|
||||
$genKey = $name;
|
||||
$genKey = $this->generatedKey($route, $methodScopedKey);
|
||||
|
||||
$lines = [];
|
||||
$lines[] = $heading;
|
||||
@@ -129,16 +160,17 @@ class ApiDocScaffolder
|
||||
*/
|
||||
private const GEN_KEY_EXTENSIONS = 'api-readme-extensions';
|
||||
|
||||
/**
|
||||
* 확장 목차 섹션 헤딩. extensionIndexBlock() 이 이 헤딩까지 소유하므로,
|
||||
* 사람 서술 추출 시 여기부터는 잘라낸다 (SSoT — 두 곳에 문자열을 두지 않는다).
|
||||
*/
|
||||
private const EXTENSION_INDEX_HEADING = '## 확장 API 레퍼런스';
|
||||
|
||||
/**
|
||||
* @var string 코어/확장 README 의 도메인 목차 생성 블록 키
|
||||
*/
|
||||
private const GEN_KEY_INDEX = 'api-readme-index';
|
||||
|
||||
/**
|
||||
* @var string 코어 README 의 확장 API 목차 섹션 헤딩 (사람 서술 보존 경계)
|
||||
*/
|
||||
private const EXTENSIONS_HEADING = '확장 API 레퍼런스';
|
||||
|
||||
/**
|
||||
* 대상(코어/확장)의 API 문서 디렉토리 목차(README.md)를 생성합니다.
|
||||
*
|
||||
@@ -164,6 +196,9 @@ class ApiDocScaffolder
|
||||
?string $existing = null,
|
||||
?array $extensions = null
|
||||
): string {
|
||||
// 줄 끝 정규화 — mergeDocument 와 같은 이유 (CRLF 체크아웃에서 줄 단위 매칭이 전부 실패).
|
||||
$existing = $existing === null ? null : $this->normalizeEol($existing);
|
||||
|
||||
usort($entries, fn ($a, $b) => strcmp($a['domain'], $b['domain']));
|
||||
$total = array_sum(array_column($entries, 'count'));
|
||||
|
||||
@@ -258,7 +293,7 @@ class ApiDocScaffolder
|
||||
});
|
||||
|
||||
$lines = [];
|
||||
$lines[] = '## '.self::EXTENSIONS_HEADING;
|
||||
$lines[] = self::EXTENSION_INDEX_HEADING;
|
||||
$lines[] = '';
|
||||
$lines[] = '> 각 확장이 자신의 API 문서를 소유합니다. 아래 표는 자동 생성됩니다.';
|
||||
$lines[] = '';
|
||||
@@ -463,9 +498,11 @@ class ApiDocScaffolder
|
||||
}
|
||||
|
||||
// 403: admin 게이트 또는 permission 요구 → 권한 부족.
|
||||
// permission 은 여러 권한의 OR 조합(`core.modules.read | core.menus.read`)일 수 있으므로
|
||||
// 셀에 박기 전에 파이프를 이스케이프한다 — 안 하면 3열 표가 갈라져 깨진다.
|
||||
if ($this->hasMiddleware($mw, 'AdminMiddleware') || ! empty($route['permission'])) {
|
||||
$cond = ! empty($route['permission'])
|
||||
? "요구 권한(`{$route['permission']}`)이 없는 경우"
|
||||
? '요구 권한(`'.$this->escapeCell((string) $route['permission']).'`)이 없는 경우'
|
||||
: '관리자 권한이 없는 경우';
|
||||
$rows[] = "| 403 | Forbidden | {$cond} |";
|
||||
}
|
||||
@@ -497,7 +534,10 @@ class ApiDocScaffolder
|
||||
* - 바디 있는 메서드(POST/PUT/PATCH)는 요청 파라미터 표의 필수 파라미터 + 타입별 샘플값을
|
||||
* 빈 줄 뒤 JSON 바디로 붙입니다.
|
||||
*
|
||||
* path 파라미터가 실측 치환값(`resolved_uri`)으로 채워졌으면 그 값을, 아니면 `{param}` placeholder 를 쓴다.
|
||||
* path 파라미터는 실측 치환값이 아니라 라우트 정의의 `{param}` placeholder 로 고정한다.
|
||||
* 실측 치환값(`resolved_uri`)을 쓰면 실측 성패·시드 데이터에 따라 같은 엔드포인트의 예시가
|
||||
* `/brands/1` ↔ `/brands/{brand}` 로 흔들려, 재실행마다 무관한 문서까지 diff 가 발생한다.
|
||||
* 레퍼런스 문서는 "어떤 파라미터를 넣는가"를 보여주는 것이 목적이므로 placeholder 가 정본이다.
|
||||
*
|
||||
* @param array<string, mixed> $route 라우트 메타데이터
|
||||
* @param array<string, mixed> $request FormRequest 분석 결과
|
||||
@@ -507,7 +547,7 @@ class ApiDocScaffolder
|
||||
public function requestExampleBlock(array $route, array $request, array $probeMeta): string
|
||||
{
|
||||
$method = strtoupper((string) $route['method']);
|
||||
$path = (string) ($probeMeta['resolved_uri'] ?? $route['uri']);
|
||||
$path = (string) $route['uri'];
|
||||
|
||||
// GET/DELETE 의 query 파라미터는 URL 쿼리스트링으로 반영한다(바디가 아니라 URL).
|
||||
if (in_array($method, ['GET', 'DELETE'], true)) {
|
||||
@@ -805,7 +845,7 @@ class ApiDocScaffolder
|
||||
$capped = $this->capExampleSize($masked);
|
||||
$json = json_encode($capped, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
|
||||
|
||||
return "```http\nHTTP/1.1 {$status}\n```\n\n```json\n".(string) $json."\n```";
|
||||
return self::PROBED_BODY_MARKER."\n\n```http\nHTTP/1.1 {$status}\n```\n\n```json\n".(string) $json."\n```";
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1028,6 +1068,24 @@ class ApiDocScaffolder
|
||||
return str_replace(['|', "\n", "\r"], ['\\|', ' ', ''], $text);
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서의 줄 끝을 LF 로 정규화합니다.
|
||||
*
|
||||
* 보존 로직(표 셀·응답 본문·에러 표·사람 서술)은 전부 `explode("\n")` 후 줄 끝 매칭
|
||||
* (`str_ends_with($line, ' |')` 등)으로 동작한다. Windows 체크아웃(core.autocrlf=true)이
|
||||
* 내려준 CRLF 문서에서는 줄 끝에 \r 이 남아 이 매칭이 전부 실패하고, 결과적으로 사람이
|
||||
* 채운 셀·본문이 하나도 보존되지 않은 채 TODO/마커로 퇴행한다.
|
||||
*
|
||||
* 문서는 `.gitattributes` 가 `eol=lf` 로 저장하므로 정규화가 저장 형식을 바꾸지 않는다.
|
||||
*
|
||||
* @param string $content 기존 문서 내용
|
||||
* @return string LF 로 정규화된 내용
|
||||
*/
|
||||
private function normalizeEol(string $content): string
|
||||
{
|
||||
return str_replace(["\r\n", "\r"], "\n", $content);
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서에 새 생성 블록을 병합합니다. 사람 서술은 보존합니다.
|
||||
*
|
||||
@@ -1043,6 +1101,12 @@ class ApiDocScaffolder
|
||||
return $header."\n".implode("\n", $sections);
|
||||
}
|
||||
|
||||
// Windows 체크아웃(core.autocrlf=true)은 문서를 CRLF 로 내려준다. 아래 보존 로직은
|
||||
// 전부 `explode("\n")` + 줄 끝 매칭(`str_ends_with($line, ' |')`) 기반이라, 줄 끝에
|
||||
// \r 이 남아 있으면 표 행이 하나도 파싱되지 않아 사람이 채운 셀이 통째로 유실된다.
|
||||
// 파싱 전에 줄 끝을 LF 로 정규화한다 (문서는 .gitattributes 가 eol=lf 로 저장한다).
|
||||
$existing = $this->normalizeEol($existing);
|
||||
|
||||
$merged = $header."\n";
|
||||
|
||||
foreach ($sections as $i => $section) {
|
||||
@@ -1057,7 +1121,25 @@ class ApiDocScaffolder
|
||||
// 순서 주의: 표 자체를 되살린 뒤에 셀 설명을 맞춘다.
|
||||
$withFields = $this->restoreEmptyProbeTable($withProse, $existing, $key, $legacy);
|
||||
$withTables = $this->restoreTableDescriptions($withFields, $existing, $key, $legacy);
|
||||
$merged .= $this->restoreErrorSection($withTables, $existing, $key, $legacy)."\n";
|
||||
// 실측 불가 마커 자리·응답 예시를 사람이 채운 경우 되살린다
|
||||
// (@probed 출처 마커 부재 = 사람 작성분, 위치 기반이므로 블록 본문으로만 대조).
|
||||
$withBodies = $this->applyPreservedResponseBodies(
|
||||
$withTables,
|
||||
$this->extractGeneratedBlockBody($existing, $key) ?? $legacy
|
||||
);
|
||||
$withErrors = $this->restoreErrorSection($withBodies, $existing, $key, $legacy);
|
||||
// 에러 표는 상태코드 행 단위로도 병합한다 — restoreErrorSection 은 새 표가 통째로
|
||||
// 스텁일 때의 복원만 다루므로, 자동 추론이 초안을 만들어 낸 경우 사람이 보강한
|
||||
// 행(409 충돌·429 제한 등 도메인 특이 에러)이 덮여 사라진다. 행 병합을 겹쳐
|
||||
// 같은 상태코드는 사람 행이 이기고, 자동 추론에만 있는 상태코드는 새로 편입한다.
|
||||
// 에러 표는 상태코드가 엔드포인트마다 중복되어 키가 고유하지 않으므로, 이 엔드포인트만
|
||||
// 정확히 잘라낸 블록으로만 대조한다. extractGeneratedBlockBody 가 아니라
|
||||
// exactGeneratedBlock 을 쓰는 이유: 에러 표 추출(extractErrorTable)은 생성 블록
|
||||
// 종료 마커를 표의 끝 경계로 삼는데, 전자는 그 마커를 잘라내고 돌려준다.
|
||||
$merged .= $this->applyPreservedErrorTable(
|
||||
$withErrors,
|
||||
$this->exactGeneratedBlock($existing, $key)
|
||||
)."\n";
|
||||
}
|
||||
|
||||
return $merged;
|
||||
@@ -1077,6 +1159,11 @@ class ApiDocScaffolder
|
||||
* "사람이 작성한 설명은 보존됩니다" 를 표 셀에도 적용한다. 사실이 바뀌면 사람이 그 셀을
|
||||
* 고치거나 비우고, 비운 셀은 다음 재생성이 채운다.
|
||||
*
|
||||
* 응답 필드 표의 `실측 예시값` 열도 보존한다. 실측값은 호출 시점 DB 상태가 낳은 표본
|
||||
* 하나라, 매번 새 값으로 덮으면 스펙이 그대로인 무관한 문서까지 재실행마다 diff 가 난다.
|
||||
* 스펙이 실제로 바뀐 경우에만 갱신하도록, 같은 필드의 타입이 그대로면 기존 예시값을 유지하고
|
||||
* 타입이 달라졌으면 새 실측값을 채택한다. 기존 문서에 없던 신규 필드는 새 값을 그대로 쓴다.
|
||||
*
|
||||
* @param string $section 새로 생성된 섹션
|
||||
* @param string $existing 기존 문서 전체
|
||||
* @param string $key 라우트명(생성 블록 키)
|
||||
@@ -1090,35 +1177,226 @@ class ApiDocScaffolder
|
||||
return $section;
|
||||
}
|
||||
|
||||
$oldDescriptions = $this->collectRowDescriptions($oldBlock);
|
||||
if ($oldDescriptions === []) {
|
||||
$previousCells = $this->collectTableCells($oldBlock);
|
||||
if ($previousCells === []) {
|
||||
return $section;
|
||||
}
|
||||
|
||||
$lines = explode("\n", $section);
|
||||
foreach ($lines as $index => $line) {
|
||||
if (! str_starts_with(trim($line), '|')) {
|
||||
$parsed = $this->parseTableRow($line);
|
||||
if ($parsed === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$cells = $this->splitRowCells($line);
|
||||
if (count($cells) < 2) {
|
||||
$previousRow = $previousCells[$parsed['key']] ?? null;
|
||||
|
||||
// 기존 문서에 없던 행(= 신규 필드/파라미터)은 새로 생성된 값을 그대로 채택한다.
|
||||
if ($previousRow === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$lastIndex = count($cells) - 1;
|
||||
$rowKey = $this->rowKey($cells);
|
||||
if ($rowKey === null || ! isset($oldDescriptions[$rowKey])) {
|
||||
continue;
|
||||
$cols = $parsed['cols'];
|
||||
|
||||
// 응답 필드 표(4열)의 타입·실측 예시값 열을 보존한다.
|
||||
// 실측값은 호출 시점 DB 상태의 표본 하나라, 매번 새 값으로 덮으면 스펙이 그대로인
|
||||
// 무관한 문서까지 재실행마다 diff 가 난다. 타입이 그대로면 기존 예시값을 유지하고,
|
||||
// 타입이 바뀌었으면(스펙 변경) 새 실측값으로 갱신한다.
|
||||
//
|
||||
// 단 nullable 필드는 그 행의 표본이 null 이냐에 따라 관측 타입이 흔들린다
|
||||
// (`loggable_type` 이 string ↔ null). null 관측은 "타입이 바뀌었다"가 아니라
|
||||
// "이번 표본에는 값이 없었다" 는 뜻이므로, 기존에 실제 값을 관측해 둔 행은 유지한다.
|
||||
if (count($cols) === 4 && count($previousRow['cols']) === 4) {
|
||||
$previousType = $previousRow['cols'][1];
|
||||
$previousExample = $previousRow['cols'][2];
|
||||
$observedNothing = $cols[1] === 'null';
|
||||
|
||||
$keepPrevious = $previousExample !== ''
|
||||
&& ($previousType === $cols[1] || ($observedNothing && $previousType !== 'null'));
|
||||
|
||||
if ($keepPrevious) {
|
||||
$cols[1] = $previousType;
|
||||
$cols[2] = $previousExample;
|
||||
}
|
||||
}
|
||||
|
||||
$cells[$lastIndex] = ' '.$oldDescriptions[$rowKey].' ';
|
||||
$lines[$index] = '|'.implode('|', $cells).'|';
|
||||
// 마지막 열(사람 서술)은 기존 값이 있으면 언제나 우선한다.
|
||||
if ($previousRow['value'] !== null) {
|
||||
$cols[count($cols) - 1] = $previousRow['value'];
|
||||
}
|
||||
|
||||
$rebuilt = '| '.implode(' | ', $cols).' |';
|
||||
|
||||
if ($rebuilt !== $line) {
|
||||
$lines[$index] = $rebuilt;
|
||||
}
|
||||
}
|
||||
|
||||
return implode("\n", $lines);
|
||||
}
|
||||
|
||||
/**
|
||||
* 사람이 보강한 에러 응답 표를 보존합니다.
|
||||
*
|
||||
* 에러 표는 라우트 메타(미들웨어·FormRequest 유무)에서 대표 상태코드만 추론하는 초안이라,
|
||||
* 도메인 특이 에러(409 충돌·429 제한, 구체적 발생 조건)는 사람이 행을 직접 추가해 채운다.
|
||||
* 재생성이 그 표를 자동 추론 결과로 덮으면 사람이 쓴 행이 통째로 사라진다
|
||||
* (실제로 KG이니시스 결제 문서의 403·404·422·429 행이 "대표 에러 없음" 으로 지워졌다).
|
||||
*
|
||||
* 행 키(상태코드) 단위로 병합한다. 자동 추론이 만든 행은 그대로 두되(라우트 메타가 바뀌면
|
||||
* 그 결과가 정본이다), 기존 문서에만 있는 행 — 사람이 추가한 도메인 특이 에러 — 은
|
||||
* 상태코드 오름차순 자리에 되살린다. 같은 상태코드가 양쪽에 있으면 사람이 쓴 발생 조건이
|
||||
* 자동 문구보다 구체적이므로 기존 행을 우선한다.
|
||||
*
|
||||
* @param string $section 표 셀 보존이 끝난 섹션
|
||||
* @param string|null $previous 기존 문서의 같은 엔드포인트 생성 블록
|
||||
* @return string 에러 표가 보존된 섹션
|
||||
*/
|
||||
private function applyPreservedErrorTable(string $section, ?string $previous): string
|
||||
{
|
||||
if ($previous === null) {
|
||||
return $section;
|
||||
}
|
||||
|
||||
$previousRows = $this->errorTableRows($previous);
|
||||
$currentBody = $this->extractErrorTable($section);
|
||||
|
||||
if ($currentBody === null) {
|
||||
return $section;
|
||||
}
|
||||
|
||||
// 기존 본문이 표가 아닌 사람 서술인 경우 (자동 추론이 에러 행을 만들지 못하는 공개 조회
|
||||
// 엔드포인트에서, 사람이 `대표 에러 없음` 초안 자리를 "왜 도메인 에러가 없는지" 로 채운 것).
|
||||
// 표 행이 없다고 보존을 건너뛰면 재생성이 그 서술을 TODO 초안으로 덮는다.
|
||||
if ($previousRows === []) {
|
||||
$previousBody = $this->extractErrorTable($previous);
|
||||
|
||||
$previousIsHumanProse = $previousBody !== null
|
||||
&& trim($previousBody) !== ''
|
||||
&& ! $this->isTodoCell($previousBody)
|
||||
&& ! str_contains($previousBody, '대표 에러 없음');
|
||||
|
||||
if ($previousIsHumanProse) {
|
||||
return str_replace($currentBody, trim($previousBody), $section);
|
||||
}
|
||||
|
||||
return $section;
|
||||
}
|
||||
|
||||
// 상태코드 키로 병합. `+` 는 왼쪽 우선이므로 기존 행을 먼저 둬서, 같은 상태코드면
|
||||
// 사람이 쓴 구체적 조건이 자동 문구를 이긴다. 자동 추론에만 있는 상태코드는 새로 편입된다.
|
||||
$merged = $previousRows + $this->errorTableRows($section);
|
||||
|
||||
if ($merged === []) {
|
||||
return $section;
|
||||
}
|
||||
|
||||
ksort($merged, SORT_NUMERIC);
|
||||
|
||||
$table = "| 상태코드 | 의미 | 발생 조건 |\n| --- | --- | --- |\n".implode("\n", $merged);
|
||||
|
||||
return str_replace($currentBody, $table, $section);
|
||||
}
|
||||
|
||||
/**
|
||||
* 섹션의 에러 응답 표에서 [상태코드 => 행] 맵을 수집합니다.
|
||||
*
|
||||
* @param string $section 엔드포인트 섹션 (또는 생성 블록)
|
||||
* @return array<string, string> 상태코드 => 표 행 원문
|
||||
*/
|
||||
private function errorTableRows(string $section): array
|
||||
{
|
||||
$body = $this->extractErrorTable($section);
|
||||
|
||||
if ($body === null) {
|
||||
return [];
|
||||
}
|
||||
|
||||
$rows = [];
|
||||
|
||||
foreach (explode("\n", $body) as $line) {
|
||||
if (! preg_match('/^\|\s*(\d{3})\s*\|/', $line, $m)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$rows[$m[1]] = rtrim($line);
|
||||
}
|
||||
|
||||
return $rows;
|
||||
}
|
||||
|
||||
/**
|
||||
* 응답 예시 본문에서 JSON 의 키 구조(값 제외)를 추출합니다.
|
||||
*
|
||||
* 값이 아니라 **필드 집합**만 비교하기 위한 지문이다. 리소스에 필드가 추가/삭제되면
|
||||
* 지문이 달라지므로 새 실측 예시를 채택하고, 값만 달라진 경우(`updated_at` 등)에는
|
||||
* 지문이 같아 기존 예시를 유지한다.
|
||||
*
|
||||
* @param string $body 응답 예시 본문 (```json 블록 포함)
|
||||
* @return string|null 키 구조 지문 (JSON 블록이 없거나 파싱 실패 시 null)
|
||||
*/
|
||||
private function exampleKeyShape(string $body): ?string
|
||||
{
|
||||
if (! preg_match('/```json\n(.*?)\n```/s', $body, $m)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$decoded = json_decode($m[1], true);
|
||||
|
||||
if (! is_array($decoded)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$shape = function (mixed $value) use (&$shape): mixed {
|
||||
if (! is_array($value)) {
|
||||
return '_';
|
||||
}
|
||||
|
||||
// 리스트는 첫 원소의 구조만 대표로 본다(원소 수는 데이터 양에 따라 달라진다).
|
||||
if (array_is_list($value)) {
|
||||
return $value === [] ? [] : [$shape($value[0])];
|
||||
}
|
||||
|
||||
$out = [];
|
||||
|
||||
foreach ($value as $k => $v) {
|
||||
$out[$k] = $shape($v);
|
||||
}
|
||||
|
||||
ksort($out);
|
||||
|
||||
return $out;
|
||||
};
|
||||
|
||||
return json_encode($shape($decoded));
|
||||
}
|
||||
|
||||
/**
|
||||
* 섹션에서 `**에러 응답**` 본문(표 또는 "대표 에러 없음" 문구)을 잘라냅니다.
|
||||
*
|
||||
* @param string $section 엔드포인트 섹션
|
||||
* @return string|null 에러 응답 본문 (없으면 null)
|
||||
*/
|
||||
private function extractErrorTable(string $section): ?string
|
||||
{
|
||||
$start = strpos($section, '**에러 응답**');
|
||||
|
||||
if ($start === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$bodyStart = $start + strlen('**에러 응답**');
|
||||
$end = strpos($section, self::GEN_END, $bodyStart);
|
||||
|
||||
if ($end === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$body = trim(substr($section, $bodyStart, $end - $bodyStart));
|
||||
|
||||
return $body === '' ? null : $body;
|
||||
}
|
||||
|
||||
/**
|
||||
* 이번 실측이 빈 응답이라 필드 표가 사라졌으면 기존 표를 되살립니다.
|
||||
*
|
||||
@@ -1330,45 +1608,6 @@ class ApiDocScaffolder
|
||||
return substr($existing, $startPos, $endPos - $startPos);
|
||||
}
|
||||
|
||||
/**
|
||||
* 표 블록에서 `행 키 => 설명` 맵을 수집합니다 (TODO 셀은 제외).
|
||||
*
|
||||
* @param string $block 생성 블록 본문
|
||||
* @return array<string, string> 행 키 => 설명
|
||||
*/
|
||||
private function collectRowDescriptions(string $block): array
|
||||
{
|
||||
$map = [];
|
||||
|
||||
foreach (explode("\n", $block) as $line) {
|
||||
if (! str_starts_with(trim($line), '|')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$cells = $this->splitRowCells($line);
|
||||
if (count($cells) < 2) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$description = trim($cells[count($cells) - 1]);
|
||||
if ($description === '' || str_contains($description, '<!-- TODO')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// 구분선(`| --- | --- |`)은 건너뛴다.
|
||||
if (preg_match('/^-{2,}$/', $description)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$rowKey = $this->rowKey($cells);
|
||||
if ($rowKey !== null) {
|
||||
$map[$rowKey] = $description;
|
||||
}
|
||||
}
|
||||
|
||||
return $map;
|
||||
}
|
||||
|
||||
/** @var string 분해 중 인라인 코드 안 파이프를 감춰 두는 자리표시자 (문서에 등장할 수 없는 제어문자) */
|
||||
private const CELL_PIPE_PLACEHOLDER = "\x00PIPE\x00";
|
||||
|
||||
@@ -1378,7 +1617,7 @@ class ApiDocScaffolder
|
||||
* 셀 구분자가 아닌 파이프는 두 종류다. 이스케이프된 파이프(`\|`)와 **인라인 코드 스팬 안의
|
||||
* 파이프**다. 후자는 실제 문서에 흔하다 — 셸 메타문자 안내처럼 파이프 자체를 설명하는 문장이
|
||||
* 그렇다. 이를 구분자로 보면 셀 수가 늘어 마지막 셀(=설명)이 파이프 뒤 조각으로 바뀌고,
|
||||
* {@see self::collectRowDescriptions()} 가 그 조각을 사람이 쓴 설명으로 승계해 문장 앞부분이
|
||||
* {@see self::parseTableRow()} 가 그 조각을 사람이 쓴 설명으로 승계해 문장 앞부분이
|
||||
* 통째로 잘려 나간다. 오류 없이 문서만 훼손되므로 분해 단계에서 막는다.
|
||||
*
|
||||
* @param string $line 표 행
|
||||
@@ -1411,27 +1650,276 @@ class ApiDocScaffolder
|
||||
}
|
||||
|
||||
/**
|
||||
* 표 행의 식별 키를 만듭니다.
|
||||
* 새 섹션의 `실측 제외` 응답 본문을, 기존 섹션에서 사람이 채운 본문으로 되살립니다.
|
||||
*
|
||||
* 파라미터 표는 `이름 + 위치(query/body/path)` 로, 응답 필드/에러 표는 이름(또는 상태코드)만으로
|
||||
* 식별한다. 두 표의 키가 섞이지 않도록 두 번째 셀이 위치 값일 때만 결합한다.
|
||||
* 실측이 불가한 엔드포인트(쓰기 메서드·바이너리·미치환 path)는 `**응답 필드**` / `**응답 예시**`
|
||||
* 자리에 `<!-- 실측 제외: ... -->` 마커만 생성된다. 사람이 코드를 근거로 그 자리를 채워도
|
||||
* 다음 재생성이 블록을 통째로 재조립하면서 마커로 되돌려, 작성분이 통째로 사라졌다.
|
||||
*
|
||||
* @param array<int, string> $cells 셀 배열
|
||||
* @return string|null 행 키 (식별 불가 시 null)
|
||||
* 보존 규칙은 표 셀(`restoreTableDescriptions`)과 같다 — **사람이 쓴 본문은 언제나 이긴다.**
|
||||
* 실측 결과는 기본값이지 덮어쓰기 권한이 아니다. 실측 1회가 관측한 표본은 사람이 코드에서
|
||||
* 읽어낸 사실(성공 케이스·엣지 케이스)보다 좁기 때문이다. 실제로 `reissue` 의 실측 표본은
|
||||
* `data: null`(전액 환불) 하나뿐이라, 실측 우선 규칙은 사람이 쓴 성공 예시를 지웠다.
|
||||
*
|
||||
* 두 하위 섹션의 판정 기준이 다르다:
|
||||
* - **응답 예시**: 실측 산출물에 `@probed` 출처 마커가 붙는다. 마커가 없으면 사람 작성분.
|
||||
* - **응답 필드**: 표 자체는 행 키로 대조하는 `restoreTableDescriptions` 가 이미 지킨다.
|
||||
* 따라서 여기서는 실측 실패로 마커만 남은 자리를 사람이 채운 경우만 되살린다.
|
||||
*
|
||||
* @param string $section 새로 생성된 섹션
|
||||
* @param string|null $previous 기존 문서의 같은 엔드포인트 생성 블록 (없으면 null)
|
||||
* @return string 사람이 작성한 응답 본문이 되살아난 섹션
|
||||
*/
|
||||
private function rowKey(array $cells): ?string
|
||||
private function applyPreservedResponseBodies(string $section, ?string $previous): string
|
||||
{
|
||||
$name = trim($cells[0]);
|
||||
if ($name === '' || preg_match('/^-{2,}$/', $name)) {
|
||||
if ($previous === null) {
|
||||
return $section;
|
||||
}
|
||||
|
||||
// [본문 시작 헤딩, 본문 끝 헤딩 후보, 실측 산출물 판정자]
|
||||
$subsections = [
|
||||
[
|
||||
'**응답 필드** (`data` 내부)',
|
||||
['**응답 예시**', '**에러 응답**'],
|
||||
// 실측 성공 시 표가 생기고 그 표는 restoreTableDescriptions 가 지킨다.
|
||||
// 여기서 되살릴 대상은 "실측 실패 마커 자리를 사람이 채운" 경우뿐이다.
|
||||
fn (string $body): bool => $this->isProbeSkipMarker($body),
|
||||
],
|
||||
[
|
||||
'**응답 예시**',
|
||||
['**에러 응답**'],
|
||||
fn (string $body): bool => $this->isProbeSkipMarker($body) || str_contains($body, self::PROBED_BODY_MARKER),
|
||||
],
|
||||
];
|
||||
|
||||
foreach ($subsections as [$label, $terminators, $isAutoGenerated]) {
|
||||
$previousBody = $this->extractSubsectionBody($previous, $label, $terminators);
|
||||
|
||||
if ($previousBody === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$bounds = $this->locateSubsectionBody($section, $label, $terminators);
|
||||
|
||||
if ($bounds === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
[$start, $end] = $bounds;
|
||||
$newBody = substr($section, $start, $end - $start);
|
||||
|
||||
// 이번 실측이 실패했으면(마커만 생성) 기존에 관측해 둔 실측 본문을 유지한다.
|
||||
// 실측 성패는 호출 시점 데이터 유무에 좌우된다 — 예컨대 DELETE /checkout 은 삭제할
|
||||
// 체크아웃이 없으면 404 다. 실측 실패는 "새로 관측하지 못했다"는 뜻이지 "기존 관측이
|
||||
// 무효"라는 뜻이 아니므로, 마커로 덮어 지난 응답 예시를 지우면 정보만 잃는다.
|
||||
$probeFailedNow = $this->isProbeSkipMarker($newBody);
|
||||
$previousWasProbed = str_contains($previousBody, self::PROBED_BODY_MARKER);
|
||||
|
||||
if ($probeFailedNow && $previousWasProbed) {
|
||||
$section = substr_replace($section, $previousBody, $start, $end - $start);
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
// 양쪽 다 실측 산출물이고 응답의 **키 구조**가 같으면 기존 예시를 유지한다.
|
||||
// 응답 예시 JSON 은 호출 시점 표본이라 `updated_at` · `cache_version` 처럼 매 실측마다
|
||||
// 달라지는 값이 섞여 들어온다. 스펙이 그대로인데 값만 바뀐 diff 를 재실행마다 만들지
|
||||
// 않도록, 필드 집합이 달라졌을 때(= 스펙 변경)만 새 실측값으로 갱신한다.
|
||||
if ($previousWasProbed
|
||||
&& str_contains($newBody, self::PROBED_BODY_MARKER)
|
||||
&& $this->exampleKeyShape($previousBody) === $this->exampleKeyShape($newBody)
|
||||
) {
|
||||
$section = substr_replace($section, $previousBody, $start, $end - $start);
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
// 기존 본문이 이번 run 과 같은 자동 생성 결과면 되살릴 것이 없다.
|
||||
if ($isAutoGenerated($previousBody)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// 새 본문이 사람 작성분이면(= 이 run 이 만든 것이 아니면) 손대지 않는다.
|
||||
// 실무상 새 섹션은 항상 자동 생성이지만, 방어적으로 확인한다.
|
||||
if (! $isAutoGenerated($newBody)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$section = substr($section, 0, $start).$previousBody.substr($section, $end);
|
||||
}
|
||||
|
||||
return $section;
|
||||
}
|
||||
|
||||
/**
|
||||
* 응답 본문이 실측 실패로 남은 사람 보강 요청 마커인지 확인합니다.
|
||||
*
|
||||
* @param string $body 응답 본문
|
||||
* @return bool 실측 제외/빈 결과 마커면 true
|
||||
*/
|
||||
private function isProbeSkipMarker(string $body): bool
|
||||
{
|
||||
return str_contains($body, '실측 제외') || str_contains($body, '실측 응답에 필드 없음');
|
||||
}
|
||||
|
||||
/**
|
||||
* 블록에서 `$label` 헤딩 ~ 다음 종료 헤딩 사이의 본문 [시작, 끝] 오프셋을 찾습니다.
|
||||
*
|
||||
* @param string $block 생성 블록 문자열
|
||||
* @param string $label 본문 시작 헤딩
|
||||
* @param array<int, string> $terminators 본문 끝 헤딩 후보
|
||||
* @return array{0: int, 1: int}|null [시작 오프셋, 끝 오프셋] (미발견 시 null)
|
||||
*/
|
||||
private function locateSubsectionBody(string $block, string $label, array $terminators): ?array
|
||||
{
|
||||
$labelPos = strpos($block, $label);
|
||||
$labelLength = strlen($label);
|
||||
|
||||
// 라벨 정확 일치 실패 시 베이스 라벨(굵은 제목)만으로 재시도한다.
|
||||
// 봉투를 쓰지 않는 엔드포인트(레이아웃 JSON 을 root 에 그대로 내리는 미리보기 서빙 등)에서는
|
||||
// `**응답 필드** (`data` 내부)` 라벨이 사실과 달라 사람이 접미를 떼어낸다. 정확 일치만 보면
|
||||
// 기존 본문 구간을 못 찾아, 표가 아닌 **서술**로 채운 내용이 마커로 퇴행한다
|
||||
// (표는 applyPreservedTableCells 가 행 키로 따로 지키지만, 서술은 이 경로가 유일하다).
|
||||
// 라벨 줄 전체를 라벨 길이로 삼아야 본문 시작 위치가 어긋나지 않는다.
|
||||
if ($labelPos === false) {
|
||||
$base = Str::before($label, ' (');
|
||||
|
||||
if ($base === $label) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$labelPos = strpos($block, $base);
|
||||
|
||||
if ($labelPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$lineEnd = strpos($block, "\n", $labelPos);
|
||||
$labelLength = ($lineEnd === false ? strlen($block) : $lineEnd) - $labelPos;
|
||||
}
|
||||
|
||||
$bodyStart = $labelPos + $labelLength;
|
||||
|
||||
$candidates = [];
|
||||
foreach ($terminators as $terminator) {
|
||||
$pos = strpos($block, $terminator, $bodyStart);
|
||||
if ($pos !== false) {
|
||||
$candidates[] = $pos;
|
||||
}
|
||||
}
|
||||
|
||||
if ($candidates === []) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$second = isset($cells[1]) ? trim($cells[1]) : '';
|
||||
if (in_array($second, ['query', 'body', 'path', 'header'], true)) {
|
||||
return $name.'@'.$second;
|
||||
return [$bodyStart, min($candidates)];
|
||||
}
|
||||
|
||||
/**
|
||||
* 블록에서 `$label` 헤딩 ~ 다음 종료 헤딩 사이의 본문 문자열을 추출합니다.
|
||||
*
|
||||
* @param string $block 생성 블록 문자열
|
||||
* @param string $label 본문 시작 헤딩
|
||||
* @param array<int, string> $terminators 본문 끝 헤딩 후보
|
||||
* @return string|null 본문 (미발견 시 null)
|
||||
*/
|
||||
private function extractSubsectionBody(string $block, string $label, array $terminators): ?string
|
||||
{
|
||||
$bounds = $this->locateSubsectionBody($block, $label, $terminators);
|
||||
|
||||
if ($bounds === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return $name;
|
||||
[$start, $end] = $bounds;
|
||||
|
||||
return substr($block, $start, $end - $start);
|
||||
}
|
||||
|
||||
/**
|
||||
* 생성 블록에서 표 행의 [키 => 기존 행 정보] 맵을 수집합니다.
|
||||
*
|
||||
* `value` 는 마지막 열(사람 서술, TODO 스텁이면 null), `cols` 는 행 전체 열이다.
|
||||
* 응답 필드 표의 실측 예시값 열을 보존하려면 행 전체가 필요하다.
|
||||
*
|
||||
* @param string $block 생성 블록 원문
|
||||
* @return array<string, array{value: string|null, cols: array<int, string>}> 키 => 기존 행 정보
|
||||
*/
|
||||
private function collectTableCells(string $block): array
|
||||
{
|
||||
$cells = [];
|
||||
|
||||
foreach (explode("\n", $block) as $line) {
|
||||
$parsed = $this->parseTableRow($line);
|
||||
|
||||
if ($parsed === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// 마지막 열(사람 서술)이 TODO 스텁이어도 예시값 열은 보존 대상이므로 행 자체는 수집한다.
|
||||
$cells[$parsed['key']] = [
|
||||
'value' => $this->isTodoCell($parsed['value']) ? null : $parsed['value'],
|
||||
'cols' => $parsed['cols'],
|
||||
];
|
||||
}
|
||||
|
||||
return $cells;
|
||||
}
|
||||
|
||||
/**
|
||||
* 표 데이터 행을 파싱합니다 (헤더·구분선 제외).
|
||||
*
|
||||
* @param string $line 한 줄
|
||||
* @return array{key: string, value: string, prefix: string, cols: array<int, string>}|null 파싱 결과 (표 행이 아니면 null)
|
||||
*/
|
||||
private function parseTableRow(string $line): ?array
|
||||
{
|
||||
if (! str_starts_with($line, '| ') || ! str_ends_with($line, ' |')) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 헤더/구분선 제외
|
||||
if (str_starts_with($line, '| --- ')
|
||||
|| str_starts_with($line, '| 이름 |')
|
||||
|| str_starts_with($line, '| 필드 |')
|
||||
|| str_starts_with($line, '| 상태코드 |')
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 셀 구분자가 아닌 파이프는 두 종류다 — 이스케이프된 파이프(`\|`)와 인라인 코드 스팬
|
||||
// 안의 파이프. 구분자로 오인하면 셀 수가 늘어 마지막 셀(=설명)이 파이프 뒤 조각으로
|
||||
// 바뀌고, 그 조각이 사람 서술로 승계돼 문장 앞부분이 잘린다. 두 경우 모두 가리는
|
||||
// splitRowCells 로 분해한다.
|
||||
$cols = array_map('trim', $this->splitRowCells($line));
|
||||
|
||||
// 파라미터 표 6열(이름+위치가 키) / 응답 필드 표 4열(필드가 키) / 에러 응답 표 3열(상태코드가 키)
|
||||
$key = match (count($cols)) {
|
||||
6 => $cols[0].'|'.$cols[1],
|
||||
4 => $cols[0],
|
||||
3 => $cols[0],
|
||||
default => null,
|
||||
};
|
||||
|
||||
if ($key === null || $cols[0] === '') {
|
||||
return null;
|
||||
}
|
||||
|
||||
$lastIndex = count($cols) - 1;
|
||||
$prefix = '| '.implode(' | ', array_slice($cols, 0, $lastIndex)).' |';
|
||||
|
||||
return ['key' => $key, 'value' => $cols[$lastIndex], 'prefix' => $prefix, 'cols' => $cols];
|
||||
}
|
||||
|
||||
/**
|
||||
* 셀이 사람이 채워야 할 TODO 스텁인지 확인합니다.
|
||||
*
|
||||
* @param string $value 셀 값
|
||||
* @return bool TODO 스텁 여부
|
||||
*/
|
||||
private function isTodoCell(string $value): bool
|
||||
{
|
||||
return $value === '' || str_contains($value, '<!-- TODO:');
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1485,13 +1973,11 @@ class ApiDocScaffolder
|
||||
|
||||
$afterGen = substr($existing, $endPos + strlen(self::GEN_END));
|
||||
|
||||
// 확장 목차 섹션(`## 확장 API 레퍼런스`)부터는 생성 블록 소관이므로 제외한다.
|
||||
// 임의의 `## ` 헤딩에서 자르면 사람이 덧붙인 헤딩 섹션이 재생성 때마다 통째로 소실된다.
|
||||
$nextSection = preg_match('/\n## '.preg_quote(self::EXTENSIONS_HEADING, '/').'/', $afterGen, $m, PREG_OFFSET_CAPTURE)
|
||||
? $m[0][1]
|
||||
: strlen($afterGen);
|
||||
|
||||
$prose = trim(substr($afterGen, 0, $nextSection));
|
||||
// 확장 목차 섹션(`## 확장 API 레퍼런스`)은 extensionIndexBlock() 이 헤딩까지 소유하므로 제외한다.
|
||||
// 그 외의 `## ` 헤딩(예: `## 개요`, `## 주의사항`)은 사람이 쓴 서술이므로 보존해야 한다.
|
||||
// (회귀: 임의의 `## ` 에서 잘라 목차 블록 뒤 사람 서술이 재생성 때마다 소실되던 문제)
|
||||
$cut = strpos($afterGen, "\n".self::EXTENSION_INDEX_HEADING);
|
||||
$prose = trim($cut !== false ? substr($afterGen, 0, $cut) : $afterGen);
|
||||
|
||||
return $prose === '' ? null : $prose;
|
||||
}
|
||||
@@ -1528,6 +2014,35 @@ class ApiDocScaffolder
|
||||
return trim(substr($existing, $from, ($endPos + strlen(self::GEN_END)) - $from));
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서에서 이 엔드포인트의 생성 블록만 종료 마커까지 정확히 잘라냅니다.
|
||||
*
|
||||
* {@see self::extractGeneratedBlock()} 은 앞의 `## ` 헤딩까지 거슬러 올라가 여러 엔드포인트를
|
||||
* 함께 반환할 수 있고, {@see self::extractGeneratedBlockBody()} 는 종료 마커를 잘라내고
|
||||
* 돌려준다. 에러 표 병합처럼 "이 엔드포인트 하나 + 종료 마커를 끝 경계로" 가 필요한
|
||||
* 소비자를 위해 시작~종료 마커 구간을 원문 그대로 돌려준다.
|
||||
*
|
||||
* @param string $existing 기존 문서
|
||||
* @param string $key 생성 블록 키
|
||||
* @return string|null 블록 원문 (없으면 null)
|
||||
*/
|
||||
private function exactGeneratedBlock(string $existing, string $key): ?string
|
||||
{
|
||||
$startPos = strpos($existing, self::GEN_START.$key.' -->');
|
||||
|
||||
if ($startPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$endPos = strpos($existing, self::GEN_END, $startPos);
|
||||
|
||||
if ($endPos === false) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return substr($existing, $startPos, ($endPos + strlen(self::GEN_END)) - $startPos);
|
||||
}
|
||||
|
||||
/**
|
||||
* 기존 문서에서 특정 엔드포인트의 사람 서술(생성 블록 밖)을 추출합니다.
|
||||
*
|
||||
@@ -1603,6 +2118,9 @@ class ApiDocScaffolder
|
||||
*/
|
||||
public function insertExampleBlocks(string $content, array $exampleBlocks): array
|
||||
{
|
||||
// 줄 끝 정규화 — mergeDocument 와 같은 이유 (CRLF 체크아웃에서 줄 단위 매칭이 전부 실패).
|
||||
$content = $this->normalizeEol($content);
|
||||
|
||||
$inserted = 0;
|
||||
|
||||
foreach ($exampleBlocks as $key => $blocks) {
|
||||
|
||||
@@ -29,13 +29,13 @@ class ApiRouteInventory
|
||||
/** @var Route $route */
|
||||
$uri = $route->uri();
|
||||
|
||||
if (! Str::startsWith($uri, 'api/')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$name = $route->getName() ?? '';
|
||||
$owner = $this->resolveOwner($name, $uri);
|
||||
|
||||
if (! $this->isDocumentable($uri, $name, $owner)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if ($scope !== null && ! $this->matchesScope($owner, $scope)) {
|
||||
continue;
|
||||
}
|
||||
@@ -57,6 +57,42 @@ class ApiRouteInventory
|
||||
return $routes;
|
||||
}
|
||||
|
||||
/**
|
||||
* 라우트가 API 레퍼런스 문서 대상인지 판별합니다.
|
||||
*
|
||||
* 두 부류를 수집한다:
|
||||
* 1. `api/` prefix 라우트 (코어 + 확장의 src/routes/api.php)
|
||||
* 2. 확장 소유가 확정된 web 라우트 중 관리자 화면(admin 컨텍스트)이 아닌 것
|
||||
*
|
||||
* (2)가 필요한 이유: PG 결제 콜백·웹훅은 외부 시스템(PG사 서버, 브라우저 리다이렉트)이
|
||||
* 호출하는 machine-facing 엔드포인트라 API 레퍼런스 대상이지만, CSRF 토큰 부재·세션 특성상
|
||||
* `api.php` 가 아니라 `web.php` 에 등록된다. `api/` 만 수집하면 이들이 영구히 무문서가 된다.
|
||||
*
|
||||
* 제외 대상:
|
||||
* - 코어 web 라우트 (블레이드 화면·SPA 진입점 등) — 소유가 'core'
|
||||
* - 확장의 관리자 화면 web 라우트 (`web.{dir}.{id}.admin.*`) — 사람이 브라우저로 여는
|
||||
* 화면이라 API 레퍼런스 대상이 아니다. 코어 admin API 는 `api/` prefix 라 영향 없다.
|
||||
*
|
||||
* @param string $uri 라우트 URI
|
||||
* @param string $name 라우트명
|
||||
* @param array{type: string, id: string|null, key: string} $owner 소유 주체
|
||||
* @return bool 문서 대상 여부
|
||||
*/
|
||||
private function isDocumentable(string $uri, string $name, array $owner): bool
|
||||
{
|
||||
if (Str::startsWith($uri, 'api/')) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// 코어 web 라우트(화면)는 대상 아님
|
||||
if ($owner['type'] === 'core') {
|
||||
return false;
|
||||
}
|
||||
|
||||
// 확장 web 라우트 중 관리자 화면(admin 컨텍스트)은 대상 아님
|
||||
return ! preg_match('/^web\.(?:modules|plugins)\.[^.]+\.admin\./', $name);
|
||||
}
|
||||
|
||||
/**
|
||||
* 하나의 라우트를 HTTP 메서드별 정규화 엔트리 배열로 변환합니다.
|
||||
*
|
||||
@@ -115,13 +151,18 @@ class ApiRouteInventory
|
||||
* 비활성/미설치 확장의 번들 라우트 파일을 임시 라우터에 로드해 수집합니다.
|
||||
*
|
||||
* 프로바이더(`ModuleRouteServiceProvider`/`PluginRouteServiceProvider`)와 동일한
|
||||
* prefix(`api/{modules|plugins}/{id}`)·name(`api.{modules|plugins}.{id}.`)·`api`
|
||||
* 미들웨어 그룹으로 `src/routes/api.php` 를 라우터에 로드한다. `api/` 로 시작하는
|
||||
* 라우트만 대상이므로 web(admin) 라우트는 자동 제외된다(그 라우트는 API 문서 대상이 아니다).
|
||||
* prefix·name·미들웨어 규약으로 번들 라우트 파일을 라우터에 로드한다:
|
||||
* - `src/routes/api.php` → prefix `api/{dir}/{id}`, name `api.{dir}.{id}.`, middleware `api`
|
||||
* - `src/routes/web.php` → prefix `{dir}/{id}`, name `web.{dir}.{id}.`, middleware `web`
|
||||
*
|
||||
* web 라우트를 함께 로드하는 이유: PG 결제 콜백·웹훅은 CSRF/세션 특성상 web.php 에
|
||||
* 등록되지만 외부 시스템이 호출하는 machine-facing 엔드포인트라 API 문서 대상이다.
|
||||
* 관리자 화면용 web 라우트는 문서에 섞이지만, 확장 소유 라우트는 모두 문서 대상이라는
|
||||
* 활성 경로(`isDocumentable`)의 판정과 일관된다.
|
||||
*
|
||||
* 라우트 파일은 `use Illuminate\Support\Facades\Route` 로 전역 파사드에 등록하므로,
|
||||
* 등록 전 라우트 이름 스냅샷을 떠서 이번 로드로 추가된 라우트만 골라낸다. 이 커맨드는
|
||||
* CLI 단발 프로세스라 전역 라우트 테이블 추가가 웹 요청에 영향을 주지 않는다.
|
||||
* 등록 후 uri/name prefix 로 이 확장 소유 라우트만 골라낸다. 이 커맨드는 CLI 단발
|
||||
* 프로세스라 전역 라우트 테이블 추가가 웹 요청에 영향을 주지 않는다.
|
||||
*
|
||||
* @param string $scope 범위 필터 (`module:{id}` / `plugin:{id}`)
|
||||
* @return array<int, array<string, mixed>> 정규화된 라우트 메타데이터 목록
|
||||
@@ -134,43 +175,55 @@ class ApiRouteInventory
|
||||
|
||||
[$type, $id] = [$m[1], $m[2]];
|
||||
$dir = $type === 'module' ? 'modules' : 'plugins';
|
||||
$apiRouteFile = base_path("{$dir}/_bundled/{$id}/src/routes/api.php");
|
||||
|
||||
if (! is_file($apiRouteFile)) {
|
||||
$groups = [
|
||||
['file' => base_path("{$dir}/_bundled/{$id}/src/routes/api.php"), 'prefix' => "api/{$dir}/{$id}", 'name' => "api.{$dir}.{$id}.", 'middleware' => 'api'],
|
||||
['file' => base_path("{$dir}/_bundled/{$id}/src/routes/web.php"), 'prefix' => "{$dir}/{$id}", 'name' => "web.{$dir}.{$id}.", 'middleware' => 'web'],
|
||||
];
|
||||
|
||||
$loaded = false;
|
||||
|
||||
foreach ($groups as $group) {
|
||||
if (! is_file($group['file'])) {
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
RouteFacade::prefix($group['prefix'])
|
||||
->name($group['name'])
|
||||
->middleware($group['middleware'])
|
||||
->group($group['file']);
|
||||
$loaded = true;
|
||||
} catch (\Throwable) {
|
||||
// 개별 라우트 파일 로드 실패는 그 파일만 건너뛴다 (나머지는 계속 수집).
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
if (! $loaded) {
|
||||
return [];
|
||||
}
|
||||
|
||||
$urlPrefix = "api/{$dir}/{$id}";
|
||||
$namePrefix = "api.{$dir}.{$id}.";
|
||||
|
||||
try {
|
||||
RouteFacade::prefix($urlPrefix)
|
||||
->name($namePrefix)
|
||||
->middleware('api')
|
||||
->group($apiRouteFile);
|
||||
RouteFacade::getRoutes()->refreshNameLookups();
|
||||
} catch (\Throwable) {
|
||||
return [];
|
||||
}
|
||||
RouteFacade::getRoutes()->refreshNameLookups();
|
||||
|
||||
// 이 확장 소유로 확정된 라우트를 전역 라우트 테이블에서 prefix(uri/name) 로 직접 골라낸다.
|
||||
// object-id 스냅샷 방식은 refreshNameLookups() 가 RouteCollection 을 재색인하며 객체를
|
||||
// 다시 만들어 dedup 이 어긋나므로(활성 확장 로드 순서·중복 로드에 취약) 쓰지 않는다.
|
||||
// 대상 확장은 uri 가 `api/{dir}/{id}/`, name 이 `api.{dir}.{id}.` 로 시작해 결정적으로 식별된다.
|
||||
// 대상 확장은 uri/name 이 `{api/}{dir}/{id}/` · `{api|web}.{dir}.{id}.` 로 시작해
|
||||
// 결정적으로 식별된다.
|
||||
$seen = [];
|
||||
$routes = [];
|
||||
|
||||
foreach (RouteFacade::getRoutes() as $route) {
|
||||
/** @var Route $route */
|
||||
$uri = $route->uri();
|
||||
|
||||
if (! Str::startsWith($uri, 'api/')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$name = $route->getName() ?? '';
|
||||
$owner = $this->resolveOwner($name, $uri);
|
||||
|
||||
if (! $this->isDocumentable($uri, $name, $owner)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// 폴백 대상 확장 소유로 확정되지 않으면(코어·타 확장) 제외
|
||||
if ($owner['key'] !== $scope) {
|
||||
continue;
|
||||
@@ -199,20 +252,22 @@ class ApiRouteInventory
|
||||
*/
|
||||
private function resolveOwner(string $name, string $uri): array
|
||||
{
|
||||
if (preg_match('/^api\.modules\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
|
||||
// 라우트명 규약: api 라우트는 `api.{modules|plugins}.{id}.*`,
|
||||
// web 라우트(PG 콜백/웹훅)는 `web.{modules|plugins}.{id}.*`
|
||||
if (preg_match('/^(?:api|web)\.modules\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
|
||||
return ['type' => 'module', 'id' => $m[1], 'key' => 'module:'.$m[1]];
|
||||
}
|
||||
|
||||
if (preg_match('/^api\.plugins\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
|
||||
if (preg_match('/^(?:api|web)\.plugins\.([^.]+)\./', $name, $m) && $this->isRealExtensionId($m[1])) {
|
||||
return ['type' => 'plugin', 'id' => $m[1], 'key' => 'plugin:'.$m[1]];
|
||||
}
|
||||
|
||||
// 라우트명이 비어도 URI prefix 로 보조 판별
|
||||
if (preg_match('#^api/modules/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
|
||||
// 라우트명이 비어도 URI prefix 로 보조 판별 (api: `api/{dir}/{id}/`, web: `{dir}/{id}/`)
|
||||
if (preg_match('#^(?:api/)?modules/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
|
||||
return ['type' => 'module', 'id' => $m[1], 'key' => 'module:'.$m[1]];
|
||||
}
|
||||
|
||||
if (preg_match('#^api/plugins/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
|
||||
if (preg_match('#^(?:api/)?plugins/([^/{]+)/#', $uri, $m) && $this->isRealExtensionId($m[1])) {
|
||||
return ['type' => 'plugin', 'id' => $m[1], 'key' => 'plugin:'.$m[1]];
|
||||
}
|
||||
|
||||
@@ -391,7 +446,8 @@ class ApiRouteInventory
|
||||
// 'modules'/'plugins' 는 확장 소유 prefix(api.modules.{id}.*)로도, 코어 확장관리
|
||||
// 리소스(api.admin.modules.*)로도 쓰인다. 소유 prefix 는 owner['id'] 스킵으로 이미
|
||||
// 걷히므로, leading 에는 순수 컨텍스트(api/admin/user/me/public)만 둔다.
|
||||
$leading = ['api', 'admin', 'user', 'me', 'public'];
|
||||
// 'web' 은 확장 PG 콜백/웹훅 라우트명(web.plugins.{id}.*)의 leading 컨텍스트다.
|
||||
$leading = ['api', 'web', 'admin', 'user', 'me', 'public'];
|
||||
$segments = array_values(array_filter(explode('.', $name), fn ($s) => $s !== ''));
|
||||
|
||||
$i = 0;
|
||||
|
||||
@@ -111,8 +111,10 @@ class FormRequestIntrospector
|
||||
$params = [];
|
||||
|
||||
foreach ($rules as $field => $rule) {
|
||||
// 중첩 필드(items.*.id)는 상위만 대표로 노출
|
||||
if (str_contains((string) $field, '.')) {
|
||||
// 배열 요소 규칙(items.*.id)은 상위 필드(items)만 대표로 노출한다.
|
||||
// 점(`.`) 포함 여부만 보면 와일드카드가 없는 중첩 **객체** 필드
|
||||
// (refund_bank.bank_code, general.site_name 등)까지 버려져 문서에서 통째로 빠진다.
|
||||
if (str_contains((string) $field, '*')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
|
||||
@@ -193,6 +193,91 @@ class ParameterDescriber
|
||||
'websocket_port' => 'WebSocket 포트 번호',
|
||||
'websocket_scheme' => 'WebSocket 스킴 (http/https)',
|
||||
'websocket_app_key' => 'WebSocket 앱 키',
|
||||
'websocket_app_secret' => 'WebSocket 앱 시크릿',
|
||||
'websocket_server_host' => 'WebSocket 서버 호스트 주소 (서버측 발행 대상)',
|
||||
'websocket_server_port' => 'WebSocket 서버 포트 번호 (서버측 발행 대상)',
|
||||
'websocket_server_scheme' => 'WebSocket 서버 스킴 (http/https — 서버측 발행 대상)',
|
||||
'websocket_verify_ssl' => 'WebSocket 서버 SSL 인증서 검증 여부',
|
||||
'log_driver' => '로그 드라이버 (single/daily/stack)',
|
||||
'log_level' => '로그 레벨 (debug/info/warning/error 등)',
|
||||
'log_days' => '로그 파일 보관 일수',
|
||||
'search_engine_driver' => '검색 엔진 드라이버 (Scout 엔진 선택)',
|
||||
'session_lifetime' => '세션 유효 시간 (분)',
|
||||
|
||||
// 레이아웃 JSON 스키마 최상위 키 (근거: docs/frontend/layout-json.md 필수/선택 필드 표,
|
||||
// UpdateLayoutContentRequest 검증 규칙. 템플릿/레이아웃 저장 API 의 content.* 키.)
|
||||
'layout_name' => '레이아웃 이름 (식별자 — 파일 경로 기반, 예: board/popular)',
|
||||
'components' => '컴포넌트 트리 배열 (레이아웃이 렌더할 컴포넌트 정의)',
|
||||
'data_sources' => 'API 데이터 소스 정의 배열 (id/endpoint/method)',
|
||||
'init_actions' => '레이아웃 로드 시 실행할 초기화 액션 배열',
|
||||
'named_actions' => '이름으로 호출 가능한 재사용 액션 정의 맵',
|
||||
'defines' => '재사용 컴포넌트 정의 맵 (컴포넌트 트리에서 참조)',
|
||||
'computed' => '계산된 값 정의 맵 (키 → 표현식)',
|
||||
'modals' => '모달 컴포넌트 정의 배열',
|
||||
'scripts' => '동적 로드할 외부 스크립트 배열',
|
||||
'errorHandling' => '레이아웃 레벨 에러 핸들링 설정 (에러 코드별 핸들러 매핑)',
|
||||
'globalHeaders' => '전역 HTTP 헤더 규칙 배열 (pattern + headers)',
|
||||
'init_state' => '초기 상태 값 맵',
|
||||
'initLocal' => 'API 응답을 `_local` 상태에 자동 복사할 키/경로',
|
||||
'initGlobal' => 'API 응답을 `_global` 상태에 자동 복사할 키/경로',
|
||||
'initIsolated' => 'API 응답을 `_isolated` 상태에 자동 복사할 키/경로',
|
||||
'global_state' => '전역 상태 초기값 맵',
|
||||
'slots' => '슬롯별 삽입 콘텐츠 맵 (베이스 레이아웃의 slot 위치에 주입)',
|
||||
'extends' => '상속할 베이스 레이아웃 이름',
|
||||
'transition_overlay' => '페이지 전환 오버레이 설정 (스켈레톤/스피너)',
|
||||
'pageConfig' => '페이지 단위 설정 객체',
|
||||
'error_config' => '에러 표시 설정 객체',
|
||||
|
||||
// SEO 페이지 생성기 (근거: docs/frontend/layout-json.md meta.seo 표,
|
||||
// docs/backend/seo-system.md, Settings SEO 카탈로그)
|
||||
'changefreq' => 'sitemap changefreq 값 (daily/weekly/monthly 등)',
|
||||
'structured_data' => 'JSON-LD 구조화 데이터 정의',
|
||||
'og' => 'Open Graph 메타태그 정의 맵',
|
||||
'page_type' => 'SEO 템플릿 키를 결정하는 페이지 유형',
|
||||
'toggle_setting' => 'SEO 활성화 여부를 결정하는 설정 경로',
|
||||
'vars' => 'SEO 변수 선언 맵 (데이터 소스 값의 표현식 매핑)',
|
||||
'meta_keywords' => 'SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분)',
|
||||
'meta_title_suffix' => '모든 페이지 SEO 제목 뒤에 붙는 접미 문구',
|
||||
'google_site_verification' => 'Google Search Console 사이트 소유 확인 코드',
|
||||
'naver_site_verification' => '네이버 서치어드바이저 사이트 소유 확인 코드',
|
||||
'twitter_default_card' => '기본 트위터 카드 유형 (summary 등)',
|
||||
'twitter_default_site' => '기본 트위터 사이트 계정 (@handle)',
|
||||
'og_image_default_width' => '기본 Open Graph 이미지 너비 (px)',
|
||||
'og_image_default_height' => '기본 Open Graph 이미지 높이 (px)',
|
||||
'sitemap_enabled' => 'sitemap.xml 생성 사용 여부',
|
||||
'sitemap_schedule' => 'sitemap 자동 생성 주기',
|
||||
'sitemap_schedule_time' => 'sitemap 자동 생성 시각',
|
||||
'sitemap_cache_ttl' => 'sitemap 캐시 유효 시간 (초)',
|
||||
'bot_detection_enabled' => '검색엔진 봇 감지 사용 여부 (봇 요청에 SEO 렌더링 적용)',
|
||||
'bot_detection_library_enabled' => '봇 감지 라이브러리 사용 여부 (User-Agent 목록 대신 라이브러리 판정)',
|
||||
'bot_user_agents' => '봇으로 판정할 User-Agent 목록',
|
||||
'generator_enabled' => 'SEO 페이지 생성기 사용 여부',
|
||||
'generator_content' => 'SEO 렌더링 본문 생성 방식',
|
||||
|
||||
// 캐시/보안/업로드 공통 (근거: Settings 카탈로그 advanced/security/upload 그룹)
|
||||
'cache_enabled' => '캐시 사용 여부',
|
||||
'cache_ttl' => '캐시 유효 시간 (초)',
|
||||
'debug_mode' => '디버그 모드 사용 여부 (상세 오류 노출)',
|
||||
'sql_query_log' => 'SQL 쿼리 로그 기록 여부',
|
||||
'maintenance_mode' => '점검 모드 사용 여부 (사이트 접근 차단)',
|
||||
'force_https' => 'HTTPS 강제 리다이렉트 여부',
|
||||
'max_login_attempts' => '로그인 실패 허용 횟수 (초과 시 잠금)',
|
||||
'login_lockout_time' => '로그인 잠금 지속 시간 (분)',
|
||||
'login_attempt_enabled' => '로그인 시도 제한 사용 여부',
|
||||
'auth_token_lifetime' => '인증 토큰 유효 시간 (분)',
|
||||
'max_file_size' => '업로드 허용 최대 파일 크기',
|
||||
'max_file_count' => '업로드 허용 최대 파일 개수',
|
||||
'allowed_extensions' => '업로드 허용 확장자 목록',
|
||||
'image_quality' => '이미지 리사이즈 시 압축 품질 (1~100)',
|
||||
'image_max_width' => '이미지 리사이즈 최대 너비 (px)',
|
||||
'image_max_height' => '이미지 리사이즈 최대 높이 (px)',
|
||||
|
||||
// 사이트 기본 정보 (근거: Settings general 그룹)
|
||||
'site_url' => '사이트 기본 URL',
|
||||
'site_description' => '사이트 설명',
|
||||
'site_logo' => '사이트 로고 이미지',
|
||||
'admin_email' => '관리자 이메일 주소',
|
||||
'currency' => '통화 코드 (ISO 4217 — 예: KRW)',
|
||||
];
|
||||
|
||||
/**
|
||||
@@ -205,6 +290,101 @@ class ParameterDescriber
|
||||
*/
|
||||
public function describe(string $name, string $location = '', string $type = ''): ?string
|
||||
{
|
||||
// 중첩 필드(general.site_name, shipping.zipcode 등)는 전체명으로는 어떤 규칙에도
|
||||
// 걸리지 않는다. 전체명 매칭을 먼저 시도하고, 실패하면 마지막 세그먼트(leaf)로
|
||||
// 재시도한다 — 중첩 경로의 의미는 leaf 가 결정하고 부모는 그룹 라벨일 뿐이다.
|
||||
// 다국어 로케일 접미(name.ko / alt_text.en)는 부모 필드의 로케일별 값이다.
|
||||
if (str_contains($name, '.')) {
|
||||
return $this->describeNested($name, $location, $type);
|
||||
}
|
||||
|
||||
return $this->describeFlat($name, $location, $type);
|
||||
}
|
||||
|
||||
/**
|
||||
* 중첩 필드(`.` 포함)의 설명을 leaf 세그먼트로 유추합니다.
|
||||
*
|
||||
* @param string $name 중첩 파라미터명 (예: general.site_name)
|
||||
* @param string $location 위치
|
||||
* @param string $type 타입
|
||||
* @return string|null 설명 (미매칭 시 null)
|
||||
*/
|
||||
private function describeNested(string $name, string $location, string $type): ?string
|
||||
{
|
||||
$leaf = Str::afterLast($name, '.');
|
||||
$parent = Str::beforeLast($name, '.');
|
||||
|
||||
// 배열 원소 인덱스(items.*.name / ids.0) — leaf 가 인덱스면 그 앞을 leaf 로 본다.
|
||||
if ($leaf === '*' || ctype_digit($leaf)) {
|
||||
return $this->describe($parent, $location, $type);
|
||||
}
|
||||
|
||||
// 로케일 접미(name.ko / alt_text.en): 부모 필드의 로케일별 값.
|
||||
if (in_array($leaf, config('app.supported_locales', ['ko', 'en']), true)) {
|
||||
$parentDesc = $this->describe($parent, $location, $type);
|
||||
|
||||
return $parentDesc === null
|
||||
? null
|
||||
: "{$parentDesc} — `{$leaf}` 로케일 값";
|
||||
}
|
||||
|
||||
// 부모가 의미를 한정하는 그룹인 경우: leaf 만으로는 오설명이 된다.
|
||||
// 예) seo_meta.title 은 "제목" 이 아니라 "SEO 메타 제목" 이다.
|
||||
$scoped = $this->describeScopedLeaf($parent, $leaf);
|
||||
if ($scoped !== null) {
|
||||
return $scoped;
|
||||
}
|
||||
|
||||
// leaf 로 재시도 (부모 그룹 라벨은 의미를 바꾸지 않는다).
|
||||
return $this->describeFlat($leaf, $location, $type);
|
||||
}
|
||||
|
||||
/**
|
||||
* 부모 그룹이 의미를 한정하는 중첩 키의 설명을 반환합니다.
|
||||
*
|
||||
* 대부분의 설정 그룹(general/mail/upload 등)은 라벨일 뿐이라 leaf 가 의미를 결정하지만,
|
||||
* SEO 메타 그룹의 `title`/`description`/`keywords` 는 일반 제목/설명이 아니라 검색엔진
|
||||
* 노출용 메타 값이다. leaf 폴백만 태우면 "제목"/"설명" 으로 축소되어 오설명이 된다.
|
||||
*
|
||||
* @param string $parent 부모 경로 (예: seo_meta, content.meta.seo)
|
||||
* @param string $leaf 마지막 세그먼트
|
||||
* @return string|null 설명 (해당 없으면 null → 일반 leaf 폴백)
|
||||
*/
|
||||
private function describeScopedLeaf(string $parent, string $leaf): ?string
|
||||
{
|
||||
$parentLeaf = Str::afterLast($parent, '.');
|
||||
|
||||
// SEO 메타 그룹 (근거: Page\*Request 의 seo_meta.{title,description,keywords},
|
||||
// 레이아웃 meta.seo — 검색엔진/소셜 공유 노출 값)
|
||||
if (in_array($parentLeaf, ['seo', 'seo_meta'], true)) {
|
||||
return match ($leaf) {
|
||||
'title' => 'SEO 메타 제목 (검색엔진/소셜 공유 표시 제목)',
|
||||
'description' => 'SEO 메타 설명 (검색엔진/소셜 공유 표시 요약)',
|
||||
'keywords' => 'SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분)',
|
||||
default => null,
|
||||
};
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 단일 세그먼트 파라미터의 설명을 반환합니다.
|
||||
*
|
||||
* @param string $name 파라미터명 (`.` 없음)
|
||||
* @param string $location 위치 (path/query/body)
|
||||
* @param string $type 타입
|
||||
* @return string|null 설명 (미매칭 시 null)
|
||||
*/
|
||||
private function describeFlat(string $name, string $location, string $type): ?string
|
||||
{
|
||||
// path 파라미터는 언제나 리소스 식별자다(라우트 모델 바인딩). 이름이 무엇이든
|
||||
// 정렬·필터 같은 조회 파라미터 의미를 가질 수 없으므로 이름 기반 규칙보다 앞서 처리한다.
|
||||
// (회귀: `{order}` path 가 "정렬 방향 asc/desc" 로 설명되던 문제)
|
||||
if ($location === 'path') {
|
||||
return self::EXACT[$name] ?? $this->describePathParam($name);
|
||||
}
|
||||
|
||||
// sort_order / order 는 타입에 따라 의미가 갈린다:
|
||||
// - 문자열: 정렬 방향(asc/desc)
|
||||
// - 정수: 표시 정렬 순서 값(작을수록 우선 — 컬럼 값)
|
||||
@@ -232,11 +412,7 @@ class ParameterDescriber
|
||||
return self::EXACT[$name];
|
||||
}
|
||||
|
||||
// path 파라미터는 대부분 리소스 식별자 — 위치를 근거로 유추.
|
||||
if ($location === 'path') {
|
||||
return $this->describePathParam($name);
|
||||
}
|
||||
|
||||
// path 파라미터는 위 진입부에서 이미 처리했다.
|
||||
return $this->byPattern($name, $type);
|
||||
}
|
||||
|
||||
|
||||
@@ -105,6 +105,8 @@ class ResourceFieldDescriber
|
||||
'install_blocked_reason' => '설치가 차단된 사유 (차단 없으면 null)',
|
||||
|
||||
// 감사/관계 공통 (도메인 무관하게 역할 고정 — 쓰기 응답에서 흔히 등장)
|
||||
// creator/permissions 는 위 "관계/연관 객체" 블록에 이미 있으므로 여기서 재정의하지 않는다
|
||||
// (PHP 배열은 뒤 키가 앞을 덮어 같은 값이 두 번 선언되는 상태였다).
|
||||
'updated_by' => '최종 수정한 사용자 정보 (uuid/name — updated_by 관계 파생, 없으면 null)',
|
||||
'user' => '대상 사용자 정보 객체 (uuid/name/email 등 — user 관계 파생)',
|
||||
'roles' => '보유 역할 목록 (각 원소 id/name/permissions — roles 관계 파생)',
|
||||
@@ -133,6 +135,47 @@ class ResourceFieldDescriber
|
||||
'spec' => '스펙 정의 객체 (편집기/컴포넌트 선언 스키마 등)',
|
||||
'source_meta' => '원천 메타데이터 객체 (출처·경로·해석 정보)',
|
||||
'validation_summary' => '검증 결과 요약 객체 (통과/실패 건수 등)',
|
||||
|
||||
// 레이아웃 JSON 스키마 키 (근거: docs/frontend/layout-json.md 필수/선택 필드 표.
|
||||
// 레이아웃 서빙/저장 응답의 content 하위 키 — 엔진 스키마 계약으로 의미 고정)
|
||||
'$schema' => 'JSON 스키마 선언 URL (편집기/검증 도구용)',
|
||||
'layout_name' => '레이아웃 이름 (식별자 — 파일 경로 기반, 예: board/popular)',
|
||||
'components' => '컴포넌트 트리 (레이아웃이 렌더할 컴포넌트 정의)',
|
||||
'data_sources' => 'API 데이터 소스 정의 배열 (id/endpoint/method)',
|
||||
'modals' => '모달 컴포넌트 정의 배열',
|
||||
'slots' => '슬롯별 삽입 콘텐츠 맵 (베이스 레이아웃의 slot 위치에 주입)',
|
||||
'extends' => '상속하는 베이스 레이아웃 이름 (미상속 시 null)',
|
||||
'schema' => '스키마 정의 객체',
|
||||
'meta' => '메타 정보 객체 (title/description/seo 등)',
|
||||
'pageConfig' => '페이지 단위 설정 객체',
|
||||
'error_config' => '에러 표시 설정 객체',
|
||||
'base_layouts' => '상속 가능한 베이스 레이아웃 목록',
|
||||
'layout_versions' => '레이아웃 버전 이력 목록',
|
||||
'preview' => '미리보기 정보 객체',
|
||||
'vars' => 'SEO 변수 선언 맵 (데이터 소스 값의 표현식 매핑)',
|
||||
'events' => '이벤트 정의 목록',
|
||||
'toggle_settings' => '토글 가능한 설정 항목 목록',
|
||||
'page_types' => 'SEO 템플릿 키로 사용 가능한 페이지 유형 목록',
|
||||
'display_mode' => '표시 방식 (렌더/노출 모드 구분 값)',
|
||||
'templateId' => '대상 템플릿의 식별자',
|
||||
|
||||
// 확장 manifest / 에셋 계약 (근거: module.json/plugin.json/template.json manifest,
|
||||
// ExtensionBundleService 에셋 매니페스트)
|
||||
'g7_version' => '요구하는 코어 최소 버전 (manifest requires.g7_version)',
|
||||
'required_version' => '요구되는 최소 버전',
|
||||
'manifest_source' => 'manifest 를 읽어온 출처 경로 (활성/_bundled 구분)',
|
||||
'manifest_present' => 'manifest 파일 존재 여부',
|
||||
'license' => '라이선스 식별자 (manifest license)',
|
||||
'release_date' => '배포일',
|
||||
'cache_version' => '에셋 캐시 무효화 버전 (번들 URL 파일명에 포함)',
|
||||
'js' => '프론트엔드 JS 에셋 목록 (manifest assets 파생)',
|
||||
'css' => '프론트엔드 CSS 에셋 목록 (manifest assets 파생)',
|
||||
'externals' => '외부 의존 라이브러리 목록 (번들에서 제외되고 전역에서 해석)',
|
||||
'routes' => '라우트 정의 목록',
|
||||
'components_count' => '컴포넌트 개수 (집계)',
|
||||
'theme_color' => '테마 대표 색상',
|
||||
'popup_width' => '팝업 창 너비 (px)',
|
||||
'popup_height' => '팝업 창 높이 (px)',
|
||||
];
|
||||
|
||||
/**
|
||||
@@ -143,6 +186,70 @@ class ResourceFieldDescriber
|
||||
* @return string|null 설명 (없으면 null)
|
||||
*/
|
||||
public function describe(string $field, string $type = ''): ?string
|
||||
{
|
||||
// 중첩 필드(settings.general.site_name, meta.total 등)는 전체명으로 어떤 규칙에도
|
||||
// 걸리지 않는다. 마지막 세그먼트(leaf)로 폴백한다 — 중첩 경로의 의미는 leaf 가
|
||||
// 결정하고 상위 세그먼트는 그룹 라벨일 뿐이다. (ParameterDescriber 와 동일 계약)
|
||||
if (str_contains($field, '.')) {
|
||||
return $this->describeNested($field, $type);
|
||||
}
|
||||
|
||||
return $this->describeFlat($field, $type);
|
||||
}
|
||||
|
||||
/**
|
||||
* 중첩 필드(`.` 포함)의 설명을 leaf 세그먼트로 유추합니다.
|
||||
*
|
||||
* @param string $field 중첩 필드명 (예: settings.general.site_name)
|
||||
* @param string $type 실측 타입
|
||||
* @return string|null 설명 (미매칭 시 null)
|
||||
*/
|
||||
private function describeNested(string $field, string $type): ?string
|
||||
{
|
||||
$leaf = Str::afterLast($field, '.');
|
||||
$parent = Str::beforeLast($field, '.');
|
||||
|
||||
// 배열 원소 인덱스(items.*.name / items.0.name) — 그 앞을 leaf 로 본다.
|
||||
if ($leaf === '*' || ctype_digit($leaf)) {
|
||||
return $this->describe($parent, $type);
|
||||
}
|
||||
|
||||
// 로케일 접미(name.ko): 부모 필드의 로케일별 값.
|
||||
if (in_array($leaf, config('app.supported_locales', ['ko', 'en']), true)) {
|
||||
$parentDesc = $this->describe($parent, $type);
|
||||
|
||||
return $parentDesc === null
|
||||
? null
|
||||
: "{$parentDesc} — `{$leaf}` 로케일 값";
|
||||
}
|
||||
|
||||
// 부모가 의미를 한정하는 그룹(seo/seo_meta)의 title/description/keywords 는
|
||||
// 일반 제목/설명이 아니라 검색엔진 노출용 메타 값이다 (ParameterDescriber 와 동일 계약).
|
||||
$parentLeaf = Str::afterLast($parent, '.');
|
||||
if (in_array($parentLeaf, ['seo', 'seo_meta'], true)) {
|
||||
$scoped = match ($leaf) {
|
||||
'title' => 'SEO 메타 제목 (검색엔진/소셜 공유 표시 제목)',
|
||||
'description' => 'SEO 메타 설명 (검색엔진/소셜 공유 표시 요약)',
|
||||
'keywords' => 'SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분)',
|
||||
default => null,
|
||||
};
|
||||
|
||||
if ($scoped !== null) {
|
||||
return $scoped;
|
||||
}
|
||||
}
|
||||
|
||||
return $this->describeFlat($leaf, $type);
|
||||
}
|
||||
|
||||
/**
|
||||
* 단일 세그먼트 필드의 설명을 반환합니다.
|
||||
*
|
||||
* @param string $field 필드명 (`.` 없음)
|
||||
* @param string $type 실측 타입
|
||||
* @return string|null 설명 (미매칭 시 null)
|
||||
*/
|
||||
private function describeFlat(string $field, string $type): ?string
|
||||
{
|
||||
// sort_order 는 응답에서 표시 정렬 순서 값(정수 컬럼)으로 고정된다.
|
||||
// 문자열이면 정렬 방향일 수 있어 도메인 특이 → TODO 유지.
|
||||
|
||||
@@ -11,7 +11,8 @@
|
||||
2. 위치: 코어 = docs/backend/api/, 확장 = {modules|plugins}/_bundled/{id}/docs/api/
|
||||
3. 생성: php artisan api:docgen — 코드에서 추출한 스캐폴딩 + 사람이 서술 보강 (순수 수기 금지)
|
||||
4. 추출 불가분(훅 주입 파라미터·동적 응답)은 <!-- TODO --> 마커 남기고 사람이 채움
|
||||
5. Swagger/OpenAPI 도구 미사용 — 마크다운 레퍼런스 전용
|
||||
5. src/routes/api.php 가 없는 web 전용 확장(브라우저 콜백)은 문서 대상 아님
|
||||
6. Swagger/OpenAPI 도구 미사용 — 마크다운 레퍼런스 전용
|
||||
```
|
||||
|
||||
---
|
||||
@@ -51,6 +52,25 @@ G7 의 REST API 는 라우트 `->name()` 규약은 있으나 엔드포인트별
|
||||
|
||||
도메인 그룹핑은 URI/라우트명 prefix 기준(`api.admin.users.*` → `users.md`)으로 커맨드가 자동 분류한다.
|
||||
|
||||
### 문서 대상이 아닌 확장 (web 전용 라우트)
|
||||
|
||||
확장의 `api/` prefix 라우트는 `src/routes/api.php` 를 통해서만 등록된다
|
||||
(`{Plugin,Module}RouteServiceProvider` 가 `api.php` → `api/{type}/{id}`, `web.php` → `{type}/{id}` 로 로드).
|
||||
|
||||
따라서 `web.php` 만 가진 확장은 API 레퍼런스 문서 대상이 아니다. 브라우저 리다이렉트/콜백
|
||||
(PG 승인 결과 수신 등)은 JSON API 계약이 아니라 사용자 브라우저를 향한 302 응답이며,
|
||||
`api:docgen --scope={type}:{id}` 는 이 경우 `범위 '...' 에 해당하는 API 라우트가 없습니다` 로 응답한다.
|
||||
|
||||
| 확장 | 라우트 | `docs/api/` |
|
||||
| --- | --- | --- |
|
||||
| `sirsoft-pay_kginicis` | `api.php` + `web.php` | 있음 — `api/` 엔드포인트 22건만 문서화 (web 콜백 9건 제외) |
|
||||
| `sirsoft-tosspayments` | `web.php` | 없음 — PG 콜백 2건 전부 브라우저 리다이렉트 |
|
||||
| `gnuboard7-hello_plugin` | `web.php` | 없음 |
|
||||
|
||||
정적 검사는 `src/routes/api.php` 존재 여부로 이를 판정해, 해당 확장의
|
||||
라우트/컨트롤러/FormRequest 변경에는 문서 동반을 요구하지 않는다. 확장에 `api.php` 를 추가하면
|
||||
그 시점부터 자동으로 검사 대상이 되므로, 문서 생성을 함께 수행한다.
|
||||
|
||||
### 문서 목차와 발견성 (README.md 규약)
|
||||
|
||||
각 대상(코어·확장)의 API 문서 디렉토리에는 `README.md` 목차가 있어야 한다. `api:docgen` 이 도메인 파일
|
||||
@@ -97,6 +117,35 @@ README.md "API 레퍼런스" 또는 AGENTS.md "API 레퍼런스 진입점" 표
|
||||
따른다. `<!-- @generated:start -->` ~ `<!-- @generated:end -->` 사이는 `api:docgen` 이 재생성하는 추출
|
||||
블록이며, 그 바깥의 사람 서술(`**설명**`)은 재생성 시 보존된다.
|
||||
|
||||
블록 **안**의 사람 작성분도 보존된다. 자동 생성은 비어 있는 자리를 채울 뿐 사람이 쓴 것을 덮어쓰지 않는다:
|
||||
|
||||
| 대상 | 보존 판정 |
|
||||
| --- | --- |
|
||||
| 파라미터 표 `용도` 셀 | 행 키(이름+위치)로 대조. 기존 값이 TODO 스텁이 아니면 유지 |
|
||||
| 응답 필드 표 `용도/설명` 셀 | 행 키(필드)로 대조. 기존 값이 TODO 스텁이 아니면 유지 |
|
||||
| 응답 필드 표 `실측 예시값` 열 | 같은 필드의 타입이 그대로면 기존 값 유지. 타입이 바뀌면(스펙 변경) 새 실측값 채택. 기존에 없던 신규 필드는 새 값 사용 |
|
||||
| 응답 필드 본문 (실측 실패로 마커만 남은 자리) | 사람이 채웠으면 유지 |
|
||||
| 응답 예시 본문 | 실측 산출물에는 `<!-- @probed -->` 출처 마커가 붙는다. 마커가 없으면 사람 작성분으로 보고 유지 |
|
||||
| 응답 예시 JSON (양쪽 다 실측 산출물) | 응답의 **키 구조**가 같으면 기존 예시 유지. 필드 집합이 달라지면 새 실측 예시 채택 |
|
||||
| 응답 예시·응답 필드 (이번 실측이 실패) | 기존이 실측 산출물이면 그대로 유지 (마커로 덮지 않는다) |
|
||||
| 에러 응답 표 | 상태코드 키 단위 병합. 사람이 추가한 행(도메인 특이 에러)은 살리고, 자동 추론에만 있는 상태코드는 편입. 같은 상태코드는 기존 행 우선 |
|
||||
|
||||
`@probed` 마커가 필요한 이유: 실측은 1회 호출이 관측한 표본 하나뿐이라, 사람이 코드를 읽고 쓴 사실
|
||||
(성공 케이스와 엣지 케이스를 함께 제시하는 등)보다 좁다. 실측 결과는 기본값이지 덮어쓰기 권한이 아니다.
|
||||
|
||||
**재생성은 멱등해야 한다.** 실측값은 호출 시점 DB 상태가 낳은 표본이라, 그대로 반영하면 코드가 하나도
|
||||
바뀌지 않은 문서까지 재실행마다 diff 가 난다(`id` 예시값, `updated_at`, `cache_version` 등). 그래서
|
||||
값이 아니라 **스펙**(필드 집합·타입)이 바뀐 경우에만 갱신한다. 같은 이유로 요청 예시의 path 파라미터는
|
||||
실측 치환값(`/brands/1`)이 아니라 라우트 정의의 placeholder(`/brands/{brand}`)로 고정한다 — 실측
|
||||
성패에 따라 예시가 흔들리지 않아야 한다.
|
||||
|
||||
실측 실패(`실측 제외: ...`)는 "새로 관측하지 못했다"는 뜻이지 기존 관측이 무효라는 뜻이 아니다.
|
||||
실측 성패는 호출 시점 데이터 유무에 좌우된다(예: `DELETE /checkout` 은 삭제할 체크아웃이 없으면 404).
|
||||
따라서 실측 실패가 기존 실측 결과를 지우지 않는다.
|
||||
|
||||
nullable 필드는 표본에 값이 있느냐에 따라 관측 타입이 흔들린다(`loggable_type` 이 string ↔ null).
|
||||
`null` 관측은 타입 변경이 아니라 "이번 표본에 값이 없었다" 는 뜻이므로, 기존에 관측한 실제 값을 유지한다.
|
||||
|
||||
에러 응답 표는 라우트 메타에서 대표 상태코드를 자동 추론한다: 인증 필수(`auth:sanctum`)→401,
|
||||
`admin`/`permission:` 요구→403, FormRequest 검증 규칙 존재→422, path 파라미터 존재→404.
|
||||
`optional.sanctum`(선택 인증)은 401 을 유발하지 않는다. 도메인 특이 에러(409·429 등)는 사람이 보강한다.
|
||||
@@ -127,8 +176,8 @@ README.md "API 레퍼런스" 또는 AGENTS.md "API 레퍼런스 진입점" 표
|
||||
조립(raw HTTP 요청 골격), 응답 예시는 `<!-- 실측 제외: {사유} — 응답 예시는 사람이 작성하세요. -->` 마커로 남긴다.
|
||||
- 두 예시 블록은 전량 `@generated` 블록 **내부**에 있다. 이미 파라미터/응답 필드 표의 사람 서술이
|
||||
채워진 문서에 예시만 추가할 때는 `api:docgen --examples-only` 로 표·서술을 건드리지 않고 예시 2블록만
|
||||
in-place 삽입/치환한다(측정은 재수행하되 표는 불가침). 백필 커맨드(`backfill-params`/`backfill-fields`)도
|
||||
예시 블록을 건드리지 않는다.
|
||||
in-place 삽입/치환한다(측정은 재수행하되 표는 불가침, 신규 엔드포인트 섹션은 만들지 못한다). 백필
|
||||
커맨드(`backfill-params`/`backfill-fields`)도 예시 블록을 건드리지 않는다.
|
||||
|
||||
### 재생성이 지우지 못하는 것
|
||||
|
||||
@@ -333,9 +382,8 @@ php artisan api:docgen --scope=core --dry-run
|
||||
### 설명 백필 커맨드 (`api:docgen-backfill-*`)
|
||||
|
||||
파라미터/응답 필드 표의 `<!-- TODO: 설명 -->` 셀 중 **도메인 무관 공통 필드**(페이지네이션·정렬·검색·
|
||||
식별자·기간·토글·공통 파생 필드 등)는 전체 재생성 없이 in-place 로 자동 서술한다. 전체 재생성
|
||||
(`api:docgen`)은 `@generated` 블록 표를 통째로 재조립해 실측 예시값·사람 서술 셀을 되돌리므로, TODO
|
||||
셀만 치환하는 별도 백필 커맨드를 쓴다(멱등 — 채워진 셀·실측 예시값 불가침).
|
||||
식별자·기간·토글·공통 파생 필드 등)는 전체 재생성 없이 in-place 로 자동 서술한다. 실측을 재수행하지 않아
|
||||
빠르고, 실측 예시값도 그대로 둔다(멱등 — 채워진 셀·실측 예시값 불가침).
|
||||
|
||||
```bash
|
||||
# 요청 파라미터 표 TODO 셀 백필 (SSoT: App\Support\ApiDoc\ParameterDescriber)
|
||||
@@ -364,22 +412,50 @@ php artisan api:docgen-backfill-fields
|
||||
즉 코어 API 표면(`routes/api.php`·`app/Http/{Controllers,Requests,Resources}/**`)을
|
||||
변경하면서 코어 API 문서를 함께 갱신하지 않으면 그 변경은 통과하지 못한다. 나머지 확장은 문서
|
||||
완비 시 순차로 차단 대상에 편입된다.
|
||||
- 면제: `src/routes/api.php` 가 없는 web 전용 확장은 문서 대상이 아니므로 검사 대상에서 제외된다
|
||||
("문서 대상이 아닌 확장" 참조).
|
||||
|
||||
---
|
||||
|
||||
## 체크리스트
|
||||
|
||||
```text
|
||||
□ 그 확장에 api/ 표면이 있는가? (src/routes/api.php 부재 = web 전용 → 문서 대상 아님)
|
||||
□ 엔드포인트가 대응 위치(코어 docs/backend/api/ 또는 확장 docs/api/)에 문서화되었는가?
|
||||
□ 요청 파라미터 표에 위치/타입/필수/허용값/용도가 모두 기재되었는가?
|
||||
□ 요청 예시(raw HTTP 요청) 블록이 방출되었는가? (curl 금지, 인증 필요 시 Bearer {YOUR_TOKEN} 마스킹)
|
||||
□ 응답 필드 표가 envelope 의 data 내부 기준으로 작성되었는가?
|
||||
□ 응답 예시(envelope 전문 JSON) 블록이 방출되었는가? (목록은 2항목 절단)
|
||||
□ 훅 주입 파라미터가 있으면 주석 + 사람 보강이 되었는가?
|
||||
□ TODO 마커가 모두 채워졌는가?
|
||||
□ 미채움 마커 5종이 전수 0 인가? (아래 참조 — `TODO:` 만 세는 부분 집계 금지)
|
||||
□ api:docgen --check 가 drift 0 인가?
|
||||
```
|
||||
|
||||
### 미채움 마커 5종 (전수 0 이 완료 기준)
|
||||
|
||||
`api:docgen` 은 실측할 수 없는 자리에 "사람이 작성하세요" 마커를 남긴다. **실측 불가는 그 자리를 비워둘
|
||||
사유가 아니다.** 컨트롤러/Resource/FormRequest/Enum/lang 을 읽어 코드 근거로 채우는 것이 규정이다.
|
||||
|
||||
| 마커 | 채울 것 | 근거 소스 |
|
||||
| --- | --- | --- |
|
||||
| `<!-- 실측 제외: {사유} — 응답 필드는 사람이 작성하세요. -->` | 응답 필드 표 | Resource `toArray()` 의 키 전수 + 타입, Enum `label()`/`variant()` |
|
||||
| `<!-- 실측 제외: {사유} — 응답 예시는 사람이 작성하세요. -->` | 응답 예시 JSON | 컨트롤러의 `ResponseHelper::success/paginated/dataSource` 호출 형태 + Resource + lang 의 message 문구 |
|
||||
| `<!-- TODO: 용도 -->` | 요청 파라미터 설명 셀 | FormRequest `rules()`/`messages()`, 설정 키는 관리자 설정 UI 다국어 라벨 |
|
||||
| `<!-- TODO: 설명 -->` | 응답 필드 설명 셀 | Resource `toArray()` 파생 로직, 모델 `$casts`/관계, 마이그레이션 한국어 comment |
|
||||
| `_대표 에러 없음 ... <!-- TODO: ... -->_` | 도메인 특이 에러 표 | 컨트롤러의 `abort()`/예외 throw, Service 의 커스텀 Exception |
|
||||
|
||||
도메인 무관하게 의미가 고정된 파라미터/필드는 문서에 손으로 쓰지 말고 `ParameterDescriber`/
|
||||
`ResourceFieldDescriber` 사전에 등재한다 — 사전은 재생성에 영속하고 신규 문서에도 자동 적용된다.
|
||||
반대로 **도메인 특이 의미를 공통 사전에 넣지 않는다** (오설명이 전 문서로 퍼진다).
|
||||
|
||||
전수 집계는 5종 마커를 한 번에 세야 한다. `TODO:` 만 세면 그 바깥의 미채움(`실측 제외` 등)이 집계에서
|
||||
빠져 부분 집계가 완료로 통과한다:
|
||||
|
||||
```bash
|
||||
grep -rcE "실측 제외:|TODO: 용도|TODO: 설명|실측 응답에 필드 없음|대표 에러 없음" \
|
||||
--include=*.md docs/backend/api {modules,plugins}/_bundled/*/docs/api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
@@ -229,22 +229,23 @@ location ~* \.(js|css|json)$ { expires max; access_log off; }
|
||||
> 각 확장이 자신의 API 문서를 소유합니다. 아래 표는 자동 생성됩니다.
|
||||
|
||||
<!-- @generated:start:api-readme-extensions -->
|
||||
- **확장 수**: 13 · **엔드포인트 수**: 391
|
||||
- **확장 수**: 14 · **엔드포인트 수**: 416
|
||||
|
||||
| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |
|
||||
| --- | --- | --- | --- |
|
||||
| `gnuboard7-hello_module` | 모듈 | [docs/api/](../../../modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 7 |
|
||||
| `sirsoft-board` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-board/docs/api/README.md) | 10 / 80 |
|
||||
| `sirsoft-ecommerce` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 232 |
|
||||
| `sirsoft-ecommerce` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-ecommerce/docs/api/README.md) | 33 / 239 |
|
||||
| `sirsoft-page` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
|
||||
| `sirsoft-ckeditor5` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-ckeditor5/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-gdpr` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-gdpr/docs/api/README.md) | 4 / 15 |
|
||||
| `sirsoft-marketing` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-marketing/docs/api/README.md) | 2 / 2 |
|
||||
| `sirsoft-message_bizppurio` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-message_bizppurio/docs/api/README.md) | 6 / 12 |
|
||||
| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 22 |
|
||||
| `sirsoft-pay_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-pay_kginicis/docs/api/README.md) | 5 / 34 |
|
||||
| `sirsoft-pay_nhnkcp` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-pay_nhnkcp/docs/api/README.md) | 0 / 0 |
|
||||
| `sirsoft-pay_nicepayments` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-pay_nicepayments/docs/api/README.md) | 0 / 0 |
|
||||
| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 1 / 1 |
|
||||
| `sirsoft-tosspayments` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-tosspayments/docs/api/README.md) | 2 / 4 |
|
||||
| `sirsoft-verification_kginicis` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-verification_kginicis/docs/api/README.md) | 2 / 3 |
|
||||
| `sirsoft-verification_nhnkcp` | 플러그인 | [docs/api/](../../../plugins/_bundled/sirsoft-verification_nhnkcp/docs/api/README.md) | 1 / 1 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -214,7 +214,7 @@ HTTP/1.1 200
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| ids | body | array | 예 | min 1 | 대상 리소스 식별자 배열 (대량 작업 대상) |
|
||||
| ids | body | array | 예 | min 1 | 삭제할 활동 로그 ID 배열 (원소는 integer 이며 `activity_logs.id` 에 존재해야 함) |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -234,18 +234,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| deleted_count | integer | `3` | 실제로 삭제된 활동 로그 건수 (`ActivityLogService::deleteMany()` 반환값 — 요청한 `ids` 중 삭제에 성공한 개수) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "선택한 활동 로그가 삭제되었습니다.",
|
||||
"data": {
|
||||
"deleted_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.activities.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.activities.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -268,7 +284,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/activity-logs/159 HTTP/1.1
|
||||
DELETE /api/admin/activity-logs/{activityLog} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -276,9 +292,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success('activity_log.delete_success')` 를 데이터 인자 없이 호출하여 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -299,8 +313,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.activities.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.activities.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| hash | path | string | 예 | — | 대상 리소스의 해시 식별자 |
|
||||
| hash | path | string | 예 | — | 다운로드할 첨부파일의 해시 식별자 (`attachments.hash`) |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -39,17 +39,45 @@ Accept: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 JSON 봉투(`data`)를 반환하지 않습니다. 성공 시 파일 바이너리 본문을 그대로 응답합니다 (실패 시에만 JSON 에러 봉투)._
|
||||
|
||||
| 응답 헤더 | 값 | 용도/설명 |
|
||||
| --- | --- | --- |
|
||||
| Content-Type | `image/png` 등 | 첨부파일의 MIME 타입 (`attachments.mime_type`) |
|
||||
| Content-Disposition | `attachment; filename="원본파일명.pdf"` | 이미지가 아닌 파일에만 부여 — 원본 파일명으로 다운로드 |
|
||||
| Cache-Control | `public, max-age=86400, immutable` (프로덕션) / `no-cache` (그 외) | 이미지 응답의 캐싱 정책. max-age 는 환경설정 `cache.layout_ttl` (기본 86400초) |
|
||||
| Expires | `Wed, 15 Jul 2026 00:00:00 GMT` | 이미지 응답의 만료 시각 (현재 시각 + max-age) |
|
||||
| ETag | `9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d` | 이미지 응답의 검증자 (파일 수정시각 + 크기의 MD5). 요청의 `If-None-Match` 와 일치하면 `304 Not Modified` |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: image/png
|
||||
Cache-Control: public, max-age=86400, immutable
|
||||
Expires: Wed, 15 Jul 2026 00:00:00 GMT
|
||||
ETag: 9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d
|
||||
|
||||
<파일 바이너리>
|
||||
```
|
||||
|
||||
이미지가 아닌 파일:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/pdf
|
||||
Content-Disposition: attachment; filename="manual.pdf"
|
||||
|
||||
<파일 바이너리>
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 304 | Not Modified | 이미지 응답에서 요청 `If-None-Match` 헤더가 현재 ETag 와 일치하는 경우 (본문 없음) |
|
||||
| 403 | Forbidden | 첨부파일 접근 권한 없음 (`core.attachment.download` 훅 권한 미충족) 또는 스토리지에 실제 파일이 없는 경우 — `{"success": false, "message": "이 첨부파일에 대한 접근 권한이 없습니다."}` |
|
||||
| 404 | Not Found | 해당 해시의 첨부파일이 존재하지 않는 경우 — `{"success": false, "message": "첨부파일을 찾을 수 없습니다."}` |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+152
-10
@@ -75,11 +75,59 @@ example-key
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AttachmentResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 첨부파일 ID (기본 키) |
|
||||
| hash | string | `"aB3xY9kLmQ7z"` | URL용 고유 해시 (12자). 다운로드 URL 식별자로 사용 |
|
||||
| original_filename | string | `"example.pdf"` | 업로드된 원본 파일명 |
|
||||
| mime_type | string | `"application/pdf"` | MIME 타입 (예: `image/jpeg`, `application/pdf`) |
|
||||
| size | integer | `102400` | 파일 크기 (바이트) |
|
||||
| size_formatted | string | `"100 KB"` | 사람이 읽기 쉬운 형식으로 포맷된 파일 크기 (B/KB/MB/GB) |
|
||||
| collection | string | `"default"` | 첨부파일 컬렉션/그룹명 (미지정 시 `default`) |
|
||||
| order | integer | `0` | 컬렉션 내 정렬 순서 |
|
||||
| download_url | string | `"/api/attachment/aB3xY9kLmQ7z"` | 해시 기반 다운로드 경로 |
|
||||
| is_image | boolean | `false` | MIME 타입이 `image/` 로 시작하는지 여부 |
|
||||
| meta | object\|null | `{"width": 800, "height": 600}` | 추가 메타데이터. 이미지 업로드 시 width/height 자동 기록, 그 외에는 빈 객체 |
|
||||
| source_type | string | `"core"` | 첨부 생성 출처 (`core` / `module` / `plugin`) |
|
||||
| source_identifier | string\|null | `"sirsoft-board"` | 모듈/플러그인 식별자 (코어 업로드 시 `null`) |
|
||||
| creator | object\|없음 | `{"uuid": "...", "name": "관리자"}` | 업로더 정보(`uuid`, `name`). `creator` 관계가 eager load 된 경우에만 포함되며, 업로드 응답에는 포함되지 않음 |
|
||||
| created_at | string | `"2026-07-14 10:23:41"` | 생성 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) |
|
||||
| updated_at | string | `"2026-07-14 10:23:41"` | 수정 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) |
|
||||
| is_owner | boolean | `true` | 요청자가 업로더(`created_by`)인지 여부 |
|
||||
| abilities | object | `{"can_update": true, "can_delete": true}` | 요청자의 권한 맵 (`can_update` = `core.attachments.update`, `can_delete` = `core.attachments.delete`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "파일이 업로드되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"hash": "aB3xY9kLmQ7z",
|
||||
"original_filename": "example.pdf",
|
||||
"mime_type": "application/pdf",
|
||||
"size": 102400,
|
||||
"size_formatted": "100 KB",
|
||||
"collection": "default",
|
||||
"order": 0,
|
||||
"download_url": "/api/attachment/aB3xY9kLmQ7z",
|
||||
"is_image": false,
|
||||
"meta": {},
|
||||
"source_type": "core",
|
||||
"source_identifier": null,
|
||||
"created_at": "2026-07-14 10:23:41",
|
||||
"updated_at": "2026-07-14 10:23:41",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -88,6 +136,7 @@ example-key
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.attachments.create`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 파일 저장/DB 기록 중 예외 발생 시 (`attachment.upload_failed` — "파일 업로드에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -136,11 +185,88 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_배열 응답: `data` 는 `AttachmentResource` 객체의 배열입니다 (페이지네이션 없음). 각 항목의 필드는 단일 업로드 응답과 동일합니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| data[].id | integer | `1` | 첨부파일 ID (기본 키) |
|
||||
| data[].hash | string | `"aB3xY9kLmQ7z"` | URL용 고유 해시 (12자) |
|
||||
| data[].original_filename | string | `"photo1.jpg"` | 업로드된 원본 파일명 |
|
||||
| data[].mime_type | string | `"image/jpeg"` | MIME 타입 |
|
||||
| data[].size | integer | `204800` | 파일 크기 (바이트) |
|
||||
| data[].size_formatted | string | `"200 KB"` | 포맷된 파일 크기 |
|
||||
| data[].collection | string | `"default"` | 첨부파일 컬렉션/그룹명 |
|
||||
| data[].order | integer | `0` | 컬렉션 내 정렬 순서 (배치 내 파일마다 순차 증가) |
|
||||
| data[].download_url | string | `"/api/attachment/aB3xY9kLmQ7z"` | 해시 기반 다운로드 경로 |
|
||||
| data[].is_image | boolean | `true` | MIME 타입이 `image/` 로 시작하는지 여부 |
|
||||
| data[].meta | object\|null | `{"width": 1920, "height": 1080}` | 이미지 업로드 시 width/height 자동 기록 |
|
||||
| data[].source_type | string | `"core"` | 첨부 생성 출처 (`core` / `module` / `plugin`) |
|
||||
| data[].source_identifier | string\|null | `null` | 모듈/플러그인 식별자 |
|
||||
| data[].created_at | string | `"2026-07-14 10:23:41"` | 생성 일시 (사용자 타임존 기준) |
|
||||
| data[].updated_at | string | `"2026-07-14 10:23:41"` | 수정 일시 (사용자 타임존 기준) |
|
||||
| data[].is_owner | boolean | `true` | 요청자가 업로더인지 여부 |
|
||||
| data[].abilities | object | `{"can_update": true, "can_delete": true}` | 요청자의 권한 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "파일이 일괄 업로드되었습니다.",
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"hash": "aB3xY9kLmQ7z",
|
||||
"original_filename": "photo1.jpg",
|
||||
"mime_type": "image/jpeg",
|
||||
"size": 204800,
|
||||
"size_formatted": "200 KB",
|
||||
"collection": "default",
|
||||
"order": 0,
|
||||
"download_url": "/api/attachment/aB3xY9kLmQ7z",
|
||||
"is_image": true,
|
||||
"meta": {
|
||||
"width": 1920,
|
||||
"height": 1080
|
||||
},
|
||||
"source_type": "core",
|
||||
"source_identifier": null,
|
||||
"created_at": "2026-07-14 10:23:41",
|
||||
"updated_at": "2026-07-14 10:23:41",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"hash": "Zq1WeRt5YuIo",
|
||||
"original_filename": "photo2.jpg",
|
||||
"mime_type": "image/jpeg",
|
||||
"size": 153600,
|
||||
"size_formatted": "150 KB",
|
||||
"collection": "default",
|
||||
"order": 1,
|
||||
"download_url": "/api/attachment/Zq1WeRt5YuIo",
|
||||
"is_image": true,
|
||||
"meta": {
|
||||
"width": 1280,
|
||||
"height": 720
|
||||
},
|
||||
"source_type": "core",
|
||||
"source_identifier": null,
|
||||
"created_at": "2026-07-14 10:23:41",
|
||||
"updated_at": "2026-07-14 10:23:41",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -149,6 +275,7 @@ Content-Type: application/json
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.attachments.create`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 배치 중 파일 저장/DB 기록 예외 발생 시 (`attachment.upload_failed` — "파일 업로드에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -187,11 +314,17 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 데이터를 반환하지 않습니다 (`data` 는 `null`, 성공 메시지만 반환)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "파일 순서가 변경되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -199,7 +332,8 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.attachments.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). `order[].id` 가 존재하지 않는 첨부파일이면 "존재하지 않는 첨부파일입니다." |
|
||||
| 500 | Internal Server Error | 순서 갱신 중 예외 발생 시 (`attachment.reorder_failed` — "파일 순서 변경에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -229,19 +363,27 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 데이터를 반환하지 않습니다 (`data` 는 `null`, 성공 메시지만 반환)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "파일이 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | 삭제 처리가 실패로 반환된 경우 (`attachment.delete_failed` — "파일 삭제에 실패했습니다.") |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.attachments.delete`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | `{attachment}` 에 해당하는 첨부파일이 없는 경우 (라우트 모델 바인딩 실패) |
|
||||
| 500 | Internal Server Error | 파일/DB 삭제 중 예외 발생 시 (`attachment.delete_failed` — "파일 삭제에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+302
-31
@@ -38,9 +38,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@logout` 이 `success('auth.logout_success')` 를 인자 없이 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -285,17 +283,59 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AuthService::login()` 이 반환한 배열 — `user` 만 `UserResource` 로 감싼다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| user | object | `{"uuid":"a234c2b1-…","name":"관리자","is_admin":true, …}` | 로그인한 관리자 정보 (`UserResource` — 필드 전수는 `GET /api/admin/auth/user` 응답 필드 표와 동일) |
|
||||
| token | string | `75\|WgPUplvLGTv8YIj4507uIR6dEOHTXyNUed…` | 발급된 Sanctum 접근 토큰 평문 (이후 `Authorization: Bearer` 헤더로 사용, 발급 시 1회만 노출) |
|
||||
| token_type | string | `Bearer` | 토큰 타입 (항상 `Bearer` — `AuthService::login()` 이 상수로 반환) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "관리자 로그인이 성공했습니다.",
|
||||
"data": {
|
||||
"user": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"status": "active",
|
||||
"is_admin": true,
|
||||
"roles": [
|
||||
{ "id": 1, "identifier": "admin", "name": "관리자" }
|
||||
],
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
},
|
||||
"token": "{MASKED}",
|
||||
"token_type": "Bearer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user` 객체는 지면 절약을 위해 축약했습니다. 실제로는 `GET /api/admin/auth/user` 의 `data` 와 동일한 `UserResource` 필드 전수가 내려옵니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 이메일/비밀번호가 일치하지 않는 경우 (`auth.login_failed`) |
|
||||
| 403 | Forbidden | 자격 증명은 맞지만 관리자 역할이 아닌 경우 (`auth.admin_required`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 423 | Locked | 로그인 실패 누적으로 계정이 잠긴 경우 (`auth.account_locked` — `error.locked_until`, `error.retry_after_seconds` 포함) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -335,17 +375,27 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@forgotPassword` 가 `success('auth.password_reset_email_sent')` 를 인자 없이 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "비밀번호 재설정 이메일이 발송되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우, 또는 등록되지 않은 이메일인 경우 (`auth.password_reset_failed` — `error.errors.email` 에 `auth.email_not_registered` 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -385,17 +435,56 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AuthService::login()` 이 반환한 배열 — `user` 만 `UserResource` 로 감싼다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| user | object | `{"uuid":"a234c2b1-…","name":"홍길동","is_admin":false, …}` | 로그인한 사용자 정보 (`UserResource` — 필드 전수는 `GET /api/auth/user` 응답 필드 표의 기본(코어) 필드와 동일) |
|
||||
| token | string | `75\|WgPUplvLGTv8YIj4507uIR6dEOHTXyNUed…` | 발급된 Sanctum 접근 토큰 평문 (이후 `Authorization: Bearer` 헤더로 사용, 발급 시 1회만 노출) |
|
||||
| token_type | string | `Bearer` | 토큰 타입 (항상 `Bearer`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "로그인이 성공했습니다.",
|
||||
"data": {
|
||||
"user": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"language": "ko",
|
||||
"status": "active",
|
||||
"is_admin": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
},
|
||||
"token": "{MASKED}",
|
||||
"token_type": "Bearer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user` 객체는 지면 절약을 위해 축약했습니다. 실제로는 `UserResource` 필드 전수가 내려옵니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 이메일/비밀번호가 일치하지 않거나 계정 상태가 활성이 아닌 경우 (`auth.login_failed`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 423 | Locked | 로그인 실패 누적으로 계정이 잠긴 경우 (`auth.account_locked` — `error.locked_until`, `error.retry_after_seconds` 포함) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -488,9 +577,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@logout` 이 `success('auth.logout_success')` 를 인자 없이 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -576,17 +663,56 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AuthService::register()` 이 반환한 배열 — `user` 만 `UserResource` 로 감싼다). 성공 시 HTTP 201._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| user | object | `{"uuid":"a234c2b1-…","name":"홍길동","status":"active", …}` | 생성된 사용자 정보 (`UserResource`. `status` 는 `active`, 가입 후 본인인증 정책이 걸린 경우 `pending_verification`) |
|
||||
| token | string | `75\|WgPUplvLGTv8YIj4507uIR6dEOHTXyNUed…` | 가입 즉시 발급되는 Sanctum 접근 토큰 평문 (가입 직후 로그인 상태로 이어짐) |
|
||||
| token_type | string | `Bearer` | 토큰 타입 (항상 `Bearer`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "회원가입이 성공했습니다.",
|
||||
"data": {
|
||||
"user": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"nickname": null,
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"language": "ko",
|
||||
"status": "active",
|
||||
"is_admin": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
},
|
||||
"token": "{MASKED}",
|
||||
"token_type": "Bearer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user` 객체는 지면 절약을 위해 축약했습니다. 실제로는 `UserResource` 필드 전수가 내려옵니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`auth.register_failed` — `error.errors` 에 필드별 메시지) |
|
||||
| 428 | Precondition Required | 가입 전 본인인증 정책이 매칭되었으나 유효한 `verification_token` 이 없는 경우 (`core.auth.before_register` 훅) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -628,17 +754,27 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@resetPassword` 가 `success('auth.password_reset_success')` 를 인자 없이 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "비밀번호가 성공적으로 재설정되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반했거나, 토큰이 유효하지 않거나 만료된 경우 (`auth.password_reset_failed` — `error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -737,7 +873,7 @@ _단건 응답: `data` 객체의 필드._
|
||||
| channels | array | `[{"key":"email_subscription","label":"광고성 이메일 수신","enable…` | 관리자 정의 전체 마케팅 채널 목록 (원소 key/label/enabled/terms_slug — marketing 플러그인 주입) |
|
||||
| consent_histories | array | `[]` | 동의 변경 이력 (원소 channel_key/action/source/created_at — marketing 플러그인 주입) |
|
||||
| ecommerce_mileage | object | `{"enabled":false}` | 마일리지 정보 (enabled/잔액 — ecommerce 모듈 주입, 모듈 비활성 시 enabled=false) |
|
||||
| ecommerce_preferred_currency | null | `null` | 선호 결제 통화 (ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_currency | string | `KRW` | 선호 결제 통화 (ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country | null | `null` | 선호 배송 국가 코드 (ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country_name | null | `null` | 선호 배송 국가 이름 (국가 코드에서 현지화 파생 — ecommerce 모듈 주입, 미설정 시 null) |
|
||||
|
||||
@@ -808,17 +944,33 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AuthService::validateResetToken()` 의 반환 배열)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| valid | boolean | `true` | 토큰 유효 여부. 성공 응답에서는 항상 `true` (유효하지 않으면 컨트롤러가 422 로 전환하므로 이 필드가 `false` 인 200 응답은 없음) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"valid": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터 검증 위반, 또는 토큰이 유효하지 않거나 만료된 경우 / 미등록 이메일 (`auth.reset_token_invalid` — `error.errors.token` 에 사유 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -848,16 +1000,27 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@logout` 이 `success('auth.logout_success')` 를 인자 없이 호출하므로 `data` 는 `null`). 공용 `POST /api/auth/logout` 과 동일한 컨트롤러 메서드._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "로그아웃이 성공했습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.auth.logout`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -888,16 +1051,27 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `AuthController@logoutFromAllDevices` 가 `success('auth.logout_all_devices_success')` 를 인자 없이 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "모든 디바이스에서 로그아웃되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.auth.logout`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -928,16 +1102,53 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`AuthService::refreshToken()` 반환 배열 — 공용 `POST /api/admin/auth/refresh` 와 동일 shape)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| user | object | `{"uuid":"a234c2b1-…","name":"홍길동", …}` | 토큰을 갱신한 사용자 정보 (`UserResource`) |
|
||||
| token | string | `75\|WgPUplvLGTv8YIj4507uIR6dEOHTXyNUed…` | 새로 발급된 Sanctum 접근 토큰 평문 (기존 토큰은 폐기됨) |
|
||||
| token_type | string | `Bearer` | 토큰 타입 (항상 `Bearer`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"user": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"status": "active",
|
||||
"is_admin": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
},
|
||||
"token": "{MASKED}",
|
||||
"token_type": "Bearer"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user` 객체는 지면 절약을 위해 축약했습니다. 실제로는 `UserResource` 필드 전수가 내려옵니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.auth.refresh`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -968,16 +1179,76 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드. 컨트롤러 메서드가 공용 `GET /api/auth/user` 와 동일한 `AuthController@user` 이므로, 응답은 `UserResource::toAuthArray()` 산물(코어 필드 + `core.user.filter_resource_data` 로 확장이 병합한 필드)로 그 문서의 응답 필드 표와 동일합니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `API 문서 샘플 사용자` | 사용자 이름 |
|
||||
| nickname | string \| null | `song.hyunji` | 닉네임 (미설정 시 null) |
|
||||
| email | string | `apidoc-sample-user@example.com` | 이메일 주소 |
|
||||
| language | string | `ko` | 사용자 언어 설정 |
|
||||
| status | string | `active` | 계정 상태 (active / inactive / blocked / withdrawn / pending_verification) |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 |
|
||||
| roles | array | `[{"id":2,"identifier":"user","name":"일반회원"}]` | 부여된 역할 목록 (id/identifier/name) |
|
||||
| permissions | array | `[{"id":81,"identifier":"sirsoft-ecommerce.user-products.read","name":"상품 조회"}]` | 역할 경유 권한 목록 (id/identifier/name) |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_update":true, …}` | 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
| (확장 병합 필드) | — | `notify_*`, `marketing_consent*`, `ecommerce_*` 등 | marketing 플러그인·ecommerce 모듈이 `core.user.filter_resource_data` 필터로 병합 — 전수는 `GET /api/auth/user` 응답 필드 표 참조 |
|
||||
|
||||
> 필드 전수(코어 + 확장 병합)는 `GET /api/auth/user` 의 응답 필드 표와 동일하므로 그 표를 SSoT 로 참조합니다. 게스트(비인증) 요청은 `optional.sanctum` 을 통과하지만 `request()->user()` 가 없으므로 이 경로는 인증 사용자 컨텍스트에서만 사용자 객체를 반환합니다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"nickname": "song.hyunji",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"language": "ko",
|
||||
"status": "active",
|
||||
"is_admin": false,
|
||||
"roles": [
|
||||
{ "id": 2, "identifier": "user", "name": "일반회원" }
|
||||
],
|
||||
"permissions": [],
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
},
|
||||
"notify_post_complete": false,
|
||||
"notify_post_reply": false,
|
||||
"notify_comment": false,
|
||||
"notify_reply_comment": false,
|
||||
"ecommerce_mileage": {
|
||||
"enabled": false
|
||||
},
|
||||
"ecommerce_preferred_currency": null,
|
||||
"ecommerce_preferred_shipping_country": null,
|
||||
"ecommerce_preferred_shipping_country_name": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 지면 절약을 위해 축약했습니다. 실제 응답은 `GET /api/auth/user` 의 응답 예시와 동일한 필드 전수를 포함합니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.auth.user`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -38,17 +38,25 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "프로필 이미지가 성공적으로 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 404 | Not Found | 삭제할 아바타 첨부파일이 없는 경우 (`user.avatar_not_found` — "삭제할 프로필 이미지가 없습니다.") |
|
||||
| 500 | Server Error | 첨부파일/실제 파일 삭제 중 예외 발생 (`user.avatar_delete_failed` — "프로필 이미지 삭제에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -86,11 +94,25 @@ Content-Type: image/png
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| avatar | string\|null | `/api/attachment/9f1c2b7d8e...` | 업로드된 아바타의 다운로드 URL (`Attachment.download_url` = `/api/attachment/{hash}`). 레거시 `avatar` 컬럼만 있는 경우 `storage/attachments/avatars/{파일명}` 형태의 절대 URL |
|
||||
| attachment_id | integer | `1` | 생성된 첨부파일(Attachment) 레코드의 기본 키 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "프로필 이미지가 성공적으로 업로드되었습니다.",
|
||||
"data": {
|
||||
"avatar": "/api/attachment/9f1c2b7d8e3a4c5b6d7e8f90a1b2c3d4",
|
||||
"attachment_id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -98,6 +120,7 @@ Content-Type: image/png
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Server Error | 파일 저장/첨부파일 생성 중 예외 발생 (`user.avatar_upload_failed` — "프로필 이미지 업로드에 실패했습니다.") |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -37,17 +37,26 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 G7 공통 응답 봉투(`success`/`message`/`data`)를 사용하지 않습니다. 라우트 클로저가 `Broadcast::auth($request)` 의 반환값을 그대로 응답하므로, 응답 본문은 Laravel 브로드캐스팅 드라이버(Reverb — Pusher 프로토콜 호환)가 생성하는 채널 인증 페이로드입니다. 등록된 채널(`routes/channels.php`, 모듈/플러그인 `getChannels()`)은 모두 boolean 을 반환하는 private 채널이므로 아래 필드만 반환됩니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| auth | string | `앱키:서명` 형식 문자열 | 클라이언트가 WebSocket 서버(Reverb)에 프라이빗 채널 구독을 요청할 때 제시하는 인증 서명. `{reverb_app_key}:{HMAC-SHA256(socket_id:channel_name)}` 형태이며, 브로드캐스팅 클라이언트 라이브러리가 자동으로 소비합니다 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"auth": "app-key:5f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8"
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 웹소켓 사용 OFF(`broadcasting.default === 'null'`) 로 채널 인증이 거부된 경우, 또는 요청한 채널의 인증 콜백이 `false` 를 반환한 경우(권한 부족·타 사용자 채널 구독 시도 등) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -95,18 +95,39 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| update_available | boolean | `false` | 새 버전 존재 여부 (최신 릴리스 버전이 현재 버전보다 높으면 `true`) |
|
||||
| current_version | string | `7.0.3` | 현재 설치된 코어 버전 (`config('app.version')`) |
|
||||
| latest_version | string | `7.0.3` | GitHub 릴리스에서 조회한 최신 코어 버전 (조회 값이 없으면 현재 버전과 동일) |
|
||||
| github_url | string | `https://github.com/gnuboard/g7` | 업데이트 조회 대상 GitHub 저장소 URL (`config('app.update.github_url')`) |
|
||||
|
||||
> 조회 실패 시(GitHub 접속 불가 등)에는 422 응답이 반환되며, `error` 객체에 `reason`(실패 사유) · `current_version` · `github_url` 이 담깁니다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "업데이트 확인이 완료되었습니다.",
|
||||
"data": {
|
||||
"update_available": false,
|
||||
"current_version": "7.0.3",
|
||||
"latest_version": "7.0.3",
|
||||
"github_url": "https://github.com/gnuboard/g7"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -141,9 +141,21 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
_목록 응답: `data` 배열 항목의 필드. `data` 는 `core.dashboard.alerts` 필터 훅의 결과이며, 알릴 항목이 없으면 빈 배열(`[]`)입니다. 코어 기본 리스너(`ExtensionCompatibilityAlertListener`)가 주입하는 항목의 필드는 다음과 같습니다._
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | string | `compat_plugins_sirsoft-gdpr` | 알림 식별자 (`compat_{type}_{identifier}` = 자동 비활성화, `recover_{type}_{identifier}` = 재호환. 알림 닫기(dismiss) 상태 판정 키) |
|
||||
| type | string | `warning` | 알림 등급 (`warning`: 코어 비호환 자동 비활성화, `info`: 재호환 복구 가능) |
|
||||
| subtype | string | `incompatible_core` | 알림 세부 분류 (`incompatible_core`: 코어 버전 비호환으로 자동 비활성화됨, `recovery_available`: 코어 업그레이드 후 다시 활성화 가능) |
|
||||
| icon | string | `exclamation-triangle` | 아이콘 식별자 (warning: `exclamation-triangle`, info: `check-circle`) |
|
||||
| title | string | `플러그인 "sirsoft-gdpr" 자동 비활성화됨` | 알림 제목 (다국어 문구 — `extensions.alerts.incompatible_deactivated` / `recovered_title`) |
|
||||
| message | string | `필요 버전: 7.0.0-beta.9, 현재 설치됨: 7.0.0-beta.8` | 알림 본문 (다국어 문구 — `extensions.alerts.incompatible_message` / `recovered_body`) |
|
||||
| extension_type | string | `plugin` | 대상 확장 종류 (`module` / `plugin` / `template`) |
|
||||
| identifier | string | `sirsoft-gdpr` | 대상 확장 식별자 |
|
||||
| recover_endpoint | string | `/api/admin/extensions/plugin/sirsoft-gdpr/recover` | 재활성화 호출 엔드포인트 (재호환 알림 `subtype=recovery_available` 에만 존재) |
|
||||
| time | string\|null | `3시간 전` | 자동 비활성화 시각의 상대 표시 (diffForHumans() 산물, 비활성화 시각이 없으면 `null`) |
|
||||
| read | boolean | `false` | 읽음 여부 (주입 시점에는 항상 `false`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -151,6 +163,8 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
알릴 항목이 없는 경우 (기본):
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
@@ -159,12 +173,48 @@ HTTP/1.1 200
|
||||
}
|
||||
```
|
||||
|
||||
코어 비호환으로 자동 비활성화된 확장이 있는 경우:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "시스템 알림을 성공적으로 조회했습니다.",
|
||||
"data": [
|
||||
{
|
||||
"id": "compat_plugins_sirsoft-gdpr",
|
||||
"type": "warning",
|
||||
"subtype": "incompatible_core",
|
||||
"icon": "exclamation-triangle",
|
||||
"title": "플러그인 \"sirsoft-gdpr\" 자동 비활성화됨",
|
||||
"message": "필요 버전: 7.0.0-beta.9, 현재 설치됨: 7.0.0-beta.8",
|
||||
"extension_type": "plugin",
|
||||
"identifier": "sirsoft-gdpr",
|
||||
"time": "3시간 전",
|
||||
"read": false
|
||||
},
|
||||
{
|
||||
"id": "recover_modules_sirsoft-board",
|
||||
"type": "info",
|
||||
"subtype": "recovery_available",
|
||||
"icon": "check-circle",
|
||||
"title": "모듈 \"sirsoft-board\" 다시 호환 가능",
|
||||
"message": "코어 업그레이드 후 호환됩니다 (이전 요구: 7.0.0-beta.9). 다시 활성화할 수 있습니다.",
|
||||
"extension_type": "module",
|
||||
"identifier": "sirsoft-board",
|
||||
"recover_endpoint": "/api/admin/extensions/module/sirsoft-board/recover",
|
||||
"time": "2일 전",
|
||||
"read": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.read`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.activities`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -273,7 +323,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notification-logs.read`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.activities`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -345,7 +395,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.read`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.activities`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -431,7 +481,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.read`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.dashboard.activities`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -102,11 +102,27 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| alert_id | string | `compat_plugins_sirsoft-tosspayments` | dismiss 처리된 자동 비활성화 알림의 식별자 (`compat_{type}s_{identifier}` 형식). 재호환 알림(`recover_{type}s_{identifier}`)도 함께 dismiss 되지만 응답에는 포함되지 않음 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림을 닫았습니다.",
|
||||
"data": {
|
||||
"alert_id": "compat_plugins_sirsoft-tosspayments"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -145,11 +161,29 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| extension_type | string | `plugin` | 복구(재활성화)된 확장의 타입 (`module` \| `plugin` \| `template`) — 요청 path의 `{type}` 을 그대로 반환 |
|
||||
| identifier | string | `sirsoft-tosspayments` | 복구된 확장의 식별자 — 요청 path의 `{identifier}` 를 그대로 반환 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "확장이 다시 활성화되었습니다.",
|
||||
"data": {
|
||||
"extension_type": "plugin",
|
||||
"identifier": "sirsoft-tosspayments"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -157,7 +191,8 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.plugins.activate`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 (`extensions.errors.not_found`) |
|
||||
| 422 | Unprocessable Entity | 재검증 결과 여전히 코어 버전이 요구 버전에 미달하는 경우 — 글로벌 핸들러가 `core_version_mismatch` 로 변환 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+669
-77
File diff suppressed because it is too large.
Load diff
File diff suppressed because it is too large.
Load diff
+129
-9
@@ -67,7 +67,7 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| token | path | string | 예 | — | 인증/검증 토큰 |
|
||||
| token | path | string | 예 | — | 미리보기 토큰(UUID). `LayoutPreviewService::createPreview` 가 발급하며 기본 30분 후 만료 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -80,17 +80,76 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `success`/`message`/`data` 봉투를 사용하지 않습니다. `LayoutPreviewController@serve` 가 `response()->json($layout)` 로 **병합된 레이아웃 JSON 객체를 최상위(root)에 그대로** 반환합니다 (상속 병합 + 모듈/플러그인 확장 적용 완료 상태). 아래는 레이아웃 JSON의 최상위 키이며, 실제 포함 여부는 저장된 레이아웃 content 에 따라 달라집니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| version | string | `"1.0"` | 레이아웃 스키마 버전 (저장 시 필수) |
|
||||
| layout_name | string | `"product_list"` | 레이아웃 이름 (식별자) |
|
||||
| extends | string\|null | `"_user_base"` | 상속할 베이스 레이아웃 이름 (미리보기 서빙 시 이미 병합됨) |
|
||||
| slots | object | `{"content": [ ... ]}` | 베이스 레이아웃 슬롯에 삽입할 컴포넌트 배열 (extends 레이아웃) |
|
||||
| components | array | `[{"type":"basic","name":"Div", ...}]` | 렌더링할 컴포넌트 트리 (병합·확장 적용 결과) |
|
||||
| endpoint | string\|null | `"/api/products"` | 화면이 주로 fetch 하는 데이터 API 경로 (레거시·선택) |
|
||||
| data_sources | array | `[{"id":"products","endpoint":"/api/products","method":"GET"}]` | 화면이 로드하는 API 데이터 소스 정의 |
|
||||
| meta | object | `{"title":"상품 목록","auth_required":false}` | 메타 정보 (title, description, keywords, auth_required, is_base, guest_only, is_error_layout, error_code, seo) |
|
||||
| permissions | array\|object | `["core.templates.layouts.edit"]` | 레이아웃 접근에 필요한 권한 (flat 배열=AND, 구조화 객체=OR/AND 중첩) |
|
||||
| modals | object | `{}` | 모달 컴포넌트 정의 |
|
||||
| state / init_state / initLocal / initGlobal / initIsolated / global_state | object | `{}` | 레이아웃 레벨 초기 상태 정의 |
|
||||
| init_actions | array | `[{"handler":"apiCall", ...}]` | 레이아웃 로드 시 실행할 초기화 액션 |
|
||||
| actions / named_actions | array\|object | `{}` | 재사용 가능한 액션 정의 |
|
||||
| computed | object | `{}` | 계산된 값 정의 |
|
||||
| defines | object | `{}` | 재사용 가능한 컴포넌트 조각 정의 |
|
||||
| errorHandling | object | `{"404":{"handler":"navigate"}}` | 상태 코드별 에러 처리 정책 |
|
||||
| globalHeaders | array | `[{"pattern":"*","headers":{"X-Foo":"bar"}}]` | API 호출 시 자동 적용되는 HTTP 헤더 규칙 |
|
||||
| transition_overlay | object | `{"enabled":true,"style":"blur"}` | 페이지 전환 오버레이 설정 |
|
||||
| routes | array | `[]` | 라우트 정의 |
|
||||
| pageConfig / schema | object | `{}` | 플러그인 설정 레이아웃 전용 (설정 UI 안내/스키마) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"layout_name": "product_list",
|
||||
"meta": {
|
||||
"title": "상품 목록",
|
||||
"auth_required": false
|
||||
},
|
||||
"data_sources": [
|
||||
{
|
||||
"id": "products",
|
||||
"endpoint": "/api/products",
|
||||
"method": "GET"
|
||||
}
|
||||
],
|
||||
"components": [
|
||||
{
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
"className": "p-4"
|
||||
},
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
404 응답은 봉투 형식입니다 (`BaseApiController::notFound` → `templates.layout_not_found`).
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "레이아웃을 찾을 수 없습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | 토큰에 해당하는 미리보기가 없거나 만료된 경우 (`templates.layout_not_found`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -148,8 +207,8 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| templateIdentifier | path | string | 예 | — | 대상 template의 식별자 |
|
||||
| layoutName | path | string | 예 | — | 대상 layout의 이름 (식별자) |
|
||||
| templateIdentifier | path | string | 예 | — | 레이아웃을 서빙할 활성 템플릿의 식별자 (예: `sirsoft-basic`) — 미존재/비활성 시 404 |
|
||||
| layoutName | path | string | 예 | — | 서빙할 레이아웃 이름 (예: `product_list`) |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -162,17 +221,78 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 는 병합된 레이아웃 JSON 객체입니다 (상속 병합 + 모듈/플러그인 확장 적용 + 사용자별 컴포넌트 권한 필터링 완료). 실제 포함 키는 저장된 레이아웃 content 에 따라 달라집니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| version | string | `"1.0"` | 레이아웃 스키마 버전 |
|
||||
| layout_name | string | `"product_list"` | 레이아웃 이름 (식별자) |
|
||||
| extends | string\|null | `"_user_base"` | 상속한 베이스 레이아웃 이름 (서빙 시 이미 병합 반영됨) |
|
||||
| slots | object | `{"content": [ ... ]}` | 베이스 슬롯에 삽입되는 컴포넌트 배열 (extends 레이아웃) |
|
||||
| components | array | `[{"type":"basic","name":"Div", ...}]` | 렌더링할 컴포넌트 트리 (병합·확장·권한 필터 적용 결과) |
|
||||
| endpoint | string\|null | `"/api/products"` | 화면이 주로 fetch 하는 데이터 API 경로 (레거시·선택) |
|
||||
| data_sources | array | `[{"id":"products","endpoint":"/api/products","method":"GET"}]` | 화면이 로드하는 API 데이터 소스 정의 |
|
||||
| meta | object | `{"title":"상품 목록","auth_required":false}` | 메타 정보 (title, description, keywords, auth_required, is_base, guest_only, is_error_layout, error_code, seo) |
|
||||
| permissions | array\|object | `["core.templates.layouts.edit"]` | 레이아웃 접근에 필요한 권한 (flat 배열=AND, 구조화 객체=OR/AND 중첩) |
|
||||
| modals | object | `{}` | 모달 컴포넌트 정의 |
|
||||
| state / init_state / initLocal / initGlobal / initIsolated / global_state | object | `{}` | 레이아웃 레벨 초기 상태 정의 |
|
||||
| init_actions | array | `[{"handler":"apiCall", ...}]` | 레이아웃 로드 시 실행할 초기화 액션 |
|
||||
| actions / named_actions | array\|object | `{}` | 재사용 가능한 액션 정의 |
|
||||
| computed | object | `{}` | 계산된 값 정의 |
|
||||
| defines | object | `{}` | 재사용 가능한 컴포넌트 조각 정의 |
|
||||
| errorHandling | object | `{"404":{"handler":"navigate"}}` | 상태 코드별 에러 처리 정책 |
|
||||
| globalHeaders | array | `[{"pattern":"*","headers":{"X-Foo":"bar"}}]` | API 호출 시 자동 적용되는 HTTP 헤더 규칙 |
|
||||
| transition_overlay | object | `{"enabled":true,"style":"blur"}` | 페이지 전환 오버레이 설정 |
|
||||
| routes | array | `[]` | 라우트 정의 |
|
||||
| pageConfig / schema | object | `{}` | 플러그인 설정 레이아웃 전용 (설정 UI 안내/스키마) |
|
||||
| lock_version | integer | `3` | 낙관적 잠금 버전. `with_source_meta=1` 일 때만 부착 (편집기 저장 시 `expected_lock_version` 으로 되돌려 보냄) |
|
||||
| __editor | object | `{"original": { ... }}` | 자식 레이아웃의 저장 원본 content. `with_source_meta=1` 일 때만 부착 (편집기 전용) |
|
||||
| __source (각 노드 내부) | object | `{"kind":"base","layout":"_user_base"}` | 각 컴포넌트/데이터소스 노드의 출처 메타 (`base` / `extension` / `partial` / `route`). `with_source_meta=1` 일 때만 부착 |
|
||||
|
||||
응답 헤더: `ETag`(본문 md5), `Cache-Control: public, max-age=3600`, `Vary: Accept-Encoding, Accept-Language`. 클라이언트 `If-None-Match` 가 일치하면 본문 없이 `304 Not Modified` 를 반환합니다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "레이아웃이 제공되었습니다.",
|
||||
"data": {
|
||||
"version": "1.0",
|
||||
"layout_name": "product_list",
|
||||
"meta": {
|
||||
"title": "상품 목록",
|
||||
"auth_required": false
|
||||
},
|
||||
"data_sources": [
|
||||
{
|
||||
"id": "products",
|
||||
"endpoint": "/api/products",
|
||||
"method": "GET"
|
||||
}
|
||||
],
|
||||
"components": [
|
||||
{
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
"className": "p-4"
|
||||
},
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 304 | Not Modified | 요청의 `If-None-Match` 가 현재 ETag 와 일치 (본문 없음) |
|
||||
| 401 | Unauthorized | 비회원이 `permissions` 요구 레이아웃에 접근 (`auth.layout_guest_permission_denied`), 또는 비회원이 `with_source_meta=1` 요청 |
|
||||
| 403 | Forbidden | 회원이지만 레이아웃 `permissions` 미충족 (`auth.layout_permission_denied`), 또는 `with_source_meta=1` 요청 시 `core.templates.layouts.edit` 권한 없음 |
|
||||
| 404 | Not Found | 템플릿이 없거나 비활성 상태, 또는 레이아웃/부모 레이아웃 미존재 (`templates.layout_not_found`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -69,7 +69,7 @@ HTTP/1.1 200
|
||||
|
||||
**에러 응답**
|
||||
|
||||
_대표 에러 없음 (공개 조회). 인증·권한 미요구 엔드포인트로 도메인 특이 에러를 반환하지 않습니다._
|
||||
_이 엔드포인트는 도메인 에러를 반환하지 않습니다. 공개 조회이므로 인증 실패(401)가 없고, 요청 파라미터가 없어 검증 실패(422)도 발생하지 않으며, 컨트롤러(`LocaleController@active`)와 `LanguagePackService::getActiveLocales()` 경로에서 던지는 예외도 없습니다._
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+83
-5
@@ -38,11 +38,17 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "회원 탈퇴가 완료되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -135,7 +141,7 @@ _단건 응답: `data` 객체의 필드._
|
||||
| channels | array | `[{"key":"email_subscription","label":"광고성 이메일 수신","enable…` | 관리자 정의 전체 마케팅 채널 목록 (원소 key/label/enabled/terms_slug, 마케팅 플러그인 주입) |
|
||||
| consent_histories | array | `[]` | 동의 변경 이력 (원소 channel_key/action/source/created_at, 마케팅 플러그인 주입) |
|
||||
| ecommerce_mileage | object | `{"enabled":false}` | 마일리지 정보 (enabled: 기능 활성 여부, 잔액, 이커머스 모듈 주입) |
|
||||
| ecommerce_preferred_currency | null | `null` | 선호 결제 통화 (이커머스 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_currency | string | `KRW` | 선호 결제 통화 (이커머스 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country | null | `null` | 선호 배송 국가 코드 (이커머스 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country_name | null | `null` | 선호 배송 국가 이름 (코드 파생, 이커머스 모듈 주입, 미설정 시 null) |
|
||||
|
||||
@@ -309,11 +315,83 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`UserResource::toArray()` 산물 — GET /api/me 의 `toProfileArray()` 와 필드 구성이 다르다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `홍길동` | 사용자 이름 |
|
||||
| nickname | string\|null | `gildong` | 닉네임 |
|
||||
| email | string | `user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 아바타 이미지 URL (`User::getAvatarUrl()` 산물, 미등록 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 (ko: 한국어, en: 영어) |
|
||||
| language_label | string\|null | `한국어` | 언어 코드의 다국어 라벨 (`user.language.{code}` 번역문) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (active, inactive, blocked, withdrawn, pending_verification) |
|
||||
| status_label | string\|null | `활성` | 상태의 사람이 읽는 라벨 (UserStatus::label() 산물) |
|
||||
| status_variant | string\|null | `success` | 상태 표시 색상/스타일 변형 키 (UserStatus::variant() 산물 — UI 배지용) |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 (`User::isAdmin()` — 역할 관계 기반 파생) |
|
||||
| homepage | string\|null | `https://example.com` | 홈페이지 URL |
|
||||
| mobile | string\|null | `010-1234-5678` | 휴대폰 번호 |
|
||||
| phone | string\|null | `02-123-4567` | 전화번호 |
|
||||
| zipcode | string\|null | `06234` | 우편번호 |
|
||||
| address | string\|null | `서울특별시 강남구 테헤란로 1` | 기본 주소 |
|
||||
| address_detail | string\|null | `101동 202호` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `2026-07-07 10:41:24` | 마지막 로그인 일시 (사용자 시간대 기준 문자열) |
|
||||
| email_verified_at | string\|null | `null` | 이메일 인증 일시 (미인증 시 null) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 (예: Asia/Seoul, UTC) |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 (사용자 시간대 기준 문자열) |
|
||||
| updated_at | string | `2026-07-08 11:02:10` | 수정 일시 (사용자 시간대 기준 문자열) |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":false,"can_create":false,"can_update":false,"can_delete":false,"can_assign_roles":false}` | 현재 사용자의 이 리소스에 대한 권한 맵 (core.users.read/create/update/delete, core.permissions.update 기준. 슈퍼관리자 계정은 `can_delete` 가 항상 false) |
|
||||
|
||||
관계형 필드(`modules`, `plugins`, `menus`, `roles`, `permissions`, `consents`, `terms_consent`, `privacy_consent`)와 카운트 필드(`modules_count`, `plugins_count`, `menus_count`)는 해당 관계가 로드된 경우에만 응답에 포함된다 (프로필 수정 응답에서는 로드하지 않으므로 나타나지 않는다).
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용자 정보가 성공적으로 업데이트되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "예시 이름",
|
||||
"nickname": "예시 이름",
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"language_label": "한국어",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": false,
|
||||
"homepage": "https://example.com",
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": "010-1234-5678",
|
||||
"zipcode": "06234",
|
||||
"address": "서울특별시 강남구 테헤란로 1",
|
||||
"address_detail": "서울특별시 강남구 테헤란로 1",
|
||||
"signature": "예시값",
|
||||
"bio": "예시 내용입니다.",
|
||||
"last_login_at": "2026-07-07 10:41:24",
|
||||
"email_verified_at": null,
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 11:02:10",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": false,
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false,
|
||||
"can_assign_roles": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
|
||||
+200
-19
@@ -324,7 +324,7 @@ HTTP/1.1 201
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.create`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -448,6 +448,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -480,11 +481,94 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_목록 응답: `data.data[]` 배열 항목의 필드 + 컬렉션 레벨 `data.abilities`._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `15` | 기본 키 (내부 식별자) |
|
||||
| name | object | `{"ko":"게시판 관리","en":"Board Management"}` | 메뉴 이름 (다국어 JSON) |
|
||||
| slug | string | `sirsoft-board` | 메뉴 슬러그 |
|
||||
| url | string \| null | `null` | 메뉴 URL (그룹 메뉴는 null) |
|
||||
| icon | string \| null | `fas fa-clipboard-list` | 메뉴 아이콘 (Font Awesome 클래스) |
|
||||
| order | integer | `30` | 메뉴 순서 (작을수록 우선 — `order` 오름차순 정렬) |
|
||||
| is_active | boolean | `true` | 활성 여부 |
|
||||
| parent_id | integer \| null | `null` | 상위 메뉴 ID (최상위는 null) |
|
||||
| extension_type | string | `module` | 확장 소유 타입 (`module` / `plugin`) |
|
||||
| extension_identifier | string | `sirsoft-board` | 확장 식별자 (요청 path 의 `identifier` 와 동일) |
|
||||
| parent | object \| null | `null` | 상위 항목 객체 (id/name/url/icon — parent 관계 파생) |
|
||||
| children | array | `[{"id":16,"name":{"ko":"환경설정"},"slug":"sirsoft-board-settings", ...}]` | 하위 메뉴 배열 (order 오름차순 — children 관계 파생) |
|
||||
| creator | object \| null | `null` | 생성자 정보 객체 (uuid/name/email — creator 관계 파생) |
|
||||
| created_at | string | `2026-07-08 10:44:35` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 10:44:35` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `false` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
> `roles` 관계는 이 엔드포인트에서 eager-load 되지 않으므로(`MenuRepository::getMenusByExtension` 은 `creator`/`parent`/`children` 만 로드) 항목에 `roles` 키가 포함되지 않습니다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메뉴를 성공적으로 가져왔습니다.",
|
||||
"data": {
|
||||
"data": [
|
||||
{
|
||||
"id": 15,
|
||||
"name": {
|
||||
"ko": "게시판 관리",
|
||||
"en": "Board Management"
|
||||
},
|
||||
"slug": "sirsoft-board",
|
||||
"url": null,
|
||||
"icon": "fas fa-clipboard-list",
|
||||
"order": 30,
|
||||
"is_active": true,
|
||||
"parent_id": null,
|
||||
"extension_type": "module",
|
||||
"extension_identifier": "sirsoft-board",
|
||||
"parent": null,
|
||||
"children": [
|
||||
{
|
||||
"id": 16,
|
||||
"name": {
|
||||
"ko": "환경설정",
|
||||
"en": "Settings"
|
||||
},
|
||||
"slug": "sirsoft-board-settings",
|
||||
"url": "/admin/boards/settings",
|
||||
"icon": "fas fa-cog",
|
||||
"order": 1,
|
||||
"is_active": true,
|
||||
"parent_id": 15,
|
||||
"extension_type": "module",
|
||||
"extension_identifier": "sirsoft-board",
|
||||
"roles": []
|
||||
}
|
||||
],
|
||||
"creator": null,
|
||||
"created_at": "2026-07-08 10:44:35",
|
||||
"updated_at": "2026-07-08 10:44:35",
|
||||
"is_owner": false,
|
||||
"abilities": {
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"abilities": {
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -493,6 +577,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -587,6 +672,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -635,19 +721,29 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success('menu.order_update_success')` 를 데이터 없이 호출)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메뉴 순서가 성공적으로 업데이트되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). `moved_items[].new_parent_id` 가 자기 자신·자손을 가리키는 순환 참조인 경우 포함 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -671,7 +767,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/menus/1 HTTP/1.1
|
||||
DELETE /api/admin/menus/{menu} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -679,19 +775,32 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success('menu.delete_success')` 를 데이터 없이 호출)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
<!-- @probed -->
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메뉴가 성공적으로 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -715,7 +824,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/menus/1 HTTP/1.1
|
||||
GET /api/admin/menus/{menu} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -852,6 +961,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -887,7 +997,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/menus/1 HTTP/1.1
|
||||
PUT /api/admin/menus/{menu} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -911,20 +1021,90 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (갱신된 메뉴를 `MenuResource` 로 반환 — `creator`/`parent`/`children`/`roles` eager-load)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| name | object | `{"ko":"API 문서 샘플 메뉴","en":"API Doc Sample Menu"}` | 메뉴 이름 (다국어 JSON) |
|
||||
| slug | string | `apidoc-sample-menu` | 메뉴 슬러그 |
|
||||
| url | string \| null | `/admin/apidoc-sample` | 메뉴 URL |
|
||||
| icon | string \| null | `fas fa-book` | 메뉴 아이콘 |
|
||||
| order | integer | `35` | 메뉴 순서 |
|
||||
| is_active | boolean | `true` | 활성 여부 |
|
||||
| parent_id | integer \| null | `null` | 상위 메뉴 ID |
|
||||
| extension_type | string \| null | `core` | 확장 소유 타입: core / module / plugin / null(사용자 정의) |
|
||||
| extension_identifier | string \| null | `core` | 확장 식별자 |
|
||||
| parent | object \| null | `null` | 상위 항목 객체 (id/name/url/icon — parent 관계 파생) |
|
||||
| children | array | `[]` | 하위 항목 배열 (order 오름차순 — children 관계 파생) |
|
||||
| creator | object \| null | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자","email":"apidoc-sample-user@example.com"}` | 생성자 정보 객체 (creator 관계 파생) |
|
||||
| roles | array | `[{"id":1,"name":{"ko":"관리자","en":"Administrator"},"permission_type":"read"}]` | 이 메뉴 노출이 허용된 역할 목록 (요청 `roles` 로 교체된 결과) |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 12:20:11` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_create":true,"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메뉴가 성공적으로 업데이트되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"name": {
|
||||
"ko": "API 문서 샘플 메뉴",
|
||||
"en": "API Doc Sample Menu"
|
||||
},
|
||||
"slug": "apidoc-sample-menu",
|
||||
"url": "/admin/apidoc-sample",
|
||||
"icon": "fas fa-book",
|
||||
"order": 35,
|
||||
"is_active": true,
|
||||
"parent_id": null,
|
||||
"extension_type": null,
|
||||
"extension_identifier": null,
|
||||
"parent": null,
|
||||
"children": [],
|
||||
"creator": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com"
|
||||
},
|
||||
"roles": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": {
|
||||
"ko": "관리자",
|
||||
"en": "Administrator"
|
||||
},
|
||||
"permission_type": "read"
|
||||
}
|
||||
],
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 12:20:11",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -950,7 +1130,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/admin/menus/1/toggle-status HTTP/1.1
|
||||
PATCH /api/admin/menus/{menu}/toggle-status HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1018,8 +1198,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.menus.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+796
-82
File diff suppressed because it is too large.
Load diff
@@ -146,7 +146,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/notification-definitions/1 HTTP/1.1
|
||||
GET /api/admin/notification-definitions/{definition} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -323,6 +323,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -349,7 +350,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/notification-definitions/1 HTTP/1.1
|
||||
PUT /api/admin/notification-definitions/{definition} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -368,20 +369,104 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드. 수정된 알림 정의를 `templates` 관계와 함께 반환합니다 (`NotificationDefinitionResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| type | string | `apidoc-sample.event` | 알림 타입 (welcome, order_confirmed 등) |
|
||||
| hook_prefix | string | `core` | 훅 접두사 (core.auth, sirsoft-ecommerce 등) |
|
||||
| extension_type | string | `core` | 이 정의를 소유한 확장의 타입 (core/module/plugin) |
|
||||
| extension_identifier | string | `` | 이 정의를 소유한 확장의 식별자 (코어는 빈 문자열) |
|
||||
| name | object | `{"ko":"API 문서 샘플 알림","en":"API Doc Sample Notification"}` | 다국어 이름 (로케일별 값 객체) |
|
||||
| description | object | `{"ko":"문서 실측용 알림 정의","en":"Sample notification"}` | 다국어 설명 (로케일별 값 객체) |
|
||||
| variables | array | `[]` | 사용 가능 변수 메타데이터 ([{key, description}]) |
|
||||
| channels | array | `["database","mail"]` | 수정 후의 활성 채널 (["mail", "database"]) |
|
||||
| hooks | array | `[]` | 수정 후의 트리거 훅 목록 (["core.auth.after_register"]) |
|
||||
| is_active | boolean | `true` | active 여부 |
|
||||
| is_default | boolean | `false` | default 여부 (사용자 수정 시 false) |
|
||||
| templates | array | `[{"id":1,"definition_id":1,"channel":"mail", ...}]` | 채널별 알림 템플릿 목록 (`templates` 관계를 로드해 반환 — NotificationTemplateResource 배열) |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 12:14:43` | 최종 수정 일시 |
|
||||
| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update/can_delete — 모두 `core.settings.update` 기준) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림 정의가 수정되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"type": "apidoc-sample.event",
|
||||
"hook_prefix": "core",
|
||||
"extension_type": "core",
|
||||
"extension_identifier": "",
|
||||
"name": {
|
||||
"ko": "API 문서 샘플 알림",
|
||||
"en": "API Doc Sample Notification"
|
||||
},
|
||||
"description": {
|
||||
"ko": "문서 실측용 알림 정의",
|
||||
"en": "Sample notification"
|
||||
},
|
||||
"variables": [],
|
||||
"channels": [
|
||||
"database",
|
||||
"mail"
|
||||
],
|
||||
"hooks": [],
|
||||
"is_active": true,
|
||||
"is_default": false,
|
||||
"templates": [
|
||||
{
|
||||
"id": 1,
|
||||
"definition_id": 1,
|
||||
"channel": "mail",
|
||||
"subject": "API 문서 샘플 템플릿 제목",
|
||||
"body": "안녕하세요 {{name}} 님, 문서 실측용 본문입니다.",
|
||||
"click_url": "/admin/apidoc-sample",
|
||||
"recipients": [
|
||||
{
|
||||
"type": "role",
|
||||
"value": "admin",
|
||||
"display_name": "관리자"
|
||||
}
|
||||
],
|
||||
"is_active": true,
|
||||
"is_default": false,
|
||||
"user_overrides": null,
|
||||
"updated_by": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 10:41:24",
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 12:14:43",
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -403,7 +488,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/admin/notification-definitions/1/reset HTTP/1.1
|
||||
POST /api/admin/notification-definitions/{definition}/reset HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -578,8 +663,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -601,7 +687,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/admin/notification-definitions/1/toggle-active HTTP/1.1
|
||||
PATCH /api/admin/notification-definitions/{definition}/toggle-active HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -711,8 +797,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -208,18 +208,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| deleted_count | integer | `3` | 실제로 삭제된 알림 발송 이력 건수 (요청한 `ids` 중 존재하는 행만 카운트) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "선택한 알림 발송 이력이 삭제되었습니다.",
|
||||
"data": {
|
||||
"deleted_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notification-logs.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notification-logs.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -242,7 +258,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/notification-logs/1 HTTP/1.1
|
||||
DELETE /api/admin/notification-logs/{notificationLog} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -250,9 +266,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success(__('notification_log.delete_success'))` 만 호출하므로 `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -273,8 +287,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notification-logs.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notification-logs.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -55,11 +55,25 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| subject | string | `[사이트명] 회원가입을 환영합니다` | 요청 `locale`(미지정 시 현재 앱 로케일) 의 제목에서 `{변수}` 를 정의(`definition_id`)의 변수 설명(`[설명]`)으로 치환한 결과 |
|
||||
| body | string | `<h1>[회원 이름]님, 환영합니다!</h1>...` | 동일 로케일 본문에서 `{변수}` 를 정의의 변수 설명으로 치환한 결과. 해당 로케일 값이 없으면 빈 문자열 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "미리보기를 생성했습니다.",
|
||||
"data": {
|
||||
"subject": "[사이트명] 회원가입을 환영합니다",
|
||||
"body": "<h1>[회원 이름]님, 환영합니다!</h1><p>[사이트명]에 가입해 주셔서 감사합니다.</p>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -96,7 +110,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/notification-templates/1 HTTP/1.1
|
||||
PUT /api/admin/notification-templates/{template} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -119,20 +133,76 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`NotificationTemplateResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| definition_id | integer | `1` | 소속 알림 정의 식별자 |
|
||||
| channel | string | `mail` | 발송 채널 (`mail`, `database`, `fcm`) |
|
||||
| subject | object | `{"ko":"[{app_name}] 회원가입을 환영합니다","en":"..."}` | 다국어 제목 (로케일 키 → 문자열, 로케일당 최대 500자) |
|
||||
| body | object | `{"ko":"<h1>{name}님, 환영합니다!</h1>...","en":"..."}` | 다국어 본문 (로케일 키 → 문자열, 로케일당 최대 65535자) |
|
||||
| click_url | string \| null | `null` | 알림 클릭 시 이동할 대상 URL (미설정 시 `null`) |
|
||||
| recipients | array | `[{"type":"role","value":"admin","display_name":"관리자"}]` | 수신자 규칙 목록. `type` 은 `trigger_user`/`related_user`/`role`/`specific_users`. `role` 이면 `display_name`, `specific_users` 면 `display_names` 가 표시용으로 부가됨 |
|
||||
| is_active | boolean | `true` | 활성 여부 (false 면 해당 채널 발송 중단) |
|
||||
| is_default | boolean | `false` | 기본값 상태 여부 (수정 시 항상 `false` 로 전환됨) |
|
||||
| user_overrides | array \| null | `["subject","body"]` | 사용자가 직접 수정한 필드명 목록 (`HasUserOverrides`) |
|
||||
| updated_by | string \| null | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 최종 수정한 사용자 UUID (없으면 `null`) |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 12:14:43` | 최종 수정 일시 |
|
||||
| abilities | object | `{"can_update":true,"can_delete":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (모두 `core.settings.update` 권한 기반) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림 템플릿이 수정되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"definition_id": 1,
|
||||
"channel": "mail",
|
||||
"subject": {
|
||||
"ko": "[{app_name}] 회원가입을 환영합니다",
|
||||
"en": "[{app_name}] Welcome to Our Service"
|
||||
},
|
||||
"body": {
|
||||
"ko": "<h1>{name}님, 환영합니다!</h1>",
|
||||
"en": "<h1>Welcome, {name}!</h1>"
|
||||
},
|
||||
"click_url": "/admin/notifications",
|
||||
"recipients": [
|
||||
{
|
||||
"type": "role",
|
||||
"value": "admin",
|
||||
"display_name": "관리자"
|
||||
}
|
||||
],
|
||||
"is_active": true,
|
||||
"is_default": false,
|
||||
"user_overrides": [
|
||||
"subject",
|
||||
"body"
|
||||
],
|
||||
"updated_by": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 12:14:43",
|
||||
"abilities": {
|
||||
"can_update": true,
|
||||
"can_delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -154,7 +224,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/admin/notification-templates/1/reset HTTP/1.1
|
||||
POST /api/admin/notification-templates/{template}/reset HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -183,6 +253,8 @@ _단건 응답: `data` 객체의 필드._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- @probed -->
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
@@ -230,8 +302,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -253,7 +326,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/admin/notification-templates/1/toggle-active HTTP/1.1
|
||||
PATCH /api/admin/notification-templates/{template}/toggle-active HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -331,8 +404,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -49,16 +49,16 @@ _목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| number | integer | `23` | 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
|
||||
| id | string | `518b9c94-5853-4b68-8193-83af1851bbc6` | 기본 키 (내부 식별자) |
|
||||
| type | string | `inquiry_received` | <!-- TODO: 설명 --> |
|
||||
| type_label | string | `상품 문의 접수` | `type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
|
||||
| subject | string | `새로운 상품 문의가 접수되었습니다` | <!-- TODO: 설명 --> |
|
||||
| body | string | `옥혜진님이 "면 손수건 3매입 #1" 상품에 문의를 남겼습니다.` | <!-- TODO: 설명 --> |
|
||||
| url | string | `https://g7_2.dev/admin/ecommerce/prod…` | <!-- TODO: 설명 --> |
|
||||
| data | object | `{"type":"inquiry_received","subject":"새로운 상품 문의가 접수되었습니다"…` | <!-- TODO: 설명 --> |
|
||||
| read_at | string | `2026-07-31 22:06:53` | read 일시 |
|
||||
| created_at | string | `2026-07-31 21:41:58` | 생성 일시 |
|
||||
| number | integer | `92` | 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
|
||||
| id | string | `02ee1121-ec63-4812-b77a-a0ffb4040acb` | 기본 키 (내부 식별자) |
|
||||
| type | string | `new_order_admin` | 알림 유형 식별자 (알림 정의의 type — 발송 트리거를 구분) |
|
||||
| type_label | string | `신규 주문 관리자 알림` | `type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
|
||||
| subject | string | `새로운 주문이 접수되었습니다` | 알림 제목 (알림 템플릿의 subject 를 변수 치환해 렌더한 문자열) |
|
||||
| body | string | `소경은님이 주문번호 20260713-0038038875 (결제금액:…` | 알림 본문 (알림 템플릿의 body 를 변수 치환해 렌더한 문자열) |
|
||||
| url | string | `https://g7.dev/admin/ecommerce/orders…` | 알림 클릭 시 이동할 URL (템플릿의 click_url 우선, 없으면 메일 CTA action_url) |
|
||||
| data | object | `{"type":"new_order_admin","subject":"새로운 주문이 접수되었습니다","bo…` | 알림 원본 페이로드 객체 (type/subject/body/click_url 과 발송 시 전달된 변수 data 를 포함) |
|
||||
| read_at | null | `null` | read 일시 |
|
||||
| created_at | string | `2026-07-13 09:38:04` | 생성 일시 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -202,7 +202,8 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -259,7 +260,8 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -300,18 +302,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| marked_count | integer | `2` | 실제로 읽음 처리된 알림 건수 (요청한 `ids` 중 본인 소유이면서 미읽음 상태였던 항목만 집계) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림을 읽음 처리했습니다.",
|
||||
"data": {
|
||||
"marked_count": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -370,6 +388,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -401,19 +420,30 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림이 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -445,19 +475,60 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (읽음 처리 후 갱신된 알림 1건 — `UserNotificationResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | string | `02ee1121-ec63-4812-b77a-a0ffb4040acb` | 알림 기본 키 (UUID) |
|
||||
| type | string | `new_order_admin` | 알림 유형 식별자 (알림 정의의 type — 발송 트리거를 구분) |
|
||||
| type_label | string | `신규 주문 관리자 알림` | `type` 값의 사람이 읽는 라벨 (알림 정의의 현지화 이름, 정의 미존재 시 빈 문자열) |
|
||||
| subject | string | `새로운 주문이 접수되었습니다` | 알림 제목 (알림 템플릿의 subject 를 변수 치환해 렌더한 문자열) |
|
||||
| body | string | `소경은님이 주문번호 20260713-0038038875 (결제금액:…` | 알림 본문 (알림 템플릿의 body 를 변수 치환해 렌더한 문자열) |
|
||||
| url | string \| null | `https://g7.dev/admin/ecommerce/orders/1` | 알림 클릭 시 이동할 URL (템플릿의 `click_url` 우선, 없으면 메일 CTA `action_url`, 둘 다 없으면 `null`) |
|
||||
| data | object | `{"type":"new_order_admin","subject":"...","body":"...","click_url":"..."}` | 알림 원본 페이로드 객체 (type/subject/body/click_url 과 발송 시 전달된 변수 data 를 포함) |
|
||||
| read_at | string \| null | `2026-07-13 09:40:11` | 읽음 처리 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) — 이 엔드포인트 성공 시 항상 값이 채워짐 |
|
||||
| created_at | string \| null | `2026-07-13 09:38:04` | 알림 생성 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림을 읽음 처리했습니다.",
|
||||
"data": {
|
||||
"id": "02ee1121-ec63-4812-b77a-a0ffb4040acb",
|
||||
"type": "new_order_admin",
|
||||
"type_label": "신규 주문 관리자 알림",
|
||||
"subject": "새로운 주문이 접수되었습니다",
|
||||
"body": "소경은님이 주문번호 20260713-0038038875 주문을 접수했습니다.",
|
||||
"url": "https://g7.dev/admin/ecommerce/orders/1",
|
||||
"data": {
|
||||
"type": "new_order_admin",
|
||||
"subject": "새로운 주문이 접수되었습니다",
|
||||
"body": "소경은님이 주문번호 20260713-0038038875 주문을 접수했습니다.",
|
||||
"click_url": "https://g7.dev/admin/ecommerce/orders/1",
|
||||
"data": {
|
||||
"action_url": "https://g7.dev/admin/ecommerce/orders/1"
|
||||
}
|
||||
},
|
||||
"read_at": "2026-07-13 09:40:11",
|
||||
"created_at": "2026-07-13 09:38:04"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -498,16 +569,16 @@ _목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| number | integer | `23` | 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
|
||||
| id | string | `518b9c94-5853-4b68-8193-83af1851bbc6` | 기본 키 (내부 식별자) |
|
||||
| type | string | `inquiry_received` | <!-- TODO: 설명 --> |
|
||||
| type_label | string | `상품 문의 접수` | `type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
|
||||
| subject | string | `새로운 상품 문의가 접수되었습니다` | <!-- TODO: 설명 --> |
|
||||
| body | string | `옥혜진님이 "면 손수건 3매입 #1" 상품에 문의를 남겼습니다.` | <!-- TODO: 설명 --> |
|
||||
| url | string | `https://g7_2.dev/admin/ecommerce/prod…` | <!-- TODO: 설명 --> |
|
||||
| data | object | `{"type":"inquiry_received","subject":"새로운 상품 문의가 접수되었습니다"…` | <!-- TODO: 설명 --> |
|
||||
| read_at | string | `2026-07-31 22:06:53` | read 일시 |
|
||||
| created_at | string | `2026-07-31 21:41:58` | 생성 일시 |
|
||||
| number | integer | `92` | 목록에서의 순번 (페이지네이션 반영 행 번호 — HasRowNumber 파생) |
|
||||
| id | string | `02ee1121-ec63-4812-b77a-a0ffb4040acb` | 기본 키 (내부 식별자) |
|
||||
| type | string | `new_order_admin` | 알림 유형 식별자 (알림 정의의 type — 발송 트리거를 구분) |
|
||||
| type_label | string | `신규 주문 관리자 알림` | `type` 값의 사람이 읽는 라벨 (현지화/Enum 파생) |
|
||||
| subject | string | `새로운 주문이 접수되었습니다` | 알림 제목 (알림 템플릿의 subject 를 변수 치환해 렌더한 문자열) |
|
||||
| body | string | `소경은님이 주문번호 20260713-0038038875 (결제금액:…` | 알림 본문 (알림 템플릿의 body 를 변수 치환해 렌더한 문자열) |
|
||||
| url | string | `https://g7.dev/admin/ecommerce/orders…` | 알림 클릭 시 이동할 URL (템플릿의 click_url 우선, 없으면 메일 CTA action_url) |
|
||||
| data | object | `{"type":"new_order_admin","subject":"새로운 주문이 접수되었습니다","bo…` | 알림 원본 페이로드 객체 (type/subject/body/click_url 과 발송 시 전달된 변수 data 를 포함) |
|
||||
| read_at | null | `null` | read 일시 |
|
||||
| created_at | string | `2026-07-13 09:38:04` | 생성 일시 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -592,7 +663,8 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.read`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -649,7 +721,9 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.delete`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -705,7 +779,9 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.update`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -746,17 +822,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| marked_count | integer | `2` | 실제로 읽음 처리된 알림 건수 (요청한 `ids` 중 본인 소유이면서 미읽음 상태였던 항목만 집계) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림을 읽음 처리했습니다.",
|
||||
"data": {
|
||||
"marked_count": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.update`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -813,7 +906,9 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.read`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -845,18 +940,30 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림이 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.delete`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -888,18 +995,60 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (읽음 처리 후 갱신된 알림 1건 — `UserNotificationResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | string | `9f2c1a44-1b6e-4a55-8b0e-4c8a3f1d90ab` | 알림 기본 키 (UUID) |
|
||||
| type | string | `order_shipped` | 알림 유형 식별자 (알림 정의의 type — 발송 트리거를 구분) |
|
||||
| type_label | string | `배송 시작 알림` | `type` 값의 사람이 읽는 라벨 (알림 정의의 현지화 이름, 정의 미존재 시 빈 문자열) |
|
||||
| subject | string | `주문하신 상품이 발송되었습니다` | 알림 제목 (알림 템플릿의 subject 를 변수 치환해 렌더한 문자열) |
|
||||
| body | string | `주문번호 20260713-0038038875 상품이 발송되었습니다.` | 알림 본문 (알림 템플릿의 body 를 변수 치환해 렌더한 문자열) |
|
||||
| url | string \| null | `https://g7.dev/mypage/orders/1` | 알림 클릭 시 이동할 URL (템플릿의 `click_url` 우선, 없으면 메일 CTA `action_url`, 둘 다 없으면 `null`) |
|
||||
| data | object | `{"type":"order_shipped","subject":"...","body":"...","click_url":"..."}` | 알림 원본 페이로드 객체 (type/subject/body/click_url 과 발송 시 전달된 변수 data 를 포함) |
|
||||
| read_at | string \| null | `2026-07-13 10:02:33` | 읽음 처리 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) — 이 엔드포인트 성공 시 항상 값이 채워짐 |
|
||||
| created_at | string \| null | `2026-07-13 09:58:12` | 알림 생성 일시 (사용자 타임존 기준 `Y-m-d H:i:s`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "알림을 읽음 처리했습니다.",
|
||||
"data": {
|
||||
"id": "9f2c1a44-1b6e-4a55-8b0e-4c8a3f1d90ab",
|
||||
"type": "order_shipped",
|
||||
"type_label": "배송 시작 알림",
|
||||
"subject": "주문하신 상품이 발송되었습니다",
|
||||
"body": "주문번호 20260713-0038038875 상품이 발송되었습니다.",
|
||||
"url": "https://g7.dev/mypage/orders/1",
|
||||
"data": {
|
||||
"type": "order_shipped",
|
||||
"subject": "주문하신 상품이 발송되었습니다",
|
||||
"body": "주문번호 20260713-0038038875 상품이 발송되었습니다.",
|
||||
"click_url": "https://g7.dev/mypage/orders/1",
|
||||
"data": {
|
||||
"action_url": "https://g7.dev/mypage/orders/1"
|
||||
}
|
||||
},
|
||||
"read_at": "2026-07-13 10:02:33",
|
||||
"created_at": "2026-07-13 09:58:12"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.user-notifications.update`)이 없는 경우 |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.notifications.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -51,11 +51,17 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "비밀번호가 성공적으로 변경되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
|
||||
+833
-86
File diff suppressed because it is too large.
Load diff
+243
-10
@@ -38,11 +38,75 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`UserResource::toProfileArray()` 산물)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a231747f-e82e-4cf2-9ae1-a261849dce40` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `홍길동` | 사용자 이름 |
|
||||
| nickname | string\|null | `gildong` | 닉네임 (미설정 시 null) |
|
||||
| email | string | `user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 아바타 이미지 URL (`User::getAvatarUrl()` 산물, 미등록 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 (`config('app.supported_locales')` 값 — 기본 `ko`, `en`) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 식별자 |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (`active`, `inactive`, `blocked`, `withdrawn`, `pending_verification`) |
|
||||
| status_label | string\|null | `활성` | 상태의 다국어 라벨 (`UserStatus::label()` 산물) |
|
||||
| status_variant | string\|null | `success` | 상태 배지 색상 키 (`success`/`secondary`/`danger`/`warning`/`info`) |
|
||||
| homepage | string\|null | `https://example.com` | 홈페이지 URL |
|
||||
| mobile | string\|null | `010-1234-5678` | 휴대전화 번호 |
|
||||
| phone | string\|null | `02-123-4567` | 전화번호 |
|
||||
| zipcode | string\|null | `06234` | 우편번호 |
|
||||
| address | string\|null | `서울특별시 강남구 테헤란로 1` | 기본 주소 |
|
||||
| address_detail | string\|null | `101동 202호` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 게시글 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| is_super | boolean | `false` | 슈퍼관리자 여부 (`User::isSuperAdmin()` 파생) |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 (`User::isAdmin()` 파생) |
|
||||
| withdrawn_at | string\|null | `null` | 탈퇴 처리 일시 (사용자 시간대 기준) |
|
||||
| last_login_at | string\|null | `2026-07-05 19:15:16` | 마지막 로그인 일시 (사용자 시간대 기준) |
|
||||
| last_login_human | string\|null | `1일 전` | 마지막 로그인 시각의 상대 표현 (`diffForHumans()` 산물) |
|
||||
| created_at | string\|null | `2026-07-06 19:15:16` | 가입 일시 (사용자 시간대 기준) |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
|
||||
> 위 필드에 더해 `core.user.filter_resource_data` 훅으로 확장 소유 필드가 병합된다 (게시판 모듈 `notify_*`, 마케팅 플러그인 `marketing_consent*`/`email_subscription*`/`third_party_consent*`/`info_disclosure*`/`channels`/`consent_histories`, 이커머스 모듈 `ecommerce_*`). 전체 목록은 `GET /api/me` 문서 참조.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "프로필 정보를 성공적으로 가져왔습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "홍길동",
|
||||
"nickname": "gildong",
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"timezone": "Asia/Seoul",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"homepage": null,
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": null,
|
||||
"zipcode": "06234",
|
||||
"address": "서울특별시 강남구 테헤란로 1",
|
||||
"address_detail": "101동 202호",
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"is_super": false,
|
||||
"is_admin": false,
|
||||
"withdrawn_at": null,
|
||||
"last_login_at": "2026-07-05 19:15:16",
|
||||
"last_login_human": "1일 전",
|
||||
"created_at": "2026-07-06 19:15:16",
|
||||
"is_owner": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -133,17 +197,89 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`UserResource::toArray()` 산물 — `show` 의 `toProfileArray()` 와 필드 구성이 다르다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID |
|
||||
| name | string | `홍길동` | 사용자 이름 |
|
||||
| nickname | string\|null | `gildong` | 닉네임 |
|
||||
| email | string | `user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 아바타 이미지 URL (미등록 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 |
|
||||
| language_label | string\|null | `한국어` | 언어의 다국어 라벨 (`user.language.{code}` 번역) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (`active`, `inactive`, `blocked`, `withdrawn`, `pending_verification`) |
|
||||
| status_label | string\|null | `활성` | 상태의 다국어 라벨 |
|
||||
| status_variant | string\|null | `success` | 상태 배지 색상 키 (`success`/`secondary`/`danger`/`warning`/`info`) |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 |
|
||||
| homepage | string\|null | `https://example.com` | 홈페이지 URL |
|
||||
| mobile | string\|null | `010-1234-5678` | 휴대전화 번호 |
|
||||
| phone | string\|null | `02-123-4567` | 전화번호 |
|
||||
| zipcode | string\|null | `06234` | 우편번호 |
|
||||
| address | string\|null | `서울특별시 강남구 테헤란로 1` | 기본 주소 |
|
||||
| address_detail | string\|null | `101동 202호` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 게시글 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `2026-07-05 19:15:16` | 마지막 로그인 일시 (사용자 시간대 기준) |
|
||||
| email_verified_at | string\|null | `null` | 이메일 인증 완료 일시 (미인증 시 null) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 식별자 |
|
||||
| created_at | string\|null | `2026-07-06 19:15:16` | 가입 일시 |
|
||||
| updated_at | string\|null | `2026-07-08 10:41:24` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
| abilities | object | `{"can_read":true,"can_update":true,...}` | 현재 사용자의 리소스 권한 맵 (`can_read`/`can_create`/`can_update`/`can_delete`/`can_assign_roles`) |
|
||||
|
||||
> `modules_count`/`plugins_count`/`menus_count`·`modules`/`plugins`/`menus`/`roles`/`permissions`/`consents`/`terms_consent`/`privacy_consent` 는 해당 관계가 로드된 경우에만 포함된다 (프로필 수정 응답에서는 로드되지 않아 생략). 확장 소유 필드는 `core.user.filter_resource_data` 훅으로 병합된다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용자 정보가 성공적으로 업데이트되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "홍길동",
|
||||
"nickname": "gildong",
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"language_label": "한국어",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": false,
|
||||
"homepage": null,
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": null,
|
||||
"zipcode": "06234",
|
||||
"address": "서울특별시 강남구 테헤란로 1",
|
||||
"address_detail": "101동 202호",
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"last_login_at": "2026-07-05 19:15:16",
|
||||
"email_verified_at": null,
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-06 19:15:16",
|
||||
"updated_at": "2026-07-08 10:41:24",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": false,
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false,
|
||||
"can_assign_roles": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 403 | Forbidden | 요구 권한(`core.profile.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.profile.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -174,11 +310,38 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체에 `activities` 배열이 담긴다 (페이지네이션 없음, 최신순 최대 50건)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| activities | array | `[{...}]` | 최근 활동 로그 목록 (최신순, 최대 50건) |
|
||||
| activities[].id | integer | `1` | 활동 로그 기본 키 |
|
||||
| activities[].action | string | `profile.update` | 활동 액션 키 (점 표기, 예: `profile.show`, `profile.update`, `auth.login`) |
|
||||
| activities[].action_label | string | `프로필 수정` | 액션의 다국어 라벨 (`activity_log.action.*` 번역, 확장 액션은 확장 lang 우선) |
|
||||
| activities[].description | string | `프로필 정보를 수정했습니다.` | 활동 설명 (현재 로케일 기준 렌더 결과, `description_key` 미설정 시 빈 문자열) |
|
||||
| activities[].ip_address | string\|null | `127.0.0.1` | 활동을 수행한 클라이언트 IP |
|
||||
| activities[].created_at | string\|null | `2026-07-06T19:15:16+09:00` | 활동 발생 일시 (ISO 8601) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "활동 기록을 성공적으로 가져왔습니다.",
|
||||
"data": {
|
||||
"activities": [
|
||||
{
|
||||
"id": 1024,
|
||||
"action": "profile.update",
|
||||
"action_label": "프로필 수정",
|
||||
"description": "프로필 정보를 수정했습니다.",
|
||||
"ip_address": "127.0.0.1",
|
||||
"created_at": "2026-07-06T19:15:16+09:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -214,17 +377,87 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`UserResource::toArray()` 산물 — `PUT /api/user/profile` 응답과 동일 구조)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID |
|
||||
| name | string | `홍길동` | 사용자 이름 |
|
||||
| nickname | string\|null | `gildong` | 닉네임 |
|
||||
| email | string | `user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 아바타 이미지 URL |
|
||||
| language | string | `en` | 변경된 사용자 언어 설정 |
|
||||
| language_label | string\|null | `English` | 언어의 다국어 라벨 (`user.language.{code}` 번역) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 |
|
||||
| status_label | string\|null | `활성` | 상태의 다국어 라벨 |
|
||||
| status_variant | string\|null | `success` | 상태 배지 색상 키 |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 |
|
||||
| homepage | string\|null | `null` | 홈페이지 URL |
|
||||
| mobile | string\|null | `010-1234-5678` | 휴대전화 번호 |
|
||||
| phone | string\|null | `null` | 전화번호 |
|
||||
| zipcode | string\|null | `06234` | 우편번호 |
|
||||
| address | string\|null | `서울특별시 강남구 테헤란로 1` | 기본 주소 |
|
||||
| address_detail | string\|null | `101동 202호` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 게시글 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `2026-07-05 19:15:16` | 마지막 로그인 일시 |
|
||||
| email_verified_at | string\|null | `null` | 이메일 인증 완료 일시 |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 식별자 |
|
||||
| created_at | string\|null | `2026-07-06 19:15:16` | 가입 일시 |
|
||||
| updated_at | string\|null | `2026-07-08 10:41:24` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
| abilities | object | `{"can_read":false,...}` | 현재 사용자의 리소스 권한 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "언어 설정이 성공적으로 변경되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "홍길동",
|
||||
"nickname": "gildong",
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "en",
|
||||
"language_label": "English",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": false,
|
||||
"homepage": null,
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": null,
|
||||
"zipcode": "06234",
|
||||
"address": "서울특별시 강남구 테헤란로 1",
|
||||
"address_detail": "101동 202호",
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"last_login_at": "2026-07-05 19:15:16",
|
||||
"email_verified_at": null,
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-06 19:15:16",
|
||||
"updated_at": "2026-07-08 10:41:24",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": false,
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false,
|
||||
"can_assign_roles": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | `language` 값이 `config('app.supported_locales')`(기본 `['ko','en']`)에 포함되지 않는 미지원 로케일인 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.profile.read`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+15
-10
@@ -273,7 +273,7 @@ HTTP/1.1 201
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.create`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -407,6 +407,8 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -430,7 +432,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/roles/1 HTTP/1.1
|
||||
DELETE /api/admin/roles/{role} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -438,7 +440,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `role.delete_success` 키로 `success()` 만 호출)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -449,8 +451,9 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -474,7 +477,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/roles/1 HTTP/1.1
|
||||
GET /api/admin/roles/{role} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -537,6 +540,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -566,7 +570,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/roles/1 HTTP/1.1
|
||||
PUT /api/admin/roles/{role} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -648,9 +652,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -674,7 +678,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/admin/roles/1/toggle-status HTTP/1.1
|
||||
PATCH /api/admin/roles/{role}/toggle-status HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -750,8 +754,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.permissions.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+111
-31
@@ -286,7 +286,7 @@ HTTP/1.1 201
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.create`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -319,18 +319,34 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| deleted_count | integer | `3` | 실제로 삭제된 스케줄 건수 (`ScheduleService::bulkDelete` 반환값) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "선택한 스케줄이 삭제되었습니다.",
|
||||
"data": {
|
||||
"deleted_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -372,18 +388,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| updated_count | integer | `3` | 상태가 실제로 변경된 스케줄 건수 (`ScheduleService::bulkUpdateStatus` 반환값) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "선택한 스케줄의 상태가 변경되었습니다.",
|
||||
"data": {
|
||||
"updated_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -414,19 +446,30 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success('schedule.history_delete_success')` 를 데이터 없이 호출)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "실행 이력이 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.delete`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | 지정한 `historyId` 의 실행 이력이 존재하지 않는 경우 (`schedule.history_not_found`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -494,6 +537,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -515,7 +559,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/schedules/1 HTTP/1.1
|
||||
DELETE /api/admin/schedules/{schedule} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -523,9 +567,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `success('schedule.delete_success')` 를 데이터 없이 호출)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -546,8 +588,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.delete`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -569,7 +612,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/schedules/1 HTTP/1.1
|
||||
GET /api/admin/schedules/{schedule} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -660,6 +703,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -695,7 +739,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/schedules/1 HTTP/1.1
|
||||
PUT /api/admin/schedules/{schedule} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -798,9 +842,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -822,7 +866,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/admin/schedules/1/duplicate HTTP/1.1
|
||||
POST /api/admin/schedules/{schedule}/duplicate HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -902,8 +946,9 @@ HTTP/1.1 201
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.create`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -935,7 +980,7 @@ HTTP/1.1 201
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/schedules/1/history?page=1&per_page=1&status=success&trigger_type=scheduled&started_from=2026-01-01&started_to=2026-01-01&sort_by=started_at&sort_order=asc HTTP/1.1
|
||||
GET /api/admin/schedules/{schedule}/history?page=1&per_page=1&status=success&trigger_type=scheduled&started_from=2026-01-01&started_to=2026-01-01&sort_by=started_at&sort_order=asc HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -945,7 +990,25 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
_목록 응답: `data.data[]` 배열 항목의 필드 + `data.pagination`._
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
목록 항목은 `ScheduleHistoryResource::toListArray()` 산물입니다 (단건 실행 응답과 달리 `output`/`error_output`/`memory_usage`(raw)/`created_at`/`updated_at` 은 포함되지 않습니다).
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `7` | 실행 이력의 기본 키 (내부 식별자) |
|
||||
| schedule_id | integer | `1` | 이 이력이 속한 스케줄의 식별자 |
|
||||
| started_at | string\|null | `2026-07-08T12:14:49+09:00` | 실행 시작 일시 (사용자 타임존 포맷) |
|
||||
| ended_at | string\|null | `2026-07-08T12:14:49+09:00` | 실행 종료 일시 (사용자 타임존 포맷, 실행 중이면 null) |
|
||||
| duration | integer\|null | `0` | 실행 소요 시간 |
|
||||
| duration_formatted | string\|null | `45초` | `duration` 값의 표시용 포맷 문자열 (모델 접근자 파생, 없으면 null) |
|
||||
| status | string | `success` | 실행 결과 상태: success(성공), failed(실패), running(실행중) |
|
||||
| status_label | string\|null | `성공` | `status` 값의 사람이 읽는 라벨 (`schedule.result.*` 현지화) |
|
||||
| exit_code | integer\|null | `0` | 실행 종료 코드 (0=성공, 그 외=실패) |
|
||||
| memory_usage_formatted | string\|null | `417.34 KB` | 실행 중 메모리 사용량의 표시용 포맷 문자열 |
|
||||
| trigger_type | string | `manual` | 실행 방식: scheduled(예약 자동 실행), manual(수동 즉시 실행) |
|
||||
| trigger_type_label | string\|null | `수동 실행` | `trigger_type` 값의 사람이 읽는 라벨 (`schedule.trigger_type.*` 현지화) |
|
||||
| triggered_by | object\|null | `{"uuid":"a234c2b1-cde8-437f-b28b-23323be2b98d","name":"관리자"}` | 수동 실행을 트리거한 사용자 정보 (uuid/name — triggeredBy 관계가 로드되지 않았거나 자동 실행이면 null) |
|
||||
|
||||
`data.pagination` 은 `current_page`/`last_page`/`per_page`/`total`/`from`/`to`/`has_more_pages` 로 구성됩니다.
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -958,14 +1021,30 @@ HTTP/1.1 200
|
||||
"success": true,
|
||||
"message": "실행 이력을 조회했습니다.",
|
||||
"data": {
|
||||
"data": [],
|
||||
"data": [
|
||||
{
|
||||
"id": 7,
|
||||
"schedule_id": 1,
|
||||
"started_at": "2026-07-08T12:14:49+09:00",
|
||||
"ended_at": "2026-07-08T12:14:49+09:00",
|
||||
"duration": 0,
|
||||
"duration_formatted": null,
|
||||
"status": "success",
|
||||
"status_label": "성공",
|
||||
"exit_code": 0,
|
||||
"memory_usage_formatted": "417.34 KB",
|
||||
"trigger_type": "manual",
|
||||
"trigger_type_label": "수동 실행",
|
||||
"triggered_by": null
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"current_page": 1,
|
||||
"last_page": 1,
|
||||
"per_page": 25,
|
||||
"total": 0,
|
||||
"from": null,
|
||||
"to": null,
|
||||
"total": 1,
|
||||
"from": 1,
|
||||
"to": 1,
|
||||
"has_more_pages": false
|
||||
}
|
||||
}
|
||||
@@ -978,8 +1057,8 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1001,7 +1080,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/admin/schedules/1/run HTTP/1.1
|
||||
POST /api/admin/schedules/{schedule}/run HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1068,8 +1147,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.run`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.schedules.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+45
-9
@@ -54,7 +54,7 @@ HTTP/1.1 200
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "messages.success",
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"urls": [],
|
||||
"count": 0
|
||||
@@ -106,19 +106,36 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| cleared | integer \| string | `12` / `"all"` | 삭제 결과. `layout` 을 지정한 경우 해당 레이아웃에서 무효화된 캐시 항목 수(정수), 미지정 시 전체 캐시를 삭제했음을 뜻하는 문자열 `"all"`. |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"cleared": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 캐시 무효화(`invalidateByLayout` / `clearAll`) 중 예외가 발생한 경우 (`messages.error_occurred`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -189,7 +206,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -315,7 +332,7 @@ HTTP/1.1 200
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "messages.success",
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"overall": {
|
||||
"total_entries": 0,
|
||||
@@ -365,18 +382,37 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| status | string | `dispatched` | 워밍업 요청 접수 상태. 현재 구현에서는 항상 `dispatched` 고정값이며, 실제 사전 렌더가 완료되었음을 뜻하지는 않는다. |
|
||||
| message | string | `SEO 캐시 워밍업이 시작되었습니다.` | 관리자에게 노출할 안내 문구 (`seo.warmup_dispatched` 다국어 키). |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "성공적으로 처리되었습니다.",
|
||||
"data": {
|
||||
"status": "dispatched",
|
||||
"message": "SEO 캐시 워밍업이 시작되었습니다."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | 워밍업 처리 중 예외가 발생한 경우 (`messages.error_occurred`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+433
-40
@@ -171,6 +171,111 @@ HTTP/1.1 200
|
||||
| advanced | body | array | 아니오 | — | 고급 탭 설정 묶음 (캐시·디버그·코어 업데이트·GeoIP 설정) |
|
||||
| notifications | body | array | 아니오 | — | 알림 탭 설정 묶음. channels 배열로 각 알림 채널의 id·is_active(활성 여부)·sort_order(표시 순서)를 저장 |
|
||||
| identity | body | array | 아니오 | — | 본인인증(IDV) 탭 설정 묶음 (기본 provider·목적별 provider 매핑·챌린지 유효시간·최대 시도 횟수) |
|
||||
| notifications.channels | body | array | 아니오 | — | 알림 채널 목록. 각 원소는 `id`(채널 식별자, 필수·최대 50자)·`is_active`(활성 여부, 필수 boolean)·`sort_order`(표시 순서, 0 이상 정수) 로 구성 |
|
||||
| general.site_name | body | string | 예 | max 100 | general.site 이름 (식별자) |
|
||||
| general.site_url | body | string | 예 | max 255 | 사이트 기본 URL |
|
||||
| general.site_description | body | string | 아니오 | max 500 | 사이트 설명 |
|
||||
| general.admin_email | body | email | 예 | max 255 | 관리자 이메일 주소 |
|
||||
| general.timezone | body | string | 예 | — | 타임존 식별자 |
|
||||
| general.language | body | string | 예 | — | 언어 코드 |
|
||||
| general.currency | body | string | 아니오 | max 10 | 통화 코드 (ISO 4217 — 예: KRW) |
|
||||
| general.maintenance_mode | body | boolean | 아니오 | — | 점검 모드 사용 여부 (사이트 접근 차단) |
|
||||
| general.site_logo | body | array | 아니오 | — | 사이트 로고 이미지 |
|
||||
| mail.mailer | body | string | 아니오 | — | 메일 발송 드라이버 (smtp/mailgun/ses) |
|
||||
| mail.host | body | string | 아니오 | max 255 | 호스트 주소 |
|
||||
| mail.port | body | integer | 아니오 | min 1, max 65535 | 포트 번호 |
|
||||
| mail.username | body | string | 아니오 | max 255 | 사용자명 (로그인/인증 아이디) |
|
||||
| mail.password | body | string | 아니오 | max 255 | 비밀번호 |
|
||||
| mail.encryption | body | string | 아니오 | — | 전송 암호화 방식 (tls/ssl) |
|
||||
| mail.mailgun_domain | body | string | 아니오 | max 255 | Mailgun 도메인 |
|
||||
| mail.mailgun_secret | body | string | 아니오 | max 255 | Mailgun 시크릿 키 |
|
||||
| mail.mailgun_endpoint | body | string | 아니오 | max 255 | Mailgun 엔드포인트 |
|
||||
| mail.ses_key | body | string | 아니오 | max 255 | SES 액세스 키 |
|
||||
| mail.ses_secret | body | string | 아니오 | max 255 | SES 시크릿 키 |
|
||||
| mail.ses_region | body | string | 아니오 | max 255 | SES 리전 |
|
||||
| mail.from_address | body | email | 아니오 | max 255 | 발신자 주소 |
|
||||
| mail.from_name | body | string | 아니오 | max 255 | mail.from 이름 (식별자) |
|
||||
| upload.max_file_size | body | integer | 아니오 | min 1, max 1024 | 업로드 허용 최대 파일 크기 |
|
||||
| upload.allowed_extensions | body | string | 아니오 | — | 업로드 허용 확장자 목록 |
|
||||
| upload.image_max_width | body | integer | 아니오 | min 100, max 10000 | 이미지 리사이즈 최대 너비 (px) |
|
||||
| upload.image_max_height | body | integer | 아니오 | min 100, max 10000 | 이미지 리사이즈 최대 높이 (px) |
|
||||
| upload.image_quality | body | integer | 아니오 | min 1, max 100 | 이미지 리사이즈 시 압축 품질 (1~100) |
|
||||
| seo.meta_title_suffix | body | string | 아니오 | max 100 | 모든 페이지 SEO 제목 뒤에 붙는 접미 문구 |
|
||||
| seo.meta_description | body | string | 아니오 | max 160 | SEO 메타 설명 (검색엔진/소셜 공유 표시 요약) |
|
||||
| seo.meta_keywords | body | string | 아니오 | max 255 | SEO 메타 키워드 (검색엔진 노출 키워드, 쉼표 구분) |
|
||||
| seo.google_analytics_id | body | string | 아니오 | max 50 | seo.google analytics 식별자 |
|
||||
| seo.google_site_verification | body | string | 아니오 | max 100 | Google Search Console 사이트 소유 확인 코드 |
|
||||
| seo.naver_site_verification | body | string | 아니오 | max 100 | 네이버 서치어드바이저 사이트 소유 확인 코드 |
|
||||
| seo.bot_user_agents | body | array | 아니오 | — | 봇으로 판정할 User-Agent 목록 |
|
||||
| seo.bot_detection_enabled | body | boolean | 아니오 | — | 검색엔진 봇 감지 사용 여부 (봇 요청에 SEO 렌더링 적용) |
|
||||
| seo.bot_detection_library_enabled | body | boolean | 아니오 | — | 봇 감지 라이브러리 사용 여부 (User-Agent 목록 대신 라이브러리 판정) |
|
||||
| seo.og_default_site_name | body | string | 아니오 | max 200 | seo.og default site 이름 (식별자) |
|
||||
| seo.og_image_default_width | body | integer | 아니오 | min 0, max 8000 | 기본 Open Graph 이미지 너비 (px) |
|
||||
| seo.og_image_default_height | body | integer | 아니오 | min 0, max 8000 | 기본 Open Graph 이미지 높이 (px) |
|
||||
| seo.twitter_default_card | body | string | 아니오 | — | 기본 트위터 카드 유형 (summary 등) |
|
||||
| seo.twitter_default_site | body | string | 아니오 | max 50 | 기본 트위터 사이트 계정 (@handle) |
|
||||
| seo.cache_enabled | body | boolean | 아니오 | — | 캐시 사용 여부 |
|
||||
| seo.cache_ttl | body | integer | 아니오 | min 60, max 86400 | 캐시 유효 시간 (초) |
|
||||
| seo.sitemap_enabled | body | boolean | 아니오 | — | sitemap.xml 생성 사용 여부 |
|
||||
| seo.sitemap_cache_ttl | body | integer | 아니오 | min 3600, max 604800 | sitemap 캐시 유효 시간 (초) |
|
||||
| seo.sitemap_schedule | body | string | 아니오 | — | sitemap 자동 생성 주기 |
|
||||
| seo.sitemap_schedule_time | body | string | 아니오 | — | sitemap 자동 생성 시각 |
|
||||
| seo.generator_enabled | body | boolean | 아니오 | — | SEO 페이지 생성기 사용 여부 |
|
||||
| seo.generator_content | body | string | 아니오 | max 200 | SEO 렌더링 본문 생성 방식 |
|
||||
| security.force_https | body | boolean | 아니오 | — | HTTPS 강제 리다이렉트 여부 |
|
||||
| security.login_attempt_enabled | body | boolean | 아니오 | — | 로그인 시도 제한 사용 여부 |
|
||||
| security.auth_token_lifetime | body | integer | 아니오 | min 0, max 3600 | 인증 토큰 유효 시간 (분) |
|
||||
| security.max_login_attempts | body | integer | 아니오 | min 0, max 100 | 로그인 실패 허용 횟수 (초과 시 잠금) |
|
||||
| security.login_lockout_time | body | integer | 아니오 | min 0, max 1440 | 로그인 잠금 지속 시간 (분) |
|
||||
| advanced.cache_enabled | body | boolean | 아니오 | — | 캐시 사용 여부 |
|
||||
| advanced.layout_cache_enabled | body | boolean | 아니오 | — | 레이아웃 캐시 사용 여부 (레이아웃 데이터를 캐시) |
|
||||
| advanced.layout_cache_ttl | body | integer | 아니오 | min 0, max 14400 | 레이아웃 캐시 만료 시간 (초, 0 = 만료 없음) |
|
||||
| advanced.stats_cache_enabled | body | boolean | 아니오 | — | 통계 캐시 사용 여부 (대시보드 통계를 캐시) |
|
||||
| advanced.stats_cache_ttl | body | integer | 아니오 | min 0, max 14400 | 통계 캐시 만료 시간 (초, 0 = 만료 없음) |
|
||||
| advanced.seo_cache_enabled | body | boolean | 아니오 | — | SEO 캐시 사용 여부 (SEO 메타데이터를 캐시) |
|
||||
| advanced.seo_cache_ttl | body | integer | 아니오 | min 0, max 14400 | SEO 캐시 만료 시간 (초, 0 = 만료 없음) |
|
||||
| advanced.debug_mode | body | boolean | 아니오 | — | 디버그 모드 사용 여부 (상세 오류 노출) |
|
||||
| advanced.sql_query_log | body | boolean | 아니오 | — | SQL 쿼리 로그 기록 여부 |
|
||||
| advanced.core_update_github_url | body | string | 아니오 | max 500 | 코어 업데이트를 확인할 GitHub 저장소 URL |
|
||||
| advanced.core_update_github_token | body | string | 아니오 | max 500 | 프라이빗 저장소의 코어/확장 업데이트에 사용할 GitHub 액세스 토큰 (공개 저장소는 비워둘 수 있음) |
|
||||
| advanced.geoip_enabled | body | boolean | 아니오 | — | IP 기반 타임존 감지(GeoIP) 사용 여부 |
|
||||
| advanced.geoip_license_key | body | string | 아니오 | max 200 | MaxMind GeoLite2 라이선스 키 |
|
||||
| advanced.geoip_auto_update_enabled | body | boolean | 아니오 | — | GeoIP DB 자동 업데이트 사용 여부 (주 1회 자동 재다운로드) |
|
||||
| drivers.storage_driver | body | string | 아니오 | — | 스토리지 드라이버 (local/s3) |
|
||||
| drivers.s3_bucket | body | string | 아니오 | max 255 | S3 버킷명 |
|
||||
| drivers.s3_region | body | string | 아니오 | — | S3 리전 |
|
||||
| drivers.s3_access_key | body | string | 아니오 | max 255 | S3 액세스 키 |
|
||||
| drivers.s3_secret_key | body | string | 아니오 | max 255 | S3 시크릿 키 |
|
||||
| drivers.s3_url | body | string | 아니오 | max 500 | S3 엔드포인트 URL |
|
||||
| drivers.cache_driver | body | string | 아니오 | — | 캐시 드라이버 (file/redis/memcached) |
|
||||
| drivers.redis_host | body | string | 아니오 | max 255 | Redis 호스트 주소 |
|
||||
| drivers.redis_port | body | integer | 아니오 | min 1, max 65535 | Redis 포트 번호 |
|
||||
| drivers.redis_password | body | string | 아니오 | max 255 | Redis 비밀번호 |
|
||||
| drivers.redis_database | body | integer | 아니오 | min 0, max 15 | Redis 데이터베이스 번호 |
|
||||
| drivers.memcached_host | body | string | 아니오 | max 255 | Memcached 호스트 주소 |
|
||||
| drivers.memcached_port | body | integer | 아니오 | min 1, max 65535 | Memcached 포트 번호 |
|
||||
| drivers.session_driver | body | string | 아니오 | — | 세션 드라이버 (file/database/redis) |
|
||||
| drivers.session_lifetime | body | integer | 아니오 | min 1, max 43200 | 세션 유효 시간 (분) |
|
||||
| drivers.queue_driver | body | string | 아니오 | — | 큐 드라이버 (sync/database/redis) |
|
||||
| drivers.websocket_enabled | body | boolean | 아니오 | — | WebSocket 사용 여부 |
|
||||
| drivers.websocket_app_id | body | string | 아니오 | max 255 | drivers.websocket app 식별자 |
|
||||
| drivers.websocket_app_key | body | string | 아니오 | max 255 | WebSocket 앱 키 |
|
||||
| drivers.websocket_app_secret | body | string | 아니오 | max 255 | WebSocket 앱 시크릿 |
|
||||
| drivers.websocket_host | body | string | 아니오 | max 255 | WebSocket 호스트 주소 |
|
||||
| drivers.websocket_port | body | integer | 아니오 | min 1, max 65535 | WebSocket 포트 번호 |
|
||||
| drivers.websocket_scheme | body | string | 아니오 | — | WebSocket 스킴 (http/https) |
|
||||
| drivers.websocket_verify_ssl | body | boolean | 아니오 | — | WebSocket 서버 SSL 인증서 검증 여부 |
|
||||
| drivers.websocket_server_host | body | string | 아니오 | max 255 | WebSocket 서버 호스트 주소 (서버측 발행 대상) |
|
||||
| drivers.websocket_server_port | body | integer | 아니오 | min 1, max 65535 | WebSocket 서버 포트 번호 (서버측 발행 대상) |
|
||||
| drivers.websocket_server_scheme | body | string | 아니오 | — | WebSocket 서버 스킴 (http/https — 서버측 발행 대상) |
|
||||
| drivers.search_engine_driver | body | string | 아니오 | — | 검색 엔진 드라이버 (Scout 엔진 선택) |
|
||||
| drivers.log_driver | body | string | 아니오 | — | 로그 드라이버 (single/daily/stack) |
|
||||
| drivers.log_level | body | string | 아니오 | — | 로그 레벨 (debug/info/warning/error 등) |
|
||||
| drivers.log_days | body | integer | 아니오 | min 1, max 365 | 로그 파일 보관 일수 |
|
||||
| identity.default_provider | body | string | 아니오 | max 100 | 본인인증 기본 프로바이더 (목적별로 지정되지 않은 경우 사용). 예: `g7:core.mail` |
|
||||
| identity.purpose_providers | body | array | 아니오 | — | 본인인증 목적(Purpose)별 프로바이더 매핑. 미지정 목적은 기본 프로바이더를 사용 |
|
||||
| identity.challenge_ttl_minutes | body | integer | 아니오 | min 1, max 1440 | 발급된 인증 코드/링크(challenge)의 유효시간 (분) |
|
||||
| identity.max_attempts | body | integer | 아니오 | min 1, max 20 | challenge 최대 시도 횟수 (연속 실패 시 잠금 — 재전송 필요) |
|
||||
|
||||
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.settings.save_validation_rules`, `core.search.engine_drivers`).
|
||||
|
||||
@@ -211,24 +316,181 @@ Content-Type: application/json
|
||||
],
|
||||
"identity": [
|
||||
"예시값"
|
||||
]
|
||||
],
|
||||
"notifications.channels": [
|
||||
"예시값"
|
||||
],
|
||||
"general.site_name": "예시 이름",
|
||||
"general.site_url": "https://example.com",
|
||||
"general.site_description": "예시 내용입니다.",
|
||||
"general.admin_email": "user@example.com",
|
||||
"general.timezone": "Asia/Seoul",
|
||||
"general.language": "예시값",
|
||||
"general.currency": "예시값",
|
||||
"general.maintenance_mode": true,
|
||||
"general.site_logo": [
|
||||
"예시값"
|
||||
],
|
||||
"mail.mailer": "예시값",
|
||||
"mail.host": "예시값",
|
||||
"mail.port": 1,
|
||||
"mail.username": "예시 이름",
|
||||
"mail.password": "Password123!",
|
||||
"mail.encryption": "예시값",
|
||||
"mail.mailgun_domain": "예시값",
|
||||
"mail.mailgun_secret": "예시값",
|
||||
"mail.mailgun_endpoint": "예시값",
|
||||
"mail.ses_key": "예시값",
|
||||
"mail.ses_secret": "예시값",
|
||||
"mail.ses_region": "예시값",
|
||||
"mail.from_address": "user@example.com",
|
||||
"mail.from_name": "예시 이름",
|
||||
"upload.max_file_size": 1,
|
||||
"upload.allowed_extensions": "예시값",
|
||||
"upload.image_max_width": 1,
|
||||
"upload.image_max_height": 1,
|
||||
"upload.image_quality": 1,
|
||||
"seo.meta_title_suffix": "예시 제목",
|
||||
"seo.meta_description": "예시 내용입니다.",
|
||||
"seo.meta_keywords": "예시값",
|
||||
"seo.google_analytics_id": "예시값",
|
||||
"seo.google_site_verification": "예시값",
|
||||
"seo.naver_site_verification": "예시값",
|
||||
"seo.bot_user_agents": [
|
||||
"예시값"
|
||||
],
|
||||
"seo.bot_detection_enabled": true,
|
||||
"seo.bot_detection_library_enabled": true,
|
||||
"seo.og_default_site_name": "예시 이름",
|
||||
"seo.og_image_default_width": 1,
|
||||
"seo.og_image_default_height": 1,
|
||||
"seo.twitter_default_card": "예시값",
|
||||
"seo.twitter_default_site": "예시값",
|
||||
"seo.cache_enabled": true,
|
||||
"seo.cache_ttl": 1,
|
||||
"seo.sitemap_enabled": true,
|
||||
"seo.sitemap_cache_ttl": 1,
|
||||
"seo.sitemap_schedule": "예시값",
|
||||
"seo.sitemap_schedule_time": "예시값",
|
||||
"seo.generator_enabled": true,
|
||||
"seo.generator_content": "예시 내용입니다.",
|
||||
"security.force_https": true,
|
||||
"security.login_attempt_enabled": true,
|
||||
"security.auth_token_lifetime": 1,
|
||||
"security.max_login_attempts": 1,
|
||||
"security.login_lockout_time": 1,
|
||||
"advanced.cache_enabled": true,
|
||||
"advanced.layout_cache_enabled": true,
|
||||
"advanced.layout_cache_ttl": 1,
|
||||
"advanced.stats_cache_enabled": true,
|
||||
"advanced.stats_cache_ttl": 1,
|
||||
"advanced.seo_cache_enabled": true,
|
||||
"advanced.seo_cache_ttl": 1,
|
||||
"advanced.debug_mode": true,
|
||||
"advanced.sql_query_log": true,
|
||||
"advanced.core_update_github_url": "https://example.com",
|
||||
"advanced.core_update_github_token": "{YOUR_TOKEN}",
|
||||
"advanced.geoip_enabled": true,
|
||||
"advanced.geoip_license_key": "예시값",
|
||||
"advanced.geoip_auto_update_enabled": true,
|
||||
"drivers.storage_driver": "예시값",
|
||||
"drivers.s3_bucket": "예시값",
|
||||
"drivers.s3_region": "예시값",
|
||||
"drivers.s3_access_key": "예시값",
|
||||
"drivers.s3_secret_key": "예시값",
|
||||
"drivers.s3_url": "https://example.com",
|
||||
"drivers.cache_driver": "예시값",
|
||||
"drivers.redis_host": "예시값",
|
||||
"drivers.redis_port": 1,
|
||||
"drivers.redis_password": "Password123!",
|
||||
"drivers.redis_database": 1,
|
||||
"drivers.memcached_host": "예시값",
|
||||
"drivers.memcached_port": 1,
|
||||
"drivers.session_driver": "예시값",
|
||||
"drivers.session_lifetime": 1,
|
||||
"drivers.queue_driver": "예시값",
|
||||
"drivers.websocket_enabled": true,
|
||||
"drivers.websocket_app_id": "예시값",
|
||||
"drivers.websocket_app_key": "예시값",
|
||||
"drivers.websocket_app_secret": "예시값",
|
||||
"drivers.websocket_host": "예시값",
|
||||
"drivers.websocket_port": 1,
|
||||
"drivers.websocket_scheme": "예시값",
|
||||
"drivers.websocket_verify_ssl": true,
|
||||
"drivers.websocket_server_host": "예시값",
|
||||
"drivers.websocket_server_port": 1,
|
||||
"drivers.websocket_server_scheme": "예시값",
|
||||
"drivers.search_engine_driver": "예시값",
|
||||
"drivers.log_driver": "예시값",
|
||||
"drivers.log_level": "예시값",
|
||||
"drivers.log_days": 1,
|
||||
"identity.default_provider": "예시값",
|
||||
"identity.purpose_providers": [
|
||||
"예시값"
|
||||
],
|
||||
"identity.challenge_ttl_minutes": 1,
|
||||
"identity.max_attempts": 1
|
||||
}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| settings | object | `{"general":{...},"security":{...},"available_drivers":{...}}` | 저장 직후 다시 조회한 전체 설정 집계. 구조는 `GET /api/admin/settings` 의 `data` 와 동일 (general/security/mail/upload/seo/advanced/cache/debug/drivers/core_update/geoip/notifications/identity + `available_drivers`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "설정이 성공적으로 저장되었습니다.",
|
||||
"data": {
|
||||
"settings": {
|
||||
"general": {
|
||||
"site_name": "Test Site",
|
||||
"site_url": "https://test.example.com",
|
||||
"site_description": "",
|
||||
"admin_email": "admin@example.com",
|
||||
"timezone": "Asia/Seoul",
|
||||
"language": "ko",
|
||||
"currency": "KRW",
|
||||
"maintenance_mode": false,
|
||||
"site_logo": []
|
||||
},
|
||||
"security": {
|
||||
"force_https": true,
|
||||
"login_attempt_enabled": true,
|
||||
"auth_token_lifetime": 0,
|
||||
"max_login_attempts": 5,
|
||||
"login_lockout_time": 30
|
||||
},
|
||||
"available_drivers": {
|
||||
"storage": [
|
||||
{
|
||||
"id": "local",
|
||||
"label": {
|
||||
"ko": "로컬",
|
||||
"en": "Local"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 위 예시는 지면상 일부 그룹만 표기한 것으로, 실제 응답의 `data.settings` 에는 `GET /api/admin/settings` 와 동일한 전체 그룹이 포함됩니다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -316,18 +578,31 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| backup_path | string | `backups/backup_2026-07-14_030000.zip` | 생성된 설정 백업 ZIP 의 저장소 상대 경로 (카테고리별 설정 JSON 을 묶은 아카이브). `POST /api/admin/settings/restore` 의 `backup_path` 로 그대로 전달해 복원에 사용 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "데이터베이스 백업이 성공적으로 시작되었습니다.",
|
||||
"data": {
|
||||
"backup_path": "backups/backup_2026-07-14_030000.zip"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | 백업 파일 생성에 실패한 경우 (`settings.backup_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -357,18 +632,26 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만). 컨트롤러가 `ResponseHelper::success('settings.backup_success')` 를 데이터 없이 호출하므로 `data` 는 `null` 입니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "데이터베이스 백업이 성공적으로 시작되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | 백업이 수행되지 않은 경우 (`settings.backup_failed`) |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | 백업 처리 중 예외가 발생한 경우 (`settings.backup_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -398,18 +681,26 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만). 컨트롤러가 `ResponseHelper::success('settings.cache_clear_success')` 를 데이터 없이 호출하므로 `data` 는 `null` 입니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "캐시가 성공적으로 정리되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | 캐시 정리가 수행되지 않은 경우 (`settings.cache_clear_failed`) |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | 캐시 정리 중 예외가 발생한 경우 (`settings.cache_clear_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -439,18 +730,38 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (GeoIpDatabaseService::updateDatabase() 의 `data`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| database_path | string | `storage/app/geoip/GeoLite2-City.mmdb` | 갱신된 GeoLite2 DB 파일의 절대 경로 (`config('geoip.database_path')`) |
|
||||
| file_size_bytes | integer | `60000000` | 다운로드·전개 후 최종 DB 파일 크기 (바이트) |
|
||||
| elapsed_seconds | number | `12.34` | 다운로드부터 교체 완료까지 소요 시간 (초) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "settings.geoip.update_success",
|
||||
"data": {
|
||||
"database_path": "storage/app/geoip/GeoLite2-City.mmdb",
|
||||
"file_size_bytes": 60000000,
|
||||
"elapsed_seconds": 12.34
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `message` 는 컨트롤러가 넘기는 `settings.geoip.update_success` 키를 번역한 값입니다. 현재 코어 `lang/{ko,en}/settings.php` 에 `geoip.*` 항목이 정의되어 있지 않아 번역이 없으면 키 문자열이 그대로 내려갑니다 (관리자 화면은 프론트엔드 다국어 키로 별도 문구를 표시).
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 400 | Bad Request | MaxMind 라이선스 키가 설정되지 않은 경우 (`missing_license_key`) |
|
||||
| 401 | Unauthorized | MaxMind 라이선스 키가 유효하지 않은 경우 (`unauthorized`) |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | MaxMind 연결 실패(`connection_failed`) 또는 다운로드·압축 해제 실패 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -480,9 +791,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만). 컨트롤러가 `ResponseHelper::success('settings.optimize_success')` 를 데이터 없이 호출하므로 `data` 는 `null` 입니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -503,7 +812,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -542,19 +851,32 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| app_key | string | `base64:97gZH********************************` | 재생성된 애플리케이션 키를 마스킹한 문자열 (앞 12자 + 별표 32개). 전체 원문 키는 반환하지 않으며 `.env` 의 `APP_KEY` 에만 기록됨 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "어플리케이션 키가 성공적으로 재생성되었습니다.",
|
||||
"data": {
|
||||
"app_key": "base64:97gZH********************************"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 401 | Unauthorized | 본문 `password` 가 요청자 본인의 비밀번호와 일치하지 않는 경우 (`settings.invalid_password`) |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없거나, FormRequest 가 `super_admin` 역할이 아닌 사용자를 거부한 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | `.env` 기록/config 캐시 재생성 실패 (`settings.app_key_regenerate_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -593,19 +915,27 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만). 컨트롤러가 `ResponseHelper::success('settings.restore_success')` 를 데이터 없이 호출하므로 `data` 는 `null` 입니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "설정이 성공적으로 복원되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | 복원이 수행되지 않은 경우 (`settings.restore_failed`) |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 백업 파일을 읽을 수 없는 등 복원 중 예외 발생 (`settings.restore_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -829,19 +1159,44 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (DriverConnectionTester::testAll() 산물)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| results | object | `{"redis":{"success":true,"message":"Redis 서버에 성공적으로 연결되었습니다.","latency":"3ms"}}` | 드라이버별 테스트 결과 맵. 키는 실제 테스트가 수행된 드라이버(`s3`/`redis`/`memcached`/`websocket`)만 포함 — 요청 설정에서 해당 드라이버를 쓰지 않으면 키 자체가 없음 |
|
||||
| results.{driver}.success | boolean | `true` | 해당 드라이버 연결 성공 여부 |
|
||||
| results.{driver}.message | string | `Redis 서버에 성공적으로 연결되었습니다.` | 결과 메시지 (성공/실패 사유 — 설정 누락·확장 미설치·인증 실패 등) |
|
||||
| results.{driver}.latency | string | `3ms` | 성공 시에만 포함. 연결 왕복 소요 시간 |
|
||||
| results.{driver}.error | string | `Connection refused` | 실패 시에만 포함. 원본 예외 메시지 |
|
||||
| all_passed | boolean | `true` | 수행된 모든 드라이버 테스트가 성공했는지 여부. `false` 여도 HTTP 200 으로 응답하며 message 가 `일부 드라이버 연결 테스트가 실패했습니다.` 로 바뀜 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "모든 드라이버 연결 테스트가 성공했습니다.",
|
||||
"data": {
|
||||
"results": {
|
||||
"redis": {
|
||||
"success": true,
|
||||
"message": "Redis 서버에 성공적으로 연결되었습니다.",
|
||||
"latency": "3ms"
|
||||
}
|
||||
},
|
||||
"all_passed": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 테스트 실행 중 예외가 발생한 경우 (`settings.driver_test_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -908,19 +1263,34 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (발송 성공 시에만 반환)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| subject | string | `그누보드7 테스트 메일` | 실제로 발송한 테스트 메일의 제목 (`settings.test_mail_subject` — 앱 이름이 치환됨) |
|
||||
| body | string | `이것은 그누보드7에서 발송한 테스트 메일입니다. 이 메일을 받으셨다면 메일 설정이 올바르게 구성되어 있습니다.` | 실제로 발송한 테스트 메일의 본문 (`settings.test_mail_body`, 평문) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-500 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "테스트 메일이 성공적으로 발송되었습니다.",
|
||||
"data": {
|
||||
"subject": "그누보드7 테스트 메일",
|
||||
"body": "이것은 그누보드7에서 발송한 테스트 메일입니다. 이 메일을 받으셨다면 메일 설정이 올바르게 구성되어 있습니다."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 발송 실패 시 — `message` 는 `테스트 메일 발송에 실패했습니다.`, `error` 에 원본 예외 메시지(SMTP 인증 실패·연결 거부 등)가 담김 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -952,11 +1322,25 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| key | string | `general.site_name` | 요청한 설정 키를 그대로 되돌려 준 값 (`{category}.{field}` 형태) |
|
||||
| value | mixed | `Test Site` | 해당 설정 키의 현재 값. 설정 항목의 자료형에 따라 문자열/정수/불리언/배열이 될 수 있으며, 키가 없으면 `null` |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "설정을 성공적으로 가져왔습니다.",
|
||||
"data": {
|
||||
"key": "general.site_name",
|
||||
"value": "Test Site"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -965,6 +1349,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 500 | Internal Server Error | 설정 조회 중 예외가 발생한 경우 (`settings.fetch_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1004,20 +1389,28 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만). 컨트롤러가 `ResponseHelper::success('settings.update_success')` 를 데이터 없이 호출하므로 `data` 는 `null` 입니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "설정이 성공적으로 업데이트되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 400 | Bad Request | 저장이 수행되지 않은 경우 (`settings.update_failed`) |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 저장 중 예외가 발생한 경우 (`settings.update_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
+185465
-198
File diff suppressed because it is too large.
Load diff
+297
-25
@@ -293,19 +293,94 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (생성된 사용자 — `UserResource::toArray()`, 관계 미로드이므로 modules/plugins/menus/roles/permissions/consents 키는 응답에 포함되지 않음)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `API 문서 샘플 사용자` | 사용자 이름 |
|
||||
| nickname | string\|null | `null` | 닉네임 |
|
||||
| email | string | `apidoc-sample-user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 프로필 아바타 이미지 URL (미설정 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 (ko: 한국어, en: English) |
|
||||
| language_label | string | `한국어` | 언어 코드의 현지화 라벨 (`user.language.{code}` 번역) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (UserStatus Enum: active/inactive/blocked/withdrawn) |
|
||||
| status_label | string | `활성` | 상태의 사람이 읽는 라벨 (UserStatus::label()) |
|
||||
| status_variant | string | `success` | 상태 표시 색상/스타일 변형 키 (UserStatus::variant() — UI 배지용) |
|
||||
| is_admin | boolean | `false` | 관리자 역할 보유 여부 (User::isAdmin()) |
|
||||
| homepage | string\|null | `null` | 홈페이지 URL |
|
||||
| mobile | string\|null | `null` | 휴대폰 번호 |
|
||||
| phone | string\|null | `null` | 전화번호 |
|
||||
| zipcode | string\|null | `null` | 우편번호 |
|
||||
| address | string\|null | `null` | 기본 주소 |
|
||||
| address_detail | string\|null | `null` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `null` | 마지막 로그인 일시 (신규 생성 시 null) |
|
||||
| email_verified_at | string\|null | `null` | 이메일 인증 일시 (미인증 시 null) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 10:41:24` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `false` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_create":true,"can_update":true,"can_delete":true,"can_assign_roles":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (슈퍼관리자 대상은 can_delete=false 강제) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용자가 성공적으로 생성되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "예시 이름",
|
||||
"nickname": null,
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"language_label": "한국어",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": false,
|
||||
"homepage": null,
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": null,
|
||||
"zipcode": null,
|
||||
"address": null,
|
||||
"address_detail": null,
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"last_login_at": null,
|
||||
"email_verified_at": null,
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 10:41:24",
|
||||
"is_owner": false,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.create`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 사용자 생성 중 예외 발생 (`user.create_failed`, `errors.error` 에 예외 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -348,19 +423,38 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (UserService::bulkUpdateStatus() 반환값)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| updated_count | integer | `3` | 실제로 상태가 변경된 사용자 수 (요청자 본인 제외 규칙 적용 후 갱신된 행 수) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": ":count명의 사용자 상태가 변경되었습니다.",
|
||||
"data": {
|
||||
"updated_count": 3
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> `user.bulk_status_updated` 메시지는 `:count` 치환자를 갖지만 컨트롤러가 messageParams 를 넘기지 않으므로 응답 message 에는 치환되지 않은 원문이 그대로 담긴다. 실제 변경 건수는 `data.updated_count` 로 판단한다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지 — 예: 요청자 본인 UUID 포함 시 `ExcludeCurrentUser` 위반) |
|
||||
| 500 | Internal Server Error | 일괄 변경 중 예외 발생 (`user.bulk_update_status_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -401,11 +495,29 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| available | boolean | `true` | 해당 이메일의 사용 가능 여부 (true: 사용 가능, false: 이미 사용 중). `exclude_user_id` 로 지정한 사용자가 소유한 이메일이면 true 로 판정 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용 가능한 이메일입니다.",
|
||||
"data": {
|
||||
"available": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 이미 사용 중인 이메일이면 동일한 200 응답에 `message` 가 `이미 사용 중인 이메일입니다.` (`user.email_unavailable`), `data.available` 이 `false` 로 반환된다.
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -413,7 +525,8 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지 — 이메일 형식/필수, exclude_user_id UUID 형식·존재 여부) |
|
||||
| 500 | Internal Server Error | 중복 확인 중 예외 발생 (`user.email_check_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -537,6 +650,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -659,6 +773,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -693,11 +808,87 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_목록 응답: `data[]` 배열 항목의 필드 (페이지네이션 없는 단순 컬렉션 — `UserResource::collection()`, 관계 미로드이므로 modules/plugins/menus/roles/permissions/consents 키는 포함되지 않음). 일치하는 사용자가 없으면 `data` 는 빈 배열._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `API 문서 샘플 사용자` | 사용자 이름 |
|
||||
| nickname | string\|null | `null` | 닉네임 |
|
||||
| email | string | `apidoc-sample-user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 프로필 아바타 이미지 URL (미설정 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 (ko: 한국어, en: English) |
|
||||
| language_label | string | `한국어` | 언어 코드의 현지화 라벨 (`user.language.{code}` 번역) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (UserStatus Enum: active/inactive/blocked/withdrawn) |
|
||||
| status_label | string | `활성` | 상태의 사람이 읽는 라벨 (UserStatus::label()) |
|
||||
| status_variant | string | `success` | 상태 표시 색상/스타일 변형 키 (UserStatus::variant() — UI 배지용) |
|
||||
| is_admin | boolean | `true` | 관리자 역할 보유 여부 (User::isAdmin()) |
|
||||
| homepage | string\|null | `null` | 홈페이지 URL |
|
||||
| mobile | string\|null | `null` | 휴대폰 번호 |
|
||||
| phone | string\|null | `null` | 전화번호 |
|
||||
| zipcode | string\|null | `null` | 우편번호 |
|
||||
| address | string\|null | `null` | 기본 주소 |
|
||||
| address_detail | string\|null | `null` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `2026-07-07 10:41:24` | 마지막 로그인 일시 (미로그인 시 null) |
|
||||
| email_verified_at | string\|null | `2026-07-08 10:41:24` | 이메일 인증 일시 (미인증 시 null) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 10:41:24` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `false` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_create":true,"can_update":true,"can_delete":true,"can_assign_roles":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용자 검색을 성공적으로 완료했습니다.",
|
||||
"data": [
|
||||
{
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"nickname": null,
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"language_label": "한국어",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": true,
|
||||
"homepage": null,
|
||||
"mobile": null,
|
||||
"phone": null,
|
||||
"zipcode": null,
|
||||
"address": null,
|
||||
"address_detail": null,
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"last_login_at": "2026-07-07 10:41:24",
|
||||
"email_verified_at": "2026-07-08 10:41:24",
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 10:41:24",
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -705,7 +896,8 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지 — `keyword`/`uuid` 를 모두 생략한 경우 포함) |
|
||||
| 500 | Internal Server Error | 검색 중 예외 발생 (`user.search_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -775,6 +967,7 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -798,7 +991,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/admin/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4 HTTP/1.1
|
||||
DELETE /api/admin/users/{user} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -806,7 +999,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -817,9 +1010,9 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.delete`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -843,7 +1036,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/admin/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4 HTTP/1.1
|
||||
GET /api/admin/users/{user} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -928,7 +1121,7 @@ _단건 응답: `data` 객체의 필드._
|
||||
| channels | array | `[{"key":"email_subscription","label":"광고성 이메일 수신","enable…` | 관리자 정의 전체 마케팅 채널 목록 (원소: key/label/enabled/terms_slug — marketing 플러그인 주입, iteration 렌더링용) |
|
||||
| consent_histories | array | `[]` | 사용자 동의 변경 이력 (원소: channel_key/action/source/created_at — marketing 플러그인 주입) |
|
||||
| ecommerce_mileage | object | `{"enabled":false}` | 이커머스 마일리지 정보 (enabled 및 잔액 등 — sirsoft-ecommerce 모듈 주입) |
|
||||
| ecommerce_preferred_currency | null | `null` | 선호 결제 통화 (sirsoft-ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_currency | string | `KRW` | 선호 결제 통화 (sirsoft-ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country | null | `null` | 선호 배송 국가 코드 (sirsoft-ecommerce 모듈 주입, 미설정 시 null) |
|
||||
| ecommerce_preferred_shipping_country_name | null | `null` | 선호 배송 국가명 (배송 국가 코드에서 파생, sirsoft-ecommerce 모듈 주입) |
|
||||
|
||||
@@ -1052,6 +1245,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1104,7 +1298,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/admin/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4 HTTP/1.1
|
||||
PUT /api/admin/users/{user} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1147,20 +1341,95 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (수정된 사용자 — `UserResource::toArray()`, 관계 미로드이므로 modules/plugins/menus/roles/permissions/consents 키는 응답에 포함되지 않음)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| uuid | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| name | string | `API 문서 샘플 사용자` | 사용자 이름 |
|
||||
| nickname | string\|null | `null` | 닉네임 |
|
||||
| email | string | `apidoc-sample-user@example.com` | 이메일 주소 |
|
||||
| avatar | string\|null | `null` | 프로필 아바타 이미지 URL (미설정 시 null) |
|
||||
| language | string | `ko` | 사용자 언어 설정 (ko: 한국어, en: English) |
|
||||
| language_label | string | `한국어` | 언어 코드의 현지화 라벨 (`user.language.{code}` 번역) |
|
||||
| country | string\|null | `KR` | 국가 코드 (ISO 3166-1 alpha-2) |
|
||||
| status | string | `active` | 계정 상태 (UserStatus Enum: active/inactive/blocked/withdrawn) |
|
||||
| status_label | string | `활성` | 상태의 사람이 읽는 라벨 (UserStatus::label()) |
|
||||
| status_variant | string | `success` | 상태 표시 색상/스타일 변형 키 (UserStatus::variant() — UI 배지용) |
|
||||
| is_admin | boolean | `true` | 관리자 역할 보유 여부 (User::isAdmin()) |
|
||||
| homepage | string\|null | `https://example.com` | 홈페이지 URL |
|
||||
| mobile | string\|null | `010-1234-5678` | 휴대폰 번호 |
|
||||
| phone | string\|null | `null` | 전화번호 |
|
||||
| zipcode | string\|null | `null` | 우편번호 |
|
||||
| address | string\|null | `null` | 기본 주소 |
|
||||
| address_detail | string\|null | `null` | 상세 주소 |
|
||||
| signature | string\|null | `null` | 서명 |
|
||||
| bio | string\|null | `null` | 자기소개 |
|
||||
| last_login_at | string\|null | `2026-07-07 10:41:24` | 마지막 로그인 일시 (미로그인 시 null) |
|
||||
| email_verified_at | string\|null | `2026-07-08 10:41:24` | 이메일 인증 일시 (미인증 시 null) |
|
||||
| timezone | string\|null | `Asia/Seoul` | 사용자 시간대 |
|
||||
| created_at | string | `2026-07-08 10:41:24` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 11:02:07` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `false` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_create":true,"can_update":true,"can_delete":true,"can_assign_roles":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (슈퍼관리자 대상은 can_delete=false 강제) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "사용자 정보가 성공적으로 업데이트되었습니다.",
|
||||
"data": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "예시 이름",
|
||||
"nickname": null,
|
||||
"email": "user@example.com",
|
||||
"avatar": null,
|
||||
"language": "ko",
|
||||
"language_label": "한국어",
|
||||
"country": "KR",
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"status_variant": "success",
|
||||
"is_admin": false,
|
||||
"homepage": "https://example.com",
|
||||
"mobile": "010-1234-5678",
|
||||
"phone": null,
|
||||
"zipcode": null,
|
||||
"address": null,
|
||||
"address_detail": null,
|
||||
"signature": null,
|
||||
"bio": null,
|
||||
"last_login_at": null,
|
||||
"email_verified_at": null,
|
||||
"timezone": "Asia/Seoul",
|
||||
"created_at": "2026-07-08 10:41:24",
|
||||
"updated_at": "2026-07-08 11:02:07",
|
||||
"is_owner": false,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_create": true,
|
||||
"can_update": true,
|
||||
"can_delete": true,
|
||||
"can_assign_roles": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지 — 마지막 관리자 본인의 admin 역할 제거 시도 시 `user.last_admin_role_cannot_remove` 포함) |
|
||||
| 500 | Internal Server Error | 수정 중 예외 발생 (`user.update_failed`, `errors.error` 에 예외 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1307,7 +1576,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/users/a26219fc-94a0-4f63-9404-04c2a6ac99e4/profile HTTP/1.1
|
||||
GET /api/users/{user}/profile HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
```
|
||||
@@ -1354,7 +1623,10 @@ HTTP/1.1 200
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`core.users.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -45,18 +45,25 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-401 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — 컨트롤러가 `ResponseHelper::success('user.password_verified')` 를 인자 없이 호출하므로 `data` 는 `null` 입니다)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-401 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "비밀번호가 확인되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 401 | 비밀번호 불일치 | 전달한 `password` 가 저장된 해시와 일치하지 않는 경우 (`message`: 비밀번호가 일치하지 않습니다.) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | 비밀번호 확인 실패 | 확인 처리 중 예기치 못한 예외가 발생한 경우 (`message`: 비밀번호 확인에 실패했습니다.) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -419,6 +419,53 @@ v1.17.0 이전: modals 내부의 extension_point는 처리되지 않았음
|
||||
| `prepend` | default **앞에** 추가 | `[NEW] [default...]` |
|
||||
| `replace` | default **완전 교체** | `[NEW]` (default 제거) |
|
||||
|
||||
### 확장 병합 칸 (주입 폼의 값을 템플릿 API 요청에 실어 보내기)
|
||||
|
||||
슬롯에 주입한 폼이 입력값을 서버로 보내려면, 그 값이 **템플릿이 소유한 apiCall 의 `params.body`** 에 도달해야 한다. 그런데 확장에는 body 에 키를 추가할 수단이 없다.
|
||||
|
||||
- 결제 버튼처럼 `id` 가 없는 노드는 overlay `target_id` 로 잡을 수 없다
|
||||
- `inject_props` 는 컴포넌트 props 병합 전용이라 `actions[].params.body` 에 닿지 않는다 (`_merge` 는 shallow)
|
||||
|
||||
그래서 템플릿이 **확장 병합 칸**을 하나 열어 둔다. 규약은 이렇다.
|
||||
|
||||
**템플릿 쪽** — body 를 통짜 표현식으로 만들고 말미에 확장 칸을 spread 한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"handler": "apiCall",
|
||||
"target": "/api/modules/sirsoft-ecommerce/user/orders",
|
||||
"params": {
|
||||
"body": "{{ ({ temp_order_id: _local.tempOrderId, payment_method: _computed.selectedPaymentMethod, ...(_local.checkoutExtraPayload ?? {}) }) }}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**확장 쪽** — 자기 필드를 그 칸에 setState 한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "change",
|
||||
"handler": "setState",
|
||||
"params": {
|
||||
"target": "local",
|
||||
"checkoutExtraPayload.cash_receipt_requested": "{{$event.target.checked}}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
지켜야 할 것:
|
||||
|
||||
- 확장은 **자기 도메인 키만** 쓴다. spread 가 뒤에 오므로 템플릿의 기존 키를 덮어쓸 수 있다
|
||||
- 폼을 접거나 신청을 해제하면 칸을 `{}` 로 비운다. 남겨 두면 서버가 신청으로 오인한다
|
||||
- 템플릿이 소유한 필드(예: 환불계좌)는 칸을 경유하지 않고 body 에 직접 기재한다
|
||||
- body 를 통짜 표현식으로 전환할 때는 **전환 전후 산출값이 동일한지** 회귀 테스트로 고정한다 (`DataBindingEngine.evaluateExpression` 으로 실제 평가)
|
||||
|
||||
현재 열려 있는 칸:
|
||||
|
||||
| 칸 이름 | 위치 | 소비처 |
|
||||
|---------|------|--------|
|
||||
| `_local.checkoutExtraPayload` | `sirsoft-basic` 주문서 (`_checkout_summary.json`) | 주문 생성 `POST /user/orders` |
|
||||
|
||||
---
|
||||
|
||||
## 템플릿 오버라이드
|
||||
|
||||
@@ -283,6 +283,14 @@ class TemplateService
|
||||
가리키기 때문이다 — 차단하면 브라우저 콘솔에 404 가 쌓인다. `--production` 빌드는 소스맵을
|
||||
생성하지 않으므로(`G7_BUILD_SOURCEMAP=0`) 운영에서는 참조 자체가 없다.
|
||||
|
||||
이 주입이 실제로 먹으려면 확장의 vite config 가 그 환경변수를 읽어야 한다. `sourcemap: true`
|
||||
리터럴 하드코딩은 주입을 조용히 무시해 `--production` 빌드에도 `.map` 과 dangling 참조가
|
||||
배포본에 남는다. 확장 vite config 의 소스맵 선언은 다음 형태만 사용한다:
|
||||
|
||||
```ts
|
||||
sourcemap: !['0', 'false'].includes(process.env.G7_BUILD_SOURCEMAP ?? ''),
|
||||
```
|
||||
|
||||
판정 지점은 `Allowed{Module,Plugin,Template}FileType::getAllowedExtensions()` 한 곳이며,
|
||||
`validate()` 도 이 게터를 참조한다(상수 직접 참조 금지 — 환경 분기가 우회된다).
|
||||
|
||||
|
||||
@@ -265,6 +265,63 @@
|
||||
}
|
||||
```
|
||||
|
||||
#### 체크박스 — boolean 값 보장
|
||||
|
||||
자동 바인딩은 **현재 값이 boolean 일 때만** `checked` 로 바인딩한다 (`DynamicRenderer` 의 `isCheckedBinding`: `typeof currentValue === 'boolean'`). 값이 `null` 이나 `undefined` 면 `value` 바인딩으로 떨어져 **빈 문자열(`''`)이 전송**된다.
|
||||
|
||||
서버가 그 빈 문자열을 `null` 로 저장하면(Laravel `ConvertEmptyStringsToNull` + `nullable` 규칙) 이후 `array_merge(defaults, saved)` 에서 `null` 이 기본값 `false` 를 덮는다. 그러면 화면에는 계속 해제 상태로 보이고, 다시 켜도 또 빈 문자열이 나가 **영구 고착**된다.
|
||||
|
||||
`initLocal` 로는 막을 수 없다. 기본 병합은 shallow 라 데이터소스 응답이 `form` 객체를 통째로 교체하고, `_merge: "deep"` 을 써도 `deepMergeState` 가 `source` 의 `null` 을 그대로 반영한다.
|
||||
|
||||
따라서 **저장값이 boolean 이 아닐 수 있는 체크박스는 레이아웃이 boolean 을 직접 보장**한다:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "basic",
|
||||
"name": "Checkbox",
|
||||
"props": {
|
||||
"name": "method_card",
|
||||
"autoBinding": false,
|
||||
"checked": "{{!!_local.form?.method_card}}"
|
||||
},
|
||||
"actions": [
|
||||
{
|
||||
"type": "change",
|
||||
"handler": "setState",
|
||||
"params": {
|
||||
"target": "local",
|
||||
"form.method_card": "{{$event.target.checked}}",
|
||||
"hasChanges": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `autoBinding: false` — 자동 바인딩의 `value` 분기 개입을 차단한다
|
||||
- `checked: "{{!!...}}"` — 저장값이 `null` 이어도 `false` 로 렌더한다
|
||||
- `change` 액션 — `$event.target.checked` 는 항상 boolean 이므로 상태에 boolean 만 기록된다
|
||||
|
||||
저장값이 항상 boolean 임이 보장되는 경우(예: 서버가 `null` 을 반환하지 않고 마이그레이션으로 기본값이 채워진 컬럼)에는 `name` 만으로 자동 바인딩해도 된다.
|
||||
|
||||
#### 체크박스 — 라벨 표시
|
||||
|
||||
`Checkbox` 컴포넌트는 `label` prop 을 받지만 **렌더하지 않는다**. 표시는 부모 `Label` 이 담당한다. `label` prop 에만 의존하면 라벨이 화면에 나타나지 않으므로, `Label` 로 감싸고 텍스트를 형제 노드로 둔다.
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "basic",
|
||||
"name": "Label",
|
||||
"props": { "className": "flex items-center gap-2 cursor-pointer" },
|
||||
"children": [
|
||||
{ "type": "basic", "name": "Checkbox", "props": { "name": "agree_terms" } },
|
||||
{ "type": "basic", "name": "Span", "text": "$t:auth.register.agree_terms" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`Label` 로 감싸면 라벨 텍스트를 클릭해도 토글되고 접근성 이름이 부여된다.
|
||||
|
||||
#### 전역 상태 바인딩 (`_global.` 접두사)
|
||||
|
||||
> **버전**: engine-v1.3.0+
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
- 예약 작업에 등록할 수 없는 Artisan 명령·옵션을 안내하는 문구 일본어 번역 추가 — 왜 등록이 거부됐는지(허용 목록 밖 / 형식 오류 / 허용되지 않은 옵션 / 추가 인자 불가)가 사유별로 표시됩니다.
|
||||
- 언어팩 설치 시 거부 사유를 안내하는 문구 일본어 번역 추가 — 허용되지 않는 파일 형식, 번역 배열이 아닌 PHP 파일(줄 번호 포함), 심볼릭 링크, 그리고 설치 직후 활성화에 필요한 권한 안내입니다.
|
||||
- 환경설정 고급 탭의 목록 상한 항목명(총 건수 집계 상한·페이지 번호 상한) 일본어 번역 추가 — 값이 범위를 벗어났을 때의 안내에 내부 식별자 대신 항목명이 표시됩니다.
|
||||
- 공통 응답 메시지 일본어 번역 추가 (`common.created`·`common.updated`·`common.deleted`) — 생성·수정·삭제 성공 응답이 일본어 로케일에서 번역문으로 표시됩니다.
|
||||
- 본인인증 정책 삭제 제한 안내 메시지 일본어 번역 추가 (`identity.errors.cannot_delete_system_policy`) — 시스템이 선언한 정책은 삭제할 수 없다는 안내가 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
|
||||
### Changed
|
||||
|
||||
|
||||
@@ -30,4 +30,7 @@ return [
|
||||
'version_format' => ':attributeのフォーマットが正しくありません。(例:1.0.0、1.0.0-beta.1)',
|
||||
'to_version_required' => '開始バージョンが指定されている場合、終了バージョンも必須です。',
|
||||
],
|
||||
'created' => '作成されました。',
|
||||
'updated' => '編集されました。',
|
||||
'deleted' => '削除されました。',
|
||||
];
|
||||
@@ -29,6 +29,7 @@ return [
|
||||
'missing_scope_or_target' => 'ポリシー照会には scope と target の両方が必要です。',
|
||||
'admin_policy_has_no_default' => '管理者が直接作成したポリシーには宣言デフォルト値がありません。',
|
||||
'reset_field_failed' => '宣言デフォルト値の復元に失敗しました。フィールドが有効であることを確認してください。',
|
||||
'cannot_delete_system_policy' => 'システムが宣言したポリシーは削除できません。管理者が直接作成したポリシーのみ削除できます。',
|
||||
],
|
||||
'messages' => [
|
||||
'challenge_requested' => '本人認証コードを送信しました。',
|
||||
|
||||
@@ -4,6 +4,18 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.1.0] - 2026-08-06
|
||||
|
||||
### Added
|
||||
|
||||
- 현금영수증 관련 문구(`cash_receipt.*` — 발급 용도, 식별번호 종류, 발급/취소 이력 상태, 배송비 과세 방식, 오류 안내) 일본어 번역 추가 — 현금영수증 발급 화면과 이커머스 환경설정이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 현금영수증 발급 요청의 입력 항목명·검증 안내·처리 결과 문구(`cash_receipt.attributes.*`, `cash_receipt.validation.*`, `cash_receipt.messages.*`)와 발급 불가 사유 안내(`cash_receipt.errors.*`) 일본어 번역 추가 — 잘못된 식별번호를 입력했을 때의 안내와 발급·취소 결과 메시지가 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 주문서의 현금영수증 신청 폼 문구(`checkout.cash_receipt.*` — 신청 여부, 발급 용도, 발급 수단, 입력 안내) 일본어 번역 추가 — 무통장입금으로 주문할 때 현금영수증을 신청하는 화면이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 주문 상세의 현금영수증 카드 문구(발급 상태 안내, 발급·발급취소·재발급 버튼, 발급 이력 표) 일본어 번역 추가 — 구매자와 관리자가 보는 현금영수증 영역이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 환불 계좌 입력 안내와 검증 문구(`validation.order.refund_bank_*`) 일본어 번역 추가 — 주문서와 관리자 취소 화면의 환불 계좌 입력란이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 현금영수증 자진발급 설정의 국세청 의무발행 업종 안내 링크 문구(`order_settings.cash_receipt.self_issue_mandatory_link`) 일본어 번역 추가 — 자진발급을 켤지 판단할 때 참고하는 국세청 안내 링크가 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 카테고리 이미지 처리 결과 안내 문구(`category_images.*` — 업로드·삭제·순서 변경·이미지 없음) 일본어 번역 추가 — 관리자가 카테고리 이미지를 등록·삭제·정렬할 때의 안내가 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
|
||||
## [1.0.8] - 2026-08-01
|
||||
|
||||
### Added
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'type' => [
|
||||
'income' => '所得控除用',
|
||||
'expense' => '支出証明用',
|
||||
],
|
||||
'identifier_type' => [
|
||||
'phone' => '携帯電話番号',
|
||||
'card' => '現金領収書カード番号',
|
||||
'business' => '事業者登録番号',
|
||||
],
|
||||
'transaction_type' => [
|
||||
'issue' => '発行',
|
||||
'cancel' => 'キャンセル',
|
||||
],
|
||||
'issue_status' => [
|
||||
'in_progress' => '処理中',
|
||||
'completed' => '発行完了',
|
||||
'failed' => '発行失敗',
|
||||
],
|
||||
'shipping_fee_tax_policy' => [
|
||||
'proportional' => '按分 (課税商品の比率に応じて課税)',
|
||||
'taxable' => '全額課税',
|
||||
'follow_main_item' => '主要な財を従う',
|
||||
],
|
||||
'errors' => [
|
||||
'provider_not_configured' => '現金領収書発行プロバイダーが設定されていません。',
|
||||
'no_provider_handled' => '現金領収書発行リクエストを処理したプロバイダーがありません。',
|
||||
'no_issuable_amount' => '発行可能な現金性金額がありません。',
|
||||
'identifier_unavailable' => '再発行に必要な識別番号を復号化できません。管理者が識別番号を再入力して発行する必要があります。',
|
||||
'payment_not_found' => '決済情報が見つかりません。',
|
||||
'not_cash_payment' => '銀行振込注文のみ現金領収書を発行できます。',
|
||||
'payment_not_paid' => '入金が確認された注文のみ現金領収書を発行できます。',
|
||||
'already_issued' => '既に現金領収書が発行された注文です。',
|
||||
'issue_failed' => '現金領収書の発行に失敗しました。',
|
||||
'cancel_failed' => '現金領収書のキャンセルに失敗しました。',
|
||||
'no_active_receipt' => 'キャンセルする現金領収書がありません。',
|
||||
],
|
||||
'attributes' => [
|
||||
'receipt_type' => '発行目的',
|
||||
'identifier_type' => '発行手段',
|
||||
'identifier' => '識別番号',
|
||||
],
|
||||
'validation' => [
|
||||
'identifier_invalid' => '識別番号の形式が正しくありません。',
|
||||
'identifier_type_not_allowed' => ':type は :identifier_type で発行できません。',
|
||||
'self_issue_income_only' => '自進発行指定番号は所得控除用でのみ発行できます。',
|
||||
'identifier_format' => [
|
||||
'phone' => '携帯電話番号は010、011、016、017、018、019で始まる10~11桁の数字である必要があります。',
|
||||
'card' => '現金領収書カード番号は13~19桁の数字である必要があります。',
|
||||
'business' => '事業者登録番号が正しくありません。10桁の数字を確認してください。',
|
||||
],
|
||||
],
|
||||
'messages' => [
|
||||
'issued' => '現金領収書が発行されました。',
|
||||
'cancelled' => '現金領収書がキャンセルされました。',
|
||||
'reissued' => '現金領収書が再発行されました。',
|
||||
'status_retrieved' => '現金領収書情報を照会しました。',
|
||||
],
|
||||
'result_status' => [
|
||||
'in_progress' => '処理中',
|
||||
'completed' => '完了',
|
||||
'failed' => '失敗',
|
||||
],
|
||||
];
|
||||
@@ -15,12 +15,6 @@ return [
|
||||
'status_changed' => 'カテゴリの状態が変更されました。',
|
||||
'order_updated' => 'カテゴリの順序が変更されました。',
|
||||
],
|
||||
'category_images' => [
|
||||
'uploaded' => 'カテゴリ画像がアップロードされました。',
|
||||
'not_found' => 'カテゴリ画像が見つかりません。',
|
||||
'deleted' => 'カテゴリ画像が削除されました。',
|
||||
'reordered' => 'カテゴリ画像の順序が変更されました。',
|
||||
],
|
||||
'settings' => [
|
||||
'fetch_success' => '設定を閲覧しました。',
|
||||
'fetch_failed' => '設定の取得に失敗しました。',
|
||||
@@ -79,6 +73,12 @@ return [
|
||||
'thumbnail_set' => 'メイン画像が設定されました。',
|
||||
'not_found' => '商品画像が見つかりません。',
|
||||
],
|
||||
'category_images' => [
|
||||
'uploaded' => '画像がアップロードされました。',
|
||||
'deleted' => '画像が削除されました。',
|
||||
'reordered' => '画像の順序が変更されました。',
|
||||
'not_found' => 'カテゴリー画像が見つかりません。',
|
||||
],
|
||||
'brands' => [
|
||||
'list_retrieved' => 'ブランド一覧を閲覧しました。',
|
||||
'retrieved' => 'ブランド情報を閲覧しました。',
|
||||
|
||||
@@ -836,6 +836,13 @@ return [
|
||||
'guest_lookup_password_min' => '注文照会パスワードは8文字以上である必要があります。',
|
||||
'guest_lookup_password_confirmed' => '注文照会パスワードが一致しません。',
|
||||
'guest_lookup_password_confirmation_required' => '注文照会パスワード確認を入力してください。',
|
||||
'cash_receipt_type_required' => '現金領収証の発行目的を選択してください。',
|
||||
'cash_receipt_type_invalid' => '現金領収証の発行目的が正しくありません。',
|
||||
'cash_receipt_identifier_type_required' => '現金領収証の発行方法を選択してください。',
|
||||
'cash_receipt_identifier_type_invalid' => '現金領収証の発行方法が正しくありません。',
|
||||
'cash_receipt_identifier_required' => '現金領収証の発行に使用する番号を入力してください。',
|
||||
'refund_bank_required_with' => '返金口座は銀行·口座番号·預金者をすべて入力する必要があります。',
|
||||
'refund_bank_required_for_vbank' => '入金が完了した仮想口座注文は返金口座が必要です。',
|
||||
],
|
||||
'order_bulk' => [
|
||||
'ids_required' => '変更する注文を選択してください。',
|
||||
|
||||
@@ -165,7 +165,8 @@
|
||||
"seoStats": "SEO統計",
|
||||
"settings": "設定",
|
||||
"shipping_policies": "配送ポリシー一覧",
|
||||
"templates": "テンプレート一覧"
|
||||
"templates": "テンプレート一覧",
|
||||
"paymentSettings": "決済環境設定"
|
||||
},
|
||||
"action": {
|
||||
"request_pg_payment": {
|
||||
@@ -195,5 +196,19 @@
|
||||
"label": "配送国",
|
||||
"hint": "基本配送国です。登録後、マイ情報で変更できます。"
|
||||
}
|
||||
},
|
||||
"checkout": {
|
||||
"cash_receipt": {
|
||||
"request": "現金領収証申請",
|
||||
"purpose": "用途",
|
||||
"purpose_income": "所得控除用",
|
||||
"purpose_expense": "支出証明用",
|
||||
"identifier_phone": "携帯電話番号",
|
||||
"identifier_card": "現金領収証カード番号",
|
||||
"identifier_business": "事業者登録番号",
|
||||
"identifier_placeholder": "- なしで数字のみ入力",
|
||||
"purpose_help": "所得控除用は年末調整に、支出証明用は事業者の仕入税額控除に使用されます。",
|
||||
"immutable_help": "発行後は用途を変更することはできません。"
|
||||
}
|
||||
}
|
||||
}
|
||||
+39
-1
@@ -419,7 +419,13 @@
|
||||
"close_btn": "閉じる",
|
||||
"estimate_failed": "返金予想金額の計算に失敗しました。",
|
||||
"cancel_success": "注文がキャンセルされました。",
|
||||
"cancel_failed": "注文のキャンセルに失敗しました。"
|
||||
"cancel_failed": "注文のキャンセルに失敗しました。",
|
||||
"refund_bank_label": "返金口座",
|
||||
"refund_bank_select": "銀行を選択",
|
||||
"refund_bank_account_placeholder": "口座番号 (ハイフンなしで入力)",
|
||||
"refund_bank_holder_placeholder": "口座名義人",
|
||||
"refund_bank_required_hint": "入金が完了した仮想口座注文は返金口座が必要です。",
|
||||
"refund_bank_partial_notice": "3つのうちいずれかを入力した場合は、残りも入力する必要があります。"
|
||||
},
|
||||
"reset_guest_password": {
|
||||
"title": "非会員閲覧パスワード再設定",
|
||||
@@ -450,6 +456,38 @@
|
||||
"mark_order_complete": "注文を決済完了として処理",
|
||||
"mark_order_complete_hint": "チェックすると入金記録とともに注文ステータスを決済完了に変更します(ポイント積立·在庫減少·通知送信含む)。チェックしないと入金内訳のみ記録します。"
|
||||
}
|
||||
},
|
||||
"cash_receipt": {
|
||||
"title": "現金領収書",
|
||||
"issue_title": "現金領収書発行",
|
||||
"status_issued": "発行完了",
|
||||
"awaiting_deposit": "入金が確認されたら発行できます。",
|
||||
"purpose": "用途",
|
||||
"purpose_income": "所得控除用",
|
||||
"purpose_expense": "支出証拠用",
|
||||
"identifier_type": "発行手段",
|
||||
"identifier": "識別番号",
|
||||
"identifier_phone": "携帯電話番号",
|
||||
"identifier_card": "現金領収書カード番号",
|
||||
"identifier_business": "事業者登録番号",
|
||||
"identifier_placeholder": "ハイフンなしで数字のみ入力",
|
||||
"immutable_help": "発行後は用途を変更することはできません。",
|
||||
"amount": "金額",
|
||||
"tax_free_amount": "非課税金額",
|
||||
"issue_number": "発行番号",
|
||||
"issued_at": "発行日時",
|
||||
"issue": "現金領収書発行",
|
||||
"cancel": "キャンセル",
|
||||
"cancel_issue": "発行取消",
|
||||
"reissue": "手動再発行",
|
||||
"view_receipt": "領収書を表示",
|
||||
"history": "発行履歴 ({{count}}件)",
|
||||
"issue_success": "現金領収書が発行されました。",
|
||||
"issue_failed": "現金領収書の発行に失敗しました。",
|
||||
"cancel_success": "現金領収書の発行がキャンセルされました。",
|
||||
"cancel_failed": "現金領収書の発行キャンセルに失敗しました。",
|
||||
"reissue_failed": "再発行失敗",
|
||||
"reissue_success": "現金領収書が再発行されました。"
|
||||
}
|
||||
},
|
||||
"preset": {
|
||||
|
||||
+17
@@ -224,6 +224,23 @@
|
||||
"restore_on_cancel": "注文キャンセル時の在庫復旧",
|
||||
"restore_on_cancel_description": "注文がキャンセルされると、差し引かれた在庫を自動的に復旧します。",
|
||||
"restore_on_cancel_hint": "返品·交換処理時にも適用されます。"
|
||||
},
|
||||
"cash_receipt": {
|
||||
"title": "現金領収証",
|
||||
"description": "現金領収証の発行プロバイダーと配送料の課税方式を設定します。",
|
||||
"provider_label": "現金領収証プロバイダー",
|
||||
"provider_none": "(未使用)",
|
||||
"provider_not_installed": "決済プラグインを有効化すると、発行プロバイダーを選択できます。",
|
||||
"provider_help": "決済に使用するPGとは別に選択できます。",
|
||||
"shipping_fee_tax_label": "配送料の課税方式",
|
||||
"shipping_fee_tax_proportional": "按分 (デフォルト)",
|
||||
"shipping_fee_tax_taxable": "全額課税",
|
||||
"shipping_fee_tax_follow_main_item": "主要な財貨基準",
|
||||
"shipping_fee_tax_help": "按分は、課税·非課税商品の金額比率で配送料を分割します。",
|
||||
"self_issue_label": "自進発行の使用",
|
||||
"self_issue_help": "購入者が申請していない無通帳入金建も自動で発行します (所得控除用専用)。",
|
||||
"self_issue_mandatory_help": "現金領収証の義務発行業種は、購入者が申請しなくても発行義務があります。該当業種であればオンにしてください。",
|
||||
"self_issue_mandatory_link": "国税庁の義務発行業種案内"
|
||||
}
|
||||
},
|
||||
"claim": {
|
||||
|
||||
@@ -12,5 +12,29 @@
|
||||
"delivered": "配送完了",
|
||||
"cancelled": "キャンセル済み",
|
||||
"refunded": "返金済み"
|
||||
},
|
||||
"cash_receipt": {
|
||||
"title": "現金領収証",
|
||||
"issue_title": "現金領収証の発行",
|
||||
"purpose": "用途",
|
||||
"purpose_income": "所得控除用",
|
||||
"purpose_expense": "支出証明用",
|
||||
"identifier_type": "発行手段",
|
||||
"identifier": "識別番号",
|
||||
"identifier_phone": "電話番号",
|
||||
"identifier_card": "現金領収証カード番号",
|
||||
"identifier_business": "事業者登録番号",
|
||||
"identifier_placeholder": "ハイフンなしで数字のみを入力",
|
||||
"immutable_help": "発行後は用途を変更することはできません。",
|
||||
"awaiting_deposit": "入金が確認されると発行されます。",
|
||||
"none": "発行された現金領収証がありません。",
|
||||
"issue": "現金領収証の発行",
|
||||
"cancel": "キャンセル",
|
||||
"issued_at": "発行日時",
|
||||
"view_receipt": "領収証を表示",
|
||||
"issue_success": "現金領収証が発行されました。",
|
||||
"issue_failed": "現金領収証の発行に失敗しました。",
|
||||
"reissue_failed": "再発行失敗",
|
||||
"reissue_failed_help": "返金に伴う現金領収証の再発行に失敗しました。カスタマーサポートにお問い合わせください。"
|
||||
}
|
||||
}
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 module (sirsoft-ecommerce) Japanese language pack (bundled)",
|
||||
"ja": "G7 モジュール (sirsoft-ecommerce) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.8",
|
||||
"version": "1.1.0",
|
||||
"license": "MIT",
|
||||
"scope": "module",
|
||||
"target_identifier": "sirsoft-ecommerce",
|
||||
|
||||
@@ -4,6 +4,16 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.1.0] - 2026-08-06
|
||||
|
||||
### Added
|
||||
|
||||
- 현금영수증 발급사 이름(`cash_receipt.provider_name`) 일본어 번역 추가.
|
||||
|
||||
### Removed
|
||||
|
||||
- KG이니시스 전용 현금영수증 발행 화면이 제거되면서 함께 쓰이지 않게 된 발행 오류 안내 3종의 번역을 정리했습니다.
|
||||
|
||||
## [1.0.3] - 2026-07-22
|
||||
|
||||
### Added
|
||||
|
||||
@@ -2,9 +2,6 @@
|
||||
|
||||
return [
|
||||
'errors' => [
|
||||
'cash_receipt_invalid_issue_type' => '発行タイプが正しくありません。',
|
||||
'cash_receipt_missing_issue_number' => '識別番号を入力してください。',
|
||||
'cash_receipt_already_issued' => 'すでに現金領収書が発行された決済です。',
|
||||
'cash_receipt_issue_failed' => '現金領収書の発行に失敗しました。',
|
||||
'order_not_found' => '注文が見つかりません。',
|
||||
'cbt_failed' => '海外決済の処理に失敗しました。',
|
||||
@@ -39,6 +36,9 @@ return [
|
||||
'japan_contact_opening_hours_required' => 'ライブ日本決済画面に表示するお問い合わせ営業時間が必要です。',
|
||||
'replace_sample_value' => 'ライブモードではサンプル値の代わりに実際の契約情報を入力してください。',
|
||||
],
|
||||
'cash_receipt' => [
|
||||
'provider_name' => 'KGイニシス',
|
||||
],
|
||||
'cbt_cvs' => [
|
||||
'simulate_success' => '入金シミュレーションが完了しました。',
|
||||
'simulate_failed' => '入金シミュレーションに失敗しました。',
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 plugin (sirsoft-pay_kginicis) Japanese language pack (bundled)",
|
||||
"ja": "G7 プラグイン (sirsoft-pay_kginicis) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.3",
|
||||
"version": "1.1.0",
|
||||
"license": "MIT",
|
||||
"scope": "plugin",
|
||||
"target_identifier": "sirsoft-pay_kginicis",
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
# Changelog
|
||||
|
||||
이 언어팩의 모든 주요 변경사항을 기록합니다.
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.0] - 2026-07-13
|
||||
|
||||
### Added
|
||||
|
||||
- 현금영수증 발급·취소 안내와 오류 메시지 일본어 번역 추가 — 일본어 로케일에서 현금영수증 발급 결과와 실패 사유가 일본어로 표시됩니다.
|
||||
- 환불 관련 안내(에스크로 부분취소 불가·환불 계좌 누락) 일본어 번역 추가.
|
||||
- 결제 화면 프론트엔드 텍스트 일본어 번역 추가 — 결제 관련 화면이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
- 주문서형 결제수단(카드·가상계좌·계좌이체·휴대폰·간편결제 9종)의 이름과 설명 일본어 번역 추가 — 일본어 로케일 주문서에서 결제수단이 일본어로 표시됩니다.
|
||||
- 관리자 설정 화면의 결제 방식·가상계좌·에스크로 항목과 입력값 오류 안내 일본어 번역 추가.
|
||||
|
||||
## [1.0.0-beta.1] - 2026-05-11
|
||||
|
||||
### Added
|
||||
|
||||
- 토스페이먼츠 플러그인(sirsoft-tosspayments)의 일본어 번들 언어팩 초기 제공
|
||||
@@ -0,0 +1,19 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'refund' => [
|
||||
'missing_payment_key' => 'Toss Payments の決済キーが存在しないため、返金処理ができません。',
|
||||
'default_reason' => '顧客リクエストによるキャンセル',
|
||||
'escrow_partial_not_allowed' => 'エスクロー決済は部分キャンセルに対応していません。全額キャンセルのみ可能です。',
|
||||
'missing_refund_account' => '仮想口座決済をキャンセルするには、返金を受け取る口座情報(銀行、口座番号、預金者名)が必要です。',
|
||||
],
|
||||
'settings_validation' => [
|
||||
'vbank_valid_hours_range' => '仮想口座の入金期限は :min~:max時間(最大90日)の間である必要があります。',
|
||||
'use_escrow_invalid' => 'エスクロー使用設定値が正しくありません。',
|
||||
],
|
||||
'cash_receipt' => [
|
||||
'provider_name' => 'Toss Payments',
|
||||
'invalid_order_id' => '現金領収書発行識別子がToss Payments形式(英数字·ハイフン·アンダースコア 6~64文字)に一致していません。',
|
||||
'cancel_reason' => '注文金額変更に伴う再発行',
|
||||
],
|
||||
];
|
||||
@@ -0,0 +1,40 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'toss_card' => [
|
||||
'name' => 'クレジットカード (Toss Payments)',
|
||||
'description' => 'クレジット·デビットカードで決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_virtual_account' => [
|
||||
'name' => '仮想口座 (Toss Payments)',
|
||||
'description' => '発行された仮想口座への入金 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_transfer' => [
|
||||
'name' => '口座振替 (Toss Payments)',
|
||||
'description' => 'リアルタイム口座振替で決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_mobile_phone' => [
|
||||
'name' => '携帯電話決済 (Toss Payments)',
|
||||
'description' => '携帯電話小額決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_tosspay' => [
|
||||
'name' => 'Toss Pay (Toss Payments)',
|
||||
'description' => 'Toss Pay簡便決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_kakaopay' => [
|
||||
'name' => 'Kakao Pay (Toss Payments)',
|
||||
'description' => 'Kakao Pay簡便決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_naverpay' => [
|
||||
'name' => 'NAVER Pay (Toss Payments)',
|
||||
'description' => 'NAVER Pay簡便決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_payco' => [
|
||||
'name' => 'Payco (Toss Payments)',
|
||||
'description' => 'Payco簡便決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
'toss_samsungpay' => [
|
||||
'name' => 'Samsung Pay (Toss Payments)',
|
||||
'description' => 'Samsung Pay簡便決済 — Toss Paymentsを通じて処理',
|
||||
],
|
||||
];
|
||||
@@ -0,0 +1,6 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'name' => 'Toss Payments',
|
||||
'description' => '国内PG会社 Toss Payments 決済連動',
|
||||
];
|
||||
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"editor": {
|
||||
"data_source": {
|
||||
"settings": "決済設定"
|
||||
}
|
||||
},
|
||||
"plugin_name": "Toss Payments",
|
||||
"plugin_description": "Toss Payments決済ゲートウェイ (統合決済窓連携)",
|
||||
"settings": {
|
||||
"title": "Toss Payments設定",
|
||||
"description": "Toss Payments API キーを設定します。",
|
||||
"test_mode": "テストモード",
|
||||
"test_mode_hint": "テストモードでは実際の決済が発生しません。",
|
||||
"test_client_key": "テストクライアントキー",
|
||||
"test_client_key_hint": "デベロッパーセンター > API 個別連携キーで確認",
|
||||
"test_secret_key": "テストシークレットキー",
|
||||
"test_secret_key_hint": "外部に露出しないようご注意ください。",
|
||||
"live_client_key": "ライブクライアントキー",
|
||||
"live_secret_key": "ライブシークレットキー",
|
||||
"live_secret_key_hint": "外部に露出しないようご注意ください。",
|
||||
"section_test_keys": "テストAPI キー",
|
||||
"section_live_keys": "ライブAPI キー",
|
||||
"section_redirect": "リダイレクト設定",
|
||||
"redirect_success_url": "決済成功リダイレクトURL",
|
||||
"redirect_success_url_hint": "相対パス(/shop/...) または完全URL(https://...) の両方が可能です。{orderId}は実際の注文番号に自動置換されます。",
|
||||
"redirect_fail_url": "決済失敗リダイレクトURL",
|
||||
"redirect_fail_url_hint": "相対パス または完全URL の両方が可能です。エラー情報(error, message, orderId)はクエリパラメーターとして自動追加されます。",
|
||||
"save": "保存",
|
||||
"saved": "設定が保存されました。",
|
||||
"section_payment_methods": "決済方法",
|
||||
"order_sheet_mode": "注文書形式の決済",
|
||||
"order_sheet_mode_hint": "有効にするとチェックアウト時に決済方法を直接選択します。無効にするとToss統合決済ウィンドウ(カード)で処理されます。",
|
||||
"enabled_methods": "表示する決済方法",
|
||||
"enabled_methods_hint": "注文書形式の決済時にチェックアウトに表示する決済方法を選択します。",
|
||||
"method_card": "カード",
|
||||
"method_virtual_account": "仮想口座",
|
||||
"method_transfer": "口座振替",
|
||||
"method_mobile_phone": "携帯電話",
|
||||
"method_tosspay": "Tossペイ",
|
||||
"method_kakaopay": "KakaoPayカード",
|
||||
"method_naverpay": "Naver Pay",
|
||||
"method_payco": "PayCo",
|
||||
"method_samsungpay": "Samsung Pay",
|
||||
"section_virtual_account": "仮想口座",
|
||||
"vbank_valid_hours": "入金期限(時間)",
|
||||
"vbank_valid_hours_hint": "仮想口座発行後の入金可能時間です。最大2160時間(90日)です。",
|
||||
"vbank_cash_receipt_type": "現金領収書自動発行タイプ",
|
||||
"vbank_cash_receipt_type_hint": "仮想口座発行時にTossが自動発行する現金領収書のタイプです。",
|
||||
"vbank_cash_receipt_none": "発行しない",
|
||||
"vbank_cash_receipt_income": "所得控除",
|
||||
"vbank_cash_receipt_expense": "支出証明",
|
||||
"use_escrow": "エスクロー使用",
|
||||
"use_escrow_hint": "仮想口座・口座振替決済にのみ適用されます。",
|
||||
"use_escrow_off": "使用しない",
|
||||
"use_escrow_on": "強制使用",
|
||||
"use_escrow_buyer_choice": "購入者選択",
|
||||
"escrow_no_partial_cancel_notice": "エスクロー注文は部分キャンセルができません。全体キャンセルのみ可能です。",
|
||||
"escrow_shipping_info_notice": "配送情報はToss店舗管理者で登録してください。",
|
||||
"escrow_shipping_info_link": "リンク ↗",
|
||||
"webhook_secret_verify": "ウェブフック secret 検証",
|
||||
"webhook_secret_verify_hint": "仮想口座入金通知ウェブフックの secret を決済承認レスポンスと照合し、不正なリクエストをブロックします。",
|
||||
"webhook_url_label": "仮想口座入金通知ウェブフック URL",
|
||||
"webhook_url_hint": "上記のパスの前に店舗全体のドメイン(https://myドメイン)を付けて、Toss開発者センター > ウェブフック メニューの DEPOSIT_CALLBACK イベントとして登録してください。",
|
||||
"webhook_url_copy": "コピー",
|
||||
"webhook_url_copied": "ウェブフック URL がコピーされました。"
|
||||
},
|
||||
"payment_error_title": "決済エラー",
|
||||
"payment_cancel_title": "決済キャンセル",
|
||||
"payment_cancelled_message": "決済がキャンセルされました。もう一度決済をお試しいただくか、別の決済方法をお選びください。",
|
||||
"errors": {
|
||||
"confirm_failed": "決済承認に失敗しました。",
|
||||
"amount_mismatch": "決済金額が一致しません。",
|
||||
"order_not_found": "注文が見つかりません。",
|
||||
"payment_failed": "決済に失敗しました。",
|
||||
"non_krw_method": "この決済方法はウォン(KRW)決済にのみ使用できます。"
|
||||
},
|
||||
"user": {
|
||||
"payment_type_label": "決済方法",
|
||||
"escrow_yes": "エスクロー",
|
||||
"receipt_label": "領収書",
|
||||
"receipt_view": "領収書を表示",
|
||||
"cash_receipt_label": "現金領収書",
|
||||
"cash_receipt_view": "現金領収書を表示"
|
||||
},
|
||||
"admin": {
|
||||
"payment_panel_title": "Toss Payments決済情報",
|
||||
"escrow_label": "決済方法",
|
||||
"escrow_yes": "エスクロー",
|
||||
"vbank_label": "仮想口座",
|
||||
"vbank_due_label": "入金期限",
|
||||
"receipt_label": "領収書",
|
||||
"receipt_view": "領収書を表示"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
{
|
||||
"identifier": "g7-plugin-sirsoft-tosspayments-ja",
|
||||
"namespace": "g7",
|
||||
"vendor": "sirsoft",
|
||||
"name": {
|
||||
"ko": "G7 플러그인 (sirsoft-tosspayments) 일본어 언어팩",
|
||||
"en": "G7 plugin (sirsoft-tosspayments) Japanese language pack",
|
||||
"ja": "G7 プラグイン (sirsoft-tosspayments) 日本語 言語パック"
|
||||
},
|
||||
"description": {
|
||||
"ko": "G7 플러그인 (sirsoft-tosspayments) 일본어 언어팩 (번들)",
|
||||
"en": "G7 plugin (sirsoft-tosspayments) Japanese language pack (bundled)",
|
||||
"ja": "G7 プラグイン (sirsoft-tosspayments) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.0",
|
||||
"license": "MIT",
|
||||
"scope": "plugin",
|
||||
"target_identifier": "sirsoft-tosspayments",
|
||||
"locale": "ja",
|
||||
"locale_name": "Japanese",
|
||||
"locale_native_name": "日本語",
|
||||
"text_direction": "ltr",
|
||||
"g7_version": ">=7.0.0-beta.4",
|
||||
"requires": {
|
||||
"target_version": null,
|
||||
"depends_on_core_locale": true
|
||||
},
|
||||
"github_url": "",
|
||||
"github_changelog_url": ""
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"name": "Toss Payments",
|
||||
"description": "Toss Payments 決済ゲートウェイ (統合決済窓口連携)"
|
||||
}
|
||||
@@ -4,6 +4,12 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.1.0] - 2026-08-06
|
||||
|
||||
### Added
|
||||
|
||||
- 주문서의 환불 계좌 입력란 문구(`shop.checkout.refund_bank_*` — 안내 제목, 은행 선택, 계좌번호·예금주 입력 안내, 부분 입력 주의) 일본어 번역 추가 — 무통장입금·가상계좌로 주문할 때 환불받을 계좌를 남기는 영역이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
|
||||
## [1.0.2] - 2026-07-22
|
||||
|
||||
### Added
|
||||
|
||||
@@ -465,7 +465,12 @@
|
||||
"guest_token_issue_failed": "非会員照会認証準備に失敗しました。注文照会時に携帯電話とパスワードで再度ご確認ください。",
|
||||
"coupon_already_used": "他の商品に既に適用されています",
|
||||
"coupon_not_applied": "一部のクーポンを適用できないため除外されました。最小注文金額·使用回数·重複使用の条件を確認してください。",
|
||||
"shipping_country": "配送国家"
|
||||
"shipping_country": "配送国家",
|
||||
"refund_bank_title": "返金口座 (注文キャンセル時に使用、選択)",
|
||||
"refund_bank_select": "銀行を選択",
|
||||
"refund_bank_account_placeholder": "口座番号 (ハイフンなしで入力)",
|
||||
"refund_bank_holder_placeholder": "口座名義人",
|
||||
"refund_bank_partial_notice": "3つのいずれかを入力した場合、残りも入力する必要があります。"
|
||||
},
|
||||
"order_complete": {
|
||||
"page_title": "注文完了",
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 template (sirsoft-basic) Japanese language pack (bundled)",
|
||||
"ja": "G7 テンプレート (sirsoft-basic) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.2",
|
||||
"version": "1.1.0",
|
||||
"license": "MIT",
|
||||
"scope": "template",
|
||||
"target_identifier": "sirsoft-basic",
|
||||
|
||||
@@ -9,6 +9,9 @@ return [
|
||||
'unauthorized' => 'Authentication is required.',
|
||||
'forbidden' => 'Access denied.',
|
||||
'validation_failed' => 'Input validation failed.',
|
||||
'created' => 'Created successfully.',
|
||||
'updated' => 'Updated successfully.',
|
||||
'deleted' => 'Deleted successfully.',
|
||||
|
||||
// Button states
|
||||
'saving' => 'Saving...',
|
||||
|
||||
@@ -30,6 +30,7 @@ return [
|
||||
'missing_scope_or_target' => 'Both scope and target are required to resolve a policy.',
|
||||
'admin_policy_has_no_default' => 'Admin-created policies do not have a declared default.',
|
||||
'reset_field_failed' => 'Failed to reset the field to its declared default. Check if the field is valid.',
|
||||
'cannot_delete_system_policy' => 'System-declared policies cannot be deleted. Only administrator-created policies can be deleted.',
|
||||
],
|
||||
|
||||
'messages' => [
|
||||
|
||||
@@ -9,6 +9,9 @@ return [
|
||||
'unauthorized' => '인증이 필요합니다.',
|
||||
'forbidden' => '권한이 없습니다.',
|
||||
'validation_failed' => '입력 값 검증에 실패했습니다.',
|
||||
'created' => '생성되었습니다.',
|
||||
'updated' => '수정되었습니다.',
|
||||
'deleted' => '삭제되었습니다.',
|
||||
|
||||
// 버튼 상태
|
||||
'saving' => '저장 중...',
|
||||
|
||||
@@ -30,6 +30,7 @@ return [
|
||||
'missing_scope_or_target' => '정책 조회를 위해 scope 와 target 이 모두 필요합니다.',
|
||||
'admin_policy_has_no_default' => '관리자가 직접 생성한 정책에는 선언 기본값이 없습니다.',
|
||||
'reset_field_failed' => '선언 기본값 복원에 실패했습니다. 필드가 유효한지 확인하세요.',
|
||||
'cannot_delete_system_policy' => '시스템이 선언한 정책은 삭제할 수 없습니다. 관리자가 직접 생성한 정책만 삭제할 수 있습니다.',
|
||||
],
|
||||
|
||||
'messages' => [
|
||||
|
||||
@@ -335,11 +335,49 @@ HTTP/1.1 200
|
||||
}
|
||||
```
|
||||
|
||||
**응답 예시**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메모를 조회했습니다.",
|
||||
"data": {
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"uuid": "9f1c0b4e-3a2d-4c8e-9f77-0a1b2c3d4e5f",
|
||||
"title": "샘플 메모",
|
||||
"content": "메모 본문 내용",
|
||||
"created_at": "2026-04-21 09:00:00",
|
||||
"updated_at": "2026-04-21 09:00:00",
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
}
|
||||
],
|
||||
"meta": {
|
||||
"current_page": 1,
|
||||
"last_page": 3,
|
||||
"per_page": 10,
|
||||
"total": 21
|
||||
},
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 429 | Too Many Requests | `throttle:600,1` 초과 (분당 600회) |
|
||||
| 500 | Internal Server Error | 목록 조회 중 예외 발생 시 `messages.memo.fetch_failed` (`메모 조회에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -378,7 +416,7 @@ HTTP/1.1 200
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| id | path | string | 예 | — | 대상 리소스의 식별자 |
|
||||
| id | path | string | 예 | — | 조회할 메모의 고유번호(기본 키). `MemoService::getMemo($id)` 로 직접 조회하며 없으면 404 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -391,17 +429,47 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체(`MemoResource`)의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 메모 고유번호 (기본 키) |
|
||||
| uuid | string | `9f1c0b4e-3a2d-4c8e-9f77-0a1b2c3d4e5f` | 메모 UUID (외부 식별자, 36자) |
|
||||
| title | string | `샘플 메모` | 메모 제목 (최대 255자) |
|
||||
| content | string | `메모 본문 내용` | 메모 본문 |
|
||||
| created_at | string | `2026-04-21 09:00:00` | 생성 일시 (사용자 타임존 기준 `Y-m-d H:i:s`, 값이 없으면 필드 자체 생략) |
|
||||
| updated_at | string | `2026-04-21 09:00:00` | 수정 일시 (사용자 타임존 기준 `Y-m-d H:i:s`, 값이 없으면 필드 자체 생략) |
|
||||
| abilities | object | `{"can_create":false,"can_update":false,"can_delete":false}` | 권한 능력 (`gnuboard7-hello_module.memos.{create,update,delete}` 보유 여부). `MemoResource` 는 `ownerField()` 미정의 → `is_owner` 미포함 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메모를 조회했습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"uuid": "9f1c0b4e-3a2d-4c8e-9f77-0a1b2c3d4e5f",
|
||||
"title": "샘플 메모",
|
||||
"content": "메모 본문 내용",
|
||||
"created_at": "2026-04-21 09:00:00",
|
||||
"updated_at": "2026-04-21 09:00:00",
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | 해당 `id` 의 메모가 없는 경우 — `ModelNotFoundException` → `메모를 찾을 수 없습니다.` |
|
||||
| 429 | Too Many Requests | `throttle:600,1` 초과 (분당 600회) |
|
||||
| 500 | Internal Server Error | 조회 중 예외 발생 시 `메모 조회에 실패했습니다.` |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Activity Stats 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Board Activities 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Board Types 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -125,11 +125,30 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `5` | 게시판 유형 ID (기본 키) |
|
||||
| slug | string | `notice-board` | 유형 식별자 (basic, card, gallery 등) — 소문자로 시작하는 소문자/숫자/하이픈 조합 |
|
||||
| name | object | `{"ko":"공지형","en":"Notice"}` | 유형명 (다국어: `{"ko": "기본형", "en": "Basic List"}`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "게시판 유형이 생성되었습니다.",
|
||||
"data": {
|
||||
"id": 5,
|
||||
"slug": "notice-board",
|
||||
"name": {
|
||||
"ko": "공지형",
|
||||
"en": "Notice"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -159,7 +178,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/sirsoft-board/admin/board-types/2 HTTP/1.1
|
||||
DELETE /api/modules/sirsoft-board/admin/board-types/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -167,11 +186,17 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "게시판 유형이 삭제되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -179,7 +204,8 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.boards.create`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | 해당 `id` 의 게시판 유형이 없는 경우 (`게시판 유형을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 해당 유형을 사용 중인 게시판이 있는 경우 (`:count개 게시판에서 사용 중인 유형은 삭제할 수 없습니다.`) 또는 게시판 기본 유형(`basic_defaults.type`)으로 설정된 경우 (`기본값으로 설정된 유형은 삭제할 수 없습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -202,7 +228,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/modules/sirsoft-board/admin/board-types/2 HTTP/1.1
|
||||
PUT /api/modules/sirsoft-board/admin/board-types/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -215,11 +241,30 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `2` | 게시판 유형 ID (기본 키) |
|
||||
| slug | string | `basic` | 유형 식별자 (basic, card, gallery 등) — 수정되지 않음 |
|
||||
| name | object | `{"ko":"기본형","en":"Basic List"}` | 유형명 (다국어: `{"ko": "기본형", "en": "Basic List"}`) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "게시판 유형이 수정되었습니다.",
|
||||
"data": {
|
||||
"id": 2,
|
||||
"slug": "basic",
|
||||
"name": {
|
||||
"ko": "기본형",
|
||||
"en": "Basic List"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -227,8 +272,8 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.boards.create`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Board 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -54,7 +54,7 @@ FULLTEXT 연산자를 제거한 뒤 검색하며, 연산자만 입력한 경우
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments HTTP/1.1
|
||||
POST /api/modules/sirsoft-board/admin/board/{slug}/attachments HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -82,11 +82,46 @@ Content-Disposition: form-data; name="temp_key"
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드. FileUploader 컴포넌트 호환을 위해 파일 메타는 `data.data` 로 한 번 더 감싸집니다._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| data | object | `{"id":1,"hash":"apidocsmpl1", ...}` | 업로드된 첨부파일 메타 객체 (아래 하위 필드) |
|
||||
| data.id | integer | `1` | 첨부파일 기본 키 (게시판별 첨부 테이블의 내부 식별자) |
|
||||
| data.hash | string | `apidocsmpl1` | 첨부파일 해시 식별자 (다운로드/미리보기 URL 에 사용) |
|
||||
| data.original_filename | string | `apidoc-sample.png` | 사용자가 업로드한 원본 파일명 |
|
||||
| data.stored_filename | string | `—` | 스토리지에 실제 저장된 파일명 (충돌 방지용 내부 파일명) |
|
||||
| data.mime_type | string | `image/png` | 업로드 파일의 MIME 타입 |
|
||||
| data.size | integer | `2048` | 파일 크기 (바이트) |
|
||||
| data.url | string | `/api/modules/sirsoft-board/boards/apidoc-sample-board/attachment/apidocsmpl1` | 첨부파일 접근 URL (`AttachmentService::getUrl()` 산물) |
|
||||
| data.order | integer | `0` | 첨부파일 표시 순서 (0 부터 오름차순) |
|
||||
| data.created_at | string | `2026-07-08 10:41:34` | 업로드(생성) 일시 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "파일이 업로드되었습니다.",
|
||||
"data": {
|
||||
"data": {
|
||||
"id": 1,
|
||||
"hash": "apidocsmpl1",
|
||||
"original_filename": "apidoc-sample.png",
|
||||
"stored_filename": "apidocsmpl1.png",
|
||||
"mime_type": "image/png",
|
||||
"size": 2048,
|
||||
"url": "/api/modules/sirsoft-board/boards/apidoc-sample-board/attachment/apidocsmpl1",
|
||||
"order": 0,
|
||||
"created_at": "2026-07-08 10:41:34"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -94,8 +129,9 @@ Content-Disposition: form-data; name="temp_key"
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.attachments.upload`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 (슬러그에 해당하는 게시판 없음 — `게시판을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 500 | Internal Server Error | 업로드 처리 실패 (`파일 업로드에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -120,7 +156,7 @@ Content-Disposition: form-data; name="temp_key"
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/download/apidocsmpl1 HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/board/{slug}/attachments/download/{hash} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -128,11 +164,17 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 JSON 봉투를 반환하지 않습니다. 성공 시 파일 본문을 그대로 내려주는 `StreamedResponse`(바이너리 스트림)이며, `data` 구조가 없습니다. 실패 시에만 JSON 에러 봉투가 반환됩니다._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-404 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: image/png
|
||||
Content-Disposition: attachment; filename="apidoc-sample.png"
|
||||
|
||||
(바이너리 파일 내용)
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -140,7 +182,8 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.attachments.download`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | 슬러그에 해당하는 게시판이 없거나(`게시판을 찾을 수 없습니다.`), 해시에 해당하는 첨부가 없거나(`파일을 찾을 수 없습니다.`), 실제 파일이 스토리지에 없는 경우 |
|
||||
| 500 | Internal Server Error | 다운로드 처리 실패 (`파일 다운로드에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -165,7 +208,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/reorder HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/board/{slug}/attachments/reorder HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -180,11 +223,21 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "첨부파일 순서가 변경되었습니다.",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -192,8 +245,9 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.attachments.upload`)이 없는 경우 |
|
||||
| 404 | Not Found | 슬러그에 해당하는 게시판이 없는 경우 (`게시판을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 500 | Internal Server Error | 순서 변경 처리 실패 (`첨부파일 순서 변경에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -216,7 +270,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/attachments/1 HTTP/1.1
|
||||
DELETE /api/modules/sirsoft-board/admin/board/{slug}/attachments/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -224,9 +278,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -266,11 +318,14 @@ HTTP/1.1 200
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| slug | path | string | 예 | — | 대상 리소스의 slug (URL 친화 식별자) |
|
||||
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
| search | query | string | 아니오 | max 255 | 검색어 (지정한 검색 대상 필드에서 부분 일치) |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/board/{slug}/posts?page=1&per_page=1&search=%EC%98%88%EC%8B%9C%EA%B0%92 HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -414,6 +469,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -437,7 +493,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts HTTP/1.1
|
||||
POST /api/modules/sirsoft-board/admin/board/{slug}/posts HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -445,11 +501,120 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`PostResource` — 게시글 수정(PUT) 응답과 동일한 구조)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| category | null | `null` | 게시글 분류(카테고리) 문자열. 게시판이 카테고리를 쓰지 않거나 미지정 시 null (최대 50자). |
|
||||
| author | object | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자"}` | 작성자 사용자 객체 (uuid/name — author 관계 파생) |
|
||||
| is_notice | boolean | `false` | 공지 게시글 여부 |
|
||||
| is_secret | boolean | `false` | 비밀글 여부 |
|
||||
| content_mode | string | `html` | 본문 편집 모드. `html`(위지윅/HTML) 또는 `text`(평문). |
|
||||
| is_new | boolean | `true` | 신규(NEW) 표시 대상 여부 (게시판 `new_display_hours` 기준) |
|
||||
| status | string | `published` | 게시글 상태 코드. `published` / `blinded` / `deleted` 중 하나. |
|
||||
| status_label | string | `게시됨` | 상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
|
||||
| view_count | integer | `0` | 조회수 (집계) |
|
||||
| comment_count | integer | `0` | 댓글 수 (집계) |
|
||||
| reply_count | integer | `0` | 답변글 수 (집계) |
|
||||
| attachment_count | integer | `0` | 첨부파일 수 (집계) |
|
||||
| has_attachment | boolean | `false` | 첨부파일 보유 여부 |
|
||||
| thumbnail | null | `null` | 썸네일 이미지 URL/경로 (없으면 null) |
|
||||
| parent_id | null | `null` | 원글 ID (답변글일 때만 값 존재) |
|
||||
| depth | integer | `0` | 계층 트리에서의 깊이 (0 = 최상위) |
|
||||
| is_reply | boolean | `false` | 답변글 여부 |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| created_at_formatted | string | `방금 전` | `created_at` 값의 표시용 포맷 문자열 |
|
||||
| is_author | boolean | `true` | 현재 사용자가 작성자인지 여부 |
|
||||
| is_guest_post | boolean | `false` | 비회원 작성 게시글 여부 |
|
||||
| title | string | `API 문서 샘플 게시글` | 제목 |
|
||||
| content | string | `<p>API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.</p>` | 본문 내용 |
|
||||
| user_id | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 작성자 사용자 식별자 |
|
||||
| trigger_type | string | `user` | 상태 변경을 유발한 주체 (`report`/`admin`/`system`/`auto_hide`/`user`/`cascade`) |
|
||||
| updated_at | string | `2026-07-08 10:41:34` | 최종 수정 일시 |
|
||||
| deleted_at | null | `null` | 소프트 삭제 일시 (미삭제 시 null) |
|
||||
| ip_address | string | `127.0.0.1` | 작성 요청이 발생한 IP 주소 |
|
||||
| action_logs | array | `[]` | 블라인드/복원/삭제 처리 이력 목록. `admin.manage` 권한 보유자에게만 노출. |
|
||||
| board | null | `null` | 소속 게시판 정보 객체. board 관계 미로드 시 null. |
|
||||
| navigation | null | `null` | 이전/다음 게시글 이동 정보. 쓰기 응답에서는 계산하지 않아 null. |
|
||||
| parent | null | `null` | 원글 객체 (parent 관계 파생) |
|
||||
| comments | null | `null` | 댓글 목록. comments 관계 미로드 시 null. |
|
||||
| attachments | null | `null` | 첨부파일 목록. attachments 관계 미로드 시 null. |
|
||||
| replies | null | `null` | 답변글 목록. replies 관계 미로드 시 null. |
|
||||
| is_already_reported | boolean | `false` | 현재 사용자가 이미 신고한 게시글인지 여부 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_write":true,…}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "게시글이 등록되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"category": null,
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"is_guest": false
|
||||
},
|
||||
"is_notice": false,
|
||||
"is_secret": false,
|
||||
"content_mode": "html",
|
||||
"is_new": true,
|
||||
"status": "published",
|
||||
"status_label": "게시됨",
|
||||
"view_count": 0,
|
||||
"comment_count": 0,
|
||||
"reply_count": 0,
|
||||
"attachment_count": 0,
|
||||
"has_attachment": false,
|
||||
"thumbnail": null,
|
||||
"parent_id": null,
|
||||
"depth": 0,
|
||||
"is_reply": false,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"created_at_formatted": "방금 전",
|
||||
"is_author": true,
|
||||
"is_guest_post": false,
|
||||
"title": "API 문서 샘플 게시글",
|
||||
"content": "<p>API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.</p>",
|
||||
"user_id": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"trigger_type": "user",
|
||||
"updated_at": "2026-07-08 10:41:34",
|
||||
"deleted_at": null,
|
||||
"ip_address": "127.0.0.1",
|
||||
"action_logs": [],
|
||||
"board": null,
|
||||
"navigation": null,
|
||||
"parent": null,
|
||||
"comments": null,
|
||||
"attachments": null,
|
||||
"replies": null,
|
||||
"is_already_reported": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_write": true,
|
||||
"can_read_secret": true,
|
||||
"can_read_comments": true,
|
||||
"can_write_comments": true,
|
||||
"can_upload": true,
|
||||
"can_download": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -457,8 +622,9 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 제목/본문 길이, 금지 키워드, 작성 쿨다운, 원글(`parent_id`) 유효성 위반 포함 |
|
||||
| 500 | Internal Server Error | 게시글 생성 처리 실패 (`게시글 등록에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -476,11 +642,13 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| slug | path | string | 예 | — | 대상 리소스의 slug (URL 친화 식별자) |
|
||||
| post_id | query | integer | 아니오 | min 1 | post 식별자 |
|
||||
| parent_id | query | integer | 아니오 | min 1 | parent 식별자 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/form-data HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/board/{slug}/posts/form-data?post_id=1&parent_id=1 HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -529,6 +697,7 @@ HTTP/1.1 200
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 제목/본문 길이, 금지 키워드, 작성 쿨다운, 원글(`parent_id`) 유효성 위반 포함 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -550,7 +719,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/form-meta HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/board/{slug}/posts/form-meta HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -675,7 +844,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
|
||||
DELETE /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -810,7 +979,7 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write|sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write\|sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
@@ -834,7 +1003,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1094,7 +1263,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1 HTTP/1.1
|
||||
PUT /api/modules/sirsoft-board/admin/board/{slug}/posts/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1223,8 +1392,8 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.posts.write`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1248,7 +1417,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/blind HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{id}/blind HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1389,8 +1558,8 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1414,7 +1583,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/restore HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{id}/restore HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1427,11 +1596,127 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`PostResource` — 복원된 게시글. 게시글 수정(PUT) 응답과 동일한 구조이며, `status` 가 `published` 로 되돌아가고 `action_logs` 에 `restore` 이력이 1건 추가됩니다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| category | null | `null` | 게시글 분류(카테고리) 문자열 (미지정 시 null) |
|
||||
| author | object | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자"}` | 작성자 사용자 객체 (uuid/name — author 관계 파생) |
|
||||
| is_notice | boolean | `false` | 공지 게시글 여부 |
|
||||
| is_secret | boolean | `false` | 비밀글 여부 |
|
||||
| content_mode | string | `html` | 본문 편집 모드 (`html` / `text`) |
|
||||
| is_new | boolean | `true` | 신규(NEW) 표시 대상 여부 |
|
||||
| status | string | `published` | 복원 후 게시글 상태 (`published` 로 되돌아감) |
|
||||
| status_label | string | `게시됨` | 상태의 사람이 읽는 라벨 |
|
||||
| view_count | integer | `44` | 조회수 (집계) |
|
||||
| comment_count | integer | `0` | 댓글 수 (집계) |
|
||||
| reply_count | integer | `0` | 답변글 수 (집계) |
|
||||
| attachment_count | integer | `0` | 첨부파일 수 (집계) |
|
||||
| has_attachment | boolean | `false` | 첨부파일 보유 여부 |
|
||||
| thumbnail | null | `null` | 썸네일 이미지 URL/경로 |
|
||||
| parent_id | null | `null` | 원글 ID (답변글일 때만 값 존재) |
|
||||
| depth | integer | `0` | 계층 트리에서의 깊이 |
|
||||
| is_reply | boolean | `false` | 답변글 여부 |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| created_at_formatted | string | `4시간 전` | `created_at` 값의 표시용 포맷 문자열 |
|
||||
| is_author | boolean | `true` | 현재 사용자가 작성자인지 여부 |
|
||||
| is_guest_post | boolean | `false` | 비회원 작성 게시글 여부 |
|
||||
| title | string | `API 문서 샘플 게시글` | 제목 |
|
||||
| content | string | `<p>API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.</p>` | 본문 내용 |
|
||||
| user_id | string | `a234c2b1-cde8-437f-b28b-23323be2b98d` | 작성자 사용자 식별자 |
|
||||
| trigger_type | string | `admin` | 상태 변경을 유발한 주체 (복원은 관리자 직권이므로 `admin`) |
|
||||
| updated_at | string | `2026-07-08 15:01:45` | 최종 수정 일시 |
|
||||
| deleted_at | null | `null` | 소프트 삭제 일시 (복원 후 null) |
|
||||
| ip_address | string | `127.0.0.1` | 작성 요청이 발생한 IP 주소 |
|
||||
| action_logs | array | `[{"action":"restore","reason":null,"admin_name":"API 문서 샘플 사용자","created_at":"2026-07-08 06:01:45"}]` | 블라인드/복원/삭제 처리 이력 목록. `admin.manage` 권한 보유자에게만 노출. |
|
||||
| board | null | `null` | 소속 게시판 정보 객체 (관계 미로드 시 null) |
|
||||
| navigation | null | `null` | 이전/다음 게시글 이동 정보 (쓰기 응답은 미계산 → null) |
|
||||
| parent | null | `null` | 원글 객체 (parent 관계 파생) |
|
||||
| comments | null | `null` | 댓글 목록 (관계 미로드 시 null) |
|
||||
| attachments | null | `null` | 첨부파일 목록 (관계 미로드 시 null) |
|
||||
| replies | null | `null` | 답변글 목록 (관계 미로드 시 null) |
|
||||
| is_already_reported | boolean | `false` | 현재 사용자가 이미 신고한 게시글인지 여부 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
| abilities | object | `{"can_read":true,"can_write":true,…}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "게시글이 복원되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"category": null,
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"is_guest": false
|
||||
},
|
||||
"is_notice": false,
|
||||
"is_secret": false,
|
||||
"content_mode": "html",
|
||||
"is_new": true,
|
||||
"status": "published",
|
||||
"status_label": "게시됨",
|
||||
"view_count": 44,
|
||||
"comment_count": 0,
|
||||
"reply_count": 0,
|
||||
"attachment_count": 0,
|
||||
"has_attachment": false,
|
||||
"thumbnail": null,
|
||||
"parent_id": null,
|
||||
"depth": 0,
|
||||
"is_reply": false,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"created_at_formatted": "4시간 전",
|
||||
"is_author": true,
|
||||
"is_guest_post": false,
|
||||
"title": "API 문서 샘플 게시글",
|
||||
"content": "<p>API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.</p>",
|
||||
"user_id": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"trigger_type": "admin",
|
||||
"updated_at": "2026-07-08 15:01:45",
|
||||
"deleted_at": null,
|
||||
"ip_address": "127.0.0.1",
|
||||
"action_logs": [
|
||||
{
|
||||
"action": "restore",
|
||||
"reason": null,
|
||||
"admin_name": "API 문서 샘플 사용자",
|
||||
"created_at": "2026-07-08 06:01:45"
|
||||
}
|
||||
],
|
||||
"board": null,
|
||||
"navigation": null,
|
||||
"parent": null,
|
||||
"comments": null,
|
||||
"attachments": null,
|
||||
"replies": null,
|
||||
"is_already_reported": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_write": true,
|
||||
"can_read_secret": true,
|
||||
"can_read_comments": true,
|
||||
"can_write_comments": true,
|
||||
"can_upload": true,
|
||||
"can_download": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -1439,8 +1724,9 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 404 | Not Found | 슬러그에 해당하는 게시판 또는 ID 에 해당하는 게시글이 없는 경우 (`존재하지 않는 게시글입니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`reason` 이 1000자를 초과하는 등) |
|
||||
| 500 | Internal Server Error | 복원 처리 실패 (`게시글 복원에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1465,7 +1751,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments HTTP/1.1
|
||||
POST /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1473,20 +1759,91 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`CommentResource`)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 댓글 기본 키 (내부 식별자) |
|
||||
| post_id | integer | `1` | 댓글이 속한 게시글 식별자 |
|
||||
| parent_id | null | `null` | 상위 댓글 식별자 (대댓글일 때만 값 존재) |
|
||||
| content | string | `API 문서 샘플 댓글입니다.` | 댓글 본문 내용 |
|
||||
| author | object | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자"}` | 작성자 사용자 객체 (author 관계 파생) |
|
||||
| is_secret | boolean | `false` | 비밀 댓글 여부 |
|
||||
| status | string | `published` | 댓글 상태 코드 (`published` / `blinded` / `deleted`) |
|
||||
| status_label | string | `게시됨` | 상태의 사람이 읽는 라벨 (상태 Enum label() 산물) |
|
||||
| depth | integer | `0` | 댓글 계층 깊이 (0 = 최상위 댓글, 서비스에서 자동 계산) |
|
||||
| replies_count | integer | `0` | 이 댓글에 달린 대댓글 수 (집계) |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| created_at_formatted | string | `방금 전` | `created_at` 값의 표시용 포맷 문자열 |
|
||||
| updated_at | string | `2026-07-08 10:41:34` | 최종 수정 일시 |
|
||||
| deleted_at | null | `null` | 소프트 삭제 일시 (미삭제 시 null) |
|
||||
| is_cascade_deleted | boolean | `false` | 상위 게시글/댓글 삭제로 연쇄 삭제된 댓글인지 여부 |
|
||||
| ip_address | string | `127.0.0.1` | 작성 요청이 발생한 IP 주소 (권한자에게만 노출) |
|
||||
| action_logs | array | `[]` | 블라인드/복원/삭제 처리 이력 목록. `admin.manage` 권한 보유자에게만 노출. |
|
||||
| is_author | boolean | `true` | 현재 사용자가 작성자인지 여부 |
|
||||
| is_guest_comment | boolean | `false` | 비회원 작성 댓글 여부 |
|
||||
| is_already_reported | boolean | `false` | 현재 사용자가 이미 신고한 댓글인지 여부 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 (BaseApiResource 표준 메타) |
|
||||
| abilities | object | `{"can_read":true,"can_write":true,"can_manage":true}` | 현재 사용자가 이 댓글에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 201
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "댓글이 등록되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"post_id": 1,
|
||||
"parent_id": null,
|
||||
"content": "API 문서 샘플 댓글입니다.",
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"is_guest": false
|
||||
},
|
||||
"is_secret": false,
|
||||
"status": "published",
|
||||
"status_label": "게시됨",
|
||||
"depth": 0,
|
||||
"replies_count": 0,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"created_at_formatted": "방금 전",
|
||||
"updated_at": "2026-07-08 10:41:34",
|
||||
"deleted_at": null,
|
||||
"is_cascade_deleted": false,
|
||||
"ip_address": "127.0.0.1",
|
||||
"action_logs": [],
|
||||
"is_author": true,
|
||||
"is_guest_comment": false,
|
||||
"is_already_reported": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_write": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없거나, 게시판의 댓글 기능이 꺼진 경우 (`이 게시판은 댓글 기능이 비활성화되어 있습니다.`) |
|
||||
| 404 | Not Found | 슬러그에 해당하는 게시판이 없는 경우 (`게시판을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 댓글 길이, 금지 키워드, 작성 쿨다운, 대상 게시글·상위 댓글 유효성 위반 포함 |
|
||||
| 500 | Internal Server Error | 댓글 생성 처리 실패 (`댓글 등록에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1510,7 +1867,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
|
||||
DELETE /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1518,9 +1875,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -1541,8 +1896,9 @@ HTTP/1.1 200
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write|sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write\|sirsoft-board.{slug}.admin.manage`)이 없거나, 타인/비회원 댓글을 `admin.manage` 없이 삭제하려는 경우(`접근 권한이 없습니다.`), 게시판의 댓글 기능이 꺼진 경우(`이 게시판은 댓글 기능이 비활성화되어 있습니다.`) |
|
||||
| 404 | Not Found | ID 에 해당하는 댓글 또는 슬러그에 해당하는 게시판이 없는 경우 (`댓글을 찾을 수 없습니다.`) |
|
||||
| 500 | Internal Server Error | 삭제 처리 실패 (`댓글 삭제에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1568,7 +1924,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1 HTTP/1.1
|
||||
PUT /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1576,20 +1932,91 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`CommentResource` — 댓글 생성/블라인드 응답과 동일한 구조)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 댓글 기본 키 (내부 식별자) |
|
||||
| post_id | integer | `1` | 댓글이 속한 게시글 식별자 |
|
||||
| parent_id | null | `null` | 상위 댓글 식별자 (대댓글일 때만 값 존재) |
|
||||
| content | string | `API 문서 샘플 댓글입니다. (수정)` | 수정된 댓글 본문 내용 |
|
||||
| author | object | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자"}` | 작성자 사용자 객체 (author 관계 파생) |
|
||||
| is_secret | boolean | `false` | 비밀 댓글 여부 |
|
||||
| status | string | `published` | 댓글 상태 코드 (`published` / `blinded` / `deleted`) |
|
||||
| status_label | string | `게시됨` | 상태의 사람이 읽는 라벨 |
|
||||
| depth | integer | `0` | 댓글 계층 깊이 (0 = 최상위 댓글) |
|
||||
| replies_count | integer | `0` | 이 댓글에 달린 대댓글 수 (집계) |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| created_at_formatted | string | `4시간 전` | `created_at` 값의 표시용 포맷 문자열 |
|
||||
| updated_at | string | `2026-07-08 15:01:45` | 최종 수정 일시 (수정 시각으로 갱신) |
|
||||
| deleted_at | null | `null` | 소프트 삭제 일시 (미삭제 시 null) |
|
||||
| is_cascade_deleted | boolean | `false` | 상위 게시글/댓글 삭제로 연쇄 삭제된 댓글인지 여부 |
|
||||
| ip_address | null | `null` | 작성 요청이 발생한 IP 주소 (권한자에게만 노출) |
|
||||
| action_logs | array | `[]` | 블라인드/복원/삭제 처리 이력 목록. `admin.manage` 권한 보유자에게만 노출. |
|
||||
| is_author | boolean | `true` | 현재 사용자가 작성자인지 여부 |
|
||||
| is_guest_comment | boolean | `false` | 비회원 작성 댓글 여부 |
|
||||
| is_already_reported | boolean | `false` | 현재 사용자가 이미 신고한 댓글인지 여부 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
| abilities | object | `{"can_read":true,"can_write":true,"can_manage":true}` | 현재 사용자가 이 댓글에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "댓글이 수정되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"post_id": 1,
|
||||
"parent_id": null,
|
||||
"content": "API 문서 샘플 댓글입니다. (수정)",
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"is_guest": false
|
||||
},
|
||||
"is_secret": false,
|
||||
"status": "published",
|
||||
"status_label": "게시됨",
|
||||
"depth": 0,
|
||||
"replies_count": 0,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"created_at_formatted": "4시간 전",
|
||||
"updated_at": "2026-07-08 15:01:45",
|
||||
"deleted_at": null,
|
||||
"is_cascade_deleted": false,
|
||||
"ip_address": null,
|
||||
"action_logs": [],
|
||||
"is_author": true,
|
||||
"is_guest_comment": false,
|
||||
"is_already_reported": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_write": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.comments.write`)이 없거나, 타인/비회원 댓글을 `admin.manage` 없이 수정하려는 경우(`접근 권한이 없습니다.`), 게시판의 댓글 기능이 꺼진 경우(`이 게시판은 댓글 기능이 비활성화되어 있습니다.`) |
|
||||
| 404 | Not Found | ID 에 해당하는 댓글 또는 슬러그에 해당하는 게시판이 없는 경우 (`댓글을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 500 | Internal Server Error | 수정 처리 실패 (`댓글 수정에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1614,7 +2041,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1/blind HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id}/blind HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -1716,8 +2143,8 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -1737,31 +2164,122 @@ HTTP/1.1 200
|
||||
| slug | path | string | 예 | — | 대상 리소스의 slug (URL 친화 식별자) |
|
||||
| postId | path | string | 예 | — | 대상 post의 식별자 |
|
||||
| id | path | string | 예 | — | 대상 리소스의 식별자 |
|
||||
| reason | body | string | 아니오 | max 1000 | 댓글 블라인드 처리 사유(최대 1000자). 처리 이력에 기록되며, 미지정 시 빈 문자열로 저장됩니다. |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/board/apidoc-sample-board/posts/1/comments/1/restore HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/board/{slug}/posts/{postId}/comments/{id}/restore HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"reason": "예시값"
|
||||
}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`CommentResource` — 복원된 댓글. 블라인드 응답과 동일한 구조이며, `status` 가 `published` 로 되돌아가고 `action_logs` 에 `restore` 이력이 1건 추가됩니다)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 댓글 기본 키 (내부 식별자) |
|
||||
| post_id | integer | `1` | 댓글이 속한 게시글 식별자 |
|
||||
| parent_id | null | `null` | 상위 댓글 식별자 (대댓글일 때만 값 존재) |
|
||||
| content | string | `API 문서 샘플 댓글입니다.` | 댓글 본문 내용 (복원되어 원문이 다시 노출됨) |
|
||||
| author | object | `{"uuid":"a234c2b1-…","name":"API 문서 샘플 사용자"}` | 작성자 사용자 객체 (author 관계 파생) |
|
||||
| is_secret | boolean | `false` | 비밀 댓글 여부 |
|
||||
| status | string | `published` | 복원 후 댓글 상태 (`published` 로 되돌아감) |
|
||||
| status_label | string | `게시됨` | 상태의 사람이 읽는 라벨 |
|
||||
| depth | integer | `0` | 댓글 계층 깊이 (0 = 최상위 댓글) |
|
||||
| replies_count | integer | `0` | 이 댓글에 달린 대댓글 수 (집계) |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| created_at_formatted | string | `4시간 전` | `created_at` 값의 표시용 포맷 문자열 |
|
||||
| updated_at | string | `2026-07-08 15:01:45` | 최종 수정 일시 |
|
||||
| deleted_at | null | `null` | 소프트 삭제 일시 (미삭제 시 null) |
|
||||
| is_cascade_deleted | boolean | `false` | 상위 게시글/댓글 삭제로 연쇄 삭제된 댓글인지 여부 |
|
||||
| ip_address | null | `null` | 작성 요청이 발생한 IP 주소 (권한자에게만 노출) |
|
||||
| action_logs | array | `[{"action":"blind","reason":"실측 예시값",…},{"action":"restore","reason":null,…}]` | 블라인드/복원/삭제 처리 이력 목록 (복원 이력이 추가됨). `admin.manage` 권한 보유자에게만 노출. |
|
||||
| is_author | boolean | `true` | 현재 사용자가 작성자인지 여부 |
|
||||
| is_guest_comment | boolean | `false` | 비회원 작성 댓글 여부 |
|
||||
| is_already_reported | boolean | `false` | 현재 사용자가 이미 신고한 댓글인지 여부 |
|
||||
| is_owner | boolean | `true` | 현재 인증 사용자가 이 리소스의 소유자인지 여부 |
|
||||
| abilities | object | `{"can_read":true,"can_write":true,"can_manage":true}` | 현재 사용자가 이 댓글에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "댓글이 복원되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"post_id": 1,
|
||||
"parent_id": null,
|
||||
"content": "API 문서 샘플 댓글입니다.",
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"avatar": null,
|
||||
"status": "active",
|
||||
"status_label": "활성",
|
||||
"is_guest": false
|
||||
},
|
||||
"is_secret": false,
|
||||
"status": "published",
|
||||
"status_label": "게시됨",
|
||||
"depth": 0,
|
||||
"replies_count": 0,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"created_at_formatted": "4시간 전",
|
||||
"updated_at": "2026-07-08 15:01:45",
|
||||
"deleted_at": null,
|
||||
"is_cascade_deleted": false,
|
||||
"ip_address": null,
|
||||
"action_logs": [
|
||||
{
|
||||
"action": "blind",
|
||||
"reason": "실측 예시값",
|
||||
"admin_name": "API 문서 샘플 사용자",
|
||||
"created_at": "2026-07-08 06:01:44"
|
||||
},
|
||||
{
|
||||
"action": "restore",
|
||||
"reason": null,
|
||||
"admin_name": "API 문서 샘플 사용자",
|
||||
"created_at": "2026-07-08 06:01:45"
|
||||
}
|
||||
],
|
||||
"is_author": true,
|
||||
"is_guest_comment": false,
|
||||
"is_already_reported": false,
|
||||
"is_owner": true,
|
||||
"abilities": {
|
||||
"can_read": true,
|
||||
"can_write": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.{slug}.admin.manage`)이 없거나, 게시판의 댓글 기능이 꺼진 경우 (`이 게시판은 댓글 기능이 비활성화되어 있습니다.`) |
|
||||
| 404 | Not Found | ID 에 해당하는 댓글 또는 슬러그에 해당하는 게시판이 없는 경우 (`댓글을 찾을 수 없습니다.`) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 복원 처리 실패 (`댓글 복원에 실패했습니다.`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Dashboard 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 My Comments 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Reports 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -217,11 +217,31 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| affected_count | integer | `3` | 실제로 상태가 변경된 신고 건수 (영구삭제·동일 상태 등 전환 불가 건은 제외) |
|
||||
| restored_count | integer | `1` | 상태 변경(반려 등)에 따라 공개 상태로 복구된 대상 콘텐츠 건수 |
|
||||
| manual_blind_restored | integer | `1` | 그중 관리자 수동 블라인드(`admin` 트리거)였다가 함께 복구된 건수 |
|
||||
| status_label | string | `반려` | 전환된 신고 상태의 사람이 읽는 라벨 (`ReportStatus::label()` 산물) |
|
||||
| message | string | `3개 신고를 반려(으)로 변경했습니다.` | 화면에 그대로 노출 가능한 안내 문구 (봉투 최상위 `message` 와 동일 값) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "3개 신고를 반려(으)로 변경했습니다. 수동 블라인드 처리된 1건이 함께 복구되었습니다.",
|
||||
"data": {
|
||||
"affected_count": 3,
|
||||
"restored_count": 1,
|
||||
"manual_blind_restored": 1,
|
||||
"status_label": "반려",
|
||||
"message": "3개 신고를 반려(으)로 변경했습니다. 수동 블라인드 처리된 1건이 함께 복구되었습니다."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -230,6 +250,7 @@ Content-Type: application/json
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.reports.manage`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 일괄 상태 변경 처리 중 오류가 발생한 경우 (`sirsoft-board::messages.reports.bulk_status_update_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -268,11 +289,57 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| status_counts | object | `{"pending":{"count":2,"label":"접수"},"deleted":{"count":1,"label":"영구삭제"}}` | 선택된 신고들의 현재 상태별 집계 맵. 키는 상태 코드(pending/review/rejected/suspended/deleted), 값은 `{count, label}` |
|
||||
| changeable_status_counts | object | `{"pending":{"count":2,"label":"접수"}}` | `status_counts` 에서 영구삭제(deleted)와 전환 대상 상태(`target_status`)를 제외한 집계 (실제로 변경될 항목만) |
|
||||
| total_count | integer | `3` | 요청한 `ids` 의 총 개수 |
|
||||
| changeable_count | integer | `2` | 실제로 상태 변경이 가능한 건수 (`total_count` − `unchangeable_count`) |
|
||||
| deleted_count | integer | `1` | 선택 항목 중 영구삭제(deleted) 상태로 변경 불가한 건수 |
|
||||
| same_status_count | integer | `0` | 선택 항목 중 이미 `target_status` 와 동일해 변경이 무의미한 건수 (`target_status` 가 deleted 이면 0) |
|
||||
| unchangeable_count | integer | `1` | 변경 불가 총 건수 (`deleted_count` + `same_status_count`) |
|
||||
| all_deleted | boolean | `false` | 선택 항목이 모두 영구삭제 상태인지 여부 |
|
||||
| all_unchangeable | boolean | `false` | 선택 항목 전부가 변경 불가인지 여부 (`changeable_count === 0`) |
|
||||
| target_status_label | string \| null | `반려` | `target_status` 의 사람이 읽는 라벨. `target_status` 미지정 시 null |
|
||||
| restorable_blind_count | integer | `1` | `target_status` 가 `rejected` 일 때, 반려 처리로 공개 상태로 복구될 블라인드 대상 건수 (그 외 상태에서는 0) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "상태별 건수를 조회했습니다.",
|
||||
"data": {
|
||||
"status_counts": {
|
||||
"pending": {
|
||||
"count": 2,
|
||||
"label": "접수"
|
||||
},
|
||||
"deleted": {
|
||||
"count": 1,
|
||||
"label": "영구삭제"
|
||||
}
|
||||
},
|
||||
"changeable_status_counts": {
|
||||
"pending": {
|
||||
"count": 2,
|
||||
"label": "접수"
|
||||
}
|
||||
},
|
||||
"total_count": 3,
|
||||
"changeable_count": 2,
|
||||
"deleted_count": 1,
|
||||
"same_status_count": 0,
|
||||
"unchangeable_count": 1,
|
||||
"all_deleted": false,
|
||||
"all_unchangeable": false,
|
||||
"target_status_label": "반려",
|
||||
"restorable_blind_count": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -281,6 +348,7 @@ Content-Type: application/json
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.reports.view`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 500 | Internal Server Error | 상태별 건수 집계 중 오류가 발생한 경우 (`sirsoft-board::messages.reports.status_counts_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -302,7 +370,7 @@ Content-Type: application/json
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/sirsoft-board/admin/reports/1 HTTP/1.1
|
||||
DELETE /api/modules/sirsoft-board/admin/reports/{report} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -310,9 +378,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
|
||||
|
||||
<!-- 실측 응답에 필드 없음(빈 목록 등) — 데이터가 있는 상태로 재실측하거나 사람이 작성. -->
|
||||
_이 엔드포인트는 `data` 를 반환하지 않습니다 (성공 메시지만 — `data` 는 `null`)._
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -356,7 +422,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/reports/1 HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/reports/{report} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -486,7 +552,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/admin/reports/1/reporters?per_page=1&page=1 HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/admin/reports/{report}/reporters?per_page=1&page=1 HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -536,8 +602,8 @@ HTTP/1.1 200
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.reports.view`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -561,7 +627,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PATCH /api/modules/sirsoft-board/admin/reports/1/status HTTP/1.1
|
||||
PATCH /api/modules/sirsoft-board/admin/reports/{report}/status HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
@@ -575,20 +641,109 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드 (`ReportResource` — 상태 변경 후 재조회한 신고 케이스)._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `1` | 기본 키 (내부 식별자) |
|
||||
| board_id | integer \| null | `1` | 게시판 ID (게시판 삭제 시 null) |
|
||||
| board | object | `{"id":1,"name":"공지사항","slug":"notice","title":"...","current_status":"blinded","deleted_at":null}` | 신고 대상이 속한 게시판 정보 + 대상 제목/현재 상태. 게시판 삭제 시 첫 신고 로그의 스냅샷 값으로 폴백합니다. |
|
||||
| target_type | string | `post` | 신고 대상 타입 (`post`, `comment`) |
|
||||
| target_type_label | string | `게시글` | `target_type` 값의 사람이 읽는 라벨 |
|
||||
| target_id | integer | `1` | 신고 대상 ID (동적 테이블의 ID) |
|
||||
| post_id | integer \| null | `1` | 대상 게시글 ID. 대상이 댓글이면 상위 게시글 ID |
|
||||
| content | null | `null` | 본문 내용 (상세(`show`) 요청에서만 채워지며, 상태 변경 응답에서는 null) |
|
||||
| content_mode | string | `html` | 대상 본문의 형식 모드 (`text`/`html`). 스냅샷이 없으면 `text` |
|
||||
| content_preview | string | `API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.` | 대상 본문의 미리보기 (앞 100자 발췌) |
|
||||
| author | object | `{"uuid":"...","name":"홍길동","email":"user@example.com","is_guest":false}` | 신고 대상 콘텐츠의 작성자. 회원 정보가 없으면 스냅샷 이름 + `is_guest: true` |
|
||||
| reporter | object \| null | `{"uuid":"...","name":"신고자","email":"reporter@example.com","is_guest":false}` | 대표 신고자(첫 번째 신고 로그) 정보. 신고 로그가 없으면 null |
|
||||
| reason_type | string \| null | `abuse` | 대표 신고 사유 코드 (첫 신고 로그의 사유 Enum 값) |
|
||||
| reason_type_label | string \| null | `욕설/비방` | `reason_type` 의 사람이 읽는 라벨 |
|
||||
| status | string | `rejected` | 변경된 신고 상태 (`pending`, `review`, `rejected`, `suspended`, `deleted`) |
|
||||
| status_label | string | `반려` | 상태의 사람이 읽는 라벨 (`ReportStatus::label()`) |
|
||||
| status_variant | string | `info` | 상태 배지 색상/스타일 변형 키 (`ReportStatus::variant()`) |
|
||||
| processor | object \| null | `{"uuid":"...","name":"관리자"}` | 상태를 변경한 처리 관리자 (uuid/name). 미지정 시 null |
|
||||
| processed_at | string \| null | `2026-07-08 10:41:34` | 처리 일시 |
|
||||
| metadata | null | `null` | 메타데이터 (상세(`show`) 요청에서만 채워지며, 상태 변경 응답에서는 null) |
|
||||
| report_count | integer \| null | `null` | 케이스 신고 건수 집계. 목록(`paginateGrouped`) 응답에서만 채워지며 단건 재조회에서는 null |
|
||||
| last_reported_at | string \| null | `2026-07-08 10:41:34` | 마지막 신고 일시 (재접수 시 갱신) |
|
||||
| is_reactivated | boolean | `false` | 반려/중단 후 재접수된 케이스인지 여부 (`last_activated_at` 존재 여부) |
|
||||
| target_status | null | `null` | 대상 콘텐츠의 현재 상태. 목록 조회의 서브쿼리로만 주입되며 단건 재조회에서는 null |
|
||||
| target_trigger_type | null | `null` | 대상 상태를 유발한 트리거 유형. 목록 조회에서만 채워지며 단건 재조회에서는 null |
|
||||
| target_status_label | null | `null` | `target_status` 의 라벨. `target_status` 가 없으면 null |
|
||||
| created_at | string | `2026-07-08 10:41:34` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-08 10:42:10` | 최종 수정 일시 |
|
||||
| is_owner | boolean | `false` | 현재 인증 사용자가 이 리소스의 소유자(`reporter_id`)인지 여부 |
|
||||
| abilities | object | `{"can_view":true,"can_manage":true}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "신고 상태가 변경되었습니다.",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"board_id": 1,
|
||||
"board": {
|
||||
"id": 1,
|
||||
"name": "API 문서 샘플 게시판",
|
||||
"slug": "apidoc-sample-board",
|
||||
"title": "API 문서 샘플 게시글",
|
||||
"current_status": "published",
|
||||
"deleted_at": null
|
||||
},
|
||||
"target_type": "post",
|
||||
"target_type_label": "게시글",
|
||||
"target_id": 1,
|
||||
"post_id": 1,
|
||||
"content": null,
|
||||
"content_mode": "html",
|
||||
"content_preview": "<p>API 레퍼런스 실측용 완전 샘플 게시글 본문입니다.</p>",
|
||||
"author": {
|
||||
"uuid": "a234c2b1-cde8-437f-b28b-23323be2b98d",
|
||||
"name": "API 문서 샘플 사용자",
|
||||
"email": "apidoc-sample-user@example.com",
|
||||
"is_guest": false
|
||||
},
|
||||
"reporter": null,
|
||||
"reason_type": null,
|
||||
"reason_type_label": null,
|
||||
"status": "rejected",
|
||||
"status_label": "반려",
|
||||
"status_variant": "info",
|
||||
"processor": {
|
||||
"uuid": "a1e0a91a-fba6-491c-a53e-7285a5686857",
|
||||
"name": "관리자"
|
||||
},
|
||||
"processed_at": "2026-07-08 10:42:10",
|
||||
"metadata": null,
|
||||
"report_count": null,
|
||||
"last_reported_at": "2026-07-08 10:41:34",
|
||||
"is_reactivated": false,
|
||||
"target_status": null,
|
||||
"target_trigger_type": null,
|
||||
"target_status_label": null,
|
||||
"created_at": "2026-07-08 10:41:34",
|
||||
"updated_at": "2026-07-08 10:42:10",
|
||||
"is_owner": false,
|
||||
"abilities": {
|
||||
"can_view": true,
|
||||
"can_manage": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.reports.manage`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.reports.manage`)이 없거나, 권한 스코프(본인만/역할 범위)를 벗어난 신고에 접근한 경우 (`auth.scope_denied`) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). 영구삭제(`deleted`) 상태 신고의 상태를 변경하려 한 경우에도 422 (`sirsoft-board::messages.reports.cannot_change_deleted_status`) |
|
||||
| 500 | Internal Server Error | 상태 변경 처리 중 오류가 발생한 경우 (`sirsoft-board::messages.reports.status_update_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Settings 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -363,10 +363,36 @@ HTTP/1.1 200
|
||||
| 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 페이지 생성 활성화 여부 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
@@ -382,24 +408,95 @@ Content-Type: application/json
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
@@ -719,11 +816,62 @@ Content-Type: application/json
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `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` | 일괄 적용 대상 게시판 총 수 |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-422 — 응답 예시는 사람이 작성하세요. -->
|
||||
성공 시
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "sirsoft-board::messages.settings.bulk_apply_success",
|
||||
"data": {
|
||||
"updated_count": 3,
|
||||
"rolled_back": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
중단·롤백 시 (HTTP 200)
|
||||
|
||||
```json
|
||||
{
|
||||
"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` 그룹이 정의되어 있지 않아 키 문자열이 그대로 노출됩니다(다른 엔드포인트 실측 응답과 동일).
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -731,7 +879,8 @@ Content-Type: application/json
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.settings.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지). `fields` 누락/빈 배열, 허용되지 않은 필드명, `apply_all=false` 인데 `board_ids` 미지정, 존재하지 않는 `board_ids` 항목 등 |
|
||||
| 500 | Internal Server Error | 일괄 적용 처리 중 롤백 예외 외의 오류가 발생한 경우 (`messages.settings.bulk_apply_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -759,11 +908,23 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: write-method — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `data` 객체의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| cleared | boolean | `true` | 캐시 초기화 수행 여부. 성공 시 항상 `true` (ModuleSettings 캐시 + 게시판 캐시 전체 초기화) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: side-effectful-write — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "sirsoft-board::messages.settings.clear_cache_success",
|
||||
"data": {
|
||||
"cleared": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -771,6 +932,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.settings.update`)이 없는 경우 |
|
||||
| 500 | Internal Server Error | 캐시 초기화 중 오류가 발생한 경우 (`messages.settings.clear_cache_error`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -800,11 +962,34 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
_단건 응답: `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` 권한 보유 여부) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
```json
|
||||
{
|
||||
"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
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
@@ -813,6 +998,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`sirsoft-board.settings.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
| 500 | Internal Server Error | 설정 조회 중 오류가 발생한 경우 (`messages.settings.fetch_failed`) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Users 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(raw HTTP) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -32,7 +32,7 @@
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/users/a234c2b1-cde8-437f-b28b-23323be2b98d/posts HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/users/{user}/posts HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
|
||||
@@ -147,7 +147,7 @@ HTTP/1.1 200
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/sirsoft-board/users/a234c2b1-cde8-437f-b28b-23323be2b98d/posts/stats HTTP/1.1
|
||||
GET /api/modules/sirsoft-board/users/{user}/posts/stats HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
|
||||
|
||||
@@ -5,12 +5,14 @@ namespace Modules\Sirsoft\Board\Http\Controllers\Admin;
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use Illuminate\Database\Eloquent\ModelNotFoundException;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
use Illuminate\Support\Facades\Auth;
|
||||
use Modules\Sirsoft\Board\Enums\PostStatus;
|
||||
use Modules\Sirsoft\Board\Exceptions\AttachmentLimitExceededException;
|
||||
use Modules\Sirsoft\Board\Exceptions\BoardNotFoundException;
|
||||
use Modules\Sirsoft\Board\Exceptions\PostNotFoundException;
|
||||
use Modules\Sirsoft\Board\Http\Requests\Admin\PostFormDataRequest;
|
||||
use Modules\Sirsoft\Board\Http\Requests\Admin\PostFormMetaRequest;
|
||||
use Modules\Sirsoft\Board\Http\Requests\Admin\PostIndexRequest;
|
||||
use Modules\Sirsoft\Board\Http\Requests\BlindPostRequest;
|
||||
use Modules\Sirsoft\Board\Http\Requests\RestorePostRequest;
|
||||
use Modules\Sirsoft\Board\Http\Requests\StorePostRequest;
|
||||
@@ -51,12 +53,11 @@ class PostController extends AdminBaseController
|
||||
/**
|
||||
* 게시글 목록을 조회합니다.
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param PostIndexRequest $request 검증된 목록 조회 요청
|
||||
* @param string $slug 게시판 슬러그
|
||||
* @return JsonResponse 게시글 목록 응답
|
||||
*/
|
||||
// audit:allow controller-base-request-injection reason: GET 목록 조회. all()로 필터·페이징 파라미터만 읽음 (검증 불필요)
|
||||
public function index(Request $request, string $slug): JsonResponse
|
||||
public function index(PostIndexRequest $request, string $slug): JsonResponse
|
||||
{
|
||||
// 권한은 라우트 미들웨어에서 체크됨 (sirsoft-board.{slug}.admin.posts.read)
|
||||
try {
|
||||
@@ -392,12 +393,11 @@ class PostController extends AdminBaseController
|
||||
* - 수정 모드: 기존 게시글 데이터
|
||||
* - 답변글 모드: 기본값이 설정된 폼 데이터
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param PostFormDataRequest $request 검증된 폼 데이터 요청
|
||||
* @param string $slug 게시판 슬러그
|
||||
* @return JsonResponse 폼 입력 데이터 응답
|
||||
*/
|
||||
// audit:allow controller-base-request-injection reason: GET 수정 폼 데이터 조회. 경로 파라미터(slug) + 쿼리만 read-only 참조 (검증 불필요)
|
||||
public function getFormData(Request $request, string $slug): JsonResponse
|
||||
public function getFormData(PostFormDataRequest $request, string $slug): JsonResponse
|
||||
{
|
||||
// 권한은 라우트 미들웨어에서 체크됨 (sirsoft-board.{slug}.admin.posts.write)
|
||||
try {
|
||||
@@ -480,12 +480,11 @@ class PostController extends AdminBaseController
|
||||
*
|
||||
* 게시판 정보, 원글 정보, 작성자 정보 등 화면 표시에 필요한 데이터를 반환합니다.
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param PostFormMetaRequest $request 검증된 폼 메타 요청
|
||||
* @param string $slug 게시판 슬러그
|
||||
* @return JsonResponse 폼 메타 데이터 응답
|
||||
*/
|
||||
// audit:allow controller-base-request-injection reason: GET 작성/수정 폼 메타 조회. 경로 파라미터(slug) + post_id 쿼리만 read-only 참조 (검증 불필요)
|
||||
public function getFormMeta(Request $request, string $slug): JsonResponse
|
||||
public function getFormMeta(PostFormMetaRequest $request, string $slug): JsonResponse
|
||||
{
|
||||
// 권한은 라우트 미들웨어에서 체크됨 (sirsoft-board.{slug}.admin.posts.write)
|
||||
try {
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Sirsoft\Board\Http\Requests\Admin;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
* 관리자 게시글 폼 데이터 조회 요청 폼 검증
|
||||
*
|
||||
* 생성/수정/답글 모드를 구분하기 위해 post_id 또는 parent_id 를 선택적으로 받습니다.
|
||||
* 권한은 라우트 permission 미들웨어가 담당합니다.
|
||||
*/
|
||||
class PostFormDataRequest extends FormRequest
|
||||
{
|
||||
/**
|
||||
* 사용자가 이 요청을 수행할 권한이 있는지 확인합니다.
|
||||
*
|
||||
* @return bool 항상 true (권한은 미들웨어 체인에서 처리)
|
||||
*/
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 요청에 적용할 검증 규칙을 반환합니다.
|
||||
*
|
||||
* @return array<string, array<int, mixed>> 검증 규칙
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'post_id' => ['sometimes', 'nullable', 'integer', 'min:1'],
|
||||
'parent_id' => ['sometimes', 'nullable', 'integer', 'min:1'],
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Sirsoft\Board\Http\Requests\Admin;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
* 관리자 게시글 폼 메타데이터 조회 요청 폼 검증
|
||||
*
|
||||
* 별도 입력 파라미터를 받지 않습니다. 권한은 라우트 permission 미들웨어가 담당하며,
|
||||
* 컨트롤러가 base Illuminate\Http\Request 를 주입받지 않도록 전용 FormRequest 를 둡니다.
|
||||
*/
|
||||
class PostFormMetaRequest extends FormRequest
|
||||
{
|
||||
/**
|
||||
* 사용자가 이 요청을 수행할 권한이 있는지 확인합니다.
|
||||
*
|
||||
* @return bool 항상 true (권한은 미들웨어 체인에서 처리)
|
||||
*/
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 요청에 적용할 검증 규칙을 반환합니다.
|
||||
*
|
||||
* @return array<string, array<int, mixed>> 검증 규칙 (요청 파라미터 없음)
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
return [];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Sirsoft\Board\Http\Requests\Admin;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
* 관리자 게시글 목록 조회 요청 폼 검증
|
||||
*
|
||||
* 목록 필터·정렬·페이지네이션 파라미터를 받습니다. 값은 Service 의 buildListParams 에서
|
||||
* 정규화되므로 여기서는 형식 수준만 검증합니다. 권한은 라우트 permission 미들웨어가 담당합니다.
|
||||
*/
|
||||
class PostIndexRequest extends FormRequest
|
||||
{
|
||||
/**
|
||||
* 사용자가 이 요청을 수행할 권한이 있는지 확인합니다.
|
||||
*
|
||||
* @return bool 항상 true (권한은 미들웨어 체인에서 처리)
|
||||
*/
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 요청에 적용할 검증 규칙을 반환합니다.
|
||||
*
|
||||
* @return array<string, array<int, mixed>> 검증 규칙
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'page' => ['sometimes', 'integer', 'min:1'],
|
||||
'per_page' => ['sometimes', 'integer', 'min:1', 'max:100'],
|
||||
'search' => ['sometimes', 'nullable', 'string', 'max:255'],
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -4,7 +4,7 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.5] - 2026-07-16
|
||||
## [1.1.0] - 2026-08-06
|
||||
|
||||
### Security
|
||||
|
||||
@@ -18,6 +18,40 @@
|
||||
|
||||
### Added
|
||||
|
||||
#### 현금영수증
|
||||
|
||||
- 현금영수증 발급 업체를 결제대행사와 따로 고를 수 있습니다 — KG이니시스로 결제받으면서 현금영수증만 토스페이먼츠로 발급하는 구성이 가능합니다. 발급 업체는 이커머스 환경설정에서 선택합니다.
|
||||
- 무통장입금 주문의 입금이 확인되면 현금영수증이 자동으로 발급됩니다. 관리자가 "결제완료로 변경"한 경우와 "입금만 기록"한 경우 모두 발급되며, 마일리지로 전액 결제되어 실제 입금액이 없는 주문에는 발급하지 않습니다. 발급은 백그라운드에서 처리되므로 발급 업체 응답이 늦어도 입금 확인 자체는 지연되지 않습니다.
|
||||
- 주문할 때 현금영수증을 신청하지 않았어도 나중에 발급할 수 있습니다 — 관리자 주문 상세와 구매자 주문 상세 양쪽에서 발급할 수 있고, 비회원도 주문 조회 후 발급할 수 있습니다. 발급 취소는 관리자만 할 수 있습니다.
|
||||
- 발급 용도(소득공제/지출증빙)와 발급 수단(휴대폰번호·현금영수증카드번호·사업자등록번호)을 따로 고를 수 있습니다. 지출증빙용도 휴대폰번호로 발급할 수 있으며, 사업자등록번호는 입력 시 유효성을 검사합니다.
|
||||
- 현금영수증을 신청하지 않은 무통장입금 건을 사업자가 자진발급하는 설정을 추가했습니다 (기본 사용 안 함). 현금영수증 의무발행 업종이라면 켜 두면 됩니다.
|
||||
- 현금영수증 발급·취소 이력이 남습니다. 부분 환불 등으로 결제금액이 바뀌면 기존 영수증을 취소하고 바뀐 금액으로 다시 발급하며, 그 과정이 모두 기록되어 국세청 신고 근거로 쓸 수 있습니다. 재발급은 환불 처리가 끝난 뒤 이뤄지므로, 재발급이 실패하더라도 환불 자체는 그대로 완료되고 관리자가 주문 상세에서 다시 발급할 수 있습니다.
|
||||
- 현금영수증 식별번호(휴대폰번호·사업자등록번호 등)는 재발급에 쓸 수 있도록 암호화해 보관하고 구매확정 시점에 폐기합니다. 이력에는 뒤 4자리를 제외한 마스킹 값만 남으며, 발급 업체가 보내온 응답에 섞여 오는 개인정보도 가려서 저장합니다. 주민등록번호는 수집하지 않습니다.
|
||||
- 결제 영수증(카드 매출전표 등)과 현금영수증을 각각 따로 조회할 수 있습니다. 두 영수증은 서로 다른 값으로 보관되어 한쪽이 다른 쪽을 덮어쓰지 않습니다.
|
||||
|
||||
#### 신청·발급 화면
|
||||
|
||||
- 주문서의 무통장입금 결제 영역에서 현금영수증을 신청할 수 있습니다. 용도(소득공제/지출증빙)에 따라 고를 수 있는 발급 수단이 바뀌며, 그 용도에 쓸 수 없는 수단이 선택되어 있으면 자동으로 되돌립니다. 발급 업체를 설정하지 않은 상점에서는 신청란이 나타나지 않습니다. 결제수단을 다른 것으로 바꾸면 입력했던 신청 내용은 지워집니다.
|
||||
- 구매자 주문 상세에 현금영수증 카드가 표시됩니다. 입금 전에는 안내만, 입금 후 미발급이면 발급 버튼, 발급 후에는 발급일시·용도·식별번호와 영수증 보기 링크가 나타납니다. 환불에 따른 재발급이 실패한 경우에는 안내 문구가 표시됩니다.
|
||||
- 관리자 주문 상세에 현금영수증 카드가 표시됩니다. 발급·발급취소·수동 재발급을 할 수 있고 발급·취소 이력을 함께 볼 수 있습니다. 재발급이 실패한 주문에는 경고와 함께 다시 발급하는 버튼이 나타납니다.
|
||||
- 이커머스 환경설정 주문설정 탭에서 현금영수증 발급 업체, 배송비 과세 방식, 자진발급 사용 여부를 설정할 수 있습니다.
|
||||
|
||||
#### 환불 계좌
|
||||
|
||||
- 주문서의 무통장입금·가상계좌 결제 영역에서 환불받을 계좌(은행·계좌번호·예금주)를 미리 입력할 수 있습니다. 입력하지 않아도 주문할 수 있지만, 세 칸 중 하나라도 입력하면 나머지도 입력해야 합니다. 무통장입금·가상계좌가 아닌 결제수단으로 주문하면 환불 계좌는 저장되지 않습니다 — 계좌를 입력한 뒤 카드 등으로 결제수단을 바꿔도 필요 없는 계좌정보가 주문에 남지 않습니다.
|
||||
- 관리자 주문 취소 화면에서 환불 계좌를 입력하거나 수정할 수 있습니다. 주문할 때 입력한 계좌가 있으면 미리 채워집니다. 입금이 완료된 가상계좌 주문은 환불에 계좌가 반드시 필요하므로 입력하지 않으면 취소할 수 없습니다. 무통장입금은 관리자가 직접 이체할 때 참고하도록 선택 입력이며, 카드·간편결제는 원래 결제수단으로 환불되므로 계좌란이 나타나지 않습니다.
|
||||
|
||||
#### 금액·과세
|
||||
|
||||
- 주문에 현금성 금액이 기록됩니다. 무통장입금 주문에서 마일리지를 사용한 경우, 실제로 계좌에 입금된 금액만 현금영수증 발급 대상이 됩니다. 주문을 일부 취소하면 남은 실입금액 기준으로 다시 계산됩니다.
|
||||
- 배송비 과세 방식을 이커머스 환경설정에서 고를 수 있습니다 — 안분(기본, 과세상품 비율만큼 배송비를 과세로 계산) / 전액 과세 / 주된 재화를 따름 중 상점의 세무 판단에 맞춰 선택합니다.
|
||||
|
||||
#### 결제수단
|
||||
|
||||
- 결제 플러그인이 등록한 결제수단(예: "가상계좌 (토스페이먼츠)")을 주문서에서 선택해 주문할 수 있습니다. 이런 결제수단은 화면에서는 독립된 항목으로 보이지만 주문에는 대응하는 기본 결제수단(가상계좌·계좌이체·휴대폰·카드)으로 기록되어, 입금 확인·취소·환불 등 이후 처리가 정상적으로 이어집니다.
|
||||
|
||||
#### 사이트맵·알림·마일리지
|
||||
|
||||
- 사이트맵에 담을 상품·카테고리 수의 안전 상한을 지원합니다. 상한을 설정하면 상품 목록·카테고리·상품 어느 항목이든 그 수를 넘지 않으며, 상한에 걸려 일부가 빠진 경우 기록으로 남습니다.
|
||||
- 상품·카테고리를 전시/숨김으로 바꾸거나 삭제하면 사이트맵에 해당 항목만 자동으로 반영됩니다. 전체를 다시 만들지 않고 바뀐 부분만 갱신하므로 상품이 많은 쇼핑몰에서도 빠르게 최신 상태가 유지됩니다.
|
||||
- 이커머스 알림 설정 화면에서도 코어와 동일하게 카카오 알림톡 템플릿을 연결할 수 있습니다(비즈뿌리오 플러그인 설치 시).
|
||||
@@ -25,6 +59,10 @@
|
||||
|
||||
### Changed
|
||||
|
||||
- 과세·면세 금액 합계에 배송비가 포함됩니다. 그동안 배송비는 과세/면세 어느 쪽에도 집계되지 않아 상품 금액만 합산되었습니다.
|
||||
- 현금영수증 발급 용도 값을 소득공제(income) / 지출증빙(expense)으로 통일했습니다. 기존에 다른 값으로 저장된 주문은 모듈 업데이트 시 자동으로 정리됩니다.
|
||||
- 주문 상세 응답에 현금영수증 정보와 결제 영수증 링크가 포함됩니다.
|
||||
- 결제대행사 환불 연동에 환불 건 정보를 함께 전달합니다. 결제 플러그인이 이 값으로 중복 취소를 방지할 수 있습니다 — 네트워크 재시도로 같은 취소 요청이 두 번 전달되어도 이중 환불되지 않습니다.
|
||||
- 관리자 상품 목록이 상품마다 옵션 전체를 함께 내려주지 않습니다. 목록에는 옵션 개수와 재고 합계만 실리고, 옵션 상세는 행을 펼칠 때 필요한 상품의 것만 한 번에 가져옵니다. 옵션을 많이 쓰는 쇼핑몰일수록 목록을 여는 속도와 전송량이 크게 개선됩니다(상품 100건에 상품당 옵션 20건 기준, 목록 응답 크기 약 94% 감소). 화면에서 보이는 내용과 일괄 변경 적용 범위는 이전과 동일하며, 옵션을 목록 응답에 함께 받으려면 주소 뒤에 `?with_options=1` 을 붙이면 됩니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
|
||||
- 관리자 주문 목록이 주문마다 주문상품 전체를 함께 내려주지 않습니다. 목록은 대표 상품 1건과 "외 N건" 표기만 사용하므로, 이제 그 1건과 개수만 읽습니다. 한 주문에 상품을 많이 담는 쇼핑몰일수록 목록을 여는 속도와 전송량이 개선됩니다. 화면에 보이는 내용(대표 상품·추가옵션 요약·"외 N건"·부분취소 표시)은 이전과 동일하며, 마이페이지 주문내역은 종전대로 주문상품 전체를 보여줍니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
|
||||
- 상품 옵션의 표시 순서를 상품 등록/수정 화면과 동일하게 정렬 순서 기준으로 통일했습니다. 이전에는 관리자 상품 목록의 펼친 옵션만 정해진 순서 없이 표시돼 화면마다 순서가 달라 보일 수 있었습니다. (#76 @jordy-bitree 님께서 제보해주셨습니다.)
|
||||
@@ -135,6 +173,9 @@
|
||||
- 해외 배송지를 수정하면 도시·주·우편번호가 안내 없이 비워지던 문제를 수정했습니다. 이번 수정에서 다시 입력하지 않은 항목은 저장된 값이 그대로 유지됩니다. (#78 @glitter-gim 님께서 제보해주셨습니다.)
|
||||
- 관리자 목록에서 기록이 아주 많아 총 건수를 끝까지 세지 못하면 "1페이지뿐" 으로 표시되어 뒤쪽 페이지를 볼 수 없던 문제를 수정했습니다. 주문·상품·마일리지·쿠폰·쿠폰 발급 이력·상품 리뷰·배송 정책·활동 이력 목록이 해당하며, 마지막 페이지로 바로 뛰는 버튼만 감춰지고 이전·다음 이동은 그대로 동작합니다.
|
||||
- 쿠폰 사용조건의 상품 검색에서 결과가 많을 때 목록 끝까지 스크롤해도 다음 묶음이 더 불러와지지 않던 문제를 수정했습니다.
|
||||
- 관리자가 주문상품을 일괄 구매확정할 때와 구매자가 직접 구매확정할 때, 구매확정 시점이 최초 확정 시각으로 동일하게 보존됩니다 — 이미 확정된 주문을 다시 확정 처리해도 시점이 덮어써지지 않습니다.
|
||||
- 구매자 주문 상세의 결제 정보 영역에 결제 플러그인이 제공하는 공급가액·부가세·영수증 링크·에스크로 구매확정 버튼이 표시되지 않던 문제를 수정했습니다.
|
||||
- 관리자가 카테고리 이미지를 등록·삭제하거나 순서를 바꾼 뒤 표시되는 안내 문구가 번역된 문장 대신 내부 식별자가 그대로 보이던 문제를 수정했습니다. 이제 사용 중인 언어에 맞는 안내 문구가 표시됩니다.
|
||||
|
||||
## [1.0.4] - 2026-07-16
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"identifier": "sirsoft-ecommerce",
|
||||
"version": "1.0.5",
|
||||
"version": "1.1.0",
|
||||
"components": {
|
||||
"basic": [],
|
||||
"composite": [],
|
||||
|
||||
Loaded 100 of 484 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user