Q-A_test/docs/architecture.md

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

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 및 배포 프로세스

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 핵심 스키마

-- 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 페이지에서 답변글 확인

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

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

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

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

6.3 관리자(Admin) 시나리오

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

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 앱 메타정보와 플랫폼 내부 운영 메타정보 간 동기화 가능 여부 확인
• 네이버웍스 알림 대상자 매핑 및 부서별 알림 정책 적용 가능 여부 확인
• 운영 복잡도 대비 활용 효과가 높은 기능 우선 적용