26Y27a2

QK·2026년 7월 26일

Confluence에서 메타데이터 표 템플릿을 엔지니어들이 작성하기 쉽도록(편의성) 만들면서도, Python Sync Engine 파이프라인에서 HTML/API로 파싱할 때 오차 없이 정확하게 읽어들이도록(정확성/활용도) 구축하는 구체적인 Confluence 설정 가이드입니다.

1. 정확도와 편의성을 모두 잡는 Confluence 매크로 조합

단순히 텍스트 표를 그려두면 오타나 양식 파괴가 발생하기 쉽습니다. Confluence의 내장 매크로 3가지를 조합해 시스템을 만듭니다.

  1. Page Properties (문서 속성) 매크로: 표 전체를 감싸서 REST API 호출 시 해당 표 데이터만 독립된 객체로 추출 가능하게 만듭니다.
  2. User Status / Dropdown (상태 매크로): 작성자가 값을 자유 텍스트로 적지 않고 정해진 선택지 중 선택하도록 제한합니다.
  3. Page Properties Report (문서 속성 보고서) 매크로: 각 문서에 들어간 메타데이터를 Confluence 메인 페이지에서 한눈에 대시보드로 모아볼 수 있게 합니다.

2. Confluence에 메타데이터 템플릿 적용하는 단계별 방법

Step 1: Confluence Space / Global Template 등록

엔지니어가 새 문서 만들기(...)를 누르면 바로 선택할 수 있도록 전용 페이지 템플릿을 등록합니다.

  1. Confluence 공간 설정(Space Settings) →\rightarrow Templates →\rightarrow Create New Template 클릭.
  2. 문서 최상단에 Page Properties (문서 속성) 매크로를 삽입합니다.
  3. 매크로 내부에 아래 형태의 2열 표준 표를 작성합니다.

Step 2: 템플릿 표 내부 구성 (선택 요소 표준화)

표의 좌측(Key)은 파이프라인의 converter.py가 인식할 정확한 이름으로 고정하고, 우측(Value)은 작성자가 편하게 선택할 수 있도록 드롭다운/태그 양식을 제공합니다.

┌──────────────────────────────────────────────────────────────────────────────┐
│ ⎘ Page Properties (문서 속성 매크로 영역)                                   │
│ ┌──────────────────┬───────────────────────────────────────────────────────┐ │
│ │ 메타데이터 항목   │ 입력 / 선택 가이드                                    │ │
│ ├──────────────────┼───────────────────────────────────────────────────────┤ │
│ │ doc_type         │ [SOP ▾]  (SOP / 작업계획서 / 장애보고서 / 아키텍처 중 선택)  │ │
│ ├──────────────────┼───────────────────────────────────────────────────────┤ │
│ │ target_solutions │ @cilium  @k8s  @minio-aistor  (태그/라벨 매크로 활용)  │ │
│ ├──────────────────┼───────────────────────────────────────────────────────┤ │
│ │ environment      │ [PRD ▾]  (PRD / STG / DEV / Shared 중 선택)           │ │
│ ├──────────────────┼───────────────────────────────────────────────────────┤ │
│ │ status           │ [Active ▾]  (Active / Deprecated / Draft 중 선택)      │ │
│ ├──────────────────┼───────────────────────────────────────────────────────┤ │
│ │ error_codes      │ OOMKilled, ImagePullBackOff (쉼표 구분 입력)          │ │
│ └──────────────────┴───────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘

💡 작성 편의성 팁 (Dropdown/Status 사용):

  • Confluence 에디터에서 /status 입력 후 Active(초록색), Deprecated(빨간색), Draft(노란색) 등으로 색상이 입혀진 라벨을 선택하게 하면 visual하게 구분하기 편하고, HTML 파싱 시에도 표준 텍스트만 깔끔하게 추출됩니다.

3. 파이프라인(Python Sync Engine) 파싱 정확도를 극대화하는 테크닉

HTML을 파싱할 때 다른 일반 표와 메타데이터 표가 섞여 잘못 파싱되는 것을 방지하기 위해 Confluence 내부 HTML Class 식별자를 활용합니다.

Page Properties 매크로를 사용해 작성된 표는 Confluence가 HTML로 변환할 때 자동으로 다음과 같은 특수한 Class 속성을 부여합니다:
<table class="confluenceTh"><tbody class="plugin_pagetree_children">... 또는 class="confluenceTable" data-macro-name="details"

converter.py 표 파싱 로직 고도화

앞서 작성한 converter.py의 extract_human_metadata_from_table 함수를 아래와 같이 보완하면, 문서 내에 다른 일반 표(예: 작업 절차 표, IP 목록 표 등)가 있더라도 메타데이터 전용 Page Properties 표만 100% 정확하게 타겟팅할 수 있습니다.

def extract_human_metadata_from_table(soup: BeautifulSoup) -> dict:
    human_meta = {}
    
    # Page Properties 매크로로 감싸진 표만 정확히 검색 (data-macro-name="details" 또는 plugin class)
    target_table = soup.find('table', attrs={"data-macro-name": "details"})
    
    # 매크로 속성을 찾지 못한 경우, 상단 <th>에 'doc_type' 또는 '문서 유형'이 포함된 표 검색
    if not target_table:
        for table in soup.find_all('table'):
            text = table.get_text()
            if "doc_type" in text or "문서 유형" in text:
                target_table = table
                break

    if not target_table:
        return human_meta

    # 키워드 표준화 매핑
    key_mapping = {
        "문서 유형": "doc_type", "doc_type": "doc_type",
        "대상 솔루션": "target_solutions", "target_solutions": "target_solutions",
        "적용 환경": "environment", "environment": "environment",
        "문서 상태": "status", "status": "status",
        "장애 코드": "error_codes", "에러 코드": "error_codes", "error_codes": "error_codes",
        "담당 팀": "owner", "owner": "owner"
    }

    for row in target_table.find_all('tr'):
        cols = row.find_all(['th', 'td'])
        if len(cols) >= 2:
            raw_key = cols[0].get_text(strip=True).lower()
            raw_val = cols[1].get_text(strip=True)

            for target_key, std_key in key_mapping.items():
                if target_key in raw_key:
                    if std_key in ["target_solutions", "error_codes"]:
                        human_meta[std_key] = [item.strip().lower() for item in re.split(r'[,/ ]+', raw_val) if item.strip()]
                    else:
                        human_meta[std_key] = raw_val.lower()
                    break

    # 파싱 완료된 메타데이터 표는 본문 DOM에서 제거 (RAG 텍스트 중복 노이즈 방지)
    target_table.decompose()
    return human_meta

4. 메타데이터 활용도 향상: Confluence 대시보드 구축

Page Properties 매크로를 사용하여 문서를 작성하도록 유도하면, 파이프라인 검색 엔진뿐만 아니라 Confluence 자체에서도 엄청난 효과를 볼 수 있습니다.

  1. 운영 대시보드 페이지 생성: Confluence 메인에 SOP & 작업계획서 통합 대시보드 페이지를 생성합니다.
  2. Page Properties Report 매크로 추가:
  • 필터 조건: Label == sop
  • 보여줄 열: Title, target_solutions, environment, status, last_modified
  1. 효과: 엔지니어들은 RAG 질문 외에도 Confluence 내부에서 현재 유효한(Active) Cilium SOP 전체 목록 등을 깔끔한 리포트 표 형태로 한눈에 확인할 수 있게 됩니다.

요약 및 추천 실행 단계

  1. Confluence 템플릿 등록: Page Properties 매크로 안에 doc_type, target_solutions, environment, status 4개 필수 항목이 포함된 템플릿 등록
  2. 선택지 제약: 작성자가 단어를 틀리지 않도록 /status 매크로(드롭다운)로 값을 선택하게 가이드
  3. 파이프라인 매칭: converter.py에서 data-macro-name="details" 필터링을 적용하여 파싱 오차 0% 달성
profile
QK
engineer
이전 포스트

26Y27a1

다음 포스트

26Y27a3

0개의 댓글