[pcwadarong]

베이스가 dev가 아니라 feat/assistant-nl-query(#203)예요. #203이 머지되면 따라 들어갑니다.

목적

"조회가 성공했다"와 "질문에 답했다"가 지금 같은 숫자로 집계돼서, 실사용 품질을 알 수 없어요. 그 둘을 쪼개고, 틀렸을 가능성이 있는 자리를 결정론으로 모아 남겨요.

	전	후
성공의 정의	outcome: 'success' 하나	exec_ok(실행 성공) · answered(질문 충족) 분리
실패 분류	없음	8개 버킷 + 결정론 신호 6종
기록 위치	stdout → CloudWatch (흘러가면 끝)	assistant_query_logs 테이블 (90일)
대화 식별	없음	session_id · turn_index
정책 위반 가시성	validationFailures 숫자에 묻힘	policy_violations 배열로 분리

적용 범위: 자연어 조회 경로만. 사용자에게 보이는 응답은 한 글자도 바뀌지 않아요.

설계

1. answered를 지금 채우지 않아요 — 일부러 NULL이에요

exec_ok   = true   검증 통과 + 읽기 전용 TX 실행 완료   ← 서버가 결정론으로 안다
answered  = null   질문에 실제로 답했는지              ← 결정론으로는 알 수 없다

exec_ok = true인데 '다음 합주'가 아니라 '모든 미래 합주'를 조회한 답일 수 있어요. 그걸 코드가 직접 알 수는 없어요.

판정(LLM 또는 사람)을 이 PR에 넣지 않은 이유는 순서예요. 판정기를 넣으려면 판정기가 맞는지 검증할 사람 라벨이 먼저 필요하고, 그 라벨을 만들 실사용 로그가 지금 0건이에요. 판정기부터 넣으면 점수가 이상할 때 판정기를 의심하게 되고, 실제 원인이 정답지나 신호 쪽이면 엉뚱한 곳을 고치게 돼요.

exec_ok = true를 성공률로 보고하지 않기로 했어요. 그 숫자는 "실행이 됐다"는 뜻뿐이에요. 문서(assistant-analytics.md)에도 인용블록으로 세워뒀어요.

2. 결정론 신호 6종 — 모델을 쓰지 않아요

신호	기준	의심하는 것
EMPTY_RESULT	실행 성공 + 0행	조건을 너무 좁게 걸었다
ZERO_VALUE	단일 집계가 0 또는 NULL	JOIN이 끊겼다
ROW_LIMIT_REACHED	상한 50행 도달	목록을 좁히지 못했다
REGENERATED	SQL을 다시 만들었다	프롬프트가 못 잡은 자리
POLICY_VIOLATION	허용 목록 밖 시도	질문이 경계를 시험했다
MISSING_DATE_FILTER	질문에 기간 표현이 있는데 SQL에 시간 조건이 없다	전체 기간을 집계했다

MISSING_DATE_FILTER는 AST를 다시 파싱하지 않아요. 이미 검증기가 뽑아둔 parameterTypes에 DATE/TIMESTAMPTZ가 있는지와, SQL에 CURRENT_DATE 계열이 있는지만 봐요. 같은 사실을 두 번 계산하지 않으려고요.

ZERO_VALUE는 0이 정답인 질문도 있어서 실패로 단정하지 않고 신호로만 둬요. 그래서 bucket은 OK로 남고 판정에 넘어가요.

3. 재질문은 저장하지 않고 질의로 계산해요

가장 싼 오답 탐지기(사람이 바로 다시 물었다 = 앞 답이 틀렸다)인데, 일부러 컬럼으로 안 만들었어요.

쓰기 시점에 계산하면          분석 시점에 계산하면
──────────────────          ──────────────────
앞 턴을 다시 읽어야 함        추가 읽기 0
유사도 기준을 바꾸면          기준을 바꿔도 과거를 다시 해석 가능
  이미 저장한 행이 낡음

session_id · turn_index · question만 남기고, 윈도 함수 질의를 assistant-analytics.md에 적어뒀어요. pg_trgm 확장이 필요한 버전과 완전 일치로 시작하는 버전 둘 다요 — 확장을 켜는 건 별도 결정이라 이 PR에 안 넣었어요.

4. 보안 위반과 의미 위반을 클래스로 나눴어요

SqlPolicyViolationError extends InvalidSqlQueryError 를 추가했어요.

전: 둘 다 InvalidSqlQueryError
    → service가 같은 분기로 받아 재생성
    → validationFailures 숫자 하나에 합쳐짐
    → "허용 목록 밖 테이블을 시도한 질문이 있었나"를 나중에 알 수 없음

후: 상속이라 재생성 정책은 그대로. 분류만 나뉘어 policy_violations 에 남음

경계를 넘어간 것만 정책 위반으로 분류했어요 — TABLE_NOT_ALLOWED, FUNCTION_NOT_ALLOWED, WRITE_STATEMENT_BLOCKED 등 18곳. 반대로 BAND_SCOPE_MISSING·SOFT_DELETE_SCOPE_MISSING 같은 범위 조건 누락은 의미 위반으로 남겨뒀어요. 모델이 흔히 빠뜨리는 것이라 정책 위반에 넣으면 "경계를 시험했나" 신호가 노이즈로 묻혀요.

#203 본문에 "보안·구문 위반은 재생성 없이 즉시 거부" 라고 적혀 있는데, 코드는 assistant.service.ts의 한 분기에서 둘을 같이 받아 둘 다 재생성해요. 이 PR은 분류만 나누고 동작은 바꾸지 않았어요 — 재생성을 막을지는 로그를 보고 판단하는 게 맞다고 봤어요. 거부가 맞다고 보시면 본문과 코드 중 어느 쪽을 맞출지 알려주세요.

5. 측정이 제품을 막지 않게

try {
  await this.repository.recordQueryLog(entry);
} catch (error) {
  this.logger.warn(`질의 측정 기록에 실패했습니다: ${toMessage(error)}`);
}

• 기록 실패는 warn만 남고 조회 결과는 그대로 나가요
• ASSISTANT_QUERY_LOG_ENABLED=false 로 끄면 stdout 로그만 남아요 (호출 시점에 읽어서 재배포 불필요)
• 조회와 같은 트랜잭션에 넣지 않아요 — 읽기 전용 TX에서는 쓸 수 없고, 기록 실패가 조회를 되돌려서도 안 돼요
• stdout 로그는 그대로 유지했어요. 기존 CloudWatch Logs Insights 질의가 깨지지 않게 필드만 늘렸어요

6. session_id는 측정 전용이에요 — 권한에 쓰이지 않아요

클라이언트가 만든 값이라 신뢰하지 않아요. 밴드 범위는 서버가 멤버십을 확인한 bandId를 $1에 바인딩하는 그대로예요. 이 값을 조작해도 보이는 데이터는 같아요. DTO 주석과 OpenAPI 설명에도 적어뒀어요.

프론트에서는 useState가 아니라 useRef로 들고 있어요. 추천 칩을 연달아 누르면 setState가 반영되기 전에 다음 질문이 나가서 턴 순서가 밀리기 때문이에요.

그리고 다시 시도는 턴을 새로 세지 않아요. 같은 질문을 다시 보내는 것이라, 재시도가 턴 수를 부풀리면 턴별 실패율이 왜곡돼요.

Changes

해시	내용
94031eb	✨ feat: 추가 자연어 조회 품질 측정과 실패 신호

함께 고친 것

• 정책 위반이 validationFailures에 묻혀 구분되지 않던 문제 (위 4번)

고려했다가 버린 것

안	왜 버렸나
LLM 판정을 지금 붙이기	판정기를 검증할 사람 라벨이 먼저 필요하고, 라벨을 만들 실사용 로그가 0건이에요
재질문을 컬럼으로 저장	유사도 기준을 고치면 저장한 행이 낡아요. 질의로 계산하면 과거를 다시 해석할 수 있어요
WRONG_SCOPE·WRONG_METRIC 버킷을 미리 정의	결정론으로 판정할 수 없어요. 판정이 붙을 때 마이그레이션으로 추가해요
범위 조건 누락을 정책 위반으로 분류	모델이 흔히 빠뜨려서 "경계를 시험했나" 신호가 노이즈에 묻혀요
밴드·사용자에 FK 연결	텔레메트리는 도메인과 수명이 달라요. 밴드가 삭제돼도 측정 기록은 남아야 해요
범용 이벤트 테이블	제품 지표 대부분은 도메인 테이블의 created_at으로 이미 답해요. 정답지가 없는 조회 품질만 따로 남기면 돼요
신호를 전량 저장	신호가 안 붙은 행도 분모로 필요해서 전량 남겨요. 대신 보관 90일로 끊어요

리뷰 포인트

1. MISSING_DATE_FILTER의 질문 정규식 (assistant-query-signal.ts:38) — 오탐을 줄이려고 좁게 잡았어요. '이번'처럼 단독으로는 기간이 아닌 말은 넣지 않았는데, 빠진 표현이 있으면 알려주세요
2. 정책 위반 분류 경계 (위 4번) — COLUMN_NOT_ALLOWED를 정책 위반에 넣었는데, 모델이 컬럼명을 틀리는 건 흔해서 노이즈일 수 있어요. 로그를 보고 재분류할 생각인데 처음부터 빼는 게 맞을까요?
3. session_id를 신뢰하지 않는다는 전제 (위 6번) — 측정 외의 용도로 쓰이지 않는지 봐주세요
4. 보관 90일을 자동으로 지우는 장치가 아직 없어요 — 지금은 문서상 규칙이에요. 크론을 어디에 둘지(n8n? pg_cron?) 정해지면 붙일게요

Test plan

실제로 실행한 것만 적었어요.

• pnpm run lint (backend) — 0 errors / 2 warnings (둘 다 기존 schedules.service.spec.ts)
• pnpm run format:check (backend) — 통과
• pnpm run build (backend) — 통과
• npx jest (backend) — 59 suites / 972 tests 통과 (신규 27건)
• pnpm run test:assistant-evaluation — 17 pass / 0 fail
• pnpm exec prisma validate · prisma generate — 통과
• pnpm run lint (frontend) — 0 errors / 1 warning (기존)
• pnpm run build (frontend) — 통과
• npx vitest run (frontend) — 98 files / 505 tests 통과 (신규 3건)
• 실제 DB에 마이그레이션 적용은 미실행 — 로컬 Postgres 없이 작성했어요. prisma migrate dev 는 리뷰 후에요

후속

지금 범위 밖이고, 무엇을 기다리는지 적었어요.

다음	시작 조건
판정기 검증 장치 (사람 라벨 30건 + 합격선 파일 + 판정 실패는 unknown)	이 테이블에 로그 30건 이상 필요. UT 후
LLM 판정 1콜 → answered 채우기	위 합격선 통과 후. 신호 붙은 행 + 무작위 표본에만 붙여요
promoted_to_corpus로 평가 코퍼스 승격	판정 사례가 쌓인 뒤. 질문 원문은 한 글자도 고치지 않아요
호출 성격별 모델 분리	이 테이블에서 100건 샘플을 뽑아 비교표를 만들 수 있을 때
보관 90일 자동 삭제	크론 위치 결정 필요

promoted_to_corpus 컬럼은 지금 아무도 쓰지 않지만 미리 뒀어요. 로그를 쌓기 시작한 뒤에 추가하면 그 전 기간의 행을 승격 후보에서 구분할 수 없어서요.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Repository: BandCo-House/BandCo/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 013f65b7-7393-43e9-8e3f-afbfb40418f0

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[njm1250]

이제 실행은 됐는데 답이 좀 이상했던 경우도 로그로 같이 살펴볼 수 있겠네요! 감사합니다 수고하셨어요~

[njm1250]

이 제한은 대화가 너무 길어지는 걸 막으려는 의도일까요? 100 제한 자체는 괜찮아 보여요. 다만 현재는 상한을 넘으면 400 오류가 나고 재시도도 계속 실패해서, 사용자에게 대화 상한을 안내하고 새 대화로 이어갈 수 있게 처리하면 좋을 것 같아요.

[pcwadarong]

의도는 대화 길이 제한이 아니라 그냥 컬럼 범위 가드였어요. 그런데 PR 본문에 "측정이 제품을 막지 않게"라고 써놓고 측정 필드로 400을 내고 있는게 모순이라 @max를 빼고 기록할 때 깎도록 했어요.

사용자에게 보이는 대화 상한 안내는 따로 작업하시는 5턴 작업에 더 맞을 것 같은데 부탁드려도 될까요~?