tdm_server_rust/service/

episode_service.rs

//! 话数业务服务 (Episode Service)
//!
//! 话数管理的核心业务逻辑：
//! - 话数 CRUD（创建、批量创建、更新、删除）
//! - 发布链接管理
//! - 上传页数据查询
//! - 统计信息（漫画统计、组员统计）
//! - 最新话查询

use crate::{
    app::AppState,
    cache::{
        get_list_page_json_cached, get_member_statistics_json_cached,
        get_statistics_list_json_cached, manga_episode_page_cache_key,
        manga_episode_simple_cache_key, member_statistics_cache_key, on_episode_mutated,
        set_list_page_json_cached, set_member_statistics_json_cached, set_result_json_cached,
        set_statistics_list_json_cached, uploaded_submit_cache_key,
    },
    common::PageBean,
    entity::enums::{MemberInternEnum, PostEnum},
    entity::episode::{
        EpisodeDetailVo, EpisodeEditDto, EpisodeListVo, EpisodeSimpleListVo, EpisodeType,
        MemberStatistics, NewestEpisodeVo, PublishLinkRequest, Statistics, UploadPageVo,
    },
    entity::manga::EpisodeDownloadRequest,
    error::{ApiResult, AppError},
    repository::{
        episode_repo::EpisodeRepository, member_repo::MemberRepository, oss_repo::OssRepository,
    },
    service::{
        oss_service::OssService,
        rss_service::{RssRefreshScope, RssService},
    },
    utils::page::slice_rows,
};
use axum::body::Bytes;
use chrono::{DateTime, Utc};
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

/// 话数服务
///
/// 提供话数及关联数据（统计、发布）的完整业务逻辑。
pub struct EpisodeService;

impl EpisodeService {
    /// 按漫画 ID 查询话数简单列表。
    ///
    /// 返回包含文件信息的精简话数列表，用于上传页展示。
    /// 结果按 `manga_episode` 升序排列，仅包含未删除的话数记录。
    ///
    /// # 返回值
    ///
    /// 返回漫画下所有未删除的话数列表，按 `manga_episode` 排序。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库查询失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use tdm_server::service::episode_service::EpisodeService;
    ///
    /// let episodes = EpisodeService::select_list_by_manga_id(&state, manga_id).await?;
    /// for ep in &episodes {
    ///     println!("话数 {}: {}", ep.manga_episode, ep.manga_episode_name);
    /// }
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn select_list_by_manga_id(
        state: &AppState,
        manga_id: i32,
    ) -> ApiResult<Vec<EpisodeSimpleListVo>> {
        EpisodeRepository::new(state.db.clone())
            .list_by_manga_id(manga_id)
            .await
    }

    /// 漫画话数简单列表预序列化 JSON（短 TTL 缓存）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn select_list_by_manga_id_json(
        state: &AppState,
        manga_id: i32,
    ) -> ApiResult<Arc<Vec<u8>>> {
        let key = manga_episode_simple_cache_key(state, manga_id);
        if let Some(json) = get_list_page_json_cached(state, &key).await {
            return Ok(json);
        }
        let list = Self::select_list_by_manga_id(state, manga_id).await?;
        set_result_json_cached(state, key.clone(), list).await;
        get_list_page_json_cached(state, &key)
            .await
            .ok_or_else(|| AppError::business("话数简单列表缓存写入失败"))
    }

    /// 批量更新话数发布链接。
    ///
    /// 接收一组发布链接请求，批量更新数据库中的链接字段。
    /// 更新完成后会刷新任务追踪缓存，并为每个话数触发 RSS 订阅源刷新。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库更新失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let requests = vec![
    ///     PublishLinkRequest { id: 1, publish_link: Some("https://example.com/1".into()) },
    ///     PublishLinkRequest { id: 2, publish_link: Some("https://example.com/2".into()) },
    /// ];
    /// EpisodeService::update_manga_episodes(&state, requests).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn update_manga_episodes(
        state: &AppState,
        requests: Vec<PublishLinkRequest>,
    ) -> ApiResult<()> {
        EpisodeRepository::new(state.db.clone())
            .update_publish_links_batch(&requests)
            .await?;
        let mut manga_ids = HashSet::new();
        let repo = EpisodeRepository::new(state.db.clone());
        for id in requests.iter().map(|r| r.id) {
            if let Ok(Some(manga_id)) = repo.get_manga_id_by_episode_id(id).await {
                manga_ids.insert(manga_id);
            }
            RssService::refresh(state, RssRefreshScope::PublishLink { episode_id: id });
        }
        for manga_id in manga_ids {
            on_episode_mutated(state, manga_id, &[]).await;
        }
        Ok(())
    }

    /// 更新单条话数的发布链接。
    ///
    /// 在写入前会检查新链接是否与其他话数冲突。更新成功后同样
    /// 会刷新任务追踪缓存和 RSS 订阅源。
    ///
    /// # Errors
    ///
    /// - `AppError::business("发布链接已存在喵")` — 链接与其他话数冲突
    /// - `AppError::Database` — 数据库操作失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// EpisodeService::update_publish_link(
    ///     &state,
    ///     42,
    ///     Some("https://example.com/ch42".to_string()),
    /// ).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn update_publish_link(
        state: &AppState,
        id: i32,
        publish_link: Option<String>,
    ) -> ApiResult<()> {
        let repo = EpisodeRepository::new(state.db.clone());
        if let Some(ref link) = publish_link {
            if !link.is_empty() && repo.count_publish_link(link, Some(id)).await? > 0 {
                return Err(AppError::business("发布链接已存在喵"));
            }
        }
        let dto = EpisodeEditDto {
            id: Some(id),
            manga_id: None,
            manga_episode: None,
            manga_episode_end: None,
            manga_episode_name: None,
            episode_type: None,
            provider_id: None,
            translator_id: None,
            proofreader_id: None,
            letterer_id: None,
            timer_id: None,
            reviewer_id: None,
            publish_link,
        };
        repo.update_publish_link_only(id, dto.publish_link).await?;
        if let Some(manga_id) = repo.get_manga_id_by_episode_id(id).await? {
            on_episode_mutated(state, manga_id, &[]).await;
        }
        RssService::refresh(state, RssRefreshScope::PublishLink { episode_id: id });
        Ok(())
    }

    /// 分页查询漫画话数。
    ///
    /// 获取指定漫画下的全部话数列表，然后在内存中进行分页截取。
    /// 返回标准分页对象 `PageBean`，包含当前页数据、总条数和总页数。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库查询失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// // 查询第 1 页，每页 20 条
    /// let page = EpisodeService::page_episode(&state, 1, 20, manga_id).await?;
    /// println!("共 {} 条，当前页 {} 条", page.total, page.rows.len());
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn page_episode(
        state: &AppState,
        page: i32,
        page_size: i32,
        manga_id: i32,
        episode_type: EpisodeType,
    ) -> ApiResult<PageBean<EpisodeListVo>> {
        let (total, rows) = EpisodeRepository::new(state.db.clone())
            .page_episodes_by_manga(manga_id, page, page_size, episode_type)
            .await?;
        Ok(slice_rows(rows, total))
    }

    /// 漫画话数分页预序列化 JSON（短 TTL 缓存）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn page_episode_json(
        state: &AppState,
        page: i32,
        page_size: i32,
        manga_id: i32,
        episode_type: EpisodeType,
    ) -> ApiResult<Arc<Vec<u8>>> {
        let key = manga_episode_page_cache_key(
            state,
            manga_id,
            page,
            page_size,
            episode_type.as_str(),
        );
        if let Some(json) = get_list_page_json_cached(state, &key).await {
            return Ok(json);
        }
        let page_data =
            Self::page_episode(state, page, page_size, manga_id, episode_type).await?;
        set_list_page_json_cached(state, key.clone(), page_data).await;
        get_list_page_json_cached(state, &key)
            .await
            .ok_or_else(|| AppError::business("话数分页缓存写入失败"))
    }

    /// 删除指定话数（软删除）。
    ///
    /// 将话数标记为删除状态，同时刷新任务追踪缓存并触发 RSS 订阅源
    /// 全量刷新。注意：此操作不会立即从数据库中物理删除数据。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库操作失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// EpisodeService::delete_episode(&state, episode_id).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn delete_episode(state: &AppState, id: i32) -> ApiResult<()> {
        let repo = EpisodeRepository::new(state.db.clone());
        let member_ids = repo.get_post_member_ids(id).await?;
        let manga_id = repo.get_manga_id_by_episode_id(id).await?;
        repo.delete_by_id(id).await?;
        if let Some(manga_id) = manga_id {
            on_episode_mutated(state, manga_id, &member_ids).await;
        }
        RssService::refresh(state, RssRefreshScope::EpisodePipeline);
        Ok(())
    }

    /// 新增话数（对齐 Java `addEpisodes`）。
    ///
    /// 支持两种模式：
    /// - **批量模式**：指定 `manga_episode` 起始值和 `manga_episode_end` 结束值，
    ///   在区间内逐条创建话数。
    /// - **单话模式**：仅指定 `manga_episode`，创建一条话数记录。
    ///
    /// 创建完成后会刷新任务追踪缓存并触发 RSS 全量刷新。
    ///
    /// # Errors
    ///
    /// - `AppError::business("缺少漫画 ID")` — DTO 中未提供 `manga_id`
    /// - `AppError::business("起始话数格式不正确")` — 话数序号不是有效整数
    /// - `AppError::business("结束话数格式不正确")` — 结束序号不是有效整数
    /// - `AppError::business("该漫画单话已存在喵！")` — 话数序号重复
    /// - `AppError::business("发布链接已存在喵")` — 链接与其他话数冲突
    /// - `AppError::Database` — 数据库操作失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// // 批量创建话数 1~10
    /// let dto = EpisodeEditDto {
    ///     manga_id: Some(100),
    ///     manga_episode: Some("1".into()),
    ///     manga_episode_end: Some("10".into()),
    ///     ..Default::default()
    /// };
    /// EpisodeService::add_episodes(&state, dto).await?;
    ///
    /// // 创建单话
    /// let dto = EpisodeEditDto {
    ///     manga_id: Some(100),
    ///     manga_episode: Some("11".into()),
    ///     ..Default::default()
    /// };
    /// EpisodeService::add_episodes(&state, dto).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn add_episodes(state: &AppState, dto: EpisodeEditDto) -> ApiResult<()> {
        let manga_id = dto
            .manga_id
            .ok_or_else(|| AppError::business("缺少漫画 ID"))?;
        let repo = EpisodeRepository::new(state.db.clone());

        let end = dto
            .manga_episode_end
            .as_deref()
            .map(str::trim)
            .filter(|s| !s.is_empty());

        if let Some(end_str) = end {
            Self::validate_batch_options(&dto)?;
            let start_str = dto.manga_episode.as_deref().unwrap_or("0");
            let start: i32 = start_str
                .parse()
                .map_err(|_| AppError::business("起始话数格式不正确"))?;
            let end_num: i32 = end_str
                .parse()
                .map_err(|_| AppError::business("结束话数格式不正确"))?;
            if start > end_num {
                return Err(AppError::business("结束话数不能小于起始话数"));
            }

            let episode_type = dto.episode_type.unwrap_or_default();
            let mut batch = Vec::with_capacity((end_num - start + 1) as usize);
            for i in start..=end_num {
                let mut one = dto.clone();
                one.manga_episode = Some(i.to_string());
                one.manga_episode_end = None;
                if repo
                    .count_episode_by_number(manga_id, &i.to_string(), episode_type)
                    .await?
                    > 0
                {
                    return Err(AppError::business(format!(
                        "该漫画第 {i} 话已存在喵！"
                    )));
                }
                batch.push(one);
            }
            repo.insert_batch(&batch, manga_id).await?;
        } else {
            Self::add_single_episode(&repo, &dto, manga_id).await?;
        }
        on_episode_mutated(state, manga_id, &[]).await;
        RssService::refresh(state, RssRefreshScope::EpisodePipeline);
        Ok(())
    }

    fn validate_batch_options(dto: &EpisodeEditDto) -> ApiResult<()> {
        if dto.episode_type.unwrap_or_default() == EpisodeType::Extra {
            return Err(AppError::business("番外和特典不支持批量添加"));
        }
        if dto
            .publish_link
            .as_deref()
            .is_some_and(|link| !link.is_empty())
        {
            return Err(AppError::business("批量添加不支持设置发布链接"));
        }
        Ok(())
    }

    /// 创建单条话数记录（内部方法）。
    ///
    /// 执行话数新增的核心逻辑：
    /// 1. 校验话数序号是否与已有记录重复
    /// 2. 校验发布链接是否与其他话数冲突
    /// 3. 插入主表记录和详情记录
    /// 4. 更新漫画的 `update_time` 时间戳
    ///
    /// # Errors
    ///
    /// - `AppError::business("缺少话数序号")` — `manga_episode` 为空
    /// - `AppError::business("该漫画单话已存在喵！")` — 序号重复
    /// - `AppError::business("发布链接已存在喵")` — 链接冲突
    /// - `AppError::Database` — 数据库操作失败
    #[tracing::instrument(skip_all, level = "debug")]
    async fn add_single_episode(
        repo: &EpisodeRepository,
        dto: &EpisodeEditDto,
        manga_id: i32,
    ) -> ApiResult<()> {
        let episode_label = dto
            .manga_episode
            .as_deref()
            .ok_or_else(|| AppError::business("缺少话数序号"))?;
        let episode_type = dto.episode_type.unwrap_or_default();
        if repo
            .count_episode_by_number(manga_id, episode_label, episode_type)
            .await?
            > 0
        {
            return Err(AppError::business("该漫画单话已存在喵！"));
        }
        if let Some(ref link) = dto.publish_link {
            if !link.is_empty() && repo.count_publish_link(link, None).await? > 0 {
                return Err(AppError::business("发布链接已存在喵"));
            }
        }
        let episode_id = repo.insert(dto).await?;
        repo.insert_detail(episode_id, dto).await?;
        repo.touch_manga_update_time(manga_id).await?;
        Ok(())
    }

    /// 按 ID 查询单条话数详情。
    ///
    /// 返回话数的完整信息，包括主表字段和详情字段。
    /// 如果话数已被软删除或不存在，返回业务错误。
    ///
    /// # Errors
    ///
    /// - `AppError::business("话数不存在喵")` — 指定 ID 的话数不存在
    /// - `AppError::Database` — 数据库查询失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let episode = EpisodeService::get_manga_episode_by_id(&state, 42).await?;
    /// println!("话数名称: {}", episode.manga_episode_name);
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_manga_episode_by_id(state: &AppState, id: i32) -> ApiResult<EpisodeDetailVo> {
        EpisodeRepository::new(state.db.clone())
            .get_by_id(id)
            .await?
            .ok_or_else(|| AppError::business("话数不存在喵"))
    }

    /// 查询漫画最新话。
    ///
    /// 获取指定漫画下序号最大的话数记录。常用于展示连载漫画的
    /// 最近更新情况。
    ///
    /// # Errors
    ///
    /// - `AppError::business("该漫画尚无单话喵")` — 漫画下没有话数记录
    /// - `AppError::Database` — 数据库查询失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let newest = EpisodeService::get_newest_manga_episode_by_id(&state, manga_id).await?;
    /// println!("最新话: {}", newest.manga_episode);
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_newest_manga_episode_by_id(
        state: &AppState,
        manga_id: i32,
    ) -> ApiResult<NewestEpisodeVo> {
        EpisodeRepository::new(state.db.clone())
            .get_newest_by_manga_id(manga_id)
            .await?
            .ok_or_else(|| AppError::business("该漫画尚无单话喵"))
    }

    /// 更新话数信息。
    ///
    /// 根据 DTO 中提供的字段更新话数主表。更新完成后刷新任务追踪
    /// 缓存并触发 RSS 全量刷新。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库更新失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// let dto = EpisodeEditDto {
    ///     id: Some(42),
    ///     manga_episode_name: Some("新标题".into()),
    ///     ..Default::default()
    /// };
    /// EpisodeService::update_manga_episode(&state, dto).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn update_manga_episode(state: &AppState, dto: EpisodeEditDto) -> ApiResult<()> {
        let should_refresh_rss = should_refresh_rss_for_episode_edit(&dto);
        let repo = EpisodeRepository::new(state.db.clone());
        let episode_id = dto.id;
        let mut member_ids = HashSet::new();
        let manga_id_before = if let Some(id) = episode_id {
            for mid in repo.get_post_member_ids(id).await? {
                member_ids.insert(mid);
            }
            repo.get_manga_id_by_episode_id(id).await?
        } else {
            None
        };
        repo.update(&dto).await?;
        if let Some(id) = episode_id {
            for mid in repo.get_post_member_ids(id).await? {
                member_ids.insert(mid);
            }
        }
        if let Some(manga_id) = dto.manga_id.or(manga_id_before) {
            let ids: Vec<i32> = member_ids.into_iter().collect();
            on_episode_mutated(state, manga_id, &ids).await;
        }
        if should_refresh_rss {
            RssService::refresh(state, RssRefreshScope::EpisodePipeline);
        }
        Ok(())
    }

    /// 分页查询已上传稿件列表。
    ///
    /// 在数据库层面执行分页查询和计数，支持按漫画译名和用户名筛选。
    /// 返回标准分页对象 `PageBean<UploadPageVo>`。
    ///
    /// # Errors
    ///
    /// - `AppError::Database` — 数据库查询失败
    ///
    /// # Examples
    ///
    /// ```ignore
    /// // 按译名筛选，查询第 1 页
    /// let page = EpisodeService::get_uploaded_submit(
    ///     &state, 1, 20,
    ///     Some("进击的巨人".into()),
    ///     None,
    /// ).await?;
    /// ```
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_uploaded_submit(
        state: &AppState,
        page: i32,
        page_size: i32,
        manga_tran_name: Option<String>,
        username: Option<String>,
    ) -> ApiResult<PageBean<UploadPageVo>> {
        let (total, rows) = EpisodeRepository::new(state.db.clone())
            .page_uploaded_submit(
                page,
                page_size,
                manga_tran_name.as_deref(),
                username.as_deref(),
            )
            .await?;
        Ok(slice_rows(rows, total))
    }

    /// 藏宝处分页预序列化 JSON（短 TTL 缓存）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_uploaded_submit_json(
        state: &AppState,
        page: i32,
        page_size: i32,
        manga_tran_name: Option<String>,
        username: Option<String>,
    ) -> ApiResult<Arc<Vec<u8>>> {
        let key = uploaded_submit_cache_key(
            state,
            page,
            page_size,
            manga_tran_name.as_deref(),
            username.as_deref(),
        );
        if let Some(json) = get_list_page_json_cached(state, &key).await {
            return Ok(json);
        }
        let page_data =
            Self::get_uploaded_submit(state, page, page_size, manga_tran_name, username).await?;
        set_list_page_json_cached(state, key.clone(), page_data).await;
        get_list_page_json_cached(state, &key)
            .await
            .ok_or_else(|| AppError::business("藏宝处缓存写入失败"))
    }
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_statistics(state: &AppState, start: &str, end: &str) -> ApiResult<Statistics> {
        let start = DateTime::parse_from_rfc3339(start)
            .map_err(|e| AppError::business(format!("时间格式错误: {e}")))?
            .with_timezone(&Utc);
        let end = DateTime::parse_from_rfc3339(end)
            .map_err(|e| AppError::business(format!("时间格式错误: {e}")))?
            .with_timezone(&Utc);
        let repo = EpisodeRepository::new(state.db.clone());
        let stats = repo.get_statistic_count(start, end).await?;
        let result = EpisodeRepository::stats_from_post(&stats);
        // #region agent log
        crate::utils::agent_debug::log(
            "H1",
            "episode_service.rs:get_statistics",
            "statistics_any",
            serde_json::json!({
                "translatorCount": result.translator_count,
                "proofreaderCount": result.proofreader_count
            }),
        );
        // #endregion
        Ok(result)
    }

    /// 预设时间段统计列表（6 项：日/月/年 + 上期对比，UTC 日界）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_statistics_list(state: &AppState) -> ApiResult<Vec<Statistics>> {
        use chrono::{Datelike, TimeZone, Utc};
        let now = Utc::now();
        let today_start = Utc
            .with_ymd_and_hms(now.year(), now.month(), now.day(), 0, 0, 0)
            .single()
            .ok_or_else(|| AppError::business("日期无效"))?;
        let yesterday_start = today_start - chrono::Duration::days(1);
        let first_day_of_month = Utc
            .with_ymd_and_hms(now.year(), now.month(), 1, 0, 0, 0)
            .single()
            .ok_or_else(|| AppError::business("日期无效"))?;
        let first_day_of_last_month = if now.month() == 1 {
            Utc.with_ymd_and_hms(now.year() - 1, 12, 1, 0, 0, 0)
                .single()
                .ok_or_else(|| AppError::business("日期无效"))?
        } else {
            Utc.with_ymd_and_hms(now.year(), now.month() - 1, 1, 0, 0, 0)
                .single()
                .ok_or_else(|| AppError::business("日期无效"))?
        };
        let first_day_of_year = Utc
            .with_ymd_and_hms(now.year(), 1, 1, 0, 0, 0)
            .single()
            .ok_or_else(|| AppError::business("日期无效"))?;
        let first_day_of_last_year = Utc
            .with_ymd_and_hms(now.year() - 1, 1, 1, 0, 0, 0)
            .single()
            .ok_or_else(|| AppError::business("日期无效"))?;

        let ranges = [
            (today_start, now),
            (first_day_of_month, now),
            (first_day_of_year, now),
            (yesterday_start, today_start),
            (first_day_of_last_month, first_day_of_month),
            (first_day_of_last_year, first_day_of_year),
        ];
        let repo = EpisodeRepository::new(state.db.clone());
        let stats = repo.get_statistic_counts_batch(&ranges).await?;
        let list: Vec<Statistics> = stats
            .iter()
            .map(EpisodeRepository::stats_from_post)
            .collect();
        // #region agent log
        crate::utils::agent_debug::log(
            "H1",
            "episode_service.rs:get_statistics_list",
            "statistics_list",
            serde_json::json!({
                "len": list.len(),
                "dayTranslatorCount": list.first().map(|s| s.translator_count)
            }),
        );
        // #endregion
        Ok(list)
    }

    /// 预设统计列表预序列化 JSON（短 TTL 缓存）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_statistics_list_json(state: &AppState) -> ApiResult<std::sync::Arc<Vec<u8>>> {
        if let Some(json) = get_statistics_list_json_cached(state).await {
            return Ok(json);
        }
        let list = Self::get_statistics_list(state).await?;
        set_statistics_list_json_cached(state, list).await;
        get_statistics_list_json_cached(state)
            .await
            .ok_or_else(|| AppError::business("statistics 缓存写入失败"))
    }

    /// 后台预热 statistics 列表 JSON（启动立即执行，之后按间隔刷新）
    pub fn spawn_statistics_warmup(state: AppState) {
        tokio::spawn(async move {
            let interval_secs = std::env::var("STATISTICS_WARMUP_SECS")
                .ok()
                .and_then(|v| v.parse().ok())
                .unwrap_or(30);
            loop {
                if let Err(e) = Self::get_statistics_list_json(&state).await {
                    tracing::warn!("statistics 预热失败: {e:?}");
                }
                tokio::time::sleep(Duration::from_secs(interval_secs)).await;
            }
        });
    }

    /// 组员完成统计
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_member_statistics(
        state: &AppState,
        start: DateTime<Utc>,
        end: DateTime<Utc>,
    ) -> ApiResult<Vec<MemberStatistics>> {
        EpisodeRepository::new(state.db.clone())
            .get_member_statistics(start, end, None)
            .await
    }

    /// 组员完成统计预序列化 JSON（短 TTL 缓存）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn get_member_statistics_json(
        state: &AppState,
        start: DateTime<Utc>,
        end: DateTime<Utc>,
    ) -> ApiResult<std::sync::Arc<Vec<u8>>> {
        let key = member_statistics_cache_key(state, &start.to_rfc3339(), &end.to_rfc3339());
        if let Some(json) = get_member_statistics_json_cached(state, &key).await {
            return Ok(json);
        }
        let list = Self::get_member_statistics(state, start, end).await?;
        set_member_statistics_json_cached(state, key.clone(), list).await;
        get_member_statistics_json_cached(state, &key)
            .await
            .ok_or_else(|| AppError::business("memberStatistics 缓存写入失败"))
    }

    /// 回退流程
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn rollback_episode(
        state: &AppState,
        episode_id: i32,
        workflow_type: &str,
        member_id: Option<i32>,
    ) -> ApiResult<()> {
        let repo = EpisodeRepository::new(state.db.clone());
        let mut member_ids: HashSet<i32> = repo
            .get_post_member_ids(episode_id)
            .await?
            .into_iter()
            .collect();
        if let Some(mid) = member_id {
            member_ids.insert(mid);
        }
        let manga_id = repo.get_manga_id_by_episode_id(episode_id).await?;
        if let Some(oss_id) = repo
            .rollback_episode(episode_id, workflow_type, member_id)
            .await?
        {
            let cfg = (*state.config).clone();
            let _ = OssRepository::new(state.db.clone(), cfg)
                .delete_oss(oss_id)
                .await;
        }
        for mid in repo.get_post_member_ids(episode_id).await? {
            member_ids.insert(mid);
        }
        if let Some(manga_id) = manga_id {
            let ids: Vec<i32> = member_ids.into_iter().collect();
            on_episode_mutated(state, manga_id, &ids).await;
        }
        RssService::refresh(state, RssRefreshScope::EpisodePipeline);
        Ok(())
    }

    /// 上传话数工作文件（对齐 Java MangaFileUtils + 更新 DB 路径）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn upload_manga_file(
        state: &AppState,
        data: Bytes,
        episode_id: i32,
        my_name: &str,
        manga_id: i32,
        original_filename: &str,
    ) -> ApiResult<()> {
        let post_id = legacy_post_id(my_name)
            .ok_or_else(|| AppError::business(format!("当前岗位文件不存在喵：{my_name}")))?;
        if data.len() > 1024 * 1024 {
            return Err(AppError::business("上传的文件不能大于1MB喵！"));
        }
        let filename = sanitize_filename(original_filename);
        let repo = EpisodeRepository::new(state.db.clone());
        if repo.get_by_id(episode_id).await?.is_none() {
            return Err(AppError::business(format!("漫画单话 {episode_id} 不存在")));
        }
        let folder = PathBuf::from(&state.config.folder.base2)
            .join(manga_id.to_string())
            .join(episode_id.to_string())
            .join(post_id.to_string());
        tokio::fs::create_dir_all(&folder)
            .await
            .map_err(|e| AppError::Internal(e.to_string()))?;
        if let Some(old) = repo.get_legacy_file_path(episode_id, my_name).await? {
            let _ = tokio::fs::remove_file(old).await;
        }
        let file_path = folder.join(&filename);
        tokio::fs::write(&file_path, data)
            .await
            .map_err(|e| AppError::business(format!("文件上传失败喵: {e}")))?;
        let stored = file_path.to_string_lossy().replace('\\', "/");
        repo.set_legacy_file_path(episode_id, my_name, &stored)
            .await?;
        on_episode_mutated(state, manga_id, &[]).await;
        Ok(())
    }

    /// 下载话数工作文件（OSS 优先 → legacy 路径 → 规范目录）
    #[tracing::instrument(skip_all, level = "debug")]
    pub async fn download_episode_file(
        state: &AppState,
        req: EpisodeDownloadRequest,
    ) -> ApiResult<(String, Bytes)> {
        let member = MemberRepository::new(state.db.clone())
            .get_by_id(req.member_id)
            .await?;
        if !MemberInternEnum::is_working_member(member.intern) {
            return Err(AppError::download_unauth(
                "目前的职阶无法下载喵！先联系管理员改职阶喵！",
            ));
        }
        if req.my_name.eq_ignore_ascii_case("translator") {
            let post_ids = &member.post_ids;
            let is_letterer = post_ids.contains(&PostEnum::LETTERER);
            let has_translation_access = post_ids.contains(&PostEnum::TRANSLATOR)
                || post_ids.contains(&PostEnum::PROOFREADER)
                || post_ids.contains(&PostEnum::REVIEWER);
            if is_letterer && !has_translation_access {
                return Err(AppError::download_unauth(
                    "不!要!下载翻译稿!嵌字要下载校对稿!如果真的需要下载翻译稿请找Gum979",
                ));
            }
        }

        let repo = EpisodeRepository::new(state.db.clone());
        if repo.get_by_id(req.id).await?.is_none() {
            return Err(AppError::business(format!("漫画单话 {} 不存在", req.id)));
        }

        let oss_repo = OssRepository::new(state.db.clone(), (*state.config).clone());
        if should_download_oss_first(&req.my_name)
            && oss_repo
                .episode_post_oss_id(req.id, &req.my_name)
                .await?
                .is_some()
        {
            return OssService::download_file_proxy(state, req.id, req.my_name.clone()).await;
        }

        let legacy_path = repo.get_legacy_file_path(req.id, &req.my_name).await?;
        if let Some(stored_path) = legacy_path.as_deref() {
            if let Some((filename, bytes)) =
                read_stored_legacy(&state.config.folder.base2, stored_path).await
            {
                return Ok((filename, bytes));
            }
        }

        if let Some((filename, bytes)) = read_canonical_legacy(
            &state.config.folder.base2,
            req.manga_id,
            req.id,
            &req.my_name,
        )
        .await
        {
            return Ok((filename, bytes));
        }

        if legacy_path.is_some() {
            let name = legacy_path
                .as_deref()
                .and_then(|p| Path::new(p).file_name())
                .and_then(|s| s.to_str())
                .unwrap_or("download.dat");
            return Err(AppError::download_failed(format!(
                "文件不存在或无法读取: {name}"
            )));
        }

        OssService::download_file_proxy(state, req.id, req.my_name.clone())
            .await
            .map_err(|e| match e {
                AppError::DownloadUnAuth { .. } => e,
                _ => AppError::download_unauth("文件不存在或无权限喵"),
            })
    }
}

/// 判断岗位下载是否需要优先使用 OSS/COS 文件。
fn should_download_oss_first(post_name: &str) -> bool {
    matches!(
        post_name.to_lowercase().as_str(),
        "provider" | "translator" | "proofreader" | "letterer" | "timer"
    )
}

/// 判断话数编辑是否需要触发 RSS feed 刷新。
///
/// 话号、标题、发布链接、各岗位指派变更均刷新 XML；稳定 GUID 不会重复推送。
fn should_refresh_rss_for_episode_edit(dto: &EpisodeEditDto) -> bool {
    dto.manga_episode
        .as_deref()
        .is_some_and(|s| !s.trim().is_empty())
        || dto
            .manga_episode_name
            .as_deref()
            .is_some_and(|s| !s.trim().is_empty())
        || dto
            .publish_link
            .as_deref()
            .is_some_and(|s| !s.trim().is_empty())
        || dto.provider_id.is_some()
        || dto.translator_id.is_some()
        || dto.proofreader_id.is_some()
        || dto.letterer_id.is_some()
        || dto.timer_id.is_some()
        || dto.reviewer_id.is_some()
}

/// 岗位名 → legacy 目录 postId
fn legacy_post_id(post_name: &str) -> Option<i32> {
    match post_name.to_lowercase().as_str() {
        "translator" => Some(PostEnum::TRANSLATOR),
        "proofreader" => Some(PostEnum::PROOFREADER),
        "timer" => Some(PostEnum::TIMER),
        _ => None,
    }
}

/// 清理上传文件名
fn sanitize_filename(name: &str) -> String {
    let base = Path::new(name)
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("upload.dat");
    if base.is_empty() || base.contains("..") {
        "upload.dat".to_string()
    } else {
        base.to_string()
    }
}

/// 生产环境 legacy 根目录前缀（DB 中存绝对路径，本地 dev 需映射到 folder.base2）
const LEGACY_PROD_PREFIXES: &[&str] = &["/www/wwwroot/data", "/www/wwwroot/tdm/data"];

/// 将 DB 中的 legacy 路径展开为候选本地路径（原路径 + base2 映射）
fn legacy_path_candidates(base2: &str, stored: &str) -> Vec<PathBuf> {
    let mut out = Vec::new();
    let mut push = |p: PathBuf| {
        if !out.iter().any(|x| x == &p) {
            out.push(p);
        }
    };
    push(PathBuf::from(stored));
    for prefix in LEGACY_PROD_PREFIXES {
        if let Some(suffix) = stored.strip_prefix(prefix) {
            push(PathBuf::from(base2).join(suffix.trim_start_matches('/')));
        }
    }
    out
}

/// 将 folder.base2 解析为可读绝对路径
fn resolve_folder_base2(base2: &str) -> PathBuf {
    let path = PathBuf::from(base2);
    if path.is_absolute() {
        path
    } else {
        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(path)
    }
}

/// 按候选路径读取 DB 记录的 legacy 稿件
#[tracing::instrument(skip_all, level = "debug")]
async fn read_stored_legacy(base2: &str, stored: &str) -> Option<(String, Bytes)> {
    let base2 = resolve_folder_base2(base2);
    for path in legacy_path_candidates(&base2.to_string_lossy(), stored) {
        let Ok(bytes) = tokio::fs::read(&path).await else {
            continue;
        };
        let filename = path
            .file_name()
            .and_then(|s| s.to_str())
            .unwrap_or("download.dat")
            .to_string();
        return Some((filename, Bytes::from(bytes)));
    }
    None
}

/// 读取 Java 规范目录下的首个稿件文件
#[tracing::instrument(skip_all, level = "debug")]
async fn read_canonical_legacy(
    base2: &str,
    manga_id: i32,
    episode_id: i32,
    post_name: &str,
) -> Option<(String, Bytes)> {
    let post_id = legacy_post_id(post_name)?;
    let dir = resolve_folder_base2(base2)
        .join(manga_id.to_string())
        .join(episode_id.to_string())
        .join(post_id.to_string());
    let mut entries = tokio::fs::read_dir(&dir).await.ok()?;
    while let Ok(Some(entry)) = entries.next_entry().await {
        let path = entry.path();
        if !path.is_file() {
            continue;
        }
        let bytes = tokio::fs::read(&path).await.ok()?;
        let filename = path.file_name()?.to_str()?.to_string();
        return Some((filename, Bytes::from(bytes)));
    }
    None
}

#[cfg(test)]
mod rss_trigger_tests {
    use super::*;

    /// 构造仅包含 ID 的话数编辑 DTO。
    fn edit_dto() -> EpisodeEditDto {
        EpisodeEditDto {
            id: Some(1),
            manga_id: Some(10),
            manga_episode: None,
            manga_episode_end: None,
            manga_episode_name: None,
            episode_type: None,
            provider_id: None,
            translator_id: None,
            proofreader_id: None,
            letterer_id: None,
            timer_id: None,
            reviewer_id: None,
            publish_link: None,
        }
    }

    /// 岗位改派需刷新 RSS feed 内容（稳定 GUID 不重复推送）。
    #[test]
    fn post_assignment_edit_refreshes_rss() {
        let dto = EpisodeEditDto {
            provider_id: Some(1),
            translator_id: Some(2),
            proofreader_id: Some(3),
            letterer_id: Some(4),
            timer_id: Some(5),
            reviewer_id: Some(6),
            ..edit_dto()
        };

        assert!(should_refresh_rss_for_episode_edit(&dto));
    }

    /// 非岗位字段编辑需要保留 RSS 通知。
    #[test]
    fn non_post_edit_refreshes_rss() {
        let episode = EpisodeEditDto {
            manga_episode: Some("12".into()),
            ..edit_dto()
        };
        let name = EpisodeEditDto {
            manga_episode_name: Some("新标题".into()),
            ..edit_dto()
        };
        let link = EpisodeEditDto {
            publish_link: Some("https://example.com/1".into()),
            ..edit_dto()
        };

        assert!(should_refresh_rss_for_episode_edit(&episode));
        assert!(should_refresh_rss_for_episode_edit(&name));
        assert!(should_refresh_rss_for_episode_edit(&link));
    }

    #[test]
    fn batch_add_rejects_extra_type_and_publish_link() {
        let extra = EpisodeEditDto {
            episode_type: Some(EpisodeType::Extra),
            ..edit_dto()
        };
        let linked = EpisodeEditDto {
            episode_type: Some(EpisodeType::Main),
            publish_link: Some("https://example.com/batch".into()),
            ..edit_dto()
        };
        let empty_link = EpisodeEditDto {
            episode_type: Some(EpisodeType::Main),
            publish_link: Some("  ".into()),
            ..edit_dto()
        };

        assert!(EpisodeService::validate_batch_options(&extra).is_err());
        assert!(EpisodeService::validate_batch_options(&linked).is_err());
        assert!(EpisodeService::validate_batch_options(&empty_link).is_err());
    }
}

#[cfg(test)]
mod download_legacy_tests {
    use super::*;

    /// 校验稿件下载岗位优先使用 OSS/COS。
    #[test]
    fn submitted_posts_prefer_oss_download() {
        assert!(should_download_oss_first("translator"));
        assert!(should_download_oss_first("proofreader"));
        assert!(should_download_oss_first("letterer"));
        assert!(should_download_oss_first("provider"));
        assert!(should_download_oss_first("timer"));
        assert!(!should_download_oss_first("reviewer"));
    }

    /// 校验生产 legacy 路径可映射到 fixture 目录并读取
    #[tokio::test]
    async fn read_remapped_proofreader_file() {
        let base2 = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/legacy/data");
        let stored = "/www/wwwroot/data/33/肚子咕噜咕噜子她和肉肉在同居！04 翻译：Gum979 校对：萝莉控之魂.txt";
        assert!(
            read_stored_legacy(base2.to_string_lossy().as_ref(), stored)
                .await
                .is_some(),
            "remapped legacy file should be readable under tests/fixtures/legacy/data"
        );
    }
}