feat(notes): REQ-315 组置顶与手动排序后端（pin 列+note_group_orders 分区快照）

Author: Aparencia

app/src-tauri/src/commands_group_orders.rs

@@ -0,0 +1,116 @@
+//! 组排序/置顶命令（REQ-315，v0.20.11 批 6）。
+//!
+//! @ai-context: 命令薄壳——kind 白名单（防任意分区字符串）/量级守卫/归属校验
+//!              （防陈旧序污染分区，note_orders 同款三防）；保存=分区快照覆写
+//!              （空 ids=分区回自动）；变更广播 NoteGroups 域（组列表即时可见）。
+//!              DB 读写见 db_note_group_orders.rs；渲染排序=前端纯函数（组侧栏/
+//!              树组头/过滤平铺共用，utils/groupOrder.ts），本层不做排序。
+
+use tauri::State;
+
+use crate::commands::AppState;
+use crate::db_note_group_orders::is_valid_group_order_kind;
+
+/// 单分区手动序量级上限（防御 IPC/DB 滥用；组数远小于笔记数，上限对齐 note_orders）。
+const GROUP_IDS_MAX: usize = 2000;
+
+fn validate_kind(kind: &str) -> Result<(), String> {
+    if is_valid_group_order_kind(kind) {
+        Ok(())
+    } else {
+        Err(format!("非法的手动排序分区: {}（支持: course/topic/standalone/feed）", kind))
+    }
+}
+
+/// 组置顶/取消置顶（pin=1/0——数据字段沿 notes.pin，措辞统一为「置顶」）。
+#[tauri::command]
+pub fn update_note_group_pin(
+    state: State<'_, AppState>,
+    id: i64,
+    pin: i64,
+) -> Result<bool, String> {
+    if id <= 0 {
+        return Err("无效的组 id".to_string());
+    }
+    if pin != 0 && pin != 1 {
+        return Err("置顶参数只能为 0（取消）或 1（置顶）".to_string());
+    }
+    let ok = state
+        .db
+        .update_note_group_pin(id, pin)
+        .map_err(|e| e.to_string())?;
+    if ok {
+        crate::notify::emit_changed(&state.app, crate::notify::DataDomain::NoteGroups);
+    }
+    Ok(ok)
+}
+
+/// 全量组手动序（(group_id, seq)；量小整拉——前端按分区过滤消费）。
+#[tauri::command]
+pub fn note_group_order_list(state: State<'_, AppState>) -> Result<Vec<(i64, i64)>, String> {
+    state.db.load_group_orders().map_err(|e| e.to_string())
+}
+
+/// 保存某 kind 分区完整手动序（分区快照先删后插单事务；空 group_ids=分区回自动）。
+#[tauri::command]
+pub fn note_group_order_save(
+    state: State<'_, AppState>,
+    kind: String,
+    group_ids: Vec<i64>,
+) -> Result<(), String> {
+    validate_kind(&kind)?;
+    if group_ids.len() > GROUP_IDS_MAX {
+        return Err(format!("组数超上限（{} > {}）", group_ids.len(), GROUP_IDS_MAX));
+    }
+    let mut seen = std::collections::HashSet::new();
+    if !group_ids.iter().all(|id| *id > 0 && seen.insert(*id)) {
+        return Err("组 id 非法或重复".to_string());
+    }
+    // 归属校验：全部 id 必须当前属于该 kind 且未置顶（陈旧/置顶序整体拒绝——
+    // 置顶组由 pin 列置顶区表达，不占手动序位）
+    let ok = state
+        .db
+        .verify_group_order_membership(&kind, &group_ids)
+        .map_err(|e| e.to_string())?;
+    if !ok {
+        return Err("部分组不属于该分区或已置顶——请刷新后再排序".to_string());
+    }
+    state
+        .db
+        .save_group_order(&kind, &group_ids)
+        .map_err(|e| e.to_string())?;
+    crate::notify::emit_changed(&state.app, crate::notify::DataDomain::NoteGroups);
+    Ok(())
+}
+
+/// 清除单组手动位（=该组回自动区；幂等——无行零动作不广播）。
+#[tauri::command]
+pub fn note_group_order_clear(state: State<'_, AppState>, group_id: i64) -> Result<(), String> {
+    if group_id <= 0 {
+        return Err("无效的组 id".to_string());
+    }
+    let cleared = state
+        .db
+        .clear_group_order(group_id)
+        .map_err(|e| e.to_string())?;
+    if cleared {
+        crate::notify::emit_changed(&state.app, crate::notify::DataDomain::NoteGroups);
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validate_kind;
+
+    #[test]
+    fn kind_whitelist_enforced() {
+        assert!(validate_kind("course").is_ok());
+        assert!(validate_kind("topic").is_ok());
+        assert!(validate_kind("standalone").is_ok());
+        assert!(validate_kind("feed").is_ok());
+        assert!(validate_kind("").is_err());
+        assert!(validate_kind("note; DROP TABLE note_groups").is_err());
+        assert!(validate_kind("Course").is_err());
+    }
+}

app/src-tauri/src/db_migrations.rs

@@ -324,6 +324,17 @@ CREATE TABLE IF NOT EXISTS contracts (
         CREATE INDEX IF NOT EXISTS idx_note_orders_scope ON note_orders(scope, ord);
         ",
     )?;
+    // REQ-315（v0.20.11 批 6）：组手动排序表——group_id 主键（组 1:1），seq=kind
+    // 分区内相对序号（渲染时按 kind 分区消费）。与 note_orders 无 FK 的差异：
+    // 笔记会跨 scope 迁移故需 purge 防 id 复活旧序位，组即排序 scope 本体、删除即
+    // 消亡无复用路径——FK ON DELETE CASCADE 即完整清理（读写在 db_note_group_orders.rs）
+    conn.execute_batch(
+        "CREATE TABLE IF NOT EXISTS note_group_orders (
+            group_id INTEGER PRIMARY KEY REFERENCES note_groups(id) ON DELETE CASCADE,
+            seq INTEGER NOT NULL
+        );
+        ",
+    )?;
     // v0.5.0 M1（REQ-043）：旧库迁移——sessions 表补 profile 列（兼容既有数据库）
     ensure_column(conn, "sessions", "profile", "ALTER TABLE sessions ADD COLUMN profile TEXT")?;
     // v0.11.7（图文会话，ADR-020）：旧库迁移——sessions 表补 kind 列
@@ -464,6 +475,14 @@ CREATE TABLE IF NOT EXISTS contracts (
         "color",
         "ALTER TABLE note_groups ADD COLUMN color TEXT",
     )?;
+    // REQ-315（v0.20.11 批 6）：旧库迁移——note_groups 补 pin 列
+    // （0=未置顶/1=置顶；NOT NULL DEFAULT 0——置顶区排序第一条件，老数据零迁移）
+    ensure_column(
+        conn,
+        "note_groups",
+        "pin",
+        "ALTER TABLE note_groups ADD COLUMN pin INTEGER NOT NULL DEFAULT 0",
+    )?;
     // v0.14.1：旧库迁移——knowledge_canvas_states 补画布偏好三列
     // （CREATE TABLE 只对新库生效；旧行升级后落 DEFAULT——行为与默认设置一致，
     //   零破坏纪律：不猜用户偏好，首开即默认 smoothstep + radial）

app/src-tauri/src/db_note_group_orders.rs

@@ -0,0 +1,128 @@
+//! 组排序与置顶数据层（REQ-315，v0.20.11 批 6）。
+//!
+//! @ai-context: 交互矩阵扩展自 REQ-287 笔记手动序（note_orders）：组列表按 kind
+//!              分区——分区渲染序 = 置顶区（pin=1，区内按 updated_at 降序）→
+//!              手动区（本表 seq 升序）→ 自动区（其余按 updated_at 降序）。
+//!              save=分区快照（先删后插单事务；空 ids=分区整体回自动）；clear=
+//!              单组回自动（稀疏行合法——渲染规则②③支持缺行成员回落自动区）。
+//!              置顶组不参与手动序写入（save 校验拒绝），存量行保留——取消置顶
+//!              即回原手动位（notes.pin 同语义，批 6 措辞统一为「置顶」）。
+//! @ai-context: FK ON DELETE CASCADE 随组删除清行（与 note_orders 无 FK 的差异：
+//!              笔记移组跨 scope 复用 id 需 purge 防"移回复活旧序位"，组即排序
+//!              scope 本体、删除即消亡无复用路径）。kind 变更边界（改判换分区）
+//!              在 db_note_groups::override_group_route 同事务清行。
+//! @ai-context: pin 列存 note_groups（与 notes.pin 对齐），但更新方法落本模块——
+//!              置顶=排序域第一区操作，与手动序同域内聚（db_note_groups.rs 已
+//!              接近 300 行上限，AGENTS §3 单文件约束）。
+
+use rusqlite::params;
+
+use crate::db::{unix_seconds, Db};
+use crate::error::Result;
+
+/// 手动序 kind 分区白名单（对齐渲染分区 course/topic/standalone/feed——非法值
+/// 拒绝防任意入库；feed 分区当前无自然成员但保留合法位防前端枚举扩展炸命令）。
+pub fn is_valid_group_order_kind(kind: &str) -> bool {
+    matches!(kind, "course" | "topic" | "standalone" | "feed")
+}
+
+impl Db {
+    /// 组置顶状态（REQ-315；pin=1 置顶 / 0 取消——排序纯函数置顶区消费）。
+    ///
+    /// @ai-context: updated_at 同步刷新：置顶动作把它推为置顶区内最新
+    ///              （置顶区内部按更新时间降序，与取消置顶回落自动区的口径一致）。
+    pub fn update_note_group_pin(&self, id: i64, pin: i64) -> Result<bool> {
+        self.with_conn(|conn| {
+            let affected = conn.execute(
+                "UPDATE note_groups SET pin = ?1, updated_at = ?2 WHERE id = ?3",
+                params![pin, unix_seconds(), id],
+            )?;
+            Ok(affected > 0)
+        })
+    }
+
+    /// 全量组手动序（group_id, seq）——侧栏/树头消费（量小整拉，渲染排序在前端
+    /// 纯函数，本层不替前端预排；seq 并列按 id 决胜保证确定序——测试可断言）。
+    pub fn load_group_orders(&self) -> Result<Vec<(i64, i64)>> {
+        self.with_conn(|conn| {
+            let mut stmt = conn
+                .prepare("SELECT group_id, seq FROM note_group_orders ORDER BY seq, group_id")?;
+            let rows = stmt.query_map([], |row| {
+                Ok((row.get::<_, i64>(0)?, row.get::<_, i64>(1)?))
+            })?;
+            rows.collect::<rusqlite::Result<Vec<_>>>().map_err(Into::into)
+        })
+    }
+
+    /// 保存某 kind 分区完整手动序（快照：先删该分区全部行再按序编号插入）。
+    ///
+    /// @ai-context: 删除域=kind 全分区而非仅入参 ids——组改判/置顶遗留的陈旧行
+    ///              一并清（分区渲染只认本表 seq，不留双轨）；空 ids=分区整体
+    ///              回自动排序（前端「手排 ↺」复位语义）。
+    pub fn save_group_order(&self, kind: &str, group_ids: &[i64]) -> Result<()> {
+        // 事务需要 &mut Connection（with_conn 只给 &Connection——同 delete_group）
+        let mut conn = self
+            .conn
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let tx = conn.transaction()?;
+        tx.execute(
+            "DELETE FROM note_group_orders WHERE group_id IN
+             (SELECT id FROM note_groups WHERE kind = ?1)",
+            params![kind],
+        )?;
+        {
+            let mut stmt = tx.prepare("INSERT INTO note_group_orders (group_id, seq) VALUES (?1, ?2)")?;
+            for (i, id) in group_ids.iter().enumerate() {
+                stmt.execute(params![*id, i as i64])?;
+            }
+        }
+        tx.commit()?;
+        Ok(())
+    }
+
+    /// 清除单组手动位（=该组回自动区；幂等——无行零动作返回 false 不广播）。
+    pub fn clear_group_order(&self, group_id: i64) -> Result<bool> {
+        self.with_conn(|conn| {
+            let affected =
+                conn.execute("DELETE FROM note_group_orders WHERE group_id = ?1", params![group_id])?;
+            Ok(affected > 0)
+        })
+    }
+
+    /// 归属校验（save 守卫）：每个 id 必须当前属于该 kind 分区且未置顶——陈旧
+    /// 序/置顶组误写整体拒绝（前端 bug/并发改判后的分区污染不落库）。
+    pub fn verify_group_order_membership(&self, kind: &str, group_ids: &[i64]) -> Result<bool> {
+        self.with_conn(|conn| {
+            if group_ids.is_empty() {
+                return Ok(true);
+            }
+            let mut sql = String::from(
+                "SELECT id FROM note_groups WHERE kind = ?1 AND pin = 0 AND id IN (",
+            );
+            for (i, _) in group_ids.iter().enumerate() {
+                if i > 0 {
+                    sql.push(',');
+                }
+                sql.push_str(&format!("?{}", i + 2));
+            }
+            sql.push(')');
+            let mut stmt = conn.prepare(&sql)?;
+            let mut ps: Vec<&dyn rusqlite::ToSql> = vec![&kind];
+            for id in group_ids {
+                ps.push(id);
+            }
+            let rows = stmt.query_map(rusqlite::params_from_iter(ps), |row| {
+                row.get::<_, i64>(0)
+            })?;
+            let found: Vec<i64> = rows.collect::<rusqlite::Result<Vec<_>>>()?;
+            let want: std::collections::HashSet<i64> = group_ids.iter().copied().collect();
+            let got: std::collections::HashSet<i64> = found.into_iter().collect();
+            Ok(got == want)
+        })
+    }
+}
+
+#[cfg(test)]
+#[path = "db_note_group_orders_tests.rs"]
+mod tests;