Q-A_test/docs/architecture_secretary_sso_components.md

사내 지원 플랫폼 통합 아키텍처 설계서

1. 문서 목적

본 문서는 BARON-SSO 기반 공용 플랫폼으로 다음 두 서비스를 하나의 구조로 통합하는 방안을 설명함.

• 각 S/W 프로그램에서 진입하는 S/W별 Q&A 플랫폼
• 회사 인트라넷에서 진입하는 사내 지원 플랫폼

본 문서는 상세 테이블 설명보다 먼저 서비스의 전체 그림, 사용자 진입 방식, 인증 구조, 핵심 처리 계층, 외부 연동 방식을 이해할 수 있도록 정리함.

2. 한눈에 보는 서비스 구조

2.1 통합 대상 서비스

구분	설명
S/W Q&A	각 S/W 프로그램에서 로그인 후 해당 앱 전용 Q&A 게시판으로 연결되는 지원 서비스
사내 지원	인트라넷에서 진입하여 물품신청, 도서 신청, 출장 차량 신청, 비품 대여, 사내 Q&A를 처리하는 지원 서비스

2.2 핵심 설계 판단

• 사용자와 tenant의 원본 정보는 BARON-SSO에서 관리
• 플랫폼 내부에서는 사용자 마스터를 별도로 두지 않고 user_id, tenant_id 기반으로 권한만 관리
• 두 서비스는 각각 별도 시스템으로 만들지 않고 공통 workspace 기반 플랫폼으로 통합
• 게시글, 신청, 댓글, 첨부, FAQ, 알림은 공통 엔진으로 처리
• 승인, 자산, 차량, 원격지원은 서비스별 확장 기능으로 분리
• 승인 및 반려는 일반 사용자 화면이 아니라 담당자용 운영 페이지에서 처리

3. High-Level Architecture

3.1 아키텍처 관점

관점	설명
사용자 접점	사용자가 어디서 진입하는지
인증 계층	BARON-SSO가 어디에서 인증을 담당하는지
핵심 서비스	어떤 애플리케이션 계층에서 업무를 처리하는지
인프라 및 외부 연동	데이터 저장과 알림, 외부 시스템 연동이 어디서 발생하는지

3.2 High-Level Architecture 다이어그램

flowchart LR
    subgraph U[사용자 영역]
        U1[인트라넷 사용자]
        U2[사내 S/W 사용자]
        U3[외부 고객]
    end

    subgraph E[사용자 접점]
        E1[인트라넷 포털]
        E2[각 S/W 프로그램]
    end

    subgraph A[인증 계층]
        A1[BARON-SSO\nOAuth 2.0 / OIDC]
    end

    subgraph P[플랫폼 시스템]
        subgraph T1[UI Tier]
            F1[웹 클라이언트\nNext.js]
            F2[운영 / 관리 페이지\n담당자 · 승인자 · 관리자]
        end

        subgraph T2[API Tier]
            B1[지원 플랫폼 API\nFastAPI]
            B2[권한 제어\nuser_id, tenant_id, workspace 기반]
            B3[업무 처리 엔진\nQ&A / 신청 / 승인 / 자산 / 차량 / 원격지원]
            B4[알림 처리\nNaver Works 우선, SMS 대체]
        end

        subgraph T3[Data Tier]
            D1[PostgreSQL]
        end
    end

    subgraph X[외부 연동]
        X1[Naver Works API]
        X2[SMS Gateway]
        X3[자산 / 조직도 / 기타 사내 API]
    end

    U1 --> E1
    U2 --> E2
    U3 --> E2
    E1 --> F1
    E2 --> F1
    F1 --> A1
    A1 --> F1
    F1 --> B1
    F2 --> A1
    A1 --> F2
    F2 --> B1
    B1 --> B2
    B1 --> B3
    B2 --> D1
    B3 --> D1
    B1 --> B4
    B4 --> X1
    B4 --> X2
    B3 --> X3

3.3 전체 흐름 요약

1. 사용자는 인트라넷 포털 또는 각 S/W 프로그램에서 지원 플랫폼으로 진입함.
2. 웹 클라이언트는 BARON-SSO를 통해 인증을 수행하고 user_id, tenant_id를 확보함.
3. 플랫폼 API는 진입 경로의 app_id 또는 service_type_id를 내부 workspace로 매핑함.
4. 권한 제어 계층은 사용자별 읽기, 쓰기, 관리, 승인 범위를 확인함.
5. 일반 사용자는 사용자 화면에서 문의 또는 신청을 등록하고, 담당자는 운영 페이지에서 승인, 반려, 답변, 상태 변경을 처리함.
6. 데이터는 PostgreSQL에 저장하고 알림은 네이버웍스 우선, 실패 시 SMS로 대체 발송함.
7. 필요 시 자산 시스템, 조직도, 기타 사내 API와 연계함.

4. 서비스 구성

4.1 공통 플랫폼으로 통합하는 이유

두 서비스는 진입 채널과 세부 기능은 다르지만, 실제로는 다음 기능을 공통으로 사용함.

• 게시글 또는 신청서 작성
• 담당자 답변 및 처리 이력 관리
• 첨부파일 관리
• FAQ 및 공지 제공
• 권한별 화면 노출
• 상태 변경 및 알림 발송

따라서 서비스별로 별도 시스템을 만드는 대신 공통 플랫폼을 두고, 서비스별 차이는 workspace와 확장 테이블로 흡수하는 구조가 적절함.

4.2 S/W Q&A 서비스

S/W Q&A 서비스는 각 프로그램 사용자 또는 외부 고객이 해당 앱의 전용 게시판에 접속하여 문의를 등록하고 답변을 받는 구조임.

주요 기능은 다음과 같음.

• 앱별 전용 게시판 제공
• 문의 작성 및 담당자 답변
• 비밀글 처리
• 상태 변경 및 FAQ 추천
• 필요 시 원격지원 일정 등록
• 답변 등록 또는 상태 변경 시 알림 발송

4.3 사내 지원 서비스

사내 지원 서비스는 인트라넷에서 접근하는 업무 지원 포털 성격의 서비스임.

지원 범위는 다음과 같음.

• 물품신청
• 도서 신청
• 출장 차량 신청
• 비품 대여
• 사내 Q&A

공통 처리 흐름은 다음과 같음.

• 신청서 작성
• 승인 또는 반려
• 자산 배정 또는 차량 일정 등록
• 처리 결과 알림 발송

4.4 운영 및 관리 페이지

사내 지원 서비스에는 담당자가 승인 또는 반려를 처리하는 운영 페이지가 필요함. 이는 단순 상태 변경 화면이 아니라 권한과 이력 관리의 중심 화면 역할을 담당함.

운영 페이지의 필요 이유는 다음과 같음.

• 승인 대기 건을 한 번에 조회 가능
• 신청 상세 내용을 확인한 뒤 승인 또는 반려 처리 가능
• 반려 사유 입력 및 승인 이력 관리 가능
• 승인 이후 자산 배정, 차량 일정 등록, 후속 알림 발송까지 연결 가능
• can_approve, can_manage, page_scope 권한과 직접 연결 가능

운영 페이지는 별도 시스템으로 분리하기보다 동일 플랫폼 내부의 권한 기반 메뉴로 구성하는 방식이 적절함.

5. 핵심 구성요소 상세

5.1 사용자 접점

접점	설명
인트라넷 포털	사내 지원 서비스 진입점
각 S/W 프로그램	S/W별 Q&A 서비스 진입점
운영 / 관리 페이지	담당자, 승인자, 관리자가 사용하는 내부 운영 화면

인트라넷에서는 서비스 유형 기준으로 진입하고, S/W 프로그램에서는 앱 기준으로 진입함. 운영 담당자는 별도 운영 메뉴를 통해 진입하지만, 이 역시 내부적으로는 동일한 workspace와 권한 체계를 사용함.

5.2 인증 및 권한 계층

BARON-SSO는 사용자 인증과 tenant 식별의 원본 시스템 역할을 담당함. 플랫폼은 BARON-SSO로부터 받은 user_id, tenant_id를 기준으로 내부 권한만 제어함.

플랫폼 내부 권한 항목은 다음과 같음.

• can_read
• can_write
• can_manage
• can_approve
• page_scope

이 구조를 사용하면 사용자 기본 정보는 외부에서 일관되게 유지하고, 플랫폼 내부에서는 읽기, 쓰기, 승인, 관리 범위만 유연하게 제어 가능함.

특히 승인 또는 반려 처리는 can_approve 권한이 있는 담당자만 수행하도록 제한하고, 운영 화면 접근 범위는 page_scope로 분리하는 방식이 적절함.

5.3 핵심 서비스 계층

핵심 서비스 계층은 FastAPI 기반 API 서버로 구성하며, 다음 기능을 공통 처리함.

기능 영역	설명
Workspace Engine	앱 또는 인트라넷 서비스를 내부 작업 단위로 매핑
Ticket Engine	Q&A와 신청서를 공통 구조로 저장 및 처리
Comment Engine	답변, 처리 메모, 협업 이력 관리
Attachment Engine	첨부파일 저장 및 조회 관리
FAQ Engine	워크스페이스별 FAQ와 공지성 정보 제공
Approval Extension	신청 승인 및 반려 처리
Asset Extension	물품, 비품, 도서, 차량 자산 관리
Remote Support Extension	S/W 문의의 원격지원 일정 및 처리 관리

이 중 Approval Extension은 일반 사용자 화면보다 운영 페이지와 더 강하게 연결됨. 승인 담당자는 운영 페이지에서 대기 건 조회, 승인 또는 반려 처리, 반려 사유 작성, 후속 조치 등록을 수행함.

5.4 데이터 및 외부 연동 계층

PostgreSQL은 플랫폼의 공통 데이터 저장소 역할을 담당함. 외부 연동은 알림과 운영 정보 보강 목적에 집중함.

연동 대상	목적
Naver Works API	기본 알림 채널
SMS Gateway	네이버웍스 실패 또는 미보유 사용자 대체 알림
자산/조직도/기타 사내 API	자산 정보 조회, 조직 기반 처리, 추가 업무 연계

알림은 네이버웍스를 우선 사용하고, 발송 실패 또는 계정 미보유 시 SMS로 대체하는 정책을 적용함.

6. DB 설계 방향

6.1 설계 원칙

• 사용자 마스터는 BARON-SSO에서 관리함.
• 로컬 DB는 권한, 워크스페이스, 업무 데이터, 알림 보조 정보만 관리함.
• Q&A와 사내 지원 요청은 분리 저장하지 않고 공통 티켓 구조로 통합함.
• 서비스별 차이는 확장 테이블로 분리하여 향후 신규 앱과 신규 사내 서비스가 추가되어도 구조 변경을 최소화함.
• 운영 페이지는 별도 사용자 테이블 없이 기존 권한 테이블과 승인 이력 테이블을 활용하여 구성함.

6.2 데이터 영역 구분

데이터 영역	주요 테이블	설명
서비스 마스터	software_apps, service_types, workspaces	진입 경로를 내부 서비스 단위로 매핑
권한 관리	user_workspace_access	사용자별 읽기, 쓰기, 관리, 승인 범위 제어
알림 보조 정보	user_notification_profiles	네이버웍스 키, 전화번호, SMS 수신 여부 관리
공통 업무 데이터	support_tickets, ticket_comments, attachments, faqs	Q&A와 신청 데이터를 공통 구조로 관리
코드 관리	support_status_codes, support_category_codes, remote_support_status_codes	상태 및 분류 표준화
사내 지원 확장	request_approvals, assets, asset_allocations, vehicle_schedules	승인, 자산, 차량 업무 처리
S/W 지원 확장	remote_support	원격지원 일정 및 처리 이력 관리
운영 이력	notification_logs	알림 발송 및 실패 이력 추적

6.3 핵심 엔터티 설명

6.3.1 workspace

workspace는 이 설계의 중심 엔터티임. 외부에서는 S/W 앱 또는 인트라넷 서비스로 보이지만, 내부에서는 모두 workspace로 수렴함. 이 구조를 사용하면 신규 앱 또는 신규 사내 서비스가 생겨도 공통 기능을 재사용 가능함.

6.3.2 support_tickets

Q&A 게시글과 각종 신청서를 별도 본문 테이블로 나누지 않고 support_tickets로 통합 관리함. 대신 ticket_type, workspace_id, category_code, status_code로 의미를 구분함.

6.3.3 user_workspace_access

플랫폼은 사용자 상세 프로필을 저장하지 않지만, 어떤 사용자가 어떤 워크스페이스에서 무엇을 할 수 있는지는 반드시 관리해야 함. 이 역할을 user_workspace_access가 담당함.

운영 페이지 관점에서는 이 테이블이 특히 중요함. 승인 담당자 여부, 운영 메뉴 접근 가능 여부, 특정 워크스페이스에 대한 승인 가능 범위가 모두 이 테이블의 권한 컬럼으로 제어되기 때문임.

6.3.4 request_approvals

request_approvals는 승인 또는 반려가 실제로 수행된 결과를 남기는 이력 테이블임. 승인 담당자 정보, 처리 결과, 반려 사유, 승인 시각을 저장하므로 운영 페이지의 감사 추적과 처리 내역 조회에 직접 사용됨.

7. DB 스키마 초안

-- 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. 사내 서비스 유형 정보
CREATE TABLE service_types (
    id SERIAL PRIMARY KEY,
    service_code VARCHAR(50) UNIQUE NOT NULL,
    service_name VARCHAR(100) UNIQUE NOT NULL,
    description TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 3. 공통 워크스페이스 마스터
CREATE TABLE workspaces (
    id SERIAL PRIMARY KEY,
    workspace_type VARCHAR(20) NOT NULL,
    software_app_id INTEGER REFERENCES software_apps(id),
    service_type_id INTEGER REFERENCES service_types(id),
    workspace_code VARCHAR(50) UNIQUE NOT NULL,
    workspace_name VARCHAR(100) NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    CHECK (
        (workspace_type = 'SOFTWARE_APP' AND software_app_id IS NOT NULL AND service_type_id IS NULL)
        OR
        (workspace_type = 'INTRANET_SERVICE' AND service_type_id IS NOT NULL AND software_app_id IS NULL)
    )
);

-- 4. 사용자별 워크스페이스 접근 권한 및 역할
CREATE TABLE user_workspace_access (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(100) NOT NULL,
    tenant_id VARCHAR(100) NOT NULL,
    workspace_id INTEGER NOT NULL REFERENCES workspaces(id),
    workspace_role VARCHAR(20) NOT NULL DEFAULT 'USER',
    can_read BOOLEAN DEFAULT TRUE,
    can_write BOOLEAN DEFAULT FALSE,
    can_manage BOOLEAN DEFAULT FALSE,
    can_approve BOOLEAN DEFAULT FALSE,
    page_scope VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (user_id, tenant_id, workspace_id)
);

-- 5. 사용자 알림 보조 정보
CREATE TABLE user_notification_profiles (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(100) NOT NULL,
    tenant_id VARCHAR(100) NOT NULL,
    user_type VARCHAR(20) NOT NULL DEFAULT 'INTERNAL',
    phone_number VARCHAR(30),
    naverworks_user_key VARCHAR(100),
    sms_opt_in BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (user_id, tenant_id)
);

-- 6. 공통 상태 코드
CREATE TABLE support_status_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 7. 공통 카테고리 코드
CREATE TABLE support_category_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 8. 공통 게시글/신청 본문
CREATE TABLE support_tickets (
    id SERIAL PRIMARY KEY,
    workspace_id INTEGER NOT NULL REFERENCES workspaces(id),
    requester_id VARCHAR(100) NOT NULL,
    requester_tenant_id VARCHAR(100) NOT NULL,
    ticket_type VARCHAR(20) NOT NULL,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    category_code VARCHAR(20) REFERENCES support_category_codes(code),
    status_code VARCHAR(20) NOT NULL DEFAULT 'OPEN' REFERENCES support_status_codes(code),
    is_secret BOOLEAN DEFAULT FALSE,
    requested_start_at TIMESTAMP,
    requested_end_at TIMESTAMP,
    priority VARCHAR(20) DEFAULT 'NORMAL',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 9. 댓글 및 처리 메모
CREATE TABLE ticket_comments (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER NOT NULL REFERENCES support_tickets(id),
    author_id VARCHAR(100) NOT NULL,
    author_tenant_id VARCHAR(100) NOT NULL,
    content TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 10. 첨부파일 통합 관리
CREATE TABLE attachments (
    id SERIAL PRIMARY KEY,
    parent_type VARCHAR(20) NOT NULL,
    parent_id INTEGER NOT NULL,
    workspace_id INTEGER NOT NULL REFERENCES workspaces(id),
    file_name VARCHAR(255) NOT NULL,
    file_path VARCHAR(500) NOT NULL,
    file_size INTEGER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 11. 사내 지원용 승인 이력
CREATE TABLE request_approvals (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER NOT NULL REFERENCES support_tickets(id),
    approver_id VARCHAR(100) NOT NULL,
    approver_tenant_id VARCHAR(100) NOT NULL,
    approval_status VARCHAR(20) NOT NULL,
    comment TEXT,
    approved_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 12. 자산/비품 마스터
CREATE TABLE assets (
    id SERIAL PRIMARY KEY,
    asset_code VARCHAR(50) UNIQUE NOT NULL,
    asset_name VARCHAR(100) NOT NULL,
    asset_type VARCHAR(30) NOT NULL,
    quantity INTEGER DEFAULT 1,
    is_active BOOLEAN DEFAULT TRUE,
    location VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 13. 자산 배정 및 대여 이력
CREATE TABLE asset_allocations (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER NOT NULL REFERENCES support_tickets(id),
    asset_id INTEGER NOT NULL REFERENCES assets(id),
    assignee_id VARCHAR(100),
    assignee_tenant_id VARCHAR(100),
    allocation_status VARCHAR(20) NOT NULL,
    loaned_at TIMESTAMP,
    due_at TIMESTAMP,
    returned_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 14. 차량 운행 일정
CREATE TABLE vehicle_schedules (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER NOT NULL REFERENCES support_tickets(id),
    asset_id INTEGER NOT NULL REFERENCES assets(id),
    departure_at TIMESTAMP NOT NULL,
    arrival_at TIMESTAMP,
    destination VARCHAR(255),
    driver_name VARCHAR(100),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 15. S/W Q&A용 원격 지원 상태 코드
CREATE TABLE remote_support_status_codes (
    code VARCHAR(20) PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    sort_order INTEGER NOT NULL
);

-- 16. S/W Q&A용 원격 지원 로그
CREATE TABLE remote_support (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER NOT NULL REFERENCES support_tickets(id),
    status_code VARCHAR(20) REFERENCES remote_support_status_codes(code),
    support_engineer_id VARCHAR(100),
    support_engineer_tenant_id VARCHAR(100),
    scheduled_time TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 17. 공통 FAQ
CREATE TABLE faqs (
    id SERIAL PRIMARY KEY,
    workspace_id INTEGER NOT NULL REFERENCES workspaces(id),
    title VARCHAR(255) NOT NULL,
    content TEXT NOT NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 18. 알림 발송 이력
CREATE TABLE notification_logs (
    id SERIAL PRIMARY KEY,
    ticket_id INTEGER REFERENCES support_tickets(id),
    recipient_id VARCHAR(100) NOT NULL,
    recipient_tenant_id VARCHAR(100) NOT NULL,
    channel VARCHAR(20) NOT NULL,
    target_address VARCHAR(100),
    delivery_status VARCHAR(20) NOT NULL,
    fallback_channel VARCHAR(20),
    error_message TEXT,
    sent_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

8. 정리

이 설계의 핵심은 S/W별 Q&A와 인트라넷 사내 지원을 서로 다른 시스템으로 분리하지 않고, BARON-SSO와 workspace 중심 공통 플랫폼으로 통합하는 데 있음. 사용자 정보는 BARON-SSO를 원본으로 유지하고, 플랫폼은 권한과 업무 처리에 집중함. 그 결과 서비스 확장성과 운영 일관성을 동시에 확보 가능함.

다음 단계에서는 상태 코드 표준값, page_scope 체계, 주요 API 목록, 화면 구성도를 추가하면 구현 준비 수준의 설계 문서로 확장 가능함.