ABAP-Indexing/ASSUMPTIONS.md

# ASSUMPTIONS — 계획서 §10 미결사항에 대한 진행 가정

계획서(§11.7)에 따라, 미결 사항은 가정을 두고 진행하고 여기에 기록한다.

## 1. DB: PostgreSQL 대신 SQLite 로 시작 (계획서 §2 와 다름)

- **가정/사유**: 개발 장비에 PostgreSQL 이 없고, 임베딩 모델이 미정이라 pgvector 가 아직
  필요하지 않다. SQLite + FTS5 로 키워드/2-gram 검색은 충분히 동작한다.
- **전환 경로**: `index/schema_postgres.sql` 에 계획서 §6.1 원안(pgvector, tsvector) 유지.
  `DATABASE_URL` 을 postgresql:// 로 바꾸고 `index/db.py` 에 pg 백엔드를 추가하면 된다
  (현재는 sqlite:// 만 구현 — pg URL 지정 시 명시적 에러).
- 전량(1만 본) 적재 후 성능 문제가 보이면 그 시점에 전환한다.

## 2. 임베딩 모델 미정 → 벡터 검색 보류

- GLM 계열 임베딩 API 사용 가능 여부 미확인. 확정 전까지 `search_programs` 는
  FTS(단어 + 한글 2-gram) + **용어 사전 동의어 확장** + LIKE 로만 동작한다.
- 동의어 확장은 원질의와 **분리된 2단 검색**이다(`query/expand.py`). `fts_or` 가 토큰과 2-gram 을
  전부 OR 로 잇는 재현율 편향 구조라, 동의어를 같은 식에 섞으면 정밀도가 더 나빠진다.
  동의어 히트는 `EXPANDED_WEIGHT` 감쇠를 받고 `matched_by='동의어 확장'` 으로 표시된다.
- **이 감쇠 계수는 아직 측정으로 정하지 않았다** — 정답셋(수정사항 7번)이 필요하다.
- `EMBED_*` 환경변수와 `index/embed.py` 어댑터 자리는 확보. 모델 확정 시
  요약 텍스트 임베딩 → 하이브리드(RRF) 로 확장한다.

## 3. GLM-5.2 인터페이스 / 키 미확보 상태의 실행 경로

- OpenAI 호환(`/chat/completions`, `response_format: json_object`)으로 가정
  (`summarize/llm_client.py`).
- **키가 없어도 Stage 3 을 돌릴 수 있다** (2026-09-16 추가). 백엔드 3종:
  - `api` — 환경변수 키로 호출. 429/5xx 는 지수 백오프로 재시도한다(`Retry-After` 존중).
  - `file` — 프롬프트를 `data/llm_jobs/<id>.prompt.md` 로 내놓고 `<id>.response.json` 을 기다린다.
    사람이 채워도 되고 코딩 에이전트가 프롬프트를 읽고 채워도 된다. `summarize/jobs.py` CLI 가
    목록·조회·**스키마 검증 저장**을 돕는다. 프롬프트 id 는 내용 해시라 재실행해도 같은 파일을 가리킨다.
  - `fake` — 스키마만 맞는 더미. 파이프라인 배선 검증용이며 **품질 검증이 아니다**.
- 무료 티어(OpenRouter `z-ai/glm-5.2:free`)로 시도한 이력이 `llm_usage_log` 에 남아 있고
  실패 원인은 전부 429 였다. 재시도가 없던 탓에 unit 이 `failed` 로 굳었다 — 지금은 재시도한다.
- 프로그램 요약은 unit 프롬프트의 문맥이므로 **요약이 먼저 확정돼야** unit 프롬프트를 내놓는다.
  (요약이 나중에 채워지면 unit 프롬프트 내용이 달라져 같은 unit 을 두 번 답해야 한다.)

## 4. 전역 클래스/펑션그룹 소스 미수집

- `zcl_fi_common` 등은 호출 그래프에서 외부 노드(external_name)로만 표시.

## 5. 테이블 정보(DD02T/DD03L) / T-Code(TSTC) 미확보

- `ddic_table`, `ddic_field`, `tcode` 테이블은 스키마만 존재. 데이터 확보 시 적재.

## 6. 소스 파일 단위

- 수집 파일 1개 = 프로그램 1개(MAIN_PROGRAM) 로 가정. 배열로 여러 프로그램이 오는
  형식이 발견되면 `ingest/normalize.py` 의 classify 를 확장한다.

## 7. 재수집/증분

- 전체 재수집 후 해시 비교 방식으로 가정. `program.source_hash` 가 같으면 스킵,
  다르면 구조 재적재 + `summary_status='stale'` 마킹(요약 재생성 대상).

## 8. unit 단위 증분은 v2

- 현재 로더는 프로그램 단위로 삭제 후 재적재. 해시가 같은 unit 의 요약·로직 조각은
  unit_id 가 동일하므로 재적재 후에도 보존된다(그 외 unit 의 조각은 삭제 → 재추출).

## 9. 인덱스 단위 = LLM 이 골라낸 로직 조각 (2026-09-16 구조 변경)

- 계획서의 "unit 마다 요약 하나" 대신, LLM 이 unit 코드를 읽고 **의미 있는 로직 조각**을
  0개 이상 골라내 각각 설명을 붙인다. 의미 없는 코드(선언·초기화·ALV 설정 …)는 인덱스에서 버린다.
- LLM 에게 코드를 보여주는 창은 파서 unit(300줄 초과 시 sub_chunks 창)이고, 프로그램 요약을
  문맥으로 함께 준다. 근거·대안 비교는 `docs/logic-chunk-design.md`.
- 조각의 줄 번호는 first_line 앵커로 검증·보정하고, 테이블·호출은 파서로 다시 뽑는다.
- 얇은 unit 색인(이름·주석·한 줄 요약)은 남겨 버려진 코드도 unit 이름으로는 도달 가능하게 한다.
- 조각의 크기 기준(3~80줄), 버리는 코드의 범위는 프롬프트 규칙이며 파일럿 결과로 조정한다.