first commit

2026-07-15 18:05:12 +09:00
commit 12e4f17b62
4633 changed files with 817125 additions and 0 deletions
@@ -0,0 +1,308 @@
+# 통합 지원 플랫폼 상세 설계서
+
+## 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 앱 메타정보와 플랫폼 내부 운영 메타정보 간 동기화 가능 여부 확인
+- 네이버웍스 알림 대상자 매핑 및 부서별 알림 정책 적용 가능 여부 확인
+- 운영 복잡도 대비 활용 효과가 높은 기능 우선 적용