docs: 마지막 2개 plan 문서 간결화 (127줄 삭제)
This commit is contained in:
parent
fc3406889f
commit
9df5ede314
@ -1,106 +1,58 @@
|
|||||||
# 기술 부채 정리
|
# 기술 부채 정리
|
||||||
|
|
||||||
## 작성일: 2025년 8월 31일
|
**날짜**: 2025-08-31
|
||||||
## 최종 수정: 2025년 9월 15일
|
**최종 수정**: 2025-09-15
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## 🔴 미해결 주요 이슈
|
## 🔴 미해결 주요 이슈
|
||||||
|
|
||||||
### 1. 임시 코드 방식 제거 필요
|
### 1. 임시 코드 방식 제거
|
||||||
**현재 상황**:
|
**현재**: Gmail/Slack → 임시 코드 → `/auth/verify` → JWT
|
||||||
- Gmail/Slack 모두 임시 코드 → `/auth/verify` → JWT
|
**문제**: Redis 의존성, 60초 TTL 제한
|
||||||
- 불필요한 Redis 의존성, 60초 TTL 제한
|
**개선**: JWT 직접 전달 또는 Secure cookie
|
||||||
|
|
||||||
**개선 방안**:
|
|
||||||
- JWT 직접 전달 또는 Secure cookie 사용
|
|
||||||
- Redis 의존성 제거
|
|
||||||
|
|
||||||
### 2. DB 스키마 불일치
|
### 2. DB 스키마 불일치
|
||||||
**문제**:
|
**문제**: company vs workspaces 테이블 공존
|
||||||
- company vs workspaces 테이블 공존
|
**해결**: `plans/250831_workspace_unification_plan.md` 참조
|
||||||
- SlackWorkspace 모델 FK 오류 (company_id를 workspace_id로 참조)
|
|
||||||
|
|
||||||
**해결 계획**:
|
### 3. 하드코딩 URL 제거
|
||||||
1. 데이터 백업
|
|
||||||
2. company → workspaces 마이그레이션
|
|
||||||
3. FK 관계 재설정
|
|
||||||
4. 모델 파일 통일
|
|
||||||
|
|
||||||
### 3. 하드코딩된 URL 제거 🔴
|
|
||||||
**위치**:
|
**위치**:
|
||||||
```python
|
- `app/providers/slack.py`: login_callback_url
|
||||||
# app/providers/slack.py
|
- `frontend-customer/src/contexts/auth-context.tsx`: auth.ro-being.com
|
||||||
login_callback_url = "https://auth.ro-being.com/auth/slack/login/callback"
|
|
||||||
redirect_uri = "http://localhost:3000"
|
|
||||||
|
|
||||||
# frontend-customer/src/contexts/auth-context.tsx
|
**해결**: 환경변수로 추출 (dev/staging/prod)
|
||||||
fetch('https://auth.ro-being.com/auth/verify')
|
|
||||||
```
|
|
||||||
|
|
||||||
**해결**: 환경변수로 추출 (dev/staging/prod 분리)
|
|
||||||
|
|
||||||
### 4. 사용자 매핑 로직 개선
|
### 4. 사용자 매핑 로직 개선
|
||||||
**문제점**:
|
**문제**: email 변경 시 중복 계정, workspace 없이 매핑 불가
|
||||||
- email 변경 시 중복 계정 생성 가능
|
**해결**: UserIdentityService 통합 서비스
|
||||||
- workspace 없이 매핑 불가
|
|
||||||
- username 생성 로직 분산
|
|
||||||
|
|
||||||
**해결**: UserIdentityService 통합 서비스 구현
|
---
|
||||||
|
|
||||||
## ✅ 해결 완료 항목
|
## ✅ 해결 완료
|
||||||
|
|
||||||
### 2025-09-15 해결
|
- 2025-09-15: Rate Limiting 구현
|
||||||
- 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 구현
|
- Refresh Token 구현
|
||||||
- PKCE 적용
|
- PKCE 적용
|
||||||
- 토큰 암호화 저장
|
- 토큰 암호화 저장
|
||||||
|
|
||||||
### 코드 품질
|
### 코드 품질
|
||||||
- 에러 처리 개선 (구체적 메시지)
|
- 에러 처리 개선
|
||||||
- 테스트 추가 (단위/통합/E2E)
|
- 테스트 추가 (단위/통합/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과 통일
|
|
||||||
|
|
||||||
### 미해결 과제
|
- `troubleshooting/250831_slack_oauth_login_implementation.md`
|
||||||
1. **기술 부채**: 임시 코드 제거, DB 스키마 통일
|
- `plans/250831_workspace_unification_plan.md`
|
||||||
2. **개선 사항**: 통합 인증 서비스, OAuth 토큰 갱신
|
- `book/300_architecture/311_FastAPI_구조_원칙.md`
|
||||||
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 적용
|
|
||||||
|
|||||||
@ -1,127 +1,84 @@
|
|||||||
# Admin Dashboard 비즈니스 통합 계획
|
# Admin Dashboard 비즈니스 통합 계획
|
||||||
|
|
||||||
**날짜**: 2025-12-04
|
**날짜**: 2025-12-04
|
||||||
**작성자**: Auto
|
**목표**: 인프라 모니터링 → 비즈니스 관리 도구 확장
|
||||||
**관련 파일**:
|
|
||||||
- `admin-dashboard/backend/admin_routes.py`
|
|
||||||
- `admin-dashboard/frontend/index.html`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 목표
|
|
||||||
|
|
||||||
admin-dashboard를 인프라 모니터링 도구에서 **로빙 프로젝트 비즈니스 관리 도구**로 확장.
|
|
||||||
|
|
||||||
## 현재 상태
|
## 현재 상태
|
||||||
|
|
||||||
### 기존 기능 (4개 탭)
|
### 기존 기능 (4개 탭)
|
||||||
- **대시보드**: 시스템 메트릭(CPU/메모리/디스크/업타임), Chart.js 그래프
|
- 대시보드: CPU/메모리/디스크/업타임
|
||||||
- **컨테이너**: Docker 컨테이너 목록, 로그 조회, 재시작
|
- 컨테이너: Docker 관리, 로그 조회
|
||||||
- **서비스**: Nginx 상태, Git 활동
|
- 서비스: Nginx 상태, Git 활동
|
||||||
- **로그**: 시스템 로그
|
- 로그: 시스템 로그
|
||||||
|
|
||||||
### 문제점
|
### 문제점
|
||||||
- **main_db 미연결**: user/team/robeing 데이터 접근 불가
|
- main_db 미연결 (user/team/robeing 데이터 접근 불가)
|
||||||
- **FastAPI 원칙 위반**: `admin_routes.py` 1053줄 (권장 300줄 초과), 계층 분리 없음
|
- `admin_routes.py` 1053줄 (권장 300줄 초과)
|
||||||
- **비즈니스 기능 전무**: 사용자 관리, 로빙 현황, 스킬 통계 없음
|
- 비즈니스 기능 전무
|
||||||
|
|
||||||
## 개선 계획 (도메인별 계층 분리 + 병렬 처리)
|
---
|
||||||
|
|
||||||
### 1. 파일 구조 리팩토링 (FastAPI 원칙 준수)
|
## 개선 계획
|
||||||
|
|
||||||
**현재 문제**: `admin_routes.py` 1053줄 (300줄 권장 초과)
|
### 1. FastAPI 계층 분리
|
||||||
|
|
||||||
**개선 구조**:
|
**현재**: admin_routes.py 1053줄 (모든 로직 혼재)
|
||||||
|
|
||||||
|
**목표 구조**:
|
||||||
```
|
```
|
||||||
admin-dashboard/backend/
|
backend/
|
||||||
├── routers/
|
├── routers/
|
||||||
│ ├── system.py # 시스템/Docker (기존 기능, ~300줄)
|
│ ├── system.py # 기존 기능 (~300줄)
|
||||||
│ ├── users.py # 사용자/팀 관리 (~200줄)
|
│ ├── users.py # 사용자/팀 관리
|
||||||
│ └── robeings.py # 로빙/스킬 관리 (~200줄)
|
│ └── robeings.py # 로빙/스킬 관리
|
||||||
├── services/
|
├── services/
|
||||||
│ ├── user_service.py # 사용자 비즈니스 로직
|
│ ├── user_service.py
|
||||||
│ └── robeing_service.py # 로빙 비즈니스 로직
|
│ └── robeing_service.py
|
||||||
├── state/
|
└── state/
|
||||||
│ ├── user_repository.py # main_db user/team CRUD
|
├── user_repository.py # main_db 연결
|
||||||
│ └── robeing_repository.py # main_db robeing/conversation CRUD
|
└── robeing_repository.py
|
||||||
└── main.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 스키마**:
|
**탭 2: 로빙**
|
||||||
- `UserResponse`: id, email, name, username, metadata(dict), is_active, last_login_at
|
- 테이블: robeing 목록 (team, name, level)
|
||||||
- `UserUpdate`: name, metadata (부분 업데이트)
|
- 시각화: 레이더 차트(5개 stats), 레벨 분포
|
||||||
- `UserList`: items(list[UserResponse]), total, page, limit
|
- 통계: 총 로빙, 평균 레벨, 팀별 활동량
|
||||||
|
|
||||||
**Robeing 스키마**:
|
**탭 3: 스킬/의도**
|
||||||
- `RobeingResponse`: id, team_id, name, level, stats(memory/compute/react/empathy/leadership)
|
- 대시보드: 의도 분류 통계, 스킬 실행 횟수
|
||||||
- `RobeingStats`: 대화 빈도, 스킬 사용 횟수, 감정 트렌드
|
- 차트: 시간대별 히트맵, 의도 분포 파이
|
||||||
|
- 테이블: rb_news, team_document, ir_deck_evaluations
|
||||||
|
|
||||||
**공통**:
|
### 3. 성능 최적화
|
||||||
- `PaginationParams`: limit(기본 50), offset(기본 0)
|
|
||||||
- `ErrorResponse`: detail(str), code(int)
|
|
||||||
- metadata JSONB는 `dict[str, Any]`로 직렬화
|
|
||||||
|
|
||||||
### 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줄) 분리
|
1. admin_routes.py → routers/system.py 분리
|
||||||
2. **Repository 레이어**: `state/user_repository.py`, `state/robeing_repository.py` 생성 (main_db 연결)
|
2. Repository/Service 레이어 생성
|
||||||
3. **Service 레이어**: `services/user_service.py`, `services/robeing_service.py` 생성
|
3. main_db 연결 추가
|
||||||
4. **Router 추가**: `routers/users.py`, `routers/robeings.py` 생성 (asyncio.gather() 병렬 처리)
|
4. 3개 신규 router 추가
|
||||||
5. **Frontend**: 3개 탭 추가, 테이블/차트 컴포넌트, metadata 편집 모달
|
5. Frontend 3개 탭 추가
|
||||||
6. **테스트**: 성능(병렬 처리 확인), CRUD, UI 동작 검증
|
|
||||||
|
---
|
||||||
|
|
||||||
## 참고
|
## 참고
|
||||||
|
|
||||||
- 문서 작성 원칙: `DOCS/book/300_architecture/312_문서_작성_원칙.md`
|
- `311_FastAPI_구조_원칙.md`
|
||||||
- 기존 admin 리팩토링: `DOCS/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md`
|
- `troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md`
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user