Files
Gnuboard7/tests/scenarios/deep-offset-pagination.yaml
T
HeuJung b10e89bef0 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" 로 보고되던 문제도 런너 사전 검증으로 막았다.

정렬 게이트 대조 하네스는 관계 정렬 변형만 쓰는 저장소를 탐지하지 못한 채 통과시키고 있었다.
탐지·제외·인자 파싱을 함께 고치고 단위 테스트를 신설했다.
2026-08-02 15:29:29 +09:00

93 lines
5.6 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# audit:allow test-scenario-coverage reason: 이슈 #492(공개 #74) 깊은 OFFSET 목록 페이지네이션 SSoT. axes cross product(수백 조합 × 26개 호출처)는 docblock 전수 @scenario 매핑이 비현실적이라 면제하고, 회귀 가드는 test_files(트레이트 단위 + 호출 계약 전수 스캔 + 도메인별 저장소 회귀 + Playwright E2E)로 커버한다. 대용량 축(scale)은 scenario-scale-axis-required 룰이 별도 강제(면제 대상 아님) — scale.assert 는 @scale 마킹으로 전수 커버.
feature: deep_offset_pagination
description: |
목록 페이지네이션이 뒤쪽 페이지로 갈수록 선형으로 느려지던 것을, 지연 조인(deferred join)
2단계 조회로 재설계한다. `OFFSET n` 은 건너뛸 n 건도 실제로 읽으며, 목록 SELECT 에 넓은
컬럼(text/longText/JSON)이 있으면 그 n 건의 넓은 컬럼까지 읽힌다. InnoDB 는 행 밖 오버플로
페이지에 저장된 값을 앞부분만 필요해도 페이지째 읽으므로 비용이 그대로 누적된다.
핵심 설계:
- inner: 필터/정렬만으로 **키 컬럼만** 조회해 이번 페이지의 ID 집합을 구한다.
- outer: 그 ID 집합에 대해서만 목록 컬럼과 관계를 조회한다 — 넓은 컬럼을 읽는 행 수가
OFFSET 과 무관하게 페이지 크기로 고정된다.
- 정렬은 닫힌 집합(ResolvesSortSpec)이어야 한다. 인덱스 없는 컬럼 정렬은 inner 도 전체
스캔하므로 개선 폭이 보장되지 않는다.
- 키 컬럼을 정렬 말미에 자동으로 덧붙여 전순서를 만든다 — 동률 정렬에서 페이지 경계가
흔들려 행이 중복/누락되는 것을 막는다.
- 총 건수는 Laravel paginate() 와 같은 집계 경로(getCountForPagination)를 쓴다. count() 는
groupBy/having 쿼리에서 첫 그룹의 행 수를 총 건수로 돌려준다.
- `SUBSTRING(col, 1, N)` 은 프루닝으로 인정하지 않는다 — 오버플로 페이지 읽기가 그대로
발생하므로 잘라내기는 outer 에서만 수행한다.
axes:
page_position: [first, middle, last]
sort_column: [key, indexed_non_key, tied_values]
total_source: [counted, injected_cache, simple_no_count]
soft_delete: [default_excluded, with_trashed]
query_shape: [flat, joined, grouped]
relations: [none, eager_load, with_count]
filter: [none, search, scoped]
columns: [pruned, all]
exclusions:
- { total_source: simple_no_count, page_position: last, reason: "simplePaginate 는 총 건수를 세지 않아 마지막 페이지 개념이 없다 — hasMorePages 판정으로 대체" }
- { query_shape: grouped, total_source: simple_no_count, reason: "그룹 쿼리의 다음 페이지 판정은 총 건수 경로와 무관 — 그룹 수 정확성이 검증 대상" }
- { soft_delete: with_trashed, query_shape: grouped, reason: "그룹 목록(회원 활동)에 휴지통 조회 진입점이 없다" }
effects:
# ── 조회 구조 (P0) ──
- inner_selects_key_column_only
- inner_excludes_wide_columns_from_offset_scan
- outer_filters_by_id_set_without_offset
- relations_eager_loaded_on_outer_only
- with_count_applied_on_outer_only
- empty_id_set_skips_outer_query
# ── 총 건수 (P0) ──
- injected_total_skips_count_query
- simple_mode_skips_count_query
- grouped_query_total_counts_groups_not_first_group_rows
- filtered_query_total_reflects_filters
# ── 페이지 경계 정합 (P0) ──
- key_column_appended_to_sort_for_total_order
- pages_do_not_overlap_or_drop_rows
- outer_result_order_matches_inner_order
- preserve_id_order_restores_inner_sequence
- simple_mode_reports_last_page_without_next
# ── 스코프 보존 (P1) ──
- soft_deleted_rows_stay_excluded
- with_trashed_scope_is_preserved
- query_filters_are_preserved_on_both_stages
- self_scoped_list_returns_only_own_rows
- comments_of_soft_deleted_parents_stay_excluded
# ── 페이지네이터 계약 (P1) ──
- paginator_supports_query_string_appending
- custom_page_name_is_reflected_in_links
# ── 호출 계약 (P1) ──
- every_call_site_declares_columns
- every_call_site_declares_non_empty_sort
- call_sites_pass_relations_as_argument
# ── 정렬 화이트리스트 (P0) ──
- sort_column_resolved_from_closed_set
- unknown_sort_column_falls_back_to_default
# scale: 대용량 회귀 축. block-array of flow objects (내장 fallback 파서 제약 — flow 객체만 중첩 파싱)
scale:
- { n: 200000, dataset: board_posts, assert: [deep_offset_bounded_growth, id_only_inner_query, no_wide_column_in_offset_scan] }
test_files:
# 코어 — 트레이트 단위 (조회 구조 / 총 건수 / 페이지 경계 / 스코프)
- tests/Unit/Repositories/Concerns/PaginatesWithDeferredJoinTest.php
- tests/Unit/Repositories/Concerns/ResolvesSortSpecTest.php
# 코어 — 호출 계약 전수 스캔 (호출처가 늘어나도 자동 편입)
- tests/Unit/Repositories/Concerns/DeferredJoinCallSiteContractTest.php
# 게시판 — 공지 병합 / 답글 트리 / 소프트 삭제 / 정렬 경계
- modules/_bundled/sirsoft-board/tests/Unit/Repositories/PostListDeferredJoinTest.php
# 게시판 — 삭제된 글의 댓글 제외 / 캐시 total / 검색 총 건수
- modules/_bundled/sirsoft-board/tests/Unit/Repositories/CommentListDeferredJoinTest.php
# 이커머스 — 주문 목록 소프트 삭제 + 페이지 경계
- modules/_bundled/sirsoft-ecommerce/tests/Feature/Http/Controllers/Admin/OrderListDeferredJoinTest.php
# 브라우저 — 마지막 페이지 다음 버튼 / 페이지 이동 후 목록 정합
- tests/Playwright/specs/pagination/deep-offset-list.spec.ts