feat(trash): add bulk purge and automatic retention

internal/api/api.go

@@ -92,6 +92,7 @@ func (s *Server) routes() []route {
 		{"PUT /api/v1/assets/{path...}", authed, s.replaceImage},
 		{"GET /api/v1/raw/{path...}", authed, s.raw},
 		{"GET /api/v1/trash", authed, s.trashList},
+		{"DELETE /api/v1/trash", authed, s.trashClear},
 		{"POST /api/v1/trash/{id}/restore", authed, s.trashRestore},
 		{"DELETE /api/v1/trash/{id}", authed, s.trashPurge},
 		{"GET /api/v1/events", authed, s.events},

internal/api/openapi.json

@@ -349,14 +349,25 @@
             "cookie": []
           }
         ],
-        "description": "按顶层键合并：请求中的键覆盖原值，值为 null 的键被删除。成功后经 WebSocket 推送 settings 事件。",
+        "description": "按顶层键合并：请求中的键覆盖原值，值为 null 的键被删除。成功后经 WebSocket 推送 settings 事件。 trashRetentionDays 为非负安全整数（默认30，0为永不自动删除），null恢复默认。期限适用于已有和新回收站条目，服务启动及每小时按原删除时间永久清理。",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
-                "additionalProperties": true
+                "additionalProperties": true,
+                "properties": {
+                  "trashRetentionDays": {
+                    "type": [
+                      "integer",
+                      "null"
+                    ],
+                    "minimum": 0,
+                    "maximum": 9007199254740991,
+                    "default": 30
+                  }
+                }
               }
             }
           }
@@ -374,7 +385,7 @@
             }
           },
           "400": {
-            "description": "不是 JSON 对象",
+            "description": "不是 JSON 对象，或自动删除期限无效",
             "content": {
               "application/json": {
                 "schema": {
@@ -1008,6 +1019,25 @@
             }
           }
         }
+      },
+      "delete": {
+        "summary": "清空回收站全部条目",
+        "description": "永久删除，不可恢复；结果逐项报告，失败条目保留。只读令牌禁止。",
+        "tags": [
+          "回收站"
+        ],
+        "responses": {
+          "200": {
+            "description": "包含成功及失败的逐项结果",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TrashPurgeResult"
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/trash/{id}/restore": {
@@ -2366,6 +2396,39 @@
             "description": "Emoji 字符或内置线性图标名称，最多64字节"
           }
         }
+      },
+      "TrashPurgeResult": {
+        "type": "object",
+        "required": [
+          "deleted",
+          "failed"
+        ],
+        "properties": {
+          "deleted": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "failed": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "error"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "error": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
       }
     }
   }

internal/api/settings.go

@@ -11,7 +11,7 @@ import (
 	"rawmark/internal/events"
 )
 
-// 应用设置：一份 JSON 对象，全部设备共用。内容由前端定义，服务端只做合并与保存
+// 应用设置：一份 JSON 对象，全部设备共用。内容由前端定义，服务端合并与保存，并校验由服务端执行的清理期限
 const settingsKey = "app.settings"
 
 func (s *Server) readSettings() (map[string]json.RawMessage, error) {
@@ -60,6 +60,10 @@ func (s *Server) patchSettings(w http.ResponseWriter, r *http.Request) {
 			settings[k] = v
 		}
 	}
+	if _, err := trashRetentionDays(settings); err != nil {
+		writeError(w, 400, err.Error())
+		return
+	}
 	merged, err := json.Marshal(settings)
 	if err != nil {
 		internalError(w, r, err)

internal/api/trash.go

@@ -0,0 +1,79 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"time"
+)
+
+// JSON/JavaScript 共同精确表示的非负整数范围；不乘天数，避免期限溢出。
+const maxRetentionDays = 1<<53 - 1
+
+func trashRetentionDays(settings map[string]json.RawMessage) (int64, error) {
+	raw, ok := settings["trashRetentionDays"]
+	if !ok || bytes.Equal(raw, []byte("null")) {
+		return 30, nil
+	}
+	var days int64
+	if err := json.Unmarshal(raw, &days); err != nil || days < 0 || days > maxRetentionDays {
+		return 0, fmt.Errorf("回收站保留天数必须为非负安全整数，0 表示永不自动删除")
+	}
+	return days, nil
+}
+
+func (s *Server) trashClear(w http.ResponseWriter, r *http.Request) {
+	result, err := s.vault.PurgeTrash(0, time.Now())
+	if err != nil {
+		internalError(w, r, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, result)
+}
+
+func (s *Server) cleanupTrash(now time.Time) error {
+	// 与设置写入串行，避免在“永不删除”已保存后使用旧期限开始清理。
+	s.settingsMu.Lock()
+	defer s.settingsMu.Unlock()
+	settings, err := s.readSettings()
+	if err != nil {
+		return err
+	}
+	days, err := trashRetentionDays(settings)
+	if err != nil || days == 0 {
+		return err
+	}
+	result, err := s.vault.PurgeTrash(days, now)
+	if err != nil {
+		return err
+	}
+	if len(result.Failed) > 0 {
+		return fmt.Errorf("回收站清理部分失败: %v", result.Failed)
+	}
+	if len(result.Deleted) > 0 {
+		slog.Info("已清理过期回收站条目", "count", len(result.Deleted))
+	}
+	return nil
+}
+
+// RunTrashCleanup 启动时执行一次，其后每小时执行；不依赖浏览器在线。
+func (s *Server) RunTrashCleanup(ctx context.Context) {
+	ticker := time.NewTicker(time.Hour)
+	defer ticker.Stop()
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+		if err := s.cleanupTrash(time.Now()); err != nil {
+			slog.Error("自动清理回收站失败", "err", err)
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+		}
+	}
+}

internal/api/trash_test.go

@@ -0,0 +1,96 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"rawmark/internal/vault"
+)
+
+func TestTrashRetentionSettingsValidation(t *testing.T) {
+	f := newFixture(t)
+	for _, body := range []string{`{"trashRetentionDays":-1}`, `{"trashRetentionDays":0.5}`, `{"trashRetentionDays":"30"}`, `{"trashRetentionDays":true}`, `{"trashRetentionDays":9007199254740992}`} {
+		if code := f.status(f.admin, "PATCH", "/api/v1/settings", body, nil); code != 400 {
+			t.Fatalf("应拒绝 %s: %d", body, code)
+		}
+	}
+	for _, value := range []string{"30", "0", "9007199254740991", "null"} {
+		if code := f.status(f.admin, "PATCH", "/api/v1/settings", `{"trashRetentionDays":`+value+`}`, nil); code != 200 {
+			t.Fatalf("应接受 %s: %d", value, code)
+		}
+	}
+	for _, raw := range []string{`{}`, `{"trashRetentionDays":null}`} {
+		settings := map[string]json.RawMessage{}
+		if err := json.Unmarshal([]byte(raw), &settings); err != nil {
+			t.Fatal(err)
+		}
+		if days, err := trashRetentionDays(settings); err != nil || days != 30 {
+			t.Fatalf("缺省应30天: %d %v", days, err)
+		}
+	}
+}
+
+func TestTrashClearAuthorization(t *testing.T) {
+	f := newFixture(t)
+	f.write("a.md", "content")
+	decode[vault.TrashItem](t, f.do(f.admin, "DELETE", "/api/v1/files/a.md", "", nil))
+	for _, scope := range []string{"read", "write"} {
+		token := decode[struct{ Token string }](t, f.do(f.admin, "POST", "/api/v1/tokens", `{"name":"test","scope":"`+scope+`"}`, nil)).Token
+		headers := map[string]string{"Authorization": "Bearer " + token}
+		if scope == "read" {
+			if code := f.status(&http.Client{}, "DELETE", "/api/v1/trash", "", headers); code != 403 {
+				t.Fatalf("只读不能清空: %d", code)
+			}
+		} else {
+			result := decode[vault.TrashPurgeResult](t, f.do(&http.Client{}, "DELETE", "/api/v1/trash", "", headers))
+			if len(result.Deleted) != 1 || len(result.Failed) != 0 {
+				t.Fatalf("写令牌清空结果异常: %+v", result)
+			}
+		}
+	}
+}
+
+func TestCleanupUsesSavedRetentionAndPreservesInvalidEntries(t *testing.T) {
+	f := newFixture(t)
+	v, err := vault.Open(f.root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	f.write("old.md", "content")
+	item, err := v.Delete("old.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	metaPath := filepath.Join(f.root, ".rawmark/trash", item.ID, "meta.json")
+	item.DeletedAt = time.Now().Add(-40 * 24 * time.Hour).UnixMilli()
+	meta, _ := json.Marshal(item)
+	if err := os.WriteFile(metaPath, meta, 0600); err != nil {
+		t.Fatal(err)
+	}
+	s := New(v, nil, f.store, f.hub, nil)
+	for _, value := range []string{`{"trashRetentionDays":0}`, `{"trashRetentionDays":-1}`, `{"trashRetentionDays":"broken"}`} {
+		if err := f.store.SetSetting(settingsKey, value); err != nil {
+			t.Fatal(err)
+		}
+		err := s.cleanupTrash(time.Now())
+		if value != `{"trashRetentionDays":0}` && err == nil {
+			t.Fatal("无效配置不可静默降级为默认删除")
+		}
+		if _, err := os.Stat(metaPath); err != nil {
+			t.Fatalf("禁用或无效设置不应删除: %v", err)
+		}
+	}
+	if err := f.store.SetSetting(settingsKey, `{}`); err != nil {
+		t.Fatal(err)
+	}
+	if err := s.cleanupTrash(time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := os.Stat(metaPath); !os.IsNotExist(err) {
+		t.Fatalf("缺省30天应删除旧条目: %v", err)
+	}
+}