AI/teaching-feedback-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add local voice transcription pipeline

Browse Source
This commit is contained in:
shay7sev
2026-07-20 10:49:41 +08:00
parent f1e5fd8793
commit 8a88706ff9
16 changed files with 2389 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
src/config.rs
View File

@@ -1,4 +1,33 @@
use std::{env, net::IpAddr};
use std::{env, net::IpAddr, path::PathBuf};
#[derive(Debug, Clone)]
pub enum SpeechProviderConfig {
Local { api_url: String },
Tencent(TencentSpeechConfig),
}
#[derive(Debug, Clone)]
pub struct TencentSpeechConfig {
pub app_id: u64,
pub secret_id: String,
pub secret_key: String,
pub engine_type: String,
}
#[derive(Debug, Clone)]
pub struct SpeechConfig {
pub provider: SpeechProviderConfig,
pub request_timeout_seconds: u64,
pub worker_concurrency: usize,
pub job_lease_seconds: i64,
}
#[derive(Debug, Clone)]
pub struct SummaryConfig {
pub api_url: String,
pub api_key: Option<String>,
pub model: String,
}
#[derive(Debug, Clone)]
pub struct Config {
@@ -7,6 +36,9 @@ pub struct Config {
pub database_url: Option<String>,
pub database_max_connections: u32,
pub cors_allowed_origin: Option<String>,
pub audio_storage_dir: PathBuf,
pub speech: Option<SpeechConfig>,
pub summary: Option<SummaryConfig>,
}
impl Config {
@@ -24,6 +56,9 @@ impl Config {
.parse()
.map_err(|_| "DATABASE_MAX_CONNECTIONS must be a valid u32 value".to_owned())?;
let speech = speech_config()?;
let summary = summary_config()?;
Ok(Self {
host,
port,
@@ -34,6 +69,99 @@ impl Config {
cors_allowed_origin: env::var("CORS_ALLOWED_ORIGIN")
.ok()
.filter(|value| !value.trim().is_empty()),
audio_storage_dir: env::var("AUDIO_STORAGE_DIR")
.map(PathBuf::from)
.unwrap_or_else(|_| PathBuf::from("./data/audio")),
speech,
summary,
})
}
}
fn speech_config() -> Result<Option<SpeechConfig>, String> {
let provider = optional_env("ASR_PROVIDER").unwrap_or_else(|| "local".to_owned());
if matches!(provider.as_str(), "disabled" | "none") {
return Ok(None);
}
let provider = match provider.as_str() {
"local" | "funasr" => SpeechProviderConfig::Local {
api_url: optional_env("LOCAL_ASR_URL")
.unwrap_or_else(|| "http://127.0.0.1:10095".to_owned())
.trim_end_matches('/')
.to_owned(),
},
"tencent" => {
let app_id = required_env("TENCENT_CLOUD_ASR_APP_ID")?
.parse()
.map_err(|_| "TENCENT_CLOUD_ASR_APP_ID must be an integer".to_owned())?;
SpeechProviderConfig::Tencent(TencentSpeechConfig {
app_id,
secret_id: required_env("TENCENT_CLOUD_ASR_SECRET_ID")?,
secret_key: required_env("TENCENT_CLOUD_ASR_SECRET_KEY")?,
engine_type: optional_env("TENCENT_CLOUD_ASR_ENGINE_TYPE")
.unwrap_or_else(|| "16k_zh".to_owned()),
})
}
_ => {
return Err(
"ASR_PROVIDER must be local, funasr, tencent, disabled, or none".to_owned(),
);
}
};
let request_timeout_seconds = parse_env("ASR_REQUEST_TIMEOUT_SECONDS", 1_800_u64)?;
let worker_concurrency = parse_env("ASR_WORKER_CONCURRENCY", 1_usize)?;
let job_lease_seconds = parse_env("ASR_JOB_LEASE_SECONDS", 3_600_i64)?;
if request_timeout_seconds == 0 {
return Err("ASR_REQUEST_TIMEOUT_SECONDS must be greater than 0".to_owned());
}
if worker_concurrency == 0 {
return Err("ASR_WORKER_CONCURRENCY must be greater than 0".to_owned());
}
if job_lease_seconds <= 0 {
return Err("ASR_JOB_LEASE_SECONDS must be greater than 0".to_owned());
}
Ok(Some(SpeechConfig {
provider,
request_timeout_seconds,
worker_concurrency,
job_lease_seconds,
}))
}
fn summary_config() -> Result<Option<SummaryConfig>, String> {
let Some(api_url) = optional_env("FEEDBACK_SUMMARY_API_URL") else {
return Ok(None);
};
let model = optional_env("FEEDBACK_SUMMARY_MODEL").ok_or_else(|| {
"FEEDBACK_SUMMARY_MODEL is required when summary API is configured".to_owned()
})?;
Ok(Some(SummaryConfig {
api_url: api_url.trim_end_matches('/').to_owned(),
api_key: optional_env("FEEDBACK_SUMMARY_API_KEY"),
model,
}))
}
fn optional_env(name: &str) -> Option<String> {
env::var(name)
.ok()
.map(|value| value.trim().to_owned())
.filter(|value| !value.is_empty())
}
fn required_env(name: &str) -> Result<String, String> {
optional_env(name).ok_or_else(|| format!("{name} is required for the selected ASR provider"))
}
fn parse_env<T>(name: &str, default: T) -> Result<T, String>
where
T: std::str::FromStr,
{
optional_env(name).map_or_else(
|| Ok(default),
|value| value.parse().map_err(|_| format!("{name} is invalid")),
)
}

3
src/error.rs
View File

@@ -16,6 +16,8 @@ pub enum ApiError {
NotFound,
#[error("database has not been configured")]
DatabaseUnavailable,
#[error("{0}")]
ServiceUnavailable(String),
#[error("internal server error")]
Internal,
}
@@ -75,6 +77,7 @@ impl IntoResponse for ApiError {
StatusCode::SERVICE_UNAVAILABLE,
"database has not been configured".to_owned(),
),
Self::ServiceUnavailable(message) => (StatusCode::SERVICE_UNAVAILABLE, message),
Self::Internal => (
StatusCode::INTERNAL_SERVER_ERROR,
"internal server error".to_owned(),

26
src/main.rs
View File

@@ -1,10 +1,14 @@
mod config;
mod error;
mod recording_routes;
mod routes;
mod speech;
mod summary;
mod transcription_worker;
use std::sync::Arc;
use std::{path::PathBuf, sync::Arc};
use axum::{Json, Router, http::HeaderValue, routing::get};
use axum::{Json, Router, extract::DefaultBodyLimit, http::HeaderValue, routing::get};
use config::Config;
use sqlx::{PgPool, postgres::PgPoolOptions};
use tower_http::{cors::CorsLayer, trace::TraceLayer};
@@ -14,6 +18,9 @@ use utoipa_scalar::{Scalar, Servable};
#[derive(Clone)]
pub struct AppState {
pub pool: Option<PgPool>,
pub audio_storage_dir: PathBuf,
pub speech: speech::SpeechService,
pub summary: summary::SummaryService,
}
#[tokio::main]
@@ -25,7 +32,19 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = Config::from_env().map_err(std::io::Error::other)?;
let pool = connect_database(&config).await?;
let app = build_app(AppState { pool }, config.cors_allowed_origin.as_deref())?;
let speech = speech::SpeechService::new(config.speech.clone());
let state = AppState {
pool,
audio_storage_dir: config.audio_storage_dir.clone(),
speech: speech.clone(),
summary: summary::SummaryService::new(config.summary.clone()),
};
if let Some(pool) = state.pool.clone()
&& speech.configured()
{
transcription_worker::spawn(pool, speech);
}
let app = build_app(state, config.cors_allowed_origin.as_deref())?;
let address = std::net::SocketAddr::from((config.host, config.port));
let listener = tokio::net::TcpListener::bind(address).await?;
@@ -49,6 +68,7 @@ pub fn build_app(state: AppState, cors_allowed_origin: Option<&str>) -> Result<R
)
.merge(Scalar::with_url("/scalar", openapi))
.with_state(Arc::new(state))
.layer(DefaultBodyLimit::max(20 * 1024 * 1024))
.layer(TraceLayer::new_for_http());
if let Some(origin) = cors_allowed_origin {

957
src/recording_routes.rs Normal file
View File

@@ -0,0 +1,957 @@
use std::{collections::HashMap, sync::Arc};
use axum::{
Json,
extract::{Multipart, Path, Query, State},
http::HeaderMap,
};
use chrono::{DateTime, NaiveDate, Utc};
use serde::{Deserialize, Serialize};
use sqlx::{FromRow, PgPool};
use utoipa::ToSchema;
use utoipa_axum::{router::OpenApiRouter, routes};
use uuid::Uuid;
use crate::{
AppState,
error::{ApiError, CommonApiErrors, ErrorBody},
};
type SharedState = Arc<AppState>;
const MAX_AUDIO_UPLOAD_BYTES: usize = 15 * 1024 * 1024;
const MAX_SEGMENT_DURATION_MS: i32 = 600_000;
const SHORT_RECORDING_DURATION_MS: i32 = 60_000;
const SHORT_TRANSCRIPT_CHARS: usize = 600;
pub fn router() -> OpenApiRouter<SharedState> {
OpenApiRouter::new()
.routes(routes!(get_active_feedback_session))
.routes(routes!(ensure_feedback_session))
.routes(routes!(update_feedback_session))
.routes(routes!(create_lesson_session))
.routes(routes!(upload_audio_segment))
.routes(routes!(finish_lesson_session))
.routes(routes!(mark_lesson_applied))
.routes(routes!(retry_audio_segment))
.routes(routes!(generate_feedback_content))
}
#[derive(Debug, Deserialize)]
struct ActiveSessionQuery {
profile_id: Option<Uuid>,
}
#[derive(Debug, Deserialize, ToSchema)]
#[schema(example = json!({
"profile_id": "11111111-1111-4111-8111-111111111111",
"feedback_date": "2026-07-16",
"content": ""
}))]
struct FeedbackSessionInput {
profile_id: Option<Uuid>,
feedback_date: NaiveDate,
#[serde(default)]
content: String,
}
#[derive(Debug, Deserialize, ToSchema)]
struct FeedbackSessionUpdateInput {
feedback_date: NaiveDate,
content: String,
}
#[derive(Debug, FromRow)]
struct FeedbackSessionRow {
id: Uuid,
profile_id: Option<Uuid>,
feedback_date: NaiveDate,
content: String,
status: String,
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
}
#[derive(Debug, FromRow)]
struct LessonRow {
id: Uuid,
sequence: i32,
status: String,
duration_ms: i32,
applied_directly: bool,
included_in_generation: bool,
started_at: DateTime<Utc>,
ended_at: Option<DateTime<Utc>>,
}
#[derive(Debug, FromRow)]
struct SegmentRow {
id: Uuid,
lesson_session_id: Uuid,
sequence: i32,
duration_ms: i32,
status: String,
error_message: Option<String>,
}
#[derive(Debug, Serialize, ToSchema)]
struct FeedbackSessionResponse {
id: Uuid,
profile_id: Option<Uuid>,
feedback_date: NaiveDate,
content: String,
status: String,
lesson_count: usize,
total_duration_ms: i64,
processing_segment_count: usize,
failed_segment_count: usize,
needs_generation: bool,
lessons: Vec<LessonSummaryResponse>,
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
}
#[derive(Debug, Serialize, ToSchema)]
struct LessonSummaryResponse {
id: Uuid,
sequence: i32,
status: String,
duration_ms: i32,
applied_directly: bool,
included_in_generation: bool,
segments: Vec<AudioSegmentResponse>,
started_at: DateTime<Utc>,
ended_at: Option<DateTime<Utc>>,
}
#[derive(Debug, Serialize, ToSchema)]
struct AudioSegmentResponse {
id: Uuid,
sequence: i32,
duration_ms: i32,
status: String,
error_message: Option<String>,
}
#[derive(Debug, Serialize, ToSchema)]
struct LessonCreatedResponse {
id: Uuid,
sequence: i32,
status: String,
started_at: DateTime<Utc>,
}
#[derive(Debug, Serialize, ToSchema)]
struct FinishedLessonResponse {
id: Uuid,
status: String,
duration_ms: i32,
transcript: String,
can_apply_directly: bool,
}
#[derive(Debug, Deserialize, ToSchema)]
struct GenerateFeedbackInput {
#[schema(example = "学生本周构图更加稳定。")]
existing_content: String,
}
#[derive(Debug, Deserialize, ToSchema)]
struct MarkLessonAppliedInput {
content: String,
}
#[derive(Debug, Serialize, ToSchema)]
struct GenerateFeedbackResponse {
content: String,
method: String,
}
#[derive(Debug, ToSchema)]
#[allow(dead_code)]
struct AudioSegmentUpload {
sequence: i32,
duration_ms: i32,
audio_format: String,
audio: String,
}
#[utoipa::path(
get,
path = "/api/v1/feedback-sessions/active",
tag = "语音反馈",
summary = "读取进行中的反馈批次",
description = "读取当前用户指定学生下尚未保存的反馈批次；profile_id 留空时读取不关联学生的批次。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("profile_id" = Option<Uuid>, Query, description = "学生档案 ID；留空表示不关联学生")
),
responses(
(status = 200, description = "进行中的反馈批次；不存在时返回 null", body = Option<FeedbackSessionResponse>),
CommonApiErrors
)
)]
async fn get_active_feedback_session(
State(state): State<SharedState>,
headers: HeaderMap,
Query(query): Query<ActiveSessionQuery>,
) -> Result<Json<Option<FeedbackSessionResponse>>, ApiError> {
let owner_id = current_user(&headers)?;
let session = sqlx::query_as::<_, FeedbackSessionRow>(
"SELECT id, profile_id, feedback_date, content, status, created_at, updated_at \
FROM feedback_sessions \
WHERE owner_id = $1 AND profile_id IS NOT DISTINCT FROM $2 AND status = 'active' \
ORDER BY updated_at DESC LIMIT 1",
)
.bind(owner_id)
.bind(query.profile_id)
.fetch_optional(pool(&state)?)
.await?;
match session {
Some(session) => Ok(Json(Some(
load_session_response(pool(&state)?, session).await?,
))),
None => Ok(Json(None)),
}
}
#[utoipa::path(
post,
path = "/api/v1/feedback-sessions",
tag = "语音反馈",
summary = "创建或恢复反馈批次",
description = "为学生创建一个反馈批次；已有未保存批次时直接恢复，并同步最新反馈日期。",
params(("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0"))),
request_body(content = FeedbackSessionInput, content_type = "application/json"),
responses(
(status = 200, description = "创建或恢复后的反馈批次", body = FeedbackSessionResponse),
(status = 404, description = "学生档案不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn ensure_feedback_session(
State(state): State<SharedState>,
headers: HeaderMap,
Json(input): Json<FeedbackSessionInput>,
) -> Result<Json<FeedbackSessionResponse>, ApiError> {
let owner_id = current_user(&headers)?;
let pool = pool(&state)?;
validate_draft_content(&input.content)?;
if let Some(profile_id) = input.profile_id {
assert_profile_owner(pool, owner_id, profile_id).await?;
}
let existing = sqlx::query_as::<_, FeedbackSessionRow>(
"UPDATE feedback_sessions SET feedback_date = $3, content = $4, updated_at = now() \
WHERE id = ( \
SELECT id FROM feedback_sessions \
WHERE owner_id = $1 AND profile_id IS NOT DISTINCT FROM $2 AND status = 'active' \
ORDER BY updated_at DESC LIMIT 1 \
) \
RETURNING id, profile_id, feedback_date, content, status, created_at, updated_at",
)
.bind(owner_id)
.bind(input.profile_id)
.bind(input.feedback_date)
.bind(&input.content)
.fetch_optional(pool)
.await?;
let session =
match existing {
Some(session) => session,
None => sqlx::query_as::<_, FeedbackSessionRow>(
"INSERT INTO feedback_sessions (id, owner_id, profile_id, feedback_date, content) \
VALUES ($1, $2, $3, $4, $5) \
RETURNING id, profile_id, feedback_date, content, status, created_at, updated_at",
)
.bind(Uuid::new_v4())
.bind(owner_id)
.bind(input.profile_id)
.bind(input.feedback_date)
.bind(&input.content)
.fetch_one(pool)
.await?,
};
Ok(Json(load_session_response(pool, session).await?))
}
#[utoipa::path(
put,
path = "/api/v1/feedback-sessions/{session_id}",
tag = "语音反馈",
summary = "自动保存反馈草稿",
description = "在用户编辑反馈正文或日期时自动保存进行中的反馈批次。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("session_id" = Uuid, Path, description = "反馈批次 ID")
),
request_body(content = FeedbackSessionUpdateInput, content_type = "application/json"),
responses(
(status = 200, description = "更新后的反馈批次", body = FeedbackSessionResponse),
(status = 404, description = "反馈批次不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn update_feedback_session(
State(state): State<SharedState>,
headers: HeaderMap,
Path(session_id): Path<Uuid>,
Json(input): Json<FeedbackSessionUpdateInput>,
) -> Result<Json<FeedbackSessionResponse>, ApiError> {
let owner_id = current_user(&headers)?;
validate_draft_content(&input.content)?;
let session = sqlx::query_as::<_, FeedbackSessionRow>(
"UPDATE feedback_sessions SET feedback_date = $3, content = $4, updated_at = now() \
WHERE id = $1 AND owner_id = $2 AND status = 'active' \
RETURNING id, profile_id, feedback_date, content, status, created_at, updated_at",
)
.bind(session_id)
.bind(owner_id)
.bind(input.feedback_date)
.bind(&input.content)
.fetch_optional(pool(&state)?)
.await?
.ok_or(ApiError::NotFound)?;
Ok(Json(load_session_response(pool(&state)?, session).await?))
}
#[utoipa::path(
post,
path = "/api/v1/feedback-sessions/{session_id}/lessons",
tag = "语音反馈",
summary = "开始一节课堂录音",
description = "在反馈批次中自动创建下一节课堂录音。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("session_id" = Uuid, Path, description = "反馈批次 ID")
),
responses(
(status = 201, description = "课堂录音已创建", body = LessonCreatedResponse),
(status = 404, description = "反馈批次不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn create_lesson_session(
State(state): State<SharedState>,
headers: HeaderMap,
Path(session_id): Path<Uuid>,
) -> Result<(axum::http::StatusCode, Json<LessonCreatedResponse>), ApiError> {
let owner_id = current_user(&headers)?;
assert_session_owner(pool(&state)?, owner_id, session_id).await?;
sqlx::query(
"DELETE FROM lesson_sessions \
WHERE feedback_session_id = $1 AND status IN ('recording', 'processing')",
)
.bind(session_id)
.execute(pool(&state)?)
.await?;
let id = Uuid::new_v4();
let lesson = sqlx::query_as::<_, (Uuid, i32, String, DateTime<Utc>)>(
"INSERT INTO lesson_sessions (id, feedback_session_id, sequence) \
SELECT $1, $2, COALESCE(MAX(sequence), 0) + 1 \
FROM lesson_sessions WHERE feedback_session_id = $2 \
RETURNING id, sequence, status, started_at",
)
.bind(id)
.bind(session_id)
.fetch_one(pool(&state)?)
.await?;
touch_session(pool(&state)?, session_id).await?;
Ok((
axum::http::StatusCode::CREATED,
Json(LessonCreatedResponse {
id: lesson.0,
sequence: lesson.1,
status: lesson.2,
started_at: lesson.3,
}),
))
}
#[utoipa::path(
post,
path = "/api/v1/feedback-lessons/{lesson_id}/segments",
tag = "语音反馈",
summary = "上传并转录录音片段",
description = "上传单个录音片段并加入后端转录队列。接口保存音频后立即返回，页面通过反馈批次状态无感获取转录结果。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("lesson_id" = Uuid, Path, description = "课堂录音 ID")
),
request_body(content = AudioSegmentUpload, content_type = "multipart/form-data"),
responses(
(status = 201, description = "片段已保存并进入转录队列", body = AudioSegmentResponse),
(status = 404, description = "课堂录音不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn upload_audio_segment(
State(state): State<SharedState>,
headers: HeaderMap,
Path(lesson_id): Path<Uuid>,
mut multipart: Multipart,
) -> Result<(axum::http::StatusCode, Json<AudioSegmentResponse>), ApiError> {
let owner_id = current_user(&headers)?;
let session_id = assert_lesson_owner(pool(&state)?, owner_id, lesson_id).await?;
let mut sequence = None;
let mut duration_ms = None;
let mut audio_format = None;
let mut audio = None;
while let Some(field) = multipart
.next_field()
.await
.map_err(|error| ApiError::BadRequest(format!("invalid multipart body: {error}")))?
{
let name = field.name().unwrap_or_default().to_owned();
match name.as_str() {
"sequence" => sequence = Some(parse_multipart_i32(field, "sequence").await?),
"duration_ms" => duration_ms = Some(parse_multipart_i32(field, "duration_ms").await?),
"audio_format" => {
audio_format = Some(
field
.text()
.await
.map_err(|_| ApiError::BadRequest("audio_format is invalid".to_owned()))?,
)
}
"audio" => {
let bytes = field
.bytes()
.await
.map_err(|_| ApiError::BadRequest("audio file is invalid".to_owned()))?;
if bytes.len() > MAX_AUDIO_UPLOAD_BYTES {
return Err(ApiError::BadRequest("audio file exceeds 15 MB".to_owned()));
}
audio = Some(bytes.to_vec());
}
_ => {}
}
}
let sequence = sequence
.filter(|value| *value > 0)
.ok_or_else(|| ApiError::BadRequest("sequence must be a positive integer".to_owned()))?;
let duration_ms = duration_ms
.filter(|value| (1..=MAX_SEGMENT_DURATION_MS).contains(value))
.ok_or_else(|| {
ApiError::BadRequest("duration_ms must be between 1 and 600000".to_owned())
})?;
let audio_format = audio_format
.map(|value| value.trim().to_ascii_lowercase())
.filter(|value| matches!(value.as_str(), "mp3" | "aac" | "wav" | "m4a" | "amr"))
.ok_or_else(|| ApiError::BadRequest("unsupported audio_format".to_owned()))?;
let audio = audio
.filter(|bytes| !bytes.is_empty())
.ok_or_else(|| ApiError::BadRequest("audio file cannot be empty".to_owned()))?;
let file_id = Uuid::new_v4();
let directory = state
.audio_storage_dir
.join(owner_id.to_string())
.join(lesson_id.to_string());
tokio::fs::create_dir_all(&directory)
.await
.map_err(internal_io_error)?;
let audio_path = directory.join(format!("{file_id}.{audio_format}"));
tokio::fs::write(&audio_path, &audio)
.await
.map_err(internal_io_error)?;
let segment_id = sqlx::query_scalar::<_, Uuid>(
"INSERT INTO audio_segments \
(id, lesson_session_id, sequence, duration_ms, audio_format, audio_path, status) \
VALUES ($1, $2, $3, $4, $5, $6, 'processing') \
ON CONFLICT (lesson_session_id, sequence) DO UPDATE SET \
duration_ms = EXCLUDED.duration_ms, audio_format = EXCLUDED.audio_format, \
audio_path = EXCLUDED.audio_path, status = 'processing', transcript = NULL, \
error_message = NULL, provider_request_id = NULL, processing_started_at = NULL, \
updated_at = now() \
RETURNING id",
)
.bind(file_id)
.bind(lesson_id)
.bind(sequence)
.bind(duration_ms)
.bind(&audio_format)
.bind(audio_path.to_string_lossy().as_ref())
.fetch_one(pool(&state)?)
.await?;
sqlx::query(
"UPDATE lesson_sessions SET status = 'processing', updated_at = now() WHERE id = $1",
)
.bind(lesson_id)
.execute(pool(&state)?)
.await?;
touch_session(pool(&state)?, session_id).await?;
Ok((
axum::http::StatusCode::CREATED,
Json(AudioSegmentResponse {
id: segment_id,
sequence,
duration_ms,
status: "processing".to_owned(),
error_message: None,
}),
))
}
#[utoipa::path(
post,
path = "/api/v1/feedback-lessons/{lesson_id}/finish",
tag = "语音反馈",
summary = "结束一节课堂录音",
description = "汇总该节课的片段状态和转录文本；短录音会标记为可直接加入反馈。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("lesson_id" = Uuid, Path, description = "课堂录音 ID")
),
responses(
(status = 200, description = "课堂录音汇总结果", body = FinishedLessonResponse),
(status = 404, description = "课堂录音不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn finish_lesson_session(
State(state): State<SharedState>,
headers: HeaderMap,
Path(lesson_id): Path<Uuid>,
) -> Result<Json<FinishedLessonResponse>, ApiError> {
let owner_id = current_user(&headers)?;
let session_id = assert_lesson_owner(pool(&state)?, owner_id, lesson_id).await?;
let segments = sqlx::query_as::<_, (String, i32, Option<String>)>(
"SELECT status, duration_ms, transcript FROM audio_segments \
WHERE lesson_session_id = $1 ORDER BY sequence",
)
.bind(lesson_id)
.fetch_all(pool(&state)?)
.await?;
let duration_ms = segments.iter().map(|segment| segment.1).sum::<i32>();
let transcript = segments
.iter()
.filter_map(|segment| segment.2.as_deref())
.collect::<Vec<_>>()
.join("\n");
let status = if segments.is_empty() || segments.iter().any(|segment| segment.0 == "failed") {
"failed"
} else if segments.iter().any(|segment| segment.0 == "processing") {
"processing"
} else {
"ready"
};
sqlx::query(
"UPDATE lesson_sessions SET status = $2, duration_ms = $3, ended_at = now(), updated_at = now() \
WHERE id = $1",
)
.bind(lesson_id)
.bind(status)
.bind(duration_ms)
.execute(pool(&state)?)
.await?;
touch_session(pool(&state)?, session_id).await?;
Ok(Json(FinishedLessonResponse {
id: lesson_id,
status: status.to_owned(),
duration_ms,
can_apply_directly: status == "ready"
&& duration_ms <= SHORT_RECORDING_DURATION_MS
&& transcript.chars().count() <= SHORT_TRANSCRIPT_CHARS,
transcript,
}))
}
#[utoipa::path(
post,
path = "/api/v1/feedback-lessons/{lesson_id}/mark-applied",
tag = "语音反馈",
summary = "标记短录音已加入反馈",
description = "短录音文字直接加入反馈内容后，标记该节课无需再次汇总。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("lesson_id" = Uuid, Path, description = "课堂录音 ID")
),
request_body(content = MarkLessonAppliedInput, content_type = "application/json"),
responses(
(status = 204, description = "已标记"),
(status = 404, description = "课堂录音不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn mark_lesson_applied(
State(state): State<SharedState>,
headers: HeaderMap,
Path(lesson_id): Path<Uuid>,
Json(input): Json<MarkLessonAppliedInput>,
) -> Result<axum::http::StatusCode, ApiError> {
let owner_id = current_user(&headers)?;
validate_draft_content(&input.content)?;
let pool = pool(&state)?;
let session_id = assert_lesson_owner(pool, owner_id, lesson_id).await?;
let mut transaction = pool.begin().await?;
let result = sqlx::query(
"UPDATE lesson_sessions SET applied_directly = TRUE, updated_at = now() \
WHERE id = $1 AND status = 'ready'",
)
.bind(lesson_id)
.execute(&mut *transaction)
.await?;
if result.rows_affected() == 0 {
return Err(ApiError::BadRequest("lesson is not ready".to_owned()));
}
sqlx::query("UPDATE feedback_sessions SET content = $2, updated_at = now() WHERE id = $1")
.bind(session_id)
.bind(&input.content)
.execute(&mut *transaction)
.await?;
transaction.commit().await?;
Ok(axum::http::StatusCode::NO_CONTENT)
}
#[utoipa::path(
post,
path = "/api/v1/audio-segments/{segment_id}/retry",
tag = "语音反馈",
summary = "重试失败的录音转录",
description = "将后端保留的失败音频重新加入转录队列，接口立即返回。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("segment_id" = Uuid, Path, description = "录音片段 ID")
),
responses(
(status = 200, description = "片段已重新进入转录队列", body = AudioSegmentResponse),
(status = 404, description = "录音片段不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn retry_audio_segment(
State(state): State<SharedState>,
headers: HeaderMap,
Path(segment_id): Path<Uuid>,
) -> Result<Json<AudioSegmentResponse>, ApiError> {
let owner_id = current_user(&headers)?;
let segment = sqlx::query_as::<_, (i32, i32, String, Uuid)>(
"SELECT s.sequence, s.duration_ms, s.audio_path, l.id \
FROM audio_segments s \
JOIN lesson_sessions l ON l.id = s.lesson_session_id \
JOIN feedback_sessions f ON f.id = l.feedback_session_id \
WHERE s.id = $1 AND f.owner_id = $2 AND f.status = 'active'",
)
.bind(segment_id)
.bind(owner_id)
.fetch_optional(pool(&state)?)
.await?
.ok_or(ApiError::NotFound)?;
tokio::fs::metadata(&segment.2)
.await
.map_err(internal_io_error)?;
sqlx::query(
"UPDATE audio_segments SET status = 'processing', error_message = NULL, \
processing_started_at = NULL, updated_at = now() WHERE id = $1",
)
.bind(segment_id)
.execute(pool(&state)?)
.await?;
sqlx::query(
"UPDATE lesson_sessions SET status = 'processing', updated_at = now() WHERE id = $1",
)
.bind(segment.3)
.execute(pool(&state)?)
.await?;
let session_id = sqlx::query_scalar::<_, Uuid>(
"SELECT feedback_session_id FROM lesson_sessions WHERE id = $1",
)
.bind(segment.3)
.fetch_one(pool(&state)?)
.await?;
touch_session(pool(&state)?, session_id).await?;
Ok(Json(AudioSegmentResponse {
id: segment_id,
sequence: segment.0,
duration_ms: segment.1,
status: "processing".to_owned(),
error_message: None,
}))
}
#[utoipa::path(
post,
path = "/api/v1/feedback-sessions/{session_id}/generate",
tag = "语音反馈",
summary = "生成汇总反馈",
description = "将尚未处理的长录音或多节课堂转录与教师已有内容合并。未配置大模型时使用本地抽取式汇总。",
params(
("X-User-Id" = Uuid, Header, description = "开发阶段用户 ID", example = json!("5a4da7f0-d70c-465f-bcab-124c504aa9f0")),
("session_id" = Uuid, Path, description = "反馈批次 ID")
),
request_body(content = GenerateFeedbackInput, content_type = "application/json"),
responses(
(status = 200, description = "汇总后的反馈正文", body = GenerateFeedbackResponse),
(status = 404, description = "反馈批次不存在或不属于当前用户", body = ErrorBody),
CommonApiErrors
)
)]
async fn generate_feedback_content(
State(state): State<SharedState>,
headers: HeaderMap,
Path(session_id): Path<Uuid>,
Json(input): Json<GenerateFeedbackInput>,
) -> Result<Json<GenerateFeedbackResponse>, ApiError> {
let owner_id = current_user(&headers)?;
validate_draft_content(&input.existing_content)?;
assert_session_owner(pool(&state)?, owner_id, session_id).await?;
let pending_status = sqlx::query_as::<_, (bool, bool)>(
"SELECT \
EXISTS(SELECT 1 FROM audio_segments s JOIN lesson_sessions l ON l.id = s.lesson_session_id \
WHERE l.feedback_session_id = $1 AND s.status = 'processing'), \
EXISTS(SELECT 1 FROM audio_segments s JOIN lesson_sessions l ON l.id = s.lesson_session_id \
WHERE l.feedback_session_id = $1 AND s.status = 'failed')",
)
.bind(session_id)
.fetch_one(pool(&state)?)
.await?;
if pending_status.0 {
return Err(ApiError::BadRequest(
"录音仍在后台转录中，请稍后再生成反馈".to_owned(),
));
}
if pending_status.1 {
return Err(ApiError::BadRequest(
"部分录音转录失败，请重试后再生成反馈".to_owned(),
));
}
let lessons = sqlx::query_as::<_, (Uuid, String)>(
"SELECT l.id, string_agg(s.transcript, E'\\n' ORDER BY s.sequence) \
FROM lesson_sessions l \
JOIN audio_segments s ON s.lesson_session_id = l.id \
WHERE l.feedback_session_id = $1 AND l.status = 'ready' \
AND l.applied_directly = FALSE AND l.included_in_generation = FALSE \
AND s.status = 'ready' AND s.transcript IS NOT NULL \
GROUP BY l.id, l.sequence ORDER BY l.sequence",
)
.bind(session_id)
.fetch_all(pool(&state)?)
.await?;
if lessons.is_empty() {
return Err(ApiError::BadRequest("没有待汇总的录音内容".to_owned()));
}
let transcripts = lessons
.iter()
.map(|lesson| lesson.1.clone())
.collect::<Vec<_>>();
let summary = state
.summary
.summarize(&input.existing_content, &transcripts)
.await
.map_err(ApiError::ServiceUnavailable)?;
let lesson_ids = lessons.iter().map(|lesson| lesson.0).collect::<Vec<_>>();
let pool = pool(&state)?;
let mut transaction = pool.begin().await?;
sqlx::query(
"UPDATE lesson_sessions SET included_in_generation = TRUE, updated_at = now() \
WHERE id = ANY($1)",
)
.bind(&lesson_ids)
.execute(&mut *transaction)
.await?;
sqlx::query("UPDATE feedback_sessions SET content = $2, updated_at = now() WHERE id = $1")
.bind(session_id)
.bind(&summary.content)
.execute(&mut *transaction)
.await?;
transaction.commit().await?;
Ok(Json(GenerateFeedbackResponse {
content: summary.content,
method: summary.method.to_owned(),
}))
}
async fn load_session_response(
pool: &PgPool,
session: FeedbackSessionRow,
) -> Result<FeedbackSessionResponse, ApiError> {
let lessons = sqlx::query_as::<_, LessonRow>(
"SELECT id, sequence, status, duration_ms, applied_directly, included_in_generation, \
started_at, ended_at FROM lesson_sessions \
WHERE feedback_session_id = $1 ORDER BY sequence",
)
.bind(session.id)
.fetch_all(pool)
.await?;
let segments = sqlx::query_as::<_, SegmentRow>(
"SELECT s.id, s.lesson_session_id, s.sequence, s.duration_ms, s.status, s.error_message \
FROM audio_segments s JOIN lesson_sessions l ON l.id = s.lesson_session_id \
WHERE l.feedback_session_id = $1 ORDER BY l.sequence, s.sequence",
)
.bind(session.id)
.fetch_all(pool)
.await?;
let processing_segment_count = segments
.iter()
.filter(|segment| segment.status == "processing")
.count()
+ lessons
.iter()
.filter(|lesson| matches!(lesson.status.as_str(), "recording" | "processing"))
.count();
let failed_segment_count = segments
.iter()
.filter(|segment| segment.status == "failed")
.count();
let total_duration_ms = lessons
.iter()
.map(|lesson| i64::from(lesson.duration_ms))
.sum();
let needs_generation = lessons.iter().any(|lesson| {
lesson.status == "ready" && !lesson.applied_directly && !lesson.included_in_generation
});
let mut segments_by_lesson: HashMap<Uuid, Vec<AudioSegmentResponse>> = HashMap::new();
for segment in segments {
segments_by_lesson
.entry(segment.lesson_session_id)
.or_default()
.push(AudioSegmentResponse {
id: segment.id,
sequence: segment.sequence,
duration_ms: segment.duration_ms,
status: segment.status,
error_message: segment.error_message,
});
}
let lesson_count = lessons.len();
let lesson_responses = lessons
.into_iter()
.map(|lesson| LessonSummaryResponse {
id: lesson.id,
sequence: lesson.sequence,
status: lesson.status,
duration_ms: lesson.duration_ms,
applied_directly: lesson.applied_directly,
included_in_generation: lesson.included_in_generation,
segments: segments_by_lesson.remove(&lesson.id).unwrap_or_default(),
started_at: lesson.started_at,
ended_at: lesson.ended_at,
})
.collect();
Ok(FeedbackSessionResponse {
id: session.id,
profile_id: session.profile_id,
feedback_date: session.feedback_date,
content: session.content,
status: session.status,
lesson_count,
total_duration_ms,
processing_segment_count,
failed_segment_count,
needs_generation,
lessons: lesson_responses,
created_at: session.created_at,
updated_at: session.updated_at,
})
}
async fn parse_multipart_i32(
field: axum::extract::multipart::Field<'_>,
name: &str,
) -> Result<i32, ApiError> {
field
.text()
.await
.map_err(|_| ApiError::BadRequest(format!("{name} is invalid")))?
.parse()
.map_err(|_| ApiError::BadRequest(format!("{name} must be an integer")))
}
fn current_user(headers: &HeaderMap) -> Result<Uuid, ApiError> {
let value = headers
.get("x-user-id")
.and_then(|header| header.to_str().ok())
.ok_or(ApiError::Unauthorized)?;
Uuid::parse_str(value).map_err(|_| ApiError::BadRequest("X-User-Id must be a UUID".to_owned()))
}
fn pool(state: &AppState) -> Result<&PgPool, ApiError> {
state.pool.as_ref().ok_or(ApiError::DatabaseUnavailable)
}
async fn assert_profile_owner(
pool: &PgPool,
owner_id: Uuid,
profile_id: Uuid,
) -> Result<(), ApiError> {
let exists = sqlx::query_scalar::<_, bool>(
"SELECT EXISTS(SELECT 1 FROM student_profiles WHERE id = $1 AND owner_id = $2)",
)
.bind(profile_id)
.bind(owner_id)
.fetch_one(pool)
.await?;
if exists {
Ok(())
} else {
Err(ApiError::NotFound)
}
}
async fn assert_session_owner(
pool: &PgPool,
owner_id: Uuid,
session_id: Uuid,
) -> Result<(), ApiError> {
let exists = sqlx::query_scalar::<_, bool>(
"SELECT EXISTS(SELECT 1 FROM feedback_sessions WHERE id = $1 AND owner_id = $2 AND status = 'active')",
)
.bind(session_id)
.bind(owner_id)
.fetch_one(pool)
.await?;
if exists {
Ok(())
} else {
Err(ApiError::NotFound)
}
}
async fn assert_lesson_owner(
pool: &PgPool,
owner_id: Uuid,
lesson_id: Uuid,
) -> Result<Uuid, ApiError> {
sqlx::query_scalar::<_, Uuid>(
"SELECT f.id FROM lesson_sessions l \
JOIN feedback_sessions f ON f.id = l.feedback_session_id \
WHERE l.id = $1 AND f.owner_id = $2 AND f.status = 'active'",
)
.bind(lesson_id)
.bind(owner_id)
.fetch_optional(pool)
.await?
.ok_or(ApiError::NotFound)
}
async fn touch_session(pool: &PgPool, session_id: Uuid) -> Result<(), ApiError> {
sqlx::query("UPDATE feedback_sessions SET updated_at = now() WHERE id = $1")
.bind(session_id)
.execute(pool)
.await?;
Ok(())
}
fn internal_io_error(error: std::io::Error) -> ApiError {
tracing::error!(?error, "audio file operation failed");
ApiError::Internal
}
fn validate_draft_content(content: &str) -> Result<(), ApiError> {
if content.chars().count() > 2000 {
return Err(ApiError::BadRequest(
"feedback content cannot exceed 2000 characters".to_owned(),
));
}
Ok(())
}

73
src/routes.rs
View File

@@ -18,6 +18,7 @@ use uuid::Uuid;
use crate::{
AppState,
error::{ApiError, CommonApiErrors, ErrorBody},
recording_routes,
};
type SharedState = Arc<AppState>;
@@ -34,6 +35,7 @@ pub fn router() -> (Router<SharedState>, OpenApi) {
.routes(routes!(get_defaults, update_defaults))
.routes(routes!(list_feedback_records, create_feedback_record))
.routes(routes!(delete_feedback_record))
.merge(recording_routes::router())
.split_for_parts();
let mut info = Info::new("教学反馈助手 API", env!("CARGO_PKG_VERSION"));
@@ -49,6 +51,7 @@ pub fn router() -> (Router<SharedState>, OpenApi) {
api_tag("学生档案", "创建、查询、更新和删除当前用户的学生档案。"),
api_tag("档案预设", "读取或保存当前用户新建档案时使用的默认值。"),
api_tag("反馈记录", "创建、查询和删除当前用户的教学反馈记录。"),
api_tag("语音反馈", "录制多节课堂、转录音频并生成反馈草稿。"),
]);
(router, openapi)
@@ -62,12 +65,27 @@ fn api_tag(name: &str, description: &str) -> Tag {
/// 健康检查响应。
#[derive(Serialize, ToSchema)]
#[schema(example = json!({"status": "ok", "database_configured": true}))]
#[schema(example = json!({
"status": "ok",
"database_configured": true,
"speech_configured": true,
"speech_available": true,
"speech_provider": "local-funasr",
"summary_configured": false
}))]
struct HealthResponse {
/// HTTP 服务状态；正常时固定为 `ok`。
status: &'static str,
/// 是否已经通过 `DATABASE_URL` 配置数据库连接。
database_configured: bool,
/// 是否已经配置长音频转录服务。
speech_configured: bool,
/// 当前转录服务是否可连接；本地模型启动和下载完成后为 `true`。
speech_available: bool,
/// 当前语音提供方；未启用转录时为 `null`。
speech_provider: Option<&'static str>,
/// 是否已经配置生成式反馈汇总服务；未配置时使用本地抽取式汇总。
summary_configured: bool,
}
/// 检查服务状态。
@@ -85,6 +103,10 @@ async fn health(State(state): State<SharedState>) -> Json<HealthResponse> {
Json(HealthResponse {
status: "ok",
database_configured: state.pool.is_some(),
speech_configured: state.speech.configured(),
speech_available: state.speech.available().await,
speech_provider: state.speech.provider_name(),
summary_configured: state.summary.configured(),
})
}
@@ -561,7 +583,8 @@ struct FeedbackRecord {
#[schema(example = json!({
"profile_id": null,
"feedback_date": "2026-07-15",
"content": "今天完成了色彩搭配练习，构图有明显进步。"
"content": "今天完成了色彩搭配练习，构图有明显进步。",
"feedback_session_id": null
}))]
struct FeedbackRecordInput {
/// 可选的学生档案 ID；如填写，必须属于当前用户。Scalar 默认留空以便直接测试。
@@ -570,6 +593,8 @@ struct FeedbackRecordInput {
feedback_date: NaiveDate,
/// 教学反馈正文，不可为空。
content: String,
/// 可选的语音反馈批次 ID；保存后对应批次会被标记为已完成。
feedback_session_id: Option<Uuid>,
}
#[derive(Debug, Deserialize)]
@@ -634,7 +659,8 @@ async fn list_feedback_records(
example = json!({
"profile_id": null,
"feedback_date": "2026-07-15",
"content": "今天完成了色彩搭配练习，构图有明显进步。"
"content": "今天完成了色彩搭配练习，构图有明显进步。",
"feedback_session_id": null
})
),
responses(
@@ -648,13 +674,33 @@ async fn create_feedback_record(
headers: HeaderMap,
Json(input): Json<FeedbackRecordInput>,
) -> Result<(axum::http::StatusCode, Json<FeedbackRecord>), ApiError> {
if input.content.trim().is_empty() {
return Err(ApiError::BadRequest("content cannot be empty".to_owned()));
if input.content.trim().is_empty() || input.content.chars().count() > 2000 {
return Err(ApiError::BadRequest(
"content must contain 1 to 2000 characters".to_owned(),
));
}
let owner_id = current_user(&headers)?;
let pool = pool(&state)?;
if let Some(profile_id) = input.profile_id {
assert_profile_owner(pool(&state)?, owner_id, profile_id).await?;
assert_profile_owner(pool, owner_id, profile_id).await?;
}
if let Some(session_id) = input.feedback_session_id {
let session_profile_id = sqlx::query_scalar::<_, Option<Uuid>>(
"SELECT profile_id FROM feedback_sessions \
WHERE id = $1 AND owner_id = $2 AND status = 'active'",
)
.bind(session_id)
.bind(owner_id)
.fetch_optional(pool)
.await?
.ok_or(ApiError::NotFound)?;
if session_profile_id != input.profile_id {
return Err(ApiError::BadRequest(
"feedback session profile does not match feedback record".to_owned(),
));
}
}
let mut transaction = pool.begin().await?;
let record = sqlx::query_as::<_, FeedbackRecord>(
"INSERT INTO feedback_records (id, owner_id, profile_id, feedback_date, content) \
VALUES ($1, $2, $3, $4, $5) \
@@ -665,8 +711,19 @@ async fn create_feedback_record(
.bind(input.profile_id)
.bind(input.feedback_date)
.bind(input.content.trim())
.fetch_one(pool(&state)?)
.fetch_one(&mut *transaction)
.await?;
if let Some(session_id) = input.feedback_session_id {
sqlx::query(
"UPDATE feedback_sessions SET status = 'finalized', finalized_record_id = $2, updated_at = now() \
WHERE id = $1",
)
.bind(session_id)
.bind(record.id)
.execute(&mut *transaction)
.await?;
}
transaction.commit().await?;
Ok((axum::http::StatusCode::CREATED, Json(record)))
}
@@ -827,7 +884,7 @@ mod tests {
.filter(|operation| operation.get("responses").is_some())
.collect::<Vec<_>>();
assert_eq!(operations.len(), 11);
assert_eq!(operations.len(), 20);
for operation in &operations {
assert_non_empty(operation, "summary");
assert_non_empty(operation, "description");

350
src/speech.rs Normal file
View File

@@ -0,0 +1,350 @@
use std::{collections::BTreeMap, time::Duration};
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64};
use hmac::{Hmac, Mac};
use reqwest::{
Client,
header::{AUTHORIZATION, CONTENT_TYPE},
multipart::{Form, Part},
};
use serde::Deserialize;
use sha1::Sha1;
use crate::config::{SpeechConfig, SpeechProviderConfig, TencentSpeechConfig};
const ASR_HOST: &str = "asr.cloud.tencent.com";
#[derive(Clone)]
pub struct SpeechService {
config: Option<SpeechConfig>,
client: Client,
}
#[derive(Debug)]
pub struct Transcription {
pub text: String,
pub duration_ms: i32,
pub request_id: String,
}
#[derive(Deserialize)]
struct LocalResponse {
text: String,
#[serde(default)]
duration_ms: i32,
#[serde(default)]
request_id: String,
}
#[derive(Deserialize)]
struct FlashResponse {
code: i32,
message: String,
request_id: Option<String>,
audio_duration: Option<i32>,
#[serde(default)]
flash_result: Vec<FlashResult>,
}
#[derive(Deserialize)]
struct FlashResult {
text: String,
}
impl SpeechService {
pub fn new(config: Option<SpeechConfig>) -> Self {
let timeout = config.as_ref().map_or(Duration::from_secs(30), |value| {
Duration::from_secs(value.request_timeout_seconds)
});
let client = Client::builder()
.timeout(timeout)
.build()
.expect("reqwest client configuration should be valid");
Self { config, client }
}
pub fn configured(&self) -> bool {
self.config.is_some()
}
pub fn provider_name(&self) -> Option<&'static str> {
self.config.as_ref().map(|config| match config.provider {
SpeechProviderConfig::Local { .. } => "local-funasr",
SpeechProviderConfig::Tencent(_) => "tencent",
})
}
pub fn worker_concurrency(&self) -> usize {
self.config
.as_ref()
.map_or(0, |config| config.worker_concurrency)
}
pub fn job_lease_seconds(&self) -> i64 {
self.config
.as_ref()
.map_or(3_600, |config| config.job_lease_seconds)
}
pub async fn available(&self) -> bool {
let Some(config) = &self.config else {
return false;
};
match &config.provider {
SpeechProviderConfig::Local { api_url } => {
let request = self.client.get(format!("{api_url}/health")).send();
matches!(
tokio::time::timeout(Duration::from_secs(2), request).await,
Ok(Ok(response)) if response.status().is_success()
)
}
SpeechProviderConfig::Tencent(_) => true,
}
}
pub async fn transcribe(
&self,
audio: Vec<u8>,
audio_format: &str,
duration_ms: i32,
) -> Result<Transcription, String> {
let config = self
.config
.as_ref()
.ok_or_else(|| "语音转录服务尚未配置".to_owned())?;
match &config.provider {
SpeechProviderConfig::Local { api_url } => {
self.transcribe_local(api_url, audio, audio_format, duration_ms)
.await
}
SpeechProviderConfig::Tencent(config) => {
self.transcribe_tencent(config, audio, audio_format).await
}
}
}
async fn transcribe_local(
&self,
api_url: &str,
audio: Vec<u8>,
audio_format: &str,
duration_ms: i32,
) -> Result<Transcription, String> {
let part = Part::bytes(audio)
.file_name(format!("segment.{audio_format}"))
.mime_str(audio_content_type(audio_format))
.map_err(|error| format!("录音格式无效：{error}"))?;
let form = Form::new()
.part("file", part)
.text("language", "zh")
.text("duration_ms", duration_ms.to_string());
let response = self
.client
.post(local_transcription_url(api_url))
.multipart(form)
.send()
.await
.map_err(|error| format!("本地语音转录服务连接失败：{error}"))?;
let status = response.status();
let body = response
.text()
.await
.map_err(|error| format!("读取本地语音转录响应失败：{error}"))?;
if !status.is_success() {
return Err(format!(
"本地语音转录服务返回 HTTP {status}：{}",
compact_error(&body)
));
}
let result: LocalResponse = serde_json::from_str(&body)
.map_err(|error| format!("本地语音转录响应格式无效：{error}"))?;
transcription(result.text, result.duration_ms, result.request_id)
}
async fn transcribe_tencent(
&self,
config: &TencentSpeechConfig,
audio: Vec<u8>,
audio_format: &str,
) -> Result<Transcription, String> {
let timestamp = chrono::Utc::now().timestamp();
let (url, signature) = signed_request(config, audio_format, timestamp)?;
let response = self
.client
.post(url)
.header(AUTHORIZATION, signature)
.header(CONTENT_TYPE, "application/octet-stream")
.body(audio)
.send()
.await
.map_err(|error| format!("语音转录服务连接失败：{error}"))?;
let status = response.status();
let body = response
.text()
.await
.map_err(|error| format!("读取语音转录响应失败：{error}"))?;
if !status.is_success() {
return Err(format!("语音转录服务返回 HTTP {status}"));
}
let result: FlashResponse = serde_json::from_str(&body)
.map_err(|error| format!("语音转录响应格式无效：{error}"))?;
if result.code != 0 {
return Err(format!(
"语音转录失败（{}）：{}",
result.code, result.message
));
}
let text = result
.flash_result
.into_iter()
.map(|channel| channel.text)
.collect::<Vec<_>>()
.join("\n");
transcription(
text,
result.audio_duration.unwrap_or_default(),
result.request_id.unwrap_or_default(),
)
}
}
fn transcription(
text: String,
duration_ms: i32,
request_id: String,
) -> Result<Transcription, String> {
let text = text.trim().to_owned();
if text.is_empty() {
return Err("未识别到清晰语音".to_owned());
}
Ok(Transcription {
text,
duration_ms,
request_id,
})
}
fn local_transcription_url(api_url: &str) -> String {
format!("{}/v1/transcriptions", api_url.trim_end_matches('/'))
}
fn audio_content_type(audio_format: &str) -> &'static str {
match audio_format {
"aac" => "audio/aac",
"wav" => "audio/wav",
"m4a" => "audio/mp4",
"amr" => "audio/amr",
_ => "audio/mpeg",
}
}
fn compact_error(body: &str) -> String {
let value = body.split_whitespace().collect::<Vec<_>>().join(" ");
value.chars().take(240).collect()
}
fn signed_request(
config: &TencentSpeechConfig,
audio_format: &str,
timestamp: i64,
) -> Result<(String, String), String> {
let mut params = BTreeMap::new();
params.insert("convert_num_mode", "1".to_owned());
params.insert("engine_type", config.engine_type.clone());
params.insert("filter_dirty", "0".to_owned());
params.insert("filter_modal", "1".to_owned());
params.insert("filter_punc", "0".to_owned());
params.insert("first_channel_only", "1".to_owned());
params.insert("secretid", config.secret_id.clone());
params.insert("speaker_diarization", "0".to_owned());
params.insert("timestamp", timestamp.to_string());
params.insert("voice_format", audio_format.to_owned());
params.insert("word_info", "0".to_owned());
let query = url::form_urlencoded::Serializer::new(String::new())
.extend_pairs(params.iter())
.finish();
let path = format!("/asr/flash/v1/{}", config.app_id);
let source = format!("POST{ASR_HOST}{path}?{query}");
let mut mac = Hmac::<Sha1>::new_from_slice(config.secret_key.as_bytes())
.map_err(|_| "语音转录密钥格式无效".to_owned())?;
mac.update(source.as_bytes());
let signature = BASE64.encode(mac.finalize().into_bytes());
Ok((format!("https://{ASR_HOST}{path}?{query}"), signature))
}
#[cfg(test)]
mod tests {
use axum::{
Json, Router,
routing::{get, post},
};
use serde_json::json;
use crate::config::{SpeechConfig, SpeechProviderConfig, TencentSpeechConfig};
use super::{SpeechService, local_transcription_url, signed_request};
#[test]
fn signed_request_sorts_parameters_and_is_stable() {
let config = TencentSpeechConfig {
app_id: 123,
secret_id: "secret-id".to_owned(),
secret_key: "secret-key".to_owned(),
engine_type: "16k_zh".to_owned(),
};
let first = signed_request(&config, "mp3", 1_700_000_000).unwrap();
let second = signed_request(&config, "mp3", 1_700_000_000).unwrap();
assert_eq!(first, second);
assert!(first.0.contains("convert_num_mode=1&engine_type=16k_zh"));
assert!(first.0.ends_with("voice_format=mp3&word_info=0"));
assert!(!first.1.is_empty());
}
#[test]
fn local_url_has_one_transcription_suffix() {
assert_eq!(
local_transcription_url("http://127.0.0.1:10095/"),
"http://127.0.0.1:10095/v1/transcriptions"
);
}
#[tokio::test]
async fn local_provider_sends_audio_and_parses_response() {
let app = Router::new()
.route("/health", get(|| async { Json(json!({"status": "ok"})) }))
.route(
"/v1/transcriptions",
post(|| async {
Json(json!({
"text": "课堂练习完成。",
"duration_ms": 12_345,
"request_id": "local-request"
}))
}),
);
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
let service = SpeechService::new(Some(SpeechConfig {
provider: SpeechProviderConfig::Local {
api_url: format!("http://{address}"),
},
request_timeout_seconds: 5,
worker_concurrency: 1,
job_lease_seconds: 60,
}));
assert!(service.available().await);
let result = service
.transcribe(vec![1, 2, 3], "mp3", 10_000)
.await
.unwrap();
assert_eq!(result.text, "课堂练习完成。");
assert_eq!(result.duration_ms, 12_345);
assert_eq!(result.request_id, "local-request");
}
}

193
src/summary.rs Normal file
View File

@@ -0,0 +1,193 @@
use std::collections::HashSet;
use reqwest::header::{AUTHORIZATION, CONTENT_TYPE};
use serde::{Deserialize, Serialize};
use crate::config::SummaryConfig;
const MAX_FEEDBACK_CHARS: usize = 2000;
#[derive(Clone)]
pub struct SummaryService {
config: Option<SummaryConfig>,
client: reqwest::Client,
}
#[derive(Debug)]
pub struct SummaryResult {
pub content: String,
pub method: &'static str,
}
#[derive(Serialize)]
struct ChatRequest<'a> {
model: &'a str,
messages: Vec<ChatMessage<'a>>,
temperature: f32,
}
#[derive(Serialize)]
struct ChatMessage<'a> {
role: &'a str,
content: &'a str,
}
#[derive(Deserialize)]
struct ChatResponse {
choices: Vec<ChatChoice>,
}
#[derive(Deserialize)]
struct ChatChoice {
message: ChatChoiceMessage,
}
#[derive(Deserialize)]
struct ChatChoiceMessage {
content: String,
}
impl SummaryService {
pub fn new(config: Option<SummaryConfig>) -> Self {
Self {
config,
client: reqwest::Client::new(),
}
}
pub fn configured(&self) -> bool {
self.config.is_some()
}
pub async fn summarize(
&self,
existing_content: &str,
lesson_transcripts: &[String],
) -> Result<SummaryResult, String> {
let Some(config) = &self.config else {
return Ok(SummaryResult {
content: extractive_summary(existing_content, lesson_transcripts),
method: "extractive",
});
};
let transcript_text = lesson_transcripts
.iter()
.enumerate()
.map(|(index, transcript)| format!("第{}节课：\n{}", index + 1, transcript))
.collect::<Vec<_>>()
.join("\n\n");
let user_prompt = format!(
"教师已填写内容：\n{}\n\n新增课堂转录：\n{}",
existing_content.trim(),
transcript_text
);
let system_prompt = "你是教学反馈整理助手。请把教师已有内容与课堂转录合并成一份面向家长的中文反馈，保留具体事实，按课堂表现、进步、问题和后续建议组织。不要虚构，不要提及录音或转录，不超过2000个汉字，只输出反馈正文。";
let request = ChatRequest {
model: &config.model,
messages: vec![
ChatMessage {
role: "system",
content: system_prompt,
},
ChatMessage {
role: "user",
content: &user_prompt,
},
],
temperature: 0.2,
};
let mut builder = self
.client
.post(&config.api_url)
.header(CONTENT_TYPE, "application/json")
.json(&request);
if let Some(api_key) = &config.api_key {
builder = builder.header(AUTHORIZATION, format!("Bearer {api_key}"));
}
let response = builder
.send()
.await
.map_err(|error| format!("反馈汇总服务连接失败：{error}"))?;
let status = response.status();
if !status.is_success() {
return Err(format!("反馈汇总服务返回 HTTP {status}"));
}
let result: ChatResponse = response
.json()
.await
.map_err(|error| format!("反馈汇总响应格式无效：{error}"))?;
let content = result
.choices
.into_iter()
.next()
.map(|choice| choice.message.content.trim().to_owned())
.filter(|content| !content.is_empty())
.ok_or_else(|| "反馈汇总服务未返回内容".to_owned())?;
Ok(SummaryResult {
content: content.chars().take(MAX_FEEDBACK_CHARS).collect(),
method: "llm",
})
}
}
fn extractive_summary(existing_content: &str, lesson_transcripts: &[String]) -> String {
let existing = existing_content.trim();
let mut result = existing
.chars()
.take(MAX_FEEDBACK_CHARS)
.collect::<String>();
let mut seen = HashSet::new();
let mut selected = Vec::new();
for transcript in lesson_transcripts {
for sentence in transcript.split_inclusive(['。', '！', '？', '\n']) {
let sentence = sentence.trim();
if sentence.chars().count() < 4 || !seen.insert(sentence.to_owned()) {
continue;
}
selected.push(sentence.to_owned());
}
}
if !selected.is_empty() && result.chars().count() < MAX_FEEDBACK_CHARS {
if !result.is_empty() {
result.push_str("\n\n");
}
result.push_str("课堂记录汇总：\n");
for sentence in selected {
let prefix = "- ";
let remaining = MAX_FEEDBACK_CHARS.saturating_sub(result.chars().count());
if remaining <= prefix.chars().count() + 4 {
break;
}
result.push_str(prefix);
result.extend(
sentence
.chars()
.take(remaining - prefix.chars().count() - 1),
);
result.push('\n');
}
}
result.trim().to_owned()
}
#[cfg(test)]
mod tests {
use super::extractive_summary;
#[test]
fn extractive_summary_preserves_manual_content_and_deduplicates() {
let result = extractive_summary(
"手动备注。",
&["完成了构图练习。完成了构图练习。色彩更大胆。".to_owned()],
);
assert!(result.starts_with("手动备注。"));
assert_eq!(result.matches("完成了构图练习。").count(), 1);
assert!(result.contains("色彩更大胆。"));
}
}

202
src/transcription_worker.rs Normal file
View File

@@ -0,0 +1,202 @@
use std::time::Duration;
use sqlx::{FromRow, PgPool};
use uuid::Uuid;
use crate::speech::{SpeechService, Transcription};
const IDLE_POLL_INTERVAL: Duration = Duration::from_millis(750);
const UNAVAILABLE_POLL_INTERVAL: Duration = Duration::from_secs(5);
#[derive(Debug, FromRow)]
struct TranscriptionJob {
id: Uuid,
lesson_session_id: Uuid,
duration_ms: i32,
audio_format: String,
audio_path: String,
}
pub fn spawn(pool: PgPool, speech: SpeechService) {
for worker_id in 1..=speech.worker_concurrency() {
let pool = pool.clone();
let speech = speech.clone();
tokio::spawn(async move {
run(worker_id, pool, speech).await;
});
}
}
async fn run(worker_id: usize, pool: PgPool, speech: SpeechService) {
let mut service_available = true;
loop {
match has_claimable_job(&pool, speech.job_lease_seconds()).await {
Ok(false) => {
tokio::time::sleep(IDLE_POLL_INTERVAL).await;
continue;
}
Ok(true) => {}
Err(error) => {
tracing::error!(worker_id, error = %error, "failed to inspect transcription queue");
tokio::time::sleep(UNAVAILABLE_POLL_INTERVAL).await;
continue;
}
}
let available = speech.available().await;
if !available {
if service_available {
tracing::warn!(worker_id, provider = ?speech.provider_name(), "ASR service is unavailable; queued audio will wait");
}
service_available = false;
tokio::time::sleep(UNAVAILABLE_POLL_INTERVAL).await;
continue;
}
if !service_available {
tracing::info!(worker_id, provider = ?speech.provider_name(), "ASR service is available again");
}
service_available = true;
match claim_next_job(&pool, speech.job_lease_seconds()).await {
Ok(Some(job)) => {
tracing::info!(worker_id, segment_id = %job.id, "transcribing audio segment");
if let Err(error) = process_job(&pool, &speech, &job).await {
tracing::error!(worker_id, segment_id = %job.id, error = %error, "transcription job update failed");
tokio::time::sleep(IDLE_POLL_INTERVAL).await;
}
}
Ok(None) => tokio::time::sleep(IDLE_POLL_INTERVAL).await,
Err(error) => {
tracing::error!(worker_id, error = %error, "failed to claim transcription job");
tokio::time::sleep(UNAVAILABLE_POLL_INTERVAL).await;
}
}
}
}
async fn has_claimable_job(pool: &PgPool, lease_seconds: i64) -> Result<bool, sqlx::Error> {
sqlx::query_scalar(
"SELECT EXISTS(\
SELECT 1 FROM audio_segments \
WHERE status = 'processing' \
AND (processing_started_at IS NULL \
OR processing_started_at < now() - ($1 * interval '1 second'))\
)",
)
.bind(lease_seconds)
.fetch_one(pool)
.await
}
async fn claim_next_job(
pool: &PgPool,
lease_seconds: i64,
) -> Result<Option<TranscriptionJob>, sqlx::Error> {
sqlx::query_as::<_, TranscriptionJob>(
"WITH next_job AS (\
SELECT id FROM audio_segments \
WHERE status = 'processing' \
AND (processing_started_at IS NULL \
OR processing_started_at < now() - ($1 * interval '1 second')) \
ORDER BY created_at, id \
FOR UPDATE SKIP LOCKED LIMIT 1\
) \
UPDATE audio_segments AS segment \
SET processing_started_at = now(), \
transcription_attempts = transcription_attempts + 1, \
updated_at = now() \
FROM next_job \
WHERE segment.id = next_job.id \
RETURNING segment.id, segment.lesson_session_id, segment.duration_ms, \
segment.audio_format, segment.audio_path",
)
.bind(lease_seconds)
.fetch_optional(pool)
.await
}
async fn process_job(
pool: &PgPool,
speech: &SpeechService,
job: &TranscriptionJob,
) -> Result<(), sqlx::Error> {
let result = match tokio::fs::read(&job.audio_path).await {
Ok(audio) => {
speech
.transcribe(audio, &job.audio_format, job.duration_ms)
.await
}
Err(error) => Err(format!("读取录音文件失败：{error}")),
};
match result {
Ok(transcription) => complete_job(pool, job, transcription).await?,
Err(message) => fail_job(pool, job, &message).await?,
}
refresh_lesson(pool, job.lesson_session_id).await?;
Ok(())
}
async fn complete_job(
pool: &PgPool,
job: &TranscriptionJob,
transcription: Transcription,
) -> Result<(), sqlx::Error> {
let duration_ms = if transcription.duration_ms > 0 {
transcription.duration_ms
} else {
job.duration_ms
};
sqlx::query(
"UPDATE audio_segments \
SET status = 'ready', duration_ms = $2, transcript = $3, error_message = NULL, \
provider_request_id = $4, processing_started_at = NULL, updated_at = now() \
WHERE id = $1",
)
.bind(job.id)
.bind(duration_ms)
.bind(&transcription.text)
.bind(&transcription.request_id)
.execute(pool)
.await?;
tracing::info!(segment_id = %job.id, "audio segment transcription is ready");
Ok(())
}
async fn fail_job(pool: &PgPool, job: &TranscriptionJob, message: &str) -> Result<(), sqlx::Error> {
tracing::warn!(segment_id = %job.id, error = %message, "audio transcription failed");
sqlx::query(
"UPDATE audio_segments \
SET status = 'failed', error_message = $2, processing_started_at = NULL, updated_at = now() \
WHERE id = $1",
)
.bind(job.id)
.bind(message)
.execute(pool)
.await?;
Ok(())
}
async fn refresh_lesson(pool: &PgPool, lesson_id: Uuid) -> Result<(), sqlx::Error> {
sqlx::query(
"UPDATE lesson_sessions AS lesson \
SET status = CASE \
WHEN EXISTS (SELECT 1 FROM audio_segments WHERE lesson_session_id = $1 AND status = 'failed') THEN 'failed' \
WHEN EXISTS (SELECT 1 FROM audio_segments WHERE lesson_session_id = $1 AND status = 'processing') THEN 'processing' \
ELSE 'ready' \
END, \
duration_ms = COALESCE((SELECT SUM(duration_ms) FROM audio_segments WHERE lesson_session_id = $1), 0), \
updated_at = now() \
WHERE lesson.id = $1 AND lesson.ended_at IS NOT NULL",
)
.bind(lesson_id)
.execute(pool)
.await?;
sqlx::query(
"UPDATE feedback_sessions SET updated_at = now() \
WHERE id = (SELECT feedback_session_id FROM lesson_sessions WHERE id = $1)",
)
.bind(lesson_id)
.execute(pool)
.await?;
Ok(())
}