9.5 KiB
다중 프로젝트 관리자 통합 대시보드 설계
1. 목적
한 명의 관리자가 여러 프로젝트의 관리자로 지정된 경우, 로그인 직후 각 프로젝트의 주요 현황을 한 화면에서 확인할 수 있는 통합 대시보드를 제공한다.
기존 프로젝트별 대시보드는 유지하고, 여러 프로젝트를 한 화면에서 확인하고 처리하기 위한 전역 관리자 작업공간을 추가한다. 이 화면은 특정 프로젝트에 종속되지 않으며 로그인 후 홈 버튼으로 언제든 접근할 수 있다.
2. 기본 진입 규칙
로그인 완료 후 /main에서 현재 사용자가 관리할 수 있는 프로젝트 수를 확인한다.
| 조건 | 로그인 후 기본 화면 |
|---|---|
| 관리 프로젝트 0개 | 프로젝트 없음 안내 화면 |
| 관리 프로젝트 1개 | 기존 프로젝트 대시보드 |
| 관리 프로젝트 2개 이상 | 통합 관리자 대시보드 |
| SUPER 관리자 | 전체 프로젝트 통합 대시보드 |
관리 프로젝트는 기존 프로젝트 멤버 역할 중 PROJECT_MANAGER 또는 Admin에 해당하는 프로젝트로 정의한다.
3. 라우팅
신규 통합 대시보드
/main/overview
기존 프로젝트별 화면
/main/project/[projectId]/dashboard
/main/project/[projectId]/feedback
/main/project/[projectId]/issue
/main/project/[projectId]/settings
통합 대시보드는 특정 projectId 없이 접근한다. 프로젝트별 상세 작업은 기존 프로젝트 라우트로 이동한다.
4. 화면 구성
4.1 전체 요약 카드
접근 가능한 프로젝트 전체를 기준으로 다음 지표를 표시한다. 카드와 Todo 목록은 같은 조회 기간·프로젝트 범위를 사용한다.
- 전체 피드백 건수
- 답변 대기 건수
- 이슈 연결률
- 평균 처리 시간
- 진행 중 이슈 건수
- 완료 피드백 건수
- 현재 작업공간에서 처리할 Todo 건수
- 담당자 미지정 건수
- 피드백 상태 처리 필요 건수
- 이슈 연결 또는 이슈 상태 처리 필요 건수
4.2 하위 탭
전역 작업공간은 처리 대상에 따라 두 개의 하위 탭으로 나눈다.
- 피드백 처리: 오늘 등록 건수 등의 요약, 담당자 지정, 관리자 댓글 등록, 피드백 상태 처리, 연결 이슈 요약을 표시한다.
- 이슈 처리: 프로젝트별 이슈를 중복 없이 묶어 Gitea 연결·상태 처리와 연결된 피드백 목록을 표시한다.
4.3 관리자 Todo 작업 목록
전역 작업공간의 핵심은 여러 프로젝트의 피드백을 한 목록에서 처리하는 것이다.
| 작업 | 처리 방식 |
|---|---|
| 프로젝트 확인 | 프로젝트별 피드백 화면 링크 제공 |
| 담당자 지정 | 해당 프로젝트의 지원 담당자 후보 조회 후 지정·해제 |
| 피드백 상태 | 기존 지원 티켓 상태 API로 상태 변경 |
| 이슈 연결 | 기존 프로젝트 이슈 검색 후 피드백과 연결·해제 |
| 이슈 상태 | 기존 6단계 이슈 상태로 변경 |
| Gitea 연결 | Gitea 검색 결과를 기존 이슈에 연결 |
| Gitea 상태 | 연결된 외부 이슈 상태 조회·새로고침 |
피드백 상태와 이슈 상태는 서로 독립적으로 처리한다. 이슈 상태 변경은 내부 이슈 상태를 기준으로 저장하며, Gitea 연결 이슈가 있는 경우 외부 상태 동기화를 시도한다.
4.4 프로젝트별 요약 테이블
| 항목 | 설명 |
|---|---|
| 프로젝트 | 프로젝트명 및 프로젝트 이동 링크 |
| 피드백 | 프로젝트의 전체 피드백 건수 |
| 답변 대기 | 답변 또는 이슈 처리가 완료되지 않은 피드백 건수 |
| 이슈 연결률 | 이슈가 연결된 피드백 비율 |
| 평균 처리 시간 | 처리 완료된 피드백의 평균 처리 시간 |
| 상태별 건수 | 피드백 상태별 건수 요약 |
| 최근 업데이트 | 해당 프로젝트의 최근 변경 시각 |
프로젝트 행 또는 프로젝트명을 클릭하면 해당 프로젝트의 기존 대시보드로 이동한다.
4.5 필터
다음 필터를 제공한다.
- 기간 필터
- 프로젝트 필터
- 담당자 지정 여부
- 피드백 상태
- 이슈 연결 여부
현재 단계에서는 행 단위 처리를 제공한다. 추후 현재 로그인 사용자 기준의 정확한 “내 담당” 필터, 일괄 상태 변경, 댓글·내부 메모 입력을 확장한다.
5. 백엔드 API 설계
프로젝트별 API를 프론트엔드에서 반복 호출하지 않고, 통합 집계 API를 제공한다.
GET /api/admin/dashboard/overview
요청 파라미터
from
to
projectIds[]
feedbackStatus
assigned
응답 예시
{
"summary": {
"totalFeedback": 73,
"waitingReply": 16,
"issueLinkedRate": 0.58,
"averageProcessingHours": 20.4
},
"projects": [
{
"projectId": 1,
"projectName": "Q&A",
"feedbackCount": 55,
"waitingReplyCount": 12,
"issueLinkedRate": 0.67,
"averageProcessingHours": 24.5,
"statusCounts": {
"INIT": 10,
"IN_PROGRESS": 20,
"DONE": 25
}
}
]
}
6. 집계 기준
기존 프로젝트 대시보드와 동일한 기준을 사용한다.
- 이슈 연결률은 전체 피드백 중 이슈가 연결된 피드백의 비율로 계산한다.
- 답변 대기는 답변이 없거나 이슈 처리가 완료되지 않은 피드백 건수로 계산한다.
- 평균 처리 시간은 처리 완료된 피드백만 대상으로 계산한다.
- 여러 프로젝트의 평균 처리 시간은 프로젝트별 평균을 다시 평균내지 않고, 전체 처리 시간 합계를 전체 처리 완료 건수로 나누어 계산한다.
- 상태별 건수는 피드백 상태값 기준으로 집계한다.
- 이슈 상태와 피드백 상태는 서로 독립적으로 집계한다.
7. 권한 및 보안
통합 API는 서버에서 사용자의 프로젝트 접근 권한을 다시 검증해야 한다.
- 일반 관리자는 자신이 관리자로 등록된 프로젝트만 조회한다.
SUPER관리자는 전체 프로젝트를 조회할 수 있다.- 요청한
projectIds중 접근 권한이 없는 프로젝트는 결과에서 제외하거나403 Forbidden으로 처리한다. - 프론트엔드의 프로젝트 목록 제한은 UI 편의 기능일 뿐, 최종 권한 검증은 백엔드에서 수행한다.
현재 프로젝트 멤버십 및 역할 구조를 재사용하며, 1차 구현에서는 별도 상위 프로젝트 테이블을 추가하지 않는다.
8. 헤더 및 전역 홈 UI
통합 대시보드는 프로젝트 선택 항목이 아니라 전역 홈 버튼으로 접근한다.
- 홈 버튼:
/main/overview - 프로젝트 선택: 개별 프로젝트 화면 이동 전용
- 프로젝트 대시보드·피드백·이슈·설정:
projectId필요
이렇게 분리하면 프로젝트 선택값을 바꾸지 않고도 여러 프로젝트의 Todo를 처리할 수 있고, 기존 프로젝트별 작업 흐름도 유지된다.
9. 1차 구현 작업 순서
- 통합 대시보드 API의 요청·응답 DTO 정의
- 프로젝트 접근 권한 범위 조회 로직 구현
- 여러 프로젝트 피드백·이슈 집계 서비스 구현
/main/overview페이지 추가- 전체 요약 카드 구현
- 프로젝트별 요약 테이블 구현
- 기간·프로젝트·상태·내 담당 필터 구현
- 로그인 후 기본 라우팅 분기 구현
- 전역 홈 버튼 및 프로젝트 선택 UI 분리
- Todo 작업 목록과 행 단위 명령 처리 구현
- 이슈·Gitea 상태 동기화 API 연결
- 권한·라우팅·집계 테스트 작성
10. 향후 확장
부서별 또는 서비스군별로 프로젝트를 직접 묶고, 상위 관리자가 그룹을 관리해야 하는 요구가 생기면 별도 그룹 엔티티를 추가한다.
portfolio
└── projects
현재 단계에서는 DB에 상위 프로젝트 개념을 추가하지 않고, 사용자의 프로젝트 접근 권한을 기반으로 한 가상 통합 대시보드로 구현한다.
11. 1차 구현 상태
전역 관리자 작업공간의 1차 기능을 적용했다. 프로젝트별 화면과 기존 권한 검증은 유지하고, /main/overview에서 접근 가능한 프로젝트의 Todo를 통합 조회·처리한다.
/api/admin/dashboard/overview집계 API에todos응답 추가- 관리자별 프로젝트 접근 권한 검증
- 프로젝트별 피드백·이슈 집계
/main/overview전역 작업공간 화면 추가- 홈 버튼으로 전역 화면 접근, 프로젝트 선택과 분리
- 전체 요약 카드 및 프로젝트별 요약 테이블 유지
- 기간·프로젝트·담당자 지정·피드백 상태·이슈 연결 필터 추가
- 피드백 담당자 지정·해제
- 피드백 상태 변경
- 관리자 댓글 등록
- 이슈 연결·해제 및 내부 이슈 6단계 상태 변경
- Gitea 이슈 검색·연결 및 외부 상태 새로고침
- 내부 이슈 상태 변경 시 연결된 Gitea 이슈 동기화 시도
- 피드백 상태와 이슈 상태를 독립적으로 처리하는 구조 유지
현재 Todo 목록은 프로젝트별 최근 피드백을 최대 500건까지 집계하며, 대량 데이터에 대한 서버 페이지네이션·가상 스크롤은 후속 작업이다. 내부 메모·일괄 처리와 이슈 처리 탭의 추가 일괄 작업은 기존 프로젝트별 API 권한을 재사용해 다음 단계로 확장한다.