//! 摘要裡「哪幾句連到哪一章」(`posts.excerpt_links`,見 migration 0020)。
//!
//! 存的是依語系分開的 JSON:`{"zh-TW": [{"text": "…", "to": "05.4"}], "en": [...]}`。
//! 寫入時逐筆檢查,讀出時只留摘要裡真的找得到的句子——摘要改寫過、句子對不上的連結
//! 直接不出現,不會在前台畫出一條指向空氣的底線。
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::handlers::posts::I18N_LOCALES;
/// 摘要裡的一句話,連到 `to` 那一章(`05` 是第五個大節,`05.4` 是它底下第四個小節)。
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, specta::Type, utoipa::ToSchema)]
pub struct ExcerptLink {
pub text: String,
pub to: String,
}
pub type LinkMap = BTreeMap<String, Vec<ExcerptLink>>;
/// 一個語系最多幾句:摘要只有幾句話,畫太多底線就等於沒有重點。
const MAX_PER_LOCALE: usize = 24;
const MAX_TEXT_CHARS: usize = 120;
/// DB 裡存的 JSON → 對照表。壞掉的 JSON 當作沒有(只有這個模組寫得進去,理論上不會壞)。
pub fn parse_stored(raw: Option<&str>) -> LinkMap {
raw.and_then(|s| serde_json::from_str(s).ok()).unwrap_or_default()
}
/// 公開 API 用:某語系的連結,只留摘要裡找得到的句子。
pub fn for_locale(raw: Option<&str>, locale: &str, excerpt: &str) -> Vec<ExcerptLink> {
let mut map = parse_stored(raw);
map.remove(locale).unwrap_or_default().into_iter().filter(|l| excerpt.contains(&l.text)).collect()
}
/// `to` 只收章節編號:兩位數,或兩位數接「.」再接一到兩位數。
fn valid_target(to: &str) -> bool {
let (major, minor) = match to.split_once('.') {
Some((a, b)) => (a, Some(b)),
None => (to, None),
};
let digits = |s: &str, lens: &[usize]| lens.contains(&s.len()) && s.bytes().all(|c| c.is_ascii_digit());
digits(major, &[2]) && minor.is_none_or(|m| digits(m, &[1, 2]))
}
fn parse_links(locale: &str, v: &Value) -> Result<Vec<ExcerptLink>, String> {
let Value::Array(items) = v else {
return Err(format!("excerpt_links.{locale} 要是陣列"));
};
if items.len() > MAX_PER_LOCALE {
return Err(format!("excerpt_links.{locale} 最多 {MAX_PER_LOCALE} 句"));
}
items
.iter()
.map(|item| {
let link: ExcerptLink = serde_json::from_value(item.clone())
.map_err(|_| format!("excerpt_links.{locale} 的每一筆要是 {{ text, to }}"))?;
let text = link.text.trim().to_string();
if text.is_empty() || text.chars().count() > MAX_TEXT_CHARS {
return Err(format!("excerpt_links.{locale} 的 text 要是 1 到 {MAX_TEXT_CHARS} 字"));
}
if !valid_target(&link.to) {
return Err(format!(
"excerpt_links.{locale} 的 to 要是章節編號(如 05 或 05.4),收到 {}",
link.to
));
}
Ok(ExcerptLink { text, to: link.to })
})
.collect()
}
fn to_stored(map: &LinkMap) -> Option<String> {
if map.is_empty() { None } else { serde_json::to_string(map).ok() }
}
/// 後台寫入:把請求帶的 `excerpt_links` 併進現有的值,回傳要存回 DB 的字串(`None` = 清成 NULL)。
///
/// - `null`:整欄清掉
/// - 物件:有帶到的語系整組換掉,`null` 或 `[]` 刪掉那個語系;沒帶到的語系不動
pub fn merge_input(stored: Option<&str>, input: &Value) -> Result<Option<String>, String> {
let Value::Object(by_locale) = input else {
return if input.is_null() { Ok(None) } else { Err("excerpt_links 要是物件或 null".into()) };
};
let mut map = parse_stored(stored);
for (locale, v) in by_locale {
if !I18N_LOCALES.contains(&locale.as_str()) {
return Err(format!("excerpt_links 不認得的語系:{locale}"));
}
let links = if v.is_null() { Vec::new() } else { parse_links(locale, v)? };
if links.is_empty() {
map.remove(locale);
} else {
map.insert(locale.clone(), links);
}
}
Ok(to_stored(&map))
}
/// 簡體譯文是從繁體轉出來的(`opencc`),連結也跟著轉:轉完在簡體摘要裡找得到的句子才留。
pub fn convert_locale(
stored: Option<&str>,
from: &str,
to: &str,
target_excerpt: Option<&str>,
convert: impl Fn(&str) -> String,
) -> Option<String> {
let mut map = parse_stored(stored);
let converted: Vec<ExcerptLink> = match (map.get(from), target_excerpt) {
(Some(links), Some(excerpt)) => links
.iter()
.map(|l| ExcerptLink { text: convert(&l.text), to: l.to.clone() })
.filter(|l| excerpt.contains(&l.text))
.collect(),
_ => Vec::new(),
};
if converted.is_empty() {
map.remove(to);
} else {
map.insert(to.to_string(), converted);
}
to_stored(&map)
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
#[test]
fn 章節編號只收兩位數大節與一到兩位數小節() {
for ok in ["01", "05", "05.4", "12.10"] {
assert!(valid_target(ok), "{ok}");
}
for bad in ["", "5", "005", "05.", "05.123", "a5", "05.x", "#ar-h05"] {
assert!(!valid_target(bad), "{bad}");
}
}
#[test]
fn 寫入只換有帶到的語系_空陣列刪掉該語系() {
let first = merge_input(None, &json!({ "zh-TW": [{ "text": " 正確率只有 38% ", "to": "05.4" }] }))
.unwrap()
.unwrap();
// 前後空白會修掉
assert_eq!(for_locale(Some(&first), "zh-TW", "…正確率只有 38%…")[0].text, "正確率只有 38%");
let both = merge_input(Some(&first), &json!({ "en": [{ "text": "only 38%", "to": "05" }] })).unwrap();
let map = parse_stored(both.as_deref());
assert_eq!(map.len(), 2, "沒帶到的 zh-TW 要留著");
let back = merge_input(both.as_deref(), &json!({ "en": [] })).unwrap();
assert_eq!(parse_stored(back.as_deref()).keys().collect::<Vec<_>>(), ["zh-TW"]);
let gone = merge_input(back.as_deref(), &json!({ "zh-TW": null })).unwrap();
assert_eq!(gone, None, "最後一個語系刪掉就整欄 NULL");
assert_eq!(merge_input(Some(&first), &Value::Null).unwrap(), None);
}
#[test]
fn 寫入擋掉格式不對的() {
assert!(merge_input(None, &json!("x")).is_err());
assert!(merge_input(None, &json!({ "fr": [] })).is_err());
assert!(merge_input(None, &json!({ "en": { "text": "a", "to": "01" } })).is_err());
assert!(merge_input(None, &json!({ "en": [{ "text": "a" }] })).is_err());
assert!(merge_input(None, &json!({ "en": [{ "text": " ", "to": "01" }] })).is_err());
assert!(merge_input(None, &json!({ "en": [{ "text": "a", "to": "1" }] })).is_err());
let long = "字".repeat(MAX_TEXT_CHARS + 1);
assert!(merge_input(None, &json!({ "en": [{ "text": long, "to": "01" }] })).is_err());
let many: Vec<_> = (0..=MAX_PER_LOCALE).map(|_| json!({ "text": "a", "to": "01" })).collect();
assert!(merge_input(None, &json!({ "en": many })).is_err());
}
#[test]
fn 讀出只留摘要裡找得到的句子() {
let raw = merge_input(
None,
&json!({ "zh-TW": [{ "text": "還在", "to": "01" }, { "text": "改寫掉了", "to": "02" }] }),
)
.unwrap();
let links = for_locale(raw.as_deref(), "zh-TW", "這句還在。");
assert_eq!(links, vec![ExcerptLink { text: "還在".into(), to: "01".into() }]);
assert_eq!(for_locale(raw.as_deref(), "en", "這句還在。"), [], "別的語系沒有就是空的");
assert_eq!(for_locale(Some("not json"), "zh-TW", "x"), []);
}
#[test]
fn 簡體連結從繁體轉出來_轉完對不上的不留() {
let raw = merge_input(
None,
&json!({ "zh-TW": [{ "text": "從零架設", "to": "02" }, { "text": "對不上", "to": "03" }] }),
)
.unwrap();
let conv = |s: &str| s.replace('從', "从").replace('設', "设");
let out = convert_locale(raw.as_deref(), "zh-TW", "zh-CN", Some("文中附上从零架设的步骤"), conv);
let map = parse_stored(out.as_deref());
assert_eq!(map["zh-CN"], vec![ExcerptLink { text: "从零架设".into(), to: "02".into() }]);
assert_eq!(map["zh-TW"].len(), 2, "繁體那組不動");
// 簡體摘要沒了 → 簡體連結一起拿掉
let cleared = convert_locale(out.as_deref(), "zh-TW", "zh-CN", None, conv);
assert!(!parse_stored(cleared.as_deref()).contains_key("zh-CN"));
}
}