Skip to main content

Wiki v1 구현 매핑

기존 URL 보존과 콘텐츠 기반 탐색 구현 계획

결정​

문서 원본을 이동하거나 복제하지 않는다. 새 진입 페이지가 기존 Docusaurus 문서 permalink를 참조한다. 문서 ID와 URL은 Docusaurus가 생성한 metadata로 구별하며, related는 실제 문서 ID를 사용한다. 관계 대상이 없거나 비공개·초안이면 빌드를 실패시킨다.

현행목표파일
홈의 카테고리 카드검색 → SAP·개발·인프라 → 대표 문서 → 지식 도구; Projects·Notes도 유지src/pages/index.tsx
SAP 문서 소개/sap 진입, 실제 업무·개발 분류로 이동src/pages/sap.tsx
Development 소개/development에서 실제 분류와 대표 문서로 이동src/pages/development.tsx
Infrastructure 소개/infrastructure에서 환경·운영 경계와 기존 API 영속 저장 문서로 이동src/pages/infrastructure.tsx
자료 추가·자료 관리/tools로 작업 안내 및 기존 두 흐름 연결src/pages/tools.tsx
Wiki 본문 검색 없음/search에서 빌드 시 생성한 문서 제목·설명·본문 검색로컬 plugin, src/pages/search.tsx
하나의 전체 사이드바SAP·개발·인프라·Projects·Notes·안내별 사이드바sidebars.ts
파일 순서의 이전·다음명시한 pagination_prev / pagination_next만 표시src/theme/DocItem/Paginator/
상세의 관련 링크 없음요약·분류별 관련 문서·상위 허브·자료 추가src/theme/DocItem/Content/, 공통 UI

새 1차 문서 폴더나 DB/API 모델은 추가하지 않는다. 문서 검색은 공개된 docs만 사용하고 업로드·SQLite·API 결과를 색인하지 않는다. 기존 검색 엔진이 없어 작은 로컬 색인을 추가하며 외부 서비스·의존성은 추가하지 않는다. 색인은 현재 규모에 맞는 단순 부분 문자열 검색이다.

콘텐츠 부재 처리​

SAP 네 관점은 업무·모듈·개발·연계라는 동등한 개념이다. 현재 업무·개발 소개만 존재하므로 두 항목만 실제 문서로 연결하고 모듈·연계는 설명에 남긴다. 투자관리, IM, PS, WBS 허브는 만들지 않는다. AI 지식 문서도 없어 /ai와 AI 영역 카드는 보류한다. AI 분석은 /tools에서 제공한다. 이 제한은 공개 화면에 존재하지 않는 자료를 노출하지 않는 명세 원칙을 우선한 것이다.

인프라는 AGENTS의 확인된 환경 규칙을 기존 docs/Development/Infrastructure/에 문서화한다. OCI 서버의 실제 명령·호스트 경로·Compose 내용은 추측하지 않는다. 기존 Infrastructure 소개는 유지하며 새 문서를 연결한다.

검증할 실제 동선​

  1. 홈 → SAP → 업무 프로세스 → 기존 Functional 소개 → 관련 Technical 소개 → SAP 복귀. 투자·PS 시나리오를 대체하지만 투자·PS 인수 통과로 표시하지 않는다.
  2. 홈 → 인프라 → code-server와 OCI 운영 경계 → Knowledge API 분석 설계의 Docker/OCI 영속 저장 → 인프라 복귀. OCI 전용 허브는 실제 콘텐츠가 더 생길 때 추가한다.
  3. 홈/상단 → 검색 → SAP 또는 OCI 본문 결과 → 제목·소속·유형 확인.
  4. 홈/문서/상단 → 업로드·AI 분석 → 기존 모달 → 검토. 자료 관리에서 기존 저장 검토 재열기.
  5. 기존 /docs/intro, /docs/SAP/, /docs/Development/Tools/knowledge-api-analysis, /knowledge, /markdown-page 등 기존 경로 보존.

구현 파일군과 검증​

  • 공통 UI: DomainCard, HubSection, DocCard, RelatedDocs, ActionLink와 HubPage. 카드 전체 링크, 키보드 포커스, 반응형 그리드.
  • 생성 데이터: Docusaurus metadata 기반 공개 docs 색인, 실제 ID 관계 검증, 검색 유틸리티와 테스트.
  • 상세: 기존 breadcrumb/TOC/본문/테마 유지, 기존 수동 링크 유지, 관련 문서가 있을 때만 표시.
  • 업로드: API 호출 코드를 유지하며 모달의 키보드 접근성을 보완한다. 기존 계약에 대상 문서 ID가 없어 임의 파라미터를 보내지 않는다.
  • 기록: 이 폴더의 inventory, implementation-map, verification. 모든 단계에서 typecheck/build 및 관련 테스트, 마지막 diff 확인.

단계 1 결과​

변경 파일: 현황 조사와 구현 매핑. 기존 baseline 검증 통과 상태에서 구현을 시작한다. 다음 단계의 위험은 metadata ID 해석, sidebar 중복 소속, 브라우저에서의 모달 회귀이며 빌드·관계 테스트·가능한 브라우저 검증으로 확인한다.

자료·지식 분리 milestone 설계 (2026-09-24)​

이번 요구사항이 이전의 API/DB 변경 제외 및 업로드 자동 분석 설계를 대체한다. 기존 v1 탐색·문서·검토 계약은 보존한다.

  • /knowledge: 원본 자료 저장소. 업로드 후 BackgroundTasks에서 추출과 비용 없는 규칙 기반 최소 분류. AI 분석은 명시적 요청만 처리한다.
  • sources에 추출 본문/파서, 독립 처리 상태·오류·횟수·시각과 분류 제안을 additive migration으로 추가한다. 기존 analysis_json/review_content_json은 유지한다.
  • 단일 프로세스에서 작업을 직렬화하고 DB 상태로 중복 요청을 방지한다. 시작 시 중단된 작업은 실패로 표시하여 사용자가 재시도한다. 영속 큐나 자동 재개는 구현하지 않는다.
  • 별도 knowledge_entries 테이블: 최초 입력 원문, 편집 본문, 선택적 AI 결과, origin 및 source_id. UI와 미래 trusted client가 동일 API를 사용한다. Wiki 자동 발행은 없다.
  • /knowledge-add: 텍스트/GPT/회의록/업무정리 저장과 선택적 AI 보완, 기존 자료 선택. /knowledge-entries: 저장한 지식 재열기.
  • 기존 /?add-source=1은 /knowledge?upload=1로 연결한다. 업로드 코드는 자료 관리에만 둔다.
  • 분류는 제한된 텍스트와 명시적 SAP 식별자만 사용한 제안이다. 추론·교차 문서 분석·외부 AI 호출은 하지 않는다. 불명확하면 미분류로 보존한다.
  • 검증: 임시 DB와 모의 파서/AI 백엔드 테스트, Node 회귀, typecheck/build/HTML 링크, 가능하면 mock API 브라우저 동선. 운영 데이터·OCI는 접근하지 않는다.

AI 검색 Phase 1 구현 전 조사와 결정 (2026-09-24)​

현재 코드 기준으로 sources는 extracted_text, analysis_json, review_content_json 및 분류·태그를 영속화한다. knowledge_entries는 original_text, content, refinement_json과 자체 분류·출처를 별도로 보존한다. 기존 문서의 검색 미구현 설명은 당시 이력이다. /search는 공개 Wiki 빌드 색인이고 자료 목록은 SQLite 부분 문자열 검색이다. 이번에는 기존 두 검색 화면을 변경하지 않는다.

없는 데이터는 구절 색인, 색인 버전/상태, 질의 계획, 근거 묶음, 교차 자료 추론 계약이다. 문서 사건 날짜 전용 필드는 없으므로 업로드/생성/수정 시각을 사건 날짜로 주장하지 않는다. 운영 SQLite 파일은 접근하지 않았으며 현재 스키마는 storage.py와 기존 임시 DB migration 테스트로 확인한다.

구현 계획: SQLite에 search_objects와 버전별 search_chunks 및 선택적 FTS5만 추가한다. 기존 테이블/행은 재생성·삭제하지 않는다. 이전 chunk도 삭제하지 않고 현재 generation만 조회하여 중복 활성 구절을 방지한다. 기존 저장 함수의 commit 후 해당 객체만 갱신하고 트리거로 pending/stale revision을 남겨 실패·중단을 재시도할 수 있게 한다. 검색은 최신 indexed revision만 사용한다. bootstrap은 관리용 CLI로 명시 실행하며 시작 시 전체 재색인은 하지 않는다.

본문 계층별 문단/문장/공백 경계 청킹과 위치·해시를 저장한다. FTS5 후보와 메타데이터 제약 → 관련도/계층 우선순위 → 중복 참조 보존 → 출처 다양성 → 예산 제한 근거 묶음으로 이어진다. 한국어 조사가 붙은 모듈·주제 검색은 가벼운 규칙으로 해석한다. FTS5 미지원 시 매개변수화된 SQLite 문자 검색으로 저하하고 알린다.

추론은 기존 OpenAI Responses 호출 방식과 ANALYSIS_MODEL/OPENAI_API_KEY 설정을 재사용하되 별도 서비스·출력 계약을 둔다. 근거 밖의 검색/파일 접근/지식 저장은 하지 않는다. confirmed/inferred/conflicting/unknown, 근거 ID, 관계, 미해결 사항, 정성 품질을 검증한다. HTTP는 최소 검색/AI 검색 계약만 추가하고 관리자 bootstrap은 공개 HTTP로 노출하지 않는다.

검증은 별도 준비된 Python 런타임의 임시 SQLite와 모의 OpenAI, 기존 Node 테스트, typecheck/build/링크 검사로 수행한다. 기존 modified/untracked 소스의 비교 스냅샷은 /tmp/wiki-ai-phase1-before에 두며 업로드·DB·비밀값은 복사하지 않았다.