docs(changelog): v0.1.34 #331 VectorService batchUpdate 기록

- N+1 단건 jdbc.update → 단일 jdbc.batchUpdate(SqlParameterSource[])
- UUID 인라인 변환 → IdGenerator.newId() 공통 유틸
- 현재 N=1로 영향 작으나, chunk 분할 도입 시를 위한 사전 정비
- 회귀 없음: 동일 INSERT SQL, 동일 파라미터 매핑

설계서: docs/design/331-vector-batch-insert/README.md

Refs: #331 (Developer 단계)

CHANGELOG.md

@@ -6,6 +6,20 @@
 
 ## 2026-06-15
 
+### ⚡ #331 VectorService batchUpdate (v0.1.34)
+- saveRestaurantVectors: N+1 단건 INSERT → 단일 jdbc.batchUpdate(SqlParameterSource[])
+- UUID 인라인 변환 제거 → IdGenerator.newId() 공통화
+- 현재 N=1이지만 chunk 분할 도입 시 효과 본격화
+- 설계서: docs/design/331-vector-batch-insert/README.md
+- Refs: #331 (close)
+
+### ⚡ #326 parseJson 단일 패스 (v0.1.33)
+- OciGenAiService.parseJson 잘린 배열 복구를 brace depth counter 단일 패스로 교체
+- 이전 O(N²) + Jackson 예외 양산 → O(N) + 명시적 에러 경로
+- 문자열/escape 처리 정확
+- 설계서: docs/design/326-parsejson-optimization/README.md
+- Refs: #326 (close)
+
 ### 🛡️ #332 Restaurant PUT 화이트리스트 명시 (v0.1.32)
 - ALLOWED_UPDATE_FIELDS set으로 PUT /api/restaurants/{id} body 필터
 - 허용 외 키 silent drop + DEBUG 로그

backend-java/src/main/java/com/tasteby/service/VectorService.java

@@ -1,10 +1,12 @@
 package com.tasteby.service;
 
+import com.tasteby.util.IdGenerator;
 import com.tasteby.util.JsonUtil;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
 import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.jdbc.core.namedparam.SqlParameterSource;
 import org.springframework.stereotype.Service;
 
 import java.util.*;
@@ -64,6 +66,9 @@ public class VectorService {
 
     /**
      * Save vector embeddings for a restaurant.
+     *
+     * #331 — N개 청크를 단일 batchUpdate 호출로 처리 (이전: N+1 INSERT round-trip).
+     * UUID 생성은 IdGenerator.newId() 공통 유틸 사용 (인라인 변환 코드 제거).
      */
     public void saveRestaurantVectors(String restaurantId, List<String> chunks) {
         if (chunks.isEmpty()) return;
@@ -75,19 +80,20 @@ public class VectorService {
             VALUES (:id, :rid, :chunk, :emb)
         """;
 
+        SqlParameterSource[] batch = new SqlParameterSource[chunks.size()];
         for (int i = 0; i < chunks.size(); i++) {
-            String id = UUID.randomUUID().toString().replace("-", "").substring(0, 32).toUpperCase();
+            List<Double> emb = embeddings.get(i);
-            float[] vec = new float[embeddings.get(i).size()];
+            float[] vec = new float[emb.size()];
             for (int j = 0; j < vec.length; j++) {
-                vec[j] = embeddings.get(i).get(j).floatValue();
+                vec[j] = emb.get(j).floatValue();
             }
-            var params = new MapSqlParameterSource();
+            batch[i] = new MapSqlParameterSource()
-            params.addValue("id", id);
+                    .addValue("id", IdGenerator.newId())
-            params.addValue("rid", restaurantId);
+                    .addValue("rid", restaurantId)
-            params.addValue("chunk", chunks.get(i));
+                    .addValue("chunk", chunks.get(i))
-            params.addValue("emb", vec);
+                    .addValue("emb", vec);
-            jdbc.update(sql, params);
         }
+        jdbc.batchUpdate(sql, batch);
     }
 
     /**

docs/design/331-vector-batch-insert/README.md

@@ -0,0 +1,81 @@
+# 설계서: VectorService batch insert + IdGenerator 공통화 (#331)
+
+> **상태**: Approved
+> **작성**: [AI] Architect · **최종수정**: 2026-06-15
+> **추적성** — Redmine: #331 · 부모: #293 (검색/벡터 Reviewer 후속, 09-Done)
+> · 구현 파일: `backend-java/src/main/java/com/tasteby/service/VectorService.java`
+> · 테스트: 본 이슈 범위 밖 (단위 테스트 인프라 도입은 #343 후속 묶음에 해당)
+
+## 1. 목적 (Why)
+
+`VectorService.saveRestaurantVectors`가 chunk N개를 N번의 단건 `jdbc.update`로 처리한다. 현재 `buildChunks`가 1개 청크만 반환해 N=1이지만, 향후 chunk 분할 도입 시 N+1 INSERT 비효율. 또한 UUID 생성 코드가 인라인 변환(`UUID.randomUUID().toString().replace("-", "").substring(0, 32).toUpperCase()`)으로 다른 곳의 `IdGenerator.newId()`와 중복.
+
+## 2. 범위
+
+- **포함**
+  - `jdbc.batchUpdate(sql, SqlParameterSource[])`로 단일 호출 전환.
+  - UUID 생성을 `IdGenerator.newId()` 공통 유틸로 교체.
+- **제외**
+  - 단위/통합 테스트 도입 (테스트 인프라 미도입 — 별도 후속 #343 묶음).
+  - `buildChunks`의 chunk 분할 로직 자체 변경 (현재 단일 청크 정책 유지).
+  - `restaurant_vectors` 스키마 변경.
+
+## 3. 인수조건
+
+- [ ] `saveRestaurantVectors`가 한 번의 `jdbc.batchUpdate` 호출로 N개 청크 삽입.
+- [ ] UUID 인라인 변환 제거 → `IdGenerator.newId()` 호출.
+- [ ] 회귀 없음 — 신규 식당 등록 시 `restaurant_vectors`에 정상 row 추가.
+- [ ] N=0 가드(`chunks.isEmpty()`)는 유지.
+
+## 4. 컨텍스트 & 제약
+
+- Spring `NamedParameterJdbcTemplate.batchUpdate(String, SqlParameterSource[])` 사용.
+- Oracle VECTOR 타입 파라미터는 `float[]`로 그대로 바인딩 가능 (`MapSqlParameterSource.addValue`).
+- 한 batch 안 `int[]` 반환 → batch 결과 카운트는 사용하지 않음(throw if 어쩌고 미적용).
+- `IdGenerator.newId()` 시그니처: `public static String newId()` → 32-char uppercase hex (현재 인라인과 동일).
+
+## 5. 아키텍처 개요
+
+```
+saveRestaurantVectors(restaurantId, chunks)
+   ├ if chunks.isEmpty() → return
+   ├ embeddings = genAi.embedTexts(chunks)
+   ├ params[] = build N개 MapSqlParameterSource
+   │      .addValue("id", IdGenerator.newId())
+   │      .addValue("rid", restaurantId)
+   │      .addValue("chunk", chunks.get(i))
+   │      .addValue("emb", float[] embeddings[i])
+   └ jdbc.batchUpdate(sql, params)
+```
+
+## 6. 함수 명세
+
+| 함수 | 책임 | 비고 |
+|------|------|------|
+| `VectorService.saveRestaurantVectors(id, chunks)` (수정) | batchUpdate 1회 | IdGenerator 사용 |
+
+## 7. 흐름
+
+1. embed 호출 (기존).
+2. `SqlParameterSource[]` 생성.
+3. `jdbc.batchUpdate(sql, params)` 단일 호출.
+
+## 8. 엣지케이스
+
+- **chunks 빈 배열**: 조기 return (기존 유지).
+- **embed 결과와 chunks 크기 불일치**: 현재 OCI GenAI는 입력 N → 출력 N 보장. 안전 가드 추가는 본 범위 밖 (필요 시 후속).
+
+## 9. 테스트 (수동만)
+
+- dev에서 신규 식당 등록(데몬 또는 수동 trigger) → `SELECT count(*) FROM restaurant_vectors WHERE restaurant_id = '...'` 정상 row 확인.
+
+## 10. 리스크 & 대안
+
+- **선택**: `NamedParameterJdbcTemplate.batchUpdate`. 단일 트랜잭션 + 단일 round-trip.
+- **대안 A**: `JdbcTemplate.batchUpdate(BatchPreparedStatementSetter)` — 더 저수준이지만 named param 손실.
+- **대안 B**: MERGE로 upsert — 동일 restaurant_id 재처리 시 중복 제거 가능. 다만 본 이슈 범위 밖.
+
+## 11. 미해결 질문
+
+- chunk 분할 정책(현재 1개 단일 청크) — 후속 (검색 정확도 vs 토큰 비용 트레이드오프 결정).
+- batchUpdate 결과 row 수 검증 — 운영 모니터링 도구 도입 후 결정.