[refactor/#56] 도메인 상태값 및 상수 enum 정리

[wantkdd]

✨ 작업 개요

도메인별로 흩어져 있던 상태값/타입 문자열을 공통 StrEnum으로 정리했습니다.
기능 동작과 API 응답 문자열은 유지하고, 내부 코드에서 같은 계약값을 한 곳에서 참조하도록 정리했습니다.

📄 작업 내용

• 공통 enum 정의 추가
  • RunStatus
  • TranscribeRunPhase
  • CommitAnalyzeRunPhase
  • TimelineStep
  • MatchStatus
  • CommitChangeDirection
  • CommitType
• 회의 분석 run 상태/phase에 enum 적용
• 커밋 분석 run 상태/phase에 enum 적용
• 커밋 매칭 상태와 커밋 타입 추론 로직에 enum 적용
• 커밋 변경 방향 검증값을 enum 기반으로 정리
• 적용사항 timeline step 프롬프트/임베딩 상수를 enum 참조로 변경
• 알 수 없는 timeline step은 502 대신 경고 로그 후 제외하도록 보강
• OpenAPI enum schema와 enum 값 안정성 테스트 추가

📌 관련 이슈

• close [refactor] 도메인 상태값 및 상수 enum 정리 #56

🔌 API 변경사항 (해당 시)

• 응답 문자열 값 변경 없음
• OpenAPI schema에는 RunStatus, TranscribeRunPhase, CommitAnalyzeRunPhase가 명명 enum component로 노출됩니다.
• Spring이 OpenAPI codegen을 사용한다면 최신 schema 기준으로 재생성이 필요할 수 있습니다.

✅ 검증

• uv run pytest → 103 passed
• uv run ruff check app tests → passed
• uv run ruff format --check app tests → passed

💬 기타 사항

• ApplicationTimelineItem.step은 LLM 변형 응답으로 인한 hard 502를 피하기 위해 str로 유지했습니다.
• enum 값 변경이 API 계약 변경으로 이어지지 않도록 테스트로 고정했습니다.

Summary by CodeRabbit

릴리스 노트

• Chores

  • 내부 상태 추적 및 타입 정의를 통합하여 데이터 일관성과 유효성 검증을 개선했습니다. 기존 산재된 타입 선언을 중앙 집중식 열거형으로 통합하여 코드 유지보수성을 강화했습니다.

• Tests

  • 내부 계약 일관성을 검증하는 새로운 테스트 케이스와 미처리 시나리오에 대한 오류 처리 테스트를 추가했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5faf6d2a-9d35-4c3e-9c86-4455c5d8f5df

📥 Commits

Reviewing files that changed from the base of the PR and between a7e61a5 and 96e33cf.

📒 Files selected for processing (12)

• app/core/enums.py
• app/domains/commit/schemas.py
• app/domains/commit/services/analyze_runs.py
• app/domains/commit/services/summarize.py
• app/domains/meeting_analysis/services/embedding.py
• app/domains/meeting_analysis/services/extraction.py
• app/domains/meeting_analysis/services/matching_scoring.py
• app/domains/pipeline/schemas.py
• app/domains/pipeline/services/analysis_runs.py
• app/domains/transcribe/router.py
• tests/test_application_embedding.py
• tests/test_domain_enums.py

---

📝 Walkthrough

Walkthrough

PR consolidates scattered string-literal statuses and locally-defined Literal type aliases across pipeline, commit, and meeting-analysis domains into a centralized app/core/enums.py module using StrEnum. All service and schema layers are updated to depend on and use these shared enums for run lifecycle states, timeline steps, and match statuses while preserving existing API contract values.

Changes

Enum 중앙화 및 도메인 마이그레이션

Layer / File(s)	Summary
Core enum 정의 app/core/enums.py	실행 상태(RunStatus), 회의/커밋 분석 단계(TranscribeRunPhase, CommitAnalyzeRunPhase), 타임라인 스텝(TimelineStep), 매칭 상태(MatchStatus), 커밋 메타데이터(CommitChangeDirection, CommitType)에 대한 StrEnum 정의 추가.
파이프라인 도메인 마이그레이션 app/domains/pipeline/schemas.py, app/domains/pipeline/services/analysis_runs.py, app/domains/transcribe/router.py	파이프라인 스키마 및 실행 서비스가 app.core.enums에서 RunStatus, TranscribeRunPhase를 임포트하고, 로컬 Literal 정의 제거. 수락된 실행 스키마에 phase 필드 추가. 실행 생성 및 상태 전환 헬퍼가 열거형 값을 사용하도록 마이그레이션. mark_run_phase 서명이 TranscribeRunPhase 타입으로 업데이트.
커밋 도메인 마이그레이션 app/domains/commit/schemas.py, app/domains/commit/services/analyze_runs.py, app/domains/commit/services/summarize.py	커밋 분석 스키마 및 서비스가 app.core.enums에서 RunStatus, CommitAnalyzeRunPhase, CommitChangeDirection을 임포트. 로컬 상태/단계 Literal 별칭 제거. 실행 레코드 저장소 및 모든 상태/단계 전환이 열거형 값을 사용하도록 마이그레이션. 정리/제거 로직이 열거형 멤버와 비교하도록 리팩터링.
회의 분석 열거형 통합 app/domains/meeting_analysis/services/embedding.py, app/domains/meeting_analysis/services/extraction.py, app/domains/meeting_analysis/services/matching_scoring.py	TimelineStep, CommitType, MatchStatus 열거형을 회의 분석 서비스에 통합. 타임라인 단계 상수를 열거형 값에서 파생. 미알려진 스텝 감지 및 경고 로깅 도입. Gemini 프롬프트 생성이 열거형 기반 스텝 값 사용. 커밋 타입 추론 및 매칭 상태 해결이 문자열 리터럴 대신 열거형 멤버 생성하도록 리팩터링.
열거형 계약 및 OpenAPI 검증 테스트 tests/test_domain_enums.py, tests/test_application_embedding.py	app.openapi() 스키마에 핵심 열거형이 올바르게 노출되고 열거형 값 집합이 기존 외부 API 계약과 일치하는지 검증. 미알려진 타임라인 스텝 처리 동작에 대한 새로운 테스트 추가.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• WhyLog-App/Whylog-AI#27: 커밋 분석 실행 status/phase를 Literal 문자열에서 공유 app.core.enums로 마이그레이션하는 것이 검색된 PR에서 도입된 비동기 커밋 분석 DTO/서비스의 Literal 상태/단계 값과 직접 겹침.
• WhyLog-App/Whylog-AI#57: 두 PR 모두 app/domains/meeting_analysis/services/embedding.py를 수정하여 application.timeline 스텝 이름을 해석하고 임베딩 컨텍스트에 통합하는 방식을 변경 (메인 PR은 TimelineStep/KNOWN_TIMELINE_STEPS를 통해, 검색된 PR은 협정/논의 컨텍스트 빌더 및 스텝 이름 상수 추가를 통해).
• WhyLog-App/Whylog-AI#10: 메인 PR이 app/domains/transcribe/router.py 및 app/domains/pipeline/schemas.py와 같은 파일에서 하드코딩된 문자열 리터럴을 공유 app.core.enums로 마이그레이션하는 것이 단계/상태 문자열 값을 사용하는 새로 추가된 전사/결정 비동기 실행 구현과 직접 겹침.

Suggested reviewers

• Yujin1219
• yj-044

Poem

🐰 열거형들이 한곳으로 모여,
문자열 혼란은 사라지고,
타입 안전함이 피어난다.
도메인 전역에 일관성 피고,
API 계약은 흔들리지 않으니,
참 좋은 정리의 시간이로다! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR 제목이 주요 변경사항(도메인 상태값 및 상수 enum 정리)을 명확하게 설명하고 있으며, 관련 이슈 #56을 명시하고 있습니다.
Description check	✅ Passed	PR 설명이 작업 개요, 작업 내용, 관련 이슈, API 변경사항, 검증 결과, 기타 사항을 포함하여 템플릿의 모든 필수 섹션을 충실히 작성했습니다.
Linked Issues check	✅ Passed	PR의 모든 변경사항이 이슈 #56의 요구사항을 충족합니다: enum 중앙화(RunStatus, TranscribeRunPhase, CommitAnalyzeRunPhase, TimelineStep, MatchStatus, CommitChangeDirection, CommitType), 각 도메인에 enum 적용, API 응답 문자열 유지, OpenAPI 스키마 노출, 전체 테스트 통과(103 passed).
Out of Scope Changes check	✅ Passed	모든 변경사항이 이슈 #56의 범위 내에 있습니다. 기능 변경 없이 enum 중앙화 및 내부 코드 정리에만 집중하고 있으며, API 응답 문자열은 유지되었습니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/wantkdd-domain-enums#56

---

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 and usage tips.}

[Yujin1219]

수고하셨습니다 !