post_lifecycle.rs
post_lifecycle.rs
//! 文章的「排程」與「回收桶」(2026-10 後台提案)。
//!
//! posts.status 的四種值:
//!
//! | status | 讀者看得到 | 怎麼離開這個狀態 |
//! |---|---|---|
//! | `draft` | 否 | 編輯器發佈/排程 |
//! | `scheduled` | 否 | 到 `publish_at` 時由 [`spawn`] 的 worker 翻成 `published` |
//! | `published` | 是 | 編輯器改回草稿、丟進回收 |
//! | `trashed` | 否 | 還原(回到 `trashed_from`);放滿 [`TRASH_KEEP_DAYS`] 天後 worker 真的刪掉 |
//!
//! 公開端點一律只讀 `status = 'published'`,所以新加的兩種狀態對讀者天生是看不到的——
//! 不需要在每一條公開查詢上補條件。
//!
//! 時間一律存 UTC 的 `YYYY-MM-DD HH:MM:SS`(SQLite `datetime('now')` 的寫法),
//! 跟 `created_at` 同一種格式,SQL 裡直接用字串比大小。
use std::time::Duration;
use chrono::{DateTime, NaiveDateTime, Utc};
use sqlx::SqlitePool;
use tokio::task::JoinHandle;
use crate::state::AppState;
/// 回收桶裡放多久才真的刪
pub const TRASH_KEEP_DAYS: i64 = 30;
/// worker 多久醒來一次。排程的精度就是這個數字:設 09:00 的文章最晚 09:01 出現
const TICK_SECS_DEFAULT: u64 = 60;
const DB_FORMAT: &str = "%Y-%m-%d %H:%M:%S";
/// 編輯器與 API 可以寫進 status 的值(`trashed` 只能透過刪除/還原進出)
pub const WRITABLE_STATUSES: &[&str] = &["draft", "published", "scheduled"];
/// 把呼叫端給的排程時間正規化成 DB 的 UTC 字串。
///
/// 收兩種寫法:
/// - RFC 3339(`2026-10-28T09:00:00+08:00`、`…Z`)——前端送的是這種,時區照它帶的換算
/// - 不帶時區的 `YYYY-MM-DD HH:MM[:SS]` 或 `YYYY-MM-DDTHH:MM[:SS]`——**當成 UTC**
/// (MCP 與腳本直接寫 DB 格式時用;不帶時區還猜當地時間,就會差八小時)
///
/// 解不出來回 `None`。
pub fn parse_publish_at(raw: &str) -> Option<String> {
let s = raw.trim();
if let Ok(dt) = DateTime::parse_from_rfc3339(s) {
return Some(dt.with_timezone(&Utc).format(DB_FORMAT).to_string());
}
let s = s.replacen('T', " ", 1);
["%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M"]
.iter()
.find_map(|f| NaiveDateTime::parse_from_str(&s, f).ok())
.map(|dt| dt.format(DB_FORMAT).to_string())
}
/// 現在(UTC,DB 格式)
fn now_db() -> String {
Utc::now().format(DB_FORMAT).to_string()
}
/// 建立/更新文章時,body 裡跟發佈時機有關的欄位解讀出來的結果
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Lifecycle {
pub status: String,
/// 只有 `scheduled` 才有值
pub publish_at: Option<String>,
/// 排程時勾了「發佈時推送電子報」
pub newsletter_pending: bool,
}
/// 驗 status 與排程時間。`status` 已經是呼叫端給的字串(缺 key 由呼叫端決定預設)。
///
/// - status 不在 [`WRITABLE_STATUSES`] 裡 → 錯(`trashed` 也是:丟回收要走刪除)
/// - `scheduled` 沒給時間、時間解不出來、或時間已經過了 → 錯。
/// 「過了就直接發佈」看起來體貼,但會讓一篇本來要明天發的文章因為時區寫錯而今天就出去
pub fn lifecycle(status: &str, publish_at: Option<&str>, send_newsletter: bool) -> Result<Lifecycle, String> {
if !WRITABLE_STATUSES.contains(&status) {
return Err(format!("無效的狀態:{status}(只能是 draft、published 或 scheduled)"));
}
if status != "scheduled" {
return Ok(Lifecycle { status: status.to_string(), publish_at: None, newsletter_pending: false });
}
let raw = publish_at.map(str::trim).filter(|s| !s.is_empty()).ok_or("排程發佈需要 publish_at")?;
let at = parse_publish_at(raw).ok_or_else(|| format!("看不懂的排程時間:{raw}"))?;
if at <= now_db() {
return Err(format!("排程時間已經過了:{at}(UTC)"));
}
Ok(Lifecycle { status: "scheduled".into(), publish_at: Some(at), newsletter_pending: send_newsletter })
}
/// 把 [`Lifecycle`] 寫回那篇文章的四個生命週期欄位。status 本身由呼叫端的 INSERT/UPDATE 寫。
/// 不在回收裡的文章,回收那兩欄一律清掉(例如從回收打開來直接改成草稿)。
pub async fn store_lifecycle(pool: &SqlitePool, id: i64, lc: &Lifecycle) -> sqlx::Result<()> {
sqlx::query(
"UPDATE posts SET publish_at = ?, newsletter_pending = ?, trashed_at = NULL, trashed_from = NULL \
WHERE id = ? AND status <> 'trashed'",
)
.bind(&lc.publish_at)
.bind(i64::from(lc.newsletter_pending))
.bind(id)
.execute(pool)
.await?;
Ok(())
}
/// 丟進回收。已經在回收裡的回 `Ok(false)`(不重設 trashed_at,免得延長保留期)。
pub async fn trash(pool: &SqlitePool, id: i64) -> sqlx::Result<bool> {
let r = sqlx::query(
"UPDATE posts SET trashed_from = status, status = 'trashed', trashed_at = datetime('now'), \
publish_at = NULL, newsletter_pending = 0, updated_at = datetime('now') \
WHERE id = ? AND status <> 'trashed'",
)
.bind(id)
.execute(pool)
.await?;
Ok(r.rows_affected() > 0)
}
/// 從回收還原:回到丟之前的狀態。丟之前是 `scheduled` 的回到草稿——
/// 排程時間在丟的時候清掉了,還原時多半也已經過了,讓人重新決定什麼時候發。
pub async fn restore(pool: &SqlitePool, id: i64) -> sqlx::Result<Option<String>> {
let r = sqlx::query(
"UPDATE posts SET status = CASE WHEN trashed_from IN ('published', 'draft') THEN trashed_from ELSE 'draft' END, \
trashed_at = NULL, trashed_from = NULL, updated_at = datetime('now') \
WHERE id = ? AND status = 'trashed'",
)
.bind(id)
.execute(pool)
.await?;
if r.rows_affected() == 0 {
return Ok(None);
}
sqlx::query_scalar::<_, String>("SELECT status FROM posts WHERE id = ?")
.bind(id)
.fetch_optional(pool)
.await
}
/// 真的刪掉一篇(連同標籤關聯)。SQLite 沒有 FK cascade,只刪 posts 會留下孤兒列,
/// 下一篇拿到同一個 id 就會莫名其妙帶著別人的標籤。
pub async fn delete_permanently(pool: &SqlitePool, id: i64) -> sqlx::Result<u64> {
let mut tx = pool.begin().await?;
sqlx::query("DELETE FROM post_tags WHERE post_id = ?").bind(id).execute(&mut *tx).await?;
let r = sqlx::query("DELETE FROM posts WHERE id = ?").bind(id).execute(&mut *tx).await?;
tx.commit().await?;
Ok(r.rows_affected())
}
/// 到期的排程翻成 `published`,回傳 `(id, 要不要寄電子報)`。
///
/// `created_at` 改成預定的時間:文章的日期是「排定發佈的那一刻」,不是寫下草稿的那天
/// (列表與 RSS 都照 created_at 排,不改的話排程的文章會插在很久以前)。
/// 逐篇帶 `AND status = 'scheduled'` 更新,同一篇不會被翻兩次、電子報不會寄兩封。
pub async fn publish_due(pool: &SqlitePool) -> sqlx::Result<Vec<(i64, bool)>> {
let due = sqlx::query_as::<_, (i64, i64)>(
"SELECT id, newsletter_pending FROM posts \
WHERE status = 'scheduled' AND publish_at IS NOT NULL AND publish_at <= datetime('now') \
ORDER BY publish_at",
)
.fetch_all(pool)
.await?;
let mut published = Vec::with_capacity(due.len());
for (id, newsletter) in due {
let r = sqlx::query(
"UPDATE posts SET status = 'published', created_at = publish_at, updated_at = datetime('now'), \
publish_at = NULL, newsletter_pending = 0 WHERE id = ? AND status = 'scheduled'",
)
.bind(id)
.execute(pool)
.await?;
if r.rows_affected() > 0 {
published.push((id, newsletter != 0));
}
}
Ok(published)
}
/// 在回收裡放滿 `keep_days` 天的真的刪掉,回傳刪了幾篇
pub async fn purge_trash(pool: &SqlitePool, keep_days: i64) -> sqlx::Result<u64> {
let ids = sqlx::query_scalar::<_, i64>(
"SELECT id FROM posts WHERE status = 'trashed' AND trashed_at IS NOT NULL \
AND trashed_at <= datetime('now', printf('-%d days', ?))",
)
.bind(keep_days)
.fetch_all(pool)
.await?;
let mut n = 0;
for id in ids {
n += delete_permanently(pool, id).await?;
}
Ok(n)
}
/// worker 的一輪:發佈到期的、寄該寄的電子報、清前端快取、倒回收。回傳發佈了幾篇
pub async fn tick(state: &AppState) -> usize {
let published = match publish_due(&state.pool).await {
Ok(v) => v,
Err(e) => {
tracing::error!("[schedule] 翻排程失敗:{e}");
Vec::new()
}
};
for &(id, newsletter) in &published {
tracing::info!("[schedule] 文章 {id} 到時間了,已發佈");
if newsletter {
match crate::handlers::mailer::dispatch_newsletter(state, id).await {
Ok((sent, failed, _)) => {
tracing::info!("[schedule] 文章 {id} 的電子報:寄出 {sent}、失敗 {failed}");
}
Err(e) => tracing::warn!("[schedule] 文章 {id} 的電子報沒寄出:{e}"),
}
}
}
if !published.is_empty() {
// 不是經過 HTTP 寫入,revalidate 的 middleware 看不到,要自己通知前端清快取
crate::revalidate::fire().await;
}
match purge_trash(&state.pool, TRASH_KEEP_DAYS).await {
Ok(0) => {}
Ok(n) => tracing::info!("[schedule] 回收桶清掉 {n} 篇放滿 {TRASH_KEEP_DAYS} 天的文章"),
Err(e) => tracing::error!("[schedule] 清回收桶失敗:{e}"),
}
published.len()
}
/// 排程 worker。**一律啟動**,不像同步 worker 要 `ENABLE_*` 開關:
/// 排程是編輯器上的功能,關掉的後果是「設好的文章永遠不會出去」,而且沒有任何錯誤訊息。
/// 週期可用 `POST_SCHEDULE_TICK_SECS` 調(測試環境縮短用)。
pub fn spawn(state: AppState) -> JoinHandle<()> {
let period = crate::worker::env_secs("POST_SCHEDULE_TICK_SECS", TICK_SECS_DEFAULT).max(1);
tokio::spawn(async move {
loop {
tick(&state).await;
tokio::time::sleep(Duration::from_secs(period)).await;
}
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn 排程時間_rfc3339_照它帶的時區換成_utc() {
assert_eq!(parse_publish_at("2026-10-28T09:00:00+08:00").as_deref(), Some("2026-10-28 01:00:00"));
assert_eq!(parse_publish_at("2026-10-28T09:00:00Z").as_deref(), Some("2026-10-28 09:00:00"));
assert_eq!(parse_publish_at("2026-10-28T09:00:00.000Z").as_deref(), Some("2026-10-28 09:00:00"));
}
#[test]
fn 排程時間_不帶時區的當成_utc() {
assert_eq!(parse_publish_at("2026-10-28 09:00:00").as_deref(), Some("2026-10-28 09:00:00"));
assert_eq!(parse_publish_at("2026-10-28T09:00").as_deref(), Some("2026-10-28 09:00:00"));
assert_eq!(parse_publish_at(" 2026-10-28 09:00 ").as_deref(), Some("2026-10-28 09:00:00"));
}
#[test]
fn 排程時間_解不出來回_none() {
assert_eq!(parse_publish_at(""), None);
assert_eq!(parse_publish_at("明天早上"), None);
assert_eq!(parse_publish_at("2026-13-01 09:00"), None);
}
#[test]
fn 狀態只收三種_回收要走刪除() {
assert!(lifecycle("draft", None, false).is_ok());
assert!(lifecycle("published", None, true).is_ok());
assert!(lifecycle("trashed", None, false).is_err());
assert!(lifecycle("", None, false).is_err());
assert!(lifecycle("Published", None, false).is_err(), "大小寫要完全一樣,DB 裡比的是字串");
}
#[test]
fn 非排程的狀態不留排程時間也不留電子報旗標() {
let lc = lifecycle("published", Some("2099-01-01 00:00"), true).unwrap();
assert_eq!(lc.publish_at, None);
assert!(!lc.newsletter_pending, "直接發佈的電子報當場就寄,不留到 worker");
}
#[test]
fn 排程要有未來的時間() {
assert!(lifecycle("scheduled", None, false).unwrap_err().contains("publish_at"));
assert!(lifecycle("scheduled", Some(" "), false).is_err());
assert!(lifecycle("scheduled", Some("明天"), false).unwrap_err().contains("看不懂"));
assert!(lifecycle("scheduled", Some("2000-01-01 00:00"), false).unwrap_err().contains("已經過了"));
let lc = lifecycle("scheduled", Some("2099-01-01T08:00:00+08:00"), true).unwrap();
assert_eq!(lc.publish_at.as_deref(), Some("2099-01-01 00:00:00"));
assert!(lc.newsletter_pending);
}
}