역할/권한 관련 문의 대응
고객이 역할 또는 권한 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.
1. 증상 목록
| # | 고객이 말하는 증상 (UI 기준) | 섹션 |
|---|---|---|
| S-1 | "특정 메뉴가 안 보입니다 / 접근이 안 됩니다" | 2.1 |
| S-2 | "권한을 변경했는데 즉시 반영이 안 됩니다" | 2.2 |
| S-3 | "역할 생성/수정 시 오류가 납니다" | 2.3 |
2. 증상별 대응 가이드
2.1 S-1: 메뉴가 안 보인다
증상: 로그인 후 특정 메뉴(트랜잭션 익스플로러, 역할 관리, 시스템 설정 등)가 사이드바에 표시되지 않거나 클릭 시 접근 거부 메시지가 표시된다.
고객에게 확인
- 어떤 역할(Role)로 로그인했는가? (
설정 > 내 정보화면에서 확인) - 관리자가 해당 역할에 메뉴 권한을 부여했는가?
- 다른 사용자(같은 역할)도 같은 증상인가?
확인 경로: 설정 > 역할 관리 > [해당 역할] > 기능 권한
확인 항목: 문제가 되는 메뉴의 체크박스 활성 여부
기술지원 확인
- 역할 해시 확인:
curl http://localhost:6600/api/flowkat/config/role/{roleHash}
# 200 OK 및 funcAuth 내용 확인
- Zustand Store에서 역할 권한 확인 (브라우저 콘솔):
// 브라우저 F12 > Console
useRoleStore.getState().currentRole
// currentRole 객체 내 roleHash 값 확인
useRoleStore.getState().funcAuth
// funcAuth 객체 내 메뉴별 권한 값 확인
- API 서버 역할 API 확인:
docker compose logs dashboard-server --tail 100 | grep -i "role\|funcAuth\|403"
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| 역할 API 응답 | 200 OK + funcAuth 포함 | 403 또는 빈 funcAuth |
| Zustand roleHash | 값 존재 | undefined 또는 null |
| 역할 관리 화면 | 메뉴 체크박스 활성 | 비활성 |
벤더 에스컬레이션 시 전달 정보
- 역할 이름 및 roleHash 값
-
/api/flowkat/config/role/{roleHash}응답 전문 - 역할 관리 화면 캡처 (기능 권한 탭)
- 증상 발생 계정의 workgroupId 및 로그인 시각
2.2 S-2: 권한 변경이 즉시 반영 안 된다
증상: 관리자가 역할 권한을 변경했으나, 해당 역할로 로그인한 사용자 화면에 즉시 반영되지 않는다.
고객에게 확인
- 관리자가 저장 버튼을 눌렀는가? (화면에 성공 메시지 떴는가?)
- 변경 대상 사용자가 현재 로그인 상태인가?
- 브라우저 콘솔에 WebSocket 관련 에러가 있는가?
기술지원 확인
- WebSocket 연결 상태 확인 (변경 대상 사용자 브라우저 콘솔):
브라우저 DevTools > Network 탭 > WS (WebSocket) 필터를 선택한다.
WebSocket 연결이 활성 상태이면 목록에 ws 프레임이 표시된다.
연결이 없으면 WebSocket 핸드셰이크 실패 여부를 확인한다.
STOMP 구독 주소: /topic/workgroup/{workgroupId}/roles
- Dashboard 서버 WebSocket 이벤트 확인:
docker compose logs dashboard-server --tail 100 | grep -i "updateRolePermissions\|websocket\|stomp"
- nginx WebSocket 프록시 설정 확인:
docker exec flowkat-ui-server grep -A5 "api/flowkat" /etc/nginx/http.d/default.conf | grep -i "upgrade"
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| WebSocket 연결 | DevTools Network WS 탭에서 활성 연결 확인 | WS 연결 없음 또는 오류 |
| STOMP 구독 | /topic/workgroup/*/roles 구독 | 구독 없음 |
| Server Action | 로그에 updateRolePermissions 성공 | 실패 로그 |
벤더 에스컬레이션 시 전달 정보
- 권한 변경 시각 및 변경 내용 (어떤 역할, 어떤 메뉴)
- Dashboard 서버 로그 (변경 전후 5분)
- 변경 대상 사용자 브라우저 콘솔 캡처
- WebSocket 연결 상태 (DevTools Network WS 탭 확인 결과)
- nginx WebSocket 설정 (
api/flowkatlocation 블록)
2.3 S-3: 역할 생성/수정 오류
증상: 역할 관리(설정 > 역할 관리) 화면에서 역할 생성 또는 수정 시 오류 메시지가 표시된다.
고객에게 확인
- 어떤 화면에서 어떤 동작 중 오류가 발생했는가?
- 화면에 표시된 에러 메시지를 정확히 알려달라.
- 관리자 권한 계정으로 로그인한 상태인가?
기술지원 확인
# API 서버 에러 확인
docker compose logs dashboard-server --tail 100 | grep -i "role\|error\|exception"
# 역할 관련 API 직접 테스트
curl -X GET http://localhost:6600/api/flowkat/config/role/list \
-H "Authorization: Bearer {token}"
벤더 에스컬레이션 시 전달 정보
- 에러 발생 화면 캡처
- 브라우저 Network 탭 (실패한 API 요청 응답 코드 및 본문)
- Dashboard 서버 에러 로그 (오류 발생 전후 10분)
- 역할 생성 시도 내용 (이름, 권한 목록)
3. 관련 문서
| 모듈 | 관련 trouble-shooting | 핵심 이슈 |
|---|---|---|
| 권한 실시간 업데이트 | 025-role-permission-realtime | WebSocket 권한 반영 |
| 역할 CRUD | 008-role-management-crud | 역할 생성/수정 |
| 역할 직렬화 | 017-role-target-direct-serialization | 직렬화 오류 |
| 기능 권한 매핑 | 013-role-funcauth-mapping-dev-menu-filter | 메뉴 필터링 |