Skip to main content

Wiki v1 검증 기록

단계별 구현 결과, 회귀 검증과 확인할 수 없는 인수 조건

범위와 보존​

2026-09-23 로컬 소스 작업이다. 커밋·푸시·OCI 배포를 수행하지 않는다. 기존 소스의 작업 시작 상태를 기준으로 보존을 확인한다. DB·업로드·비밀값을 읽거나 변경하지 않는다.

단계별 기록​

단계변경 파일군검증 결과다음 단계 위험
0 현황wiki-inventory.md변경 전 typecheck/build, 검토 모델 5개 테스트 통과없는 SAP/OCI 문서를 있는 것으로 가정하지 않기
1 매핑wiki-implementation-map.md15개 기존 문서와 경로 확인, MOVE 없음metadata ID와 permalink 구분
2 탐색navbar, sidebars, 홈, hubs, 검색, catalog plugin, 공통 UI, 인프라 환경 문서typecheck/build 통과; plugin 파일 경로와 MDX anchor 초기 오류 수정 후 재통과관련 문서 존재 검증과 테마 조합
3 상세DocItem Content/Paginator, related frontmatter, 기존 소개 링크, 검색·관계 테스트typecheck/build, Node 8개 테스트 통과; 기존 route 정의 23개(중복 wrapper와 wildcard 제외 공개 URL 19개) 모두 보존실제 키보드·모바일 확인
4 기능 진입홈/상단/문서의 기존 업로드 진입, 지식 도구, 모달 접근성API·KnowledgeReview·자료 관리 등 보호 소스 15개 해시 동일; 준비된 Python 런타임에서 백엔드 16개 모의 테스트 통과운영 프록시·실제 모델은 검증 불가
5 품질브라우저 회귀, 대비·breadcrumb·모바일 너비 수정, 최종 기록데스크톱/모바일 동선, 모의 저장·재열기, 실제 dark mode, typecheck/build/Node/HTML 검사 통과실서비스와 없는 콘텐츠에 대한 제한은 아래에 기록

현재 문서들은 명시적인 순서를 갖지 않으므로 상세 이전·다음을 표시하지 않는다. 실제 순서가 있는 문서를 추가할 때 Docusaurus pagination_prev, pagination_next에 실제 doc ID를 명시하면 표시된다.

관계와 검색의 유지보수​

related는 processes(업무), modules(모듈), technical(기술), integration(연계), reference(참고) 그룹별 실제 Docusaurus doc ID 배열이다. 빌드 시 알 수 없는 그룹, 자기 참조, 잘못된 형식, 존재하지 않거나 공개 색인에 없는 대상은 오류로 처리한다. 제목/URL을 ID로 추정하지 않는다. 기존 본문 수동 링크는 유지한다.

검색 색인은 빌드할 때 공개 docs의 제목·설명·본문에서 생성된다. draft/unlisted는 제외하고 원본 업로드와 API 저장 내용은 읽지 않는다. 단순 부분 문자열 AND 검색이며 제목 일치를 우선한다. 문서 증가 시 성능 측정 후 검색 엔진 확장을 별도로 결정한다. 최근 수정 순서나 이용 빈도 데이터가 없어 홈에는 대표 문서라고 표시한다.

확인하지 않은 인수 조건​

  • 투자관리→IM→PS/연계, 모듈→PS: 원본 콘텐츠가 없어서 구현·통과 처리하지 않는다.
  • AI 지식 허브: AI 지식 원문이 없어서 빈 카드/라우트를 만들지 않는다. 기존 AI 분석 기능은 지식 도구에 유지한다.
  • OCI 전용 허브→실제 운영 매뉴얼: 저장소에 원본이 없어, 확인된 환경 경계→기존 API 배포 문서로 대체한다. 운영 환경 검증과 같지 않다.
  • 실파일 업로드, 실제 Docling 파싱, 실제 모델 품질·비용, OCI 인증/프록시/볼륨: 이번 로컬 검증 범위 밖이다.

재현 명령​

저장소 루트에서:

npm run typecheck
node --test tests/*.test.mjs
npm run build
git diff --check

백엔드는 기존에 준비된 별도 런타임에서 모의 서비스와 임시 SQLite·업로드만 사용한다:

cd services/knowledge-api
PYTHONDONTWRITEBYTECODE=1 /tmp/wiki-management-venv/bin/python -m unittest discover -s tests -v

Node 테스트의 MODULE_TYPELESS_PACKAGE_JSON 경고는 기존 package module 설정에서 발생하며 결과에는 영향이 없다. 경고 제거를 위해 프로젝트 전체 모듈 설정을 바꾸지 않는다.

이번 실행의 파일 변경 목록​

작업 시작 스냅샷 기준 기존 파일 14개 수정, 새 파일 19개 추가다. 원래부터 수정/untracked였던 파일은 이 목록의 신규 작업과 구분한다.

구분파일
설정·탐색 수정docusaurus.config.ts, sidebars.ts
홈·스타일 수정src/pages/index.tsx, src/pages/index.module.css, src/pages/knowledge.module.css, src/css/custom.css
기존 문서의 metadata/링크 추가docs/intro.mdx, docs/SAP/index.md, docs/SAP/Functional/index.md, docs/SAP/Technical/index.md, docs/Development/index.md, docs/Development/Infrastructure/index.md, docs/Development/Tools/index.md, docs/Development/Tools/knowledge-api-analysis.md
새 진입 페이지src/pages/sap.tsx, development.tsx, infrastructure.tsx, tools.tsx, search.tsx
새 공통 UIsrc/components/WikiNavigation/index.tsx, styles.module.css
새 상세 확장src/theme/DocItem/Content/index.tsx, src/theme/DocItem/Paginator/index.tsx
새 문서 데이터 처리plugins/wiki-catalog/index.ts, src/utils/wikiCatalog.ts
새 테스트tests/wiki-navigation.test.mjs, tests/wiki-build.mjs, tests/wiki-browser.mjs, tests/fixtures/wiki-v1-existing-routes.json
새 문서docs/Development/Infrastructure/environment-operations.md, 이 폴더의 wiki-inventory.md, wiki-implementation-map.md, wiki-verification.md

기존 15개 문서의 본문이 모두 그대로 포함되어 있음을 스냅샷과 비교했다. 원래의 수동 링크도 남아 있다. API·저장 계층·Dockerfile·검토 컴포넌트·자료 관리 로직·기존 테스트·AGENTS/.gitignore 등 보호 대상 15개 소스 파일은 해시가 동일하다. 홈의 handleAnalyze 함수도 byte 단위로 동일하다. API 문서는 frontmatter만 추가했다. .gitignore, AGENTS.md, 로그, 명세, 기존 백엔드/검토 작업을 되돌리지 않았다.

브라우저 검증 환경​

Playwright 1.63.0 / axe 4.13.0 / Chromium 153을 사용했다. Playwright/axe는 프로젝트 의존성을 바꾸지 않고 /tmp/wiki-v1-browser에 준비했다. Chromium 실행에 필요한 라이브러리와 한글 폰트가 기본 컨테이너에 없었다. 시스템 설치는 sudo 비밀번호가 필요했으므로 진행하지 않았고, 패키지를 임시 폴더에 추출하여 해당 프로세스에서만 사용했다. 저장소의 package.json/package-lock.json은 변경하지 않았다.

로컬 정적 빌드는 npm run serve -- --host 127.0.0.1 --port 4173 --no-open으로 제공한다. 모든 /api/** 요청은 브라우저 테스트가 모의 응답으로 가로채며 실제 API·DB·모델에 접속하지 않는다. 별도 브라우저 도구가 준비된 환경에서는 다음처럼 재현한다.

WIKI_BROWSER_TOOLS=/tmp/wiki-v1-browser/node_modules \
LD_LIBRARY_PATH=/tmp/wiki-v1-browser/libs/usr/lib/aarch64-linux-gnu \
FONTCONFIG_FILE=/tmp/wiki-v1-browser/fonts.conf \
node tests/wiki-browser.mjs

이 경로들은 이번 code-server 검증 환경의 임시 경로이며 운영 설정이 아니다. 일반적으로 Chromium 런타임이 준비된 환경에서는 LD_LIBRARY_PATH와 FONTCONFIG_FILE 설정 없이 실행할 수 있다. WIKI_TEST_URL과 WIKI_TEST_OUTPUT으로 로컬 서버와 결과 디렉터리를 변경할 수 있다.

빌드 산출물의 실제 링크와 기존 URL 검사는 다음 명령을 추가로 실행한다.

node tests/wiki-build.mjs

검증 중 수정한 문제​

  • plugin 로더의 TS 진입 파일 경로를 명시했다.

  • 이 설정에서 지원하지 않는 수동 MDX anchor 구문을 제거했다.

  • 업로드 모달 제목의 불필요한 permalink를 제거해 키보드 순환을 명확히 했다.

  • 모달 배경에 테마의 불투명 surface 색상을 사용했다.

  • axe가 찾은 기존 light breadcrumb, YAML key와 light/dark code comment 대비 부족을 수정했다.

  • 모바일 메뉴는 기존 Docusaurus의 닫기 버튼으로 검증한다. Escape 닫기는 업로드 모달에서 제공하며 테마 메뉴에 새 동작을 추가하지 않았다.

  • 영역 sidebar에 명시적 부모 category를 유지해 native breadcrumb가 홈 → 개발 → 도구 → 상세, 홈 → SAP → Functional처럼 표시되도록 수정했다. 중복 index 자식은 generator에서 제외한다.

  • 실제 data-theme=dark를 확인한 다음 dark-mode 검증을 수행한다. 테마가 적용되지 않은 검사는 dark 검증으로 집계하지 않는다.

  • 기존 자료 관리 페이지의 모바일 너비가 테이블의 최소 너비까지 확장되는 것을 발견해 knowledge.module.css의 .page에 width: 100%와 min-width: 0만 추가했다. 테이블 내부 스크롤, 필터 및 조회·검토 로직은 유지한다. 이 CSS는 byte 단위 보존 대상에서 제외하고 변경 전후 diff를 확인했다.

최종 검증 결과​

검증결과와 범위
TypeScriptnpm run typecheck 통과
정적 빌드npm run build 통과; SSR 및 broken-link 검사 포함
Node 테스트기존 검토 모델 5개 + 검색/관계 3개, 총 8개 통과
백엔드 테스트준비된 Python 런타임에서 16개 통과; 임시 SQLite/파일과 모의 OpenAI/Docling 사용
빌드 HTML 검사기존 공개 URL 19개와 새 진입 URL 5개 유지; 모든 로컬 링크·anchor와 명시적 pagination 정책 검사 통과
브라우저 동선Chromium에서 SAP/인프라/검색/직접 URL/업로드·검토/모바일/다크 모드 검사 통과
업로드와 검토 회귀모의 업로드 실패와 재시도 → 분석 → 제목 저장 → 요약 수정·저장 → 자료 관리 재열기 통과; AI 원본 요약 유지 확인
화면 폭1440px desktop, 390px mobile 메뉴·사이드바·관련 링크·업로드·자료 관리, 320px 문서의 수평 넘침 없음
접근성홈 desktop light, 업로드 모달, 검토 모달, 문서 mobile light, 홈 mobile dark, 문서 mobile dark 총 6개 화면에서 axe WCAG 2 A/AA 및 2.1 AA 위반 0개
브라우저 오류테스트 중 pageerror 0개
기존 콘텐츠최초 15개 문서 본문 모두 보존; 원본 문서 이동·삭제·중복 복제 없음
변경 검토git status / git diff 확인, git diff --check 통과; 커밋·푸시·배포 없음

자동 접근성 검사는 모든 사용자·스크린리더·브라우저 조합의 접근성을 보장하지 않는다. 화면 캡처는 실제 운영 화면이 아닌 로컬 production build의 Chromium 결과다.

대표 동선 판정​

  1. 홈 → SAP → Functional → 관련 Technical → SAP: 통과. 실제 투자·IM·PS 시나리오를 대신하는 현재 콘텐츠 동선이며 원래 시나리오는 보류다.
  2. 홈 → 인프라 → 환경 경계 → API 상세 → 관련 환경 경계 → 인프라: 통과. OCI 서버 운영 사실을 새로 확인한 것은 아니다.
  3. 홈에서 SAP 검색, 한국어 본문 영속 볼륨 검색, 영역 필터, 결과 없음: 통과. 결과 카드에서 제목·영역·문서 유형 확인.
  4. 기존 /docs/intro, /docs/SAP/, /docs/Development/Tools/knowledge-api-analysis, /knowledge, /markdown-page 직접 접속: 통과.
  5. 지식 도구 → 기존 자료 추가 → 오류/재시도 → 분석 → 메타데이터·검토본 저장 → 자료 관리 재열기: 모의 API로 통과.
  6. 모바일 상단 메뉴·현재 영역 sidebar·표의 페이지 내 수용·관련 링크 및 업로드: 통과. 코드/표의 내부 가로 스크롤은 유지한다.

검토 자료​

브라우저 결과 JSON과 스크린샷은 소스 트리 밖의 /tmp/wiki-v1-validation/에 있다. browser-results.json, home-desktop.png, home-mobile-dark.png, detail-mobile.png, upload-mobile.png, review-desktop.png를 생성하고 화면을 확인했다. 테스트 데이터는 모의 값이다. 임시 디렉터리는 다음 세션에서 없어질 수 있으므로 테스트 스크립트를 재실행할 수 있다.

권장 다음 단계​

확인된 원문을 확보해 투자관리/IM/PS와 AI 지식 문서를 실제로 작성하고 해당 관점의 허브를 확장한다. 실제 OCI 운영 문서도 확인된 설정을 근거로 보강한다. 이후 별도로 승인된 비운영 환경에서 실제 업로드·Docling·분석·검토 저장·프록시 흐름을 확인한 다음 운영 배포 여부를 결정한다. 이번 작업은 DB/API/저장 경로, Docker 배포 방식, 비밀값을 변경하지 않았다.

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

위의 v1 검증 기록은 이전 milestone의 결과다. 현재 구현 계약은 Knowledge API 분석 설계의 추가 절을 따른다. 기존 업로드 모달 검증은 자료 관리 업로드·명시적 분석·기존 URL 연결 검증으로 대체한다.

실행 환경과 검증 범위​

기존 /tmp/wiki-management-venv/bin/python을 사용하는 준비된 테스트 런타임을 확인했다. 기본 Python/Docker 실행이나 운영 OCI에 접근하지 않는다. 백엔드는 모든 테스트마다 TemporaryDirectory의 SQLite/파일을 사용하고 OpenAI/Docling을 모의 처리한다. Node 테스트와 브라우저는 기존 준비된 도구를 재사용하며 프로젝트 의존성을 추가하지 않았다.

code-server 정적 UI 미리보기​

기존 DOCUSAURUS_BASE_URL 환경변수와 code-server absproxy 패턴을 사용한다. 서버가 URL prefix를 유지해야 하므로 /proxy/ 대신 /absproxy/다. 사용 가능한 예시 포트 4174에서:

cd /workspace/wiki
DOCUSAURUS_BASE_URL=/absproxy/4174/ npm run build
DOCUSAURUS_BASE_URL=/absproxy/4174/ npm run serve -- --host 0.0.0.0 --port 4174 --no-open

브라우저에서 https://<현재-code-server-호스트>/absproxy/4174/를 연다. 같은 포트가 이미 사용 중이면 기존 프로세스를 임의 종료하지 말고 다른 포트를 선택하고 두 명령과 URL의 포트를 모두 맞춘다. 이 빌드는 로컬 미리보기 산출물일 뿐 배포하지 않는다. 일반 루트 경로 빌드를 복구하려면 npm run build를 실행한다. 설정 파일을 수정할 필요 없다.

자료 관리 /absproxy/4174/knowledge, 지식 추가 /absproxy/4174/knowledge-add, 저장 지식 /absproxy/4174/knowledge-entries를 확인한다. /?add-source=1의 호환 동선도 해당 base URL 안에서 자료 관리로 이동한다. API 요청은 기존과 동일하게 origin의 /api/**이며 정적 미리보기 서버가 백엔드를 제공하지 않는다. 실제 API 프록시가 없는 code-server 미리보기에서는 API 조회 오류가 예상된다. 저장·업로드 동작 검증은 아래 mock 브라우저 테스트 또는 별도로 준비한 비운영 backend 연결에서 수행한다.

재현 명령​

npm run typecheck
node --test tests/*.test.mjs
npm run build
node tests/wiki-build.mjs
git diff --check
cd /workspace/wiki/services/knowledge-api
PYTHONDONTWRITEBYTECODE=1 /tmp/wiki-management-venv/bin/python -m unittest discover -s tests -v

루트 경로 production build를 로컬 4174에서 제공한 상태에서:

WIKI_TEST_URL=http://127.0.0.1:4174 \
WIKI_TEST_OUTPUT=/tmp/wiki-v2-validation \
WIKI_BROWSER_TOOLS=/tmp/wiki-v1-browser/node_modules \
LD_LIBRARY_PATH=/tmp/wiki-v1-browser/libs/usr/lib/aarch64-linux-gnu \
FONTCONFIG_FILE=/tmp/wiki-v1-browser/fonts.conf \
node tests/wiki-browser.mjs

브라우저 테스트는 /api/**를 가로채므로 운영 API에 요청하지 않는다. 결과와 화면은 /tmp/wiki-v2-validation/에 기록한다.

최종 결과​

항목결과
TypeScriptnpm run typecheck 통과
production buildnpm run build 통과, SSR·broken-link 검사 포함
Node기존 검토 모델·검색·관계 테스트 8개 통과
backend26개 통과. 기존 16개 + 신규 10개. 모두 임시 DB/업로드 및 모의 외부 서비스
HTML기존 공개 URL 19개와 신규 진입 7개 보존, 31개 페이지의 내부 링크/앵커 882개 통과
browserSAP/인프라/검색/기존 URL, 업로드 오류·재시도, 자동 AI 없음, 명시적 AI, 검토 저장·재열기, 자료 기반 지식, GPT 직접 저장·보완·원문 보존·재열기 통과
responsive1440px desktop, 390px 자료 관리·지식 작성·메뉴, 320px 문서. 검사 화면의 페이지 수평 넘침 없음
accessibility검사한 8개 화면에서 axe WCAG A/AA 위반 0개, pageerror 0개
absproxy별도 /absproxy/4175/ 빌드와 로컬 serve에서 이전 업로드 URL 이동, 지식 화면 이동, 저장 후 URL prefix 보존 통과. 실제 외부 code-server 접속 검증은 아님
diffgit status/diff 및 시작 소스 스냅샷 비교, diff whitespace 검사 통과
safety스냅샷의 기존 파일 삭제 0개, 기존 문서 본문 모두 보존. 변경 파일에 runtime DB/업로드/env 없음, 비밀키 패턴 검출 0개. 운영 DB/파일은 읽거나 변경하지 않음

브라우저 결과 JSON·모바일 화면은 /tmp/wiki-v2-validation/에 있으며 knowledge-mobile.png, repository-mobile.png 등을 확인했다. 실제 OpenAI 응답·Docling 처리·OCI 운영 상태를 검증했다는 의미가 아니다.

이번 milestone 파일 변경​

시작 스냅샷 기준 기존 파일 18개 수정, 5개 추가, 삭제 없음이다. Git HEAD에 비해 보이는 기존 v1 변경과 구분한다.

  • backend 수정: services/knowledge-api/main.py, storage.py, tests/test_analysis.py, tests/test_storage.py
  • backend 추가: services/knowledge-api/processing.py, tests/test_repository_knowledge.py
  • UI 수정: src/pages/index.tsx, knowledge.tsx, knowledge.module.css, tools.tsx, src/components/KnowledgeReview/index.tsx, src/components/WikiNavigation/index.tsx, src/theme/DocItem/Content/index.tsx, docusaurus.config.ts
  • UI 추가: src/pages/knowledge-add.tsx, knowledge-entries.tsx, src/utils/knowledgeApi.ts
  • 테스트 수정: tests/wiki-browser.mjs, tests/wiki-build.mjs
  • 문서 추가 기록: docs/Development/Tools/knowledge-api-analysis.md, wiki-v1/wiki-inventory.md, wiki-implementation-map.md, wiki-verification.md

AGENTS.md, .gitignore, 기존 로그/백업, package.json/package-lock.json, Dockerfile, 기존 분석 prompt/schema, 검토 내용 에디터/model, sidebar/검색/허브의 기존 구현은 이번 milestone에서 변경하지 않았다. 커밋·푸시·OCI 배포는 수행하지 않았다.

남은 실제 검증과 다음 milestone​

비운영 API 환경에서 실제 PDF/Word/Excel의 Docling 추출, 실제 configured model의 공통 분석·텍스트 보완, 소규모 복수 업로드 응답 시간, API 재시작 중 작업 복구, 프록시 timeout·인증·원본 다운로드·영속 볼륨을 확인한다. 운영 SQLite를 복제/초기화하는 작업은 이번에 수행하지 않았다.

후속 milestone은 실제 문서 기반 통합 검증과 운영 복구 절차, 필요 시 파일 크기 제한·목록 페이지네이션·작업 timeout·지식 편집 충돌 감지를 우선한다. 이후 근거 구절의 안정적인 참조와 사용자 승인 기반 Wiki 발행을 설계한다. 교차 도메인 추론은 관련 자료 검색과 provenance를 갖춘 뒤 별도 milestone으로 진행한다.

AI 검색 Phase 1 검증 (2026-09-24)​

이 실행은 자료·지식 저장소의 색인/검색/추론 백엔드와 문서만 변경했다. 기존 modified/untracked 작업은 /tmp/wiki-ai-phase1-before의 작업 시작 해시·소스와 비교한다. 운영 SQLite·업로드·OCI를 사용하거나 수정하지 않았다. 이전 검증 절은 각 milestone의 이력이다.

변경 파일​

기존 파일의 focused update:

  • services/knowledge-api/storage.py: additive search migration과 commit 후 객체별 색인 hook
  • services/knowledge-api/main.py: 구조화된 retrieve/reason 최소 API
  • docs/Development/Tools/knowledge-api-analysis.md: 현재 계약·절차·제한
  • docs/Development/Tools/wiki-v1/wiki-implementation-map.md: 구현 전 조사/설계
  • 이 verification 문서

새 파일:

  • services/knowledge-api/search_config.py: 중앙 환경설정/예산
  • services/knowledge-api/search_index.py: schema/trigger/청킹/증분/관리 CLI
  • services/knowledge-api/retrieval.py: query plan, typed evidence bundle, FTS/필터/다양성/중복 제거
  • services/knowledge-api/reasoning.py: 근거 전용 AI 서비스/strict 결과 검증
  • services/knowledge-api/tests/test_search.py: 새 색인·검색·추론·안전 회귀

프런트엔드/기존 tests/analysis.py/processing.py/Dockerfile/requirements 및 package 파일은 변경하지 않았다. 기존 source/entry schema·본문 갱신 SQL과 기존 분석/검토 원본 보존 조건을 유지한다. 새 색인은 source/entry 행을 삭제·덮어쓰지 않는다. 이전 chunk도 append-only이며 현재 generation만 검색한다.

검증 범위와 결과​

별도로 준비된 /tmp/wiki-management-venv/bin/python에서 임시 SQLite/업로드를 사용한다. 새 테스트는 실제 SDK 네트워크 호출을 차단한다. 초기 endpoint mock이 이중 import 때문에 적용되지 않아 테스트용 무효 키 요청이 거절된 문제가 있었으며, 정확한 module 객체 patch와 SDK request 차단으로 수정했다. 성공한 실제 모델 호출이나 실제 키 사용은 없다.

  • 백엔드 기존 26개 + 신규 28개 = 54개: bootstrap/legacy/additive migration, 생성·수정·재색인/재시도, 반복 실행, 원본 보존, 실패 rollback, stale 배제, orphan index 제외, FTS 미지원 및 복구, 설정 signature 변경, 한국어 모듈·의도·날짜 계획, 필터/식별자/모든 콘텐츠 계층, 후보 다양성/중복 provenance/예산, strict API/모의 추론·인용·충돌/부족·timeout·오류·비저장 계약.
  • Node 회귀 8개 통과: 기존 검토 모델과 Wiki 탐색/검색.
  • npm run typecheck 통과.
  • npm run build 통과.
  • node tests/wiki-build.mjs 통과: 기존 19개 및 신규 기준 경로 7개 보존; 31개 HTML 페이지의 링크/anchor 검사.
  • git diff --check 및 작업 시작 스냅샷 대비 새/수정 파일 whitespace 검사 통과. untracked 파일은 일반 Git diff에 포함되지 않으므로 별도로 비교한다.

실행 로그와 비교 결과는 /tmp/wiki-ai-phase1-validation에만 둔다. 명령은 저장소 루트에서 Node/typecheck/build/diff를 실행하고, 백엔드 디렉터리에서 다음을 실행한다.

PYTHONDONTWRITEBYTECODE=1 /tmp/wiki-management-venv/bin/python -m unittest discover -s tests -v

검증의 한계와 다음 단계​

실제 OpenAI의 한국어 의미/추론 정확도, Docling 변환, 운영 SQLite의 FTS5 지원·대규모 성능, 운영 인증·프록시·볼륨은 확인하지 않았다. source_date는 저장 시각이며 사건 날짜가 아니다. lexical 후보 누락과 미발견 충돌 가능성이 있고 자동 semantic 검증은 없다. 실제 데이터 bootstrap은 수행하지 않았다.

다음 단계는 비운영 MM/CO/PP 문서 세트로 검색 재현율·충돌/누락 응답을 평가한 뒤, 일반/AI 검색 UI·근거 보기·비동기 상태/취소·사용자 검토 후 지식 저장·권한/rate limit 계약을 구현하는 것이다. knowledge-api와 문서 공개용 Docusaurus 서비스는 향후 운영 적용 시 rebuild가 필요하지만 OCI 서비스 키는 미확인이다. commit/push/deploy/운영 rebuild는 수행하지 않았다.

AI Search Phase 1.5 검증​

2026-09-27. stopword/relevance cutoff/coverage expansion을 구현했다. 변경 파일은 services/knowledge-api/retrieval.py, search_config.py, reasoning.py(payload 생성 코드 공유), 신규 tests/test_search_quality.py, knowledge-api-analysis.md와 이 문서다. 기존의 다른 작업 변경은 유지했다.

자동 검증​

기존 준비된 /tmp/wiki-management-venv/bin/python에서 임시 DB/업로드와 mock AI를 사용했다. production DB에 접근하지 않았다.

  • 신규 16개: 한국어/영어 stopword, SAP identifier/숫자, 보수적 coverage 판별, 58/51 대 6/4 cutoff, limit 미충족과 counts, 약한 top, 37 Activity 순차 coverage, focused 확장 미호출, MM/CO/PP 분배, chunk/char/context 예산, authoritative layer/substring fallback, additive plan/config, 원본/identity 보존, coverage 필터/stale 제외, 중복 provenance.
  • 기존 54개 포함 backend 전체 70개 통과. metadata/extracted_text/analysis/knowledge 검색, dedup, targeted reindex, scope/필터, FTS fallback, evidence-only reasoning/비저장/confirmed·inferred, incompatible index 회귀 포함.
  • Node 회귀 8개 통과, npm run typecheck 및 npm run build 통과.
  • git diff --check 통과. 기존 untracked backend/문서는 /tmp/wiki-phase15-before 스냅샷과 별도 diff 검토.
# services/knowledge-api에서 실행
PYTHONDONTWRITEBYTECODE=1 /tmp/wiki-management-venv/bin/python -m unittest discover -s tests -v
# 저장소 루트에서 실행
node --test tests/*.test.mjs
npm run typecheck
npm run build
git diff --check

대표 Query 수동 검증 — 합성 fixture​

임시 DB에 313 repository 원문, Storage만 겹치는 PS/MM 투자 문서, 37 Activity의 NIMS knowledge를 생성하고 요청한 Q1/Q2/Q3를 직접 호출했다. 운영 NIMS 원문 검증이나 실제 AI 호출은 아니다.

Query결과
Q1: 313 Stock Transfer Storage Location to Storage Location in Two Steps Removal from Storagefocused, extracted_text 최상위 43.0, evidence 1개/source 1개. 투자 문서 제외, low_relevance_candidates_dropped
Q2: NIMS Cut-over에서 선이행, 본이행, 후이행 전체 작업을 단계별로 정리해줘broad_object, knowledge_content 3 chunk/source 1개. Task 37까지 포함, budget warning 없음
Q3: NIMS Cut-over에서 Go/No-Go 판단 기준은 뭐야?focused, Go/No-Go 포함 knowledge_content 최상위 13.5868. 확장 없이 lexical evidence 4개. 제목 일치로 다른 chunk도 반환 가능

호환성·한계·다음 단계​

SearchRequest 원문, endpoint, ReasoningResult를 유지하며 QueryPlan.coverage_mode만 default를 가진 additive 필드다. 원본/색인 schema, identity, generation, signature 변경이나 migration은 없다. DB 초기화·자료 삭제·runtime 이동·production DB 변경 명령·OCI 배포·commit/push를 수행하지 않았다. /search와 기존 upload/analysis 구현은 수정하지 않았다.

cutoff 기본값은 absolute 3.0/relative 0.2이고 운영 corpus에 따른 조정이 필요할 수 있다. coverage 최대 3 object와 기존 source당 4 chunk 제한을 유지한다. 긴 문서는 coverage_truncated_by_budget/partial로, 객체 선정 제한은 coverage_object_scope_limited로 알린다. 전체 자료의 완전성·대규모 성능·실제 모델 품질은 미검증이며 semantic search는 미도입이다.

Phase 2 UI는 passage/원본 계층/navigation_ref/중복 참조 및 confirmed/inferred/unknown을 연결하고 부분 coverage·모듈 부족·색인 미완료를 사용자 문구로 표시한다. cutoff 기술 경고는 상세 진단으로 처리한다. 이번 작업은 UI·배포를 포함하지 않는다.