From 9df5ede31453be67a4b7ccfd9a9fad423a8e5cfb Mon Sep 17 00:00:00 2001 From: happybell80 Date: Thu, 4 Dec 2025 22:14:40 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EB=A7=88=EC=A7=80=EB=A7=89=202?= =?UTF-8?q?=EA=B0=9C=20plan=20=EB=AC=B8=EC=84=9C=20=EA=B0=84=EA=B2=B0?= =?UTF-8?q?=ED=99=94=20(127=EC=A4=84=20=EC=82=AD=EC=A0=9C)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- journey/plans/250831_todo_and_tech_debt.md | 110 ++++--------- ...04_admin_dashboard_business_integration.md | 147 +++++++----------- 2 files changed, 83 insertions(+), 174 deletions(-) diff --git a/journey/plans/250831_todo_and_tech_debt.md b/journey/plans/250831_todo_and_tech_debt.md index a860cc8..d17549d 100644 --- a/journey/plans/250831_todo_and_tech_debt.md +++ b/journey/plans/250831_todo_and_tech_debt.md @@ -1,106 +1,58 @@ # 기술 부채 정리 -## 작성일: 2025년 8월 31일 -## 최종 수정: 2025년 9월 15일 +**날짜**: 2025-08-31 +**최종 수정**: 2025-09-15 + +--- ## 🔴 미해결 주요 이슈 -### 1. 임시 코드 방식 제거 필요 -**현재 상황**: -- Gmail/Slack 모두 임시 코드 → `/auth/verify` → JWT -- 불필요한 Redis 의존성, 60초 TTL 제한 - -**개선 방안**: -- JWT 직접 전달 또는 Secure cookie 사용 -- Redis 의존성 제거 +### 1. 임시 코드 방식 제거 +**현재**: Gmail/Slack → 임시 코드 → `/auth/verify` → JWT +**문제**: Redis 의존성, 60초 TTL 제한 +**개선**: JWT 직접 전달 또는 Secure cookie ### 2. DB 스키마 불일치 -**문제**: -- company vs workspaces 테이블 공존 -- SlackWorkspace 모델 FK 오류 (company_id를 workspace_id로 참조) +**문제**: company vs workspaces 테이블 공존 +**해결**: `plans/250831_workspace_unification_plan.md` 참조 -**해결 계획**: -1. 데이터 백업 -2. company → workspaces 마이그레이션 -3. FK 관계 재설정 -4. 모델 파일 통일 - -### 3. 하드코딩된 URL 제거 🔴 +### 3. 하드코딩 URL 제거 **위치**: -```python -# app/providers/slack.py -login_callback_url = "https://auth.ro-being.com/auth/slack/login/callback" -redirect_uri = "http://localhost:3000" +- `app/providers/slack.py`: login_callback_url +- `frontend-customer/src/contexts/auth-context.tsx`: auth.ro-being.com -# frontend-customer/src/contexts/auth-context.tsx -fetch('https://auth.ro-being.com/auth/verify') -``` - -**해결**: 환경변수로 추출 (dev/staging/prod 분리) +**해결**: 환경변수로 추출 (dev/staging/prod) ### 4. 사용자 매핑 로직 개선 -**문제점**: -- email 변경 시 중복 계정 생성 가능 -- workspace 없이 매핑 불가 -- username 생성 로직 분산 +**문제**: email 변경 시 중복 계정, workspace 없이 매핑 불가 +**해결**: UserIdentityService 통합 서비스 -**해결**: UserIdentityService 통합 서비스 구현 +--- -## ✅ 해결 완료 항목 +## ✅ 해결 완료 -### 2025-09-15 해결 -- Rate Limiting 구현 완료 +- 2025-09-15: Rate Limiting 구현 +- 2025-09-04: python-multipart, Docker 정리 (3.9GB 회수) +- 2025-08-31: Slack OAuth 로그인 구현 -### 2025-09-04 해결 -- python-multipart 의존성 추가 완료 -- Docker dangling 이미지 39개 제거 (3.9GB 회수) -- nginx 권한 644 정상 확인 -- Redis TTL 자동 만료 정상 작동 -- PostgreSQL 테이블 robeings 소유권 확인 -- git config pull.rebase false 설정 완료 +--- -### 2025-08-31 해결 -- Slack OAuth 2.0 로그인 구현 -- Frontend-Backend 인증 방식 통일 (임시 코드 방식) -- Git merge conflict 해결 (커밋: 5bb14a6) +## 🟡 개선 필요 -## 🟡 개선 필요 사항 - -### 보안 강화 +### 보안 - Refresh Token 구현 - PKCE 적용 - 토큰 암호화 저장 ### 코드 품질 -- 에러 처리 개선 (구체적 메시지) +- 에러 처리 개선 - 테스트 추가 (단위/통합/E2E) -- API 문서화 (OpenAPI/Swagger) +- API 문서화 (OpenAPI) -## 📋 작업 요약 +--- -### 완료된 작업 -1. **Slack OAuth 구현**: `/auth/slack/login`, JWT 30일, Redis 60초 TTL -2. **사용자 매핑**: slack_user_mapping 테이블 활용 -3. **프론트엔드 통합**: auth-context.tsx 수정, Gmail과 통일 +## 참고 -### 미해결 과제 -1. **기술 부채**: 임시 코드 제거, DB 스키마 통일 -2. **개선 사항**: 통합 인증 서비스, OAuth 토큰 갱신 -3. **문서화**: API 문서, 배포 가이드, 트러블슈팅 - -## 📌 관련 문서 -- [미해결 항목 매트릭스](./000000_unresolved_items_matrix.md) -- [인증 시스템 아키텍처](../300_architecture/380_authentication_system.md) -- [Slack OAuth 구현](../troubleshooting/250831_slack_oauth_login_implementation.md) - -## 환경변수 위치 -- `/home/admin/auth-server/.env` -- `/home/admin/frontend-customer/.env` - -## 체크리스트 -- [ ] 하드코딩 URL 환경변수화 -- [ ] DB 스키마 통일 (company → workspaces) -- [ ] 임시 코드 방식 제거 -- [ ] UserIdentityService 구현 -- [ ] Refresh Token 구현 -- [ ] PKCE 적용 \ No newline at end of file +- `troubleshooting/250831_slack_oauth_login_implementation.md` +- `plans/250831_workspace_unification_plan.md` +- `book/300_architecture/311_FastAPI_구조_원칙.md` diff --git a/journey/plans/251204_admin_dashboard_business_integration.md b/journey/plans/251204_admin_dashboard_business_integration.md index d8590c3..97ada58 100644 --- a/journey/plans/251204_admin_dashboard_business_integration.md +++ b/journey/plans/251204_admin_dashboard_business_integration.md @@ -1,127 +1,84 @@ # Admin Dashboard 비즈니스 통합 계획 -**날짜**: 2025-12-04 -**작성자**: Auto -**관련 파일**: -- `admin-dashboard/backend/admin_routes.py` -- `admin-dashboard/frontend/index.html` +**날짜**: 2025-12-04 +**목표**: 인프라 모니터링 → 비즈니스 관리 도구 확장 --- -## 목표 - -admin-dashboard를 인프라 모니터링 도구에서 **로빙 프로젝트 비즈니스 관리 도구**로 확장. - ## 현재 상태 ### 기존 기능 (4개 탭) -- **대시보드**: 시스템 메트릭(CPU/메모리/디스크/업타임), Chart.js 그래프 -- **컨테이너**: Docker 컨테이너 목록, 로그 조회, 재시작 -- **서비스**: Nginx 상태, Git 활동 -- **로그**: 시스템 로그 +- 대시보드: CPU/메모리/디스크/업타임 +- 컨테이너: Docker 관리, 로그 조회 +- 서비스: Nginx 상태, Git 활동 +- 로그: 시스템 로그 ### 문제점 -- **main_db 미연결**: user/team/robeing 데이터 접근 불가 -- **FastAPI 원칙 위반**: `admin_routes.py` 1053줄 (권장 300줄 초과), 계층 분리 없음 -- **비즈니스 기능 전무**: 사용자 관리, 로빙 현황, 스킬 통계 없음 +- main_db 미연결 (user/team/robeing 데이터 접근 불가) +- `admin_routes.py` 1053줄 (권장 300줄 초과) +- 비즈니스 기능 전무 -## 개선 계획 (도메인별 계층 분리 + 병렬 처리) +--- -### 1. 파일 구조 리팩토링 (FastAPI 원칙 준수) +## 개선 계획 -**현재 문제**: `admin_routes.py` 1053줄 (300줄 권장 초과) +### 1. FastAPI 계층 분리 -**개선 구조**: +**현재**: admin_routes.py 1053줄 (모든 로직 혼재) + +**목표 구조**: ``` -admin-dashboard/backend/ +backend/ ├── routers/ -│ ├── system.py # 시스템/Docker (기존 기능, ~300줄) -│ ├── users.py # 사용자/팀 관리 (~200줄) -│ └── robeings.py # 로빙/스킬 관리 (~200줄) +│ ├── system.py # 기존 기능 (~300줄) +│ ├── users.py # 사용자/팀 관리 +│ └── robeings.py # 로빙/스킬 관리 ├── services/ -│ ├── user_service.py # 사용자 비즈니스 로직 -│ └── robeing_service.py # 로빙 비즈니스 로직 -├── state/ -│ ├── user_repository.py # main_db user/team CRUD -│ └── robeing_repository.py # main_db robeing/conversation CRUD -└── main.py +│ ├── user_service.py +│ └── robeing_service.py +└── state/ + ├── user_repository.py # main_db 연결 + └── robeing_repository.py ``` -**원칙 준수**: router(HTTP) → service(비즈니스) → repository(DB), DB 접근은 repository에서만 +**원칙**: router → service → repository (311_FastAPI_구조_원칙.md) -### 2. API 스키마 정의 (schemas/) +### 2. 신규 탭 3개 -**패턴 참고**: auth-server의 WorkspaceResponse/WorkspaceCreate 구조 +**탭 1: 사용자/팀** +- 테이블: user/team 목록, 검색/필터 +- 컬럼: email, name, metadata(nickname/position), is_active, last_login_at +- 액션: 편집(metadata), 상세(OAuth 상태), 비활성화 +- 통계: 총 사용자, 활성 사용자, 팀별 분포 -**User 스키마**: -- `UserResponse`: id, email, name, username, metadata(dict), is_active, last_login_at -- `UserUpdate`: name, metadata (부분 업데이트) -- `UserList`: items(list[UserResponse]), total, page, limit +**탭 2: 로빙** +- 테이블: robeing 목록 (team, name, level) +- 시각화: 레이더 차트(5개 stats), 레벨 분포 +- 통계: 총 로빙, 평균 레벨, 팀별 활동량 -**Robeing 스키마**: -- `RobeingResponse`: id, team_id, name, level, stats(memory/compute/react/empathy/leadership) -- `RobeingStats`: 대화 빈도, 스킬 사용 횟수, 감정 트렌드 +**탭 3: 스킬/의도** +- 대시보드: 의도 분류 통계, 스킬 실행 횟수 +- 차트: 시간대별 히트맵, 의도 분포 파이 +- 테이블: rb_news, team_document, ir_deck_evaluations -**공통**: -- `PaginationParams`: limit(기본 50), offset(기본 0) -- `ErrorResponse`: detail(str), code(int) -- metadata JSONB는 `dict[str, Any]`로 직렬화 +### 3. 성능 최적화 -### 3. 페이지네이션 전략 +**병렬 처리**: `asyncio.gather()`로 다중 DB 조회 동시 실행 +**페이지네이션**: limit/offset (기본 50건) -**기본 방식**: 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% 성능 향상) -**검증 완료**: 계층 분리는 성능 오버헤드 없음 (테스트 확인) - -### 5. 신규 탭 3개 (UX 중심) - -#### 탭 1: 사용자/팀 -- **테이블 뷰**: user/team 목록, 검색/필터/정렬 -- **컬럼**: email, name, username, metadata(nickname/position), is_active, last_login_at -- **액션 버튼**: 편집(metadata 수정 모달), 상세보기(OAuth 연동 상태), 비활성화 -- **통계 카드**: 총 사용자 수, 활성 사용자, 팀별 사용자 분포 - -#### 탭 2: 로빙 -- **테이블 뷰**: robeing 목록(team_id, name, level) -- **시각화**: 레이더 차트(memory/compute/react/empathy/leadership), 레벨 분포 막대 그래프 -- **액션**: 로빙 상세(대화 빈도, 스킬 사용 이력), 팀별 비교 -- **통계 카드**: 총 로빙 수, 평균 레벨, 팀별 활동량(conversation_log 기반) - -#### 탭 3: 스킬/의도 -- **대시보드**: 의도 분류 통계(intents), 스킬 실행 횟수(뉴스/이메일/IR분석), LLM 호출 추이 -- **차트**: 히트맵(시간대별 스킬 사용), 파이 차트(의도 분포) -- **테이블**: rb_news(최근 발행), team_document(RAG 문서), ir_deck_evaluations(IR 평가 현황) - -### 6. 공통 UI 패턴 -- **우측 상단**: 새로고침/필터/CSV 다운로드 버튼 -- **테이블 행**: 편집/삭제/상세 아이콘 버튼 -- **모달**: metadata 편집, 상세 정보 표시 -- **차트**: Chart.js, 일/주/월 필터 +--- ## 구현 단계 -1. **기존 파일 분리**: `admin_routes.py`(1053줄) → `routers/system.py`(~300줄) 분리 -2. **Repository 레이어**: `state/user_repository.py`, `state/robeing_repository.py` 생성 (main_db 연결) -3. **Service 레이어**: `services/user_service.py`, `services/robeing_service.py` 생성 -4. **Router 추가**: `routers/users.py`, `routers/robeings.py` 생성 (asyncio.gather() 병렬 처리) -5. **Frontend**: 3개 탭 추가, 테이블/차트 컴포넌트, metadata 편집 모달 -6. **테스트**: 성능(병렬 처리 확인), CRUD, UI 동작 검증 +1. admin_routes.py → routers/system.py 분리 +2. Repository/Service 레이어 생성 +3. main_db 연결 추가 +4. 3개 신규 router 추가 +5. Frontend 3개 탭 추가 + +--- ## 참고 -- 문서 작성 원칙: `DOCS/book/300_architecture/312_문서_작성_원칙.md` -- 기존 admin 리팩토링: `DOCS/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md` - +- `311_FastAPI_구조_원칙.md` +- `troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md`