tKB 지식 베이스 관리 가이드

프로젝트(csn)별 지식 베이스(tKB) 항목을 등록·조회·수정·삭제하는 관리자 화면입니다. tKB는 서버 장애 대응 노하우, 설정 정보, 분석 결과 등을 프로젝트 단위로 쌓아두는 저장소이며, Graphify(지식 그래프) 화면의 데이터 원천이기도 합니다.

🗂️ tKB 관리 페이지로 이동 →

📋 개요

tKB 관리 페이지는 현재 선택된 프로젝트(csn)에 속한 지식 베이스 항목을 목록으로 보고, 새 항목을 등록하거나 기존 항목을 수정·삭제하는 관리자 화면입니다. 항목은 서버(lssn)·DB(mdb_id)·일반(GENERAL) 등 참조 대상별로 분류되며, 제목·본문·태그로 구성됩니다.

⚠️ 이 화면은 관리자 전용입니다. 접근하려면 관리자 레벨 **uLevel >= 70**이 필요합니다(페이지에 minLevel={70}으로 하드코딩된 prop 모드). 그 미만 사용자는 홈으로 리다이렉트됩니다.

🔍 화면 구성

1. 목록 화면 (/admin/tkb)

요소	설명
Refresh 버튼	현재 페이지 데이터를 다시 불러옵니다
+ New tKB 버튼	등록 화면(/admin/tkb/new)으로 이동합니다
Per page 선택	페이지당 표시 개수(25/50/100)를 바꿉니다
목록 항목	제목, refType 배지, #kbSn, 등록일(regDt), 태그를 한 줄로 보여줍니다. 제목 또는 [Details]를 클릭하면 상세 화면으로 이동합니다
페이지네이션	서버가 totalCount를 내려주면 서버 사이드 페이징, 아니면 클라이언트에서 잘라서 표시합니다

프로젝트가 선택되지 않으면 "No Project Selected" 안내가 표시됩니다. 상단 내비게이션에서 프로젝트를 먼저 선택하세요. 목록은 로그인 세션의 csn을 기준으로 조회되며, csn이 바뀌면 자동으로 1페이지부터 다시 조회합니다.

2. 등록 화면 (/admin/tkb/new)

필드	필수	설명
CSN	✅	프로젝트 번호. 로그인 세션의 csn으로 자동 채워짐(수정 가능)
Reference Type	✅	GENERAL / MANUAL / ERROR / ANALYSIS / GUIDE 중 선택
Title	✅	그래프 노드 라벨로도 쓰이는 제목
Tags	-	쉼표로 구분한 태그(예: backend, deploy, fix)
Content	-	본문(마크다운 텍스트)
LSSN	-	특정 서버와 연관지을 때 서버 번호
MDB_ID	-	특정 DB와 연관지을 때 DB 번호

"Create tKB" 버튼을 누르면 POST /api/giipKb로 등록되고, 성공 시 목록 화면으로 돌아갑니다.

3. 상세/수정 화면 (/admin/tkb/[kbsn])

등록 화면과 동일한 필드에 더해, 하단에 등록일시/등록자/수정일시/수정자(regDt/regBy/modDt/modBy)를 읽기 전용으로 보여줍니다. 우측 상단의 Delete Entry 버튼은 확인창(confirm) 후 해당 항목을 삭제하고 목록으로 돌아갑니다. "Save Changes" 버튼은 PUT /api/giipKb로 수정 내용을 반영합니다.

🛠️ tKB 등록·수정·삭제 방법

1. 상단 내비게이션에서 대상 프로젝트를 선택합니다(선택하지 않으면 목록이 비어 있음).
2. + New tKB를 눌러 CSN·Reference Type·Title을 채우고(Content/Tags/LSSN/MDB_ID는 선택), Create tKB를 클릭합니다.
3. 목록에서 항목 제목 또는 Details를 클릭해 상세 화면으로 이동합니다.
4. 내용을 수정한 뒤 Save Changes를 누르면 즉시 반영되고, 화면에 "Successfully updated." 메시지가 표시됩니다.
5. 더 이상 필요 없는 항목은 상세 화면의 Delete Entry로 삭제합니다(복구 불가, 확인창 필수).
6. 등록/수정/삭제 후에는 그래프에 자동 반영되지 않습니다. 변경 내용을 지식 그래프에서 확인하려면 /graphify 페이지로 이동해 [Rebuild] 버튼을 눌러야 합니다(로그인 필요, giip #2099). 자세한 내용은 아래 Graphify와의 관계 섹션을 참고하세요.

🌐 Graphify와의 관계 (필독)

tKB는 /graphify(지식 그래프) 화면의 유일한 데이터 원천입니다(giip #2099 실측 확인). 백엔드 SP(pApiGraphifyRebuildbyAk)가 tKB WHERE csn=@csn 항목들로부터 그래프의 문서(DOC) 노드와 태그(TAG) 노드를 생성합니다.

• 자동 반영 안 됨: 이 화면에서 tKB 항목을 등록·수정·삭제해도 그래프는 즉시 바뀌지 않습니다.
• 반영 방법: /graphify 페이지 헤더의 [Rebuild] 버튼(로그인 필요)을 눌러야 최신 tKB 내용으로 그래프가 다시 생성됩니다. 완료되면 그래프가 자동으로 새로고침됩니다.
• giip 이슈 등 다른 데이터는 자동 포함 안 됨: graphify는 giip 이슈, 서버 정보 등을 자동으로 수집하지 않습니다. 프로젝트에 이슈가 있어도 tKB에 아직 아무것도 등록하지 않았다면 그래프는 비어 있습니다 — 정상 동작입니다.
• 자동화 스크립트(giipAgentWin 등)에서 tKB를 채우려면 이 화면 대신 giipKb API를 직접 호출할 수 있습니다(아래 API 참조).

🤖 K-Layer 위키 일일 자동 반영

tKB 목록에 직접 등록한 적 없는 항목이 매일 쌓인다면, 태그 k-layer-wiki가 붙은 자동 생성 항목일 가능성이 높습니다.

• 무엇인가: GIIP_Daily_KLayerWiki라는 이름의 Windows 작업 스케줄러 태스크(giip #2096, giipdb/mgmt/run_klayer_daily_wiki.ps1)가 매일 1회, **"어제 하루" 동안 각 csn에 새로 등록된 giip issue(제목+본문+코멘트)**를 모아 MiniMax AI로 요약하고, 그 요약을 새 tKB 항목으로 자동 적재합니다.
• 식별 방법(화면에 전용 필터는 아직 없음): 이 화면에는 태그/유형 전용 필터 UI가 없습니다. 대신 목록의 각 행에서 다음을 확인하면 자동 생성 항목을 구분할 수 있습니다.
  • Reference Type 배지: k-layer-daily
  • Tags: k-layer-wiki,daily
  • Title 형식: K-Layer Wiki <csn> - <yyyy-MM-dd> (예: K-Layer Wiki 47 - 2026-09-06)
• 대상 범위: giip issue가 하나라도 등록된 모든 csn이 대상입니다(별도의 프로젝트 허용 목록과 무관). 그날 새 이슈가 0건인 csn은 완전히 건너뜁니다(AI 호출도 tKB 삽입도 없음).
• 민감정보 마스킹: 이슈/코멘트 본문은 giipdb/mgmt/lib/Mask-SensitiveInfo.ps1로 (1) MiniMax 전송 전, (2) tKB 저장 전, 두 차례 마스킹을 거칩니다.
• 누적 방식: 같은 csn의 기존 K-Layer 위키(가장 최근 k-layer-wiki 태그 항목)를 체크포인트로 불러와, 새 이슈에서 발견된 내용만 CLAIM 형식으로 추가/갱신한 뒤 문서 전체를 다시 저장합니다 — 기존 내용은 삭제되지 않고 하나의 누적 문서로 유지됩니다.

⚠️ 다른 스크립트와 혼동 주의: giipdb/mgmt/sync_klayer_to_tkb.ps1이라는 별개의 스크립트도 tKB에 항목을 넣지만, 이것은 giip issue가 아니라 로컬 지식노트 파일(.agent/k_layer/notes/*.md, 기본 csn=47 전용)을 원본으로 하며, refType='KNOWLEDGE', tags='sync, k-layer, ai-memory'로 저장됩니다. 두 스크립트 모두 "K-Layer"라는 이름을 쓰지만 원천 데이터와 대상 csn 범위가 다른 별개 기능입니다 — Tags 값(k-layer-wiki,daily vs sync, k-layer, ai-memory)으로 구분하세요.

💡 참고

• 태그(Tags)는 자유 형식 문자열이며 강제되는 목록/스키마는 없습니다. 쉼표로 구분해 입력한 그대로 저장됩니다.
• Reference Type은 GENERAL/MANUAL/ERROR/ANALYSIS/GUIDE 5종 중에서만 선택할 수 있습니다(화면 select 옵션 기준).
• 목록은 로그인 세션의 csn을 그대로 사용합니다 — 다른 프로젝트의 tKB를 보려면 먼저 상단에서 프로젝트를 전환하세요.
• 삭제는 되돌릴 수 없습니다. 삭제 전 내용을 보존해야 한다면 별도로 백업해 두세요.

API 참조

이 화면이 호출하는 giipKb API의 엔드포인트·페이로드·인증 방식은 별도 API 가이드에 자기완결적으로 정리되어 있습니다.

📘 KB Management API User Guide

giipAgentWin 등 외부 스크립트에서 세션 로그인 없이 tKB를 등록/조회하려면 위 가이드의 SK 기반(giipApiSk3) 호출 방식을 참고하세요.

문제 해결

증상	원인	해결
접속 즉시 홈으로 튕김	uLevel이 70 미만	관리자 계정(레벨 70 이상)으로 로그인하세요.
"No Project Selected"만 표시됨	세션에 프로젝트(csn)가 선택되지 않음	상단 내비게이션에서 프로젝트를 선택하세요.
"Please login to continue" / 401 오류	로그인 세션이 없거나 만료됨	다시 로그인한 뒤 새로고침하세요.
항목을 등록/수정했는데 /graphify에서 그래프가 그대로임	Rebuild를 아직 실행하지 않음 — tKB 변경은 그래프에 자동 반영되지 않음	/graphify 페이지에서 로그인 후 [Rebuild] 버튼을 누르세요(giip #2099).
CSN, Title, and RefType are required. 오류	등록 화면에서 필수값 미입력	CSN·Title·Reference Type을 모두 채운 뒤 다시 제출하세요.
삭제 버튼을 눌러도 반응이 없음	확인창(confirm)에서 취소를 눌렀거나 인증 토큰 만료	확인창에서 [확인]을 누르고, 401이면 재로그인 후 다시 시도하세요.

---

버전: 1.0 최종 수정: 2026-09-07 (giip #2122: admin/tkb 유저 가이드 신설) 소스 파일: giipv3/public/help/tkb.ko.md