[HCR-226] 회원별 키워드 집계기(Aggregator) 구현 및 추출 파이프라인(Stage 2, 3) 정확도 개선

[YeongHyeonHeo]

📝작업 내용

1. Aho-Corasick 오토마톤 중복 매핑 버그 수정 (Stage 2)

• 사전 빌드 시 동일한 텍스트에 같은 keyword_id가 중복으로 등록되어 카운트가 2배로 집계되는 버그를 수정했습니다.

2. 회원(member_id) 기준 분석 결과 집계기 구현 (aggregator.py)

• 분산된 여러 청크 파일(chunk-*.mapping.jsonl.gz)을 읽어들여, member_id 기준으로 키워드 출현 횟수를 누적(+) 합산하는 로직을 추가했습니다.

• 백엔드(Spring) 배치에서 바로 읽어갈 수 있도록 최종 결과를 단일 파일(aggregated_summary.json)로 원자적 저장합니다.

3. 오타 교정(Fallback) 알고리즘 고도화 (Stage 3)

• spaCy AI가 미등록 단어(오타)의 품사를 명사(NOUN)가 아닌 부사(ADV), 접속사(SCONJ) 등으로 오판하여 오타 교정에서 누락되는 현상을 해결했습니다.

4. 파이프라인 통합 E2E 테스트 검증 완료

• 중복 카운트 방지, 다메라우-리벤슈타인 오타 교정, 회원별 누적합 집계가 정상적으로 이어지는지 검증하는 통합 테스트 코드를 작성했습니다.

👀변경 사항

• app/pipeline/extractor.py: 오토마톤 트리에 단어를 추가하는 _add_to_automaton() 내부에 동일 keyword_id 중복 검증 방어 로직이 추가되었습니다.

• app/pipeline/scorer.py: 다메라우 연산을 위한 명사 추출 로직 변경

  • 형태소 분석 허용 범위를 대폭 확대했습니다. (NOUN, PROPN ➔ ADV, SCONJ, X, VERB, ADJ 추가)

  • 과도하게 단어가 뭉치는 것을 방지하기 위해 띄어쓰기(token.whitespace_)를 기준으로 검사 덩어리를 분리하도록 수정했습니다.

• app/pipeline/aggregator.py: ResultAggregator 클래스를 통해 Job 단위의 최종 통계를 산출합니다.

• tests/test_e2e.py: Stage 3(다메라우 연산)의 완벽한 테스트 커버리지를 위해 Mock 데이터의 구조를 일부 변경하고(의도적인 미등록 오타 주입), Analyze -> Aggregator로 이어지는 연속 실행 검증 로직을 추가했습니다.

🎫 Jira Ticket

• Jira Ticket: HCR-226

#️⃣관련 이슈

• closes [HSC-226] Aho-Corasick 중복 카운트 수정 및 회원(member_id) 단위 키워드 집계기(Aggregator) 구현 #13

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

이 Pull Request는 키워드 추출 파이프라인의 정확성을 높이고 사용자별 키워드 사용 통계를 효율적으로 집계하기 위한 개선 사항을 포함합니다. 기존의 중복 카운팅 버그를 수정하고, 오타 교정 알고리즘의 탐지율을 향상시켰으며, 여러 분석 결과를 회원 ID 기준으로 통합하는 새로운 집계 모듈을 도입하여 데이터 처리의 신뢰성과 유용성을 증대시켰습니다.

Highlights

• Aho-Corasick 오토마톤 중복 매핑 버그 수정 (Stage 2): 동일한 텍스트에 같은 keyword_id가 중복 등록되어 카운트가 2배로 집계되던 문제를 해결했습니다.
• 회원별 키워드 집계기 구현 (aggregator.py): 분산된 청크 파일에서 member_id 기준으로 키워드 출현 횟수를 누적 합산하고, 백엔드에서 읽기 쉬운 단일 파일로 저장하는 로직을 추가했습니다.
• 오타 교정(Fallback) 알고리즘 고도화 (Stage 3): spaCy AI가 미등록 단어의 품사를 오판하여 오타 교정에서 누락되던 현상을 개선하기 위해 형태소 분석 허용 범위를 확장하고 띄어쓰기 기반으로 단어 덩어리를 분리하도록 수정했습니다.
• 파이프라인 통합 E2E 테스트 검증 완료: 중복 카운트 방지, 다메라우-리벤슈타인 오타 교정, 회원별 누적합 집계가 정상적으로 작동하는지 확인하는 통합 테스트 코드를 작성하고 검증했습니다.

Changelog

• app/pipeline/aggregator.py
  • ResultAggregator 클래스가 추가되어 여러 청크 파일에서 member_id별 키워드 출현 횟수를 누적 합산하고, 최종 결과를 aggregated_summary.json 파일로 저장하는 기능이 구현되었습니다.
• app/pipeline/extractor.py
  • _add_to_automaton 함수에 동일한 keyword_id가 중복 등록되는 것을 방지하는 로직이 추가되었습니다.
• app/pipeline/scorer.py
  • rescue_typos 함수에서 오타 교정을 위한 형태소 분석 허용 품사(POS)가 NOUN, PROPN 외에 ADV, SCONJ, X, VERB, ADJ로 확장되었습니다.
  • 단어 덩어리 분리 로직이 token.whitespace_를 기준으로 추가되어 과도한 단어 뭉침을 방지합니다.
  • 디버깅을 위한 print 문이 추가되었습니다.
• e2e_test_efs/analysis/res/job-2026/aggregated_summary.json
  • E2E 테스트 결과로 생성된 집계 요약 파일이 추가되었습니다.
• e2e_test_efs/analysis/res/job-2026/chunk-01.chunk.json
  • 테스트용 청크 파일의 recordCount 및 processedAt 필드가 업데이트되었습니다.
• e2e_test_efs_agg/analysis/res/job-9999/aggregated_summary.json
  • test_aggregator.py 테스트 결과로 생성된 집계 요약 파일이 추가되었습니다.
• tests/test_aggregator.py
  • ResultAggregator 클래스의 회원별 키워드 집계 기능을 검증하는 단위 테스트가 추가되었습니다.
• tests/test_e2e.py
  • test_analyze_e2e 함수에서 Aho-Corasick 중복 카운트 버그 재현 및 오타 교정 테스트를 위한 mock 데이터가 수정되었습니다.
  • ResultAggregator를 사용하여 분석 결과의 집계까지 검증하는 로직이 추가되어 파이프라인 통합 테스트가 강화되었습니다.

Activity

• Jira 티켓 HCR-226과 연동되었습니다.
• 이슈 #13이 이 Pull Request로 인해 해결되었습니다.
• 새로운 기능 구현 및 버그 수정을 포함하는 여러 파일이 추가/수정되었습니다.
• 새로운 단위 테스트와 E2E 테스트가 추가되어 변경 사항의 유효성이 검증되었습니다.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This PR aims to add member-based keyword aggregation and improve the accuracy of the existing analysis pipeline. The implementation includes a new aggregator.py for merging distributed result files and fixes a duplicate count bug in extractor.py, along with thorough E2E and unit testing. However, it's critical to address a security and privacy risk: several debug print statements in app/pipeline/scorer.py are logging customer input text, which likely contains Personally Identifiable Information (PII). These must be removed before merging. Additionally, consider improving code robustness and maintainability by standardizing logging, strengthening exception handling, and adopting a more concise code style.