04072dc94b
All checks were successful
Gitea Actions Demo / Explore-Gitea-Actions (push) Successful in 1m6s
101 lines
2.3 KiB
Markdown
101 lines
2.3 KiB
Markdown
# Subtitle Jobs Async Design
|
|
|
|
## Goal
|
|
|
|
Replace the synchronous `/api/generate-subtitles` request with an async job flow so long-running subtitle generation can survive gateway timeouts and provide user-visible progress.
|
|
|
|
## Chosen Approach
|
|
|
|
Use a single-process in-memory job store on the backend and 5-second polling on the frontend.
|
|
|
|
The backend will:
|
|
|
|
- accept subtitle generation requests
|
|
- create a job with `queued` status
|
|
- return `202 Accepted` immediately with `jobId`
|
|
- continue subtitle generation in the background
|
|
- expose `GET /api/generate-subtitles/:jobId` for status and result lookup
|
|
|
|
The frontend will:
|
|
|
|
- submit the job
|
|
- poll every 5 seconds
|
|
- map backend `stage` values to a staged progress bar
|
|
- stop polling on `succeeded`, `failed`, or timeout
|
|
|
|
## Job Model
|
|
|
|
Each subtitle job stores:
|
|
|
|
- `id`
|
|
- `requestId`
|
|
- `status`
|
|
- `stage`
|
|
- `progress`
|
|
- `message`
|
|
- `createdAt`
|
|
- `updatedAt`
|
|
- `provider`
|
|
- `targetLanguage`
|
|
- `fileId`
|
|
- `filePath`
|
|
- `error`
|
|
- `result`
|
|
|
|
Statuses:
|
|
|
|
- `queued`
|
|
- `running`
|
|
- `succeeded`
|
|
- `failed`
|
|
|
|
Stages:
|
|
|
|
- `queued`
|
|
- `upload_received`
|
|
- `preparing`
|
|
- `calling_provider`
|
|
- `processing_result`
|
|
- `succeeded`
|
|
- `failed`
|
|
|
|
Jobs expire from memory after 1 hour.
|
|
|
|
## Progress Strategy
|
|
|
|
Progress is stage-based, not byte-accurate. This avoids fake precision while still keeping the user informed.
|
|
|
|
Suggested mapping:
|
|
|
|
- `queued`: 5
|
|
- `upload_received`: 15
|
|
- `preparing`: 30
|
|
- `calling_provider`: 70
|
|
- `processing_result`: 90
|
|
- `succeeded`: 100
|
|
- `failed`: keep last reported progress
|
|
|
|
## Backend Flow
|
|
|
|
1. Parse request and validate source input.
|
|
2. Create a job.
|
|
3. Return `202` with the new job state.
|
|
4. Run subtitle generation in a detached async task.
|
|
5. Update the job on each pipeline stage.
|
|
6. Store final result or error.
|
|
7. Clean up uploaded temp files after background completion.
|
|
|
|
## Frontend Flow
|
|
|
|
1. Doubao still uploads to Ark Files first and waits for file readiness.
|
|
2. Frontend posts to `/api/generate-subtitles`.
|
|
3. Frontend polls `/api/generate-subtitles/:jobId` every 5 seconds.
|
|
4. Progress UI updates from backend job status and stage.
|
|
5. Final result is normalized into `SubtitlePipelineResult`.
|
|
|
|
## Risks
|
|
|
|
- In-memory jobs are lost on restart.
|
|
- Single-instance memory state will not scale across multiple backend replicas.
|
|
- Upload time can still be slow, but the long model invocation is no longer tied to one HTTP response.
|