feat(note): 手动排序后端——scope 独立表与命令族（REQ-287 地基）

Author: Aparencia

app/src-tauri/src/commands_note_orders.rs

@@ -0,0 +1,69 @@
+//! 笔记手动排序命令（REQ-287，v0.19.7）。
+//!
+//! @ai-context: 命令薄壳——scope 校验（防注入/越界：仅 `g:{数字}`/`none`）、
+//!              量级守卫（≤2000/scope）、保存=整表覆写快照（事务单命令）；
+//!              变更广播 notes 域（列表刷新即时可见）。DB 读写见 db_note_orders.rs。
+//! @ai-context: 排序语义互斥：scope 有手动序=该区手排；清空=回自动。前端树
+//!              视图默认消费，搜索/标签/非默认排序平铺态不应用（交互矩阵锁定）。
+
+use tauri::State;
+
+use crate::commands::AppState;
+use crate::db_note_orders::is_valid_scope;
+
+/// 单 scope 手动序量级上限（防御 IPC/DB 滥用）。
+const SCOPE_IDS_MAX: usize = 2000;
+
+fn validate(scope: &str) -> Result<(), String> {
+    if !is_valid_scope(scope) {
+        return Err("非法的排序范围（应为 g:{组id} 或 none）".to_string());
+    }
+    Ok(())
+}
+
+/// 全量手动序（scope 升序；量小直接返回）。
+#[tauri::command]
+pub fn note_order_list(state: State<'_, AppState>) -> Result<Vec<(String, i64, i64)>, String> {
+    state.db.load_note_orders().map_err(|e| e.to_string())
+}
+
+/// 保存某 scope 完整手动序（整表覆写快照；首启=前端写当前可见序）。
+#[tauri::command]
+pub fn note_order_save(state: State<'_, AppState>, scope: String, note_ids: Vec<i64>) -> Result<(), String> {
+    validate(&scope)?;
+    if note_ids.len() > SCOPE_IDS_MAX {
+        return Err(format!("笔记数超上限（{} > {}）", note_ids.len(), SCOPE_IDS_MAX));
+    }
+    let mut seen = std::collections::HashSet::new();
+    if !note_ids.iter().all(|id| *id > 0 && seen.insert(*id)) {
+        return Err("笔记 id 非法或重复".to_string());
+    }
+    state.db.save_note_order(&scope, &note_ids).map_err(|e| e.to_string())?;
+    // REQ-278：notes 域广播（排序变化 → 列表刷新）
+    crate::notify::emit_changed(&state.app, crate::notify::DataDomain::Notes);
+    Ok(())
+}
+
+/// 清除某 scope 手动序（=回自动排序；幂等）。
+#[tauri::command]
+pub fn note_order_clear(state: State<'_, AppState>, scope: String) -> Result<(), String> {
+    validate(&scope)?;
+    let cleared = state.db.clear_note_order(&scope).map_err(|e| e.to_string())?;
+    if cleared {
+        crate::notify::emit_changed(&state.app, crate::notify::DataDomain::Notes);
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validate;
+
+    #[test]
+    fn validate_accepts_only_scoped_values() {
+        assert!(validate("g:1").is_ok());
+        assert!(validate("none").is_ok());
+        assert!(validate("g:1; DROP TABLE notes").is_err());
+        assert!(validate("").is_err());
+    }
+}

app/src-tauri/src/db_migrations.rs

@@ -312,6 +312,18 @@ CREATE TABLE IF NOT EXISTS contracts (
         );
         ",
     )?;
+    // REQ-287（v0.19.7）：笔记手动排序表（scope=g{id} 组 / none 未分组；独立表
+    // 免改 notes 列与全库行映射涟漪——读写见 db_note_orders.rs）
+    conn.execute_batch(
+        "CREATE TABLE IF NOT EXISTS note_orders (
+            scope TEXT NOT NULL,
+            note_id INTEGER NOT NULL,
+            ord INTEGER NOT NULL,
+            PRIMARY KEY (scope, note_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_note_orders_scope ON note_orders(scope, ord);
+        ",
+    )?;
     // 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 列

app/src-tauri/src/db_note_orders.rs

@@ -0,0 +1,83 @@
+//! 笔记手动排序数据层（REQ-287，v0.19.7）。
+//!
+//! @ai-context: 交互矩阵裁决——组内位置移动=该组切"手动排序"（首次拖拽自动
+//!              快照）；与自动排序（更新时间/固定/创建）互斥，scope 级生效：
+//!              `g:{groupId}`=具体组，`none`=未分组区。独立表免改 notes 列与
+//!              全库行映射（35 表重建涟漪零承担）；排序仅在树视图（无搜索/
+//!              标签/非手动排序筛选）由前端消费（前端先拉全量再按 scope 排）。
+//!              空序=未启用（清表即回自动）；数据量 ≤2000/scope（命令层守卫）。
+
+use crate::db::Db;
+use crate::error::Result;
+
+/// scope 合法性（纯函数可单测）：`g:` + 纯数字，或 `none`。
+pub fn is_valid_scope(scope: &str) -> bool {
+    if scope == "none" {
+        return true;
+    }
+    scope
+        .strip_prefix("g:")
+        .is_some_and(|rest| !rest.is_empty() && rest.chars().all(|c| c.is_ascii_digit()))
+}
+
+impl Db {
+    /// 全量拉取手动序（scope, note_id, ord 升序）——前端树视图消费（量小）。
+    pub fn load_note_orders(&self) -> Result<Vec<(String, i64, i64)>> {
+        self.with_conn(|conn| {
+            let mut stmt =
+                conn.prepare("SELECT scope, note_id, ord FROM note_orders ORDER BY scope, ord")?;
+            let rows = stmt.query_map([], |row| {
+                Ok((row.get::<_, String>(0)?, row.get::<_, i64>(1)?, row.get::<_, i64>(2)?))
+            })?;
+            rows.collect::<rusqlite::Result<Vec<_>>>().map_err(Into::into)
+        })
+    }
+
+    /// 保存某 scope 的完整手动序（事务内先删后插=快照语义；ids 保序编号）。
+    ///
+    /// @ai-context: 首次启用=前端把当前可见序全量写入；后续移动=前端重算后整
+    ///              表覆写（单命令单事务，无逐位移动的复杂度）。with_conn 仅给
+    ///              &Connection 无法开事务（db_fragments 同款：直接锁 + tx）。
+    pub fn save_note_order(&self, scope: &str, note_ids: &[i64]) -> Result<()> {
+        let mut conn = self
+            .conn
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let tx = conn.transaction()?;
+        tx.execute("DELETE FROM note_orders WHERE scope = ?1", [scope])?;
+        {
+            let mut stmt =
+                tx.prepare("INSERT INTO note_orders (scope, note_id, ord) VALUES (?1, ?2, ?3)")?;
+            for (i, id) in note_ids.iter().enumerate() {
+                stmt.execute([scope, &id.to_string(), &(i as i64).to_string()])?;
+            }
+        }
+        tx.commit()?;
+        Ok(())
+    }
+
+    /// 清除某 scope 手动序（=回自动排序；幂等——无记录时零动作）。
+    pub fn clear_note_order(&self, scope: &str) -> Result<bool> {
+        self.with_conn(|conn| {
+            let affected = conn.execute("DELETE FROM note_orders WHERE scope = ?1", [scope])?;
+            Ok(affected > 0)
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::is_valid_scope;
+
+    #[test]
+    fn scope_validation() {
+        assert!(is_valid_scope("g:3"));
+        assert!(is_valid_scope("g:123456789"));
+        assert!(is_valid_scope("none"));
+        assert!(!is_valid_scope(""));
+        assert!(!is_valid_scope("g:"));
+        assert!(!is_valid_scope("G:1"));
+        assert!(!is_valid_scope("g:1a"));
+        assert!(!is_valid_scope("notes"));
+    }
+}

app/src-tauri/src/lib.rs

@@ -56,6 +56,9 @@ mod commands_ai_enrich;
 // 记录/纯逻辑/命令层
 mod note_version;
 mod db_notes_versions;
+// REQ-287（v0.19.7）：笔记手动排序数据层（scope 独立表）
+mod db_note_orders;
+mod commands_note_orders;
 mod db_ai_usage;
 // v0.8.0 F2（2026-08-21）：AI 任务中心持久化——任务记录/结果恢复/保留策略
 mod db_ai_tasks;
@@ -539,6 +542,10 @@ pub fn run() {
             // v0.11.0（REQ-195~198）：笔记组——列表/详情/组内笔记/自建主题组/
             // 重命名/路由改判（修改即记忆）/移动笔记
             commands_groups::list_note_groups,
+            // REQ-287（v0.19.7）：笔记手动排序（scope=g{id}/none）
+            commands_note_orders::note_order_list,
+            commands_note_orders::note_order_save,
+            commands_note_orders::note_order_clear,
             commands_groups::get_note_group,
             commands_groups::list_group_notes,
             commands_groups::create_topic_group,