# 통합 지원 플랫폼 상세 설계서

## 1. 프로젝트 개요

### 1.1 프로젝트 정보

| 항목 | 내용 |
| --- | --- |
| 플랫폼명 | BARON Q&A System |
| 핵심 목적 | EG-BIM 등 복수 소프트웨어의 Q&A, FAQ, 원격 지원 기능을 통합하고 BARON-SSO 기반 보안을 적용한 전사 기술지원 허브 구축 |
| 주요 대상 | BARON-SSO에 등록된 일반 사용자(User), 소프트웨어 담당자(Support), 시스템 관리자(Admin) |

### 1.2 추진 배경 및 기대 효과

- 여러 제품군에 분산된 기술지원 채널의 단일 플랫폼 통합
- 사용자 질문, FAQ, 원격 지원 이력의 일원화를 통한 대응 품질 및 추적성 향상
- BARON-SSO와 앱 단위 권한 제어를 통한 보안성 및 운영 효율 확보

## 2. 기술 아키텍처

### 2.1 기술 스택

| 구분 | 기술 |
| --- | --- |
| Frontend | Next.js, React, Tailwind CSS, Headless UI |
| Backend | FastAPI, Python, SQLAlchemy, Pydantic |
| Database | PostgreSQL |
| 인증/권한 | BARON-SSO, OAuth 2.0, OpenID Connect |
| 외부 연동 | ABC User Feedback 웹훅, 네이버웍스 알림 연동 |
| 인프라 | Ubuntu 24.04 (WSL2), Docker Compose, Nginx |

### 2.2 아키텍처 방향

- 프론트엔드의 Next.js 기반 구성으로 사용자 경험 및 생산성 확보
- 백엔드의 FastAPI 중심 경량 API 구조 설계를 통한 인증, 게시판, FAQ, 원격 지원 기능 분리 구현
- PostgreSQL과 SQLAlchemy 기반 데이터 계층 구성 및 앱별 접근 제어의 데이터 모델 반영
- BARON-SSO 연동 전제의 인증 구조 적용 및 표준 OAuth 2.0 / OIDC 기반 세션·토큰 검증 수행
- ABC User Feedback 연계를 통한 사용자 의견 수집 및 지원 품질 개선 체계 확보
- ABC User Feedback 웹훅 이벤트와 네이버웍스 알림 연계를 통한 실시간 커뮤니케이션 체계 확보

### 2.3 CI/CD 및 배포 프로세스

```mermaid
graph TD
    A[개발자: 코드 작성 및 로컬 테스트] --> B[Main 브랜치 Push]
    B --> C{GitHub Actions}
    C --> D[Lint 및 Unit Test 실행]
    D --> E[Docker Image 빌드]
    E --> F[Container Registry 저장]
    F --> G[운영 서버 배포]
    G --> H[Nginx Proxy 라우팅]
    H --> I[서비스 가동 및 모니터링]
```

## 3. 데이터베이스 설계

### 3.1 설계 원칙

권한 기반 데이터 격리(RBAC)를 위해 모든 게시물이 `app_id`를 참조하고, 사용자는 `user_app_access`를 통해 허용된 앱에만 접근하도록 설계

- 신규 앱이 추가되더라도 공통 스키마 변경 없이 `software_apps` 데이터 추가만으로 확장 가능한 구조 적용
- 전역 관리자 권한과 앱별 운영 권한 분리를 통한 멀티앱 확장 대응
- 사용자-앱 매핑의 중복 방지 및 상태값 표준화를 통한 운영 일관성 확보
- 목록 조회 성능 확보를 위한 앱 기준 인덱스 설계 반영

### 3.2 핵심 스키마

```sql
-- 1. 소프트웨어 정보
CREATE TABLE software_apps (
    id SERIAL PRIMARY KEY,
    app_code VARCHAR(50) UNIQUE NOT NULL,
    app_name VARCHAR(100) UNIQUE NOT NULL,
    description TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 2. 사용자 정보 (BARON-SSO 동기화)
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    sso_user_id VARCHAR(100) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    name VARCHAR(100),
    company VARCHAR(100),
    department VARCHAR(100),
    global_role VARCHAR(20) DEFAULT 'USER', -- ADMIN, USER
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 3. 사용자별 앱 접근 권한 및 앱별 역할
CREATE TABLE user_app_access (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id),
    app_id INTEGER NOT NULL REFERENCES software_apps(id),
    app_role VARCHAR(20) NOT NULL DEFAULT 'USER', -- SUPPORT, USER
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (user_id, app_id)
);

-- 4. Q&A 상태 코드
CREATE TABLE qna_status_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 5. Q&A 카테고리 코드
CREATE TABLE qna_category_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 6. Q&A 게시글
CREATE TABLE qna_posts (
    id SERIAL PRIMARY KEY,
    app_id INTEGER NOT NULL REFERENCES software_apps(id),
    user_id INTEGER NOT NULL REFERENCES users(id),
    title VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    category_code VARCHAR(20) REFERENCES qna_category_codes(code),
    status_code VARCHAR(20) NOT NULL DEFAULT 'RECEIVED' REFERENCES qna_status_codes(code),
    is_secret BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 7. 댓글
CREATE TABLE comments (
    id SERIAL PRIMARY KEY,
    post_id INTEGER NOT NULL REFERENCES qna_posts(id),
    author_id INTEGER NOT NULL REFERENCES users(id),
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 8. 첨부파일 통합 관리
CREATE TABLE attachments (
    id SERIAL PRIMARY KEY,
    parent_type VARCHAR(20) NOT NULL, -- 'POST' 또는 'COMMENT'
    parent_id INTEGER NOT NULL,
    app_id INTEGER NOT NULL REFERENCES software_apps(id),
    file_name VARCHAR(255) NOT NULL,
    file_path VARCHAR(500) NOT NULL,
    file_size INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 9. 원격 지원 상태 코드
CREATE TABLE remote_support_status_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 10. 원격 지원 로그
CREATE TABLE remote_support (
    id SERIAL PRIMARY KEY,
    post_id INTEGER NOT NULL REFERENCES qna_posts(id),
    scheduled_time TIMESTAMP,
    status_code VARCHAR(20) REFERENCES remote_support_status_codes(code),
    support_engineer_id INTEGER REFERENCES users(id),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 11. 주요 조회 인덱스
CREATE INDEX idx_user_app_access_app_role ON user_app_access (app_id, app_role);
CREATE INDEX idx_qna_posts_app_status_created ON qna_posts (app_id, status_code, created_at DESC);
CREATE INDEX idx_qna_posts_user_created ON qna_posts (user_id, created_at DESC);
CREATE INDEX idx_comments_post_created ON comments (post_id, created_at DESC);
CREATE INDEX idx_attachments_app_parent ON attachments (app_id, parent_type, parent_id);
```

## 4. 권한 및 보안 설계

### 4.1 역할 기반 접근 제어(RBAC)

| 역할 | 접근 범위 | 주요 권한 |
| --- | --- | --- |
| Admin | 전사 전체 소프트웨어 | 전체 통계 조회, 모든 게시글 수정/삭제, FAQ 관리, 앱 권한 부여 |
| Support | 본인에게 할당된 소프트웨어 | 담당 앱 Q&A 답변, 원격 지원 시작, 상태 변경 |
| User | 본인이 사용 중인 소프트웨어 | Q&A 작성/조회, FAQ 검색, 원격 지원 신청 |

### 4.2 권한 검증 로직

- 모든 API 요청에서 JWT 토큰 기준 사용자 식별 정보 추출
- 전사 관리자 여부는 `users.global_role` 기준 확인
- 앱 단위 접근 권한과 역할은 `user_app_access.app_role` 기준 검증
- 요청 앱에 대한 권한이 없을 경우 `403 Forbidden` 반환
- 비밀글(`is_secret = true`)의 작성자 본인, 권한 있는 Support, Admin 한정 조회

## 5. 주요 기능 및 UI 설계

### 5.1 통합 Q&A 리스트

- 제품별, 상태별, 날짜별 필터 제공
- 접수중, 검토중, 패치예정, 해결완료 상태의 컬러 배지 구분을 통한 가시성 강화
- MS Q&A 및 EG-BIM 사례를 참고한 검색성·가독성 중심 리스트 구조 적용

### 5.2 지능형 FAQ 및 원격 지원

- 질문 작성 시 제목 키워드 기반 관련 FAQ 실시간 추천
- 게시글 내용이 복잡하거나 재현이 어려운 경우 담당자에 의한 원격 지원 세션 생성 및 링크 전달
- Q&A에서 원격 지원으로 자연스럽게 전환되는 단순 운영 흐름 구성

### 5.3 파일 및 이미지 업로드

- 게시글 본문 및 댓글에서 드래그 앤 드롭 방식의 이미지 첨부 지원
- `attachments` 테이블을 통한 게시글·댓글 출처 구분 및 보존·삭제 이력 관리
- 초기 저장소의 로컬 볼륨 또는 S3 호환 스토리지 기준 검토

### 5.4 웹훅 기반 알림 연동

- ABC User Feedback에서 제공하는 웹훅을 활용한 앱별 Q&A 이벤트 수신
- 각 앱 사용자의 Q&A 화면 접근 시 주요 공지 또는 신규 문의 현황 노출
- 사용자의 신규 Q&A 글 작성 시 담당자 대상 네이버웍스 알림 발송
- 담당자의 답변글 작성 시 작성자 대상 네이버웍스 알림 발송
- 알림 이벤트의 앱별 라우팅, 수신 대상 매핑, 발송 이력 관리 체계 구성

## 6. 역할별 사용 시나리오

### 6.1 일반 사용자(User) 시나리오

- 각 소프트웨어 프로그램 로그인
- Q&A 페이지 접근
- 해당 앱 기준 Q&A 리스트 노출 및 기존 문의 확인
- 신규 문의 글 작성
- 담당자의 답변글 등록 시 네이버웍스 알림 수신
- 알림 확인 후 Q&A 페이지에서 답변글 확인

```mermaid
flowchart LR
    A[사용자 로그인] --> B[Q&A 페이지 접근]
    B --> C[해당 앱 Q&A 리스트 확인]
    C --> D[신규 문의 글 작성]
    D --> E[담당자 답변 등록]
    E --> F[네이버웍스 알림 수신]
    F --> G[답변글 확인]
```

### 6.2 소프트웨어 담당자(Support) 시나리오

- 본인 담당 소프트웨어 관련 글만 노출 및 확인
- 신규 등록 글의 새글 표시 확인
- 문의 내용 검토 후 답변글 작성
- 처리 단계에 따른 상태값 변경
- 답변 등록 시 사용자 대상 네이버웍스 알림 발송

```mermaid
flowchart LR
    A[담당 앱 글 목록 확인] --> B[새글 표시 확인]
    B --> C[문의 내용 검토]
    C --> D[답변글 작성]
    D --> E[상태값 변경]
    E --> F[사용자 대상 네이버웍스 알림 발송]
```

### 6.3 관리자(Admin) 시나리오

- 로컬 개발 환경에서 기능 개발 및 수정
- Git 저장소 업로드
- CI/CD 파이프라인을 통한 운영 서버 Docker 환경 배포
- 배포 결과 및 운영 상태 확인

```mermaid
flowchart LR
    A[로컬 개발 및 수정] --> B[Git 저장소 업로드]
    B --> C[CI/CD 파이프라인 실행]
    C --> D[운영 서버 Docker 배포]
    D --> E[배포 결과 및 운영 상태 확인]
```

## 7. 구현 로드맵

### 7.1 Phase 1. 핵심 인프라 구축

- [ ] Ubuntu 및 Docker 서버 환경 셋업
- [ ] BARON-SSO OAuth2 연동 및 사용자 매핑 로직 구현
- [ ] RBAC 기반 DB 스키마 생성 및 기초 API 개발

### 7.2 Phase 2. 통합 플랫폼 UI 개발

- [ ] 소프트웨어별 격리 게시판 및 통합 리스트 UI 구현
- [ ] 첨부파일 및 이미지 업로드 시스템 구축
- [ ] 원격 지원 신청 기능 및 관리자 대시보드 연동

### 7.3 Phase 3. 고도화 및 운영 최적화

- [ ] AI 기반 FAQ 자동 추천 엔진 탑재
- [ ] ABC User Feedback 웹훅 및 네이버웍스 알림 연동 고도화
- [ ] 이슈 해결 통계 및 제품 품질 인사이트 보고서 자동화

### 7.4 추후 개발 예정 기능

#### 7.4.1 ADC User Feedback 연계 확장 기능

- 앱 메타정보 동기화 기능: BARON-SSO 또는 ADC User Feedback에 등록된 앱 코드, 앱명, 사용 여부 등의 정보를 우리 플랫폼과 자동으로 맞추는 기능
- 상태 변경 이벤트 기반 네이버웍스 추가 알림 기능
- FAQ, 기존 문의, 공지사항 기반 중복 문의 사전 방지 기능
- 앱별 문의 건수, 처리량, 응답 시간 기준 통계 대시보드 기능
- 소프트웨어별 Q&A 딥링크 또는 임베드 연동 기능: 각 소프트웨어 내부에서 해당 앱의 Q&A 화면으로 바로 이동하거나, Q&A 일부 화면을 프로그램 내부에 직접 표시하는 기능

#### 7.4.2 적용 검토 기준

- ADC User Feedback 제공 API, 웹훅, 임베드 기능의 실제 지원 범위 확인
- SSO 앱 메타정보와 플랫폼 내부 운영 메타정보 간 동기화 가능 여부 확인
- 네이버웍스 알림 대상자 매핑 및 부서별 알림 정책 적용 가능 여부 확인
- 운영 복잡도 대비 활용 효과가 높은 기능 우선 적용