Skip to content

[ai-assisted] feat(vector): add projection visualization api#381

Merged
donghyuck merged 1 commit into2.xfrom
codex/issue-380-vector-projections
Apr 30, 2026
Merged

[ai-assisted] feat(vector): add projection visualization api#381
donghyuck merged 1 commit into2.xfrom
codex/issue-380-vector-projections

Conversation

@donghyuck
Copy link
Copy Markdown
Owner

@donghyuck donghyuck commented Apr 30, 2026

Why

  • 관리자 React 화면에서 기존 tb_ai_document_chunk 벡터를 2D 산점도로 시각화할 수 있는 서버 API가 필요합니다.
  • 화면 요청 시마다 projection을 다시 계산하지 않고, 비동기 job으로 좌표를 생성해 저장해야 합니다.

What

  • tb_ai_vector_projection, tb_ai_vector_projection_point V603 migration을 추가했습니다.
  • studio-platform-ai에 vector projection core contract와 PCA generator를 추가했습니다.
  • starter-ai에 기존 tb_ai_document_chunk adapter, projection repository, projection job/service, search visualization service를 추가했습니다.
  • starter-ai-web/api/mgmt/ai/vectors/projections, /items/{vectorItemId}, /search-visualization API와 DTO를 추가했습니다.
  • 산점도 응답은 client 렌더링에 필요한 vectorItemId, targetType, sourceId, label, x, y, clusterId, allowlist metadata를 반환합니다.
  • 보안/리뷰 결과에 따라 metadata allowlist, query 2,000자 제한, projection item 10,000개 상한, executor rejection 실패 처리, projection scope 기반 search visualization 제한을 반영했습니다.
  • README와 CHANGELOG에 API 흐름, polling 기준, 제약을 문서화했습니다.

Related Issues

Validation

  • Command: ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test && git diff --check
  • Result: PASS
  • Command: ./gradlew test
  • Result: PASS

Risk / Rollback

  • Risk: 대량 벡터 projection job은 CPU/DB 부하가 발생할 수 있어 기본 상한을 10,000개로 제한했습니다. 실제 운영 데이터에서 추가 튜닝이 필요할 수 있습니다.
  • Rollback: 이 PR 커밋을 revert하고 V603 migration 적용 전이면 migration 파일도 함께 제외합니다. 이미 migration이 적용된 환경에서는 projection 테이블은 원본 벡터 테이블과 분리되어 있어 기능 비활성화 또는 테이블 미사용으로 후퇴할 수 있습니다.

AI / Subagent Usage

Checklist

  • commit message follows policy
  • issue template used or exception recorded
  • AI-Assisted value is correct
  • validation recorded
  • subagent usage recorded when used
  • CI / repository verification passed
  • human review completed before merge
  • no unrelated changes included

Issue:
- Closes #380

Why:
- 관리자 화면에서 기존 벡터 저장 테이블을 기반으로 2D 산점도 시각화 API가 필요하다.

What:
- 기존 tb_ai_document_chunk를 변경하지 않고 projection 상태/좌표 테이블과 V603 migration을 추가했다.
- PCA 기반 projection generator, JDBC repository, 비동기 job service, search visualization service를 추가했다.
- /api/mgmt/ai/vectors/projections, /items/{vectorItemId}, /search-visualization API와 클라이언트용 DTO를 추가했다.
- metadata allowlist, query 길이 제한, projection item 상한, executor rejection 처리, projection scope 기반 검색 제한을 반영했다.
- README와 CHANGELOG에 API 사용 흐름과 제약을 문서화했다.

Validation:
- ./gradlew :studio-platform-ai:test :starter:studio-platform-starter-ai:test :starter:studio-platform-starter-ai-web:test && git diff --check: PASS
- ./gradlew test: PASS

AI / Subagent Usage:
- AI-assisted: Yes
- Subagent used: Yes
- Delegated scope: code review and security review for issue #380
- Main author validation: subagent findings were reviewed, data exposure and lifecycle issues were addressed, targeted and full tests passed
@donghyuck donghyuck force-pushed the codex/issue-380-vector-projections branch from 58c0c03 to 66c5959 Compare April 30, 2026 03:43
@donghyuck donghyuck merged commit efa87c5 into 2.x Apr 30, 2026
2 checks passed
@donghyuck donghyuck deleted the codex/issue-380-vector-projections branch April 30, 2026 04:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant