feat: add local analysis orchestration

[seonghobae]

Summary

• add typed analysis job request and status contracts across shared types, the desktop shell, Tauri commands, and the Python engine CLI
• expose a narrow allowlisted Tauri IPC boundary for starting and polling local analysis jobs without opening a loopback HTTP listener
• harden the orchestration boundary with runtime engine discovery, strict schema validation, localized UI states, in-flight limiting, timeout handling, and pinned SBOM tooling

Verification

• ./scripts/harness/quickcheck.sh
• cargo check --manifest-path apps/desktop/src-tauri/Cargo.toml

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Summary by CodeRabbit

릴리스 노트

• 새로운 기능

  • 분석 작업 시작 및 추적: 데스크톱 앱에서 음악 분석을 시작하고 완료될 때까지 진행 상황을 실시간으로 추적합니다.
  • 상세 결과 표시: 노래 섹션, 악기별 역할, 화음 정보, 신뢰도 수준을 포함한 분석 결과를 표시합니다.
  • 한국어 지원: 분석 기능에 대한 한국어 번역이 추가되었습니다.

• 문서

  • 로컬 분석 오케스트레이션의 아키텍처 및 보안 지침이 추가되었습니다.

Walkthrough

분석 작업 조율을 위한 로컬 오케스트레이션 인프라를 구현합니다. Tauri IPC 명령(start_analysis_job, get_analysis_job_status)을 통해 데스크톱 프론트엔드에서 Python 서브프로세스를 호출하며, 공유 타입, Rust 백엔드 로직, CLI 엔트포인트, 포괄적인 테스트를 추가합니다.

Changes

혼합 / 파일	요약
Tauri 빌드 및 역량 구성 apps/desktop/src-tauri/build.rs, apps/desktop/src-tauri/tauri.conf.json, apps/desktop/src-tauri/capabilities/main.json, apps/desktop/src-tauri/permissions/autogenerated/*	Tauri 빌드 스크립트를 try_build로 업데이트하여 start_analysis_job, get_analysis_job_status 명령 및 권한을 등록합니다. 호출 가능한 명령을 명시적으로 선언하는 역량 기술자와 권한 TOML 파일을 추가합니다.
Rust 백엔드 오케스트레이션 로직 apps/desktop/src-tauri/src/main.rs, apps/desktop/src-tauri/Cargo.toml	포괄적인 job 큐 시스템(AppState, MAX_IN_FLIGHT_JOBS 제한), 분석 요청/상태 데이터 모델(AnalysisJobRequest, AnalysisJobStatus), Python 서브프로세스 실행(run_analysis_engine), 타임스탬프 유틸리티 및 경로 해석 로직을 포함한 두 개의 공용 Tauri 명령을 추가합니다.
데스크톱 패키지 의존성 apps/desktop/package.json	@tauri-apps/api@^2.8.0을 추가합니다.
분석 브리지 모듈 apps/desktop/src/lib/analysis.ts	Tauri invoke 호출을 통해 시작 및 상태 폴링을 하는 createDefaultAnalysisRequest(), startAnalysisJob(), getAnalysisJobStatus()을 제공하는 통합 분석 API 계층을 도입합니다. 브라우저 환경의 폴백을 포함합니다.
데스크톱 UI 및 테스트 apps/desktop/src/App.tsx, apps/desktop/src/App.test.tsx	실제 분석 워크플로우로 변경하여 job 상태 추적, 폴링 루프, 결과 렌더링을 추가합니다. App.test.tsx는 tauriInvoke 모킹, 비동기 상태 검증, 오류 처리 시나리오를 포함한 포괄적인 통합 테스트로 변경합니다.
국제화 업데이트 apps/desktop/src/i18n/index.ts, apps/desktop/src/locales/en/common.json, apps/desktop/src/locales/ko/common.json	TranslationKey 타입을 도입하고 분석 UI 상태(Queued, Running, Succeeded, Failed) 및 오류 메시지에 대한 6개의 새로운 translation 키를 추가합니다.
공유 타입 정의 packages/shared-types/src/index.ts, packages/shared-types/test/index.test.ts	분석 job 오케스트레이션(AnalysisJobRequest, AnalysisJobStatus, AnalysisJobError, AnalysisJobState 등)에 대한 TypeScript 타입과 검증 함수(parseAnalysisJobRequest, isAnalysisJobStatus, createDemoAnalysisJobRequest)를 추가합니다. 포괄적인 검증 테스트를 포함합니다.
Python 분석 엔진 API services/analysis-engine/src/bandscope_analysis/api.py, services/analysis-engine/tests/test_api.py	AnalysisJobRequest, AnalysisJobStatus, RehearsalSong 등에 대한 TypedDict 타입, validate_analysis_job_request(), build_demo_rehearsal_song(), run_analysis_job() 함수를 도입합니다. validation 및 demo payload 생성을 위한 테스트를 추가합니다.
Python CLI 엔트포인트 services/analysis-engine/src/bandscope_analysis/cli.py, services/analysis-engine/tests/test_cli.py	stdin에서 JSON job 페이로드를 읽고, 검증하고, 분석을 실행하고, 결과를 stdout에 쓰는 CLI를 추가합니다. 성공/실패 경로, malformed JSON, 유효하지 않은 jobId를 다루는 테스트를 포함합니다.
문서 및 워크플로우 ARCHITECTURE.md, docs/architecture/overview.md, docs/security/app-security.md, docs/plans/2026-03-12-issue-32-*.md, .github/workflows/sbom.yml	로컬 분석 오케스트레이션이 Tauri IPC 및 Python subprocess를 사용함을 설명하는 아키텍처 노트를 업데이트합니다. Issue 32 설계 및 구현 계획 문서를 추가합니다. SBOM 생성을 anchore/sbom-action에서 직접 Syft 호출로 변경합니다.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant Desktop as Desktop UI
    participant Tauri as Tauri/Rust
    participant Python as Python CLI
    participant State as In-Memory<br/>Job State

    User->>Desktop: Click Start Analysis
    activate Desktop
    Desktop->>Tauri: invoke start_analysis_job(request)
    activate Tauri
    Tauri->>Tauri: validate request payload
    Tauri->>Tauri: assign job_id
    Tauri->>State: store status (Queued)
    Tauri->>Tauri: spawn worker thread
    Tauri->>Desktop: return {jobId, state: "queued"}
    deactivate Tauri
    deactivate Desktop

    Desktop->>Desktop: polling loop
    activate Desktop
    loop Poll Status (while Queued/Running)
        Desktop->>Tauri: invoke get_analysis_job_status(jobId)
        activate Tauri
        Tauri->>State: fetch current status
        Tauri->>Desktop: return AnalysisJobStatus
        deactivate Tauri
        Desktop->>Desktop: check state
    end

    par Parallel: Worker Thread Processing
        activate Tauri
        Tauri->>Tauri: run_analysis_engine(job_id, payload)
        Tauri->>Python: spawn subprocess, stdin: payload
        activate Python
        Python->>Python: validate job payload
        Python->>Python: run_analysis_job(jobId, request)
        Python->>Python: build demo result
        Python->>Python: JSON response to stdout
        Python-->>Tauri: stdout: {state: "succeeded", result: {...}}
        deactivate Python
        Tauri->>State: store status (Succeeded/Failed)
        deactivate Tauri
    end

    Tauri->>Desktop: status updated (Succeeded)
    Desktop->>Desktop: render result
    deactivate Desktop

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• chore: bootstrap setup baseline #1: 기존 SBOM GitHub 워크플로우 및 데스크톱/오케스트레이션 파일들을 수정하므로 파일/함수 수준에서 직접 관련이 있습니다.
• feat: add shared rehearsal contract baseline #37: 공유 타입 재정의(shared-types/src/index.ts)와 데스크톱 앱 UI/테스트(App.tsx, App.test.tsx, locale 키)를 모두 수정하므로 동일한 코드 수준의 엔티티에 영향을 미칩니다.
• chore: promote bootstrap baseline to main #5: .github/workflows/sbom.yml을 anchore/sbom-action에서 직접 Syft 호출로 변경하여 이전 PR #5에서 도입한 동일한 SBOM 워크플로우를 수정합니다.

Poem

🐰 분석의 길을 열며 뛰어가,
Tauri와 Python이 손을 잡고,
job을 큐에 담아 실행하네!
상태를 묻고 결과를 얻고,
타이핑된 계약이 모두를 지키누. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 변경 세트의 주요 내용을 명확하게 요약하고 있습니다. '로컬 분석 오케스트레이션 추가'는 PR의 핵심 목표를 정확히 설명합니다.
Description check	✅ Passed	설명이 변경 세트와 관련이 있으며, 공유 타입, 데스크톱 셸, Tauri 명령, Python 엔진 CLI를 포함한 구체적인 구현 세부 사항을 제공합니다.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/issue-32-analysis-orchestration-v4

---

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

[seonghobae]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

Superseded by #51 to clear the remaining stale CodeRabbit pending state after all required checks passed and no actionable review remained.