feat: persist voice samples to disk, generate VTT, cleanup after analysis

internal/domain/entity/voice_sample.go

@@ -0,0 +1,17 @@
+package entity
+
+import "time"
+
+// VoiceSample tracks all files produced during voice message processing.
+// Files are kept on disk until Cleanup() is called after successful analysis.
+type VoiceSample struct {
+	ID         string
+	UserID     int64
+	ChatID     int64
+	FileIDTg   string // original Telegram file ID
+	OGGPath    string // downloaded raw audio
+	WAVPath    string // ffmpeg-converted audio
+	VTTPath    string // WebVTT subtitle file generated by Whisper
+	Transcript string
+	CreatedAt  time.Time
+}

internal/domain/port/speech_transcriber.go

@@ -2,6 +2,12 @@ package port
 
 import "context"
 
-type SpeechTranscriber interface {
-	Transcribe(ctx context.Context, audioData []byte, mimeType string) (string, error)
+// TranscriptionResult holds both the plain-text transcript and the WebVTT subtitle content.
+type TranscriptionResult struct {
+	Text string
+	VTT  string // WebVTT format, empty if not available
+}
+
+type SpeechTranscriber interface {
+	Transcribe(ctx context.Context, audioData []byte, mimeType string) (TranscriptionResult, error)
 }

internal/domain/port/voice_file_store.go

@@ -0,0 +1,12 @@
+package port
+
+import "context"
+
+// VoiceFileStore manages lifecycle of voice sample files on disk.
+// Files are persisted until Cleanup is called after successful analysis.
+type VoiceFileStore interface {
+	SaveRaw(ctx context.Context, sampleID string, data []byte) (path string, err error)
+	SaveConverted(ctx context.Context, sampleID string, data []byte) (path string, err error)
+	SaveVTT(ctx context.Context, sampleID string, content string) (path string, err error)
+	Cleanup(ctx context.Context, sampleID string) error
+}