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/shared/constants.go

@@ -0,0 +1,25 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package shared
+
+// Upload size, path, media quality, and cache constants shared across subpackages.
+const (
+	MaxUploadSize           = 32 * 1024 * 1024 // 32MB
+	DetectContentBytes      = 512              // http.DetectContentType 需要的最小字节数
+	UploadDirPerm           = 0o755            // 上传目录权限
+	UploadFilePerm          = 0o644            // 上传文件权限
+	ImageQualityLow         = "low"
+	ImageQualityMedium      = "medium"
+	ImageQualityHigh        = "high"
+	ImageQualityOrigin      = "origin"
+	DefaultPublicUploadType = "avatar"
+	FileStatsTrendDays      = 7
+	MaxS3KeyLength          = 1024
+	AccessCacheTTL          = 5 // seconds; multiplied by time.Second at use site
+
+	UploadStatDimensionTotal    = "total"
+	UploadStatDimensionType     = "type"
+	UploadStatDimensionCategory = "category"
+	UploadStatDimensionTrend    = "trend"
+)

backend/plugins/domain/upload/shared/context_services.go

@@ -0,0 +1,130 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package shared
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"sync"
+
+	"gorm.io/gorm"
+)
+
+var (
+	svcMu      sync.RWMutex
+	dbSvc      contracts.DBService
+	cacheSvc   contracts.CacheService
+	storageSvc contracts.StorageService
+	taskSvc    contracts.TaskService
+	authSvc    contracts.AuthService
+)
+
+// SetDBService configures the DBService.
+func SetDBService(s contracts.DBService) {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	dbSvc = s
+}
+
+// SetCacheService configures the CacheService.
+func SetCacheService(s contracts.CacheService) {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	cacheSvc = s
+}
+
+// SetStorageService configures the StorageService.
+func SetStorageService(s contracts.StorageService) {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	storageSvc = s
+}
+
+// SetTaskService configures the TaskService.
+func SetTaskService(s contracts.TaskService) {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	taskSvc = s
+}
+
+// SetAuthService configures the AuthService.
+func SetAuthService(s contracts.AuthService) {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	authSvc = s
+}
+
+// ResetServices clears all injected services.
+func ResetServices() {
+	svcMu.Lock()
+	defer svcMu.Unlock()
+	dbSvc = nil
+	cacheSvc = nil
+	storageSvc = nil
+	taskSvc = nil
+	authSvc = nil
+}
+
+// GetDB resolves the GORM DB instance.
+func GetDB(ctx context.Context) *gorm.DB {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.DBService](c); err == nil && s != nil {
+			return s.DB(ctx)
+		}
+	}
+	svcMu.RLock()
+	s := dbSvc
+	svcMu.RUnlock()
+	if s != nil {
+		return s.DB(ctx)
+	}
+	return nil
+}
+
+// GetCache resolves the CacheService instance.
+func GetCache(ctx context.Context) contracts.CacheService {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.CacheService](c); err == nil && s != nil {
+			return s
+		}
+	}
+	svcMu.RLock()
+	s := cacheSvc
+	svcMu.RUnlock()
+	return s
+}
+
+// GetStorage resolves the StorageService instance.
+func GetStorage(ctx context.Context) contracts.StorageService {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.StorageService](c); err == nil && s != nil {
+			return s
+		}
+	}
+	svcMu.RLock()
+	s := storageSvc
+	svcMu.RUnlock()
+	return s
+}
+
+// GetTaskService resolves the TaskService instance.
+func GetTaskService() contracts.TaskService {
+	svcMu.RLock()
+	defer svcMu.RUnlock()
+	return taskSvc
+}
+
+// GetAuthService resolves the AuthService instance.
+func GetAuthService(ctx context.Context) contracts.AuthService {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.AuthService](c); err == nil && s != nil {
+			return s
+		}
+	}
+	svcMu.RLock()
+	s := authSvc
+	svcMu.RUnlock()
+	return s
+}

backend/plugins/domain/upload/shared/errs.go

@@ -0,0 +1,48 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package shared holds upload error and configuration constants shared across subpackages.
+package shared
+
+// 文件管理常量
+const (
+	ErrNoFileSelected                  = "请选择要上传的文件"
+	ErrUnsupportedFormat               = "只支持 JPG、PNG、WEBP 格式的图片"
+	ErrProcessFileFailed               = "处理文件失败"
+	ErrSaveFileFailed                  = "保存文件失败"
+	ErrOpenFileFailed                  = "打开文件失败"
+	ErrSaveUploadRecordFailed          = "保存上传记录失败"
+	ErrGenericFileTooLarge             = "文件大小不能超过 32MB"
+	ErrFileContentExtensionMismatch    = "文件内容与扩展名不匹配，可能包含安全风险"
+	ErrFileValidationFailed            = "文件校验失败"
+	ErrInvalidMetadataJSON             = "元数据 JSON 格式不合法"
+	ErrInvalidFileID                   = "无效的文件 ID"
+	ErrQueryUploadRecordFailed         = "查询文件记录失败"
+	ErrInvalidBatchDownloadRequest     = "参数绑定失败，请传入有效的文件 ID 数组"
+	ErrInvalidIDValueFormat            = "无效的 ID 值: %s"
+	ErrRetrieveUploadRecordsFailed     = "检索文件记录失败"
+	ErrNoValidFilesForArchive          = "没有找到任何有效的文件记录进行打包"
+	ErrInvalidParams                   = "参数错误"
+	ErrQueryFileCountFailed            = "查询文件数量失败"
+	ErrQueryFileListFailed             = "查询文件列表失败"
+	ErrDeleteFileFailed                = "删除文件失败"
+	ErrStorageReadOnly                 = "存储迁移维护中，当前仅允许读取文件"
+	ErrS3KeyRequired                   = "s3 key must not be empty"
+	ErrS3KeyTooLongFormat              = "s3 key exceeds maximum length of %d"
+	ErrS3KeyStartsWithSlash            = "s3 key must not start with /"
+	ErrS3KeyContainsNullBytes          = "s3 key must not contain null bytes"
+	ErrQueryUnusedUploadsFailed        = "查询未使用的上传文件失败: %w"
+	ErrImageCacheWarmupPayloadRequired = "图片缓存预热参数不能为空"
+	ErrInvalidImageCacheWarmupPayload  = "图片缓存预热参数格式无效: %w"
+	ErrInvalidImageCacheWarmupQuality  = "图片质量仅支持 low、medium、high"
+	ErrParseImageCacheWarmupPayload    = "解析图片缓存预热参数失败: %w"
+	ErrQueryImagesForCacheWarmup       = "查询待预热图片失败: %w"
+	ErrQueryTypeListFailed             = "查询文件类型列表失败"
+	ErrUpdateFileFailed                = "更新文件失败"
+	ErrUnauthorized                    = "未登录"
+	ErrFileRecordNotFound              = "文件记录未找到"
+	ErrFileNotFound                    = "文件未找到"
+	ErrOperationForbidden              = "无权操作"
+	ErrInvalidAccessModeParam          = "无效的 access_mode 参数"
+	ErrInternalServerError             = "服务器内部错误"
+)

backend/plugins/domain/upload/shared/test_helpers.go

@@ -0,0 +1,299 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package shared
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/testhelper"
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+// MockDBService is a mock implementation of contracts.DBService for unit testing.
+type MockDBService struct {
+	DBInstance *gorm.DB
+}
+
+// GORM returns the underlying GORM instance.
+func (m *MockDBService) GORM() *gorm.DB {
+	return m.DBInstance
+}
+
+// DB returns the GORM instance bound to context.
+func (m *MockDBService) DB(ctx context.Context) *gorm.DB {
+	return m.DBInstance.WithContext(ctx)
+}
+
+// Named returns the named GORM instance.
+func (m *MockDBService) Named(_ string) *gorm.DB {
+	return m.DBInstance
+}
+
+// MockCacheService is an in-memory mock implementation of contracts.CacheService for unit testing.
+type MockCacheService struct {
+	mu   sync.RWMutex
+	data map[string][]byte
+}
+
+// NewMockCacheService creates a new MockCacheService.
+func NewMockCacheService() *MockCacheService {
+	return &MockCacheService{
+		data: make(map[string][]byte),
+	}
+}
+
+// Get retrieves a cached value.
+func (m *MockCacheService) Get(_ context.Context, key string, val any) error {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	b, ok := m.data[key]
+	if !ok {
+		return contracts.ErrCacheMiss
+	}
+	return json.Unmarshal(b, val)
+}
+
+// Set stores a key-value pair in cache.
+func (m *MockCacheService) Set(_ context.Context, key string, val any, _ time.Duration) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	b, err := json.Marshal(val)
+	if err != nil {
+		return err
+	}
+	m.data[key] = b
+	return nil
+}
+
+// Delete removes a key from cache.
+func (m *MockCacheService) Delete(_ context.Context, key string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.data, key)
+	return nil
+}
+
+// GetOrSet retrieves or populates a cache entry.
+func (m *MockCacheService) GetOrSet(ctx context.Context, key string, target any, ttl time.Duration, loader func() (any, error)) error {
+	err := m.Get(ctx, key, target)
+	if err == nil {
+		return nil
+	}
+	val, err := loader()
+	if err != nil {
+		return err
+	}
+	return m.Set(ctx, key, val, ttl)
+}
+
+// Invalidate invalidates a cache tag or prefix.
+func (m *MockCacheService) Invalidate(_ context.Context, _ string) error {
+	return nil
+}
+
+// MockStorageService is an in-memory mock implementation of contracts.StorageService for unit testing.
+type MockStorageService struct {
+	mu      sync.RWMutex
+	objects map[string][]byte
+}
+
+// NewMockStorageService creates a new MockStorageService.
+func NewMockStorageService() *MockStorageService {
+	return &MockStorageService{
+		objects: make(map[string][]byte),
+	}
+}
+
+// Put uploads an object into mock storage.
+func (m *MockStorageService) Put(_ context.Context, key string, body io.Reader, _ int64, _ string) (contracts.StoragePutResult, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	data, err := io.ReadAll(body)
+	if err != nil {
+		return contracts.StoragePutResult{}, err
+	}
+	m.objects[key] = data
+	return contracts.StoragePutResult{Key: key, Bucket: "test-bucket"}, nil
+}
+
+// PutRaw seeds an object directly into the in-memory store (test helper, no I/O).
+func (m *MockStorageService) PutRaw(key string, data []byte) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.objects[key] = data
+}
+
+// Get retrieves an object from mock storage.
+func (m *MockStorageService) Get(_ context.Context, key string) (*contracts.StorageObject, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	data, ok := m.objects[key]
+	if ok {
+		return &contracts.StorageObject{
+			Key:           key,
+			Body:          io.NopCloser(bytes.NewReader(data)),
+			ContentLength: int64(len(data)),
+			ContentType:   "application/octet-stream",
+		}, nil
+	}
+	return nil, gorm.ErrRecordNotFound
+}
+
+// Delete removes an object from mock storage.
+func (m *MockStorageService) Delete(_ context.Context, key string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.objects, key)
+	return nil
+}
+
+// Ingest handles programmatic file ingestion for mock storage.
+func (m *MockStorageService) Ingest(_ context.Context, _ io.Reader, _ contracts.IngestOptions) (*contracts.IngestResult, error) {
+	return &contracts.IngestResult{ID: 1, Key: "test.png", Created: true, Stored: true}, nil
+}
+
+// MockAuthService is a mock implementation of contracts.AuthService for unit testing.
+type MockAuthService struct {
+	DB *gorm.DB
+}
+
+// errMockNotImplemented marks a mock method no test exercises yet, so an
+// accidental call reports this instead of dereferencing a nil result.
+var errMockNotImplemented = errors.New("mock auth service: not implemented")
+
+// RequireAuthMiddleware returns a dummy auth middleware.
+func (a *MockAuthService) RequireAuthMiddleware() any {
+	return func(c *gin.Context) { c.Next() }
+}
+
+// RequireAdminMiddleware returns a dummy admin middleware.
+func (a *MockAuthService) RequireAdminMiddleware() any {
+	return func(c *gin.Context) { c.Next() }
+}
+
+// DisallowTokenAuthMiddleware returns a dummy disallow token middleware.
+func (a *MockAuthService) DisallowTokenAuthMiddleware() any {
+	return func(c *gin.Context) { c.Next() }
+}
+
+// GetCurrentUser returns the user associated with the request context.
+func (a *MockAuthService) GetCurrentUser(ctx context.Context) (*contracts.UserDTO, error) {
+	if c, ok := ctx.(*gin.Context); ok {
+		authHeader := c.GetHeader("Authorization")
+		if strings.HasPrefix(authHeader, "Bearer ") {
+			tokenStr := strings.TrimPrefix(authHeader, "Bearer ")
+			tokenHash := fmt.Sprintf("%x", sha256.Sum256([]byte(tokenStr)))
+			var tokenRecord struct {
+				UserID uint64
+			}
+			if err := a.DB.Table("w_access_tokens").Where("token_hash = ?", tokenHash).First(&tokenRecord).Error; err == nil {
+				return &contracts.UserDTO{ID: tokenRecord.UserID, IsActive: true}, nil
+			}
+		}
+	}
+	return nil, errors.New("unauthorized")
+}
+
+// GetCurrentUserID returns the current user ID.
+func (a *MockAuthService) GetCurrentUserID(ctx context.Context) (uint64, error) {
+	u, err := a.GetCurrentUser(ctx)
+	if err != nil {
+		return 0, err
+	}
+	return u.ID, nil
+}
+
+// VerifyToken verifies an access token.
+func (a *MockAuthService) VerifyToken(_ context.Context, token string) (*contracts.UserDTO, error) {
+	tokenHash := fmt.Sprintf("%x", sha256.Sum256([]byte(token)))
+	var tokenRecord struct {
+		UserID uint64
+	}
+	if err := a.DB.Table("w_access_tokens").Where("token_hash = ?", tokenHash).First(&tokenRecord).Error; err == nil {
+		return &contracts.UserDTO{ID: tokenRecord.UserID, IsActive: true}, nil
+	}
+	return nil, errors.New("unauthorized")
+}
+
+// Authenticate verifies credentials.
+func (a *MockAuthService) Authenticate(_ context.Context, _, _ string) (*contracts.UserDTO, error) {
+	return nil, errMockNotImplemented
+}
+
+// CreateSession creates a login session.
+func (a *MockAuthService) CreateSession(_ context.Context, _ uint64, _ map[string]any) (string, error) {
+	return "test-session", nil
+}
+
+// RevokeToken revokes an access token.
+func (a *MockAuthService) RevokeToken(_ context.Context, _ string) error {
+	return nil
+}
+
+// RevokeUserSessions revokes all sessions for a user.
+func (a *MockAuthService) RevokeUserSessions(_ context.Context, _ uint64) error {
+	return nil
+}
+
+// InvalidateCachedUser invalidates cached user profile.
+func (a *MockAuthService) InvalidateCachedUser(_ context.Context, _ uint64) {}
+
+// InvalidateCachedToken invalidates cached access token.
+func (a *MockAuthService) InvalidateCachedToken(_ context.Context, _ string) {}
+
+// ListAuthSources lists configured authentication sources.
+func (a *MockAuthService) ListAuthSources(_ context.Context) ([]contracts.AuthSourceViewDTO, error) {
+	return nil, nil
+}
+
+// CreateAuthSource creates an authentication source.
+func (a *MockAuthService) CreateAuthSource(_ context.Context, _ contracts.AuthSourceDTO) (*contracts.AuthSourceDTO, error) {
+	return nil, errMockNotImplemented
+}
+
+// UpdateAuthSource updates an authentication source.
+func (a *MockAuthService) UpdateAuthSource(_ context.Context, _ uint64, _ contracts.AuthSourceDTO) (*contracts.AuthSourceDTO, error) {
+	return nil, errMockNotImplemented
+}
+
+// DeleteAuthSource deletes an authentication source.
+func (a *MockAuthService) DeleteAuthSource(_ context.Context, _ uint64) error {
+	return nil
+}
+
+// ToggleAuthSource toggles an authentication source active state.
+func (a *MockAuthService) ToggleAuthSource(_ context.Context, _ uint64) (*contracts.AuthSourceDTO, error) {
+	return nil, errMockNotImplemented
+}
+
+// SetupTestEnv initializes test helper environment and binds DB, Cache, Storage, Auth mocks to shared services.
+func SetupTestEnv(t *testing.T) (*gorm.DB, func()) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	dbSvc := &MockDBService{DBInstance: dbConn}
+	cacheSvc := NewMockCacheService()
+	storageSvc := NewMockStorageService()
+	authSvc := &MockAuthService{DB: dbConn}
+
+	SetDBService(dbSvc)
+	SetCacheService(cacheSvc)
+	SetStorageService(storageSvc)
+	SetAuthService(authSvc)
+
+	return dbConn, func() {
+		ResetServices()
+		cleanup()
+	}
+}