From db3865cb6c68e97427cf33de57dc5adb2d996d45 Mon Sep 17 00:00:00 2001
From: kjh2064 <kjh2064@gmail.com>
Date: Sat, 15 Aug 2026 21:45:50 +0900
Subject: [PATCH] feat(fe): standardize empty data state with
 EmptyStatePlaceholder component and AGENTS.md rule

---
 AGENTS.md                                     |  3 +
 frontend/src/shared/ui/DataGridShell.vue      |  8 +--
 frontend/src/shared/ui/QueryStateBoundary.vue |  3 +-
 .../ui/components/EmptyStatePlaceholder.vue   | 72 +++++++++++++++++++
 frontend/src/shared/ui/components/index.ts    |  1 +
 5 files changed, 82 insertions(+), 5 deletions(-)
 create mode 100644 frontend/src/shared/ui/components/EmptyStatePlaceholder.vue

diff --git a/AGENTS.md b/AGENTS.md
index 066a6d86..303d4a70 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -99,6 +99,7 @@ All work in this repository MUST follow `docs/CURRENT/WBS_EXECUTION_PROCEDURES.m
   2. **Grid Row & Item Context Actions (Table Row Actions)**: Dedicated to **Single-Row CRUD & Processing** (e.g., `✏️ 수정`, `🗑️ 삭제`, `🔍 상세보기`, `▶ 재처리`). Placed in a pinned right column or explicit context menu; never placed in page top toolbar.
   3. **Multi-Selection Batch Toolbar (Grid Top/Bottom Selection Bar)**: Activated conditionally upon multi-row selection for **Bulk Actions** (e.g., `선택 일괄 승인(3)`, `선택 일괄 삭제`).
 - **[CRITICAL IRON RULE] Standardized Loading Skeleton Rule**: ALL screen-level and section-level data loading MUST render animated `SkeletonLoader` (shimmer mode) matching the expected layout (e.g. `skeletonType="table"` for grids, `skeletonType="card"` for forms/summaries) through `QueryStateBoundary`/`StandardScreenBoundary`. Static text ("불러오는 중...") or empty screen placeholders during loading states are STRICTLY PROHIBITED.
+- **[CRITICAL IRON RULE] Standardized Empty Data State Rule**: When zero records or empty dataset states occur, ALL grids, lists, and summary cards MUST render standard `EmptyStatePlaceholder` component (`📭` icon, clear title, descriptive helper text, and optional recovery action button). Blank white spaces or plain `<p>데이터가 없습니다</p>` text tags are STRICTLY PROHIBITED.
 
 ## v16.0 Gitea API & CI/CD Automation
 
@@ -360,6 +361,7 @@ Every task — code change, refactor, new feature, tooling, infrastructure — m
 - [ ] **Viewport Fit (UI):** 대시보드를 제외한 모든 업무 화면이 페이지 스크롤 없이 초기 로딩 시 100% 한눈에 들어오는가?
 - [ ] **Button Standard (UI):** 상단 툴바(배치/등록), 행별 작업(수정/상세), 다중선택(일괄), 폼 푸터(취소/저장) 버튼 배치가 규칙 매트릭스를 따르는가?
 - [ ] **Skeleton Loading (UI):** 로딩 상태 시 텍스트 대신 레이아웃에 반응하는 shimmer 스켈레톤(SkeletonLoader)이 제대로 노출되는가?
+- [ ] **Empty State (UI):** 데이터 0건 또는 조회 결과가 없을 시 표준 EmptyStatePlaceholder(아이콘+설명+조치버튼)가 노출되는가?
 
 ### Anti-Patterns (금지)
 
@@ -367,6 +369,7 @@ Every task — code change, refactor, new feature, tooling, infrastructure — m
 - ❌ "페이지에 창 스크롤바가 생기게 방치" → 대시보드 제외 모든 업무 화면은 Viewport-Fit Zero-Scroll 필수
 - ❌ "버튼 위치 난잡 배치" → 상단 우측(페이지/배치), 행 내부(개별 CRUD), 선택바(일괄), 폼 푸터(저장/취소) 표준 무시 금지
 - ❌ "로딩 시 '불러오는 중...' 텍스트 방치" → 반드시 레이아웃 맞춤형 애니메이션 스켈레톤(SkeletonLoader) 적용 필수
+- ❌ "데이터 0건 시 빈 흰색 공간 방치" → 반드시 표준 EmptyStatePlaceholder 컴포넌트 렌더링 필수
 - ❌ "혹시 필요할까봐 추상화" → Necessity-driven만
 - ❌ SELECT * / Generic Repository → Explicit columns, explicit logic
 - ❌ "이건 작은 변경이라 테스트 스킵" → 모든 경로 characterize
diff --git a/frontend/src/shared/ui/DataGridShell.vue b/frontend/src/shared/ui/DataGridShell.vue
index b6854cf2..6bf4c71e 100644
--- a/frontend/src/shared/ui/DataGridShell.vue
+++ b/frontend/src/shared/ui/DataGridShell.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { UiGridColumn } from './adapter/contracts'
-import { KsDataGrid, KsPaginator } from './components'
+import { KsDataGrid, KsPaginator, SkeletonLoader, EmptyStatePlaceholder } from './components'
 
 const props = withDefaults(defineProps<{
   rows: unknown[]
@@ -11,14 +11,14 @@ const props = withDefaults(defineProps<{
   page?: number
   pageSize?: number
   total?: number
-}>(), { loading: false, emptyMessage: '표시할 데이터가 없습니다.', height: 'calc(100vh - 230px)' })
+}>(), { loading: false, emptyMessage: '검색 조건에 해당하거나 조회된 데이터가 없습니다.', height: 'calc(100vh - 230px)' })
 const emit = defineEmits<{ pageChange: [value: { page: number; pageSize: number }] }>()
 </script>
 
 <template>
   <section class="ks-grid-shell-section" aria-label="데이터 표" :aria-busy="loading">
-    <p v-if="loading">데이터를 불러오는 중입니다.</p>
-    <p v-else-if="rows.length === 0">{{ emptyMessage }}</p>
+    <SkeletonLoader v-if="loading" type="table" :rows="6" />
+    <EmptyStatePlaceholder v-else-if="rows.length === 0" :message="emptyMessage" />
     <KsDataGrid v-else :rows="rows" :columns="columns" :height="props.height" />
     <KsPaginator
       v-if="props.page !== undefined && props.pageSize !== undefined && props.total !== undefined"
diff --git a/frontend/src/shared/ui/QueryStateBoundary.vue b/frontend/src/shared/ui/QueryStateBoundary.vue
index cbc30d93..0cada3c1 100644
--- a/frontend/src/shared/ui/QueryStateBoundary.vue
+++ b/frontend/src/shared/ui/QueryStateBoundary.vue
@@ -2,6 +2,7 @@
 import KsButton from './components/KsButton.vue'
 import KsInlineMessage from './components/KsInlineMessage.vue'
 import SkeletonLoader from './components/SkeletonLoader.vue'
+import EmptyStatePlaceholder from './components/EmptyStatePlaceholder.vue'
 const props = defineProps<{
   loading: boolean
   processing?: boolean
@@ -34,7 +35,7 @@ const emit = defineEmits<{ retry: [] }>()
       <KsButton label="같은 요청 다시 시도" severity="secondary" @click="emit('retry')" />
       <small v-if="correlationId">Correlation: {{ correlationId }}</small>
     </div>
-    <KsInlineMessage v-else-if="props.empty" severity="info" message="표시할 데이터가 없습니다." />
+    <EmptyStatePlaceholder v-else-if="props.empty" />
     <template v-else>
       <KsInlineMessage v-if="props.partial" severity="warning" message="일부 데이터만 표시하고 있습니다. 완전성 경고를 확인하세요." />
       <KsInlineMessage v-if="props.warning" severity="warning" :message="props.warning" />
diff --git a/frontend/src/shared/ui/components/EmptyStatePlaceholder.vue b/frontend/src/shared/ui/components/EmptyStatePlaceholder.vue
new file mode 100644
index 00000000..bbc389fc
--- /dev/null
+++ b/frontend/src/shared/ui/components/EmptyStatePlaceholder.vue
@@ -0,0 +1,72 @@
+<script setup lang="ts">
+defineProps<{
+  title?: string
+  message?: string
+  icon?: string
+  actionLabel?: string
+}>()
+
+const emit = defineEmits<{ action: [] }>()
+</script>
+
+<template>
+  <div class="ks-empty-state" role="status" aria-label="조회된 데이터 없음">
+    <div class="ks-empty-state__icon">{{ icon ?? '📭' }}</div>
+    <div class="ks-empty-state__title">{{ title ?? '조회된 데이터가 없습니다' }}</div>
+    <p class="ks-empty-state__message">{{ message ?? '검색 조건을 변경하거나 신규 데이터를 생성해 주세요.' }}</p>
+    <button v-if="actionLabel" class="ks-empty-state__action" @click="emit('action')">
+      {{ actionLabel }}
+    </button>
+  </div>
+</template>
+
+<style scoped>
+.ks-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: var(--ks-space-4);
+  text-align: center;
+  background: #fff;
+  border: 1px dashed var(--ks-color-neutral-300);
+  border-radius: var(--ks-radius-md);
+  min-height: 220px;
+  flex: 1;
+  width: 100%;
+}
+
+.ks-empty-state__icon {
+  font-size: 32px;
+  line-height: 1;
+  margin-bottom: var(--ks-space-2);
+}
+
+.ks-empty-state__title {
+  font-size: var(--ks-font-body);
+  font-weight: 700;
+  color: var(--ks-color-neutral-800);
+  margin-bottom: var(--ks-space-1);
+}
+
+.ks-empty-state__message {
+  font-size: var(--ks-font-caption);
+  color: var(--ks-color-neutral-600);
+  margin: 0;
+  max-width: 360px;
+}
+
+.ks-empty-state__action {
+  margin-top: var(--ks-space-3);
+  padding: 4px 12px;
+  font-size: var(--ks-font-caption);
+  background: var(--ks-color-action);
+  color: #fff;
+  border: none;
+  border-radius: var(--ks-radius-sm);
+  cursor: pointer;
+}
+.ks-empty-state__action:hover {
+  background: var(--ks-color-action-hover);
+}
+</style>
diff --git a/frontend/src/shared/ui/components/index.ts b/frontend/src/shared/ui/components/index.ts
index 0e811bbf..67b42f18 100644
--- a/frontend/src/shared/ui/components/index.ts
+++ b/frontend/src/shared/ui/components/index.ts
@@ -1,4 +1,5 @@
 export { default as SkeletonLoader } from './SkeletonLoader.vue'
+export { default as EmptyStatePlaceholder } from './EmptyStatePlaceholder.vue'
 export { default as KsButton } from './KsButton.vue'
 export { default as KsTextField } from './KsTextField.vue'
 export { default as KsTextArea } from './KsTextArea.vue'