feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误

refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本

按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。

验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。

docs(cordis): 记录 T1 清理结果与五个复用阻塞点

refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本

按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。

两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
  避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
  副本，待与 infra 初始化一并迁移（已登记在清理计划）。

验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。

chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染

按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。

同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。

AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。

验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。

feat(cordis): server 插件化并改由内核挂载控制面路由

新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。

路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。

已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。

feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由

server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。

验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。

docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口

feat(cordis): agent/relay/flared 落地为内核驱动插件

三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。

入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。

验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。

refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层

backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。

验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。

feat(cordis): 落地 backend/share 共享层与上游同步脚本

跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。

go build 通过，go test ./... exit 0（142 包 ok），前端零改动。

refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核

按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。

行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。

style: 修正模块路径改写导致的 import 分组排序漂移

refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare

对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。

行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。

chore(cordis): 落地改造计划与 schema/路由基线

新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。

docs(cordis): add OpenFlare Cordis 架构改造设计

明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。

backend/plugins/domain/upload/ingest/errors.go

@@ -0,0 +1,15 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"Wavelet/plugins/domain/upload/shared"
+	"errors"
+)
+
+// ErrForbidden indicates the caller is not allowed to mutate the upload record.
+var ErrForbidden = errors.New("upload forbidden")
+
+// ErrStorageReadOnly indicates the storage backend is in migration read-only mode.
+var ErrStorageReadOnly = errors.New(shared.ErrStorageReadOnly)

backend/plugins/domain/upload/ingest/helpers.go

@@ -0,0 +1,217 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/logger"
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/repository"
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	uploadcache "Wavelet/plugins/domain/upload/cache"
+
+	uploadstats "Wavelet/plugins/domain/upload/stats"
+	uploadstorage "Wavelet/plugins/domain/upload/storage"
+)
+
+func normalizeRequest(req *Request) {
+	req.Extension = strings.ToLower(strings.TrimSpace(req.Extension))
+	if req.Extension == "" {
+		req.Extension = "bin"
+	}
+	if req.Type == "" {
+		req.Type = "generic"
+	}
+	if req.Status == "" {
+		req.Status = models.UploadStatusUsed
+	}
+}
+
+func resolveAccessMode(uploadType string, explicit *int) int {
+	if explicit != nil {
+		return *explicit
+	}
+	if uploadType == shared.DefaultPublicUploadType {
+		return 1
+	}
+	return 0
+}
+
+func validateAllowedExtension(ctx context.Context, ext string) error {
+	var val string
+	db := shared.GetDB(ctx)
+	if db != nil {
+		err := db.Table("w_system_configs").Where("key = ?", "upload_allowed_extensions").Pluck("value", &val).Error
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return nil
+			}
+			logger.WarnF(ctx, "failed to query upload_allowed_extensions: %v", err)
+			return nil
+		}
+	}
+	if val == "" {
+		return nil
+	}
+
+	var list []string
+	if err := json.Unmarshal([]byte(val), &list); err == nil {
+		for _, allowedExt := range list {
+			if strings.EqualFold(strings.TrimSpace(allowedExt), ext) {
+				return nil
+			}
+		}
+		return errors.New(shared.ErrUnsupportedFormat)
+	}
+
+	allowedExts := strings.Split(strings.ToLower(val), ",")
+	for _, allowedExt := range allowedExts {
+		if strings.TrimSpace(allowedExt) == ext {
+			return nil
+		}
+	}
+	return errors.New(shared.ErrUnsupportedFormat)
+}
+
+func defaultObjectKey(id uint64, ext string) string {
+	return fmt.Sprintf("uploads/%s/%d.%s", time.Now().Format("2006/01/02"), id, ext)
+}
+
+func buildObjectKey(req Request, id uint64) string {
+	if req.ObjectKeyFn != nil {
+		return req.ObjectKeyFn(id, req.Extension)
+	}
+	return defaultObjectKey(id, req.Extension)
+}
+
+func storeObject(ctx context.Context, objectKey string, reader io.Reader, size int64, mimeType string, meta *models.UploadMetadata) (string, error) {
+	if uploadstorage.ReadOnly(ctx) {
+		return "", ErrStorageReadOnly
+	}
+
+	storageSvc := shared.GetStorage(ctx)
+	if storageSvc == nil {
+		logger.ErrorF(ctx, "初始化活动存储失败: storage service is nil")
+		return "", errors.New(shared.ErrSaveFileFailed)
+	}
+
+	result, err := storageSvc.Put(ctx, objectKey, reader, size, mimeType)
+	if err != nil {
+		logger.ErrorF(ctx, "写入存储失败: %v", err)
+		return "", errors.New(shared.ErrSaveFileFailed)
+	}
+
+	meta.Bucket = result.Bucket
+	return result.Key, nil
+}
+
+func persistUploadRecord(ctx context.Context, upload *models.Upload, objectKey string) error {
+	if err := createUploadWithStats(ctx, upload); err != nil {
+		if storageSvc := shared.GetStorage(ctx); storageSvc != nil {
+			if deleteErr := storageSvc.Delete(ctx, objectKey); deleteErr != nil {
+				logger.WarnF(ctx, "清理未写入数据库的上传对象失败: %v", deleteErr)
+			}
+		}
+		return err
+	}
+	uploadcache.SetUploadMeta(ctx, *upload)
+	return nil
+}
+
+func createUploadWithStats(ctx context.Context, upload *models.Upload) error {
+	db := shared.GetDB(ctx)
+	if db == nil {
+		return errors.New("database service not available")
+	}
+	return db.Transaction(func(tx *gorm.DB) error {
+		if err := repository.CreateUploadTx(tx, upload); err != nil {
+			return err
+		}
+		return uploadstats.ApplyUploadStatsDeltaTx(tx, upload, 1)
+	})
+}
+
+func createDedupRecord(ctx context.Context, existing models.Upload, req Request) (Result, error) {
+	accessMode := resolveAccessMode(req.Type, req.AccessMode)
+	newUpload := models.Upload{
+		ID:         idgen.NextUint64ID(),
+		UserID:     req.UserID,
+		FileName:   req.FileName,
+		FilePath:   existing.FilePath,
+		FileSize:   req.Size,
+		MimeType:   req.MimeType,
+		Extension:  req.Extension,
+		Hash:       req.Hash,
+		Type:       req.Type,
+		Status:     req.Status,
+		AccessMode: accessMode,
+		Metadata:   existing.Metadata,
+	}
+	if err := persistUploadRecord(ctx, &newUpload, existing.FilePath); err != nil {
+		return Result{}, err
+	}
+	logger.InfoF(ctx, "文件触发秒传成功! ID: %d, Path: %s", newUpload.ID, existing.FilePath)
+	return Result{
+		Upload:  newUpload,
+		Created: true,
+		Stored:  false,
+	}, nil
+}
+
+func uploadstorageReadOnly(ctx context.Context) bool {
+	return uploadstorage.ReadOnly(ctx)
+}
+
+func createNewUpload(ctx context.Context, req Request) (Result, error) {
+	if uploadstorageReadOnly(ctx) {
+		return Result{}, ErrStorageReadOnly
+	}
+	if !req.SkipExtensionCheck {
+		if err := validateAllowedExtension(ctx, req.Extension); err != nil {
+			return Result{}, err
+		}
+	}
+
+	id := idgen.NextUint64ID()
+	objectKey := buildObjectKey(req, id)
+	storedKey, err := storeObject(ctx, objectKey, req.Reader, req.Size, req.MimeType, &req.Metadata)
+	if err != nil {
+		return Result{}, err
+	}
+
+	accessMode := resolveAccessMode(req.Type, req.AccessMode)
+	upload := models.Upload{
+		ID:         id,
+		UserID:     req.UserID,
+		FileName:   req.FileName,
+		FilePath:   storedKey,
+		FileSize:   req.Size,
+		MimeType:   req.MimeType,
+		Extension:  req.Extension,
+		Hash:       req.Hash,
+		Type:       req.Type,
+		Status:     req.Status,
+		AccessMode: accessMode,
+		Metadata:   req.Metadata,
+	}
+	if err := persistUploadRecord(ctx, &upload, storedKey); err != nil {
+		return Result{}, err
+	}
+
+	return Result{
+		Upload:  upload,
+		Created: true,
+		Stored:  true,
+	}, nil
+}

backend/plugins/domain/upload/ingest/ingest.go

@@ -0,0 +1,64 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/repository"
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+)
+
+// Ingest stores or resolves an upload using the configured policy and side effects.
+func Ingest(ctx context.Context, req Request) (Result, error) {
+	normalizeRequest(&req)
+	if req.Hash == "" {
+		return Result{}, errors.New("ingest hash is required")
+	}
+	if req.Reader == nil {
+		return Result{}, errors.New("ingest reader is required")
+	}
+	if req.Size < 0 {
+		return Result{}, errors.New("ingest size must be non-negative")
+	}
+
+	switch req.Policy {
+	case PolicyDedupNewRecord, PolicyResolveExisting:
+		return ingestWithHashPolicy(ctx, req)
+	case PolicyCreate:
+		return createNewUpload(ctx, req)
+	default:
+		return Result{}, errors.New("unsupported ingest policy")
+	}
+}
+
+// FindByHash returns a reusable active upload with the same hash and size.
+func FindByHash(ctx context.Context, hash string, size int64) (models.Upload, error) {
+	return repository.FindReusableUploadByHash(ctx, hash, size)
+}
+
+func ingestWithHashPolicy(ctx context.Context, req Request) (Result, error) {
+	existing, err := repository.FindReusableUploadByHash(ctx, req.Hash, req.Size)
+	if err == nil {
+		switch req.Policy {
+		case PolicyResolveExisting:
+			return Result{
+				Upload:   existing,
+				Resolved: true,
+			}, nil
+		case PolicyDedupNewRecord:
+			if uploadstorageReadOnly(ctx) {
+				return Result{}, ErrStorageReadOnly
+			}
+			return createDedupRecord(ctx, existing, req)
+		}
+	}
+	if err != nil && !errors.Is(err, gorm.ErrRecordNotFound) {
+		return Result{}, err
+	}
+
+	return createNewUpload(ctx, req)
+}

backend/plugins/domain/upload/ingest/ingest_test.go

@@ -0,0 +1,358 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/idgen"
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/shared"
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"os"
+	"sync"
+	"testing"
+)
+
+func init() {
+	_ = idgen.Init(1)
+}
+
+type testStorageService struct {
+	mu        sync.RWMutex
+	mockFiles map[string][]byte
+	putCount  *int
+}
+
+func (s *testStorageService) Put(_ context.Context, key string, body io.Reader, _ int64, _ string) (contracts.StoragePutResult, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	data, err := io.ReadAll(body)
+	if err != nil {
+		return contracts.StoragePutResult{}, err
+	}
+	s.mockFiles[key] = data
+	if s.putCount != nil {
+		*s.putCount++
+	}
+	return contracts.StoragePutResult{Key: key, Bucket: "test-bucket"}, nil
+}
+
+func (s *testStorageService) Get(_ context.Context, key string) (*contracts.StorageObject, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	data, ok := s.mockFiles[key]
+	if !ok {
+		return nil, os.ErrNotExist
+	}
+	return &contracts.StorageObject{
+		Key:           key,
+		Body:          io.NopCloser(bytes.NewReader(data)),
+		ContentLength: int64(len(data)),
+		ContentType:   "application/octet-stream",
+	}, nil
+}
+
+func (s *testStorageService) Delete(_ context.Context, key string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.mockFiles, key)
+	return nil
+}
+
+func (s *testStorageService) Ingest(_ context.Context, _ io.Reader, _ contracts.IngestOptions) (*contracts.IngestResult, error) {
+	return nil, nil
+}
+
+func setupMockStorage(t *testing.T, putCount *int) (restore, disable func()) {
+	t.Helper()
+	mockSvc := &testStorageService{
+		mockFiles: make(map[string][]byte),
+		putCount:  putCount,
+	}
+	shared.SetStorageService(mockSvc)
+	return func() {
+			shared.SetStorageService(nil)
+		}, func() {
+			shared.SetStorageService(nil)
+		}
+}
+
+func loadTotalStats(ctx context.Context) (totalStatsSnapshot, error) {
+	var rows []models.UploadStat
+	if err := shared.GetDB(ctx).Where("dimension = ?", models.UploadStatDimensionTotal).Find(&rows).Error; err != nil {
+		return totalStatsSnapshot{}, err
+	}
+	if len(rows) == 0 {
+		return totalStatsSnapshot{}, nil
+	}
+	return totalStatsSnapshot{
+		TotalCount: rows[0].FileCount,
+		TotalSize:  rows[0].FileSize,
+	}, nil
+}
+
+type totalStatsSnapshot struct {
+	TotalCount int64
+	TotalSize  int64
+}
+
+func TestIngestPolicyCreateIncrementsStats(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01")
+	hash := sha256.Sum256(content)
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	result, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "mirror.png",
+		MimeType:  "image/png",
+		Extension: "png",
+		Hash:      hex.EncodeToString(hash[:]),
+		Type:      "pixez_mirror",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("Ingest(PolicyCreate) returned error: %v", err)
+	}
+	if !result.Created || !result.Stored || result.Resolved {
+		t.Fatalf("Ingest(PolicyCreate) = %+v, want Created+Stored without Resolved", result)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 1 || stats.TotalSize != int64(len(content)) {
+		t.Fatalf("loadTotalStats() = count %d size %d, want count 1 size %d", stats.TotalCount, stats.TotalSize, len(content))
+	}
+}
+
+func TestIngestPolicyResolveExistingSkipsStatsOnHit(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("hello duplicate resolution")
+	hash := sha256.Sum256(content)
+	hashStr := hex.EncodeToString(hash[:])
+
+	putCount := 0
+	restoreStorage, disableStorage := setupMockStorage(t, &putCount)
+	defer restoreStorage()
+	defer disableStorage()
+
+	first, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "first.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hashStr,
+		Type:      "attachment",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("first Ingest returned error: %v", err)
+	}
+	if !first.Created || !first.Stored {
+		t.Fatalf("first Ingest = %+v, want Created and Stored true", first)
+	}
+	if putCount != 1 {
+		t.Fatalf("putCount = %d, want 1 after initial store", putCount)
+	}
+
+	second, err := Ingest(ctx, Request{
+		UserID:    1002,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "second.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hashStr,
+		Type:      "attachment",
+		Policy:    PolicyResolveExisting,
+	})
+	if err != nil {
+		t.Fatalf("second Ingest(PolicyResolveExisting) returned error: %v", err)
+	}
+	if second.Created || second.Stored || !second.Resolved {
+		t.Fatalf("second Ingest = %+v, want Created/Stored false and Resolved true", second)
+	}
+	if second.Upload.ID != first.Upload.ID {
+		t.Fatalf("resolved ID = %d, want %d", second.Upload.ID, first.Upload.ID)
+	}
+	if putCount != 1 {
+		t.Fatalf("putCount = %d, want 1 after hit with PolicyResolveExisting", putCount)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats returned error: %v", err)
+	}
+	if stats.TotalCount != 1 || stats.TotalSize != int64(len(content)) {
+		t.Fatalf("stats = %+v, want count 1 size %d", stats, len(content))
+	}
+}
+
+func TestIngestPolicyDedupNewRecordReusesStorage(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("hello dedup reuse")
+	hash := sha256.Sum256(content)
+	hashStr := hex.EncodeToString(hash[:])
+
+	putCount := 0
+	restoreStorage, disableStorage := setupMockStorage(t, &putCount)
+	defer restoreStorage()
+	defer disableStorage()
+
+	first, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "first.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hashStr,
+		Type:      "attachment",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("first Ingest: %v", err)
+	}
+
+	second, err := Ingest(ctx, Request{
+		UserID:    1002,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "second.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hashStr,
+		Type:      "attachment",
+		Policy:    PolicyDedupNewRecord,
+	})
+	if err != nil {
+		t.Fatalf("second Ingest(PolicyDedupNewRecord): %v", err)
+	}
+	if !second.Created || second.Stored || second.Resolved {
+		t.Fatalf("second Ingest = %+v, want Created=true Stored=false Resolved=false", second)
+	}
+	if second.Upload.ID == first.Upload.ID {
+		t.Fatalf("expected new upload record, got matching ID %d", second.Upload.ID)
+	}
+	if second.Upload.FilePath != first.Upload.FilePath {
+		t.Fatalf("expected reused FilePath %q, got %q", first.Upload.FilePath, second.Upload.FilePath)
+	}
+	if putCount != 1 {
+		t.Fatalf("putCount = %d, want 1 after dedup new record", putCount)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats: %v", err)
+	}
+	if stats.TotalCount != 2 || stats.TotalSize != int64(len(content)*2) {
+		t.Fatalf("stats = %+v, want count 2 size %d", stats, len(content)*2)
+	}
+}
+
+func TestRemoveDecrementsStats(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("remove payload")
+	hash := sha256.Sum256(content)
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	ingested, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "to_remove.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hex.EncodeToString(hash[:]),
+		Type:      "generic",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("Ingest: %v", err)
+	}
+
+	removed, err := Remove(ctx, ingested.Upload.ID)
+	if err != nil {
+		t.Fatalf("Remove: %v", err)
+	}
+	if removed.Status != models.UploadStatusDeleted {
+		t.Fatalf("removed status = %q, want deleted", removed.Status)
+	}
+
+	stats, err := loadTotalStats(ctx)
+	if err != nil {
+		t.Fatalf("loadTotalStats: %v", err)
+	}
+	if stats.TotalCount != 0 || stats.TotalSize != 0 {
+		t.Fatalf("stats = %+v, want count 0 size 0 after remove", stats)
+	}
+}
+
+func TestRemoveOwnedEnforcesOwnership(t *testing.T) {
+	_, cleanup := shared.SetupTestEnv(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	content := []byte("owner payload")
+	hash := sha256.Sum256(content)
+
+	restoreStorage, disableStorage := setupMockStorage(t, nil)
+	defer restoreStorage()
+	defer disableStorage()
+
+	ingested, err := Ingest(ctx, Request{
+		UserID:    1001,
+		Reader:    bytes.NewReader(content),
+		Size:      int64(len(content)),
+		FileName:  "owned.txt",
+		MimeType:  "text/plain",
+		Extension: "txt",
+		Hash:      hex.EncodeToString(hash[:]),
+		Type:      "generic",
+		Policy:    PolicyCreate,
+	})
+	if err != nil {
+		t.Fatalf("Ingest: %v", err)
+	}
+
+	if _, err := RemoveOwned(ctx, 2002, ingested.Upload.ID); err == nil {
+		t.Fatal("expected ErrForbidden for non-owner RemoveOwned")
+	}
+
+	removed, err := RemoveOwned(ctx, 1001, ingested.Upload.ID)
+	if err != nil {
+		t.Fatalf("RemoveOwned owner failed: %v", err)
+	}
+	if removed.Status != models.UploadStatusDeleted {
+		t.Fatalf("removed status = %q, want deleted", removed.Status)
+	}
+}

backend/plugins/domain/upload/ingest/remove.go

@@ -0,0 +1,63 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package ingest
+
+import (
+	"Wavelet/plugins/domain/upload/models"
+	"Wavelet/plugins/domain/upload/repository"
+	"Wavelet/plugins/domain/upload/shared"
+	"context"
+
+	"gorm.io/gorm"
+
+	uploadcache "Wavelet/plugins/domain/upload/cache"
+
+	uploadstats "Wavelet/plugins/domain/upload/stats"
+)
+
+// Remove soft-deletes an upload and decrements incremental stats.
+func Remove(ctx context.Context, uploadID uint64) (models.Upload, error) {
+	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
+	if err != nil {
+		return models.Upload{}, err
+	}
+	if err := softDeleteUploadWithStats(ctx, &upload); err != nil {
+		return models.Upload{}, err
+	}
+	upload.Status = models.UploadStatusDeleted
+	return upload, nil
+}
+
+// RemoveOwned soft-deletes an upload owned by userID and decrements incremental stats.
+func RemoveOwned(ctx context.Context, userID, uploadID uint64) (models.Upload, error) {
+	upload, err := repository.GetActiveUploadByID(ctx, uploadID)
+	if err != nil {
+		return models.Upload{}, err
+	}
+	if upload.UserID != userID {
+		return models.Upload{}, ErrForbidden
+	}
+	if err := softDeleteUploadWithStats(ctx, &upload); err != nil {
+		return models.Upload{}, err
+	}
+	upload.Status = models.UploadStatusDeleted
+	return upload, nil
+}
+
+func softDeleteUploadWithStats(ctx context.Context, upload *models.Upload) error {
+	statsSnapshot := *upload
+	db := shared.GetDB(ctx)
+	if db != nil {
+		if err := db.Transaction(func(tx *gorm.DB) error {
+			if err := repository.SoftDeleteUploadTx(tx, upload); err != nil {
+				return err
+			}
+			return uploadstats.ApplyUploadStatsDeltaTx(tx, &statsSnapshot, -1)
+		}); err != nil {
+			return err
+		}
+	}
+	uploadcache.EvictUploadMeta(ctx, upload.ID)
+	return nil
+}

backend/plugins/domain/upload/ingest/types.go

@@ -0,0 +1,59 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package ingest provides the programmatic upload domain service for Wavelet.
+package ingest
+
+import (
+	"Wavelet/plugins/domain/upload/models"
+	"io"
+)
+
+// Policy controls how ingest handles hash collisions and record creation.
+type Policy int
+
+const (
+	// PolicyCreate always stores a new object and creates a new upload record.
+	PolicyCreate Policy = iota
+
+	// PolicyDedupNewRecord reuses an existing object path on hash match but creates a new record and stats delta.
+	PolicyDedupNewRecord
+
+	// PolicyResolveExisting returns an existing upload on hash match without creating a record or stats delta.
+	PolicyResolveExisting
+)
+
+// ObjectKeyFn builds the storage object key for a new upload.
+type ObjectKeyFn func(id uint64, ext string) string
+
+// Request describes a programmatic file ingest operation.
+type Request struct {
+	UserID uint64
+	Type   string
+
+	AccessMode *int
+	Status     models.UploadStatus
+
+	Reader    io.Reader
+	Size      int64
+	FileName  string
+	MimeType  string
+	Extension string
+	Hash      string
+
+	Metadata models.UploadMetadata
+	Policy   Policy
+
+	ObjectKeyFn ObjectKeyFn
+
+	// SkipExtensionCheck bypasses the configured upload extension whitelist.
+	SkipExtensionCheck bool
+}
+
+// Result reports the outcome of an ingest operation.
+type Result struct {
+	Upload   models.Upload
+	Created  bool
+	Stored   bool
+	Resolved bool
+}