fix(core,board,ecommerce,page,gdpr,ckeditor5,kginicis,admin_basic,basic): 목록 조회·검증 계층 정비 및 감사 지적 전건 처리
목록 조회 성능 축(깊은 OFFSET·정렬·색인)과 그 검증 계층에서 계획서 전수검수와 3회에 걸친 감사가 지적한 항목을 처리했다. 세부 경위는 의 각 회차 문서에 있다. 검증 계층 — 컨트롤러가 base Request 를 직접 주입받던 확장 13곳을 전용 FormRequest 로 옮겼다. 옮기면서 기존 동작 계약은 그대로 두었다: 상한 초과 limit 을 거부하지 않고 상한까지 반환하던 공개 API, per_page 를 범위로 조정하던 관리자 목록, 미지원 period 를 year 로 해석하던 인기글 목록 모두 종전과 같은 응답을 낸다. 상한/폴백을 rules 로 승격시키면 200 이던 응답이 422 가 되어 기존 링크가 깨지므로, 규칙은 타입만 닫고 클램프·폴백은 접근자가 맡는다. period 는 접근자가 닫힌 집합만 반환해 캐시 키 공간도 함께 닫힌다. ckeditor5 이미지 업로드만 ResponseHelper 봉투를 쓰지 않는다. 응답을 파싱하는 주체가 CDN 으로 로드되는 상위 CKEditor5 43.3.1 의 SimpleUploadAdapter 라 규약을 바꿀 수 없어, 각 응답 지점에 사유를 명시한 면제를 부착하고 근거를 API 문서에 남겼다. 하네스 — 룰 5개의 대상 경로 패턴이 매처와 맞지 않아 번들 확장 컨트롤러가 검사 대상에서 통째로 빠져 있었다. 패턴을 고치자 확장 위반 17건이 드러나 전건 처리했다. severity 오타가 요약 집계 양쪽에 안 잡혀 "0 error" 로 보고되던 문제도 런너 사전 검증으로 막았다. 정렬 게이트 대조 하네스는 관계 정렬 변형만 쓰는 저장소를 탐지하지 못한 채 통과시키고 있었다. 탐지·제외·인자 파싱을 함께 고치고 단위 테스트를 신설했다.
This commit is contained in:
HeuJung
@@ -115,7 +115,7 @@
|
||||
| [module-assets.md](docs/extension/module-assets.md) | 모듈 프론트엔드 에셋 시스템 | module.json에 에셋 매니페스트 정의 (js, css, loading strategy) |
|
||||
| [module-basics.md](docs/extension/module-basics.md) | 모듈 개발 기초 | 디렉토리: vendor-module (예: sirsoft-ecommerce) |
|
||||
| [module-commands.md](docs/extension/module-commands.md) | 모듈 Artisan 커맨드 | 목록: php artisan module:list |
|
||||
| [module-i18n.md](docs/extension/module-i18n.md) | 모듈 다국어 시스템 | 백엔드: /lang/{locale}/*.php → __('vendor-module::key') |
|
||||
| [module-i18n.md](docs/extension/module-i18n.md) | 모듈 다국어 시스템 | 백엔드: /src/lang/{locale}/*.php → __('vendor-module::key') ... |
|
||||
| [module-identity-settings.md](docs/extension/module-identity-settings.md) | 모듈/플러그인 본인인증(IDV) 설정 통합 가이드 | 정책/목적/메시지: module.php::getIdentity{Policies,Purposes,Mess... |
|
||||
| [module-layouts.md](docs/extension/module-layouts.md) | 모듈 레이아웃 시스템 | 위치: modules/_bundled/vendor-module/resources/layouts/admi... |
|
||||
| [module-routing.md](docs/extension/module-routing.md) | 모듈 라우트 규칙 | URL prefix 자동: /api/modules/[vendor-module]/... |
|
||||
@@ -160,7 +160,7 @@
|
||||
|
||||
| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |
|
||||
|------|------|--------------|----------------|
|
||||
| `gnuboard7-hello_module` | 모듈 | [docs/api/](modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 2 |
|
||||
| `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 / 231 |
|
||||
| `sirsoft-page` | 모듈 | [docs/api/](modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
|
||||
@@ -363,12 +363,36 @@ Icon 은 `<i>` 글리프라 박스 크기가 곧 `font-size` 다. `w-N h-N` 은
|
||||
| `->paginate($perPage)` / `->paginate($perPage, ['*'])` (컬럼 목록 미지정) | 목록이 실제로 쓰는 컬럼만 명시. 깊은 OFFSET 이 가능한 목록은 `PaginatesWithDeferredJoin` |
|
||||
| 요청 값에서 온 정렬 컬럼을 그대로 `orderBy` 에 전달 | `ResolvesSortSpec` 으로 닫힌 집합 해석 (방향만 검사하는 `in_array` 는 보호가 아니다) |
|
||||
| 지연 조인의 `$query` 에 미리 `orderBy`/`with`/`select` 적용 | 필터/where 만 적용해 넘기고, 정렬·관계·컬럼은 trait 인자로 전달 |
|
||||
| 쿼리에 `with()` 만 하고 `relations:` 인자 생략 | 관계는 `relations:` 로 전달 — trait 이 inner 뿐 아니라 **outer 에서도** eager load 를 지우므로 관계가 조용히 사라진다 (예외·쿼리 오류 없이 응답에서 필드만 없어져 관계를 단언하지 않는 테스트는 전부 통과) |
|
||||
| 목록 SELECT 에 `SUBSTRING(content, 1, N)` 을 두고 프루닝했다고 간주 | 오버플로 페이지 읽기가 그대로 발생 — 잘라내기는 outer(`$columns`)에서만 |
|
||||
| 그룹 쿼리(`groupBy`)의 총 건수를 `count()` 로 계산 | `getCountForPagination()` (서브쿼리로 감싸 그룹 수를 센다) |
|
||||
| raw SQL 안에 테이블명·별칭을 문자열로 조립 | 테이블명은 `(new Model)->getTable()`, 프리픽스는 `DB::getTablePrefix()`, 별칭은 빌더(`join($table.' as uc', …)`)가 만들게 |
|
||||
| `whereRaw('1 = 0')` / `where($c, DB::raw("({$sub->toSql()})"))` + `mergeBindings` | `whereIn($key, [])` / `where($c, '=', $sub)` (빌더가 바인딩까지 처리) |
|
||||
| 화면 정렬 셀렉트에 게이트가 모르는 컬럼을 넣기 | `화면 옵션 ⊆ FormRequest 게이트 ⊆ Repository 화이트리스트` — 어긋나면 422 후 직전 목록이 남아 정렬된 것처럼 보인다 |
|
||||
| 분류값 필터의 허용 어휘를 화면·게이트·기록 지점에 각각 리터럴로 적기 | 어휘는 Enum 단일 출처에서 파생 — `화면 필터 옵션 = 라벨 키 = 실제 기록 어휘`. 부분집합이 되면 빠진 값으로 기록된 행이 어떤 필터 조합으로도 도달 불가하고, 라벨 키가 없는 값은 목록 셀에 원시 키 문자열로 노출된다 |
|
||||
| 목록 응답이 `last_page > 1` 인데 화면에 페이저·총건수가 없음 | 페이지 이동 컨트롤과 총건수를 함께 노출 — 없으면 1페이지 밖 행이 조용히 잘리고, 잘렸다는 사실조차 화면에 나타나지 않는다 |
|
||||
| 쿼리 파라미터 불리언에 `boolean` 규칙만 부착 | `prepareForValidation()` 으로 `"true"`/`"false"` 정규화 (쿼리는 문자열로 도착 — 화면이 그 형태로 보내면 목록 전체가 422). 단, 해석 불가한 값은 건드리지 말 것 |
|
||||
| 같은 화면의 개수 배지와 그 배지가 여는 목록이 서로 다른 엔드포인트 | 배지 계산과 목록 조회는 같은 스코프의 같은 데이터소스에서 |
|
||||
| 관계 테이블 컬럼 정렬을 `join`+`groupBy` 로 구현 | `SortsByRelatedColumn` 의 상관 서브쿼리 (1:N 조인은 원 행을 부풀려 총 건수·페이지 경계를 깨고, INNER 는 자식 없는 행을 지운다) |
|
||||
| 관계 정렬을 넣고 인덱스는 그대로 | `(외래키, 정렬컬럼)` 복합 인덱스 마이그레이션 동반 (서브쿼리가 행마다 실행된다) |
|
||||
| 페이지네이션 정렬을 비고유 컬럼(`created_at` 등)으로만 끝내기 | 정렬 마지막에 기본키를 덧붙여 전순서 보장 (동률 구간에서 인접 페이지가 같은 행을 중복 노출하고 다른 행을 누락한다) |
|
||||
|
||||
> 상세: [service-repository.md "목록 조회 컬럼 프루닝과 지연 조인" / "정렬 컬럼 화이트리스트" / "허용되는 Raw 쿼리"](docs/backend/service-repository.md)
|
||||
> 상세: [service-repository.md "목록 조회 컬럼 프루닝과 지연 조인" / "정렬 컬럼 화이트리스트" / "화면 정렬 옵션은 게이트의 부분집합이어야 한다" / "관계 테이블 컬럼 기준 정렬" / "허용되는 Raw 쿼리"](docs/backend/service-repository.md)
|
||||
|
||||
### 검색 인덱스 재생성(리인덱싱)
|
||||
|
||||
| ❌ 금지 | ✅ 올바른 사용 |
|
||||
|--------|---------------|
|
||||
| 재생성을 자동 트리거(마이그레이션 종료·확장 업데이트 완료 등)에 연결 | 운영자가 **명시적으로 선택**했을 때만 수행. 인덱스 잠금·전체 재색인 비용이 운영 중 사이트를 멈춘다 |
|
||||
| 재생성 체크 상태를 전역에 남겨 다음 모달 진입에 이월 | 모달 진입 시드와 제출 후 초기화 **양쪽**에서 해제. 이월되면 운영자가 아무것도 누르지 않았는데 재생성이 수행되고, 서버 옵인 가드는 정상이라 HTTP 테스트로는 드러나지 않는다 |
|
||||
| 모듈·플러그인 모달이 같은 전역 키 공유 | 면마다 별도 키 (한쪽 체크가 다른 쪽으로 전이 금지) |
|
||||
| 응답 헬퍼가 `JsonResource::resolve()` 만 호출해 `additional()` 유실 | 부가 데이터를 응답 최상위에 병합 — 색인 누락은 오류 없이 "검색 0건" 으로만 나타나므로 응답 페이로드가 유일한 통로다 |
|
||||
| 재생성 수행을 곧 복구로 간주 | `remaining` 은 **재생성 후 재점검** 결과 — "재생성했다" 와 "복구됐다" 를 구분해 보고 |
|
||||
| 점검 커맨드의 비-0 종료를 "실행 실패" 로 표시 | 이상 발견 신호다. 종료 코드와 출력을 그대로 노출 |
|
||||
| 특정 엔진(FULLTEXT) 전용으로 점검·재생성 구현 | `SearchIndexMaintainer` 계약 + `core.search.index_maintainers` 훅 |
|
||||
| "점검 대상 0" 과 "점검 불가" 를 같은 문구로 보고 | 구분 보고 — 뭉뚱그리면 "인덱스가 다 정상" 으로 읽힌다 |
|
||||
|
||||
> 상세: [search-system.md](docs/backend/search-system.md)
|
||||
|
||||
### Listener 데이터 접근
|
||||
|
||||
|
||||
+22
-3
@@ -49,7 +49,17 @@
|
||||
|
||||
#### 목록 성능
|
||||
|
||||
- 목록 화면이 뒤쪽 페이지로 갈수록 느려지는 문제를 구조적으로 해결할 수 있도록, 확장이 함께 쓸 수 있는 공통 조회 방식을 코어에 추가했습니다. 목록을 두 단계(먼저 이번 페이지에 해당하는 항목만 추려내고, 그 항목에 대해서만 본문·상세 정보를 읽기)로 나눠 읽으므로 게시글·주문·로그가 수십만 건으로 늘어나도 마지막 페이지 조회 비용이 첫 페이지와 비슷하게 유지됩니다. 목록 정렬 기준을 미리 정해 둔 항목으로만 해석하는 공통 처리도 함께 제공하므로, 확장이 목록 조회를 직접 만들 때 정렬 처리를 매번 새로 구현하지 않아도 됩니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 검색 인덱스가 실제로 내용을 담고 있는지 점검하고, 비어 있으면 다시 만들 수 있는 기능을 추가했습니다. 인덱스가 비면 검색은 오류 없이 "결과 없음" 만 돌려주기 때문에 그동안은 알아차릴 방법이 없었습니다. 관리자 > 개발 도구에서 「검색 인덱스 점검」 으로 확인할 수 있고, `php artisan search:index` 로도 실행됩니다. 점검·재생성 방식은 검색 엔진마다 다르므로, 다른 검색 엔진을 쓰는 확장도 자기 방식의 점검을 등록해 같은 화면에서 함께 다룰 수 있습니다.
|
||||
- 다시 만들기는 **선택할 때만** 실행됩니다. 인덱스를 다시 만드는 동안에는 해당 인덱스가 잠기거나 전체 재색인이 일어나 운영 중인 사이트에 영향을 주기 때문입니다. 확장·코어 업데이트 화면과 명령어에 「업데이트 후 검색 인덱스 재생성」 선택 항목을 두었고, 선택하지 않아도 색인이 비어 있으면 그 사실은 알려 드립니다. 사이트 규모가 크다면 선택하지 말고 접속이 적은 시간에 따로 실행하시길 권합니다.
|
||||
- 업데이트 화면의 「검색 인덱스 재생성」 선택이 그 창에서만 유효하도록 바로잡았습니다. 예전에는 한 번 선택하면 창을 닫거나 업데이트를 마친 뒤에도 선택이 남아 있어, 다음 확장을 업데이트할 때 아무것도 고르지 않았는데 인덱스 재생성이 다시 실행됐습니다.
|
||||
- 확장을 업데이트하면 색인이 비어 있는 검색 인덱스가 있는지 결과가 함께 전달되도록 바로잡았습니다. 예전에는 점검은 이루어졌지만 그 결과가 화면까지 오지 않아 운영자가 알 수 없었습니다.
|
||||
- 모듈·플러그인 업데이트 완료 안내에 확장 이름과 버전이 표시되지 않던 문제를 수정했습니다.
|
||||
- 모듈·플러그인 목록의 총 개수와 페이지 이동이 동작하지 않던 문제를 수정했습니다. 설치된 확장이 12개를 넘으면 2페이지 이후 항목이 화면에 나타나지 않았습니다.
|
||||
- `php artisan module:check-updates` 등 업데이트 확인 명령이 업데이트가 있는 확장을 「최신」 으로 표시하고 요약도 "업데이트 가능 0개" 로 알리던 문제를 수정했습니다.
|
||||
- 통신이 끊겨 요청이 전송되지 못했을 때 내부 식별 문구가 그대로 표시되던 것을 네트워크 오류 안내로 바꿨습니다.
|
||||
- 개발 도구에서 점검 명령이 이상을 발견해 알려 준 경우를 「실행 실패」 로 표시하던 것을 종료 코드 안내로 바꿨습니다. 점검은 정상 수행된 것이며, 발견된 내용은 출력에 그대로 표시됩니다.
|
||||
|
||||
- 목록 화면이 뒤쪽 페이지로 갈수록 느려지는 문제를 구조적으로 해결할 수 있도록, 확장이 함께 쓸 수 있는 공통 조회 방식을 코어에 추가했습니다. 목록을 두 단계(먼저 이번 페이지에 해당하는 항목만 추려내고, 그 항목에 대해서만 본문·상세 정보를 읽기)로 나눠 읽으므로 게시글·주문·로그가 수십만 건으로 늘어나도 마지막 페이지 조회 비용이 첫 페이지와 비슷하게 유지됩니다. 목록 정렬 기준을 미리 정해 둔 항목으로만 해석하는 공통 처리도 함께 제공하므로, 확장이 목록 조회를 직접 만들 때 정렬 처리를 매번 새로 구현하지 않아도 됩니다. 주문 목록의 「발송일」처럼 정렬 기준이 다른 표에 있는 값일 때도 총 건수와 페이지 경계가 어긋나지 않게 조회하는 공통 처리를 함께 넣었습니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
|
||||
#### 성능 점검
|
||||
|
||||
@@ -59,6 +69,7 @@
|
||||
|
||||
- 활동 로그·알림 발송 이력·본인인증 기록·스케줄 실행 이력·회원 목록을 뒤쪽 페이지에서도 빠르게 열 수 있도록 조회 방식을 바꿨습니다. 예전에는 페이지가 뒤로 갈수록 건너뛰는 기록의 본문·변경 내역까지 함께 읽어 느려졌지만, 이제 현재 페이지에 해당하는 기록만 상세 정보를 읽습니다. 화면에 보이는 내용은 이전과 동일합니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 확장이 업로드 허용 형식을 넓힐 수 있도록 `core.attachment.allowed_extensions` 필터를 추가했습니다. 관리자 설정 목록을 기준으로, 확장이 자기 기능에 필요한 형식만 덧붙일 수 있습니다.
|
||||
- 활동 로그·알림 발송 이력·회원 목록의 정렬 색인을 정비했습니다. 같은 시각에 쌓인 기록이 많은 구간에서 순서를 정하느라 생기던 추가 작업이 사라져, 기록이 많은 사이트일수록 목록이 빨라집니다. 기존 사이트도 업데이트 시 자동으로 반영되며, 기록이 아주 많은 경우 이 과정에 수 분이 걸리고 그동안 해당 기록의 저장이 잠시 대기할 수 있습니다.
|
||||
- 확장이 검증 규칙을 추가할 때 쓰는 필터 이름 10개를 나머지 92개와 같은 규칙(`{대상}.{동작}_validation_rules`)으로 통일했습니다. 본인인증 메시지와 알림 관련 화면이 대상이며, 예전 이름(`...filter_index_rules` 형태)을 사용하던 확장은 새 이름으로 바꿔야 검증 규칙 추가가 계속 동작합니다. 코어와 기본 제공 확장에는 이 이름을 사용하던 곳이 없어 영향이 없습니다.
|
||||
- 같은 규칙에서 벗어나 있던 필터 이름 6개(플러그인 설정 저장, 비밀번호 재설정 토큰 확인, 비밀번호 확인, 변경사항 조회, 통합 검색, 프로필 사진 업로드)를 추가로 통일했습니다. 이번에는 예전 이름도 함께 계속 발행하므로 기존 확장은 수정 없이 그대로 동작하며, 예전 이름을 사용 중인 확장이 있으면 서버 기록에 한 번 안내가 남습니다. 새로 만드는 확장은 새 이름을 사용하세요.
|
||||
|
||||
@@ -96,6 +107,11 @@
|
||||
|
||||
#### 확장·데이터베이스 안정성
|
||||
|
||||
- 관리자 역할 관리·언어팩 관리·알림 목록에서 같은 시각에 등록된 항목이 여러 건일 때, 페이지를 넘기면 같은 항목이 두 번 보이고 다른 항목은 아예 보이지 않던 문제를 수정했습니다. 이제 페이지를 모두 넘겨도 목록에 있는 항목이 빠짐없이 한 번씩만 나옵니다.
|
||||
- 메뉴 관리 목록에서 검색 조건을 하나도 걸지 않은 채 정렬만 바꾸면 순서가 그대로이던 문제를 수정했습니다. 검색 조건이 있을 때만 정렬이 반영되고 있었으며, 이제 조건 유무와 관계없이 선택한 정렬이 적용됩니다.
|
||||
- 메뉴 관리 검색에서 한글 메뉴명으로 찾으면 결과가 나오지 않던 문제를 수정했습니다. 이제 한국어·영어 어느 쪽 메뉴명으로도 검색되고, 이름 정렬도 화면에 보이는 글자 기준으로 정렬됩니다.
|
||||
- 목록의 열 제목을 눌렀을 때 지금 보고 있는 페이지의 줄만 순서가 바뀌면서 전체가 정렬된 것처럼 보이던 문제를 수정했습니다. 페이지를 나눠 불러오는 목록에서 열 제목 정렬을 지원하지 않는 화면은 이제 정렬 표시를 띄우지 않으므로, 정렬 결과를 잘못 읽을 일이 없습니다. 정렬은 화면 위쪽의 정렬 선택으로 이용할 수 있습니다.
|
||||
- 언어팩 관리 목록이 모듈의 내장 번역을 실제 화면에 쓰이지 않는 위치 기준으로 보여주던 문제를 수정했습니다. 그 결과 일부 모듈의 한국어·영어 내장 번역이 목록에 아예 나오지 않았고, 번역 대상으로 표시된 문구를 고쳐도 화면에 반영되지 않았습니다. 이제 목록과 실제 화면의 문구 출처가 같습니다.
|
||||
- 데이터베이스 연결이 일시적으로 끊기거나 확장 설치가 중간에 실패한 직후 확장 목록을 다시 만들면, 설치된 모듈·플러그인 정보가 통째로 비워지면서 게시판·쇼핑몰 등 모든 확장 화면이 500 오류를 내던 문제를 수정했습니다. 이제 확장 폴더가 그대로 남아 있는데 목록만 비어 있으면 기존 정보를 지우지 않고 보존하며, 왜 갱신하지 않았는지 로그에 남깁니다.
|
||||
- 확장 목록이 손상된 상태에서 복구 명령을 실행하면 목록은 되살아나지만 확장 기능 연결이 비어 있는 채로 남아, 명령을 두 번 실행해야 완전히 복구되던 문제를 수정했습니다. 이제 한 번 실행으로 모두 복구됩니다.
|
||||
- 데이터베이스에서 일부 컬럼의 설명이 비어 있던 문제를 바로잡았습니다. 회원·작성자 등 다른 표를 가리키는 컬럼이 대상이며, 업그레이드하면 이미 운영 중인 데이터베이스에도 설명이 채워집니다(직접 적어 넣은 설명은 그대로 둡니다).
|
||||
@@ -120,6 +136,11 @@
|
||||
- 일부 안내가 실제 문장 대신 내부 식별자(`messages.auth.unauthenticated` 같은 문자열)로 표시되던 문제를 수정했습니다. 로그인하지 않았거나 역할 권한이 없어 요청이 거절될 때, 메뉴에 역할을 지정할 때, 확장 식별자를 잘못 입력했을 때, 활동 로그를 기간·유형으로 검색할 때가 해당됩니다.
|
||||
- 환경설정 저장이 실패했을 때 안내 문구에 항목 이름이 `security.password min length` 같은 내부 식별자로 표시되던 문제를 수정했습니다. 보안·업로드·SEO·고급·드라이버·메일 등 모든 설정 항목이 화면에 보이는 한글 항목명으로 안내됩니다.
|
||||
- 플러그인을 GitHub 주소나 ZIP 파일로 설치할 때의 입력 안내가 내부 식별자로 표시되던 문제를 수정했습니다. 주소 형식이 잘못됐거나, ZIP이 아닌 파일을 올렸거나, 파일 용량을 초과했을 때 정상 문장으로 안내합니다.
|
||||
- 목록의 열 제목을 눌러 정렬할 때, 이미 다른 열로 정렬 중이었다면 화살표는 새로 누른 열에 표시되면서 실제 정렬은 이전 열 기준으로 바뀌던 문제를 수정했습니다. 표시와 실제 정렬 기준이 어긋나 결과를 신뢰할 수 없었으며, 이제 누른 열 기준으로 한 번에 정렬됩니다.
|
||||
- 목록에서 뒤쪽 페이지를 보던 중 정렬을 바꾸면 이전 페이지 번호에 그대로 머물러, 정렬을 바꿨는데 엉뚱한 구간이 보이거나 빈 목록이 나오던 문제를 수정했습니다. 이제 정렬을 바꾸면 항상 첫 페이지부터 보여줍니다. 사용자 관리·게시판 신고현황·페이지 관리 목록이 해당됩니다.
|
||||
- 사용자 관리 목록에서 "페이지당 개수"가 10개로 표시되는데 실제로는 15개가 나오던 문제를 수정했습니다. 표시된 값과 실제 목록 건수가 일치합니다. 일정 관리 목록에서도 표시가 20개 목록을 10개로 잘못 안내하던 문제를 함께 바로잡았습니다.
|
||||
- 알림 발송 이력에서 정렬을 "수신자명순" 또는 "제목순"으로 바꾸면 목록이 비면서 오류 안내가 뜨던 문제를 수정했습니다. 화면이 제공하는 정렬인데 서버가 거부하고 있었으며, 이제 두 정렬 모두 정상 동작합니다. 많은 이력에서도 빠르게 정렬되도록 색인을 함께 추가했습니다.
|
||||
- 마이페이지 활동 목록에서 한 페이지에 표시할 개수를 0이나 음수로 요청하면 서버 오류가 나던 문제를 수정했습니다. 이제 허용 범위(1~100)로 자동 조정됩니다.
|
||||
- 레이아웃 편집기 화면이 정상 동작하는데도 서버가 "페이지 없음"(404)으로 응답하던 문제를 수정했습니다. 화면은 그대로 보였지만 브라우저 캐싱과 서버 접속 기록에서 없는 페이지로 취급되던 상태입니다.
|
||||
- 주소 끝에 슬래시가 붙은 형태(예: `/admin/`)로 접속하면 화면이 "페이지 없음"(404)으로 뜨던 문제를 수정했습니다. 특히 로그인이 풀린 상태에서 이렇게 접속하면 로그인 화면으로 넘어가지 않고 404가 나타났습니다. 이제 끝 슬래시가 있어도 정상적으로 같은 페이지로 연결됩니다.
|
||||
|
||||
@@ -1500,7 +1521,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
|
||||
- 휴대폰 인증, 아이핀 인증 등 본인인증 기능 제공
|
||||
- 사용자 관리 화면 레이아웃 확장 (본인인증 상세/폼)
|
||||
- 역할 기반 접근 제어 (본인인증 관리자)
|
||||
- 다국어 지원 (ko, en)
|
||||
|
||||
#### 템플릿: sirsoft-admin_basic (관리자)
|
||||
|
||||
@@ -1536,7 +1556,6 @@ abort 발생 시 운영자에게 수동 재개 명령 (`php artisan core:execute
|
||||
- CMS 페이지 표시 화면
|
||||
- 에러 페이지 (403, 404, 500, 503)
|
||||
- 점검 모드(maintenance) 전용 페이지
|
||||
- 반응형 레이아웃 (데스크톱/태블릿/모바일)
|
||||
|
||||
#### 다국어 시스템 (i18n)
|
||||
|
||||
|
||||
@@ -71,19 +71,22 @@ class ListAxisRunner implements BenchmarkAxisRunner
|
||||
$notify("비움: {$table}");
|
||||
}
|
||||
|
||||
$columns = $this->existingColumns($table, (array) $profile->option('columns', ['*']));
|
||||
$order = $this->existingOrder($table, (array) $profile->option('order', [['id', 'desc']]));
|
||||
|
||||
if ($options->seed > 0) {
|
||||
$notify("시딩: {$table} ".number_format($options->seed).' 건');
|
||||
$this->seeder->seed(
|
||||
$table,
|
||||
$options->seed,
|
||||
(array) $profile->option('seed_overrides', []),
|
||||
fn (int $inserted, int $total) => $notify(sprintf(' 시딩 %s / %s', number_format($inserted), number_format($total)))
|
||||
fn (int $inserted, int $total) => $notify(sprintf(' 시딩 %s / %s', number_format($inserted), number_format($total))),
|
||||
// 정렬 기준 컬럼은 nullable 이어도 채운다 — 비워두면 합성 행이 전부 동률이 되어
|
||||
// 계측이 정렬 인덱스가 아니라 tie-break 경로를 잰다.
|
||||
array_column($order, 0),
|
||||
);
|
||||
}
|
||||
|
||||
$columns = $this->existingColumns($table, (array) $profile->option('columns', ['*']));
|
||||
$order = $this->existingOrder($table, (array) $profile->option('order', [['id', 'desc']]));
|
||||
|
||||
$rows = [];
|
||||
$notes = [];
|
||||
|
||||
|
||||
@@ -0,0 +1,203 @@
|
||||
<?php
|
||||
|
||||
namespace App\Benchmark;
|
||||
|
||||
use App\Benchmark\DTO\BenchmarkProfile;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
/**
|
||||
* 목록 프로파일 선언에서 필요한 색인을 도출하고 스키마와 대조합니다.
|
||||
*
|
||||
* 배경: 지연 조인은 inner 가 키 컬럼만 읽게 만들지만, 그 inner 가 **인덱스 순서 그대로**
|
||||
* 끝나야 깊은 OFFSET 이 싸진다. 정렬을 덮는 인덱스가 없으면 inner 도 filesort 로 전체를
|
||||
* 훑으므로 개선 폭이 사라진다. 그런데 어떤 색인이 필요한지는 지금까지 테이블마다 사람이
|
||||
* 손으로 설계했고, 맞는지 검사하는 장치가 없었다.
|
||||
*
|
||||
* 필요한 정보는 이미 계측 프로파일에 선언돼 있다 — `filters` / `order` / `soft_delete` 를
|
||||
* 이으면 그대로 색인 레시피가 된다:
|
||||
*
|
||||
* (등치 필터 컬럼들 → soft_delete 면 deleted_at → 정렬 컬럼들 → 기본키)
|
||||
*
|
||||
* 이 클래스는 그 도출을 한 곳에 두어, 새 목록이 프로파일을 선언하는 순간 필요한 색인이
|
||||
* 자동으로 드러나게 한다. 색인 설계를 사람의 기억이 아니라 이미 있는 선언에 붙이는 것이라
|
||||
* 호출자가 추가로 선언할 것은 없다.
|
||||
*
|
||||
* 등치가 아닌 필터(`in` / `not in` / 범위)는 선행 컬럼에 넣지 않는다 — 선행 컬럼이 등치로
|
||||
* 고정되지 않으면 뒤따르는 정렬 컬럼을 인덱스 순서로 쓸 수 없기 때문이다. 이 판정을 틀리면
|
||||
* "색인이 있는데도 filesort" 라는, 눈으로는 구분되지 않는 상태를 정상으로 보고하게 된다.
|
||||
*/
|
||||
class ListIndexAdvisor
|
||||
{
|
||||
/** 선행 컬럼으로 쓸 수 있는 연산자 (등치만) */
|
||||
private const EQUALITY_OPERATORS = ['='];
|
||||
|
||||
/**
|
||||
* 프로파일이 요구하는 색인 선행 컬럼 목록을 도출합니다.
|
||||
*
|
||||
* @param array<string, mixed> $options 목록 프로파일 옵션
|
||||
* @return array<int, string> 선행 컬럼 순서 (등치 → deleted_at → 정렬 → 기본키)
|
||||
*/
|
||||
public function requiredColumns(array $options, string $keyName = 'id'): array
|
||||
{
|
||||
$leading = [];
|
||||
|
||||
foreach (($options['filters'] ?? []) as $column => $declared) {
|
||||
if (is_array($declared) && count($declared) === 2 && is_string($declared[0])) {
|
||||
// [연산자, 값] 형태 — 등치만 선행 컬럼 자격이 있다
|
||||
if (in_array(strtolower($declared[0]), self::EQUALITY_OPERATORS, true)) {
|
||||
$leading[] = (string) $column;
|
||||
}
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
// 값만 준 형태는 등가 비교
|
||||
$leading[] = (string) $column;
|
||||
}
|
||||
|
||||
if ($options['soft_delete'] ?? false) {
|
||||
$leading[] = 'deleted_at';
|
||||
}
|
||||
|
||||
foreach (($options['order'] ?? []) as $spec) {
|
||||
$column = is_array($spec) ? ($spec[0] ?? null) : $spec;
|
||||
|
||||
if (is_string($column) && $column !== '') {
|
||||
$leading[] = $column;
|
||||
}
|
||||
}
|
||||
|
||||
// 정렬 끝에 기본키가 없으면 동률 구간에서 filesort 가 남는다
|
||||
if (end($leading) !== $keyName) {
|
||||
$leading[] = $keyName;
|
||||
}
|
||||
|
||||
return array_values(array_unique($leading));
|
||||
}
|
||||
|
||||
/**
|
||||
* 도출한 색인이 실제 스키마에 있는지 대조합니다.
|
||||
*
|
||||
* @param array<string, mixed> $options 목록 프로파일 옵션
|
||||
* @return array{
|
||||
* table: string|null,
|
||||
* required: array<int, string>,
|
||||
* satisfied_by: string|null,
|
||||
* partial_by: string|null,
|
||||
* status: string
|
||||
* } status: satisfied | tiebreak_missing | missing | table_absent | not_applicable
|
||||
*/
|
||||
public function inspect(array $options, string $keyName = 'id'): array
|
||||
{
|
||||
$table = $options['table'] ?? null;
|
||||
$required = $this->requiredColumns($options, $keyName);
|
||||
|
||||
$result = [
|
||||
'table' => $table,
|
||||
'required' => $required,
|
||||
'satisfied_by' => null,
|
||||
'partial_by' => null,
|
||||
'status' => 'not_applicable',
|
||||
];
|
||||
|
||||
if (! is_string($table) || $table === '') {
|
||||
return $result;
|
||||
}
|
||||
|
||||
if (! Schema::hasTable($table)) {
|
||||
$result['status'] = 'table_absent';
|
||||
|
||||
return $result;
|
||||
}
|
||||
|
||||
// 기본키를 뺀 형태 — 색인은 있으나 tie-break 만 빠진 경우를 구분한다.
|
||||
// 이 둘은 처방이 다르다: 전자는 색인 신설, 후자는 기존 색인에 기본키를 덧붙이는 교체.
|
||||
$withoutKey = $required;
|
||||
if (end($withoutKey) === $keyName) {
|
||||
array_pop($withoutKey);
|
||||
}
|
||||
|
||||
foreach (Schema::getIndexes($table) as $index) {
|
||||
$columns = $index['columns'] ?? [];
|
||||
|
||||
if ($result['satisfied_by'] === null && $this->hasPrefix($columns, $required)) {
|
||||
$result['satisfied_by'] = $index['name'];
|
||||
}
|
||||
|
||||
if ($this->hasPrefix($columns, $withoutKey)) {
|
||||
// UNIQUE 색인은 값이 중복되지 않으므로 그 컬럼만으로 이미 전순서다.
|
||||
// 기본키를 덧붙일 필요가 없고, 붙여도 filesort 가 줄지 않는다.
|
||||
if ($result['satisfied_by'] === null && ($index['unique'] ?? false)) {
|
||||
$result['satisfied_by'] = $index['name'];
|
||||
}
|
||||
|
||||
if ($result['partial_by'] === null) {
|
||||
$result['partial_by'] = $index['name'];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$result['status'] = match (true) {
|
||||
$result['satisfied_by'] !== null => 'satisfied',
|
||||
$result['partial_by'] !== null => 'tiebreak_missing',
|
||||
default => 'missing',
|
||||
};
|
||||
|
||||
return $result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 프로파일에 선언된 면제 사유를 돌려줍니다.
|
||||
*
|
||||
* 행 수가 고정되거나 상한이 작아 색인이 불필요한 목록은 프로파일에 사유를 적어 면제한다.
|
||||
* 사유 없는 면제를 허용하지 않는 이유는, 면제가 쌓이면 검사 자체가 무의미해지는데
|
||||
* 사유가 없으면 나중에 그 판단이 여전히 옳은지 확인할 방법이 없기 때문이다.
|
||||
*
|
||||
* @param array<string, mixed> $options 목록 프로파일 옵션
|
||||
* @return string|null 면제 사유 (없으면 null)
|
||||
*/
|
||||
public function exemptionReason(array $options): ?string
|
||||
{
|
||||
$reason = $options['index_exempt'] ?? null;
|
||||
|
||||
return is_string($reason) && trim($reason) !== '' ? trim($reason) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 프로파일 목록을 한 번에 점검합니다.
|
||||
*
|
||||
* @param array<string, BenchmarkProfile> $profiles 목록 축 프로파일
|
||||
* @return array<int, array<string, mixed>> 프로파일별 점검 결과
|
||||
*/
|
||||
public function inspectAll(array $profiles): array
|
||||
{
|
||||
$rows = [];
|
||||
|
||||
foreach ($profiles as $key => $profile) {
|
||||
$options = $profile->options ?? [];
|
||||
|
||||
$rows[] = array_merge(
|
||||
['profile' => is_string($key) ? $key : $profile->qualifiedKey()],
|
||||
$this->inspect($options),
|
||||
['exemption' => $this->exemptionReason($options)]
|
||||
);
|
||||
}
|
||||
|
||||
return $rows;
|
||||
}
|
||||
|
||||
/**
|
||||
* 인덱스 컬럼이 요구 목록을 선행 프리픽스로 포함하는지 판정합니다.
|
||||
*
|
||||
* @param array<int, string> $columns 인덱스 컬럼 순서
|
||||
* @param array<int, string> $required 요구 선행 컬럼
|
||||
*/
|
||||
private function hasPrefix(array $columns, array $required): bool
|
||||
{
|
||||
if ($required === [] || count($columns) < count($required)) {
|
||||
return false;
|
||||
}
|
||||
|
||||
return array_slice(array_values($columns), 0, count($required)) === array_values($required);
|
||||
}
|
||||
}
|
||||
@@ -32,16 +32,18 @@ class SyntheticSeeder
|
||||
* @param int $count 시딩 건수
|
||||
* @param array<string, mixed> $overrides 컬럼별 고정값 (실제 조회 조건과 맞추기 위한 지정)
|
||||
* @param \Closure|null $onProgress 진행 콜백 (int $inserted, int $total)
|
||||
* @param array<int, string> $requiredColumns nullable 이어도 반드시 채울 컬럼 (계측이 정렬 기준으로 삼는 컬럼)
|
||||
*/
|
||||
public function seed(string $table, int $count, array $overrides = [], ?\Closure $onProgress = null): void
|
||||
public function seed(string $table, int $count, array $overrides = [], ?\Closure $onProgress = null, array $requiredColumns = []): void
|
||||
{
|
||||
$fillable = $this->fillableColumns($table);
|
||||
$required = $this->requiredColumnDefinitions($table, $requiredColumns, $fillable);
|
||||
|
||||
$chunk = [];
|
||||
$inserted = 0;
|
||||
|
||||
for ($i = 1; $i <= $count; $i++) {
|
||||
$chunk[] = $this->synthesizeRow($table, $fillable, $overrides, $i);
|
||||
$chunk[] = $this->synthesizeRow($table, array_merge($fillable, $required), $overrides, $i);
|
||||
|
||||
if (count($chunk) >= self::CHUNK_SIZE) {
|
||||
$this->insert($table, $chunk);
|
||||
@@ -94,6 +96,48 @@ class SyntheticSeeder
|
||||
));
|
||||
}
|
||||
|
||||
/**
|
||||
* 계측이 정렬 기준으로 삼는 컬럼의 정의를 반환합니다.
|
||||
*
|
||||
* `fillableColumns()` 는 "NOT NULL + 기본값 없음" 만 남기므로, Laravel 기본 `timestamps()`
|
||||
* 처럼 nullable 로 선언된 `created_at` 계열은 여기서 빠진다. 그런데 목록 프로파일 대부분이
|
||||
* `created_at` 으로 정렬하므로, 그대로 두면 합성 행이 전부 NULL 동률이 되어 계측이
|
||||
* 정렬 인덱스가 아니라 tie-break 경로를 재게 된다.
|
||||
*
|
||||
* @param string $table 대상 테이블
|
||||
* @param array<int, string> $names 반드시 채울 컬럼명 목록
|
||||
* @param array<int, array<string, mixed>> $already 이미 채우기로 한 컬럼 목록
|
||||
* @return array<int, array<string, mixed>> 추가로 채울 컬럼 정의 목록
|
||||
*/
|
||||
private function requiredColumnDefinitions(string $table, array $names, array $already): array
|
||||
{
|
||||
if ($names === []) {
|
||||
return [];
|
||||
}
|
||||
|
||||
$covered = array_column($already, 'name');
|
||||
$columns = collect(Schema::getColumns($table))->keyBy('name');
|
||||
|
||||
$extra = [];
|
||||
|
||||
foreach (array_unique($names) as $name) {
|
||||
if (in_array($name, $covered, true) || ! $columns->has($name)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$column = $columns->get($name);
|
||||
|
||||
// auto increment 키는 DB 가 채운다
|
||||
if ($column['auto_increment'] ?? false) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$extra[] = $column;
|
||||
}
|
||||
|
||||
return $extra;
|
||||
}
|
||||
|
||||
/**
|
||||
* 합성 행 1건을 만듭니다.
|
||||
*
|
||||
|
||||
@@ -7,6 +7,7 @@ use App\Extension\ModuleManager;
|
||||
use App\Extension\PluginManager;
|
||||
use App\Extension\TemplateManager;
|
||||
use App\Extension\Vendor\VendorMode;
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
use App\Services\CoreUpdateService;
|
||||
use App\Services\LanguagePackService;
|
||||
use Illuminate\Support\Facades\File;
|
||||
@@ -109,6 +110,10 @@ trait BundledExtensionUpdatePrompt
|
||||
// 확장별 전략 오버라이드
|
||||
$strategies = $this->collectPerExtensionStrategies($updates, $globalStrategy, $force);
|
||||
|
||||
// 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 운영 중인 사이트에서는
|
||||
// 기본값(아니오)을 유지하고 유지보수 시간에 별도로 수행하는 것이 안전하다.
|
||||
$rebuildSearchIndex = $this->askRebuildSearchIndex($force);
|
||||
|
||||
// 일괄 실행
|
||||
return $this->executeBulkUpdate(
|
||||
$moduleManager,
|
||||
@@ -116,6 +121,7 @@ trait BundledExtensionUpdatePrompt
|
||||
$templateManager,
|
||||
$updates,
|
||||
$strategies,
|
||||
$rebuildSearchIndex,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -200,8 +206,11 @@ trait BundledExtensionUpdatePrompt
|
||||
TemplateManager $templateManager,
|
||||
array $updates,
|
||||
array $strategies,
|
||||
bool $rebuildSearchIndex = false,
|
||||
): array {
|
||||
$manifest = $this->buildBundledUpdateManifest($updates, $strategies);
|
||||
// 운영자의 선택을 매니페스트에 실어 spawn 자식과 in-process fallback 이 같은 결정을 따르게 한다
|
||||
$manifest['rebuild_search_index'] = $rebuildSearchIndex;
|
||||
if ($this->bundledManifestIsEmpty($manifest)) {
|
||||
return ['success' => 0, 'failed' => 0, 'skipped' => 0, 'has_updates' => false];
|
||||
}
|
||||
@@ -228,6 +237,7 @@ trait BundledExtensionUpdatePrompt
|
||||
$templateManager,
|
||||
$updates,
|
||||
$strategies,
|
||||
$rebuildSearchIndex,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -385,6 +395,7 @@ trait BundledExtensionUpdatePrompt
|
||||
TemplateManager $templateManager,
|
||||
array $updates,
|
||||
array $strategies,
|
||||
bool $rebuildSearchIndex = false,
|
||||
): array {
|
||||
$success = 0;
|
||||
$failed = 0;
|
||||
@@ -452,6 +463,8 @@ trait BundledExtensionUpdatePrompt
|
||||
$this->newLine();
|
||||
$this->info("업데이트 완료: 성공 {$success}, 실패 {$failed}");
|
||||
|
||||
$this->runSearchIndexRebuildIfRequested($rebuildSearchIndex);
|
||||
|
||||
return [
|
||||
'success' => $success,
|
||||
'failed' => $failed,
|
||||
@@ -460,4 +473,60 @@ trait BundledExtensionUpdatePrompt
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* 검색 인덱스 재생성 여부를 운영자에게 확인합니다.
|
||||
*
|
||||
* 재생성은 인덱스 잠금 또는 전체 재색인을 유발하므로 기본값은 "아니오" 입니다.
|
||||
* `--force` (무인 실행) 시에도 묻지 않고 수행하지 않습니다 — 무인 실행이
|
||||
* 대용량 테이블을 잠그는 일이 없어야 합니다. 필요하면 `core:update
|
||||
* --rebuild-search-index` 로 명시하거나 이후 `search:index --repair` 를 실행합니다.
|
||||
*
|
||||
* @param bool $force 강제(무인) 실행 여부
|
||||
* @return bool 재생성 수행 여부
|
||||
*/
|
||||
private function askRebuildSearchIndex(bool $force): bool
|
||||
{
|
||||
// 커맨드가 옵션으로 이미 선택을 받았으면 그대로 따른다
|
||||
if ($this->hasOption('rebuild-search-index') && (bool) $this->option('rebuild-search-index')) {
|
||||
return true;
|
||||
}
|
||||
|
||||
if ($force) {
|
||||
return false;
|
||||
}
|
||||
|
||||
$manager = app(SearchIndexMaintenanceManager::class);
|
||||
|
||||
// 점검을 제공하지 않는 엔진에서는 물을 것이 없다
|
||||
if (! $manager->hasMaintainer() || $manager->unavailableReason() !== null) {
|
||||
return false;
|
||||
}
|
||||
|
||||
$this->newLine();
|
||||
$this->line(' '.__('search.index.rebuild_cost_warning'));
|
||||
|
||||
return $this->unifiedConfirm(__('search.index.rebuild_after_bulk_confirm'), false);
|
||||
}
|
||||
|
||||
/**
|
||||
* 요청이 있었으면 검색 인덱스를 재생성합니다.
|
||||
*
|
||||
* @param bool $requested 재생성 요청 여부
|
||||
* @return void
|
||||
*/
|
||||
private function runSearchIndexRebuildIfRequested(bool $requested): void
|
||||
{
|
||||
if (! $requested) {
|
||||
return;
|
||||
}
|
||||
|
||||
$report = app(SearchIndexMaintenanceManager::class)->repairStale();
|
||||
|
||||
$this->newLine();
|
||||
$this->info('검색 인덱스: '.$report->summary());
|
||||
|
||||
foreach ($report->failed as $identifier => $message) {
|
||||
$this->warn(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -34,7 +34,8 @@ class CoreUpdateCommand extends Command
|
||||
{--local : 로컬 코드베이스를 업데이트 소스로 사용 (GitHub 스킵)}
|
||||
{--source= : 수동 업데이트용 소스 디렉토리 경로 (GitHub 다운로드 대신 지정 디렉토리 사용)}
|
||||
{--zip= : 수동 업데이트용 ZIP 파일 경로 (GitHub 다운로드 대신 지정 ZIP 추출 사용)}
|
||||
{--vendor-mode=auto : vendor 설치 모드 (auto|composer|bundled)}';
|
||||
{--vendor-mode=auto : vendor 설치 모드 (auto|composer|bundled)}
|
||||
{--rebuild-search-index : 번들 확장 일괄 업데이트 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
|
||||
|
||||
protected $description = '그누보드7 코어를 최신 버전으로 업데이트합니다';
|
||||
|
||||
|
||||
@@ -2,10 +2,12 @@
|
||||
|
||||
namespace App\Console\Commands\Core;
|
||||
|
||||
use App\Extension\ExtensionManager;
|
||||
use App\Extension\ModuleManager;
|
||||
use App\Extension\PluginManager;
|
||||
use App\Extension\TemplateManager;
|
||||
use App\Extension\Vendor\VendorMode;
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
use App\Services\LanguagePackService;
|
||||
use Illuminate\Console\Command;
|
||||
use Illuminate\Support\Facades\File;
|
||||
@@ -45,7 +47,8 @@ class ExecuteBundledUpdatesCommand extends Command
|
||||
|
||||
protected $signature = 'core:execute-bundled-updates
|
||||
{--manifest= : 업데이트 매니페스트 JSON 파일 경로 (필수)}
|
||||
{--force : 강제 업데이트 플래그 (확장 매니저 update 호출에 전달)}';
|
||||
{--force : 강제 업데이트 플래그 (확장 매니저 update 호출에 전달)}
|
||||
{--rebuild-search-index : 일괄 업데이트 후 검색 인덱스 재생성 (매니페스트의 선택보다 우선)}';
|
||||
|
||||
protected $description = '번들 확장 일괄 업데이트를 실행합니다 (CoreUpdateCommand 내부용 — fresh PHP 프로세스에서 호출)';
|
||||
|
||||
@@ -63,7 +66,7 @@ class ExecuteBundledUpdatesCommand extends Command
|
||||
// (Artisan::call 대신 직접 메서드 호출 — nested Artisan::call 이 outer 명령의
|
||||
// output buffer 를 덮어쓰는 Laravel 동작 회피)
|
||||
try {
|
||||
app(\App\Extension\ExtensionManager::class)->updateComposerAutoload();
|
||||
app(ExtensionManager::class)->updateComposerAutoload();
|
||||
} catch (\Throwable $e) {
|
||||
Log::warning('bundled update spawn 자식: updateComposerAutoload 호출 실패', [
|
||||
'error' => $e->getMessage(),
|
||||
@@ -77,6 +80,9 @@ class ExecuteBundledUpdatesCommand extends Command
|
||||
return self::FAILURE;
|
||||
}
|
||||
|
||||
// 부모(core:update)가 운영자 선택을 매니페스트에 실어 보낸다 — 자식이 임의로 정하지 않는다
|
||||
$rebuildSearchIndex = (bool) $this->option('rebuild-search-index') || (bool) ($manifest['rebuild_search_index'] ?? false);
|
||||
|
||||
$modules = $manifest['modules'] ?? [];
|
||||
$plugins = $manifest['plugins'] ?? [];
|
||||
$templates = $manifest['templates'] ?? [];
|
||||
@@ -166,6 +172,17 @@ class ExecuteBundledUpdatesCommand extends Command
|
||||
$this->newLine();
|
||||
$this->info("업데이트 완료: 성공 {$success}, 실패 {$failed}");
|
||||
|
||||
// 검색 인덱스 재생성 — 운영자가 부모 단계에서 선택했을 때만 수행 (인덱스 잠금·재색인 비용)
|
||||
if ($rebuildSearchIndex) {
|
||||
$report = app(SearchIndexMaintenanceManager::class)->repairStale();
|
||||
$this->newLine();
|
||||
$this->info('검색 인덱스: '.$report->summary());
|
||||
|
||||
foreach ($report->failed as $identifier => $message) {
|
||||
$this->warn(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
|
||||
}
|
||||
}
|
||||
|
||||
// 부모 프로세스가 결과를 복원할 수 있도록 표식 라인으로 페이로드 출력
|
||||
$this->line(self::RESULT_PREFIX.json_encode([
|
||||
'success' => $success,
|
||||
@@ -174,5 +191,4 @@ class ExecuteBundledUpdatesCommand extends Command
|
||||
|
||||
return $failed > 0 ? self::FAILURE : self::SUCCESS;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
@@ -116,7 +116,7 @@ class CheckModuleUpdatesCommand extends Command
|
||||
$updateCount = 0;
|
||||
|
||||
foreach ($result['details'] as $detail) {
|
||||
$isUpdate = $detail['update_available'] ?? false;
|
||||
$isUpdate = (bool) ($detail['update_available'] ?? true);
|
||||
if ($isUpdate) {
|
||||
$updateCount++;
|
||||
}
|
||||
@@ -143,7 +143,7 @@ class CheckModuleUpdatesCommand extends Command
|
||||
$this->table($headers, $tableData);
|
||||
$this->newLine();
|
||||
$this->info(__('modules.commands.check_updates.summary', [
|
||||
'total' => count($result['details']),
|
||||
'total' => $result['checked_count'] ?? count($result['details']),
|
||||
'updates' => $updateCount,
|
||||
]));
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
namespace App\Console\Commands\Module;
|
||||
|
||||
use App\Console\Commands\Traits\HasProgressBar;
|
||||
use App\Console\Commands\Traits\RebuildsSearchIndex;
|
||||
use App\Contracts\Repositories\ModuleRepositoryInterface;
|
||||
use App\Enums\ExtensionOwnerType;
|
||||
use App\Extension\ModuleManager;
|
||||
@@ -17,6 +18,7 @@ use Illuminate\Support\Facades\Validator;
|
||||
class InstallModuleCommand extends Command
|
||||
{
|
||||
use HasProgressBar;
|
||||
use RebuildsSearchIndex;
|
||||
|
||||
/**
|
||||
* The name and signature of the console command.
|
||||
@@ -24,7 +26,8 @@ class InstallModuleCommand extends Command
|
||||
protected $signature = 'module:install
|
||||
{identifier : 설치할 모듈 식별자}
|
||||
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
|
||||
{--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}';
|
||||
{--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
|
||||
{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
|
||||
|
||||
/**
|
||||
* The console command description.
|
||||
@@ -114,6 +117,9 @@ class InstallModuleCommand extends Command
|
||||
|
||||
Log::info(__('modules.commands.install.success', ['module' => $identifier]));
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
|
||||
$this->handleSearchIndexRebuild();
|
||||
|
||||
return Command::SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@ namespace App\Console\Commands\Module;
|
||||
|
||||
use App\Console\Commands\Traits\HasProgressBar;
|
||||
use App\Console\Commands\Traits\HasUnifiedConfirm;
|
||||
use App\Console\Commands\Traits\RebuildsSearchIndex;
|
||||
use App\Contracts\Repositories\ModuleRepositoryInterface;
|
||||
use App\Enums\LayoutSourceType;
|
||||
use App\Extension\ModuleManager;
|
||||
@@ -16,6 +17,7 @@ class UpdateModuleCommand extends Command
|
||||
{
|
||||
use HasProgressBar;
|
||||
use HasUnifiedConfirm;
|
||||
use RebuildsSearchIndex;
|
||||
|
||||
/**
|
||||
* The name and signature of the console command.
|
||||
@@ -26,7 +28,8 @@ class UpdateModuleCommand extends Command
|
||||
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
|
||||
{--layout-strategy=overwrite : 레이아웃 전략 (overwrite|keep)}
|
||||
{--source=auto : 업데이트 소스 (auto|bundled|github) — bundled 는 _bundled 만 사용(GitHub 우회)}
|
||||
{--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 module.json 기준)}';
|
||||
{--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 module.json 기준)}
|
||||
{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
|
||||
|
||||
/**
|
||||
* The console command description.
|
||||
@@ -203,6 +206,9 @@ class UpdateModuleCommand extends Command
|
||||
'layout_strategy' => $layoutStrategy,
|
||||
]);
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
|
||||
$this->handleSearchIndexRebuild();
|
||||
|
||||
return Command::SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
@@ -116,7 +116,7 @@ class CheckPluginUpdatesCommand extends Command
|
||||
$updateCount = 0;
|
||||
|
||||
foreach ($result['details'] as $detail) {
|
||||
$isUpdate = $detail['update_available'] ?? false;
|
||||
$isUpdate = (bool) ($detail['update_available'] ?? true);
|
||||
if ($isUpdate) {
|
||||
$updateCount++;
|
||||
}
|
||||
@@ -143,7 +143,7 @@ class CheckPluginUpdatesCommand extends Command
|
||||
$this->table($headers, $tableData);
|
||||
$this->newLine();
|
||||
$this->info(__('plugins.commands.check_updates.summary', [
|
||||
'total' => count($result['details']),
|
||||
'total' => $result['checked_count'] ?? count($result['details']),
|
||||
'updates' => $updateCount,
|
||||
]));
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
namespace App\Console\Commands\Plugin;
|
||||
|
||||
use App\Console\Commands\Traits\HasProgressBar;
|
||||
use App\Console\Commands\Traits\RebuildsSearchIndex;
|
||||
use App\Contracts\Repositories\PluginRepositoryInterface;
|
||||
use App\Enums\ExtensionOwnerType;
|
||||
use App\Extension\PluginManager;
|
||||
@@ -16,6 +17,7 @@ use Illuminate\Support\Facades\Validator;
|
||||
class InstallPluginCommand extends Command
|
||||
{
|
||||
use HasProgressBar;
|
||||
use RebuildsSearchIndex;
|
||||
|
||||
/**
|
||||
* The name and signature of the console command.
|
||||
@@ -23,7 +25,8 @@ class InstallPluginCommand extends Command
|
||||
protected $signature = 'plugin:install
|
||||
{identifier : 설치할 플러그인 식별자}
|
||||
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
|
||||
{--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}';
|
||||
{--force : 이미 설치된 경우에도 _bundled/_pending 원본으로 활성 디렉토리를 덮어쓰고 재설치 (불완전 설치 복구)}
|
||||
{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
|
||||
|
||||
/**
|
||||
* The console command description.
|
||||
@@ -111,6 +114,9 @@ class InstallPluginCommand extends Command
|
||||
|
||||
Log::info(__('plugins.commands.install.success', ['plugin' => $identifier]));
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
|
||||
$this->handleSearchIndexRebuild();
|
||||
|
||||
return Command::SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@ namespace App\Console\Commands\Plugin;
|
||||
|
||||
use App\Console\Commands\Traits\HasProgressBar;
|
||||
use App\Console\Commands\Traits\HasUnifiedConfirm;
|
||||
use App\Console\Commands\Traits\RebuildsSearchIndex;
|
||||
use App\Contracts\Repositories\PluginRepositoryInterface;
|
||||
use App\Enums\LayoutSourceType;
|
||||
use App\Extension\PluginManager;
|
||||
@@ -16,6 +17,7 @@ class UpdatePluginCommand extends Command
|
||||
{
|
||||
use HasProgressBar;
|
||||
use HasUnifiedConfirm;
|
||||
use RebuildsSearchIndex;
|
||||
|
||||
/**
|
||||
* The name and signature of the console command.
|
||||
@@ -26,7 +28,8 @@ class UpdatePluginCommand extends Command
|
||||
{--vendor-mode=auto : Vendor 설치 모드 (auto|composer|bundled)}
|
||||
{--layout-strategy=overwrite : 레이아웃 전략 (overwrite|keep)}
|
||||
{--source=auto : 업데이트 소스 (auto|bundled|github) — bundled 는 _bundled 만 사용(GitHub 우회)}
|
||||
{--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 plugin.json 기준)}';
|
||||
{--zip= : 외부 ZIP 파일 경로 (지정 시 GitHub/번들 우회 + 버전은 plugin.json 기준)}
|
||||
{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 유지보수 시간에 수행하세요)}';
|
||||
|
||||
/**
|
||||
* The console command description.
|
||||
@@ -202,6 +205,9 @@ class UpdatePluginCommand extends Command
|
||||
'layout_strategy' => $layoutStrategy,
|
||||
]);
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 선택했을 때만 수행한다 (인덱스 잠금·재색인 비용)
|
||||
$this->handleSearchIndexRebuild();
|
||||
|
||||
return Command::SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,194 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands\Search;
|
||||
|
||||
use App\Console\Commands\Traits\HasUnifiedConfirm;
|
||||
use App\Enums\SearchIndexStatus;
|
||||
use App\Search\DTO\SearchIndexHealth;
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 점검·재생성 커맨드
|
||||
*
|
||||
* 인덱스는 있는데 내용이 색인되지 않아 검색이 조용히 0건을 돌려주는 상태를 검출하고,
|
||||
* 운영자가 선택하면 재생성합니다. 이 상태는 예외도 로그도 남기지 않으므로
|
||||
* "원래 검색이 안 되는 줄" 알고 지나가기 쉽습니다.
|
||||
*
|
||||
* 점검 방법은 **활성 Scout 엔진의 유지보수기**가 정합니다. 확장이 자체 검색 엔진을
|
||||
* 등록하면서 유지보수기를 함께 등록하면 이 커맨드가 그대로 그 엔진을 다룹니다
|
||||
* (`core.search.index_maintainers` 필터 훅).
|
||||
*
|
||||
* 사용 예시:
|
||||
* php artisan search:index # 활성 엔진의 인덱스 점검 (읽기 전용)
|
||||
* php artisan search:index --repair # 색인 누락 인덱스 재생성
|
||||
* php artisan search:index --filter=table=pages # 엔진별 필터 전달
|
||||
* php artisan search:index --json # 기계 판독용 출력
|
||||
*/
|
||||
class SearchIndexCommand extends Command
|
||||
{
|
||||
use HasUnifiedConfirm;
|
||||
|
||||
protected $signature = 'search:index
|
||||
{--repair : 색인이 누락된 인덱스를 재생성 (미지정 시 점검만)}
|
||||
{--filter=* : 엔진별 필터 (key=value 형태, 다중 지정 가능. FULLTEXT: table, index, samples)}
|
||||
{--json : 기계 판독용 JSON 출력}';
|
||||
|
||||
protected $description = '활성 검색 엔진의 인덱스가 실제로 내용을 색인하고 있는지 점검하고, 누락 시 재생성합니다';
|
||||
|
||||
/**
|
||||
* 커맨드를 실행합니다.
|
||||
*
|
||||
* @param SearchIndexMaintenanceManager $manager 검색 인덱스 유지보수 진입점
|
||||
* @return int 종료 코드 (색인 누락 잔존 시 1)
|
||||
*/
|
||||
public function handle(SearchIndexMaintenanceManager $manager): int
|
||||
{
|
||||
$driver = $manager->driver();
|
||||
$filters = $this->parseFilters();
|
||||
|
||||
if (! $manager->hasMaintainer()) {
|
||||
$this->components->warn(__('search.index.no_maintainer', ['driver' => $driver]));
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
|
||||
if (($reason = $manager->unavailableReason()) !== null) {
|
||||
$this->components->warn($reason);
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
|
||||
$results = $manager->inspect($filters);
|
||||
|
||||
if ($results === []) {
|
||||
$this->components->warn(__('search.index.no_targets', ['driver' => $driver]));
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
|
||||
$report = null;
|
||||
|
||||
if ($this->option('repair')) {
|
||||
$targets = array_values(array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild()));
|
||||
|
||||
if ($targets !== [] && $this->confirmRebuild($targets)) {
|
||||
$report = $manager->repairStale($filters);
|
||||
$results = $manager->inspect($filters);
|
||||
}
|
||||
}
|
||||
|
||||
if ($this->option('json')) {
|
||||
$this->line((string) json_encode([
|
||||
'driver' => $driver,
|
||||
'results' => array_map(fn (SearchIndexHealth $h) => $h->toArray(), $results),
|
||||
'repair' => $report?->toArray(),
|
||||
], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT));
|
||||
} else {
|
||||
$this->render($driver, $results, $report?->summary());
|
||||
}
|
||||
|
||||
$remaining = array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild());
|
||||
|
||||
return ($remaining === [] && ($report === null || $report->failed === [])) ? self::SUCCESS : self::FAILURE;
|
||||
}
|
||||
|
||||
/**
|
||||
* `--filter=key=value` 옵션을 연관 배열로 해석합니다.
|
||||
*
|
||||
* @return array<string, string>
|
||||
*/
|
||||
private function parseFilters(): array
|
||||
{
|
||||
$filters = [];
|
||||
|
||||
foreach ((array) $this->option('filter') as $raw) {
|
||||
if (! is_string($raw) || ! str_contains($raw, '=')) {
|
||||
continue;
|
||||
}
|
||||
|
||||
[$key, $value] = explode('=', $raw, 2);
|
||||
$key = trim($key);
|
||||
|
||||
if ($key !== '') {
|
||||
$filters[$key] = trim($value);
|
||||
}
|
||||
}
|
||||
|
||||
return $filters;
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성 대상을 보여 주고 진행 여부를 확인합니다.
|
||||
*
|
||||
* @param array<int, SearchIndexHealth> $targets 재생성 대상
|
||||
* @return bool 진행 여부
|
||||
*/
|
||||
private function confirmRebuild(array $targets): bool
|
||||
{
|
||||
$this->newLine();
|
||||
$this->components->info(__('search.index.rebuild_targets', ['count' => count($targets)]));
|
||||
|
||||
foreach ($targets as $target) {
|
||||
$this->line(' - '.$target->identifier.' ('.$target->measurement.')');
|
||||
}
|
||||
|
||||
$this->components->warn(__('search.index.rebuild_cost_warning'));
|
||||
|
||||
if ($this->unifiedConfirm(__('search.index.rebuild_confirm'), true)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
$this->components->info(__('search.index.rebuild_skipped'));
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 판정 결과를 표로 출력합니다.
|
||||
*
|
||||
* @param string $driver 드라이버명
|
||||
* @param array<int, SearchIndexHealth> $results 판정 결과
|
||||
* @param string|null $repairSummary 재생성 요약 (수행했을 때만)
|
||||
* @return void
|
||||
*/
|
||||
private function render(string $driver, array $results, ?string $repairSummary): void
|
||||
{
|
||||
$rows = array_map(fn (SearchIndexHealth $health) => [
|
||||
$health->identifier,
|
||||
'<fg='.$health->status->consoleColor().'>'.$health->status->label().'</>',
|
||||
$health->measurement,
|
||||
], $results);
|
||||
|
||||
$this->newLine();
|
||||
$this->line(' '.__('search.index.driver_label', ['driver' => $driver]));
|
||||
$this->table([__('search.index.col.index'), __('search.index.col.status'), __('search.index.col.measurement')], $rows);
|
||||
|
||||
$counts = [];
|
||||
foreach (SearchIndexStatus::cases() as $case) {
|
||||
$counts[$case->value] = count(array_filter($results, fn (SearchIndexHealth $h) => $h->status === $case));
|
||||
}
|
||||
|
||||
$this->line(' '.__('search.index.counts', [
|
||||
'healthy' => $counts[SearchIndexStatus::Healthy->value],
|
||||
'degraded' => $counts[SearchIndexStatus::Degraded->value],
|
||||
'stale' => $counts[SearchIndexStatus::Stale->value],
|
||||
'skipped' => $counts[SearchIndexStatus::Skipped->value],
|
||||
'total' => count($results),
|
||||
]));
|
||||
|
||||
if ($repairSummary !== null) {
|
||||
$this->newLine();
|
||||
$this->components->info($repairSummary);
|
||||
}
|
||||
|
||||
if ($counts[SearchIndexStatus::Stale->value] > 0 && ! $this->option('repair')) {
|
||||
$this->newLine();
|
||||
$this->components->warn(__('search.index.stale_hint'));
|
||||
}
|
||||
|
||||
if ($counts[SearchIndexStatus::Degraded->value] > 0) {
|
||||
$this->line(' <comment>'.__('search.index.degraded_hint').'</comment>');
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -116,7 +116,7 @@ class CheckTemplateUpdatesCommand extends Command
|
||||
$updateCount = 0;
|
||||
|
||||
foreach ($result['details'] as $detail) {
|
||||
$isUpdate = $detail['update_available'] ?? false;
|
||||
$isUpdate = (bool) ($detail['update_available'] ?? true);
|
||||
if ($isUpdate) {
|
||||
$updateCount++;
|
||||
}
|
||||
@@ -143,7 +143,7 @@ class CheckTemplateUpdatesCommand extends Command
|
||||
$this->table($headers, $tableData);
|
||||
$this->newLine();
|
||||
$this->info(__('templates.commands.check_updates.summary', [
|
||||
'total' => count($result['details']),
|
||||
'total' => $result['checked_count'] ?? count($result['details']),
|
||||
'updates' => $updateCount,
|
||||
]));
|
||||
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands\Traits;
|
||||
|
||||
use App\Search\DTO\SearchIndexHealth;
|
||||
use App\Search\DTO\SearchIndexRepairReport;
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
|
||||
/**
|
||||
* 설치·업데이트 커맨드에 "검색 인덱스 재생성" 선택 옵션을 제공하는 트레이트.
|
||||
*
|
||||
* 재생성 비용은 엔진마다 다르지만(테이블 잠금 / 전체 재색인) 어느 쪽이든 운영 중인
|
||||
* 사이트에 영향을 줍니다. 그래서 **기본값은 재생성하지 않음**이고, 운영자가
|
||||
* `--rebuild-search-index` 로 명시했을 때만 수행합니다.
|
||||
*
|
||||
* 옵션을 주지 않아도 점검 결과는 안내합니다 — 색인이 누락되면 검색이 오류 없이 0건을
|
||||
* 돌려주므로, 알려주지 않으면 운영자가 알 방법이 없습니다.
|
||||
*/
|
||||
trait RebuildsSearchIndex
|
||||
{
|
||||
/**
|
||||
* 커맨드 `$signature` 에 붙일 옵션 정의.
|
||||
*
|
||||
* @return string 옵션 시그니처 조각
|
||||
*/
|
||||
public static function rebuildSearchIndexOption(): string
|
||||
{
|
||||
return '{--rebuild-search-index : 완료 후 색인이 누락된 검색 인덱스를 재생성 (인덱스가 잠기거나 재색인됩니다 — 운영 중에는 점검 결과만 확인하고 유지보수 시간에 수행하세요)}';
|
||||
}
|
||||
|
||||
/**
|
||||
* 작업 완료 후 검색 인덱스를 점검하고, 요청이 있었으면 재생성합니다.
|
||||
*
|
||||
* @param bool|null $requested 재생성 요청 여부 (null 이면 커맨드 옵션에서 읽음)
|
||||
* @return SearchIndexRepairReport|null 재생성 보고 (재생성을 하지 않았으면 null)
|
||||
*/
|
||||
protected function handleSearchIndexRebuild(?bool $requested = null): ?SearchIndexRepairReport
|
||||
{
|
||||
$manager = app(SearchIndexMaintenanceManager::class);
|
||||
|
||||
// 점검을 제공하지 않는 엔진에서는 조용히 넘어간다 (검색 자체는 정상 동작)
|
||||
if (! $manager->hasMaintainer() || $manager->unavailableReason() !== null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$requested ??= (bool) $this->option('rebuild-search-index');
|
||||
|
||||
if ($requested) {
|
||||
$report = $manager->repairStale();
|
||||
$this->reportRebuild($report);
|
||||
|
||||
return $report;
|
||||
}
|
||||
|
||||
$this->warnStale($manager->inspect());
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성하지 않은 경우, 색인 누락 사실만 안내합니다.
|
||||
*
|
||||
* @param array<int, SearchIndexHealth> $results 점검 결과
|
||||
* @return void
|
||||
*/
|
||||
private function warnStale(array $results): void
|
||||
{
|
||||
$stale = array_values(array_filter($results, fn (SearchIndexHealth $h) => $h->needsRebuild()));
|
||||
|
||||
if ($stale === []) {
|
||||
return;
|
||||
}
|
||||
|
||||
$this->newLine();
|
||||
$this->warn('⚠️ '.__('search.index.stale_after_update', ['count' => count($stale)]));
|
||||
|
||||
foreach ($stale as $health) {
|
||||
$this->line(' - '.$health->identifier);
|
||||
}
|
||||
|
||||
$this->line(' '.__('search.index.stale_hint'));
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성 보고를 콘솔에 출력합니다.
|
||||
*
|
||||
* @param SearchIndexRepairReport $report 재생성 보고
|
||||
* @return void
|
||||
*/
|
||||
private function reportRebuild(SearchIndexRepairReport $report): void
|
||||
{
|
||||
$this->newLine();
|
||||
|
||||
if (! $report->didRebuild()) {
|
||||
$this->info('✅ '.$report->summary());
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
$this->info('✅ '.$report->summary());
|
||||
|
||||
foreach ($report->repaired as $identifier) {
|
||||
$this->line(' '.__('search.index.rebuilt_item', ['index' => $identifier]));
|
||||
}
|
||||
|
||||
foreach ($report->failed as $identifier => $message) {
|
||||
$this->error(' '.__('search.index.rebuild_failed_item', ['index' => $identifier, 'error' => $message]));
|
||||
}
|
||||
|
||||
foreach ($report->remaining as $identifier) {
|
||||
$this->warn(' '.__('search.index.still_stale_item', ['index' => $identifier]));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
<?php
|
||||
|
||||
namespace App\Enums;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 건강도 등급 (엔진 중립)
|
||||
*
|
||||
* 판정 방법은 엔진마다 다릅니다 — 각 `SearchIndexMaintainer` 구현이 자기 방식으로
|
||||
* 판정한 뒤 이 등급 중 하나로 답합니다. 코어는 등급만 보고 재생성 대상을 고릅니다.
|
||||
*/
|
||||
enum SearchIndexStatus: string
|
||||
{
|
||||
/** 정상 — 색인된 내용으로 검색이 성립한다 */
|
||||
case Healthy = 'healthy';
|
||||
|
||||
/** 부분 — 일부만 성립. 엔진 특성일 수 있어 자동 재생성 대상이 아니다 */
|
||||
case Degraded = 'degraded';
|
||||
|
||||
/** 색인 누락 — 검색이 성립하지 않는다. 재생성 대상 */
|
||||
case Stale = 'stale';
|
||||
|
||||
/** 판정 불가 — 표본·연결 부재 등 (사유를 함께 기록) */
|
||||
case Skipped = 'skipped';
|
||||
|
||||
/**
|
||||
* 사용자 친화 라벨을 반환합니다.
|
||||
*
|
||||
* @return string lang 키 해석 결과 (locale 자동 반영)
|
||||
*/
|
||||
public function label(): string
|
||||
{
|
||||
return __('search.index.status.'.$this->value);
|
||||
}
|
||||
|
||||
/**
|
||||
* 콘솔 출력용 색상명을 반환합니다.
|
||||
*
|
||||
* @return string Symfony 콘솔 색상명
|
||||
*/
|
||||
public function consoleColor(): string
|
||||
{
|
||||
return match ($this) {
|
||||
self::Healthy => 'green',
|
||||
self::Degraded => 'yellow',
|
||||
self::Stale => 'red',
|
||||
self::Skipped => 'gray',
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* 모든 케이스의 string 값 목록.
|
||||
*
|
||||
* @return array<int, string>
|
||||
*/
|
||||
public static function allValues(): array
|
||||
{
|
||||
return array_column(self::cases(), 'value');
|
||||
}
|
||||
}
|
||||
@@ -3971,9 +3971,11 @@ class ModuleManager implements ModuleManagerInterface
|
||||
$moduleRecords = $this->moduleRepository->getAllKeyedByIdentifier();
|
||||
$details = [];
|
||||
$updatedCount = 0;
|
||||
$checkedCount = 0;
|
||||
|
||||
foreach ($moduleRecords as $identifier => $record) {
|
||||
$result = $this->checkModuleUpdate($identifier);
|
||||
$checkedCount++;
|
||||
|
||||
// DB 갱신
|
||||
$updateData = [
|
||||
@@ -3997,6 +3999,7 @@ class ModuleManager implements ModuleManagerInterface
|
||||
$updatedCount++;
|
||||
$details[] = [
|
||||
'identifier' => $identifier,
|
||||
'update_available' => true,
|
||||
'current_version' => $result['current_version'],
|
||||
'latest_version' => $result['latest_version'],
|
||||
'update_source' => $result['update_source'],
|
||||
@@ -4006,6 +4009,7 @@ class ModuleManager implements ModuleManagerInterface
|
||||
|
||||
return [
|
||||
'updated_count' => $updatedCount,
|
||||
'checked_count' => $checkedCount,
|
||||
'details' => $details,
|
||||
];
|
||||
}
|
||||
|
||||
@@ -4153,9 +4153,11 @@ class PluginManager implements PluginManagerInterface
|
||||
$pluginRecords = $this->pluginRepository->getAllKeyedByIdentifier();
|
||||
$details = [];
|
||||
$updatedCount = 0;
|
||||
$checkedCount = 0;
|
||||
|
||||
foreach ($pluginRecords as $identifier => $record) {
|
||||
$result = $this->checkPluginUpdate($identifier);
|
||||
$checkedCount++;
|
||||
|
||||
// DB 갱신
|
||||
$updateData = [
|
||||
@@ -4179,6 +4181,7 @@ class PluginManager implements PluginManagerInterface
|
||||
$updatedCount++;
|
||||
$details[] = [
|
||||
'identifier' => $identifier,
|
||||
'update_available' => true,
|
||||
'current_version' => $result['current_version'],
|
||||
'latest_version' => $result['latest_version'],
|
||||
'update_source' => $result['update_source'],
|
||||
@@ -4188,6 +4191,7 @@ class PluginManager implements PluginManagerInterface
|
||||
|
||||
return [
|
||||
'updated_count' => $updatedCount,
|
||||
'checked_count' => $checkedCount,
|
||||
'details' => $details,
|
||||
];
|
||||
}
|
||||
|
||||
@@ -2685,9 +2685,11 @@ class TemplateManager implements TemplateManagerInterface
|
||||
$templateRecords = $this->templateRepository->getAllKeyedByIdentifier();
|
||||
$details = [];
|
||||
$updatedCount = 0;
|
||||
$checkedCount = 0;
|
||||
|
||||
foreach ($templateRecords as $identifier => $record) {
|
||||
$result = $this->checkTemplateUpdate($identifier);
|
||||
$checkedCount++;
|
||||
|
||||
$updateData = [
|
||||
'update_available' => $result['update_available'],
|
||||
@@ -2711,6 +2713,7 @@ class TemplateManager implements TemplateManagerInterface
|
||||
$updatedCount++;
|
||||
$details[] = [
|
||||
'identifier' => $identifier,
|
||||
'update_available' => true,
|
||||
'current_version' => $result['current_version'],
|
||||
'latest_version' => $result['latest_version'],
|
||||
'update_source' => $result['update_source'],
|
||||
@@ -2720,6 +2723,7 @@ class TemplateManager implements TemplateManagerInterface
|
||||
|
||||
return [
|
||||
'updated_count' => $updatedCount,
|
||||
'checked_count' => $checkedCount,
|
||||
'details' => $details,
|
||||
];
|
||||
}
|
||||
|
||||
@@ -335,6 +335,12 @@ class ResponseHelper
|
||||
/**
|
||||
* JSON Resource를 사용한 성공 응답을 생성합니다.
|
||||
*
|
||||
* `$resource->additional([...])` 로 실은 부가 데이터는 응답 최상위에 함께 나갑니다.
|
||||
* `JsonResource::resolve()` 는 리소스 본문만 돌려주므로, 그것만 쓰면 호출자가 실은
|
||||
* 부가 데이터가 조용히 사라집니다 — 예를 들어 확장 업데이트 응답의 `search_index`
|
||||
* (색인 누락 안내)가 사라지면 검색이 0건을 돌려주는 사실을 운영자가 알 방법이 없습니다.
|
||||
* `success`/`message`/`data` 키는 부가 데이터로 덮어쓰지 않습니다.
|
||||
*
|
||||
* @param string $messageKey 멤시지 키 (기본값: 'messages.success')
|
||||
* @param JsonResource|ResourceCollection|null $resource JSON 리소스
|
||||
* @param int $statusCode HTTP 상태 코드 (기본값: 200)
|
||||
@@ -351,11 +357,19 @@ class ResponseHelper
|
||||
): JsonResponse {
|
||||
$data = $resource ? $resource->resolve() : null;
|
||||
|
||||
return response()->json([
|
||||
$payload = [
|
||||
'success' => true,
|
||||
'message' => self::trans($messageKey, $messageParams, $domain),
|
||||
'data' => $data,
|
||||
], $statusCode, [], self::JSON_ENCODE_OPTIONS);
|
||||
];
|
||||
|
||||
$additional = $resource instanceof JsonResource ? (array) $resource->additional : [];
|
||||
|
||||
if ($additional !== []) {
|
||||
$payload += array_diff_key($additional, $payload);
|
||||
}
|
||||
|
||||
return response()->json($payload, $statusCode, [], self::JSON_ENCODE_OPTIONS);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -198,4 +198,31 @@ class TimezoneHelper
|
||||
|
||||
return Carbon::parse($normalized, static::getSiteTimezone())->utc();
|
||||
}
|
||||
|
||||
/**
|
||||
* 기간 필터의 **종료값**을 사이트 기본 타임존 기준으로 해석하여 UTC Carbon을 반환합니다.
|
||||
*
|
||||
* `<input type="date">` 는 시각 없이 'Y-m-d' 만 보낸다. 이 값을 그대로 datetime 비교에 쓰면
|
||||
* '00:00:00' 으로 해석되어 **종료일 당일이 통째로 빠진다**. 시각이 없는 입력만 그날 끝
|
||||
* (23:59:59)까지 확장하고, 시각이 함께 온 입력은 그 시각 그대로 둔다.
|
||||
*
|
||||
* 예: '2026-03-15' + Asia/Seoul → 2026-03-15 23:59:59 KST → 2026-03-15 14:59:59 UTC
|
||||
* '2026-03-15 09:30' + Asia/Seoul → 2026-03-15 00:30:00 UTC (확장하지 않음)
|
||||
*
|
||||
* @param string|null $dateTimeString Y-m-d 또는 Y-m-d\TH:i / Y-m-d H:i:s 형식
|
||||
* @return Carbon|null UTC Carbon 인스턴스
|
||||
*/
|
||||
public static function fromSiteRangeEnd(?string $dateTimeString): ?Carbon
|
||||
{
|
||||
if (! $dateTimeString) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$normalized = trim(str_replace('T', ' ', $dateTimeString));
|
||||
$dateOnly = preg_match('/^\d{4}-\d{2}-\d{2}$/', $normalized) === 1;
|
||||
|
||||
$parsed = Carbon::parse($normalized, static::getSiteTimezone());
|
||||
|
||||
return ($dateOnly ? $parsed->endOfDay() : $parsed)->utc();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -29,18 +29,22 @@ class MenuController extends AdminBaseController
|
||||
parent::__construct();
|
||||
}
|
||||
|
||||
/**
|
||||
* 관리용 메뉴 목록을 조회합니다.
|
||||
*
|
||||
* @param MenuListRequest $request 목록 필터·정렬 요청
|
||||
* @return JsonResponse 메뉴 컬렉션을 담은 JSON 응답
|
||||
*/
|
||||
public function index(MenuListRequest $request): JsonResponse
|
||||
{
|
||||
try {
|
||||
$filters = $request->validated();
|
||||
$user = Auth::user();
|
||||
|
||||
// 필터가 있으면 필터링된 메뉴 조회, 없으면 전체 조회
|
||||
if (isset($filters['is_active']) || ! empty($filters['filters'])) {
|
||||
// 필터 유무와 무관하게 같은 경로로 조회한다. 예전에는 필터가 없으면 filters 를
|
||||
// 받지 않는 메서드로 분기했는데, 그 경로는 sort_by/sort_order 를 통째로 버려
|
||||
// "필터를 하나라도 걸어야 정렬이 먹는" 상태가 됐다 (#492 D-22).
|
||||
$menus = $this->menuService->getFilteredMenusForManagement($filters, $user);
|
||||
} else {
|
||||
$menus = $this->menuService->getTopLevelMenusForManagement($user);
|
||||
}
|
||||
|
||||
return $this->successWithResource(
|
||||
'menu.fetch_success',
|
||||
|
||||
@@ -7,6 +7,7 @@ use App\Extension\Vendor\VendorMode;
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use App\Http\Controllers\Concerns\InjectsExtensionLanguagePacks;
|
||||
use App\Http\Controllers\Concerns\OrchestratesCascadeInstall;
|
||||
use App\Http\Controllers\Concerns\RebuildsSearchIndexOnDemand;
|
||||
use App\Http\Requests\Extension\ChangelogRequest;
|
||||
use App\Http\Requests\Module\ActivateModuleRequest;
|
||||
use App\Http\Requests\Module\DeactivateModuleRequest;
|
||||
@@ -38,6 +39,7 @@ class ModuleController extends AdminBaseController
|
||||
{
|
||||
use InjectsExtensionLanguagePacks;
|
||||
use OrchestratesCascadeInstall;
|
||||
use RebuildsSearchIndexOnDemand;
|
||||
|
||||
public function __construct(
|
||||
private ModuleService $moduleService,
|
||||
@@ -531,25 +533,36 @@ class ModuleController extends AdminBaseController
|
||||
$force = (bool) ($validated['force'] ?? false);
|
||||
$result = $this->moduleService->updateModule($moduleName, $vendorMode, $layoutStrategy, $force);
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 체크했을 때만 수행한다 — 인덱스 잠금·재색인 비용이
|
||||
// 있어 운영 중인 사이트에서 업데이트만으로 발생해서는 안 된다.
|
||||
$searchIndex = $this->rebuildSearchIndexIfRequested(
|
||||
(bool) ($validated['rebuild_search_index'] ?? false)
|
||||
);
|
||||
|
||||
$moduleInfo = $result['module_info'] ?? null;
|
||||
|
||||
// 메시지 치환 파라미터를 반드시 전달한다 — 누락 시 ":module"/":version"
|
||||
// 플레이스홀더가 그대로 사용자에게 노출된다.
|
||||
$messageParams = [
|
||||
'module' => $moduleName,
|
||||
'version' => $result['to_version'] ?? ($moduleInfo['version'] ?? ''),
|
||||
'version' => (string) ($result['to_version'] ?? data_get($moduleInfo, 'version') ?? ''),
|
||||
];
|
||||
|
||||
if ($moduleInfo) {
|
||||
return $this->successWithResource(
|
||||
'modules.update_success',
|
||||
new ModuleResource($moduleInfo),
|
||||
(new ModuleResource($moduleInfo))->additional(['search_index' => $searchIndex]),
|
||||
200,
|
||||
$messageParams
|
||||
);
|
||||
}
|
||||
|
||||
return $this->success('modules.update_success', $result, 200, $messageParams);
|
||||
return $this->success(
|
||||
'modules.update_success',
|
||||
$result + ['search_index' => $searchIndex],
|
||||
200,
|
||||
$messageParams
|
||||
);
|
||||
} catch (ValidationException $e) {
|
||||
// Service/Manager에서 이미 번역된 메시지를 errors에 포함하므로
|
||||
// 첫 번째 에러를 top-level message로 직접 사용 (이중 래핑 방지)
|
||||
|
||||
@@ -8,6 +8,7 @@ use App\Helpers\PermissionHelper;
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use App\Http\Controllers\Concerns\InjectsExtensionLanguagePacks;
|
||||
use App\Http\Controllers\Concerns\OrchestratesCascadeInstall;
|
||||
use App\Http\Controllers\Concerns\RebuildsSearchIndexOnDemand;
|
||||
use App\Http\Requests\Extension\ChangelogRequest;
|
||||
use App\Http\Requests\Plugin\ActivatePluginRequest;
|
||||
use App\Http\Requests\Plugin\DeactivatePluginRequest;
|
||||
@@ -39,6 +40,7 @@ class PluginController extends AdminBaseController
|
||||
{
|
||||
use InjectsExtensionLanguagePacks;
|
||||
use OrchestratesCascadeInstall;
|
||||
use RebuildsSearchIndexOnDemand;
|
||||
|
||||
public function __construct(
|
||||
private PluginService $pluginService,
|
||||
@@ -538,25 +540,35 @@ class PluginController extends AdminBaseController
|
||||
$force = (bool) ($validated['force'] ?? false);
|
||||
$result = $this->pluginService->updatePlugin($pluginName, $vendorMode, $layoutStrategy, $force);
|
||||
|
||||
// 검색 인덱스 재생성은 운영자가 체크했을 때만 수행한다 — 인덱스 잠금·재색인 비용이
|
||||
// 있어 운영 중인 사이트에서 업데이트만으로 발생해서는 안 된다.
|
||||
$searchIndex = $this->rebuildSearchIndexIfRequested(
|
||||
(bool) ($validated['rebuild_search_index'] ?? false)
|
||||
);
|
||||
|
||||
$pluginInfo = $result['plugin_info'] ?? null;
|
||||
|
||||
// 메시지 치환 파라미터를 반드시 전달한다 — 누락 시 ":plugin"/":version"
|
||||
// 플레이스홀더가 그대로 사용자에게 노출된다.
|
||||
// 성공 메시지는 ":plugin"/":version" 치환자를 쓰므로 값을 함께 넘긴다
|
||||
$messageParams = [
|
||||
'plugin' => $pluginName,
|
||||
'version' => $result['to_version'] ?? ($pluginInfo['version'] ?? ''),
|
||||
'version' => (string) ($result['to_version'] ?? data_get($pluginInfo, 'version') ?? ''),
|
||||
];
|
||||
|
||||
if ($pluginInfo) {
|
||||
return $this->successWithResource(
|
||||
'plugins.update_success',
|
||||
new PluginResource($pluginInfo),
|
||||
(new PluginResource($pluginInfo))->additional(['search_index' => $searchIndex]),
|
||||
200,
|
||||
$messageParams
|
||||
);
|
||||
}
|
||||
|
||||
return $this->success('plugins.update_success', $result, 200, $messageParams);
|
||||
return $this->success(
|
||||
'plugins.update_success',
|
||||
$result + ['search_index' => $searchIndex],
|
||||
200,
|
||||
$messageParams
|
||||
);
|
||||
} catch (ValidationException $e) {
|
||||
// Service/Manager에서 이미 번역된 메시지를 errors에 포함하므로
|
||||
// 첫 번째 에러를 top-level message로 직접 사용 (이중 래핑 방지)
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
<?php
|
||||
|
||||
namespace App\Http\Controllers\Concerns;
|
||||
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
|
||||
/**
|
||||
* 관리자 화면의 설치·업데이트 응답에 "검색 인덱스 재생성" 선택 결과를 싣는 트레이트.
|
||||
*
|
||||
* 재생성 비용은 엔진마다 다르지만(테이블 잠금 / 전체 재색인) 어느 쪽이든 운영 중인
|
||||
* 사이트에 영향을 줍니다. 그래서 **운영자가 화면에서 체크했을 때만** 수행하고,
|
||||
* 체크하지 않았을 때는 점검 결과만 실어 보내 화면이 "지금 색인이 누락된 인덱스가 있다"
|
||||
* 는 사실을 알릴 수 있게 합니다 — 색인이 비면 검색이 오류 없이 0건을 돌려주므로
|
||||
* 알려 주지 않으면 운영자가 알 방법이 없습니다.
|
||||
*/
|
||||
trait RebuildsSearchIndexOnDemand
|
||||
{
|
||||
/**
|
||||
* 요청이 있었으면 재생성하고, 없었으면 점검 결과만 반환합니다.
|
||||
*
|
||||
* @param bool $requested 재생성 요청 여부
|
||||
* @return array<string, mixed>|null 응답에 실을 페이로드 (점검 불가 엔진이면 null)
|
||||
*/
|
||||
protected function rebuildSearchIndexIfRequested(bool $requested): ?array
|
||||
{
|
||||
$manager = app(SearchIndexMaintenanceManager::class);
|
||||
|
||||
// 점검을 제공하지 않는 엔진에서는 실을 정보가 없다 (검색 자체는 정상 동작)
|
||||
if (! $manager->hasMaintainer() || $manager->unavailableReason() !== null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
if ($requested) {
|
||||
return ['rebuilt' => true] + $manager->repairStale()->toArray();
|
||||
}
|
||||
|
||||
$stale = array_values(array_filter($manager->inspect(), fn ($health) => $health->needsRebuild()));
|
||||
|
||||
return [
|
||||
'rebuilt' => false,
|
||||
'driver' => $manager->driver(),
|
||||
'stale' => array_map(fn ($health) => $health->identifier, $stale),
|
||||
'stale_count' => count($stale),
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -3,9 +3,11 @@
|
||||
namespace App\Http\Middleware;
|
||||
|
||||
use Closure;
|
||||
use Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse;
|
||||
use Illuminate\Cookie\Middleware\EncryptCookies;
|
||||
use Illuminate\Http\Request;
|
||||
use Illuminate\Pipeline\Pipeline;
|
||||
use Illuminate\Support\Facades\Log;
|
||||
use Illuminate\Session\Middleware\StartSession;
|
||||
use Symfony\Component\HttpFoundation\Response;
|
||||
|
||||
/**
|
||||
@@ -29,28 +31,10 @@ class StartApiSession
|
||||
*/
|
||||
public function handle(Request $request, Closure $next): Response
|
||||
{
|
||||
Log::info('[StartApiSession] 미들웨어 시작', ['url' => $request->url()]);
|
||||
|
||||
return (new Pipeline(app()))
|
||||
->send($request)
|
||||
->through($this->sessionPipeline())
|
||||
->then(function ($request) use ($next) {
|
||||
Log::info('[StartApiSession] 세션 파이프라인 완료', [
|
||||
'hasSession' => $request->hasSession(),
|
||||
'sessionStarted' => $request->hasSession() ? $request->session()->isStarted() : false,
|
||||
'sessionId' => $request->hasSession() ? $request->session()->getId() : null,
|
||||
]);
|
||||
|
||||
$response = $next($request);
|
||||
|
||||
Log::info('[StartApiSession] 컨트롤러 응답 후', [
|
||||
'status' => $response->getStatusCode(),
|
||||
'cookies' => collect($response->headers->getCookies())->map(fn($c) => $c->getName())->all(),
|
||||
'webGuardCheck' => \Illuminate\Support\Facades\Auth::guard('web')->check(),
|
||||
]);
|
||||
|
||||
return $response;
|
||||
});
|
||||
->then(fn ($request) => $next($request));
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -63,9 +47,9 @@ class StartApiSession
|
||||
protected function sessionPipeline(): array
|
||||
{
|
||||
return [
|
||||
\Illuminate\Cookie\Middleware\EncryptCookies::class,
|
||||
\Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
|
||||
\Illuminate\Session\Middleware\StartSession::class,
|
||||
EncryptCookies::class,
|
||||
AddQueuedCookiesToResponse::class,
|
||||
StartSession::class,
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@ namespace App\Http\Requests\ActivityLog;
|
||||
|
||||
use App\Enums\ActivityLogType;
|
||||
use App\Extension\HookManager;
|
||||
use App\Models\User;
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
use Illuminate\Validation\Rule;
|
||||
|
||||
@@ -33,7 +34,7 @@ class ActivityLogIndexRequest extends FormRequest
|
||||
'log_type' => ['nullable', 'array'],
|
||||
'log_type.*' => ['string', Rule::in(ActivityLogType::values())],
|
||||
'action' => ['nullable', 'string', 'max:100'],
|
||||
'user_id' => ['nullable', 'integer', Rule::exists('users', 'id')],
|
||||
'user_id' => ['nullable', 'integer', Rule::exists(User::class, 'id')],
|
||||
'loggable_type' => ['nullable', 'string', 'max:255'],
|
||||
'search' => ['nullable', 'string', 'max:255'],
|
||||
'search_type' => ['nullable', 'string', Rule::in(['all', 'action', 'description', 'ip_address'])],
|
||||
@@ -41,6 +42,9 @@ class ActivityLogIndexRequest extends FormRequest
|
||||
'date_from' => ['nullable', 'date'],
|
||||
'date_to' => ['nullable', 'date', 'after_or_equal:date_from'],
|
||||
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
|
||||
// 게이트는 화면이 제공하는 정렬만 연다. ActivityLogRepository::SORTABLE_COLUMNS 는
|
||||
// 이보다 넓게(id·user_id 포함) 두어, 확장이 이 규칙을 훅으로 넓혔을 때 저장소가
|
||||
// 조용히 기본 정렬로 되돌리지 않도록 한다 (service-repository.md "정렬 컬럼 화이트리스트").
|
||||
'sort_by' => ['nullable', 'string', Rule::in(['created_at', 'action', 'log_type'])],
|
||||
'sort_order' => ['nullable', 'string', Rule::in(['asc', 'desc'])],
|
||||
];
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
namespace App\Http\Requests\Module;
|
||||
|
||||
use App\Extension\HookManager;
|
||||
use Illuminate\Contracts\Validation\ValidationRule;
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
@@ -28,7 +29,7 @@ class PerformModuleUpdateRequest extends FormRequest
|
||||
/**
|
||||
* 요청에 적용할 검증 규칙
|
||||
*
|
||||
* @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
|
||||
* @return array<string, ValidationRule|array<mixed>|string>
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
@@ -37,6 +38,8 @@ class PerformModuleUpdateRequest extends FormRequest
|
||||
'vendor_mode' => ['nullable', 'string', 'in:auto,composer,bundled'],
|
||||
// 코어 버전 비호환 강제 우회 플래그
|
||||
'force' => ['nullable', 'boolean'],
|
||||
// 업데이트 후 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 기본은 미수행
|
||||
'rebuild_search_index' => ['nullable', 'boolean'],
|
||||
];
|
||||
|
||||
return HookManager::applyFilters('core.module.perform_update_validation_rules', $rules, $this);
|
||||
|
||||
@@ -36,7 +36,9 @@ class NotificationLogIndexRequest extends FormRequest
|
||||
'extension_type' => ['nullable', 'string', 'in:core,module,plugin'],
|
||||
'status' => ['nullable', 'string', Rule::enum(NotificationLogStatus::class)],
|
||||
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
|
||||
'sort_by' => ['nullable', 'string', 'in:id,channel,notification_type,status,sent_at,created_at'],
|
||||
// 허용 집합은 NotificationLogRepository::SORTABLE_COLUMNS 와 동일해야 한다.
|
||||
// 게이트가 더 좁으면 화면 정렬 셀렉트가 제공하는 옵션(수신자명순/제목순)이 422 로 막힌다.
|
||||
'sort_by' => ['nullable', 'string', 'in:id,channel,notification_type,status,sent_at,created_at,recipient_name,subject'],
|
||||
'sort_order' => ['nullable', 'string', 'in:asc,desc'],
|
||||
];
|
||||
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
namespace App\Http\Requests\Plugin;
|
||||
|
||||
use App\Extension\HookManager;
|
||||
use Illuminate\Contracts\Validation\ValidationRule;
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
@@ -28,7 +29,7 @@ class PerformPluginUpdateRequest extends FormRequest
|
||||
/**
|
||||
* 요청에 적용할 검증 규칙
|
||||
*
|
||||
* @return array<string, \Illuminate\Contracts\Validation\ValidationRule|array<mixed>|string>
|
||||
* @return array<string, ValidationRule|array<mixed>|string>
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
@@ -37,6 +38,8 @@ class PerformPluginUpdateRequest extends FormRequest
|
||||
'vendor_mode' => ['nullable', 'string', 'in:auto,composer,bundled'],
|
||||
// 코어 버전 비호환 강제 우회 플래그 (위험 인지 후 사용자 명시 필요)
|
||||
'force' => ['nullable', 'boolean'],
|
||||
// 업데이트 후 검색 인덱스 재생성 여부 — 인덱스 잠금·재색인 비용이 있어 기본은 미수행
|
||||
'rebuild_search_index' => ['nullable', 'boolean'],
|
||||
];
|
||||
|
||||
return HookManager::applyFilters('core.plugin.perform_update_validation_rules', $rules, $this);
|
||||
|
||||
@@ -304,10 +304,7 @@ class LanguagePackServiceProvider extends ServiceProvider
|
||||
$syncFor = function (string $scope, string $identifier, ?array $info, string $relativeBase) use ($registrar) {
|
||||
$vendor = $this->resolveVendor($identifier, $info);
|
||||
$version = (string) ($info['version'] ?? '1.0.0');
|
||||
$langDir = $relativeBase.'/'.$identifier.'/lang';
|
||||
if (! File::isDirectory(base_path($langDir))) {
|
||||
$langDir = $relativeBase.'/'.$identifier.'/resources/lang';
|
||||
}
|
||||
$langDir = $this->resolveExtensionLangDir($scope, $identifier, $relativeBase);
|
||||
$registrar->syncFromExtension($scope, $identifier, $vendor, $version, $langDir);
|
||||
};
|
||||
|
||||
@@ -359,6 +356,38 @@ class LanguagePackServiceProvider extends ServiceProvider
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 확장의 백엔드 다국어 디렉토리를 반환합니다.
|
||||
*
|
||||
* **런타임이 실제로 로드하는 경로와 같아야 한다** (`TranslationServiceProvider`).
|
||||
* 모듈은 `src/lang`, 플러그인은 `lang` 이며, 코어의 확장 설치 검증
|
||||
* (`ValidatesTranslationPath`)도 같은 규칙을 강제한다. 여기서 다른 경로를 잡으면
|
||||
* 언어팩에 등록된 키와 화면에 나오는 문구의 출처가 어긋난다.
|
||||
*
|
||||
* 존재하지 않으면 관례 경로들을 순서대로 확인해 실제 있는 디렉토리를 돌려준다
|
||||
* (제3자 확장이 다른 배치를 쓰는 경우 대비).
|
||||
*
|
||||
* @param string $scope 확장 스코프 (module|plugin|template)
|
||||
* @param string $identifier 확장 식별자
|
||||
* @param string $relativeBase base_path 기준 상위 디렉토리 (modules|plugins|templates)
|
||||
* @return string base_path 기준 상대 lang 디렉토리
|
||||
*/
|
||||
private function resolveExtensionLangDir(string $scope, string $identifier, string $relativeBase): string
|
||||
{
|
||||
$primary = $scope === 'module' ? 'src/lang' : 'lang';
|
||||
$candidates = array_unique([$primary, 'lang', 'src/lang', 'resources/lang']);
|
||||
|
||||
foreach ($candidates as $candidate) {
|
||||
$dir = $relativeBase.'/'.$identifier.'/'.$candidate;
|
||||
|
||||
if (File::isDirectory(base_path($dir))) {
|
||||
return $dir;
|
||||
}
|
||||
}
|
||||
|
||||
return $relativeBase.'/'.$identifier.'/'.$primary;
|
||||
}
|
||||
|
||||
/**
|
||||
* 확장 manifest 또는 identifier 로부터 vendor 를 추출합니다.
|
||||
*
|
||||
|
||||
@@ -3,8 +3,10 @@
|
||||
namespace App\Repositories\Concerns;
|
||||
|
||||
use Closure;
|
||||
use Illuminate\Contracts\Database\Query\Expression;
|
||||
use Illuminate\Contracts\Pagination\Paginator as PaginatorContract;
|
||||
use Illuminate\Database\Eloquent\Builder;
|
||||
use Illuminate\Database\Query\Builder as QueryBuilder;
|
||||
use Illuminate\Pagination\LengthAwarePaginator;
|
||||
use Illuminate\Pagination\Paginator;
|
||||
use Illuminate\Support\Collection;
|
||||
@@ -27,7 +29,10 @@ use Illuminate\Support\Collection;
|
||||
*
|
||||
* 호출 계약:
|
||||
* - `$query` 에는 **필터/where 만** 적용한다 (`orderBy`/`with`/`select` 미적용)
|
||||
* - `whereHas` 는 결과 집합을 결정하므로 그대로 둔다 — `with` 만 inner 에서 제거된다
|
||||
* - `whereHas` 는 결과 집합을 결정하므로 그대로 둔다 — 제거되는 것은 `with`(eager load) 뿐이다
|
||||
* - 관계는 **반드시 `$relations` 인자로** 넘긴다. `setEagerLoads([])` 는 inner 뿐 아니라
|
||||
* **outer 에도** 적용되므로, `$query->with()` 만 하고 인자를 생략하면 관계가 로드되지 않는다.
|
||||
* 이 실패는 예외도 쿼리 오류도 내지 않고 응답에서 관계 필드만 사라진다
|
||||
* - 정렬은 닫힌 집합이어야 한다 (ResolvesSortSpec 참조). 인덱스 없는 컬럼 정렬은 inner 도
|
||||
* 전체 스캔하므로 개선 폭이 보장되지 않는다
|
||||
* - 키 컬럼은 정렬 마지막에 자동으로 덧붙는다 (동률 시 페이지 경계가 흔들리는 것을 방지)
|
||||
@@ -180,8 +185,12 @@ trait PaginatesWithDeferredJoin
|
||||
/**
|
||||
* 정렬 스펙을 쿼리에 적용합니다.
|
||||
*
|
||||
* 컬럼이 상관 서브쿼리(Builder)면 `orderBy()` 가 서브 select 로 전개한다. 서브쿼리는
|
||||
* 원 행의 키에 상관되므로 inner/outer 어느 쪽에 적용해도 같은 순서를 만든다 —
|
||||
* outer 에서는 이번 페이지 건수만큼만 실행된다.
|
||||
*
|
||||
* @param Builder $query 대상 쿼리
|
||||
* @param array<int, array{column: string, direction: string}> $sort 정렬 스펙
|
||||
* @param array<int, array{column: string|Builder|Expression, direction: string}> $sort 정렬 스펙
|
||||
*/
|
||||
private function applySortSpec(Builder $query, array $sort): void
|
||||
{
|
||||
@@ -196,9 +205,13 @@ trait PaginatesWithDeferredJoin
|
||||
* 정렬 컬럼에 중복이 많으면(상태/조회수/평점 등) 동률 행의 순서가 실행마다 달라져 페이지
|
||||
* 경계에서 행이 중복되거나 누락된다. inner 와 outer 가 같은 순서를 갖도록 하는 전제이기도 하다.
|
||||
*
|
||||
* @param array<int, array{column: string, direction: string}> $sort 정렬 스펙
|
||||
* 정렬 컬럼은 문자열 외에 **상관 서브쿼리(Builder)** 나 Expression 도 올 수 있다
|
||||
* (관계 테이블 컬럼 기준 정렬 — `SortsByRelatedColumn`). 이 경우 키 컬럼일 수 없으므로
|
||||
* 전순서 보장을 위해 키 컬럼이 항상 덧붙는다.
|
||||
*
|
||||
* @param array<int, array{column: string|Builder|Expression, direction: string}> $sort 정렬 스펙
|
||||
* @param string $keyName 키 컬럼명
|
||||
* @return array<int, array{column: string, direction: string}> 키 컬럼이 보장된 정렬 스펙
|
||||
* @return array<int, array{column: string|Builder|Expression, direction: string}> 키 컬럼이 보장된 정렬 스펙
|
||||
*/
|
||||
private function normalizeSortSpecForKey(array $sort, string $keyName): array
|
||||
{
|
||||
@@ -207,7 +220,7 @@ trait PaginatesWithDeferredJoin
|
||||
foreach ($sort as $spec) {
|
||||
$column = $spec['column'] ?? null;
|
||||
|
||||
if (! is_string($column) || $column === '') {
|
||||
if (is_string($column) ? $column === '' : ! ($column instanceof Builder || $column instanceof QueryBuilder || $column instanceof Expression)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
@@ -219,6 +232,10 @@ trait PaginatesWithDeferredJoin
|
||||
|
||||
foreach ($normalized as $spec) {
|
||||
// 이미 키 컬럼으로 정렬한다면 그것으로 전순서가 성립한다
|
||||
if (! is_string($spec['column'])) {
|
||||
continue;
|
||||
}
|
||||
|
||||
if ($spec['column'] === $keyName || str_ends_with($spec['column'], '.'.$keyName)) {
|
||||
return $normalized;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
<?php
|
||||
|
||||
namespace App\Repositories\Concerns;
|
||||
|
||||
use Illuminate\Database\Eloquent\Builder;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
/**
|
||||
* 관계 테이블 컬럼 기준 정렬 Trait
|
||||
*
|
||||
* 목록의 정렬 기준이 원 테이블에 없고 관계 테이블에 있는 경우가 있다.
|
||||
* (예: 주문 목록의 "발송일" — `shipped_at` 은 주문이 아니라 배송 테이블에 있고, 한 주문에
|
||||
* 배송 행이 여러 건일 수 있다.)
|
||||
*
|
||||
* 이때 화면이 정렬 옵션을 제공하는데 백엔드가 그 컬럼을 모르면 422 로 조용히 실패하거나,
|
||||
* 임시로 조인을 붙이면 다음 두 문제가 생긴다.
|
||||
*
|
||||
* 1. `JOIN` + `GROUP BY` 로 집계하면 1:N 조인이 원 행을 부풀려 총 건수와 페이지 경계가 깨진다
|
||||
* 2. inner 쿼리(지연 조인)에 집계를 붙이면 건너뛸 행 전체에 대해 집계가 돌아 OFFSET 이
|
||||
* 깊어질수록 비용이 그대로 누적된다 — 지연 조인을 도입한 이유가 사라진다
|
||||
*
|
||||
* 본 Trait 은 **상관 서브쿼리 정렬**로 두 문제를 함께 피한다. 원 행 수를 바꾸지 않으므로
|
||||
* 총 건수·페이지 경계가 그대로 유지되고, `(외래키, 정렬컬럼)` 복합 인덱스가 있으면 각 행당
|
||||
* 인덱스 첫 항목 한 건만 읽는다.
|
||||
*
|
||||
* 방향과 집계를 분리해 지정하지 않는 이유: 서브쿼리를 정렬 방향과 같은 방향으로 정렬해
|
||||
* 한 건만 취하면 `desc` 는 자연히 최댓값(가장 늦은 발송), `asc` 는 최솟값(가장 이른 발송)이
|
||||
* 된다. 운영자가 "최근 발송순" 을 골랐을 때 기대하는 값과 일치한다.
|
||||
*
|
||||
* 사용 계약:
|
||||
* - 정렬 키 → 관계 스펙 맵을 리포지토리 상수(`RELATED_SORTABLE_COLUMNS`)로 선언한다
|
||||
* - 그 키들은 FormRequest 의 `sort_by` 허용 목록에도 함께 들어가야 한다
|
||||
* (게이트 ⊆ 저장소 불변식 — `SortWhitelistGateParityTest` 가 검사한다)
|
||||
* - 정렬 대상 관계 테이블에는 `(외래키, 정렬컬럼)` 복합 인덱스를 반드시 둔다
|
||||
*
|
||||
* @see ResolvesSortSpec 원 테이블 컬럼 정렬 해석 (본 Trait 과 함께 사용)
|
||||
* @see PaginatesWithDeferredJoin 서브쿼리 정렬 스펙을 그대로 받는다
|
||||
*/
|
||||
trait SortsByRelatedColumn
|
||||
{
|
||||
/**
|
||||
* 관계 테이블 컬럼 정렬을 포함해 정렬 스펙을 해석합니다.
|
||||
*
|
||||
* 요청 정렬 키가 `$relatedMap` 에 있으면 상관 서브쿼리 스펙을, 그렇지 않으면
|
||||
* `ResolvesSortSpec::resolveSortSpec()` 의 일반 컬럼 스펙을 돌려준다.
|
||||
*
|
||||
* @param array $filters 요청 유래 필터 배열
|
||||
* @param array<int, string> $allowedColumns 원 테이블 허용 정렬 컬럼
|
||||
* @param array<string, array{model: class-string<Model>, foreign_key: string, column: string}> $relatedMap 정렬 키 → 관계 스펙
|
||||
* @param Model $parent 정렬 대상 원 모델 (상관 조건의 좌변)
|
||||
* @param string $defaultColumn 기본 정렬 컬럼
|
||||
* @param string $defaultDirection 기본 정렬 방향
|
||||
* @param string $columnKey 정렬 컬럼이 담긴 필터 키
|
||||
* @param string $directionKey 정렬 방향이 담긴 필터 키
|
||||
* @return array<int, array{column: string|Builder, direction: string}> 정렬 스펙 배열
|
||||
*/
|
||||
protected function resolveSortSpecWithRelated(
|
||||
array $filters,
|
||||
array $allowedColumns,
|
||||
array $relatedMap,
|
||||
Model $parent,
|
||||
string $defaultColumn,
|
||||
string $defaultDirection = 'desc',
|
||||
string $columnKey = 'sort_by',
|
||||
string $directionKey = 'sort_order',
|
||||
): array {
|
||||
$requested = $filters[$columnKey] ?? null;
|
||||
$requested = is_string($requested) ? trim($requested) : '';
|
||||
|
||||
if ($requested === '' || ! isset($relatedMap[$requested])) {
|
||||
return $this->resolveSortSpec(
|
||||
$filters,
|
||||
$allowedColumns,
|
||||
$defaultColumn,
|
||||
$defaultDirection,
|
||||
columnKey: $columnKey,
|
||||
directionKey: $directionKey,
|
||||
);
|
||||
}
|
||||
|
||||
$direction = $this->normalizeSortDirection($filters[$directionKey] ?? null, $defaultDirection);
|
||||
|
||||
return [[
|
||||
'column' => $this->relatedSortSubquery($relatedMap[$requested], $parent, $direction),
|
||||
'direction' => $direction,
|
||||
]];
|
||||
}
|
||||
|
||||
/**
|
||||
* 관계 테이블에서 정렬 기준값 한 건을 뽑는 상관 서브쿼리를 만듭니다.
|
||||
*
|
||||
* 정렬 방향과 같은 방향으로 관계 행을 정렬해 첫 건만 취한다 —
|
||||
* `desc` 면 가장 늦은 값, `asc` 면 가장 이른 값이 기준이 된다.
|
||||
*
|
||||
* @param array{model: class-string<Model>, foreign_key: string, column: string} $spec 관계 스펙
|
||||
* @param Model $parent 원 모델
|
||||
* @param string $direction 정렬 방향 (asc|desc)
|
||||
* @return Builder 상관 서브쿼리
|
||||
*/
|
||||
protected function relatedSortSubquery(array $spec, Model $parent, string $direction): Builder
|
||||
{
|
||||
/** @var Model $related */
|
||||
$related = new $spec['model'];
|
||||
|
||||
return $related->newQuery()
|
||||
->select($related->qualifyColumn($spec['column']))
|
||||
->whereColumn($related->qualifyColumn($spec['foreign_key']), $parent->qualifyColumn($parent->getKeyName()))
|
||||
->orderBy($related->qualifyColumn($spec['column']), $direction)
|
||||
->limit(1);
|
||||
}
|
||||
}
|
||||
@@ -4,6 +4,7 @@ namespace App\Repositories;
|
||||
|
||||
use App\Contracts\Repositories\IdentityVerificationLogRepositoryInterface;
|
||||
use App\Enums\IdentityVerificationStatus;
|
||||
use App\Helpers\TimezoneHelper;
|
||||
use App\Models\IdentityPolicy;
|
||||
use App\Models\IdentityVerificationLog;
|
||||
use App\Repositories\Concerns\PaginatesWithDeferredJoin;
|
||||
@@ -195,12 +196,15 @@ class IdentityVerificationLogRepository implements IdentityVerificationLogReposi
|
||||
}
|
||||
}
|
||||
|
||||
// 기간 필터는 사이트 타임존 기준으로 해석한다 — created_at 은 UTC 로 저장되고
|
||||
// 화면은 사이트 타임존으로 보여주므로, 입력 문자열을 그대로 비교하면 하루가 어긋난다.
|
||||
// 종료값은 시각 없이 날짜만 오는 경우(`<input type="date">`) 그날 끝까지 포함한다.
|
||||
if (! empty($filters['date_from'])) {
|
||||
$query->where('created_at', '>=', $filters['date_from']);
|
||||
$query->where('created_at', '>=', TimezoneHelper::fromSiteDateTime($filters['date_from']));
|
||||
}
|
||||
|
||||
if (! empty($filters['date_to'])) {
|
||||
$query->where('created_at', '<=', $filters['date_to']);
|
||||
$query->where('created_at', '<=', TimezoneHelper::fromSiteRangeEnd($filters['date_to']));
|
||||
}
|
||||
|
||||
$sortBy = in_array($filters['sort_by'] ?? null, ['created_at', 'attempts'], true)
|
||||
|
||||
@@ -195,7 +195,9 @@ class LanguagePackRepository implements LanguagePackRepositoryInterface
|
||||
return $query
|
||||
->orderBy('scope')
|
||||
->orderBy('target_identifier')
|
||||
->orderBy('locale');
|
||||
->orderBy('locale')
|
||||
// 전순서 보장 — 위 세 컬럼 조합이 유니크하더라도 정렬 계약을 키로 닫아 둔다
|
||||
->orderBy('id');
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -21,6 +21,13 @@ class MenuRepository implements MenuRepositoryInterface
|
||||
/** 허용 정렬 컬럼 (MenuListRequest 와 동일 집합) */
|
||||
private const SORTABLE_COLUMNS = ['created_at', 'name', 'slug', 'order'];
|
||||
|
||||
/**
|
||||
* 다국어 JSON 컬럼 목록 (검색·정렬 시 로케일 경로로 풀어야 하는 컬럼)
|
||||
*
|
||||
* @var array<int, string>
|
||||
*/
|
||||
private const TRANSLATABLE_COLUMNS = ['name'];
|
||||
|
||||
/**
|
||||
* 모든 메뉴를 조회합니다.
|
||||
*
|
||||
@@ -434,19 +441,19 @@ class MenuRepository implements MenuRepositoryInterface
|
||||
$query->where(function ($q) use ($searchableFields, $value, $operator) {
|
||||
foreach ($searchableFields as $searchField) {
|
||||
$q->orWhere(function ($subQ) use ($searchField, $value, $operator) {
|
||||
$this->applyFilterOperator($subQ, $searchField, $value, $operator);
|
||||
$this->applySearchableField($subQ, $searchField, $value, $operator);
|
||||
});
|
||||
}
|
||||
});
|
||||
} elseif (in_array($field, $searchableFields)) {
|
||||
$this->applyFilterOperator($query, $field, $value, $operator);
|
||||
$this->applySearchableField($query, $field, $value, $operator);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 정렬 (허용 컬럼 화이트리스트로 해석)
|
||||
foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'order', 'asc') as $sort) {
|
||||
$query->orderBy($sort['column'], $sort['direction']);
|
||||
$query->orderBy($this->qualifySortColumn($sort['column']), $sort['direction']);
|
||||
}
|
||||
|
||||
// 자식 메뉴도 동일한 조건 적용하여 로드
|
||||
@@ -475,6 +482,69 @@ class MenuRepository implements MenuRepositoryInterface
|
||||
* @param string $value 검색 값
|
||||
* @param string $operator 연산자 (like, eq, starts_with, ends_with)
|
||||
*/
|
||||
/**
|
||||
* 검색 대상 필드에 조건을 적용합니다. (다국어 JSON 컬럼 인지)
|
||||
*
|
||||
* `name` 은 다국어 JSON 컬럼이다. JSON 은 유니코드 이스케이프(`\uXXXX`)로 저장되므로
|
||||
* 컬럼 전체에 LIKE 를 걸면 한글·일본어 검색어가 **절대 매칭되지 않는다**
|
||||
* (저장된 바이트는 `{"ko":"대시보드"}` 이다).
|
||||
* 지원 로케일별 JSON 경로(`name->ko`)로 나눠 검색한다 — 저장소 공통 관례다.
|
||||
*
|
||||
* @param Builder $query 쿼리 빌더
|
||||
* @param string $field 필드명
|
||||
* @param string $value 검색 값
|
||||
* @param string $operator 연산자 (like, eq, starts_with, ends_with)
|
||||
*/
|
||||
private function applySearchableField($query, string $field, string $value, string $operator): void
|
||||
{
|
||||
if (! in_array($field, self::TRANSLATABLE_COLUMNS, true)) {
|
||||
$this->applyFilterOperator($query, $field, $value, $operator);
|
||||
|
||||
return;
|
||||
}
|
||||
|
||||
$query->where(function ($q) use ($field, $value, $operator) {
|
||||
foreach ($this->translatableLocales() as $locale) {
|
||||
$q->orWhere(function ($subQ) use ($field, $locale, $value, $operator) {
|
||||
$this->applyFilterOperator($subQ, "{$field}->{$locale}", $value, $operator);
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* 정렬 컬럼이 다국어 JSON 컬럼이면 현재 로케일 경로로 바꿉니다.
|
||||
*
|
||||
* JSON 원문으로 정렬하면 `{"ko":"\uXXXX...` 문자열 순서가 되어 사람이 읽는 순서와
|
||||
* 무관해진다. 화면에 보이는 값(현재 로케일)으로 정렬해야 목록 순서가 납득 가능해진다.
|
||||
*
|
||||
* @param string $column 정렬 컬럼
|
||||
* @return string 실제 정렬에 쓸 컬럼 표현
|
||||
*/
|
||||
private function qualifySortColumn(string $column): string
|
||||
{
|
||||
if (! in_array($column, self::TRANSLATABLE_COLUMNS, true)) {
|
||||
return $column;
|
||||
}
|
||||
|
||||
return $column.'->'.app()->getLocale();
|
||||
}
|
||||
|
||||
/**
|
||||
* 다국어 필드가 값을 가질 수 있는 로케일 목록을 반환합니다.
|
||||
*
|
||||
* 다국어 JSON 필드의 언어 집합은 `translatable_locales` 다 — 번역 파일이 없어도
|
||||
* 데이터는 저장될 수 있으므로 UI 표시 언어(`supported_locales`)보다 넓다.
|
||||
*
|
||||
* @return array<int, string> 로케일 코드 목록
|
||||
*/
|
||||
private function translatableLocales(): array
|
||||
{
|
||||
$locales = config('app.translatable_locales', config('app.supported_locales', []));
|
||||
|
||||
return empty($locales) ? [app()->getLocale()] : array_values($locales);
|
||||
}
|
||||
|
||||
private function applyFilterOperator($query, string $field, string $value, string $operator): void
|
||||
{
|
||||
switch ($operator) {
|
||||
|
||||
@@ -33,6 +33,7 @@ class NotificationLogRepository implements NotificationLogRepositoryInterface
|
||||
'channel',
|
||||
'notification_type',
|
||||
'recipient_name',
|
||||
'subject',
|
||||
];
|
||||
|
||||
/**
|
||||
|
||||
@@ -30,7 +30,9 @@ class NotificationRepository implements NotificationRepositoryInterface
|
||||
// audit:allow repository-paginate-column-pruning reason: 사용자 1명에 종속된 알림함 —
|
||||
// $user->notifications() 로 이미 좁혀지고, 목록이 표시하는 본문 자체가 data(JSON) 라
|
||||
// 걷어낼 넓은 컬럼이 없다
|
||||
return $query->orderBy('created_at', 'desc')->paginate($perPage);
|
||||
// 정렬 마지막의 기본키는 전순서 보장용이다 — created_at 동률에서 페이지 경계가
|
||||
// 흔들려 인접 페이지가 같은 알림을 중복 노출하고 다른 알림을 누락하는 것을 막는다.
|
||||
return $query->orderBy('created_at', 'desc')->orderBy('id', 'desc')->paginate($perPage);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -215,8 +215,12 @@ class RoleRepository implements RoleRepositoryInterface
|
||||
}
|
||||
|
||||
// 정렬 (코어/확장 소유 역할 먼저, 그 다음 사용자 생성 역할)
|
||||
// 정렬 마지막의 기본키는 전순서 보장용이다. 시더가 일괄 생성한 역할은 created_at 이
|
||||
// 한 타임스탬프에 몰려 있어(실측: 한 값에 최대 10행) 키가 없으면 동률 구간의 순서가
|
||||
// 페이지마다 달라지고, 인접 페이지가 같은 역할을 중복 노출하면서 다른 역할을 누락한다.
|
||||
$query->orderByRaw('CASE WHEN extension_type IS NOT NULL THEN 0 ELSE 1 END')
|
||||
->orderBy('created_at', 'desc');
|
||||
->orderBy('created_at', 'desc')
|
||||
->orderBy('id', 'desc');
|
||||
|
||||
// audit:allow repository-paginate-column-pruning reason: 역할 정의 테이블 — 행 수가 운영상 고정(수십 건)이고 넓은 컬럼이 없다
|
||||
return $query->paginate($perPage);
|
||||
|
||||
@@ -6,6 +6,7 @@ use App\Contracts\Repositories\ScheduleHistoryRepositoryInterface;
|
||||
use App\Models\ScheduleHistory;
|
||||
use App\Repositories\Concerns\PaginatesWithDeferredJoin;
|
||||
use App\Repositories\Concerns\ResolvesSortSpec;
|
||||
use Carbon\Carbon;
|
||||
use Illuminate\Contracts\Pagination\LengthAwarePaginator;
|
||||
use Illuminate\Database\Eloquent\Collection;
|
||||
|
||||
@@ -68,7 +69,11 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
|
||||
*/
|
||||
public function getPaginatedByScheduleId(int $scheduleId, array $filters = []): LengthAwarePaginator
|
||||
{
|
||||
$query = ScheduleHistory::with('triggeredBy')
|
||||
// 관계는 쿼리에 미리 붙이지 않는다 — 지연 조인 트레이트가 inner/outer 양쪽에서
|
||||
// setEagerLoads([]) 로 지우므로, 여기서 with() 하면 outer 에서도 사라져
|
||||
// ScheduleHistoryResource 의 whenLoaded('triggeredBy') 가 항상 비게 된다.
|
||||
// 로드는 relations: 인자로 넘긴다.
|
||||
$query = ScheduleHistory::query()
|
||||
->where('schedule_id', $scheduleId);
|
||||
|
||||
// 상태 필터
|
||||
@@ -81,13 +86,15 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
|
||||
$query->where('trigger_type', $filters['trigger_type']);
|
||||
}
|
||||
|
||||
// 날짜 필터
|
||||
// 기간 필터 — whereDate 는 컬럼에 DATE() 를 씌워 인덱스를 못 쓰게 만든다.
|
||||
// 같은 결과를 내는 범위 조건으로 바꿔 started_at 인덱스를 살린다
|
||||
// (종료일은 그날 23:59:59.999999 까지 포함해야 whereDate 와 동일한 경계를 갖는다).
|
||||
if (! empty($filters['started_from'])) {
|
||||
$query->whereDate('started_at', '>=', $filters['started_from']);
|
||||
$query->where('started_at', '>=', Carbon::parse($filters['started_from'])->startOfDay());
|
||||
}
|
||||
|
||||
if (! empty($filters['started_to'])) {
|
||||
$query->whereDate('started_at', '<=', $filters['started_to']);
|
||||
$query->where('started_at', '<=', Carbon::parse($filters['started_to'])->endOfDay());
|
||||
}
|
||||
|
||||
// 정렬 — 요청 값은 허용 목록으로만 해석한다.
|
||||
@@ -108,6 +115,7 @@ class ScheduleHistoryRepository implements ScheduleHistoryRepositoryInterface
|
||||
columns: ['*'],
|
||||
sort: $sort,
|
||||
perPage: $perPage,
|
||||
relations: ['triggeredBy'],
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,78 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search\Contracts;
|
||||
|
||||
use App\Search\DTO\SearchIndexHealth;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 점검·재생성 계약
|
||||
*
|
||||
* Scout 엔진마다 "인덱스" 의 실체가 다릅니다 — MySQL FULLTEXT 는 테이블에 붙은 인덱스,
|
||||
* Meilisearch/Elasticsearch 는 외부 서버의 인덱스입니다. 그래서 코어는 **무엇을 어떻게
|
||||
* 점검·재생성할지 모르는 채** 이 계약만 호출하고, 판정 방법은 각 엔진 제공자가 정합니다.
|
||||
*
|
||||
* 확장(모듈/플러그인)이 자체 검색 엔진을 등록할 때 이 계약의 구현을 함께 등록하면
|
||||
* 관리자 화면·커맨드·업데이트 절차가 코어 수정 없이 그 엔진을 다룹니다.
|
||||
* 등록은 `core.search.index_maintainers` 필터 훅에 `드라이버명 => 구현 클래스` 로 합니다.
|
||||
*
|
||||
* ```php
|
||||
* HookManager::addFilter('core.search.index_maintainers', function (array $maintainers) {
|
||||
* $maintainers['meilisearch'] = MeilisearchIndexMaintainer::class;
|
||||
*
|
||||
* return $maintainers;
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* 구현하지 않은 엔진은 점검 대상에서 제외될 뿐 검색 자체는 정상 동작합니다.
|
||||
*/
|
||||
interface SearchIndexMaintainer
|
||||
{
|
||||
/**
|
||||
* 이 유지보수기가 담당하는 Scout 드라이버명을 반환합니다.
|
||||
*
|
||||
* `config('scout.driver')` 값과 대조해 활성 엔진의 유지보수기를 고릅니다.
|
||||
*
|
||||
* @return string 드라이버명 (예: mysql-fulltext)
|
||||
*/
|
||||
public function driver(): string;
|
||||
|
||||
/**
|
||||
* 현재 환경에서 점검을 수행할 수 있는지 반환합니다.
|
||||
*
|
||||
* 예) FULLTEXT 미지원 DBMS, 외부 검색 서버 미연결 등에서 false.
|
||||
*
|
||||
* @return bool 점검 가능 여부
|
||||
*/
|
||||
public function isAvailable(): bool;
|
||||
|
||||
/**
|
||||
* 점검 불가 사유를 반환합니다.
|
||||
*
|
||||
* `isAvailable()` 이 false 일 때 운영자에게 보여 줄 문장입니다.
|
||||
* 사유를 남기지 않으면 "점검 대상 0" 과 "점검할 수 없었음" 이 구분되지 않습니다.
|
||||
*
|
||||
* @return string|null 사유 (사용 가능하면 null)
|
||||
*/
|
||||
public function unavailableReason(): ?string;
|
||||
|
||||
/**
|
||||
* 관리 중인 인덱스의 건강도를 판정합니다.
|
||||
*
|
||||
* @param array<string, mixed> $filters 엔진별 필터 (예: ['table' => 'pages'])
|
||||
* @return array<int, SearchIndexHealth> 인덱스별 판정 결과
|
||||
*/
|
||||
public function inspect(array $filters = []): array;
|
||||
|
||||
/**
|
||||
* 재생성이 필요하다고 판정된 인덱스를 재생성합니다.
|
||||
*
|
||||
* 재생성은 비용이 크고 서비스에 영향을 줄 수 있으므로, 호출자는 반드시
|
||||
* 운영자의 명시적 선택을 받은 뒤에만 호출합니다.
|
||||
*
|
||||
* @param SearchIndexHealth $health 재생성 대상 판정 결과
|
||||
* @return void
|
||||
*
|
||||
* @throws \Throwable 재생성 실패 시
|
||||
*/
|
||||
public function rebuild(SearchIndexHealth $health): void;
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search\DTO;
|
||||
|
||||
/**
|
||||
* FULLTEXT 인덱스 정의 (Value Object)
|
||||
*
|
||||
* `INFORMATION_SCHEMA` + `SHOW CREATE TABLE` 에서 읽어 온 실제 인덱스 구성입니다.
|
||||
* 재생성 시 이 값을 그대로 다시 써서 검색 동작이 달라지지 않게 합니다.
|
||||
*/
|
||||
readonly class FulltextIndexDefinition
|
||||
{
|
||||
/**
|
||||
* @param string $table 테이블명 (프리픽스 포함 — 스키마에서 읽은 실제 이름)
|
||||
* @param string $name 인덱스명
|
||||
* @param array<int, string> $columns 색인 컬럼 목록
|
||||
* @param string|null $parser 파서명 (예: ngram). 지정되지 않은 인덱스는 null
|
||||
*/
|
||||
public function __construct(
|
||||
public string $table,
|
||||
public string $name,
|
||||
public array $columns,
|
||||
public ?string $parser = null,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* 백틱을 두른 테이블명을 반환합니다.
|
||||
*
|
||||
* @return string 예: `g7_pages`
|
||||
*/
|
||||
public function quotedTable(): string
|
||||
{
|
||||
return '`'.$this->table.'`';
|
||||
}
|
||||
|
||||
/**
|
||||
* 백틱을 두른 컬럼 목록을 반환합니다.
|
||||
*
|
||||
* @return string 예: `title`, `content`
|
||||
*/
|
||||
public function quotedColumns(): string
|
||||
{
|
||||
return '`'.implode('`, `', $this->columns).'`';
|
||||
}
|
||||
|
||||
/**
|
||||
* `ALTER TABLE ... ADD FULLTEXT` 에 붙일 파서 절을 반환합니다.
|
||||
*
|
||||
* @return string 파서가 없으면 빈 문자열
|
||||
*/
|
||||
public function parserClause(): string
|
||||
{
|
||||
return $this->parser === null ? '' : ' WITH PARSER '.$this->parser;
|
||||
}
|
||||
|
||||
/**
|
||||
* 사람이 읽는 식별자를 반환합니다.
|
||||
*
|
||||
* @return string 예: g7_pages.ft_pages_title
|
||||
*/
|
||||
public function label(): string
|
||||
{
|
||||
return $this->table.'.'.$this->name;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search\DTO;
|
||||
|
||||
use App\Enums\SearchIndexStatus;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 건강도 판정 결과 (Value Object · 엔진 중립)
|
||||
*
|
||||
* 어떤 엔진이든 공통으로 답할 수 있는 것만 필드로 둡니다 — 무엇을(`identifier`),
|
||||
* 어떤 상태로(`status`), 무엇을 근거로(`measurement`) 판정했는가.
|
||||
*
|
||||
* 엔진마다 다른 세부(FULLTEXT 의 테이블·컬럼·파서, 외부 엔진의 샤드·문서 수 등)는
|
||||
* `details` 에 담습니다. 코어가 그 내용을 해석하지 않으므로 새 엔진이 추가되어도
|
||||
* 코어를 고칠 일이 없습니다.
|
||||
*
|
||||
* `context` 는 엔진 구현이 재생성에 필요한 자기 정보를 실어 두는 자리입니다
|
||||
* (코어는 그대로 되돌려 줄 뿐 들여다보지 않습니다).
|
||||
*/
|
||||
readonly class SearchIndexHealth
|
||||
{
|
||||
/**
|
||||
* @param string $driver 판정을 만든 Scout 드라이버명
|
||||
* @param string $identifier 인덱스 식별자 (엔진 내에서 유일)
|
||||
* @param SearchIndexStatus $status 판정 등급
|
||||
* @param string $measurement 판정 근거 수치·사유 (사람이 읽는 한 줄)
|
||||
* @param array<string, mixed> $details 엔진별 부가 정보 (표시 전용)
|
||||
* @param array<string, mixed> $context 재생성에 필요한 엔진 내부 정보
|
||||
*/
|
||||
public function __construct(
|
||||
public string $driver,
|
||||
public string $identifier,
|
||||
public SearchIndexStatus $status,
|
||||
public string $measurement = '',
|
||||
public array $details = [],
|
||||
public array $context = [],
|
||||
) {}
|
||||
|
||||
/**
|
||||
* 재생성 대상인지 여부.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function needsRebuild(): bool
|
||||
{
|
||||
return $this->status === SearchIndexStatus::Stale;
|
||||
}
|
||||
|
||||
/**
|
||||
* 기계 판독용 배열로 반환합니다.
|
||||
*
|
||||
* `context` 는 엔진 내부 정보라 응답에 싣지 않습니다.
|
||||
*
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function toArray(): array
|
||||
{
|
||||
return [
|
||||
'driver' => $this->driver,
|
||||
'identifier' => $this->identifier,
|
||||
'status' => $this->status->value,
|
||||
'status_label' => $this->status->label(),
|
||||
'measurement' => $this->measurement,
|
||||
'details' => $this->details,
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search\DTO;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 재생성 실행 보고 (Value Object · 엔진 중립)
|
||||
*
|
||||
* 커맨드는 콘솔 출력으로, 컨트롤러는 API 응답으로 같은 값을 씁니다.
|
||||
*
|
||||
* `remaining` 은 재생성 **후 다시 점검한** 잔존 목록입니다 — "재생성했다" 와
|
||||
* "복구됐다" 는 다른 사실이라 따로 담습니다.
|
||||
*/
|
||||
readonly class SearchIndexRepairReport
|
||||
{
|
||||
/**
|
||||
* @param string $driver 대상 Scout 드라이버명
|
||||
* @param int $inspected 점검한 인덱스 수
|
||||
* @param array<int, string> $repaired 재생성 성공 인덱스 식별자
|
||||
* @param array<string, string> $failed 재생성 실패 [식별자 => 사유]
|
||||
* @param array<int, string> $remaining 재생성 후에도 색인 누락으로 남은 식별자
|
||||
* @param bool $available 이 엔진에서 점검을 수행할 수 있었는지
|
||||
* @param string|null $reason 수행 불가 사유 (available=false 일 때)
|
||||
*/
|
||||
public function __construct(
|
||||
public string $driver,
|
||||
public int $inspected = 0,
|
||||
public array $repaired = [],
|
||||
public array $failed = [],
|
||||
public array $remaining = [],
|
||||
public bool $available = true,
|
||||
public ?string $reason = null,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* 점검을 수행할 수 없었던 경우의 보고를 만듭니다.
|
||||
*
|
||||
* @param string $driver 드라이버명
|
||||
* @param string|null $reason 사유
|
||||
* @return self
|
||||
*/
|
||||
public static function unavailable(string $driver, ?string $reason): self
|
||||
{
|
||||
return new self(driver: $driver, available: false, reason: $reason);
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성 대상이 없었을 때의 보고를 만듭니다.
|
||||
*
|
||||
* @param string $driver 드라이버명
|
||||
* @param int $inspected 점검한 인덱스 수
|
||||
* @return self
|
||||
*/
|
||||
public static function nothingToDo(string $driver, int $inspected): self
|
||||
{
|
||||
return new self(driver: $driver, inspected: $inspected);
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성을 실제로 수행했는지 여부.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function didRebuild(): bool
|
||||
{
|
||||
return $this->repaired !== [] || $this->failed !== [];
|
||||
}
|
||||
|
||||
/**
|
||||
* 전부 복구되었는지 여부 (실패·잔존 모두 없음).
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function isClean(): bool
|
||||
{
|
||||
return $this->failed === [] && $this->remaining === [];
|
||||
}
|
||||
|
||||
/**
|
||||
* 한 줄 요약을 반환합니다.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function summary(): string
|
||||
{
|
||||
if (! $this->available) {
|
||||
return $this->reason ?? __('search.index.unavailable', ['driver' => $this->driver]);
|
||||
}
|
||||
|
||||
if (! $this->didRebuild()) {
|
||||
return __('search.index.report.nothing_to_do', ['count' => $this->inspected]);
|
||||
}
|
||||
|
||||
return __('search.index.report.rebuilt', [
|
||||
'inspected' => $this->inspected,
|
||||
'repaired' => count($this->repaired),
|
||||
'failed' => count($this->failed),
|
||||
'remaining' => count($this->remaining),
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* 기계 판독용 배열로 반환합니다.
|
||||
*
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function toArray(): array
|
||||
{
|
||||
return [
|
||||
'driver' => $this->driver,
|
||||
'available' => $this->available,
|
||||
'reason' => $this->reason,
|
||||
'inspected' => $this->inspected,
|
||||
'repaired' => $this->repaired,
|
||||
'failed' => $this->failed,
|
||||
'remaining' => $this->remaining,
|
||||
'summary' => $this->summary(),
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,127 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search\Engines\Maintenance;
|
||||
|
||||
use App\Enums\SearchIndexStatus;
|
||||
use App\Search\Contracts\SearchIndexMaintainer;
|
||||
use App\Search\DTO\FulltextIndexDefinition;
|
||||
use App\Search\DTO\SearchIndexHealth;
|
||||
use App\Search\Engines\DatabaseFulltextEngine;
|
||||
use App\Search\FulltextIndexInspector;
|
||||
|
||||
/**
|
||||
* `mysql-fulltext` 드라이버의 인덱스 유지보수기
|
||||
*
|
||||
* 엔진 중립 계약(`SearchIndexMaintainer`)을 MySQL FULLTEXT 방식으로 구현합니다.
|
||||
* 판정 방법(자기 매칭 프로브)과 재생성 방법(같은 정의로 DROP/ADD)은
|
||||
* `FulltextIndexInspector` 가 갖고 있고, 이 클래스는 그 결과를 엔진 중립 DTO 로 옮깁니다.
|
||||
*
|
||||
* 다른 엔진(Meilisearch 등)은 이 클래스를 상속하지 않고 계약을 각자 구현합니다 —
|
||||
* 인덱스의 실체가 다르므로 공유할 구현이 없습니다.
|
||||
*/
|
||||
class FulltextIndexMaintainer implements SearchIndexMaintainer
|
||||
{
|
||||
/** 이 유지보수기가 담당하는 Scout 드라이버명 */
|
||||
public const DRIVER = 'mysql-fulltext';
|
||||
|
||||
/**
|
||||
* @param FulltextIndexInspector $inspector FULLTEXT 인덱스 점검기
|
||||
*/
|
||||
public function __construct(private readonly FulltextIndexInspector $inspector) {}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*/
|
||||
public function driver(): string
|
||||
{
|
||||
return self::DRIVER;
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*/
|
||||
public function isAvailable(): bool
|
||||
{
|
||||
return DatabaseFulltextEngine::supportsFulltext();
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*/
|
||||
public function unavailableReason(): ?string
|
||||
{
|
||||
return $this->isAvailable()
|
||||
? null
|
||||
: __('search.index.fulltext.unsupported_driver');
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*
|
||||
* 지원 필터: `table`(테이블명, 프리픽스 생략 가능) · `index`(인덱스명) · `samples`(표본 행 수)
|
||||
*/
|
||||
public function inspect(array $filters = []): array
|
||||
{
|
||||
$sampleSize = (int) ($filters['samples'] ?? FulltextIndexInspector::DEFAULT_SAMPLE_SIZE);
|
||||
|
||||
$results = $this->inspector->inspectAll(
|
||||
table: isset($filters['table']) ? (string) $filters['table'] : null,
|
||||
index: isset($filters['index']) ? (string) $filters['index'] : null,
|
||||
sampleSize: max(1, $sampleSize),
|
||||
);
|
||||
|
||||
return array_map(fn (array $result) => $this->toHealth($result), $results);
|
||||
}
|
||||
|
||||
/**
|
||||
* {@inheritDoc}
|
||||
*/
|
||||
public function rebuild(SearchIndexHealth $health): void
|
||||
{
|
||||
$context = $health->context;
|
||||
|
||||
$this->inspector->rebuild(new FulltextIndexDefinition(
|
||||
table: (string) ($context['table'] ?? ''),
|
||||
name: (string) ($context['name'] ?? ''),
|
||||
columns: (array) ($context['columns'] ?? []),
|
||||
parser: isset($context['parser']) ? (string) $context['parser'] : null,
|
||||
));
|
||||
}
|
||||
|
||||
/**
|
||||
* 점검기 결과를 엔진 중립 판정 DTO 로 옮깁니다.
|
||||
*
|
||||
* @param array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: ?string} $result 점검기 결과
|
||||
* @return SearchIndexHealth
|
||||
*/
|
||||
private function toHealth(array $result): SearchIndexHealth
|
||||
{
|
||||
$definition = $result['definition'];
|
||||
$status = $result['status'];
|
||||
|
||||
$measurement = $status === SearchIndexStatus::Skipped
|
||||
? (string) $result['reason']
|
||||
: __('search.index.fulltext.self_match', ['found' => $result['found'], 'probed' => $result['probed']]);
|
||||
|
||||
return new SearchIndexHealth(
|
||||
driver: self::DRIVER,
|
||||
identifier: $definition->label(),
|
||||
status: $status,
|
||||
measurement: $measurement,
|
||||
details: [
|
||||
'table' => $definition->table,
|
||||
'index' => $definition->name,
|
||||
'columns' => $definition->columns,
|
||||
'parser' => $definition->parser,
|
||||
'probed' => $result['probed'],
|
||||
'found' => $result['found'],
|
||||
],
|
||||
context: [
|
||||
'table' => $definition->table,
|
||||
'name' => $definition->name,
|
||||
'columns' => $definition->columns,
|
||||
'parser' => $definition->parser,
|
||||
],
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,367 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search;
|
||||
|
||||
use App\Enums\SearchIndexStatus;
|
||||
use App\Search\DTO\FulltextIndexDefinition;
|
||||
use App\Search\Engines\DatabaseFulltextEngine;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Throwable;
|
||||
|
||||
/**
|
||||
* FULLTEXT 인덱스 건강도 점검·복구기
|
||||
*
|
||||
* 인덱스는 존재하는데 **행이 색인되어 있지 않아** `MATCH ... AGAINST` 가 아무것도
|
||||
* 돌려주지 않는 상태를 검출하고, 같은 정의로 재생성해 복구합니다. 이 상태는
|
||||
* 오류를 남기지 않고 "검색 결과 0건" 으로만 나타나므로 로그·예외로는 드러나지 않습니다.
|
||||
*
|
||||
* 대상은 하드코딩하지 않습니다 — `INFORMATION_SCHEMA` 에서 현재 스키마의 FULLTEXT
|
||||
* 인덱스를 전수 수집하므로 코어·모듈·플러그인이 나중에 추가하는 인덱스도 자동 포함됩니다.
|
||||
*
|
||||
* ## 판정 방법 — 자기 매칭(self-match)
|
||||
*
|
||||
* 표본 행을 뽑아 **그 행 자신의 내용에서 만든 검색어로 그 행을 찾을 수 있는지** 봅니다.
|
||||
* 특정 키워드를 사람이 골라 넣지 않으므로 어떤 테이블·언어에도 그대로 적용됩니다.
|
||||
*
|
||||
* 토큰은 행마다 여러 개 만듭니다. 하나만 쓰면 토크나이저 특성으로 인한 실패를
|
||||
* 색인 누락으로 오판합니다 — 예를 들어 ngram(`ngram_token_size=2`) 은 `Basic` 을
|
||||
* `Ba/as/si/ic` 로 쪼개는데 그중 `as` 가 기본 불용어라 구문 검색이 깨집니다.
|
||||
* 그래서 **한 행이 어떤 토큰으로도 자신을 찾지 못할 때만** 그 행을 실패로 셉니다.
|
||||
*
|
||||
* ## 판정 등급
|
||||
*
|
||||
* - `healthy` — 표본 전 행이 자기 자신을 찾는다
|
||||
* - `degraded` — 일부만 찾는다. 토크나이저 특성일 수도, 일부 행만 누락된 것일 수도 있어
|
||||
* 자동 복구 대상에서 제외하고 수치만 보고한다
|
||||
* - `stale` — 표본 중 **한 행도** 자기 자신을 찾지 못한다. 색인 누락의 신호이며 복구 대상
|
||||
* - `skipped` — 표본을 만들 수 없다(행이 없거나 내용이 모두 비어 토큰 추출 불가). 사유·수치 기재
|
||||
*/
|
||||
class FulltextIndexInspector
|
||||
{
|
||||
/** 인덱스당 기본 표본 행 수 */
|
||||
public const DEFAULT_SAMPLE_SIZE = 5;
|
||||
|
||||
/** 한 행에서 만들 최대 토큰 수 */
|
||||
private const MAX_TOKENS_PER_ROW = 4;
|
||||
|
||||
/** 토큰 최대 길이 (긴 토큰은 구문 검색 비용만 늘린다) */
|
||||
private const MAX_TOKEN_LENGTH = 12;
|
||||
|
||||
/**
|
||||
* 현재 스키마의 FULLTEXT 인덱스를 전수 수집합니다.
|
||||
*
|
||||
* @param string|null $table 테이블명 필터 (프리픽스 포함/미포함 모두 허용)
|
||||
* @param string|null $index 인덱스명 필터
|
||||
* @return array<int, FulltextIndexDefinition>
|
||||
*/
|
||||
public function discover(?string $table = null, ?string $index = null): array
|
||||
{
|
||||
if (! DatabaseFulltextEngine::supportsFulltext()) {
|
||||
return [];
|
||||
}
|
||||
|
||||
$rows = DB::select(
|
||||
'SELECT TABLE_NAME AS table_name, INDEX_NAME AS index_name,
|
||||
GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) AS columns
|
||||
FROM INFORMATION_SCHEMA.STATISTICS
|
||||
WHERE TABLE_SCHEMA = DATABASE() AND INDEX_TYPE = ?
|
||||
GROUP BY TABLE_NAME, INDEX_NAME
|
||||
ORDER BY TABLE_NAME, INDEX_NAME',
|
||||
['FULLTEXT']
|
||||
);
|
||||
|
||||
$prefix = DB::getTablePrefix();
|
||||
$wanted = $table === null ? null : [$table, $prefix.$table];
|
||||
|
||||
$definitions = [];
|
||||
foreach ($rows as $row) {
|
||||
if ($wanted !== null && ! in_array($row->table_name, $wanted, true)) {
|
||||
continue;
|
||||
}
|
||||
if ($index !== null && $row->index_name !== $index) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$definitions[] = new FulltextIndexDefinition(
|
||||
table: $row->table_name,
|
||||
name: $row->index_name,
|
||||
columns: explode(',', (string) $row->columns),
|
||||
parser: $this->resolveParser($row->table_name, $row->index_name),
|
||||
);
|
||||
}
|
||||
|
||||
return $definitions;
|
||||
}
|
||||
|
||||
/**
|
||||
* 인덱스 하나의 건강도를 판정합니다.
|
||||
*
|
||||
* 엔진 중립 DTO 로의 변환은 호출자(`FulltextIndexMaintainer`)가 합니다 — 이 클래스는
|
||||
* FULLTEXT 고유의 판정만 담당하고 표현 형식을 알지 않습니다.
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @param int $sampleSize 표본 행 수
|
||||
* @return array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: string|null}
|
||||
*/
|
||||
public function inspect(FulltextIndexDefinition $definition, int $sampleSize = self::DEFAULT_SAMPLE_SIZE): array
|
||||
{
|
||||
$key = $this->resolvePrimaryKey($definition->table);
|
||||
|
||||
if ($key === null) {
|
||||
return $this->skipped($definition, __('search.index.fulltext.skip.no_single_pk'));
|
||||
}
|
||||
|
||||
$samples = $this->sampleRows($definition, $key, $sampleSize);
|
||||
|
||||
if ($samples === []) {
|
||||
return $this->skipped($definition, __('search.index.fulltext.skip.no_rows'));
|
||||
}
|
||||
|
||||
$probed = 0;
|
||||
$found = 0;
|
||||
|
||||
foreach ($samples as $sample) {
|
||||
$tokens = $this->buildTokens((string) $sample->body);
|
||||
|
||||
if ($tokens === []) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$probed++;
|
||||
|
||||
if ($this->rowFindsItself($definition, $key, $sample->pk, $tokens)) {
|
||||
$found++;
|
||||
}
|
||||
}
|
||||
|
||||
if ($probed === 0) {
|
||||
return $this->skipped($definition, __('search.index.fulltext.skip.no_tokens'));
|
||||
}
|
||||
|
||||
return [
|
||||
'definition' => $definition,
|
||||
'status' => match (true) {
|
||||
$found === 0 => SearchIndexStatus::Stale,
|
||||
$found < $probed => SearchIndexStatus::Degraded,
|
||||
default => SearchIndexStatus::Healthy,
|
||||
},
|
||||
'probed' => $probed,
|
||||
'found' => $found,
|
||||
'reason' => null,
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* 전체(또는 필터된) 인덱스의 건강도를 판정합니다.
|
||||
*
|
||||
* @param string|null $table 테이블명 필터
|
||||
* @param string|null $index 인덱스명 필터
|
||||
* @param int $sampleSize 표본 행 수
|
||||
* @return array<int, array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: string|null}>
|
||||
*/
|
||||
public function inspectAll(?string $table = null, ?string $index = null, int $sampleSize = self::DEFAULT_SAMPLE_SIZE): array
|
||||
{
|
||||
return array_map(
|
||||
fn (FulltextIndexDefinition $definition) => $this->inspect($definition, $sampleSize),
|
||||
$this->discover($table, $index)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 판정 불가 결과를 만듭니다.
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @param string $reason 사유
|
||||
* @return array{definition: FulltextIndexDefinition, status: SearchIndexStatus, probed: int, found: int, reason: string}
|
||||
*/
|
||||
private function skipped(FulltextIndexDefinition $definition, string $reason): array
|
||||
{
|
||||
return [
|
||||
'definition' => $definition,
|
||||
'status' => SearchIndexStatus::Skipped,
|
||||
'probed' => 0,
|
||||
'found' => 0,
|
||||
'reason' => $reason,
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* 인덱스를 같은 정의로 재생성합니다.
|
||||
*
|
||||
* 컬럼 구성과 파서를 그대로 유지하므로 검색 동작이 달라지지 않습니다.
|
||||
* 재생성 중에는 대상 테이블이 잠기므로 대용량 테이블에서는 시간이 걸립니다.
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @return void
|
||||
*
|
||||
* @throws Throwable 재생성 실패 시 (드롭까지만 되고 끝나지 않도록 예외를 그대로 전파)
|
||||
*/
|
||||
public function rebuild(FulltextIndexDefinition $definition): void
|
||||
{
|
||||
$table = $definition->quotedTable();
|
||||
$name = $definition->name;
|
||||
|
||||
DB::statement("ALTER TABLE {$table} DROP INDEX `{$name}`");
|
||||
|
||||
try {
|
||||
DB::statement(
|
||||
"ALTER TABLE {$table} ADD FULLTEXT INDEX `{$name}` ({$definition->quotedColumns()})"
|
||||
.$definition->parserClause()
|
||||
);
|
||||
} catch (Throwable $e) {
|
||||
// 드롭만 되고 끝나면 검색이 아예 죽는다 — 원 정의로 되돌린 뒤 예외를 전파한다
|
||||
$this->restoreQuietly($definition);
|
||||
|
||||
throw $e;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 인덱스의 파서를 조회합니다.
|
||||
*
|
||||
* `INFORMATION_SCHEMA` 는 파서를 노출하지 않으므로 `SHOW CREATE TABLE` 정의에서 읽습니다.
|
||||
*
|
||||
* @param string $table 테이블명 (프리픽스 포함)
|
||||
* @param string $index 인덱스명
|
||||
* @return string|null 파서명 (없으면 null)
|
||||
*/
|
||||
private function resolveParser(string $table, string $index): ?string
|
||||
{
|
||||
try {
|
||||
$create = DB::selectOne('SHOW CREATE TABLE `'.$table.'`');
|
||||
} catch (Throwable) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$sql = (array) $create;
|
||||
$ddl = (string) (($sql['Create Table'] ?? $sql['Create View'] ?? ''));
|
||||
|
||||
$pattern = '/FULLTEXT\s+KEY\s+`'.preg_quote($index, '/').'`[^\n]*?WITH\s+PARSER\s+`?(\w+)`?/i';
|
||||
|
||||
return preg_match($pattern, $ddl, $m) === 1 ? $m[1] : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 테이블의 단일 컬럼 기본키를 조회합니다.
|
||||
*
|
||||
* @param string $table 테이블명 (프리픽스 포함)
|
||||
* @return string|null 기본키 컬럼명 (복합키·부재 시 null)
|
||||
*/
|
||||
private function resolvePrimaryKey(string $table): ?string
|
||||
{
|
||||
$rows = DB::select(
|
||||
'SELECT COLUMN_NAME AS column_name FROM INFORMATION_SCHEMA.STATISTICS
|
||||
WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND INDEX_NAME = ?
|
||||
ORDER BY SEQ_IN_INDEX',
|
||||
[$table, 'PRIMARY']
|
||||
);
|
||||
|
||||
return count($rows) === 1 ? (string) $rows[0]->column_name : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 색인 컬럼에 내용이 있는 표본 행을 뽑습니다.
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @param string $key 기본키 컬럼명
|
||||
* @param int $sampleSize 표본 행 수
|
||||
* @return array<int, object> `pk`, `body` 를 가진 행 배열
|
||||
*/
|
||||
private function sampleRows(FulltextIndexDefinition $definition, string $key, int $sampleSize): array
|
||||
{
|
||||
$body = "CONCAT_WS(' ', {$definition->quotedColumns()})";
|
||||
|
||||
return DB::select(
|
||||
"SELECT `{$key}` AS pk, {$body} AS body
|
||||
FROM {$definition->quotedTable()}
|
||||
WHERE {$body} <> '' AND {$body} IS NOT NULL
|
||||
ORDER BY `{$key}` DESC
|
||||
LIMIT ".max(1, $sampleSize)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* 행 내용에서 검색 토큰 후보를 만듭니다.
|
||||
*
|
||||
* 비-라틴(한글·한자 등) 조각을 먼저 담습니다 — 기본 불용어 목록이 영어라
|
||||
* 라틴 토큰보다 토크나이저 영향을 덜 받습니다.
|
||||
*
|
||||
* @param string $text 행 내용
|
||||
* @return array<int, string> 토큰 후보 목록
|
||||
*/
|
||||
private function buildTokens(string $text): array
|
||||
{
|
||||
// 부울 모드 연산자(+ - > < ( ) ~ * " @)와 구분자를 제거한다
|
||||
$normalized = preg_replace('/[^\p{L}\p{N}]+/u', ' ', $text) ?? '';
|
||||
$pieces = array_values(array_filter(
|
||||
explode(' ', $normalized),
|
||||
fn (string $piece) => mb_strlen($piece) >= 2
|
||||
));
|
||||
|
||||
if ($pieces === []) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// 길이 내림차순 — 짧은 조각일수록 불용어·잡음일 확률이 높다
|
||||
usort($pieces, fn (string $a, string $b) => mb_strlen($b) <=> mb_strlen($a));
|
||||
|
||||
$nonLatin = [];
|
||||
$latin = [];
|
||||
|
||||
foreach ($pieces as $piece) {
|
||||
$token = mb_substr($piece, 0, self::MAX_TOKEN_LENGTH);
|
||||
|
||||
if (preg_match('/^[\x00-\x7F]+$/', $token) === 1) {
|
||||
$latin[] = $token;
|
||||
} else {
|
||||
$nonLatin[] = $token;
|
||||
}
|
||||
}
|
||||
|
||||
return array_slice(array_values(array_unique([...$nonLatin, ...$latin])), 0, self::MAX_TOKENS_PER_ROW);
|
||||
}
|
||||
|
||||
/**
|
||||
* 한 행이 자기 토큰 중 하나로 자신을 찾을 수 있는지 확인합니다.
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @param string $key 기본키 컬럼명
|
||||
* @param mixed $pk 행의 기본키 값
|
||||
* @param array<int, string> $tokens 토큰 후보
|
||||
* @return bool 하나라도 찾으면 true
|
||||
*/
|
||||
private function rowFindsItself(FulltextIndexDefinition $definition, string $key, mixed $pk, array $tokens): bool
|
||||
{
|
||||
foreach ($tokens as $token) {
|
||||
$hit = DB::selectOne(
|
||||
"SELECT COUNT(*) AS hits FROM {$definition->quotedTable()}
|
||||
WHERE `{$key}` = ? AND MATCH({$definition->quotedColumns()}) AGAINST(? IN BOOLEAN MODE)",
|
||||
[$pk, '"'.$token.'"']
|
||||
);
|
||||
|
||||
if ((int) ($hit->hits ?? 0) > 0) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 재생성 실패 시 원 정의로 되돌립니다 (실패해도 원 예외를 가리지 않도록 조용히 처리).
|
||||
*
|
||||
* @param FulltextIndexDefinition $definition 인덱스 정의
|
||||
* @return void
|
||||
*/
|
||||
private function restoreQuietly(FulltextIndexDefinition $definition): void
|
||||
{
|
||||
try {
|
||||
DB::statement(
|
||||
"ALTER TABLE {$definition->quotedTable()} ADD FULLTEXT INDEX `{$definition->name}` "
|
||||
."({$definition->quotedColumns()})".$definition->parserClause()
|
||||
);
|
||||
} catch (Throwable) {
|
||||
// 되돌리기까지 실패하면 원 예외가 더 중요한 정보다
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,232 @@
|
||||
<?php
|
||||
|
||||
namespace App\Search;
|
||||
|
||||
use App\Extension\HookManager;
|
||||
use App\Search\Contracts\SearchIndexMaintainer;
|
||||
use App\Search\DTO\SearchIndexHealth;
|
||||
use App\Search\DTO\SearchIndexRepairReport;
|
||||
use App\Search\Engines\Maintenance\FulltextIndexMaintainer;
|
||||
use Illuminate\Support\Facades\Log;
|
||||
use Throwable;
|
||||
|
||||
/**
|
||||
* 검색 인덱스 점검·재생성 진입점
|
||||
*
|
||||
* 활성 Scout 드라이버에 해당하는 `SearchIndexMaintainer` 를 찾아 위임합니다.
|
||||
* 코어는 어떤 엔진이 무엇을 어떻게 점검하는지 알지 못하며, 등급(`SearchIndexStatus`)만
|
||||
* 보고 재생성 대상을 고릅니다.
|
||||
*
|
||||
* ## 등록
|
||||
*
|
||||
* 기본 제공은 `mysql-fulltext` 하나이고, 확장은 필터 훅으로 자기 엔진의 유지보수기를
|
||||
* 추가합니다.
|
||||
*
|
||||
* ```php
|
||||
* HookManager::addFilter('core.search.index_maintainers', function (array $maintainers) {
|
||||
* $maintainers['meilisearch'] = MeilisearchIndexMaintainer::class;
|
||||
*
|
||||
* return $maintainers;
|
||||
* });
|
||||
* ```
|
||||
*
|
||||
* 유지보수기를 등록하지 않은 엔진은 점검 대상에서 빠질 뿐 검색은 그대로 동작합니다.
|
||||
* 그 경우 `hasMaintainer()` 가 false 이고, 화면·커맨드는 "이 엔진은 점검을 제공하지
|
||||
* 않는다" 를 명시합니다 — 점검 결과 0건과 구분되어야 하기 때문입니다.
|
||||
*
|
||||
* ## 재생성은 언제나 선택 사항이다
|
||||
*
|
||||
* 재생성 비용은 엔진에 따라 테이블 잠금(FULLTEXT)이나 전체 재색인(외부 엔진)입니다.
|
||||
* 운영 중인 사이트에서 확장 업데이트만으로 그 비용이 발생하면 안 되므로,
|
||||
* 이 클래스는 어떤 자동 트리거에도 연결하지 않고 호출자의 명시적 요청만 수행합니다.
|
||||
*/
|
||||
class SearchIndexMaintenanceManager
|
||||
{
|
||||
/** 확장이 유지보수기를 등록하는 필터 훅 */
|
||||
public const MAINTAINERS_FILTER = 'core.search.index_maintainers';
|
||||
|
||||
/** 해석된 유지보수기 캐시 (요청 수명) */
|
||||
private ?SearchIndexMaintainer $resolved = null;
|
||||
|
||||
/** 해석을 시도했는지 여부 (없음도 캐시하기 위함) */
|
||||
private bool $resolvedAttempted = false;
|
||||
|
||||
/**
|
||||
* 현재 활성 Scout 드라이버명을 반환합니다.
|
||||
*
|
||||
* @return string 드라이버명
|
||||
*/
|
||||
public function driver(): string
|
||||
{
|
||||
return (string) config('scout.driver', 'mysql-fulltext');
|
||||
}
|
||||
|
||||
/**
|
||||
* 등록된 유지보수기 맵을 반환합니다.
|
||||
*
|
||||
* @return array<string, class-string<SearchIndexMaintainer>> 드라이버명 => 구현 클래스
|
||||
*/
|
||||
public function registered(): array
|
||||
{
|
||||
$maintainers = [
|
||||
'mysql-fulltext' => FulltextIndexMaintainer::class,
|
||||
];
|
||||
|
||||
$maintainers = HookManager::applyFilters(self::MAINTAINERS_FILTER, $maintainers);
|
||||
|
||||
return is_array($maintainers) ? $maintainers : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* 활성 드라이버의 유지보수기를 반환합니다.
|
||||
*
|
||||
* @return SearchIndexMaintainer|null 등록되지 않았으면 null
|
||||
*/
|
||||
public function maintainer(): ?SearchIndexMaintainer
|
||||
{
|
||||
if ($this->resolvedAttempted) {
|
||||
return $this->resolved;
|
||||
}
|
||||
|
||||
$this->resolvedAttempted = true;
|
||||
$class = $this->registered()[$this->driver()] ?? null;
|
||||
|
||||
if ($class === null) {
|
||||
return $this->resolved = null;
|
||||
}
|
||||
|
||||
try {
|
||||
$instance = app($class);
|
||||
} catch (Throwable $e) {
|
||||
Log::warning('검색 인덱스 유지보수기 생성 실패', [
|
||||
'driver' => $this->driver(),
|
||||
'class' => $class,
|
||||
'error' => $e->getMessage(),
|
||||
]);
|
||||
|
||||
return $this->resolved = null;
|
||||
}
|
||||
|
||||
if (! $instance instanceof SearchIndexMaintainer) {
|
||||
Log::warning('검색 인덱스 유지보수기가 계약을 구현하지 않음', [
|
||||
'driver' => $this->driver(),
|
||||
'class' => $class,
|
||||
]);
|
||||
|
||||
return $this->resolved = null;
|
||||
}
|
||||
|
||||
return $this->resolved = $instance;
|
||||
}
|
||||
|
||||
/**
|
||||
* 활성 엔진이 점검을 제공하는지 여부.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function hasMaintainer(): bool
|
||||
{
|
||||
return $this->maintainer() !== null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 활성 엔진의 인덱스를 점검합니다.
|
||||
*
|
||||
* @param array<string, mixed> $filters 엔진별 필터
|
||||
* @return array<int, SearchIndexHealth>
|
||||
*/
|
||||
public function inspect(array $filters = []): array
|
||||
{
|
||||
$maintainer = $this->maintainer();
|
||||
|
||||
if ($maintainer === null || ! $maintainer->isAvailable()) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return $maintainer->inspect($filters);
|
||||
}
|
||||
|
||||
/**
|
||||
* 점검 불가 사유를 반환합니다.
|
||||
*
|
||||
* @return string|null 점검 가능하면 null
|
||||
*/
|
||||
public function unavailableReason(): ?string
|
||||
{
|
||||
$maintainer = $this->maintainer();
|
||||
|
||||
if ($maintainer === null) {
|
||||
return __('search.index.no_maintainer', ['driver' => $this->driver()]);
|
||||
}
|
||||
|
||||
return $maintainer->isAvailable() ? null : $maintainer->unavailableReason();
|
||||
}
|
||||
|
||||
/**
|
||||
* 색인이 누락된 인덱스를 재생성합니다.
|
||||
*
|
||||
* 재생성 후 **다시 점검해서** 잔존 여부를 담습니다 — 재생성했다는 사실만으로
|
||||
* 복구됐다고 단정하지 않습니다.
|
||||
*
|
||||
* @param array<string, mixed> $filters 엔진별 필터
|
||||
* @return SearchIndexRepairReport 실행 보고
|
||||
*/
|
||||
public function repairStale(array $filters = []): SearchIndexRepairReport
|
||||
{
|
||||
$maintainer = $this->maintainer();
|
||||
|
||||
if ($maintainer === null) {
|
||||
return SearchIndexRepairReport::unavailable($this->driver(), $this->unavailableReason());
|
||||
}
|
||||
|
||||
if (! $maintainer->isAvailable()) {
|
||||
return SearchIndexRepairReport::unavailable($this->driver(), $maintainer->unavailableReason());
|
||||
}
|
||||
|
||||
$before = $maintainer->inspect($filters);
|
||||
$targets = array_values(array_filter($before, fn (SearchIndexHealth $h) => $h->needsRebuild()));
|
||||
|
||||
if ($targets === []) {
|
||||
return SearchIndexRepairReport::nothingToDo($this->driver(), count($before));
|
||||
}
|
||||
|
||||
$repaired = [];
|
||||
$failed = [];
|
||||
|
||||
foreach ($targets as $target) {
|
||||
try {
|
||||
$maintainer->rebuild($target);
|
||||
$repaired[] = $target->identifier;
|
||||
} catch (Throwable $e) {
|
||||
$failed[$target->identifier] = $e->getMessage();
|
||||
Log::error('검색 인덱스 재생성 실패', [
|
||||
'driver' => $this->driver(),
|
||||
'index' => $target->identifier,
|
||||
'error' => $e->getMessage(),
|
||||
]);
|
||||
}
|
||||
}
|
||||
|
||||
$after = $maintainer->inspect($filters);
|
||||
$remaining = array_values(array_map(
|
||||
fn (SearchIndexHealth $h) => $h->identifier,
|
||||
array_filter($after, fn (SearchIndexHealth $h) => $h->needsRebuild())
|
||||
));
|
||||
|
||||
Log::info('검색 인덱스 재생성 수행', [
|
||||
'driver' => $this->driver(),
|
||||
'inspected' => count($after),
|
||||
'repaired' => $repaired,
|
||||
'failed' => array_keys($failed),
|
||||
'remaining' => $remaining,
|
||||
]);
|
||||
|
||||
return new SearchIndexRepairReport(
|
||||
driver: $this->driver(),
|
||||
inspected: count($after),
|
||||
repaired: $repaired,
|
||||
failed: $failed,
|
||||
remaining: $remaining,
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -256,9 +256,10 @@ class LanguagePackService
|
||||
* 코어/번들 확장의 `lang/{ko,en}/` 디렉토리를 자동 스캔하여 가상 보호 LanguagePack
|
||||
* 인스턴스 컬렉션을 반환합니다 (요구사항 #1, #2).
|
||||
*
|
||||
* 스캔 대상:
|
||||
* 스캔 대상 — **런타임이 실제로 로드하는 경로**와 같아야 한다. 어긋나면 관리자 화면이
|
||||
* "내장 번역" 으로 보여주는 것과 화면에 나오는 문구의 출처가 달라진다.
|
||||
* - 코어: lang/{ko,en}/
|
||||
* - 번들 모듈: modules/_bundled/{id}/resources/lang/{ko,en}/
|
||||
* - 번들 모듈: modules/_bundled/{id}/src/lang/{ko,en}/ (TranslationServiceProvider 기준)
|
||||
* - 번들 플러그인: plugins/_bundled/{id}/lang/{ko,en}/
|
||||
* - 번들 템플릿: templates/_bundled/{id}/lang/{ko,en}.json
|
||||
*
|
||||
@@ -288,11 +289,11 @@ class LanguagePackService
|
||||
}
|
||||
}
|
||||
|
||||
// 번들 모듈
|
||||
// 번들 모듈 (런타임 등록 경로 = src/lang)
|
||||
$packs = $packs->concat($this->scanBundledExtensionLang(
|
||||
bundledRoot: 'modules/_bundled',
|
||||
scope: LanguagePackScope::Module->value,
|
||||
langSubpath: 'resources/lang/'.$locale,
|
||||
langSubpath: 'src/lang/'.$locale,
|
||||
locale: $locale,
|
||||
filters: $filters,
|
||||
));
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
/**
|
||||
* 알림 발송 이력 목록의 정렬 컬럼(수신자명·제목)에 인덱스를 추가합니다.
|
||||
*
|
||||
* 목록은 지연 조인(PaginatesWithDeferredJoin)으로 페이지네이션되는데, 그 전제는
|
||||
* "정렬은 인덱스가 있는 닫힌 집합" 이다. 인덱스가 없으면 inner 쿼리도 전체 스캔이 되어
|
||||
* 깊은 OFFSET 개선 폭이 사라진다. 화면 정렬 셀렉트가 수신자명순·제목순을 제공하므로
|
||||
* 두 컬럼에 인덱스를 둔다.
|
||||
*
|
||||
* - recipient_name: 수신자명순 정렬
|
||||
* - subject: 제목순 정렬
|
||||
*/
|
||||
return new class extends Migration
|
||||
{
|
||||
/**
|
||||
* Run the migrations.
|
||||
*/
|
||||
public function up(): void
|
||||
{
|
||||
if (! Schema::hasTable('notification_logs')) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existingIndexes = array_column(Schema::getIndexes('notification_logs'), 'name');
|
||||
|
||||
Schema::table('notification_logs', function (Blueprint $table) use ($existingIndexes) {
|
||||
if (! in_array('idx_notification_logs_recipient_name', $existingIndexes)) {
|
||||
$table->index('recipient_name', 'idx_notification_logs_recipient_name');
|
||||
}
|
||||
|
||||
if (! in_array('idx_notification_logs_subject', $existingIndexes)) {
|
||||
$table->index('subject', 'idx_notification_logs_subject');
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reverse the migrations.
|
||||
*/
|
||||
public function down(): void
|
||||
{
|
||||
if (! Schema::hasTable('notification_logs')) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existingIndexes = array_column(Schema::getIndexes('notification_logs'), 'name');
|
||||
|
||||
Schema::table('notification_logs', function (Blueprint $table) use ($existingIndexes) {
|
||||
$indexes = [
|
||||
'idx_notification_logs_recipient_name',
|
||||
'idx_notification_logs_subject',
|
||||
];
|
||||
|
||||
foreach ($indexes as $index) {
|
||||
if (in_array($index, $existingIndexes)) {
|
||||
$table->dropIndex($index);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,86 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
/**
|
||||
* 코어 목록(활동 로그·알림 발송 이력·회원)의 정렬 색인 끝에 기본키를 덧붙입니다.
|
||||
*
|
||||
* 세 목록 모두 `created_at DESC, id DESC` 로 정렬한다. 색인이 `created_at` 에서 끝나면
|
||||
* 동률 구간의 `id` 순서를 인덱스로 만들 수 없어 filesort 가 붙고, 지연 조인의 inner 가
|
||||
* 인덱스 순서 그대로 끝나지 못해 깊은 OFFSET 개선 폭이 사라진다. 활동 로그처럼 같은 초에
|
||||
* 여러 건이 쌓이는 테이블에서 동률 구간은 예외가 아니라 일상이다.
|
||||
*
|
||||
* 필요한 색인은 계측 프로파일 선언(filters / order / soft_delete)에서 도출한 것이며,
|
||||
* `ListIndexCoverageTest` 가 같은 규칙으로 전 목록을 검사한다.
|
||||
*
|
||||
* - activity_logs : (created_at) → (created_at, id) 교체
|
||||
* - notification_logs : (created_at, id) 신설 (기존 정렬 색인 없음)
|
||||
* - users : (created_at) → (created_at, id) 교체
|
||||
*
|
||||
* 교체 대상 단일 색인은 새 색인의 좌측 프리픽스라 그대로 두면 쓰기 비용만 늘어난다.
|
||||
* 새 색인을 먼저 만들고 기존 색인을 나중에 지우므로, 중간에 중단되어도 조회가 색인 없이
|
||||
* 남는 구간은 없다.
|
||||
*/
|
||||
return new class extends Migration
|
||||
{
|
||||
/**
|
||||
* 대상 [테이블 => [신규 색인명, 컬럼, 교체 대상 기존 색인명(없으면 null)]]
|
||||
*
|
||||
* @var array<string, array{0: string, 1: array<int, string>, 2: string|null}>
|
||||
*/
|
||||
private const TARGETS = [
|
||||
'activity_logs' => ['idx_activity_logs_created_id', ['created_at', 'id'], 'g7_activity_logs_created_at_index'],
|
||||
'notification_logs' => ['idx_notification_logs_created_id', ['created_at', 'id'], null],
|
||||
'users' => ['idx_users_created_id', ['created_at', 'id'], 'idx_users_created_at'],
|
||||
];
|
||||
|
||||
/**
|
||||
* Run the migrations.
|
||||
*/
|
||||
public function up(): void
|
||||
{
|
||||
foreach (self::TARGETS as $table => [$newIndex, $columns, $oldIndex]) {
|
||||
if (! Schema::hasTable($table)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes($table), 'name');
|
||||
|
||||
Schema::table($table, function (Blueprint $blueprint) use ($existing, $newIndex, $columns, $oldIndex) {
|
||||
if (! in_array($newIndex, $existing, true)) {
|
||||
$blueprint->index($columns, $newIndex);
|
||||
}
|
||||
|
||||
if ($oldIndex !== null && in_array($oldIndex, $existing, true)) {
|
||||
$blueprint->dropIndex($oldIndex);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reverse the migrations.
|
||||
*/
|
||||
public function down(): void
|
||||
{
|
||||
foreach (self::TARGETS as $table => [$newIndex, $columns, $oldIndex]) {
|
||||
if (! Schema::hasTable($table)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes($table), 'name');
|
||||
|
||||
Schema::table($table, function (Blueprint $blueprint) use ($existing, $newIndex, $oldIndex) {
|
||||
if ($oldIndex !== null && ! in_array($oldIndex, $existing, true)) {
|
||||
$blueprint->index(['created_at'], $oldIndex);
|
||||
}
|
||||
|
||||
if (in_array($newIndex, $existing, true)) {
|
||||
$blueprint->dropIndex($newIndex);
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
};
|
||||
@@ -201,11 +201,11 @@ location ~* \.(js|css|json)$ { expires max; access_log off; }
|
||||
> 각 확장이 자신의 API 문서를 소유합니다. 아래 표는 자동 생성됩니다.
|
||||
|
||||
<!-- @generated:start:api-readme-extensions -->
|
||||
- **확장 수**: 13 · **엔드포인트 수**: 385
|
||||
- **확장 수**: 13 · **엔드포인트 수**: 390
|
||||
|
||||
| 확장 | 유형 | API 문서 목차 | 문서/엔드포인트 |
|
||||
| --- | --- | --- | --- |
|
||||
| `gnuboard7-hello_module` | 모듈 | [docs/api/](../../../modules/_bundled/gnuboard7-hello_module/docs/api/README.md) | 1 / 2 |
|
||||
| `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 / 231 |
|
||||
| `sirsoft-page` | 모듈 | [docs/api/](../../../modules/_bundled/sirsoft-page/docs/api/README.md) | 2 / 17 |
|
||||
|
||||
@@ -3456,6 +3456,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| layout_strategy | body | string | 아니오 | `overwrite`, `keep` | 업데이트 시 레이아웃 처리 전략 (overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) |
|
||||
| vendor_mode | body | string | 아니오 | `auto`, `composer`, `bundled` | 벤더 설치 모드 (auto/composer/bundled) |
|
||||
| force | body | boolean | 아니오 | — | 강제 실행 여부 (안전 확인/선행 검사 우회) |
|
||||
| rebuild_search_index | body | boolean | 아니오 | — | 업데이트 후 색인이 누락된 검색 인덱스를 재생성할지 여부 (기본 false). 재생성 중에는 대상 인덱스가 잠기거나 재색인되므로 운영 중인 사이트에서는 접속이 적은 시간에 별도로 수행하는 것을 권장 |
|
||||
|
||||
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.module.perform_update_validation_rules`).
|
||||
|
||||
@@ -3471,7 +3472,8 @@ Content-Type: application/json
|
||||
{
|
||||
"layout_strategy": "overwrite",
|
||||
"vendor_mode": "auto",
|
||||
"force": true
|
||||
"force": true,
|
||||
"rebuild_search_index": false
|
||||
}
|
||||
```
|
||||
|
||||
@@ -3494,7 +3496,7 @@ Content-Type: application/json
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** 특정 모듈을 최신 버전으로 업데이트합니다. `core.modules.install` 권한이 필요합니다. `layout_strategy` 로 레이아웃 처리 방식을(overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) 지정하며, `vendor_mode` 로 Composer 의존성 처리 방식을 선택합니다. 버전 제약·호환성 문제로 막힐 경우 `force: true` 로 강제 진행할 수 있습니다. `keep` 을 지정하면 사용자가 수정한 레이아웃(원본 해시와 현재 내용이 다른 레이아웃)은 갱신 대상에서 제외되어 현재 내용이 그대로 유지되고, 나머지 레이아웃만 파일 기준으로 갱신됩니다. 성공 응답 메시지에는 대상 식별자와 적용된 버전이 채워집니다.
|
||||
**설명** 특정 모듈을 최신 버전으로 업데이트합니다. `core.modules.install` 권한이 필요합니다. `layout_strategy` 로 레이아웃 처리 방식을(overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) 지정하며, `vendor_mode` 로 Composer 의존성 처리 방식을 선택합니다. 버전 제약·호환성 문제로 막힐 경우 `force: true` 로 강제 진행할 수 있습니다. `keep` 을 지정하면 사용자가 수정한 레이아웃(원본 해시와 현재 내용이 다른 레이아웃)은 갱신 대상에서 제외되어 현재 내용이 그대로 유지되고, 나머지 레이아웃만 파일 기준으로 갱신됩니다. 성공 응답 메시지에는 대상 식별자와 적용된 버전이 채워집니다. `rebuild_search_index: true` 를 함께 보내면 업데이트 후 색인이 누락된 검색 인덱스를 재생성합니다 — 인덱스 잠금·재색인 비용이 있어 기본은 수행하지 않으며, 보내지 않아도 응답의 `search_index` 에 현재 누락 여부가 담깁니다.
|
||||
|
||||
|
||||
### GET /api/modules/assets/{identifier}/{path}
|
||||
|
||||
@@ -35,7 +35,7 @@
|
||||
| extension_type | query | string | 아니오 | `core`, `module`, `plugin` | 확장 유형 (core/module/plugin/template) |
|
||||
| status | query | string | 아니오 | — | 상태 필터 (해당 상태의 항목만 조회) |
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
| sort_by | query | string | 아니오 | `id`, `channel`, `notification_type`, `status`, `sent_at`, `created_at` | 정렬 기준 필드명 |
|
||||
| sort_by | query | string | 아니오 | `id`, `channel`, `notification_type`, `status`, `sent_at`, `created_at`, `recipient_name`, `subject` | 정렬 기준 필드명 (`recipient_name`·`subject` 는 관리자 화면의 "수신자명순"·"제목순" 정렬에 대응) |
|
||||
| sort_order | query | string | 아니오 | `asc`, `desc` | 정렬 방향 (asc 오름차순 / desc 내림차순) |
|
||||
|
||||
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.notification_log.index_validation_rules`).
|
||||
|
||||
@@ -1208,6 +1208,7 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
| layout_strategy | body | string | 아니오 | `overwrite`, `keep` | 레이아웃 처리 전략 (overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) |
|
||||
| vendor_mode | body | string | 아니오 | `auto`, `composer`, `bundled` | 벤더 설치 모드 (auto/composer/bundled) |
|
||||
| force | body | boolean | 아니오 | — | 강제 실행 여부 (안전 확인/선행 검사 우회) |
|
||||
| rebuild_search_index | body | boolean | 아니오 | — | 업데이트 후 색인이 누락된 검색 인덱스를 재생성할지 여부 (기본 false). 재생성 중에는 대상 인덱스가 잠기거나 재색인되므로 운영 중인 사이트에서는 접속이 적은 시간에 별도로 수행하는 것을 권장 |
|
||||
|
||||
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.plugin.perform_update_validation_rules`).
|
||||
|
||||
@@ -1223,7 +1224,8 @@ Content-Type: application/json
|
||||
{
|
||||
"layout_strategy": "overwrite",
|
||||
"vendor_mode": "auto",
|
||||
"force": true
|
||||
"force": true,
|
||||
"rebuild_search_index": false
|
||||
}
|
||||
```
|
||||
|
||||
@@ -1246,7 +1248,7 @@ Content-Type: application/json
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** 특정 플러그인을 최신 버전으로 업데이트합니다. `core.plugins.install` 권한이 필요합니다. `layout_strategy` 로 레이아웃 처리 방식을(overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) 지정하며, `vendor_mode` 로 Composer 의존성 처리 방식을 선택합니다. 버전 제약·호환성 문제로 막힐 경우 `force: true` 로 강제 진행할 수 있습니다. `keep` 을 지정하면 사용자가 수정한 레이아웃(원본 해시와 현재 내용이 다른 레이아웃)은 갱신 대상에서 제외되어 현재 내용이 그대로 유지되고, 나머지 레이아웃만 파일 기준으로 갱신됩니다. 성공 응답 메시지에는 대상 식별자와 적용된 버전이 채워집니다.
|
||||
**설명** 특정 플러그인을 최신 버전으로 업데이트합니다. `core.plugins.install` 권한이 필요합니다. `layout_strategy` 로 레이아웃 처리 방식을(overwrite: 새 버전으로 교체, keep: 사용자 수정본 유지) 지정하며, `vendor_mode` 로 Composer 의존성 처리 방식을 선택합니다. 버전 제약·호환성 문제로 막힐 경우 `force: true` 로 강제 진행할 수 있습니다. `keep` 을 지정하면 사용자가 수정한 레이아웃(원본 해시와 현재 내용이 다른 레이아웃)은 갱신 대상에서 제외되어 현재 내용이 그대로 유지되고, 나머지 레이아웃만 파일 기준으로 갱신됩니다. 성공 응답 메시지에는 대상 식별자와 적용된 버전이 채워집니다. `rebuild_search_index: true` 를 함께 보내면 업데이트 후 색인이 누락된 검색 인덱스를 재생성합니다 — 인덱스 잠금·재색인 비용이 있어 기본은 수행하지 않으며, 보내지 않아도 응답의 `search_index` 에 현재 누락 여부가 담깁니다.
|
||||
|
||||
|
||||
### GET /api/plugins/assets/{identifier}/{path}
|
||||
|
||||
@@ -11,8 +11,9 @@
|
||||
1. Laravel Scout + DatabaseFulltextEngine: MySQL FULLTEXT + ngram 기반 검색 (기본 드라이버)
|
||||
2. FulltextSearchable 인터페이스: searchableColumns() + searchableWeights() 구현 필수
|
||||
3. LIKE fallback 자동 적용: FULLTEXT 미지원 DBMS(SQLite, PostgreSQL)에서 자동 전환
|
||||
4. 확장 포인트: core.search.engine_drivers 필터 훅으로 Meilisearch 등 커스텀 엔진 등록 가능
|
||||
5. AsUnicodeJson 캐스트: JSON 컬럼 FULLTEXT 검색 시 한글 \uXXXX 이스케이프 방지 필수
|
||||
4. 확장 포인트: core.search.engine_drivers(엔진) + core.search.index_maintainers(인덱스 점검) 필터 훅
|
||||
5. 인덱스 재생성은 언제나 선택 사항 — 자동 트리거 없음 (테이블 잠금·전체 재색인 비용)
|
||||
6. AsUnicodeJson 캐스트: JSON 컬럼 FULLTEXT 검색 시 한글 \uXXXX 이스케이프 방지 필수
|
||||
```
|
||||
|
||||
---
|
||||
@@ -56,6 +57,10 @@ DatabaseFulltextEngine
|
||||
| `app/Providers/ScoutServiceProvider.php` | 엔진 등록 + 필터 훅 처리 |
|
||||
| `app/Casts/AsUnicodeJson.php` | FULLTEXT ngram용 UTF-8 JSON 캐스트 |
|
||||
| `config/scout.php` | Scout 설정 (드라이버, 큐, 소프트삭제 등) |
|
||||
| `app/Search/Contracts/SearchIndexMaintainer.php` | 인덱스 점검·재생성 계약 (엔진 중립) |
|
||||
| `app/Search/SearchIndexMaintenanceManager.php` | 활성 드라이버의 점검기 해석 + 재생성 진입점 |
|
||||
| `app/Search/Engines/Maintenance/FulltextIndexMaintainer.php` | mysql-fulltext 드라이버의 점검기 구현 |
|
||||
| `app/Console/Commands/Search/SearchIndexCommand.php` | `search:index` 점검·재생성 커맨드 |
|
||||
|
||||
**설계 원칙**:
|
||||
|
||||
@@ -225,6 +230,120 @@ $this->app->resolving(EngineManager::class, function (EngineManager $manager) us
|
||||
});
|
||||
```
|
||||
|
||||
### core.search.index_maintainers 필터 훅
|
||||
|
||||
검색 엔진은 "인덱스가 있는데 내용이 색인되어 있지 않은" 상태가 될 수 있습니다. 이때 검색은
|
||||
**오류 없이 0건**을 돌려주므로 예외도 로그도 남지 않고, 운영자는 "원래 검색이 안 되는 줄" 알고
|
||||
지나갑니다. `SearchIndexMaintainer` 계약이 그 상태를 점검·복구하는 방법을 엔진마다 정의합니다.
|
||||
|
||||
인덱스의 실체가 엔진마다 다르므로(FULLTEXT = 테이블에 붙은 인덱스, Meilisearch/Elasticsearch =
|
||||
외부 서버의 인덱스) 코어는 판정 방법을 알지 못한 채 계약만 호출하고, 등급(`SearchIndexStatus`)만
|
||||
보고 재생성 대상을 고릅니다.
|
||||
|
||||
```php
|
||||
use App\Extension\HookManager;
|
||||
use App\Search\SearchIndexMaintenanceManager;
|
||||
|
||||
HookManager::addFilter(SearchIndexMaintenanceManager::MAINTAINERS_FILTER, function (array $maintainers) {
|
||||
$maintainers['meilisearch'] = MeilisearchIndexMaintainer::class;
|
||||
|
||||
return $maintainers;
|
||||
});
|
||||
```
|
||||
|
||||
구현할 메서드
|
||||
|
||||
| 메서드 | 반환 | 설명 |
|
||||
|--------|------|------|
|
||||
| `driver()` | `string` | 담당 Scout 드라이버명 (`config('scout.driver')` 와 대조) |
|
||||
| `isAvailable()` | `bool` | 현재 환경에서 점검 가능 여부 (미지원 DBMS·서버 미연결 등) |
|
||||
| `unavailableReason()` | `?string` | 점검 불가 사유. **"점검 대상 0" 과 "점검할 수 없었음" 은 구분되어야 한다** |
|
||||
| `inspect(array $filters)` | `SearchIndexHealth[]` | 인덱스별 판정. 엔진별 세부는 `details`, 재생성에 필요한 자기 정보는 `context` 에 담는다 |
|
||||
| `rebuild(SearchIndexHealth $health)` | `void` | 재생성 (`context` 를 그대로 되돌려받는다) |
|
||||
|
||||
판정 등급 (`App\Enums\SearchIndexStatus`)
|
||||
|
||||
| 등급 | 뜻 | 재생성 대상 |
|
||||
|------|-----|:---:|
|
||||
| `healthy` | 색인된 내용으로 검색이 성립 | — |
|
||||
| `degraded` | 일부만 성립. 토크나이저 특성(불용어 등)일 수 있다 | ✕ |
|
||||
| `stale` | 검색이 성립하지 않음 | ✅ |
|
||||
| `skipped` | 표본·연결 부재로 판정 불가 (사유 기재) | — |
|
||||
|
||||
유지보수기를 등록하지 않은 엔진은 점검 대상에서 빠질 뿐 **검색은 그대로 동작**합니다. 화면·커맨드는
|
||||
그 경우 "이 엔진은 점검을 제공하지 않는다" 를 명시합니다.
|
||||
|
||||
### 재생성은 언제나 선택 사항이다
|
||||
|
||||
재생성 비용은 엔진에 따라 테이블 잠금(FULLTEXT)이나 전체 재색인(외부 엔진)입니다. **운영 중인
|
||||
사이트에서 확장을 업데이트했다는 이유만으로 그 비용이 발생해서는 안 되므로**, 재생성은 어떤 자동
|
||||
트리거에도 연결하지 않고 운영자가 명시적으로 선택했을 때만 수행합니다.
|
||||
|
||||
| 경로 | 선택 방법 | 기본값 |
|
||||
|------|----------|:---:|
|
||||
| `search:index --repair` | 옵션 + 확인 프롬프트 | 점검만 |
|
||||
| `module:update` / `plugin:update` / `module:install` / `plugin:install` | `--rebuild-search-index` | 미수행 |
|
||||
| `core:update` (번들 확장 일괄 업데이트 단계) | 대화형 확인 또는 `--rebuild-search-index` | 미수행 |
|
||||
| 관리자 화면 확장 업데이트 모달 | 「업데이트 후 색인이 누락된 검색 인덱스를 재생성」 체크박스 | 미체크 |
|
||||
|
||||
선택하지 않아도 **누락 사실은 안내**합니다 — 알려주지 않으면 운영자가 알 방법이 없기 때문입니다.
|
||||
|
||||
`--force`(무인 실행)에서는 묻지도 재생성하지도 않습니다. 무인 실행이 대용량 테이블을 잠그는 일이
|
||||
없어야 합니다.
|
||||
|
||||
### 선택은 그 창에서만 유효하다 — 화면 상태를 이월하지 않는다
|
||||
|
||||
재생성 체크는 **모달을 열 때마다 해제된 상태**로 시작해야 합니다. 체크 상태를 전역 상태에 남겨 두면
|
||||
한 번 체크한 운영자가 다음 확장을 업데이트할 때 **아무것도 누르지 않았는데 재생성이 다시 수행**됩니다.
|
||||
서버의 옵인 가드(요청에 실린 값만 신뢰)는 정상 동작하므로 HTTP 레벨 테스트로는 드러나지 않습니다 —
|
||||
화면이 이미 체크된 값을 보내기 때문입니다.
|
||||
|
||||
| ❌ 금지 | ✅ 올바른 사용 |
|
||||
| --- | --- |
|
||||
| 모달을 여는 `setState` 시드에 재생성 키를 빼 둠 | 시드와 제출 후 초기화 **양쪽**에 `<x>RebuildSearchIndex: false` |
|
||||
| 제출 성공 후 다른 상태만 되돌리고 재생성 체크는 그대로 둠 | `onSuccess` 초기화 목록에 재생성 키 포함 |
|
||||
| 모듈·플러그인이 같은 전역 키를 공유 | 면마다 별도 키 (한쪽 체크가 다른 쪽으로 전이되면 안 됨) |
|
||||
|
||||
정적 고정: `templates/_bundled/sirsoft-admin_basic/__tests__/layouts/admin-extension-update-rebuild-optin.test.tsx`
|
||||
종단 고정: `tests/Playwright/specs/admin/extension-update-search-index-optin.spec.ts`
|
||||
|
||||
### 점검 결과는 반드시 호출자에게 도달해야 한다
|
||||
|
||||
색인이 비면 검색은 **오류 없이 0건**을 돌려줍니다. 운영자가 알 수 있는 유일한 통로가 응답에 실린
|
||||
`search_index` 페이로드이므로, 그 페이로드가 중간에서 사라지면 점검 기능 자체가 무의미해집니다.
|
||||
|
||||
| ❌ 금지 | ✅ 올바른 사용 |
|
||||
| --- | --- |
|
||||
| 응답 헬퍼가 `JsonResource::resolve()` 만 호출 (부가 데이터 유실) | `ResponseHelper::successWithResource` 가 `additional()` 을 응답 최상위에 병합 |
|
||||
| 재생성 여부만 알리고 잔존 여부는 생략 | `rebuilt` / `stale`·`stale_count` (미수행) 또는 `repaired`·`failed`·`remaining` (수행) |
|
||||
| 재생성 성공을 곧 복구로 간주 | **`remaining` 은 재생성 후 재점검 결과** — "재생성했다" 와 "복구됐다" 를 구분 |
|
||||
|
||||
### 점검의 비-0 종료는 "실패" 가 아니다
|
||||
|
||||
`search:index` 는 색인 누락이 남아 있으면 종료 코드 1 을 돌려줍니다. 점검 자체는 정상 수행된 것이며,
|
||||
이는 CI 에서 이상을 감지하기 위한 신호입니다. 실행 결과를 화면에 표시하는 도구(개발 도구 대시보드 등)가
|
||||
이를 「실행 실패」로 적으면 운영자는 도구가 고장난 것으로 읽고 **정작 발견된 색인 누락을 놓칩니다**.
|
||||
종료 코드와 출력을 그대로 보여 주고, 실패로 단정하지 않습니다.
|
||||
|
||||
### mysql-fulltext 의 판정 방법 — 자기 매칭(self-match)
|
||||
|
||||
기본 드라이버의 유지보수기는 표본 행을 뽑아 **그 행 자신의 내용에서 만든 검색어로 그 행을 찾을 수
|
||||
있는지** 봅니다. 특정 키워드를 사람이 골라 넣지 않으므로 어떤 테이블·언어에도 그대로 적용됩니다.
|
||||
|
||||
토큰은 행마다 여러 개 만들고, **한 행이 어떤 토큰으로도 자신을 찾지 못할 때만** 실패로 셉니다.
|
||||
하나만 쓰면 토크나이저 특성을 색인 누락으로 오판합니다 — 예를 들어 ngram(`ngram_token_size=2`)은
|
||||
`Basic` 을 `Ba/as/si/ic` 로 쪼개는데 그중 `as` 가 기본 불용어라 구문 검색이 깨집니다.
|
||||
|
||||
대상은 하드코딩하지 않고 `INFORMATION_SCHEMA` 에서 전수 수집하므로, 확장이 나중에 추가하는
|
||||
FULLTEXT 인덱스도 커맨드 수정 없이 포함됩니다.
|
||||
|
||||
```bash
|
||||
php artisan search:index # 활성 엔진의 인덱스 점검 (읽기 전용)
|
||||
php artisan search:index --repair # 색인 누락 인덱스 재생성
|
||||
php artisan search:index --filter=table=pages # 엔진별 필터 (FULLTEXT: table, index, samples)
|
||||
php artisan search:index --json # 기계 판독용 출력
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 마이그레이션
|
||||
|
||||
@@ -27,6 +27,7 @@
|
||||
- [상태 변경 자동 처리](#상태-변경-자동-처리)
|
||||
- [Repository 클래스](#repository-클래스)
|
||||
- [목록 조회 컬럼 프루닝과 지연 조인](#목록-조회-컬럼-프루닝과-지연-조인)
|
||||
- [페이지네이션 정렬의 전순서 보장](#페이지네이션-정렬의-전순서-보장)
|
||||
- [다중 검색 필터 Trait](#다중-검색-필터-trait-hasmultiplesearchfilters)
|
||||
- [모듈에서 Repository 인터페이스 바인딩](#모듈에서-repository-인터페이스-바인딩)
|
||||
- [중첩 리소스 스코프](#중첩-리소스-스코프)
|
||||
@@ -859,9 +860,7 @@ php artisan g7:bench --profile=sirsoft-board/board_posts --seed=200000 --offsets
|
||||
|
||||
같은 계측의 실행 계획을 보면 원인이 하나 더 드러난다. OFFSET 0 은 `(board_id, created_at)` 인덱스를 역방향으로 훑어 정렬 없이 끝나지만, OFFSET 이 커지면 옵티마이저가 소프트 삭제 단독 인덱스(`deleted_at`)로 갈아타면서 `filesort` 가 붙는다. 넓은 컬럼을 걷어내는 것과 정렬을 인덱스로 덮는 것은 함께 가야 한다.
|
||||
|
||||
`SUBSTRING(content, 1, N)` 을 목록 컬럼에 두는 것도 프루닝이 아니다. 앞 N 바이트를 얻기 위해 오버플로 페이지를 그대로 읽는다.
|
||||
|
||||
`SUBSTRING(content, 1, 200)` 을 목록 컬럼에 두는 것은 프루닝이 아니다. 앞 200바이트를 얻기 위해 오버플로 페이지를 그대로 읽기 때문이다. 잘라내기는 지연 조인의 outer 로 옮긴다.
|
||||
`SUBSTRING(content, 1, N)` 을 목록 컬럼에 두는 것은 프루닝이 아니다. 앞 N 바이트를 얻기 위해 오버플로 페이지를 그대로 읽기 때문이다. 잘라내기는 지연 조인의 outer 로 옮긴다.
|
||||
|
||||
계측 대상 프로파일 선언 방법과 나머지 3축(화면 응답·쓰기·배치)은 [benchmark.md](benchmark.md) 를 참조한다.
|
||||
|
||||
@@ -897,10 +896,13 @@ class OrderRepository implements OrderRepositoryInterface
|
||||
| 항목 | 규칙 |
|
||||
| ------ | ------ |
|
||||
| `$query` | 필터/where 만 적용한다. `orderBy`/`with`/`select` 는 Trait 이 담당한다 |
|
||||
| `whereHas` | 결과 집합을 결정하는 조건이므로 그대로 둔다. Trait 은 `with` 만 inner 에서 제거한다 |
|
||||
| `whereHas` | 결과 집합을 결정하는 조건이므로 그대로 둔다. Trait 이 지우는 것은 `with`(eager load) 뿐이다 |
|
||||
| 관계 | **반드시 `relations:` 인자로 넘긴다.** Trait 은 inner 뿐 아니라 **outer 에서도** `setEagerLoads([])` 로 eager load 를 지우므로, `$query->with()` 만 하고 인자를 생략하면 관계가 로드되지 않는다 |
|
||||
| 정렬 | 닫힌 집합이어야 한다. 인덱스 없는 임의 컬럼 정렬은 inner 도 전체 스캔하므로 개선 폭이 보장되지 않는다 |
|
||||
| 키 컬럼 | 정렬 스펙 끝에 자동으로 덧붙는다. 동률 행의 순서가 흔들려 페이지 경계에서 행이 중복·누락되는 것을 막는다 |
|
||||
|
||||
관계 계약을 어겨도 예외나 쿼리 오류는 나지 않는다. 응답에서 관계 필드만 사라지므로, 그 필드를 단언하지 않는 테스트는 전부 통과한다. 실제로 스케줄 실행 이력의 실행자(`triggered_by`)가 이 형태로 유실됐다. `DeferredJoinCallSiteContractTest` 가 호출처를 스캔해 이 조합을 차단한다.
|
||||
|
||||
`paginate` / `simplePaginate` / 캐시 total 주입은 인자로 구분한다 — inner 쿼리는 동일하고 COUNT 수행 여부와 반환 클래스만 달라진다.
|
||||
|
||||
| 호출자 상황 | `$simple` | `$total` | 반환 |
|
||||
@@ -944,6 +946,137 @@ foreach ($this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at')
|
||||
|
||||
`repository-sort-column-whitelist` 룰은 **정렬 컬럼 변수 자체를 인자로 받는** `in_array`/`match`/`array_key_exists` 또는 `resolveSortSpec` 만 화이트리스트로 인정한다.
|
||||
|
||||
### 화면 정렬 옵션은 게이트의 부분집합이어야 한다
|
||||
|
||||
앞 절의 불변식(게이트 ⊆ 저장소)은 백엔드 두 계층 사이의 관계다. 그 위에 하나가 더 있다.
|
||||
|
||||
```text
|
||||
화면 정렬 옵션 ⊆ FormRequest 게이트 ⊆ Repository 화이트리스트
|
||||
```
|
||||
|
||||
레이아웃의 정렬 셀렉트가 게이트에 없는 컬럼을 제공하면 그 옵션을 고르는 순간 **422 가 나고 목록은 직전 결과 그대로 남는다.** 셀렉트 라벨만 새 값으로 바뀌므로 운영자는 정렬이 적용됐다고 읽는다. 토스트도 뜨지 않는다(목록 데이터소스의 오류 경로라 화면에 노출되지 않는다).
|
||||
|
||||
정렬 옵션을 추가할 때는 세 곳을 함께 본다.
|
||||
|
||||
1. 레이아웃의 `options[].value` (`{col}_{asc|desc}` 형태로 `sort_by` 를 만든다)
|
||||
2. FormRequest 의 `sort_by` `in:` / `Rule::in`
|
||||
3. Repository 의 `SORTABLE_COLUMNS` (원 테이블 컬럼) 또는 `RELATED_SORTABLE_COLUMNS` (관계 테이블 컬럼)
|
||||
|
||||
정렬 기준 컬럼이 **원 테이블에 없으면** 다음 절의 관계 정렬을 쓴다. 화면에서 옵션을 지우는 것은 마지막 수단이다 — 운영자가 쓰던 기능이 사라진다.
|
||||
|
||||
`layout-sort-option-gate-parity` 룰이 레이아웃 정렬 옵션과 게이트를 정적으로 대조한다.
|
||||
|
||||
### 분류값 필터의 허용 어휘도 같은 불변식을 따른다
|
||||
|
||||
정렬에서 성립하는 포함관계는 **분류값 필터**(출처·유형·상태 등)에서도 그대로 성립한다. 다만 어긋나는 방향이 반대다 — 정렬은 화면이 게이트보다 넓어서 422 가 나고, 필터는 화면이 **좁아서** 아무 오류 없이 일부 행이 사라진다.
|
||||
|
||||
```text
|
||||
화면 필터 옵션 = 라벨 키 = 실제 기록 어휘 (부분집합이 아니라 일치여야 한다)
|
||||
```
|
||||
|
||||
빠진 값으로 기록된 행에는 두 가지가 동시에 일어난다.
|
||||
|
||||
| 어긋난 지점 | 증상 | 화면에 오류가 나는가 |
|
||||
|---|---|---|
|
||||
| 화면 필터 옵션에 그 값이 없음 | 그 값의 행은 **어떤 필터 조합으로도 도달 불가** — "전체" 로만 스쳐 지나간다 | 아니다 |
|
||||
| 라벨 키가 없음 | 목록 셀에 `vendor-plugin.admin.x.source.그값` 원시 키 문자열이 노출 | 아니다 |
|
||||
|
||||
그래서 어휘는 **Enum 하나에서 파생**시킨다. FormRequest 의 `in:` 문자열, 리스너·서비스의 기록 리터럴, 레이아웃 체크박스, lang 파일에 같은 목록을 네 번 적으면 한 곳만 늘어난 순간 위 두 증상이 조용히 생긴다.
|
||||
|
||||
```php
|
||||
enum ConsentSource: string
|
||||
{
|
||||
case Banner = 'banner';
|
||||
case Register = 'register'; // 리스너가 기록하는 값도 반드시 여기에
|
||||
case MypageRenewAll = 'mypage_renew_all'; // 서버 자체 기록 경로도 마찬가지
|
||||
|
||||
/** 공개 요청으로 지정 가능한 값 — 서버 자체 기록 경로는 제외 */
|
||||
public static function requestSelectableValues(): array { /* ... */ }
|
||||
}
|
||||
```
|
||||
|
||||
라벨은 **백엔드와 프론트 두 표면 모두**에 정의한다. 관리자 화면의 `$t:` 는 `resources/lang/{locale}.json` 에서 해석되므로 `lang/{locale}/messages.php` 만 채우면 화면에는 여전히 원시 키가 남는다. 치환 문법도 다르다 — 백엔드는 `:name`, 프론트 엔진(`TranslationEngine.replaceParams`)은 `{name}` / `{{name}}` 만 치환한다.
|
||||
|
||||
어느 enum 이 어느 화면의 어휘인지는 의미 추론이 필요해 정적 검출이 어렵다(`coverage.json` 의 `filter-vocabulary-enum-parity` = `manual-only`). 확장별로 정합 테스트를 둔다 — 예: `ConsentSourceVocabularyParityTest` (기록 리터럴 ⊆ enum / 화면 옵션 = enum / ko·en × 백엔드·프론트 라벨 전수).
|
||||
|
||||
### 목록에 `last_page > 1` 이면 화면에도 페이저가 있어야 한다
|
||||
|
||||
응답이 페이지네이션인데 화면이 1페이지만 렌더하고 페이지 이동 컨트롤을 두지 않으면, 나머지 페이지는 **어떤 조작으로도 도달할 수 없다.** 총건수 표시까지 없으면 잘렸다는 사실 자체가 화면에 나타나지 않아 "이력이 그것뿐" 으로 읽힌다(감사 이력·정책 버전처럼 입증 책임이 있는 목록에서는 특히 위험하다).
|
||||
|
||||
데이터가 얕은 개발 환경에서는 `last_page` 가 늘 1 이라 이 결함이 드러나지 않는다. 페이지네이션 응답을 소비하는 화면을 만들 때는 `per_page` 를 줄이거나 행을 늘려 **2페이지 이상인 상태를 한 번은 눈으로 확인**한다.
|
||||
|
||||
### 관계 테이블 컬럼 기준 정렬 (`SortsByRelatedColumn`)
|
||||
|
||||
정렬 기준이 원 테이블이 아니라 관계 테이블에 있는 경우가 있다. 주문 목록의 "발송일" 이 그렇다 — `shipped_at` 은 주문이 아니라 배송 테이블에 있고, 한 주문에 배송 행이 여러 건일 수 있다.
|
||||
|
||||
이때 **조인으로 해결하지 않는다.** 두 가지가 함께 깨진다.
|
||||
|
||||
| 방식 | 무엇이 깨지는가 |
|
||||
|---|---|
|
||||
| `join` + `groupBy` | 1:N 조인이 원 행을 부풀린다 → 총 건수가 늘고 페이지 경계가 어긋난다 |
|
||||
| `leftJoin` 만 | 자식이 여러 건인 부모가 목록에 중복 노출된다 |
|
||||
| `join` (INNER) | 자식이 없는 부모(미발송 주문)가 목록에서 사라진다 |
|
||||
| inner 쿼리에 집계 | 건너뛸 행 전체에 집계가 돌아 OFFSET 이 깊어질수록 비용이 누적된다 — 지연 조인을 넣은 이유가 사라진다 |
|
||||
|
||||
**상관 서브쿼리 정렬**을 쓴다. 원 행 수를 바꾸지 않으므로 총 건수·페이지 경계가 그대로 유지되고, 자식이 없는 행도 남는다(값이 `NULL` 로 정렬될 뿐이다).
|
||||
|
||||
```php
|
||||
use App\Repositories\Concerns\PaginatesWithDeferredJoin;
|
||||
use App\Repositories\Concerns\ResolvesSortSpec;
|
||||
use App\Repositories\Concerns\SortsByRelatedColumn;
|
||||
|
||||
class OrderRepository implements OrderRepositoryInterface
|
||||
{
|
||||
use PaginatesWithDeferredJoin;
|
||||
use ResolvesSortSpec;
|
||||
use SortsByRelatedColumn;
|
||||
|
||||
/** 원 테이블 컬럼 */
|
||||
private const SORTABLE_COLUMNS = ['ordered_at', 'paid_at', 'total_amount'];
|
||||
|
||||
/** 관계 테이블 컬럼 — `(외래키, 정렬컬럼)` 복합 인덱스가 전제 */
|
||||
private const RELATED_SORTABLE_COLUMNS = [
|
||||
'shipped_at' => [
|
||||
'model' => OrderShipping::class,
|
||||
'foreign_key' => 'order_id',
|
||||
'column' => 'shipped_at',
|
||||
],
|
||||
];
|
||||
|
||||
public function getListWithFilters(array $filters, int $perPage): LengthAwarePaginator
|
||||
{
|
||||
// ... 필터/where 적용 ...
|
||||
|
||||
$sort = $this->resolveSortSpecWithRelated(
|
||||
$filters,
|
||||
self::SORTABLE_COLUMNS,
|
||||
self::RELATED_SORTABLE_COLUMNS,
|
||||
$this->model,
|
||||
'ordered_at',
|
||||
);
|
||||
|
||||
return $this->paginateWithDeferredJoin(
|
||||
query: $query,
|
||||
columns: self::LIST_COLUMNS,
|
||||
sort: $sort,
|
||||
perPage: $perPage,
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**집계 함수를 인자로 받지 않는 이유.** 서브쿼리를 정렬 방향과 같은 방향으로 정렬해 한 건만 취하면, `desc` 는 자연히 최댓값(가장 늦은 발송), `asc` 는 최솟값(가장 이른 발송)이 된다. 운영자가 "최근 발송순" 을 골랐을 때 기대하는 값과 일치하고, `MAX()`/`MIN()` 을 따로 지정하다 방향과 어긋나는 실수가 생기지 않는다.
|
||||
|
||||
**복합 인덱스는 선택이 아니다.** 서브쿼리는 목록 행마다 한 번씩 실행되므로 `(외래키, 정렬컬럼)` 인덱스가 없으면 행 수만큼 관계 테이블을 스캔한다. 외래키 단일 인덱스만 있으면 정렬 컬럼이 인덱스에 없어 매번 행을 읽어 정렬한다. 관계 정렬을 추가하는 변경에는 **인덱스 마이그레이션을 함께 넣는다.**
|
||||
|
||||
```php
|
||||
$table->index(['order_id', 'shipped_at'], 'ecommerce_order_shippings_order_id_shipped_at_index');
|
||||
```
|
||||
|
||||
정렬 스펙의 `column` 은 문자열 외에 `Builder`/`Expression` 도 올 수 있다. `PaginatesWithDeferredJoin` 이 이를 그대로 받아 inner/outer 양쪽에 적용한다 — 서브쿼리가 원 행의 키에 상관되므로 어느 쪽에 적용해도 같은 순서가 나오고, outer 에서는 이번 페이지 건수만큼만 실행된다. 키 컬럼은 전순서 보장을 위해 항상 마지막에 덧붙는다.
|
||||
|
||||
**게이트에도 함께 올린다.** `RELATED_SORTABLE_COLUMNS` 의 키는 FormRequest 의 `sort_by` 허용 목록에 들어가야 한다. `SortWhitelistGateParityTest` 가 두 상수를 합쳐 게이트 ⊆ 저장소 불변식을 검사한다.
|
||||
|
||||
### 예외
|
||||
|
||||
설정/정의성 테이블처럼 행 수가 고정이고 넓은 컬럼이 없으면 컬럼 목록 없이 페이지네이션해도 된다. 다만 그 판단 근거를 코드 옆에 남긴다.
|
||||
@@ -982,12 +1115,73 @@ return $this->model->newQuery()
|
||||
|
||||
다만 `columns:` 자체를 생략하면 outer 가 무엇을 읽는지 호출처에서 드러나지 않으므로 항상 명시한다. `DeferredJoinCallSiteContractTest` 가 호출처를 스캔해 `columns:`/`sort:` 명시 여부를 전수 검사한다.
|
||||
|
||||
### 페이지네이션 정렬의 전순서 보장
|
||||
|
||||
페이지네이션 목록의 정렬은 **고유 키로 닫는다**. 정렬이 비고유 컬럼만으로 끝나면 동률 구간의
|
||||
행 순서가 페이지마다 달라질 수 있고(SQL 표준은 동률의 순서를 보장하지 않는다), 그 결과
|
||||
**인접 페이지가 같은 행을 중복 노출하면서 다른 행은 어느 페이지에도 나오지 않는다.**
|
||||
|
||||
```php
|
||||
// ❌ created_at 동률 구간에서 페이지 경계가 흔들린다
|
||||
$query->orderBy('created_at', 'desc')->paginate($perPage);
|
||||
|
||||
// ✅ 정렬 마지막에 기본키를 덧붙여 전순서를 만든다
|
||||
$query->orderBy('created_at', 'desc')->orderBy('id', 'desc')->paginate($perPage);
|
||||
```
|
||||
|
||||
`ResolvesSortSpec` / `PaginatesWithDeferredJoin` 를 경유하는 목록은 트레이트가 키 컬럼을 자동으로
|
||||
덧붙이므로 이 규율을 이미 만족한다. 손으로 `orderBy` 를 조립한 뒤 `paginate()` 하는 지점만
|
||||
위험하다.
|
||||
|
||||
동률은 드문 일이 아니다 — 시더·일괄 등록·대량 마이그레이션은 여러 행에 같은 `created_at` 을
|
||||
남긴다(#492 실측: `roles.created_at` 한 타임스탬프에 최대 10행, 110건 목록에서 고유 키 109개).
|
||||
|
||||
판정은 눈으로 하지 않는다. 전 페이지를 순회해 키를 모으고 **합집합 크기 = 총건수**, 인접 페이지
|
||||
교집합 = ∅ 를 확인한다.
|
||||
|
||||
### 필요한 색인은 선언에서 도출한다
|
||||
|
||||
지연 조인은 inner 가 키 컬럼만 읽게 만들지만, 그 inner 가 **인덱스 순서 그대로** 끝나야 깊은 OFFSET 이 싸진다. 정렬을 덮는 색인이 없으면 inner 도 filesort 로 전체를 훑으므로 개선 폭이 사라진다. 즉 지연 조인과 색인은 함께 가야 하며, 한쪽만 해두면 화면에서는 "여전히 뒤로 갈수록 느리다" 로만 드러난다.
|
||||
|
||||
어떤 색인이 필요한지는 계측 프로파일 선언에 이미 들어 있다. `filters` · `order` · `soft_delete` 를 이으면 그대로 레시피가 된다:
|
||||
|
||||
```text
|
||||
(등치 필터 컬럼들 → soft_delete 면 deleted_at → 정렬 컬럼들 → 기본키)
|
||||
```
|
||||
|
||||
`App\Benchmark\ListIndexAdvisor` 가 이 도출을 담당하고, `ListIndexCoverageTest` 가 전 목록을 검사한다. **새 목록이 프로파일을 선언하면 필요한 색인이 자동으로 검사 대상이 되므로**, 색인 설계를 테이블마다 손으로 반복하지 않아도 된다.
|
||||
|
||||
| 판정 | 뜻 | 처방 |
|
||||
| ------ | ------ | ------ |
|
||||
| `satisfied` | 도출한 선행 컬럼을 그대로 덮는 색인이 있다 | — |
|
||||
| `tiebreak_missing` | 색인이 정렬 컬럼에서 끝나 동률 구간에 filesort 가 남는다 | 기존 색인 끝에 기본키를 덧붙여 **교체** (좌측 프리픽스라 남기면 쓰기 비용만 늘어난다) |
|
||||
| `missing` | 정렬을 덮는 색인이 없다 | 도출한 순서대로 색인 신설 |
|
||||
|
||||
주의할 점 둘.
|
||||
|
||||
- **등치가 아닌 필터는 선행 컬럼이 될 수 없다.** `in` / `not in` / 범위 조건은 그 지점에서 등치 사슬을 끊으므로 뒤따르는 정렬 컬럼을 인덱스 순서로 쓸 수 없다. 이 판정을 틀리면 "색인이 있는데도 filesort" 라는, 눈으로는 구분되지 않는 상태를 정상으로 보고하게 된다.
|
||||
- **UNIQUE 색인은 기본키를 덧붙일 필요가 없다.** 값이 중복되지 않아 그 컬럼만으로 이미 전순서다.
|
||||
|
||||
색인이 불필요한 목록(행 수가 고정이거나 상한이 작은 정의성 데이터)은 프로파일에 사유와 함께 면제를 선언한다. 사유 없는 면제를 받지 않는 이유는, 면제가 쌓이면 검사 자체가 무의미해지는데 사유가 없으면 그 판단이 여전히 옳은지 나중에 확인할 방법이 없기 때문이다.
|
||||
|
||||
```php
|
||||
'index_exempt' => '페이지는 사이트 구조를 구성하는 정의성 데이터라 ... 수천을 넘기 시작하면 (created_at, id) 색인을 추가할 것.',
|
||||
```
|
||||
|
||||
모듈/플러그인 프로파일은 **그 확장의 테스트 스위트에서** 검사한다. 확장 테이블은 그 스위트에서만 마이그레이션되므로 코어 스위트에 몰면 테이블이 없어 건너뛰고 초록인 채 미검사가 된다. 같은 이유로 "테이블이 없으면 skip" 도 하지 않고 실패로 보고한다.
|
||||
|
||||
### 정적 검사 대상
|
||||
|
||||
| 검출 대상 | 처리 |
|
||||
|---|---|
|
||||
| `->paginate($perPage)` / `->paginate($perPage, ['*'])` — 컬럼 목록 미지정 또는 전체 컬럼 | 차단 |
|
||||
| 요청 값에서 온 정렬 컬럼을 닫힌 집합 검증 없이 `orderBy` 에 전달 | 차단 |
|
||||
| 페이지네이션 정렬이 비고유 컬럼으로만 끝남 (기본키 타이브레이크 부재) | 차단 |
|
||||
| 그룹 쿼리의 총 건수를 `count()` 로 계산 (`getCountForPagination()` 필요) | 차단 |
|
||||
| 요청 값에서 온 정렬 컬럼을 닫힌 집합 검증 없이 `orderBy` 에 전달 | 경고 |
|
||||
|
||||
검사 범위는 `app/Repositories/**`, `modules|plugins/_bundled/**/Repositories/**` 와 컨트롤러 3계열이다. 미수정 파일까지 확인하려면 변경분이 아니라 저장소 전체를 대상으로 검사한다 — 변경 파일만 보는 방식으로는 이미 저장소에 있던 위반이 드러나지 않는다.
|
||||
|
||||
호출 계약 중 `relations:` 항목은 정적 룰이 아니라 테스트(`DeferredJoinCallSiteContractTest`)가 검사한다. 쿼리에 `with()` 를 붙이고 `relations:` 를 넘기지 않으면 관계가 조용히 사라지는데, 이 실패는 예외도 쿼리 오류도 내지 않아 관계 필드를 단언하지 않는 HTTP 테스트는 전부 통과한다.
|
||||
|
||||
검사 범위는 `app/Repositories/**`, `modules|plugins/_bundled/**/Repositories/**` 와 컨트롤러 3계열이다. 미수정 파일까지 확인하려면 변경분이 아니라 저장소 전체를 대상으로 검사한다 — 변경 파일만 보는 방식으로는 이미 저장소에 있던 위반이 드러나지 않는다.
|
||||
|
||||
|
||||
@@ -14,6 +14,8 @@
|
||||
5. 훅 확장: HookManager::applyFilters()로 동적 규칙 추가
|
||||
6. 필수: Rule::exists(Model::class, 'col') 사용 (문자열 테이블명 사용 금지)
|
||||
7. 런타임 조건부 검증: 드라이버/모드별 분기 시 메서드 추출 패턴 사용
|
||||
8. Store/Update 조건부 규칙은 대칭 — 한쪽 누락 시 과잉 검증(수정 실패) 또는 검증 우회
|
||||
9. min/size 가 붙은 필드는 required_if 로 조건부화 불가 → exclude_if (조건 필드가 nullable 이면 exclude_unless)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -26,6 +28,9 @@
|
||||
- [prepareForValidation() 데이터 전처리](#prepareforvalidation-데이터-전처리)
|
||||
- [훅 기반 동적 Validation Rules 확장](#훅-기반-동적-validation-rules-확장)
|
||||
- [런타임 조건부 Validation Rules (드라이버/모드별 분기)](#런타임-조건부-validation-rules-드라이버모드별-분기)
|
||||
- [조건부 Validation 원칙](#조건부-validation-원칙)
|
||||
- [`exclude_if` vs `exclude_unless` — 조건 필드가 nullable 일 때](#exclude_if-vs-exclude_unless--조건-필드가-nullable-일-때)
|
||||
- [조건 필드가 요청에 없을 때 — 저장값 주입](#조건-필드가-요청에-없을-때--저장값-주입)
|
||||
- [권한 체크 방식](#권한-체크-방식)
|
||||
- [Custom Rule 검증 메시지 다국어 처리](#custom-rule-검증-메시지-다국어-처리)
|
||||
- [다국어 필드 검증 규칙](#다국어-필드-검증-규칙)
|
||||
@@ -34,6 +39,7 @@
|
||||
- [exists/unique 검증 규칙](#existsunique-검증-규칙)
|
||||
- [계층 리소스 순환 참조](#계층-리소스-순환-참조)
|
||||
- [배열 항목의 상위 스코프](#배열-항목의-상위-스코프)
|
||||
- [관대한 기존 동작을 규칙으로 승격하지 않는다](#관대한-기존-동작을-규칙으로-승격하지-않는다)
|
||||
- [Custom Rule 개발 체크리스트](#custom-rule-개발-체크리스트)
|
||||
|
||||
---
|
||||
@@ -1151,6 +1157,61 @@ Service 에도 동일한 검증을 두어 FormRequest 를 우회한 내부/훅
|
||||
|
||||
---
|
||||
|
||||
## 관대한 기존 동작을 규칙으로 승격하지 않는다
|
||||
|
||||
컨트롤러가 base `Request` 를 주입받던 코드를 FormRequest 로 옮길 때, 그 컨트롤러가 하던 일이
|
||||
**거부**였는지 **수용**이었는지 먼저 읽는다. 수용하던 동작(클램핑·폴백·별칭 매핑)을 `rules()` 로
|
||||
올리면 200 이던 응답이 422 가 된다. 위반을 없애는 것이 목적이지 계약을 바꾸는 것이 아니다.
|
||||
|
||||
```php
|
||||
// 원본 컨트롤러 — 상한 초과를 거부하지 않고 상한까지 반환한다
|
||||
$limit = min((int) $request->input('limit', 20), 50);
|
||||
|
||||
// ❌ 규칙으로 승격 — `?limit=100` 이 200 → 422 (기존 링크·북마크가 깨진다)
|
||||
public function rules(): array
|
||||
{
|
||||
return ['limit' => ['nullable', 'integer', 'max:50']];
|
||||
}
|
||||
|
||||
// ✅ 규칙은 타입만 닫고, 상한은 접근자가 클램프한다
|
||||
public function rules(): array
|
||||
{
|
||||
return ['limit' => ['nullable', 'integer', 'min:0']];
|
||||
}
|
||||
|
||||
public function limit(): int
|
||||
{
|
||||
return min((int) $this->validated('limit', 20), self::MAX_LIMIT);
|
||||
}
|
||||
```
|
||||
|
||||
같은 원칙이 어휘에도 적용된다. 저장소가 미지원 값을 기본 분기로 처리해 왔다면 `Rule::in` 으로
|
||||
막는 순간 그 값을 담은 URL 이 전부 깨진다. 어휘를 닫아야 할 별도 이유(예: 요청 값이 캐시 키에
|
||||
그대로 들어가 키 공간이 무한히 늘어남)가 있어도, **접근자가 닫힌 집합만 반환**하게 하면 응답
|
||||
계약을 건드리지 않고 목적을 달성한다.
|
||||
|
||||
```php
|
||||
// ✅ 응답은 종전과 동일(미지원 값 → year), 캐시 키만 정규화된다
|
||||
public function period(): string
|
||||
{
|
||||
$period = $this->validated('period');
|
||||
|
||||
if ($period === null || $period === '') {
|
||||
return self::DEFAULT_PERIOD;
|
||||
}
|
||||
|
||||
return in_array((string) $period, self::RESOLVED_PERIODS, true) ? (string) $period : 'year';
|
||||
}
|
||||
```
|
||||
|
||||
`Rule::in` 승격이 적절한 경우는 **입력원이 화면 컨트롤 하나뿐**일 때다 — 관리자 DataGrid 의 필터
|
||||
select 처럼 사용자가 URL 을 손으로 만들 일이 없는 면. 판정 기준은 "북마크 가능한 공개 경로인가".
|
||||
|
||||
기존 테스트가 이 전환에서 RED 가 되면 그 테스트가 무엇을 고정하고 있는지 먼저 읽는다. 리팩토링에서
|
||||
테스트가 깨질 때의 기본 해석은 "테스트가 낡았다" 가 아니라 "계약을 바꿨다" 이다.
|
||||
|
||||
---
|
||||
|
||||
## Custom Rule 개발 체크리스트
|
||||
|
||||
- [ ] `/lang/ko/validation.php`에 한국어 메시지 추가
|
||||
|
||||
@@ -108,6 +108,31 @@ vendor/bin/pint --dirty
|
||||
|
||||
---
|
||||
|
||||
## 목록 조회 (컬럼 프루닝 · 지연 조인)
|
||||
|
||||
```php
|
||||
// 계속 쌓이는 목록 = 지연 조인. 정렬 컬럼이 요청 값이면 닫힌 집합으로 해석.
|
||||
use App\Repositories\Concerns\{PaginatesWithDeferredJoin, ResolvesSortSpec};
|
||||
|
||||
return $this->paginateWithDeferredJoin(
|
||||
query: $query, // 필터/where 만. orderBy·with·select 금지
|
||||
columns: self::LIST_COLUMNS, // ['*'] 도 위반 아님
|
||||
sort: $this->resolveSortSpec($filters, self::SORTABLE_COLUMNS, 'created_at'),
|
||||
perPage: $perPage,
|
||||
relations: ['user'], // 관계는 반드시 이 인자로 (with() 는 지워진다)
|
||||
);
|
||||
```
|
||||
|
||||
| 함정 | 결과 |
|
||||
| ------ | ------ |
|
||||
| `$query->with()` 만 하고 `relations:` 생략 | 관계가 조용히 사라짐 — 예외·오류 없음 |
|
||||
| `SUBSTRING(content,1,N)` 을 inner 에 둠 | 오버플로 페이지 읽기 그대로 발생 (프루닝 아님) |
|
||||
| 정렬을 비고유 컬럼으로만 끝냄 | 페이지 경계에서 행 중복·누락 (trait 이 PK 자동 append) |
|
||||
|
||||
상세: [service-repository.md](backend/service-repository.md#목록-조회-컬럼-프루닝과-지연-조인)
|
||||
|
||||
---
|
||||
|
||||
## 마이그레이션
|
||||
|
||||
```bash
|
||||
|
||||
@@ -75,9 +75,9 @@ injection 또는 modals/data_sources/scripts/init_actions 보유, EP: 병합할
|
||||
필수: Layout Extension 시스템을 통한 동적 UI 주입
|
||||
필수: 모듈 비활성화 시 관련 UI 자동 숨김
|
||||
✅ 필수: 확장 컴포넌트에 ExtensionBadge 표시 (관리자 UI)
|
||||
필수: 플러그인은 완전한 레이아웃 등록 불가 → 확장 지점(layout_extensions)만 사용
|
||||
(예외: settings.json 환경설정 레이아웃은 registerPluginLayouts()로 등록)
|
||||
필수: 모듈만 완전한 레이아웃 등록 가능 (admin/user 모두)
|
||||
필수: 플러그인이 자기 화면을 가질 때 라우트는 plugins/{identifier}/ 네임스페이스 안에 선언
|
||||
(다른 확장이 소유한 경로를 선언하면 설치 순서에 따라 화면이 조용히 바뀐다)
|
||||
필수: 다른 확장의 화면에 UI 를 끼워 넣을 때는 확장 지점(layout_extensions) 사용
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -7,8 +7,8 @@
|
||||
## TL;DR (5초 요약)
|
||||
|
||||
```text
|
||||
1. 백엔드: /lang/{locale}/*.php → __('vendor-module::key')
|
||||
2. 프론트엔드: /resources/lang/{locale}.json → $t:key
|
||||
1. 백엔드: /src/lang/{locale}/*.php → __('vendor-module::key') — 이 경로만 로드된다
|
||||
2. 프론트엔드: /resources/lang/{locale}.json → $t:key (resources/lang 아래 *.php 는 미로드)
|
||||
3. JSON에 moduleIdentifier 포함 금지! (자동 병합됨)
|
||||
4. 지원 언어: ko, en 필수
|
||||
5. 키 충돌 방지: 모듈별 고유 prefix 사용 권장
|
||||
@@ -36,9 +36,18 @@
|
||||
|
||||
| 구분 | 파일 경로 | 형식 | 사용처 |
|
||||
|------|----------|------|--------|
|
||||
| 백엔드 | `/lang/{locale}/*.php` | PHP 배열 | Laravel `__()` 함수 |
|
||||
| 백엔드 | `/src/lang/{locale}/*.php` | PHP 배열 | Laravel `__()` 함수 |
|
||||
| 프론트엔드 | `/resources/lang/{locale}.json` | JSON | 레이아웃 JSON `$t:` 문법 |
|
||||
|
||||
> 모듈의 백엔드 다국어는 `src/lang` **한 곳**이다. `TranslationServiceProvider` 가 그 경로만
|
||||
> 등록하고, 확장 설치 검증(`ValidatesTranslationPath`)도 같은 경로를 강제한다. 언어팩 시스템
|
||||
> (`LanguagePackService` · `LanguagePackServiceProvider`) 도 같은 경로를 스캔한다.
|
||||
>
|
||||
> `resources/lang/{locale}/*.php` 에 백엔드 문구를 두면 **아무도 읽지 않는다** — 화면에는
|
||||
> `src/lang` 값이 나오고, 그 파일을 고쳐도 반영되지 않으며, 그 사실이 화면에 드러나지 않는다.
|
||||
> `resources/lang` 아래에서 유효한 것은 프런트엔드용 `{locale}.json` 과 `partial/{locale}/*.json`
|
||||
> 뿐이다. (플러그인은 `lang/{locale}/*.php`, 템플릿은 `lang/{locale}.json` 이 각각 그 자리다.)
|
||||
|
||||
> **코어 자체 다국어 자원도 동일 구조** — 코어는 `lang/{ko,en}/*.php` (백엔드) +
|
||||
> `lang/{ko,en}.json` (+ `lang/partial/{ko,en}/*.json`) (프론트엔드) 를 사용한다.
|
||||
> 모듈/플러그인/템플릿/코어 모두 같은 디렉토리 구조와 $partial 디렉티브 메커니즘을
|
||||
|
||||
@@ -1040,19 +1040,25 @@ $response = Http::withToken($token)
|
||||
// 변경 시에만 캐시 갱신
|
||||
```
|
||||
|
||||
#### 6. 레이아웃 제한 (Layout Restriction)
|
||||
#### 6. 레이아웃 소유와 라우트 네임스페이스 (Layout Ownership)
|
||||
|
||||
플러그인은 모듈과 달리 완전한 레이아웃을 등록할 수 없습니다.
|
||||
플러그인도 자기 화면(완전한 레이아웃)을 가질 수 있습니다. 다만 그 화면의 라우트는
|
||||
플러그인 네임스페이스 안에 선언해야 합니다.
|
||||
|
||||
```text
|
||||
필수: 페이지 레이아웃은 모듈만 등록 가능 (플러그인은 layout_extensions만 사용)
|
||||
허용: admin/plugin_settings.json (환경설정 UI) — 유일한 완전 레이아웃
|
||||
✅ 필수: 설정 외 UI 확장은 layout_extensions(확장 지점/Overlay)로만 가능
|
||||
필수: 플러그인이 소유하는 화면의 라우트는 plugins/{identifier}/ 아래에 선언
|
||||
예) "*/admin/plugins/sirsoft-gdpr/consent-log"
|
||||
필수: 다른 확장이 소유한 화면에 UI 를 끼워 넣을 때는 layout_extensions(확장 지점/Overlay) 사용
|
||||
```
|
||||
|
||||
라우트 네임스페이스를 지키지 않으면, 같은 경로를 소유한 모듈/템플릿과 어느 쪽이 이기는지가
|
||||
설치 순서에 좌우됩니다. 화면이 조용히 다른 것으로 바뀌고, 어느 확장 때문인지 화면만 봐서는
|
||||
알 수 없습니다. 정적 검사가 이 위반을 차단합니다.
|
||||
|
||||
| 방식 | 모듈 | 플러그인 |
|
||||
|------|------|---------|
|
||||
| 임의 페이지 레이아웃 (admin/user) | 가능 | 금지 |
|
||||
| 자기 네임스페이스 화면 (`plugins/{id}/...`) | 해당 없음 | 가능 |
|
||||
| 임의 경로 페이지 레이아웃 (`admin/users` 등) | 가능 | 금지 (경로 침범) |
|
||||
| admin/plugin_settings.json (환경설정) | 가능 | 가능 |
|
||||
| layout_extensions (확장 지점) | 가능 | 가능 |
|
||||
|
||||
|
||||
@@ -4,6 +4,18 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.9] - 2026-08-01
|
||||
|
||||
### Added
|
||||
|
||||
- 통신이 끊겼을 때 표시되는 네트워크 오류 안내 문구 일본어 번역 추가 — 종전에는 내부 식별 문구가 영문 그대로 노출됐습니다.
|
||||
|
||||
## [1.0.8] - 2026-08-01
|
||||
|
||||
### Added
|
||||
|
||||
- 검색 인덱스 점검·재생성(`search:index`) 화면 문구 일본어 번역 추가 — 판정 등급(정상/부분적/미반영/판정불가), 점검 결과 표, 재생성 확인·경고 문구가 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
|
||||
## [1.0.7] - 2026-07-22
|
||||
|
||||
### Added
|
||||
|
||||
@@ -14,4 +14,46 @@ return [
|
||||
'per_page_min' => 'ページあたりの項目数は1以上である必要があります。',
|
||||
'per_page_max' => 'ページあたりの項目数は最大100個まで可能です。',
|
||||
],
|
||||
'index' => [
|
||||
'status' => [
|
||||
'healthy' => '正常',
|
||||
'degraded' => '部分的',
|
||||
'stale' => 'インデックス未反映',
|
||||
'skipped' => '判定不可',
|
||||
],
|
||||
'no_maintainer' => '現在の検索エンジン(:driver)はインデックス点検を提供していません。エンジン提供元が点検機能を登録すると、この画面で併せて扱えます。',
|
||||
'unavailable' => '現在の検索エンジン(:driver)のインデックスを点検できません。',
|
||||
'no_targets' => '検索エンジン(:driver)に点検対象のインデックスがありません。',
|
||||
'driver_label' => '検索エンジン: :driver',
|
||||
'col' => [
|
||||
'index' => 'インデックス',
|
||||
'status' => '判定',
|
||||
'measurement' => '測定',
|
||||
],
|
||||
'counts' => '正常 :healthy · 部分的 :degraded · 未反映 :stale · 判定不可 :skipped (合計 :total)',
|
||||
'rebuild_targets' => '再生成対象 :count件',
|
||||
'rebuild_cost_warning' => '再生成中は対象インデックスがロックされるか再インデックスされます。稼働中のサイトではメンテナンス時間帯に実行してください。',
|
||||
'rebuild_confirm' => '上記のインデックスを再生成しますか?',
|
||||
'rebuild_after_bulk_confirm' => '一括アップデート後に検索インデックスを再生成しますか? (既定: いいえ — 稼働中であればメンテナンス時間帯に別途実行してください)',
|
||||
'rebuild_skipped' => '再生成をスキップします。',
|
||||
'stale_hint' => 'インデックスが未反映のものがあります。`php artisan search:index --repair` で再生成してください。',
|
||||
'stale_after_update' => 'インデックスが未反映の検索インデックスが :count 件あり、該当する検索が結果を返しません。',
|
||||
'rebuilt_item' => '再生成: :index',
|
||||
'rebuild_failed_item' => '再生成失敗: :index — :error',
|
||||
'still_stale_item' => '再生成後も未反映: :index',
|
||||
'degraded_hint' => '「部分的」はエンジンのトークン処理特性の可能性があるため、自動再生成の対象外です。必要であれば個別に確認してください。',
|
||||
'report' => [
|
||||
'nothing_to_do' => '点検 :count件 · 再生成対象なし',
|
||||
'rebuilt' => '点検 :inspected件 · 再生成 :repaired件 · 失敗 :failed件 · 残存 :remaining件',
|
||||
],
|
||||
'fulltext' => [
|
||||
'unsupported_driver' => '現在のDBドライバはFULLTEXTをサポートしていません (LIKE検索で動作し、点検対象はありません)。',
|
||||
'self_match' => ':found/:probed 行が自分自身を検出',
|
||||
'skip' => [
|
||||
'no_single_pk' => '単一カラムの主キーがないため、行単位の判定ができません',
|
||||
'no_rows' => 'インデックス対象カラムに内容がある行がありません',
|
||||
'no_tokens' => 'サンプル行から検索トークンを作成できません (内容が短すぎます)',
|
||||
],
|
||||
],
|
||||
],
|
||||
];
|
||||
|
||||
@@ -6,5 +6,6 @@
|
||||
"component_load_failed_with_name": "コンポーネント({componentName})の読み込みに失敗しました",
|
||||
"translation_load_failed": "多言語ファイルの読み込みに失敗しました",
|
||||
"translation_load_failed_with_locale": "{locale}多言語ファイルの読み込みに失敗しました",
|
||||
"template_init_error": "テンプレートエンジンの初期化中にエラーが発生しました"
|
||||
"template_init_error": "テンプレートエンジンの初期化中にエラーが発生しました",
|
||||
"network_request_failed": "リクエストを送信できませんでした。ネットワーク接続を確認してから再度お試しください。"
|
||||
}
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 core Japanese language pack (bundled)",
|
||||
"ja": "G7 コア 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.7",
|
||||
"version": "1.0.9",
|
||||
"license": "MIT",
|
||||
"scope": "core",
|
||||
"target_identifier": null,
|
||||
|
||||
@@ -4,6 +4,16 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.7] - 2026-07-31
|
||||
|
||||
### Added
|
||||
|
||||
- 상품 문의 처리가 실패했을 때 그 사유를 그대로 보여주는 안내 문구의 일본어 번역을 추가했습니다.
|
||||
|
||||
### Removed
|
||||
|
||||
- 어디에서도 사용하지 않는 안내 문구 11건의 일본어 번역을 정리했습니다. 한국어 원본이 실제 화면에 쓰이지 않는 위치에 있어 번역만 남아 있던 항목입니다.
|
||||
|
||||
## [1.0.6] - 2026-07-22
|
||||
|
||||
### Added
|
||||
|
||||
@@ -279,8 +279,6 @@ return [
|
||||
'select_items_message' => '商品を選択してください',
|
||||
'checkout' => '注文する',
|
||||
'continue_shopping' => 'ショッピングを続ける',
|
||||
'updated' => 'カートが修正されました。',
|
||||
'removed' => 'カートから削除されました。',
|
||||
'reorder_added' => '過去の注文の商品をカートに追加しました。',
|
||||
'reorder_failed' => '再注文に失敗しました。',
|
||||
'reorder_option_not_found' => '商品オプションはもう存在しません。',
|
||||
@@ -319,9 +317,6 @@ return [
|
||||
'invalid_target' => '当該商品には適用できないクーポンです。',
|
||||
'already_used' => '既に使用されたクーポンです。',
|
||||
'not_found' => 'クーポンが見つかりません。',
|
||||
'applied' => 'クーポンが適用されました。',
|
||||
'removed' => 'クーポンが解除されました。',
|
||||
'invalid' => '無効なクーポンです。',
|
||||
'per_user_limit_exceeded' => 'このクーポンの使用可能回数を超過しました。',
|
||||
],
|
||||
'mileage' => [
|
||||
@@ -1102,6 +1097,7 @@ return [
|
||||
'reply_deleted' => '回答が削除されました。',
|
||||
'reply_delete_failed' => '回答の削除に失敗しました。',
|
||||
'reply_not_found' => '回答が見つかりません。',
|
||||
'operation_failed_reason' => ':reason',
|
||||
],
|
||||
'address' => [
|
||||
'created' => '配送先が追加されました。',
|
||||
@@ -1121,15 +1117,8 @@ return [
|
||||
'name_duplicate' => '同じ名前の配送先が既に存在します。上書きしますか？',
|
||||
'auto_saved_label' => '新しい配送先',
|
||||
],
|
||||
'product' => [
|
||||
'not_found' => '商品が見つかりません。',
|
||||
'not_available' => '現在、購入できない商品です。',
|
||||
'option_not_found' => '商品オプションが見つかりません。',
|
||||
],
|
||||
'product' => [],
|
||||
'payment' => [
|
||||
'method_not_supported' => 'サポートされていない決済方法です。',
|
||||
'dbank_account_required' => '銀行振込の口座を選択してください。',
|
||||
'depositor_name_required' => '振込人名を入力してください。',
|
||||
'provider_not_found' => '決済プロバイダーが見つかりません。',
|
||||
'client_config_success' => '決済クライアント設定を取得しました。',
|
||||
],
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 module (sirsoft-ecommerce) Japanese language pack (bundled)",
|
||||
"ja": "G7 モジュール (sirsoft-ecommerce) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.6",
|
||||
"version": "1.0.7",
|
||||
"license": "MIT",
|
||||
"scope": "module",
|
||||
"target_identifier": "sirsoft-ecommerce",
|
||||
|
||||
@@ -4,10 +4,12 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.2] - 2026-07-29
|
||||
## [1.0.2] - 2026-08-01
|
||||
|
||||
### Added
|
||||
|
||||
- 동의 이력의 출처 "会員登録" / "マイページ一括再同意" 일본어 라벨 추가
|
||||
- 정책 버전 이력 페이지 이동(前へ / 次へ)과 총 건수 표시 일본어 번역 추가
|
||||
- 자동 차단 정책 카드에 보호 범위 한계 안내 문구(운영자가 직접 삽입한 외부 스크립트는 보호 범위 밖) 일본어 번역 추가
|
||||
|
||||
## [1.0.1] - 2026-07-27
|
||||
|
||||
@@ -140,6 +140,9 @@ return [
|
||||
'snapshot_action' => '本文',
|
||||
],
|
||||
],
|
||||
'history_page_summary' => '全 :total 件 · :current / :last ページ',
|
||||
'history_prev' => '前へ',
|
||||
'history_next' => '次へ',
|
||||
'snapshot_view_short' => '表示',
|
||||
'material_modal' => [
|
||||
'title' => 'ポリシーバージョン公開 + 再同意トリガー',
|
||||
@@ -197,7 +200,9 @@ return [
|
||||
'source' => [
|
||||
'banner' => 'バナー',
|
||||
'preference_center' => '環境設定',
|
||||
'register' => '会員登録',
|
||||
'mypage' => 'マイページ',
|
||||
'mypage_renew_all' => 'マイページ一括再同意',
|
||||
],
|
||||
'col' => [
|
||||
'created_at' => '時点',
|
||||
|
||||
@@ -201,7 +201,10 @@
|
||||
"open_policy_page": "本文ページを開く",
|
||||
"no_policy_slug": "登録されたポリシー本文ページがありません。"
|
||||
},
|
||||
"not_found": "そのポリシーバージョンが見つかりません。"
|
||||
"not_found": "そのポリシーバージョンが見つかりません。",
|
||||
"history_page_summary": "全体 {total}件 · {current} / {last} ページ",
|
||||
"history_prev": "前へ",
|
||||
"history_next": "次へ"
|
||||
}
|
||||
},
|
||||
"admin": {
|
||||
@@ -233,7 +236,9 @@
|
||||
"source": {
|
||||
"banner": "バナー",
|
||||
"preference_center": "環境設定",
|
||||
"mypage": "マイページ"
|
||||
"mypage": "マイページ",
|
||||
"register": "会員登録",
|
||||
"mypage_renew_all": "マイページ一括再同意"
|
||||
},
|
||||
"col": {
|
||||
"created_at": "時点",
|
||||
|
||||
@@ -4,6 +4,12 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [1.0.5] - 2026-08-01
|
||||
|
||||
### Added
|
||||
|
||||
- 확장 업데이트 모달의 「검색 인덱스 재생성」 선택 항목 문구 일본어 번역 추가 — 항목 이름과 설명(재생성 시 인덱스 잠금·재색인 안내)이 일본어 로케일에서 자연스럽게 표시됩니다.
|
||||
|
||||
## [1.0.4] - 2026-07-17
|
||||
|
||||
### Added
|
||||
|
||||
+4
-1
@@ -30,6 +30,9 @@
|
||||
"compat_warning_title": "コアバージョン互換性警告",
|
||||
"compat_warning_message": "この{{type}}はコア {{required}} 以上が必要です。(現在: {{installed}})",
|
||||
"compat_guide_link": "コアアップグレードガイドを表示",
|
||||
"force_label": "警告を無視して強制アップデート (推奨されません)"
|
||||
"force_label": "警告を無視して強制アップデート (推奨されません)",
|
||||
"rebuild_search_index_title": "検索インデックス",
|
||||
"rebuild_search_index_label": "アップデート後、インデックスが未反映の検索インデックスを再生成",
|
||||
"rebuild_search_index_desc": "再生成中は対象インデックスがロックされるか再インデックスされます。稼働中のサイトではチェックせず、メンテナンス時間帯に別途実行してください。"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"en": "G7 template (sirsoft-admin_basic) Japanese language pack (bundled)",
|
||||
"ja": "G7 テンプレート (sirsoft-admin_basic) 日本語 言語パック(バンドル)"
|
||||
},
|
||||
"version": "1.0.4",
|
||||
"version": "1.0.5",
|
||||
"license": "MIT",
|
||||
"scope": "template",
|
||||
"target_identifier": "sirsoft-admin_basic",
|
||||
|
||||
@@ -20,4 +20,54 @@ return [
|
||||
'per_page_min' => 'Items per page must be at least 1.',
|
||||
'per_page_max' => 'Items per page must not exceed 100.',
|
||||
],
|
||||
|
||||
// Search index inspection / rebuild (search:index) — engine neutral
|
||||
'index' => [
|
||||
'status' => [
|
||||
'healthy' => 'Healthy',
|
||||
'degraded' => 'Partial',
|
||||
'stale' => 'Not indexed',
|
||||
'skipped' => 'Not determinable',
|
||||
],
|
||||
|
||||
'no_maintainer' => 'The current search engine (:driver) does not provide index inspection. It will appear here once its provider registers one.',
|
||||
'unavailable' => 'The index of the current search engine (:driver) cannot be inspected.',
|
||||
'no_targets' => 'The search engine (:driver) has no index to inspect.',
|
||||
'driver_label' => 'Search engine: :driver',
|
||||
|
||||
'col' => [
|
||||
'index' => 'Index',
|
||||
'status' => 'Status',
|
||||
'measurement' => 'Measurement',
|
||||
],
|
||||
|
||||
'counts' => 'Healthy :healthy · Partial :degraded · Not indexed :stale · Not determinable :skipped (total :total)',
|
||||
'rebuild_targets' => ':count index(es) to rebuild',
|
||||
'rebuild_cost_warning' => 'Rebuilding locks or re-indexes the target. On a live site, run it during a maintenance window.',
|
||||
'rebuild_confirm' => 'Rebuild the indexes listed above?',
|
||||
'rebuild_after_bulk_confirm' => 'Rebuild search indexes after the bulk update? (default: no — on a live site, run it during a maintenance window)',
|
||||
'rebuild_skipped' => 'Skipping the rebuild.',
|
||||
'stale_hint' => 'Some indexes hold no indexed content. Rebuild them with `php artisan search:index --repair`.',
|
||||
'stale_after_update' => ':count search index(es) hold no indexed content, so those searches return nothing.',
|
||||
'rebuilt_item' => 'Rebuilt: :index',
|
||||
'rebuild_failed_item' => 'Rebuild failed: :index — :error',
|
||||
'still_stale_item' => 'Still not indexed after rebuild: :index',
|
||||
'degraded_hint' => '"Partial" may come from the engine tokenizer, so it is not rebuilt automatically. Inspect individually if needed.',
|
||||
|
||||
'report' => [
|
||||
'nothing_to_do' => 'Inspected :count · nothing to rebuild',
|
||||
'rebuilt' => 'Inspected :inspected · rebuilt :repaired · failed :failed · still stale :remaining',
|
||||
],
|
||||
|
||||
// mysql-fulltext driver specific
|
||||
'fulltext' => [
|
||||
'unsupported_driver' => 'The current database driver does not support FULLTEXT (search falls back to LIKE; nothing to inspect).',
|
||||
'self_match' => ':found/:probed rows found themselves',
|
||||
'skip' => [
|
||||
'no_single_pk' => 'No single-column primary key, so per-row inspection is not possible',
|
||||
'no_rows' => 'No row has content in the indexed columns',
|
||||
'no_tokens' => 'Could not build a search token from the sampled rows (content too short)',
|
||||
],
|
||||
],
|
||||
],
|
||||
];
|
||||
@@ -20,4 +20,54 @@ return [
|
||||
'per_page_min' => '페이지당 항목 수는 1 이상이어야 합니다.',
|
||||
'per_page_max' => '페이지당 항목 수는 최대 100개까지 가능합니다.',
|
||||
],
|
||||
|
||||
// 검색 인덱스 점검·재생성 (search:index) — 엔진 중립
|
||||
'index' => [
|
||||
'status' => [
|
||||
'healthy' => '정상',
|
||||
'degraded' => '부분',
|
||||
'stale' => '색인 누락',
|
||||
'skipped' => '판정 불가',
|
||||
],
|
||||
|
||||
'no_maintainer' => '현재 검색 엔진(:driver)은 인덱스 점검을 제공하지 않습니다. 엔진 제공자가 점검 기능을 등록하면 이 화면에서 함께 다룹니다.',
|
||||
'unavailable' => '현재 검색 엔진(:driver)의 인덱스를 점검할 수 없습니다.',
|
||||
'no_targets' => '검색 엔진(:driver)에 점검할 인덱스가 없습니다.',
|
||||
'driver_label' => '검색 엔진: :driver',
|
||||
|
||||
'col' => [
|
||||
'index' => '인덱스',
|
||||
'status' => '판정',
|
||||
'measurement' => '측정',
|
||||
],
|
||||
|
||||
'counts' => '정상 :healthy · 부분 :degraded · 색인누락 :stale · 판정불가 :skipped (총 :total)',
|
||||
'rebuild_targets' => '재생성 대상 :count개',
|
||||
'rebuild_cost_warning' => '재생성 중에는 대상 인덱스가 잠기거나 재색인됩니다. 운영 중인 사이트에서는 유지보수 시간에 수행하세요.',
|
||||
'rebuild_confirm' => '위 인덱스를 재생성할까요?',
|
||||
'rebuild_after_bulk_confirm' => '일괄 업데이트 후 검색 인덱스를 재생성할까요? (기본: 아니오 — 운영 중이면 유지보수 시간에 별도로 수행하세요)',
|
||||
'rebuild_skipped' => '재생성을 건너뜁니다.',
|
||||
'stale_hint' => '색인이 누락된 인덱스가 있습니다. `php artisan search:index --repair` 로 재생성하세요.',
|
||||
'stale_after_update' => '색인이 누락된 검색 인덱스 :count개가 있어 해당 검색이 결과를 돌려주지 않습니다.',
|
||||
'rebuilt_item' => '재생성: :index',
|
||||
'rebuild_failed_item' => '재생성 실패: :index — :error',
|
||||
'still_stale_item' => '재생성 후에도 색인 누락: :index',
|
||||
'degraded_hint' => '「부분」 은 엔진의 토큰 처리 특성일 수 있어 자동 재생성 대상이 아닙니다. 필요하면 개별 확인하세요.',
|
||||
|
||||
'report' => [
|
||||
'nothing_to_do' => '점검 :count개 · 재생성 대상 없음',
|
||||
'rebuilt' => '점검 :inspected개 · 재생성 :repaired개 · 실패 :failed개 · 잔존 :remaining개',
|
||||
],
|
||||
|
||||
// mysql-fulltext 드라이버 전용 문구
|
||||
'fulltext' => [
|
||||
'unsupported_driver' => '현재 DB 드라이버는 FULLTEXT 를 지원하지 않습니다 (LIKE 검색으로 동작하며 점검 대상이 없습니다).',
|
||||
'self_match' => ':found/:probed 행이 자기 자신을 찾음',
|
||||
'skip' => [
|
||||
'no_single_pk' => '단일 컬럼 기본키가 없어 행 단위 판정을 할 수 없습니다',
|
||||
'no_rows' => '색인 컬럼에 내용이 있는 행이 없습니다',
|
||||
'no_tokens' => '표본 행에서 검색 토큰을 만들 수 없습니다 (내용이 너무 짧음)',
|
||||
],
|
||||
],
|
||||
],
|
||||
];
|
||||
@@ -6,5 +6,6 @@
|
||||
"component_load_failed_with_name": "Failed to load component ({componentName})",
|
||||
"translation_load_failed": "Failed to load translation file",
|
||||
"translation_load_failed_with_locale": "Failed to load {locale} translation file",
|
||||
"template_init_error": "An error occurred while initializing the template engine"
|
||||
"template_init_error": "An error occurred while initializing the template engine",
|
||||
"network_request_failed": "The request could not be sent. Check your network connection and try again."
|
||||
}
|
||||
|
||||
@@ -6,5 +6,6 @@
|
||||
"component_load_failed_with_name": "컴포넌트({componentName})를 불러오는데 실패했습니다",
|
||||
"translation_load_failed": "다국어 파일을 불러오는데 실패했습니다",
|
||||
"translation_load_failed_with_locale": "{locale} 다국어 파일을 불러오는데 실패했습니다",
|
||||
"template_init_error": "템플릿 엔진을 초기화하는 중 오류가 발생했습니다"
|
||||
"template_init_error": "템플릿 엔진을 초기화하는 중 오류가 발생했습니다",
|
||||
"network_request_failed": "요청을 보내지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요."
|
||||
}
|
||||
|
||||
@@ -4,11 +4,19 @@
|
||||
형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 따르며,
|
||||
[Semantic Versioning](https://semver.org/lang/ko/)을 준수합니다.
|
||||
|
||||
## [0.1.1] - 2026-07-31
|
||||
|
||||
### Fixed
|
||||
|
||||
- 관리자 메모 목록 화면에 메모가 하나도 보이지 않던 문제를 수정했습니다. 화면이 부르는 주소와 실제로 열려 있는 주소가 달라 목록을 받아오지 못하고 있었습니다.
|
||||
- 메모 목록에서 한 페이지에 보여줄 개수를 0·음수·과도하게 큰 값으로 요청하면 오류가 나거나 메모 전체가 한 번에 조회되던 문제를 수정했습니다. 1~100 범위를 벗어나면 요청이 거부됩니다.
|
||||
|
||||
## [0.1.0] - 2026-07-01
|
||||
|
||||
### Fixed
|
||||
|
||||
- 메모 목록에서 작성·수정 화면에 다녀오면 보고 있던 페이지가 사라지고 1페이지로 되돌아가던 문제를 수정했습니다. (#75 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 메모 목록에서 같은 시각에 등록된 메모가 여러 건일 때 페이지를 넘기면 같은 메모가 두 번 보이던 문제를 수정했습니다.
|
||||
|
||||
### Changed
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
"name": "modules/gnuboard7-hello_module",
|
||||
"description": "Hello sample module for Gnuboard7 (learning purpose)",
|
||||
"type": "library",
|
||||
"version": "0.1.0",
|
||||
"version": "0.1.1",
|
||||
"license": "MIT",
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
|
||||
@@ -4,11 +4,11 @@
|
||||
> 아래 표는 자동 생성됩니다. 각 문서를 열면 엔드포인트별 파라미터·응답·예시를 볼 수 있습니다.
|
||||
|
||||
<!-- @generated:start:api-readme-index -->
|
||||
- **문서 수**: 1 · **엔드포인트 수**: 2
|
||||
- **문서 수**: 1 · **엔드포인트 수**: 7
|
||||
|
||||
| 문서 | 도메인 | 엔드포인트 |
|
||||
| --- | --- | --- |
|
||||
| [memos.md](memos.md) | `memos` | 2 |
|
||||
| [memos.md](memos.md) | `memos` | 7 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
|
||||
@@ -8,8 +8,8 @@
|
||||
|
||||
```text
|
||||
1. 이 문서는 실제 API 호출로 실측한 Memos 엔드포인트 레퍼런스입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
|
||||
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
|
||||
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
|
||||
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
|
||||
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
|
||||
5. 설명(TODO) 칸은 사람이 채웁니다
|
||||
```
|
||||
@@ -17,6 +17,233 @@
|
||||
---
|
||||
|
||||
|
||||
### GET /api/modules/gnuboard7-hello_module/admin/memos
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.admin.memos.index -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.admin.memos.index`
|
||||
- **컨트롤러**: `Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@index`
|
||||
- **인증/권한**: `auth:sanctum` + `permission:gnuboard7-hello_module.memos.read`
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/gnuboard7-hello_module/admin/memos?page=1&per_page=1 HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`gnuboard7-hello_module.memos.read`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** <!-- TODO: 이 엔드포인트의 용도·주의사항·예시 시나리오를 작성하세요 -->
|
||||
|
||||
|
||||
### POST /api/modules/gnuboard7-hello_module/admin/memos
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.admin.memos.store -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.admin.memos.store`
|
||||
- **컨트롤러**: `Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@store`
|
||||
- **인증/권한**: `auth:sanctum` + `permission:gnuboard7-hello_module.memos.create`
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| title | body | string | 예 | max 255 | 제목 |
|
||||
| content | body | string | 예 | — | 본문 내용 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
POST /api/modules/gnuboard7-hello_module/admin/memos HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"title": "예시 제목",
|
||||
"content": "예시 내용입니다."
|
||||
}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: http-403 — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`gnuboard7-hello_module.memos.create`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** <!-- TODO: 이 엔드포인트의 용도·주의사항·예시 시나리오를 작성하세요 -->
|
||||
|
||||
|
||||
### DELETE /api/modules/gnuboard7-hello_module/admin/memos/{id}
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.admin.memos.destroy -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.admin.memos.destroy`
|
||||
- **컨트롤러**: `Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@destroy`
|
||||
- **인증/권한**: `auth:sanctum` + `permission:gnuboard7-hello_module.memos.delete`
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| id | path | string | 예 | — | 대상 리소스의 식별자 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
DELETE /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`gnuboard7-hello_module.memos.delete`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** <!-- TODO: 이 엔드포인트의 용도·주의사항·예시 시나리오를 작성하세요 -->
|
||||
|
||||
|
||||
### GET /api/modules/gnuboard7-hello_module/admin/memos/{id}
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.admin.memos.show -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.admin.memos.show`
|
||||
- **컨트롤러**: `Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@show`
|
||||
- **인증/권한**: `auth:sanctum` + `permission:gnuboard7-hello_module.memos.read`
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| id | path | string | 예 | — | 대상 리소스의 식별자 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`gnuboard7-hello_module.memos.read`)이 없는 경우 |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** <!-- TODO: 이 엔드포인트의 용도·주의사항·예시 시나리오를 작성하세요 -->
|
||||
|
||||
|
||||
### PUT /api/modules/gnuboard7-hello_module/admin/memos/{id}
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.admin.memos.update -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.admin.memos.update`
|
||||
- **컨트롤러**: `Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController@update`
|
||||
- **인증/권한**: `auth:sanctum` + `permission:gnuboard7-hello_module.memos.update`
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| id | path | string | 예 | — | 대상 리소스의 식별자 |
|
||||
| title | body | string | 예 | max 255 | 제목 |
|
||||
| content | body | string | 예 | — | 본문 내용 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
PUT /api/modules/gnuboard7-hello_module/admin/memos/{id} HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"title": "예시 제목",
|
||||
"content": "예시 내용입니다."
|
||||
}
|
||||
```
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
|
||||
| 403 | Forbidden | 요구 권한(`gnuboard7-hello_module.memos.update`)이 없는 경우 |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
| 404 | Not Found | path 파라미터에 해당하는 리소스가 없는 경우 |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** <!-- TODO: 이 엔드포인트의 용도·주의사항·예시 시나리오를 작성하세요 -->
|
||||
|
||||
|
||||
### GET /api/modules/gnuboard7-hello_module/memos
|
||||
<!-- @generated:start:api.modules.gnuboard7-hello_module.memos.index -->
|
||||
- **라우트명**: `api.modules.gnuboard7-hello_module.memos.index`
|
||||
@@ -25,12 +252,15 @@
|
||||
|
||||
**요청 파라미터**
|
||||
|
||||
_요청 파라미터 없음._
|
||||
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
|
||||
**요청 예시**
|
||||
|
||||
```http
|
||||
GET /api/modules/gnuboard7-hello_module/memos HTTP/1.1
|
||||
GET /api/modules/gnuboard7-hello_module/memos?page=1&per_page=1 HTTP/1.1
|
||||
Host: api.example.com
|
||||
Accept: application/json
|
||||
Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생략 가능)
|
||||
@@ -38,11 +268,78 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
**응답 필드** (`data` 내부)
|
||||
|
||||
<!-- 실측 제외: http-404 — 응답 필드는 사람이 작성하세요. -->
|
||||
_목록 응답: `data.data[]` 배열 항목의 필드._
|
||||
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| id | integer | `2` | 기본 키 (내부 식별자) |
|
||||
| uuid | string | `4473e9ee-ecdf-4ad0-afb3-78ada47265af` | 외부 노출용 UUID (URL/API 식별자, 내부 id 비노출) |
|
||||
| title | string | `두 번째 메모` | 제목 |
|
||||
| content | string | `Memo 엔티티의 CRUD 동작을 확인할 수 있는 추가 샘플입니다.` | 본문 내용 |
|
||||
| created_at | string | `2026-07-31 22:09:15` | 생성 일시 |
|
||||
| updated_at | string | `2026-07-31 22:09:15` | 최종 수정 일시 |
|
||||
| abilities | object | `{"can_create":false,"can_update":false,"can_delete":false}` | 현재 사용자가 이 리소스에 수행 가능한 작업 불리언 맵 (can_update, can_delete 등 — 권한 맵 기반) |
|
||||
|
||||
**응답 예시**
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "메모를 조회했습니다.",
|
||||
"data": {
|
||||
"data": [
|
||||
{
|
||||
"id": 2,
|
||||
"uuid": "4473e9ee-ecdf-4ad0-afb3-78ada47265af",
|
||||
"title": "두 번째 메모",
|
||||
"content": "Memo 엔티티의 CRUD 동작을 확인할 수 있는 추가 샘플입니다.",
|
||||
"created_at": "2026-07-31 22:09:15",
|
||||
"updated_at": "2026-07-31 22:09:15",
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"uuid": "86a29502-24cd-4124-a283-b0454d499fc1",
|
||||
"title": "환영합니다",
|
||||
"content": "Hello 모듈의 첫 번째 샘플 메모입니다. 학습용으로 제공됩니다.",
|
||||
"created_at": "2026-07-31 22:09:15",
|
||||
"updated_at": "2026-07-31 22:09:15",
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
},
|
||||
"... (총 25건 중 2건 표시)"
|
||||
],
|
||||
"meta": {
|
||||
"current_page": 1,
|
||||
"last_page": 2,
|
||||
"per_page": 25,
|
||||
"total": 34
|
||||
},
|
||||
"abilities": {
|
||||
"can_create": false,
|
||||
"can_update": false,
|
||||
"can_delete": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**에러 응답**
|
||||
|
||||
_대표 에러 없음 (공개 조회). <!-- TODO: 도메인 특이 에러가 있으면 보강 -->_
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
| --- | --- | --- |
|
||||
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (`error.errors` 에 필드별 메시지) |
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
@@ -96,6 +393,10 @@ Authorization: Bearer {YOUR_TOKEN} (optional.sanctum: 비회원은 헤더 생
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 필드는 사람이 작성하세요. -->
|
||||
|
||||
**응답 예시**
|
||||
|
||||
<!-- 실측 제외: unresolved-path-param — 응답 예시는 사람이 작성하세요. -->
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
"ko": "Hello 모듈",
|
||||
"en": "Hello Module"
|
||||
},
|
||||
"version": "0.1.0",
|
||||
"version": "0.1.1",
|
||||
"license": "MIT",
|
||||
"description": {
|
||||
"ko": "학습용 최소 샘플 모듈 (Memo CRUD)",
|
||||
|
||||
+3
-3
@@ -92,20 +92,20 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "memo_items",
|
||||
"id": "memo_items_{{idx}}",
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
"className": "row-stack"
|
||||
},
|
||||
"iteration": {
|
||||
"data": "{{memos?.data?.data ?? []}}",
|
||||
"source": "{{memos?.data?.data ?? []}}",
|
||||
"item_var": "memo",
|
||||
"index_var": "idx"
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"id": "memo_item",
|
||||
"id": "memo_item_{{idx}}",
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
|
||||
@@ -51,20 +51,20 @@
|
||||
"text": "$t:gnuboard7-hello_module.user.memos.index.title"
|
||||
},
|
||||
{
|
||||
"id": "user_memo_items",
|
||||
"id": "user_memo_items_{{idx}}",
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
"className": "space-y-3"
|
||||
},
|
||||
"iteration": {
|
||||
"data": "{{memos?.data?.data ?? []}}",
|
||||
"source": "{{memos?.data?.data ?? []}}",
|
||||
"item_var": "memo",
|
||||
"index_var": "idx"
|
||||
},
|
||||
"children": [
|
||||
{
|
||||
"id": "user_memo_item",
|
||||
"id": "user_memo_item_{{idx}}",
|
||||
"type": "basic",
|
||||
"name": "Div",
|
||||
"props": {
|
||||
|
||||
+8
-7
@@ -3,10 +3,11 @@
|
||||
namespace Modules\Gnuboard7\HelloModule\Http\Controllers\Admin;
|
||||
|
||||
use App\Http\Controllers\Api\Base\AdminBaseController;
|
||||
use Illuminate\Database\Eloquent\ModelNotFoundException;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Requests\Admin\StoreMemoRequest;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Requests\Admin\UpdateMemoRequest;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Requests\MemoListRequest;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Resources\MemoCollection;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Resources\MemoResource;
|
||||
use Modules\Gnuboard7\HelloModule\Services\MemoService;
|
||||
@@ -32,13 +33,13 @@ class MemoController extends AdminBaseController
|
||||
/**
|
||||
* 메모 목록을 조회합니다.
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param MemoListRequest $request 목록 조회 요청 (페이지네이션 상·하한 검증)
|
||||
* @return JsonResponse 메모 목록 응답
|
||||
*/
|
||||
public function index(Request $request): JsonResponse
|
||||
public function index(MemoListRequest $request): JsonResponse
|
||||
{
|
||||
try {
|
||||
$perPage = (int) $request->query('per_page', 10);
|
||||
$perPage = (int) ($request->validated()['per_page'] ?? 10);
|
||||
$memos = $this->memoService->getMemos($perPage);
|
||||
|
||||
return $this->success(
|
||||
@@ -65,7 +66,7 @@ class MemoController extends AdminBaseController
|
||||
'gnuboard7-hello_module::messages.memo.fetch_success',
|
||||
new MemoResource($memo)
|
||||
);
|
||||
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
|
||||
} catch (ModelNotFoundException) {
|
||||
return $this->notFound('gnuboard7-hello_module::messages.memo.not_found');
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('gnuboard7-hello_module::messages.memo.fetch_failed', 500, $e->getMessage());
|
||||
@@ -110,7 +111,7 @@ class MemoController extends AdminBaseController
|
||||
'gnuboard7-hello_module::messages.memo.update_success',
|
||||
new MemoResource($memo)
|
||||
);
|
||||
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
|
||||
} catch (ModelNotFoundException) {
|
||||
return $this->notFound('gnuboard7-hello_module::messages.memo.not_found');
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('gnuboard7-hello_module::messages.memo.update_failed', 500, $e->getMessage());
|
||||
@@ -130,7 +131,7 @@ class MemoController extends AdminBaseController
|
||||
$this->memoService->deleteMemo($memo);
|
||||
|
||||
return $this->success('gnuboard7-hello_module::messages.memo.delete_success');
|
||||
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
|
||||
} catch (ModelNotFoundException) {
|
||||
return $this->notFound('gnuboard7-hello_module::messages.memo.not_found');
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('gnuboard7-hello_module::messages.memo.delete_failed', 500, $e->getMessage());
|
||||
|
||||
@@ -3,8 +3,9 @@
|
||||
namespace Modules\Gnuboard7\HelloModule\Http\Controllers\Api;
|
||||
|
||||
use App\Http\Controllers\Api\Base\PublicBaseController;
|
||||
use Illuminate\Database\Eloquent\ModelNotFoundException;
|
||||
use Illuminate\Http\JsonResponse;
|
||||
use Illuminate\Http\Request;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Requests\MemoListRequest;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Resources\MemoCollection;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Resources\MemoResource;
|
||||
use Modules\Gnuboard7\HelloModule\Services\MemoService;
|
||||
@@ -30,13 +31,13 @@ class MemoController extends PublicBaseController
|
||||
/**
|
||||
* 메모 목록을 조회합니다.
|
||||
*
|
||||
* @param Request $request HTTP 요청
|
||||
* @param MemoListRequest $request 목록 조회 요청 (페이지네이션 상·하한 검증)
|
||||
* @return JsonResponse 메모 목록 응답
|
||||
*/
|
||||
public function index(Request $request): JsonResponse
|
||||
public function index(MemoListRequest $request): JsonResponse
|
||||
{
|
||||
try {
|
||||
$perPage = (int) $request->query('per_page', 10);
|
||||
$perPage = (int) ($request->validated()['per_page'] ?? 10);
|
||||
$memos = $this->memoService->getMemos($perPage);
|
||||
|
||||
return $this->success(
|
||||
@@ -63,7 +64,7 @@ class MemoController extends PublicBaseController
|
||||
'gnuboard7-hello_module::messages.memo.fetch_success',
|
||||
new MemoResource($memo)
|
||||
);
|
||||
} catch (\Illuminate\Database\Eloquent\ModelNotFoundException) {
|
||||
} catch (ModelNotFoundException) {
|
||||
return $this->notFound('gnuboard7-hello_module::messages.memo.not_found');
|
||||
} catch (\Exception $e) {
|
||||
return $this->error('gnuboard7-hello_module::messages.memo.fetch_failed', 500, $e->getMessage());
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
<?php
|
||||
|
||||
namespace Modules\Gnuboard7\HelloModule\Http\Requests;
|
||||
|
||||
use Illuminate\Foundation\Http\FormRequest;
|
||||
|
||||
/**
|
||||
* 메모 목록 조회 요청
|
||||
*
|
||||
* 목록 조회도 FormRequest 로 검증한다는 규정을 보여주는 샘플이다.
|
||||
* 페이지네이션 파라미터에 상·하한이 없으면 per_page=0 은 모델 기본값으로 조용히 바뀌고,
|
||||
* 음수는 예외가 되며, 과대값은 테이블 전량을 반환한다.
|
||||
*/
|
||||
class MemoListRequest extends FormRequest
|
||||
{
|
||||
/**
|
||||
* 권한 확인
|
||||
*
|
||||
* 인증·권한은 라우트 미들웨어가 담당하므로 항상 true 를 반환합니다.
|
||||
*
|
||||
* @return bool
|
||||
*/
|
||||
public function authorize(): bool
|
||||
{
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 유효성 검사 규칙
|
||||
*
|
||||
* @return array 검증 규칙
|
||||
*/
|
||||
public function rules(): array
|
||||
{
|
||||
return [
|
||||
'page' => ['nullable', 'integer', 'min:1'],
|
||||
'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -22,6 +22,8 @@ class MemoRepository implements MemoRepositoryInterface
|
||||
{
|
||||
return Memo::query()
|
||||
->orderByDesc('created_at')
|
||||
// 전순서 보장 — created_at 동률에서 페이지 경계가 흔들리지 않도록 기본키를 덧붙인다
|
||||
->orderByDesc('id')
|
||||
// audit:allow repository-paginate-column-pruning reason: 학습용 샘플 확장의 메모 테이블 —
|
||||
// 넓은 컬럼(text/JSON)이 없고, 지연 조인을 넣으면 샘플 코드의 학습 목적이 흐려진다
|
||||
->paginate($perPage);
|
||||
|
||||
@@ -1,17 +1,26 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Support\Facades\Route;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController as AdminMemoController;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Controllers\Api\MemoController;
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Hello Module Public API Routes
|
||||
| Hello Module API Routes
|
||||
|--------------------------------------------------------------------------
|
||||
|
|
||||
| 비로그인 사용자도 접근 가능한 공개 읽기 API.
|
||||
| ModuleRouteServiceProvider 가 자동으로 prefix 를 적용합니다.
|
||||
| - URL prefix: 'api/modules/gnuboard7-hello_module'
|
||||
| - Name prefix: 'api.modules.gnuboard7-hello_module.'
|
||||
|
|
||||
| 레이아웃 JSON 의 data_sources 가 소비하는 엔드포인트는 전부 이 파일에 둔다.
|
||||
| routes/web.php 는 'modules/{id}' prefix + web 미들웨어라 JSON API 로는 도달하지 않는다.
|
||||
|
|
||||
*/
|
||||
|
||||
/*
|
||||
| 공개 읽기 API — 비로그인 사용자도 접근 가능
|
||||
*/
|
||||
Route::prefix('memos')
|
||||
->middleware(['optional.sanctum', 'throttle:600,1'])
|
||||
->name('memos.')
|
||||
@@ -21,3 +30,34 @@ Route::prefix('memos')
|
||||
->whereNumber('id')
|
||||
->name('show');
|
||||
});
|
||||
|
||||
/*
|
||||
| 관리자 CRUD API — 인증 + 권한 미들웨어로 보호
|
||||
*/
|
||||
Route::prefix('admin/memos')
|
||||
->middleware(['auth:sanctum', 'throttle:600,1'])
|
||||
->name('admin.memos.')
|
||||
->group(function () {
|
||||
Route::get('/', [AdminMemoController::class, 'index'])
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.read')
|
||||
->name('index');
|
||||
|
||||
Route::post('/', [AdminMemoController::class, 'store'])
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.create')
|
||||
->name('store');
|
||||
|
||||
Route::get('/{id}', [AdminMemoController::class, 'show'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.read')
|
||||
->name('show');
|
||||
|
||||
Route::put('/{id}', [AdminMemoController::class, 'update'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.update')
|
||||
->name('update');
|
||||
|
||||
Route::delete('/{id}', [AdminMemoController::class, 'destroy'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.delete')
|
||||
->name('destroy');
|
||||
});
|
||||
|
||||
@@ -1,43 +1,20 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Support\Facades\Route;
|
||||
use Modules\Gnuboard7\HelloModule\Http\Controllers\Admin\MemoController;
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Hello Module Admin Routes
|
||||
| Hello Module Web Routes
|
||||
|--------------------------------------------------------------------------
|
||||
|
|
||||
| ModuleRouteServiceProvider 가 자동으로 prefix 를 적용합니다.
|
||||
| - URL prefix: 'api/modules/gnuboard7-hello_module'
|
||||
| - Name prefix: 'api.modules.gnuboard7-hello_module.'
|
||||
| - URL prefix: 'modules/gnuboard7-hello_module'
|
||||
| - Name prefix: 'web.modules.gnuboard7-hello_module.'
|
||||
| - 미들웨어 그룹: 'web' (세션/CSRF)
|
||||
|
|
||||
| 이 모듈은 화면을 레이아웃 JSON 으로 그리고 데이터는 JSON API 로만 받으므로
|
||||
| 웹(세션) 라우트가 필요 없다. 관리자 CRUD 는 routes/api.php 의
|
||||
| 'api/modules/gnuboard7-hello_module/admin/memos' 그룹에 있다.
|
||||
|
|
||||
| 레이아웃 data_sources 가 호출하는 엔드포인트를 이 파일에 두면 prefix 가
|
||||
| 'api/modules/...' 가 아니라 'modules/...' 가 되어 화면에서 404 가 된다.
|
||||
|
|
||||
*/
|
||||
|
||||
Route::prefix('admin/memos')
|
||||
->middleware(['auth:sanctum', 'throttle:600,1'])
|
||||
->name('admin.memos.')
|
||||
->group(function () {
|
||||
Route::get('/', [MemoController::class, 'index'])
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.read')
|
||||
->name('index');
|
||||
|
||||
Route::post('/', [MemoController::class, 'store'])
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.create')
|
||||
->name('store');
|
||||
|
||||
Route::get('/{id}', [MemoController::class, 'show'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.read')
|
||||
->name('show');
|
||||
|
||||
Route::put('/{id}', [MemoController::class, 'update'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.update')
|
||||
->name('update');
|
||||
|
||||
Route::delete('/{id}', [MemoController::class, 'destroy'])
|
||||
->whereNumber('id')
|
||||
->middleware('permission:admin,gnuboard7-hello_module.memos.delete')
|
||||
->name('destroy');
|
||||
});
|
||||
|
||||
@@ -23,6 +23,7 @@
|
||||
- 게시글 목록을 뒤쪽 페이지에서도 빠르게 열 수 있도록 조회 방식을 바꿨습니다. 예전에는 페이지가 뒤로 갈수록 건너뛰는 게시글의 본문 앞부분까지 함께 읽어 느려졌지만, 이제 현재 페이지의 게시글만 본문 미리보기를 읽습니다. 공지 노출·답글 표시·다음 페이지 버튼은 이전과 동일하게 동작합니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 신고 관리 목록도 같은 방식으로 개선했습니다. 신고 건수·대상 글 상태처럼 목록에 함께 표시되는 정보를 예전에는 건너뛰는 신고까지 모두 계산했지만, 이제 현재 페이지의 신고에 대해서만 계산합니다. 신고가 많이 쌓인 사이트에서 목록 페이지 이동이 빨라집니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 마이페이지의 「내가 쓴 댓글」·「내가 댓글 단 글」 목록도 같은 방식으로 개선했습니다. 각 글의 최근 댓글을 예전에는 건너뛰는 글까지 모두 찾아봤지만, 이제 현재 페이지의 글에 대해서만 찾습니다. 댓글 활동이 많은 회원의 목록 페이지 이동이 빨라집니다. (#74 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 게시글이 많은 게시판에서 목록 정렬이 더 빨라지도록 색인을 정비했습니다. 신고 관리 목록에도 같은 정비를 적용했습니다. 같은 시각에 등록된 게시글이 많은 구간에서 순서를 정하느라 생기던 추가 작업이 사라집니다. 기존 사이트도 업데이트 시 자동으로 반영되며, 게시글이 아주 많은 경우 이 과정에 수 분이 걸리고 그동안 글쓰기가 잠시 대기할 수 있습니다.
|
||||
- 개선된 사이트맵 생성 기능을 사용하기 위해 이 모듈은 이제 코어 7.0.6 이상이 필요합니다.
|
||||
|
||||
### Fixed
|
||||
@@ -35,13 +36,19 @@
|
||||
- 데이터베이스에서 일부 컬럼의 설명이 비어 있던 문제를 바로잡았습니다. 회원·작성자 등 다른 표를 가리키는 컬럼이 대상이며, 업그레이드하면 이미 운영 중인 데이터베이스에도 설명이 채워집니다(직접 적어 넣은 설명은 그대로 둡니다).
|
||||
- 관리자 게시글 목록에서 글을 열어 이전글·다음글로 넘어가거나 수정 후 돌아올 때 보고 있던 페이지·검색어·분류가 사라지던 문제를 수정했습니다. 목록 ↔ 상세 ↔ 이전/다음 글 ↔ 작성·수정 폼 어디로 오가든 목록 상태가 유지되며, 신고 관리와 게시판 목록도 동일하게 개선됐습니다. 새로고침 버튼도 걸어 둔 검색·필터를 지운 채 새로 부르지 않고 보고 있던 목록을 그대로 다시 부릅니다. (#75 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 관리자 게시글 목록에서 뒤쪽 페이지를 보던 중 검색하거나 게시 상태를 바꾸면 그 페이지 번호가 그대로 유지돼 결과가 없는 빈 화면이 열리던 문제를 수정했습니다. 검색과 상태 변경은 1페이지부터 보여주며, 사용자가 고른 표시 개수와 정렬은 그대로 유지됩니다. 검색창에서 엔터를 치는 경우와 검색 버튼을 누르는 경우가 서로 다르게 동작하던 것도 함께 맞췄습니다. (#75 @jiwonpapa 님께서 제보해주셨습니다.)
|
||||
- 신고 상세의 신고자 목록에서 한 페이지에 보여줄 개수를 0 이나 음수로 요청하면 오류가 나던 문제를 수정했습니다.
|
||||
- 게시판 관리 목록과 신고 처리 로그에서 같은 시각에 등록된 항목이 여러 건일 때, 페이지를 넘기면 같은 항목이 두 번 보이고 다른 항목은 아예 보이지 않던 문제를 수정했습니다.
|
||||
- 첨부파일을 사용하지 않는 게시판을 아무것도 바꾸지 않고 저장해도 "허용 파일 확장자를 최소 1개 이상 입력하세요" 오류가 나며 저장이 막히던 문제를 수정했습니다. 첨부를 쓰지 않는 게시판에서는 허용 확장자를 비워 두어도 정상적으로 저장됩니다. 게시판 환경설정의 기본값도 동일하게 동작합니다. (#78 @glitter-gim 님께서 제보해주셨습니다.)
|
||||
- 마이페이지 「내가 댓글 단 글」에서 검색어를 입력하면 목록이 열리지 않고 오류가 나던 문제를 수정했습니다. 이제 댓글 내용으로 정상 검색됩니다.
|
||||
- 새 글 표시 기간을 "0시간"(새 글 표시 안 함)으로 저장할 수 없던 문제를 수정했습니다. 0은 원래 새 글 배지를 끄는 값으로 동작하도록 되어 있었으나 저장 단계에서 막혀 있었습니다.
|
||||
- 게시판 환경설정에서 제목·댓글 최소 길이를 0(제한 없음)으로 저장할 수 없던 문제를 수정했습니다. 내용 최소 길이는 0이 허용되어 같은 화면에서 항목마다 동작이 달랐습니다.
|
||||
- 댓글 계층 정리 시 서로가 서로의 부모로 얽혀 최상위 댓글에서 닿을 수 없는 댓글이 아무 기록 없이 넘어가던 문제를 수정했습니다. 이런 댓글은 내용과 위치를 그대로 보존하되, 정리되지 않았다는 사실이 업데이트 기록에 남아 확인할 수 있습니다.
|
||||
- 마이페이지 활동 목록에서 한 페이지에 표시할 개수를 0이나 음수로 요청하면 서버 오류가 나던 문제를 수정했습니다. 이제 허용 범위(1~100)로 자동 조정되며, 지나치게 큰 값도 상한으로 잘립니다.
|
||||
- 게시판 신고현황 목록에서 뒤쪽 페이지를 보던 중 정렬을 바꾸면 이전 페이지 번호에 그대로 머물러 엉뚱한 구간이 보이던 문제를 수정했습니다. 이제 정렬을 바꾸면 첫 페이지부터 보여줍니다.
|
||||
- 허용 확장자를 지정하지 않은 게시판에서 어떤 파일도 첨부할 수 없던 문제를 수정했습니다. 파일 선택 단계에서 막히던 것과 서버에서 거부되던 것을 함께 고쳐, 확장자를 지정하지 않은 게시판은 기본 확장자 목록을 사용합니다. 첨부 안내에 확장자가 비어 표시되던 것도 함께 해소됩니다. 확장자를 지정한 게시판은 지금처럼 목록에 없는 파일을 계속 거부합니다.
|
||||
- 게시판 알림 설정에서 저장에 실패해도 아무 안내 없이 넘어가던 화면을 수정했습니다. 실패하면 그 이유가 화면에 표시됩니다.
|
||||
- 신고 상세의 신고자 목록에서 한 페이지에 표시할 개수에 상한이 없어 신고자 전체를 한 번에 불러올 수 있던 문제를 수정했습니다. 이제 다른 목록과 같은 상한(100)이 적용됩니다.
|
||||
- 게시판 유형 상세를 조회한 기록이 활동 로그에 내부 식별자로 표시되던 문제를 수정했습니다.
|
||||
- 일부 안내 문구가 실제 문장 대신 내부 식별자(`sirsoft-board::messages....` 같은 문자열)로 표시되던 문제를 수정했습니다. 첨부파일이 있는 게시판을 찾지 못했을 때, 댓글 목록을 불러오지 못했을 때, 비회원 댓글의 비밀번호를 확인할 때, 삭제·블라인드된 글에 댓글을 달려 할 때, 권한이 없어 거절될 때가 해당됩니다.
|
||||
- 비밀글을 쓸 수 없는 게시판에서 비밀글로 저장하려 할 때, 답글 대상 게시판을 찾지 못했을 때, 신고 상태를 바꿀 수 없는 상태로 변경하려 할 때 나오던 안내가 정상 문장으로 표시됩니다.
|
||||
- 댓글 수정, 신고 접수·처리, 블라인드·복원, 게시판 설정 일괄 적용 화면에서 오류 안내에 항목 이름이 영문 필드명으로 나오던 것을 한글 항목명으로 바로잡았습니다.
|
||||
|
||||
+87
@@ -0,0 +1,87 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
/**
|
||||
* 게시글 목록 인덱스 말미에 기본키를 덧붙여 정렬을 완전히 덮습니다.
|
||||
*
|
||||
* 기존 `idx_board_posts_list_count` 는 [board_id, is_notice, parent_id, deleted_at, created_at]
|
||||
* 로 끝난다. 목록 정렬은 `created_at DESC, id DESC` 인데 인덱스가 created_at 에서 끝나므로
|
||||
* 동률 구간의 id 순서를 인덱스로 만들 수 없어 filesort 가 붙는다.
|
||||
*
|
||||
* 20만 행 계측(2026-08-01, MySQL 8.4.3)에서 지연 조인의 inner 쿼리가
|
||||
* `key=idx_board_posts_list_count ... Using index; Using filesort` 로 잡혔고, OFFSET 199,980
|
||||
* 에서 77.8ms 였다. inner 는 키 컬럼만 읽으므로 filesort 만 걷어내면 인덱스 순서 그대로
|
||||
* 끝난다(= `Using index` 단독).
|
||||
*
|
||||
* 같은 선행 컬럼을 가진 인덱스를 새로 만들면 기존 인덱스가 그대로 남아 쓰기 비용만 늘어나므로
|
||||
* **교체**한다. 뒤에 id 를 덧붙인 인덱스는 기존 인덱스가 답하던 조회를 모두 포함한다.
|
||||
*
|
||||
* `idx_board_posts_adjacent` 로는 대체되지 않는다 — 그 인덱스는 2번째가 `status` 인데
|
||||
* 목록 조회가 status 를 등치로 고정하지 않는 경우가 있어 그 지점에서 등치 사슬이 끊기고
|
||||
* 뒤의 created_at 을 정렬에 쓸 수 없다.
|
||||
*
|
||||
* 소프트 삭제 단독 인덱스(`g7_board_posts_deleted_at_index`) 제거는 다른 조회가 의존할 수
|
||||
* 있으므로 이번 범위에서 다루지 않는다.
|
||||
*/
|
||||
return new class extends Migration
|
||||
{
|
||||
private const TABLE = 'board_posts';
|
||||
|
||||
private const OLD_INDEX = 'idx_board_posts_list_count';
|
||||
|
||||
private const NEW_INDEX = 'idx_board_posts_list_count_id';
|
||||
|
||||
/** @var array<int, string> */
|
||||
private const OLD_COLUMNS = ['board_id', 'is_notice', 'parent_id', 'deleted_at', 'created_at'];
|
||||
|
||||
/** @var array<int, string> */
|
||||
private const NEW_COLUMNS = ['board_id', 'is_notice', 'parent_id', 'deleted_at', 'created_at', 'id'];
|
||||
|
||||
/**
|
||||
* Run the migrations.
|
||||
*/
|
||||
public function up(): void
|
||||
{
|
||||
if (! Schema::hasTable(self::TABLE)) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes(self::TABLE), 'name');
|
||||
|
||||
Schema::table(self::TABLE, function (Blueprint $table) use ($existing) {
|
||||
if (! in_array(self::NEW_INDEX, $existing, true)) {
|
||||
$table->index(self::NEW_COLUMNS, self::NEW_INDEX);
|
||||
}
|
||||
|
||||
// 새 인덱스가 기존 인덱스의 상위집합이므로 남겨 두면 쓰기 비용만 늘어난다
|
||||
if (in_array(self::OLD_INDEX, $existing, true)) {
|
||||
$table->dropIndex(self::OLD_INDEX);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reverse the migrations.
|
||||
*/
|
||||
public function down(): void
|
||||
{
|
||||
if (! Schema::hasTable(self::TABLE)) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes(self::TABLE), 'name');
|
||||
|
||||
Schema::table(self::TABLE, function (Blueprint $table) use ($existing) {
|
||||
if (! in_array(self::OLD_INDEX, $existing, true)) {
|
||||
$table->index(self::OLD_COLUMNS, self::OLD_INDEX);
|
||||
}
|
||||
|
||||
if (in_array(self::NEW_INDEX, $existing, true)) {
|
||||
$table->dropIndex(self::NEW_INDEX);
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
<?php
|
||||
|
||||
use Illuminate\Database\Migrations\Migration;
|
||||
use Illuminate\Database\Schema\Blueprint;
|
||||
use Illuminate\Support\Facades\Schema;
|
||||
|
||||
/**
|
||||
* 신고 목록의 정렬 색인을 추가합니다.
|
||||
*
|
||||
* 신고 관리 목록은 `deleted_at IS NULL` 로 좁힌 뒤 `created_at DESC, id DESC` 로 정렬하는데,
|
||||
* 그 순서를 덮는 색인이 없어 뒤쪽 페이지가 테이블 전체를 훑고 정렬했다. 지연 조인의 inner 가
|
||||
* 키 컬럼만 읽어도 인덱스 순서로 끝나지 못하면 깊은 OFFSET 개선 폭이 사라진다.
|
||||
*
|
||||
* 필요한 색인은 계측 프로파일 선언(filters / order / soft_delete)에서 도출한 것이며,
|
||||
* 게시판 모듈의 `ListIndexCoverageTest` 가 같은 규칙으로 전 목록을 검사한다.
|
||||
*/
|
||||
return new class extends Migration
|
||||
{
|
||||
private const TABLE = 'boards_reports';
|
||||
|
||||
private const INDEX_NAME = 'idx_boards_reports_deleted_created_id';
|
||||
|
||||
/** @var array<int, string> */
|
||||
private const INDEX_COLUMNS = ['deleted_at', 'created_at', 'id'];
|
||||
|
||||
/**
|
||||
* Run the migrations.
|
||||
*/
|
||||
public function up(): void
|
||||
{
|
||||
if (! Schema::hasTable(self::TABLE)) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes(self::TABLE), 'name');
|
||||
|
||||
Schema::table(self::TABLE, function (Blueprint $table) use ($existing) {
|
||||
if (! in_array(self::INDEX_NAME, $existing, true)) {
|
||||
$table->index(self::INDEX_COLUMNS, self::INDEX_NAME);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Reverse the migrations.
|
||||
*/
|
||||
public function down(): void
|
||||
{
|
||||
if (! Schema::hasTable(self::TABLE)) {
|
||||
return;
|
||||
}
|
||||
|
||||
$existing = array_column(Schema::getIndexes(self::TABLE), 'name');
|
||||
|
||||
Schema::table(self::TABLE, function (Blueprint $table) use ($existing) {
|
||||
if (in_array(self::INDEX_NAME, $existing, true)) {
|
||||
$table->dropIndex(self::INDEX_NAME);
|
||||
}
|
||||
});
|
||||
}
|
||||
};
|
||||
@@ -133,6 +133,6 @@ HTTP/1.1 200
|
||||
|
||||
<!-- @generated:end -->
|
||||
|
||||
**설명** 로그인한 회원 본인의 게시글 활동을 마이페이지에 표시하기 위해 반환합니다. `auth:sanctum` 인증이 필요한 회원 전용 엔드포인트로, 대상 사용자는 항상 인증된 본인(`Auth::id()`)입니다. `board_slug`·`search`·`activity_type`·`sort`(latest/oldest/views) 필터와 `per_page`(기본 20) 페이지네이션을 지원하며, 응답에는 적용된 필터가 `query` 로 함께 담깁니다.
|
||||
**설명** 로그인한 회원 본인의 게시글 활동을 마이페이지에 표시하기 위해 반환합니다. `auth:sanctum` 인증이 필요한 회원 전용 엔드포인트로, 대상 사용자는 항상 인증된 본인(`Auth::id()`)입니다. `board_slug`·`search`·`activity_type`·`sort`(latest/oldest/views) 필터와 `per_page`(기본 20, 허용 범위 1~100) 페이지네이션을 지원하며, 응답에는 적용된 필터가 `query` 로 함께 담깁니다. 범위를 벗어난 `per_page` 는 오류 대신 경계값으로 잘립니다(0·음수 → 1, 100 초과 → 100).
|
||||
|
||||
|
||||
|
||||
@@ -873,8 +873,11 @@ class Module extends AbstractModule
|
||||
'trigger_type', 'ip_address', 'created_at', 'updated_at', 'deleted_at',
|
||||
],
|
||||
'order' => [['created_at', 'desc'], ['id', 'desc']],
|
||||
'filters' => ['board_id' => 1],
|
||||
'seed_overrides' => ['board_id' => 1, 'is_notice' => 0],
|
||||
// 실제 목록 쿼리(PostRepository::buildSortedPostList)는 공지와 답글을 빼고
|
||||
// 원글만 페이지네이션한다. 필터를 board_id 만 걸면 등치 사슬이 is_notice 에서
|
||||
// 끊겨 옵티마이저가 다른 인덱스를 골라, 제품이 실행하지 않는 실행 계획을 재게 된다.
|
||||
'filters' => ['board_id' => 1, 'is_notice' => 0, 'parent_id' => null],
|
||||
'seed_overrides' => ['board_id' => 1, 'is_notice' => 0, 'parent_id' => null],
|
||||
'soft_delete' => true,
|
||||
],
|
||||
// 댓글은 계측 프로파일을 두지 않는다. 페이지네이션되는 댓글 목록은 회원 본인 댓글
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'description' => [
|
||||
// Board management (Admin)
|
||||
'board_index' => 'Board list viewed',
|
||||
'board_show' => 'Board details viewed (:board_name)',
|
||||
'board_create' => 'Board created (:board_name)',
|
||||
'board_update' => 'Board updated (:board_name)',
|
||||
'board_delete' => 'Board deleted (:board_name)',
|
||||
'board_copy' => 'Board copied (:board_name)',
|
||||
'board_add_to_menu' => 'Board added to menu (:board_name)',
|
||||
|
||||
// Board type (Admin)
|
||||
'board_type_index' => 'Board type list viewed',
|
||||
'board_type_show' => 'Board type details viewed (:type_name)',
|
||||
'board_type_create' => 'Board type created (:type_name)',
|
||||
'board_type_update' => 'Board type updated (:type_name)',
|
||||
'board_type_delete' => 'Board type deleted (:type_name)',
|
||||
|
||||
// Posts
|
||||
'post_create' => 'Post created (Board: :board_name, Title: :title)',
|
||||
'post_update' => 'Post updated (Board: :board_name, Title: :title)',
|
||||
'post_delete' => 'Post deleted (Board: :board_name, ID: :post_id)',
|
||||
'post_blind' => 'Post blinded (Board: :board_name, ID: :post_id)',
|
||||
'post_restore' => 'Post restored (Board: :board_name, ID: :post_id)',
|
||||
|
||||
// Comments
|
||||
'comment_create' => 'Comment created (Board: :board_name, Post: :post_id)',
|
||||
'comment_update' => 'Comment updated (ID: :comment_id)',
|
||||
'comment_delete' => 'Comment deleted (ID: :comment_id)',
|
||||
'comment_blind' => 'Comment blinded (ID: :comment_id)',
|
||||
'comment_restore' => 'Comment restored (ID: :comment_id)',
|
||||
|
||||
// Attachments
|
||||
'board_attachment_upload' => 'Attachment uploaded (Post: :post_id)',
|
||||
'board_attachment_delete' => 'Attachment deleted (Post: :post_id)',
|
||||
'board_attachment_download' => 'Attachment downloaded (Post: :post_id)',
|
||||
'board_attachment_reorder' => 'Attachment order changed (Post: :post_id)',
|
||||
|
||||
// Report management (Admin)
|
||||
'report_create' => 'Report created (ID: :report_id)',
|
||||
'report_update_status' => 'Report status changed (ID: :report_id)',
|
||||
'report_bulk_update_status' => 'Report statuses bulk changed (:count items)',
|
||||
'report_delete' => 'Report deleted (ID: :report_id)',
|
||||
'report_restore_content' => 'Report content restored (ID: :report_id)',
|
||||
'report_blind_content' => 'Report content blinded (ID: :report_id)',
|
||||
'report_delete_content' => 'Report content deleted (ID: :report_id)',
|
||||
|
||||
// Board settings
|
||||
'board_settings_index' => 'Board settings viewed',
|
||||
'board_settings_bulk_apply' => 'Board settings bulk applied',
|
||||
'board_settings_bulk_apply_aborted' => 'Board settings bulk apply aborted (full rollback, failed board: :failed_board_name, :failed_at/:total)',
|
||||
],
|
||||
];
|
||||
@@ -1,55 +0,0 @@
|
||||
<?php
|
||||
|
||||
return [
|
||||
'description' => [
|
||||
// 게시판 관리 (Admin)
|
||||
'board_index' => '게시판 목록 조회',
|
||||
'board_show' => '게시판 상세 조회 (:board_name)',
|
||||
'board_create' => '게시판 생성 (:board_name)',
|
||||
'board_update' => '게시판 수정 (:board_name)',
|
||||
'board_delete' => '게시판 삭제 (:board_name)',
|
||||
'board_copy' => '게시판 복사 (:board_name)',
|
||||
'board_add_to_menu' => '게시판 메뉴 추가 (:board_name)',
|
||||
|
||||
// 게시판 유형 (Admin)
|
||||
'board_type_index' => '게시판 유형 목록 조회',
|
||||
'board_type_show' => '게시판 유형 상세 조회 (:type_name)',
|
||||
'board_type_create' => '게시판 유형 생성 (:type_name)',
|
||||
'board_type_update' => '게시판 유형 수정 (:type_name)',
|
||||
'board_type_delete' => '게시판 유형 삭제 (:type_name)',
|
||||
|
||||
// 게시물
|
||||
'post_create' => '게시물 작성 (게시판: :board_name, 제목: :title)',
|
||||
'post_update' => '게시물 수정 (게시판: :board_name, 제목: :title)',
|
||||
'post_delete' => '게시물 삭제 (게시판: :board_name, ID: :post_id)',
|
||||
'post_blind' => '게시물 블라인드 (게시판: :board_name, ID: :post_id)',
|
||||
'post_restore' => '게시물 복원 (게시판: :board_name, ID: :post_id)',
|
||||
|
||||
// 댓글
|
||||
'comment_create' => '댓글 작성 (게시판: :board_name, 게시물: :post_id)',
|
||||
'comment_update' => '댓글 수정 (ID: :comment_id)',
|
||||
'comment_delete' => '댓글 삭제 (ID: :comment_id)',
|
||||
'comment_blind' => '댓글 블라인드 (ID: :comment_id)',
|
||||
'comment_restore' => '댓글 복원 (ID: :comment_id)',
|
||||
|
||||
// 첨부파일
|
||||
'board_attachment_upload' => '첨부파일 업로드 (게시물: :post_id)',
|
||||
'board_attachment_delete' => '첨부파일 삭제 (게시물: :post_id)',
|
||||
'board_attachment_download' => '첨부파일 다운로드 (게시물: :post_id)',
|
||||
'board_attachment_reorder' => '첨부파일 순서 변경 (게시물: :post_id)',
|
||||
|
||||
// 신고 관리 (Admin)
|
||||
'report_create' => '신고 접수 (ID: :report_id)',
|
||||
'report_update_status' => '신고 상태 변경 (ID: :report_id)',
|
||||
'report_bulk_update_status' => '신고 일괄 상태 변경 (:count건)',
|
||||
'report_delete' => '신고 삭제 (ID: :report_id)',
|
||||
'report_restore_content' => '신고 콘텐츠 복원 (ID: :report_id)',
|
||||
'report_blind_content' => '신고 콘텐츠 블라인드 (ID: :report_id)',
|
||||
'report_delete_content' => '신고 콘텐츠 삭제 (ID: :report_id)',
|
||||
|
||||
// 게시판 설정
|
||||
'board_settings_index' => '게시판 설정 조회',
|
||||
'board_settings_bulk_apply' => '게시판 설정 일괄 적용',
|
||||
'board_settings_bulk_apply_aborted' => '게시판 설정 일괄 적용 중단 (전체 롤백, 실패 게시판: :failed_board_name, :failed_at/:total)',
|
||||
],
|
||||
];
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user