AI 단계별 작업 문서 00 — 작업 지침 및 구현 원칙
이 문서는 원본 가이드의 해당 구간을 그대로 보존합니다. 코드 블록을 삭제하거나 축약하지 않았습니다. 먼저 읽고, 실제 작업 요청에 해당하는 다음 단계 문서를 이어서 확인하세요.
DXCMS 여분 필드 — 목록 노출 · 검색 필터 구현 가이드
대상: DXCMS v10.3.0 / AI 에이전트 작업 지침서 범위: 여분 필드의
is_list(목록 노출)와is_search(검색 필터) 두 설정을 실제로 동작하게 만드는 방법 근거: 소스 직접 분석(boards/handler.php,core/BoardFields.php, 번들 gallery 스킨) + 이 문서의 코드를 MariaDB 10.11 / PHP 8.3 에서 실행 검증 (부록 A)
0. AI 에이전트 사용 지침
- 사용자가 "여분 필드를 목록에 보이게 해줘", "필드 값으로 검색/필터하고 싶다"고 요청하면 이 문서대로 작업한다.
- 기본 구조(정의
dx_board_fields, 값dx_post_meta, 폼 namebf_{key})는 이미 알고 있다고 가정한다. - 추측하지 말 것.
is_list,is_search체크박스는 DB에 값만 저장하며, 코어는 이 값을 읽는 코드가 없다. 이 문서의 코드를 설치해야 비로소 동작한다. - 작업 순서는 항상 아래와 같다.
[1단계] 헬퍼 파일 설치 (코어 수정 없음) ← 필수
[2단계] 스킨에 목록 칸 추가 ← "목록 노출" 요청일 때
[3단계] handler.php 패치 3곳 + 스킨에 필터 폼 ← "검색 필터" 요청일 때
[4단계] 검증 체크리스트 수행 ← 항상
- 수정 전에 대상 파일을 백업하고, 수정 후에는
php -l 파일로 문법을 확인한다. - 사용자가 "목록 노출만" 원하면 3단계는 하지 않는다. (코어 파일 수정이 필요한 것은 3단계뿐)
1. 소스에서 확인된 사실 (이 가이드의 근거)
| # | 사실 | 의미 |
|---|---|---|
| 1 | is_list, is_search 를 읽는 코드는 코어 어디에도 없다 (관리자 저장 화면에서만 사용) |
스킨/핸들러에서 직접 구현해야 함 |
| 2 | 목록 쿼리는 boards/handler.php 의 case 'list': case 'search': 안에서 $where 문자열과 $params 배열로 조립된다. 조건을 끼워 넣는 훅이 없다 |
필터는 handler.php 에 소량 패치가 필요 |
| 3 | COUNT(*) 쿼리와 목록 쿼리가 같은 $where/$params 를 쓴다. 글 별칭은 p |
조건을 한 번만 붙이면 총 개수·페이지 수가 함께 맞는다 |
| 4 | 목록 캐시(DxCache, 60초, 키=게시판+페이지)는 !$search && !$cat && !$tag && 비로그인 && $action!=='search' 일 때만 사용된다 |
필터 조건을 캐시 조건에 넣지 않으면 필터가 무시된 캐시 목록이 나온다 → 패치에 반드시 포함 |
| 5 | dx_board_list_context 훅은 쿼리 이후에 실행되지만, 캐시 경로에서는 실행되지 않는다 |
훅으로 글에 meta를 붙이는 방식은 비로그인 방문자에게 누락될 수 있음 → 스킨에서 직접 조회 |
| 6 | 목록 파라미터는 s, sf, cat, parent, tag, page. 스킨의 페이지네이션은 이 값들만 링크에 이어붙인다 |
필터 파라미터(bf_*)를 페이지네이션 링크에 직접 추가해야 2페이지에서 필터가 풀리지 않음 |
| 7 | gallery 스킨은 _list_rows.php(카드 행 partial), list-live.js(새 글 실시간 삽입, /api/post_row 호출)를 쓴다 |
실시간으로 삽입된 새 행에는 여분 필드 칸이 없을 수 있음 (새로고침하면 정상) |
| 8 | 글 상세 하단의 "목록"은 별도 쿼리(view 액션)이다 |
필터는 목록 화면에만 적용된다 |
2. 구현 방식 선택
| 요구 | 권장 방법 | 코어 수정 | 비고 |
|---|---|---|---|
| 목록에 값 표시 | 스킨에서 일괄 조회 후 출력 | 없음 | 2단계 |
| 필드 값으로 검색/필터 | handler.php 3곳 패치 + 헬퍼 |
소량 (3곳) | 3단계, 권장 |
(대안) 스킨 독립 핸들러 list/handler.php |
목록 액션 전체를 스킨이 처리 | 없음 | 공지·카테고리·캐시·SEO·소켓을 전부 재구현해야 하므로 비권장 |
| (비권장) 현재 페이지 결과를 JS/PHP로 걸러내기 | — | — | 페이지 단위로만 걸러져 총 개수·페이지네이션이 어긋남 |
(비권장) dx_board_list_context 훅으로 meta 부착 |
— | — | 캐시 경로에서 실행 안 됨 (사실 #5) |