Q-A_test/docs/architecture_secretary_sso_role_access.md

# BARON-SSO 권한 및 접근 제어 설계

## 1. 문서 목적

본 문서는 BARON-SSO 연동 시점에 필요한 역할 분리, 테넌트 전략, 로그인 후 페이지 분기, 프로젝트/채널 접근 제어 규칙을 별도로 정리한 문서임.

핵심 목적은 다음과 같음.

- 개발자, 담당자, 사용자의 권한 범위를 명확히 구분함.
- BARON-SSO `tenant_id` 와 우리 시스템의 페이지 분기 기준을 연결함.
- Q&A 관리자 전용 테넌트와 일반 사용자 테넌트의 진입 흐름을 분리 정의함.
- 프로젝트, 채널, 문의 구분, 관리자 콘솔 처리 구조를 현재 구현 방향 기준으로 문서화함.
- 이후 실제 SSO 구현, 테넌트 생성, 라우팅, 권한 테이블 설계의 기준 문서로 사용함.

## 2. 적용 대상 범위

- 인증 원본: BARON-SSO
- 사용자 화면: `/support/[workspaceCode]/new`, `/support/[workspaceCode]/list`, `/support/[workspaceCode]/[ticketId]`
- 관리자 콘솔: `/main/project/[projectId]/feedback?channelId=[channelId]`
- 운영 보조 화면: `/ops`, `/admin/issues`
- 제어 백엔드: `apps/secretary-api`
- 관리자 API: `apps/api`

## 3. 역할 정의

| 역할 | 영문 역할명 | 주요 권한 | 접근 범위 | 로그인 후 기본 진입 화면 |
| --- | --- | --- | --- | --- |
| 개발자 | `SYSTEM_ADMIN`, `SUPER_ADMIN` | 시스템 전체 설정, SSO 연동 관리, 테넌트 관리, 프로젝트/채널 생성 및 삭제, 권한 정책 변경 | 모든 프로젝트, 모든 채널, 모든 관리자 기능 | 관리자 콘솔 또는 시스템 설정 화면 |
| 담당자 | `CHANNEL_MANAGER`, `PROJECT_MANAGER` | 배정된 프로젝트/채널의 피드백 조회, 댓글 처리, 이슈 연동, 채널 운영, 담당자 간 업무 분배 | 본인이 속한 관리자 테넌트 내부의 프로젝트/채널 | 관리자 콘솔 |
| 사용자 | `END_USER`, `FEEDBACK_PROVIDER` | 피드백 작성, 본인 글 조회, 본인 글 상태 확인, 공개된 Q&A 확인 | 본인이 진입한 프로젝트/채널과 본인 작성 데이터 | 사용자 피드백 작성 페이지 |

## 4. 권한 모델 핵심 원칙

### 4.1 1차 판정 기준

- 로그인 자체는 모두 BARON-SSO에서 처리함.
- 우리 시스템은 BARON-SSO 세션 또는 userinfo 기준으로 `user_id`, `tenant_id`, `role_keys` 를 받음.
- 1차 분기는 `Q&A 관리자 전용 tenant` 포함 여부로 처리함.

### 4.2 2차 판정 기준

- 관리자 테넌트에 속한 사용자는 관리자 콘솔 진입 대상으로 처리함.
- 그 외 사용자는 일반 사용자로 처리함.
- 추가 세부 권한은 `tenant_id + project + channel + role` 조합으로 제한함.

### 4.3 3차 판정 기준

- 관리자 콘솔에 진입한 이후에는 프로젝트/채널별 접근 권한을 다시 확인함.
- 동일 관리자 테넌트 소속이라도 모든 프로젝트를 다 보는 구조로 고정하지 않고, 이후 프로젝트/채널별 세분화가 가능하도록 설계함.

## 5. 테넌트 전략

### 5.1 신규 테넌트 구성

- BARON-SSO에 `Q&A 관리자 테넌트`를 신규 생성함.
- 이 테넌트에 속한 인원은 Q&A 관리 권한 후보군으로 사용함.
- 이외 나머지 일반 테넌트 사용자는 사용자 피드백 작성 화면으로 이동시킴.

### 5.2 테넌트 기반 분기 규칙

| BARON-SSO 테넌트 | 기본 사용자 분류 | 기본 이동 경로 | 추가 분기 |
| --- | --- | --- | --- |
| `Q&A 관리자 테넌트` | 관리자/담당자 | 관리자 콘솔 | 프로젝트/채널별 접근 제한 적용 |
| 일반 사용자 테넌트 | 사용자 | 프로젝트별 피드백 작성 페이지 | 본인 글 목록/상세 접근 허용 |

## 6. 로그인 후 페이지 분기 정책

### 6.1 관리자 테넌트 사용자

- 로그인 성공 후 관리자 콘솔로 이동함.
- 기본 진입 후보 경로는 다음과 같음.
- `/main/project/[projectId]/feedback?channelId=[channelId]`
- 필요 시 운영 보조 화면 `/ops`, `/admin/issues` 로 이동 가능
- 이후 프로젝트/채널별 권한에 따라 진입 가능한 콘솔 페이지를 다시 제한함.

### 6.2 일반 사용자

- 로그인 성공 후 각 소프트웨어 또는 서비스가 지정한 피드백 작성 페이지로 이동함.
- 진입 URL에는 프로젝트/채널에 대응되는 `workspaceCode` 또는 서비스 식별자가 함께 전달됨.
- 예시
- `/support/EGBIM/new`
- `/support/TOVA/new`
- `/support/GAIA/new`
- `/support/KNGIL/new`
- `/support/INTRANET_QNA/new`

## 7. 프로젝트 및 채널 초기 운영 구조

### 7.1 초기 프로젝트 생성 대상

| 프로젝트명 | 설명 | 최초 기본 채널 |
| --- | --- | --- |
| `EGBIM` | EGBIM 전용 Q&A | `EGBIM` |
| `TOVA` | TOVA 전용 Q&A | `TOVA` |
| `GAIA` | GAIA 전용 Q&A | `GAIA` |
| `KNGIL` | KNGIL 전용 Q&A | `KNGIL` |
| `INTRANET_QNA` | 인트라넷 공통 Q&A | `INTRANET_QNA` |

### 7.2 채널 운영 확장 계획

- 최초에는 프로젝트당 채널 1개로 시작함.
- 이후 각 프로젝트 내부에서 채널을 별도로 확장하여 문의 유형별로 분리 관리함.
- 예시
- `EGBIM > 일반 문의`, `EGBIM > 장애 문의`, `EGBIM > 기능 개선`
- `INTRANET_QNA > 계정 문의`, `INTRANET_QNA > 권한 문의`, `INTRANET_QNA > 시스템 오류`

## 8. 사용자 진입 구조

### 8.1 기본 시나리오

1. 사용자는 각 소프트웨어에서 이미 BARON-SSO 로그인 상태임.
2. 사용자가 Q&A 이동 버튼을 클릭함.
3. 소프트웨어는 자기 프로젝트에 대응되는 Q&A 진입 URL로 이동시킴.
4. 우리 시스템은 세션에서 `user_id`, `tenant_id` 를 읽음.
5. 관리자 테넌트 여부를 판단함.
6. 일반 사용자면 해당 프로젝트의 작성 페이지로 이동함.
7. 관리자 테넌트면 관리자 콘솔로 이동함.

### 8.2 프로젝트별 사용자 진입 예시

| 진입 서비스 | 사용자 이동 경로 | 관리자 이동 경로 |
| --- | --- | --- |
| EGBIM | `/support/EGBIM/new` | `/main/project/[egbimProjectId]/feedback?channelId=[egbimChannelId]` |
| TOVA | `/support/TOVA/new` | `/main/project/[tovaProjectId]/feedback?channelId=[tovaChannelId]` |
| GAIA | `/support/GAIA/new` | `/main/project/[gaiaProjectId]/feedback?channelId=[gaiaChannelId]` |
| KNGIL | `/support/KNGIL/new` | `/main/project/[kngilProjectId]/feedback?channelId=[kngilChannelId]` |
| 인트라넷 Q&A | `/support/INTRANET_QNA/new` | `/main/project/[intranetProjectId]/feedback?channelId=[intranetChannelId]` |

## 9. 문의 작성과 관리자 콘솔 분기 구조

### 9.1 기본 원칙

- 사용자는 프로젝트 안에서 글을 작성함.
- 글 작성 시 `문의 구분` 값을 함께 선택함.
- 이 `문의 구분` 은 장기적으로 채널 또는 내부 `workspace` 분기 기준으로 사용함.
- 관리자 콘솔에서는 프로젝트/채널 단위로 유입 건을 구분하여 관리함.

### 9.2 현재 구조와 향후 확장 방향

| 항목 | 현재 기준 | 향후 확장 방향 |
| --- | --- | --- |
| 프로젝트 | 서비스 단위 분리 | 유지 |
| 채널 | 프로젝트당 1개 기본 채널 | 프로젝트별 다중 채널 확장 |
| 문의 구분 | 사용자 작성 폼의 선택 값 | 채널 자동 라우팅 또는 하위 큐 분기 |
| 관리자 화면 | 프로젝트/채널별 피드백 목록 | 프로젝트/채널/문의구분 기반 다중 큐 |

## 10. 현재 구현 구조와의 연결 기준

### 10.1 사용자 화면

- 현재 사용자용 지원 화면은 `apps/web/src/pages/support/**` 경로에 구성되어 있음.
- 사용자 상세에서는 관리자 이슈 상태, 댓글, 본인 글 수정/삭제를 제공함.
- 사용자 상세 상태 표시는 현재 ABC 원본 피드백의 연결 이슈 상태를 읽어 반영하도록 확장됨.

### 10.2 관리자 화면

- 실제 관리자 콘솔은 `apps/web/src/pages/main/project/[projectId]/feedback.tsx` 경로를 중심으로 동작함.
- 피드백 상세 시트에서 댓글 CRUD와 이슈 연결 상태를 확인할 수 있도록 연계됨.
- 관리자 콘솔에서 이슈 연결 시 `apps/api` 와 `apps/secretary-api` 사이에서 내부 `support_tickets.issue_link_status` 를 함께 동기화하도록 보강됨.

### 10.3 제어 백엔드

- `apps/secretary-api` 는 사용자 화면용 상태, 댓글, 내부 티켓 메타데이터를 관리함.
- `apps/api` 는 ABC 관리자 콘솔의 피드백/이슈 기능을 제공함.
- 장기적으로는 BARON-SSO 로그인 완료 후 `tenant_id` 기반으로 사용자 경로와 관리자 경로를 라우팅하는 정책 계층이 추가되어야 함.

## 11. 권한 처리 시퀀스

```mermaid
flowchart TD
    A[사용자 또는 관리자\nBARON-SSO 로그인 상태] --> B[Q&A 이동 버튼 클릭]
    B --> C[우리 시스템 진입]
    C --> D[세션에서 user_id, tenant_id, role_keys 확인]
    D --> E{Q&A 관리자 테넌트 소속인가?}
    E -- 예 --> F[관리자 콘솔 진입]
    E -- 아니오 --> G[사용자 작성 페이지 진입]
    F --> H{프로젝트/채널 접근 권한 존재?}
    H -- 예 --> I[프로젝트별 관리자 콘솔 페이지 진입]
    H -- 아니오 --> J[권한 없음 또는 다른 프로젝트로 재분기]
    G --> K[프로젝트별 사용자 작성 페이지 이동]
    K --> L[피드백 작성]
    L --> M[문의 구분 값 저장]
    M --> N[프로젝트/채널/문의구분 기준 관리자 콘솔 큐 반영]
```

## 12. 권한 매핑 테이블 초안

| 구분 | BARON-SSO 값 | 우리 시스템 해석 | 화면 권한 | 데이터 권한 |
| --- | --- | --- | --- | --- |
| 관리자 테넌트 + 최고 권한 | 관리자 테넌트 + `SUPER_ADMIN` | 시스템 관리자 | 전체 관리자 콘솔, 설정, 프로젝트/채널 관리 | 전체 프로젝트/채널 |
| 관리자 테넌트 + 담당자 권한 | 관리자 테넌트 + `PROJECT_MANAGER` 또는 `CHANNEL_MANAGER` | 운영 담당자 | 담당 프로젝트 콘솔, 채널 설정, 댓글/이슈 처리 | 배정 프로젝트/채널 |
| 일반 테넌트 | 일반 tenant | 사용자 | 사용자 작성/목록/상세 | 본인 작성 글 |

## 13. 구현 시 체크리스트

- BARON-SSO에 `Q&A 관리자 테넌트` 생성
- 관리자 대상 계정들을 해당 테넌트에 배정
- 프로젝트 `EGBIM`, `TOVA`, `GAIA`, `KNGIL`, `INTRANET_QNA` 생성
- 각 프로젝트에 동일명 기본 채널 1개 생성
- 프로젝트/채널별 관리자 접근 정책 정의
- 사용자 Q&A 이동 버튼의 프로젝트별 URL 매핑 정의
- 로그인 후 `tenant_id` 기준 관리자/사용자 라우팅 구현
- 문의 구분 값과 채널 분기 규칙 설계
- 프로젝트별 확장 채널 생성 전략 수립

## 14. 최종 정리

- BARON-SSO는 인증과 1차 권한 분기의 기준 시스템임.
- `Q&A 관리자 테넌트`는 관리자 콘솔 진입 여부를 결정하는 최우선 조건임.
- 일반 사용자는 프로젝트별 피드백 작성 페이지로 이동함.
- 관리자/담당자는 프로젝트/채널별 관리자 콘솔로 이동함.
- 초기에는 프로젝트당 채널 1개로 시작하고, 이후 채널을 세분화하여 문의 구분과 운영 큐를 확장함.
- 현재 구현된 사용자 화면, 관리자 콘솔, 내부 티켓/댓글/이슈 상태 동기화 구조는 이 권한 설계 문서를 기준으로 다음 단계 SSO 분기 구현으로 연결할 수 있음.