From 56b48f81ffde5e972d6dee4399f31052abb81839 Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Thu, 4 Dec 2025 16:58:45 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Admin=20Dashboard=20=EA=B3=84=ED=9A=8D?=
 =?UTF-8?q?=EC=97=90=20API=20=EC=8A=A4=ED=82=A4=EB=A7=88=20=EB=B0=8F=20?=
 =?UTF-8?q?=ED=8E=98=EC=9D=B4=EC=A7=80=EB=84=A4=EC=9D=B4=EC=85=98=20?=
 =?UTF-8?q?=EC=A0=84=EB=9E=B5=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...04_admin_dashboard_business_integration.md | 38 +++++++++++++++++--
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/journey/plans/251204_admin_dashboard_business_integration.md b/journey/plans/251204_admin_dashboard_business_integration.md
index dd6fcb6..d8590c3 100644
--- a/journey/plans/251204_admin_dashboard_business_integration.md
+++ b/journey/plans/251204_admin_dashboard_business_integration.md
@@ -49,12 +49,44 @@ admin-dashboard/backend/
 
 **원칙 준수**: router(HTTP) → service(비즈니스) → repository(DB), DB 접근은 repository에서만
 
-### 2. 성능 최적화
+### 2. API 스키마 정의 (schemas/)
+
+**패턴 참고**: auth-server의 WorkspaceResponse/WorkspaceCreate 구조
+
+**User 스키마**:
+- `UserResponse`: id, email, name, username, metadata(dict), is_active, last_login_at
+- `UserUpdate`: name, metadata (부분 업데이트)
+- `UserList`: items(list[UserResponse]), total, page, limit
+
+**Robeing 스키마**:
+- `RobeingResponse`: id, team_id, name, level, stats(memory/compute/react/empathy/leadership)
+- `RobeingStats`: 대화 빈도, 스킬 사용 횟수, 감정 트렌드
+
+**공통**:
+- `PaginationParams`: limit(기본 50), offset(기본 0)
+- `ErrorResponse`: detail(str), code(int)
+- metadata JSONB는 `dict[str, Any]`로 직렬화
+
+### 3. 페이지네이션 전략
+
+**기본 방식**: limit/offset 파라미터 (단순 구현, admin 용도 충분)
+- 모든 리스트 API: `?limit=50&offset=0` 기본값
+- 응답: `{"items": [...], "total": int, "page": int, "limit": int}`
+
+**대용량 테이블 처리**:
+- conversation_log(수만 건): 날짜 범위 필터 필수 (`?start_date=&end_date=`)
+- emotion_readings: 시간대별 집계 쿼리 (GROUP BY), 원본 데이터 페이지네이션
+- rb_news/team_document: created_at DESC 인덱스 활용
+
+**프론트엔드 UI**: 페이지 번호 버튼 (1, 2, 3... 10) + 이전/다음
+**향후 고려**: cursor 기반 페이지네이션 (성능 우수, 구현 복잡)
+
+### 4. 성능 최적화
 
 **병렬 처리**: asyncio.gather()로 다중 DB 조회 동시 실행 (순차 대비 66% 성능 향상)
 **검증 완료**: 계층 분리는 성능 오버헤드 없음 (테스트 확인)
 
-### 3. 신규 탭 3개 (UX 중심)
+### 5. 신규 탭 3개 (UX 중심)
 
 #### 탭 1: 사용자/팀
 - **테이블 뷰**: user/team 목록, 검색/필터/정렬
@@ -73,7 +105,7 @@ admin-dashboard/backend/
 - **차트**: 히트맵(시간대별 스킬 사용), 파이 차트(의도 분포)
 - **테이블**: rb_news(최근 발행), team_document(RAG 문서), ir_deck_evaluations(IR 평가 현황)
 
-### 4. 공통 UI 패턴
+### 6. 공통 UI 패턴
 - **우측 상단**: 새로고침/필터/CSV 다운로드 버튼
 - **테이블 행**: 편집/삭제/상세 아이콘 버튼
 - **모달**: metadata 편집, 상세 정보 표시