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/drivers/driver_asynq_worker/executor.go

@@ -0,0 +1,502 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_asynq_worker
+
+import (
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/util"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/hibiken/asynq"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/trace"
+
+	otel_trace "Wavelet/pkg/trace"
+)
+
+var (
+	handlerRegistryMutex sync.RWMutex
+	handlerRegistry      = make(map[string]TaskHandler)
+
+	completedHandlersMutex sync.RWMutex
+	taskCompletedHandlers  []CompletedHandler
+)
+
+// CompletedHandler is called when a task execution completes.
+type CompletedHandler func(ctx context.Context, execution *TaskExecution, result *TaskResult, execErr error)
+
+// OnTaskCompleted registers a handler for task completion events.
+// Handlers must be registered during application bootstrap before processing tasks.
+func OnTaskCompleted(handler CompletedHandler) {
+	completedHandlersMutex.Lock()
+	defer completedHandlersMutex.Unlock()
+	taskCompletedHandlers = append(taskCompletedHandlers, handler)
+}
+
+// RegisterHandler 注册任务处理器
+// 传入任务类型标识（对应 AsynqTask 常量）和 TaskHandler 实现
+func RegisterHandler(asynqTaskType string, handler TaskHandler) {
+	handlerRegistryMutex.Lock()
+	defer handlerRegistryMutex.Unlock()
+	handlerRegistry[asynqTaskType] = handler
+}
+
+// getHandler 获取已注册的处理器
+func getHandler(asynqTaskType string) (TaskHandler, bool) {
+	handlerRegistryMutex.RLock()
+	defer handlerRegistryMutex.RUnlock()
+	h, ok := handlerRegistry[asynqTaskType]
+	return h, ok
+}
+
+// ValidateAndNormalizePayload 校验并标准化任务参数。
+// 如果 Handler 实现了 PayloadValidator，调用其 ValidatePayload 方法；
+// 否则直接返回原始 payload。
+func ValidateAndNormalizePayload(asynqTaskType string, payload []byte) ([]byte, error) {
+	handler, ok := getHandler(asynqTaskType)
+	if !ok {
+		return payload, nil
+	}
+	if validator, ok := handler.(PayloadValidator); ok {
+		return validator.ValidatePayload(payload)
+	}
+	return payload, nil
+}
+
+// contextKey 用于 context 存取 taskID
+type contextKey string
+
+const (
+	taskIDKey contextKey = "task_execution_task_id"
+
+	traceEnvelopeVersion = 1
+)
+
+type traceEnvelope struct {
+	WaveletTraceEnvelope bool              `json:"_wavelet_trace_envelope"`
+	Version              int               `json:"version"`
+	TraceContext         map[string]string `json:"trace_context,omitempty"`
+	Payload              []byte            `json:"payload"`
+}
+
+// withTaskID 将 taskID 注入 context
+func withTaskID(ctx context.Context, taskID string) context.Context {
+	return context.WithValue(ctx, taskIDKey, taskID)
+}
+
+// GetTaskID 从 context 中获取 taskID
+func GetTaskID(ctx context.Context) string {
+	if v, ok := ctx.Value(taskIDKey).(string); ok {
+		return v
+	}
+	return ""
+}
+
+// IsFinalAttempt 判断当前任务执行是否为最后一次重试尝试（若再次失败即为最终失败）
+func IsFinalAttempt(ctx context.Context) bool {
+	retryCount, hasRetryCount := asynq.GetRetryCount(ctx)
+	maxRetry, hasMaxRetry := asynq.GetMaxRetry(ctx)
+	if !hasRetryCount || !hasMaxRetry {
+		return true
+	}
+	return retryCount >= maxRetry
+}
+
+// AppendLog 追加日志到任务执行记录
+// 在 TaskHandler.Execute 中调用，日志会自动追加到 TaskExecution.Log 字段
+func AppendLog(ctx context.Context, format string, args ...interface{}) {
+	taskID := GetTaskID(ctx)
+	if taskID == "" {
+		// 上下文中没有 taskID，降级到普通日志
+		logger.InfoF(ctx, format, args...)
+		return
+	}
+
+	logLine := fmt.Sprintf(format, args...)
+	if err := appendTaskExecutionLog(ctx, taskID, logLine); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加任务日志失败 taskID=%s: %v", taskID, err)
+	}
+}
+
+// DispatchTask 下发任务（创建 TaskExecution 记录 → 入队 Asynq）
+func DispatchTask(ctx context.Context, taskType string, payload []byte, triggeredBy string) (string, error) {
+	meta := GetTaskMeta(taskType)
+	if meta == nil {
+		return "", fmt.Errorf(errUnknownTaskType, taskType)
+	}
+
+	// 生成唯一的 TaskID
+	taskID := generateTaskID(taskType, triggeredBy)
+
+	// 创建任务执行记录
+	execution := &TaskExecution{
+		TaskID:      taskID,
+		TaskType:    meta.AsynqTask,
+		TaskName:    meta.Name,
+		Status:      TaskExecutionStatusPending,
+		Retryable:   meta.Retryable,
+		MaxRetry:    meta.MaxRetry,
+		RetryCount:  0,
+		Payload:     string(payload),
+		TriggeredBy: triggeredBy,
+	}
+
+	if err := createTaskExecution(ctx, execution); err != nil {
+		return "", fmt.Errorf(errCreateTaskExecutionFailed, err)
+	}
+
+	// 入队 Asynq
+	taskInfo := asynq.NewTask(meta.AsynqTask, injectTaskTraceContext(ctx, payload))
+	if _, err := GetAsynqClient().Enqueue(
+		taskInfo,
+		asynq.TaskID(taskID),
+		asynq.MaxRetry(meta.MaxRetry),
+		asynq.Queue(meta.Queue),
+	); err != nil {
+		// 入队失败，更新执行记录状态
+		execution.Status = TaskExecutionStatusFailed
+		execution.ErrorMessage = fmt.Sprintf("入队失败: %v", err)
+		now := time.Now()
+		execution.StartedAt = &now
+		execution.FinishedAt = &now
+		_ = updateTaskExecution(ctx, execution)
+		return "", fmt.Errorf(errTaskEnqueueFailed, err)
+	}
+
+	if err := appendTaskExecutionLog(ctx, taskID, fmt.Sprintf("[系统] 任务已成功入队，等待调度执行 (队列: %s, 最大重试次数: %d)", meta.Queue, meta.MaxRetry)); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加入队日志失败 taskID=%s: %v", taskID, err)
+	}
+
+	return taskID, nil
+}
+
+// RetryTask 重试失败的任务
+func RetryTask(ctx context.Context, id uint64) (string, error) {
+	execution, err := getTaskExecutionByID(ctx, id)
+	if err != nil {
+		return "", fmt.Errorf(errTaskExecutionNotFound, err)
+	}
+
+	if execution.Status != TaskExecutionStatusFailed {
+		return "", fmt.Errorf(errRetryOnlyFailedTask, execution.Status)
+	}
+
+	if !execution.Retryable {
+		return "", errors.New(errTaskNotRetryable)
+	}
+
+	// 生成新的 TaskID
+	newTaskID := generateRetryTaskID(execution.TaskID, execution.RetryCount+1)
+
+	// 创建新的执行记录
+	newExecution := &TaskExecution{
+		TaskID:      newTaskID,
+		TaskType:    execution.TaskType,
+		TaskName:    execution.TaskName,
+		Status:      TaskExecutionStatusPending,
+		Retryable:   execution.Retryable,
+		MaxRetry:    execution.MaxRetry,
+		RetryCount:  execution.RetryCount + 1,
+		Payload:     execution.Payload,
+		TriggeredBy: "retry",
+	}
+
+	if err := createTaskExecution(ctx, newExecution); err != nil {
+		return "", fmt.Errorf(errCreateRetryExecutionFailed, err)
+	}
+
+	meta := GetTaskMeta(execution.TaskType)
+	queueName := QueueDefault
+	if meta != nil {
+		queueName = meta.Queue
+	}
+
+	// 入队 Asynq
+	taskInfo := asynq.NewTask(execution.TaskType, injectTaskTraceContext(ctx, []byte(execution.Payload)))
+	if _, err := GetAsynqClient().Enqueue(
+		taskInfo,
+		asynq.TaskID(newTaskID),
+		asynq.MaxRetry(execution.MaxRetry),
+		asynq.Queue(queueName),
+	); err != nil {
+		newExecution.Status = TaskExecutionStatusFailed
+		newExecution.ErrorMessage = fmt.Sprintf("重试入队失败: %v", err)
+		now := time.Now()
+		newExecution.StartedAt = &now
+		newExecution.FinishedAt = &now
+		_ = updateTaskExecution(ctx, newExecution)
+		return "", fmt.Errorf(errRetryTaskEnqueueFailed, err)
+	}
+
+	if err := appendTaskExecutionLog(ctx, newTaskID, fmt.Sprintf("[系统] 手动触发重试，已重新创建任务并入队 (原任务ID: %s, 重试次数: %d/%d)", execution.TaskID, execution.RetryCount+1, execution.MaxRetry)); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 追加重试日志失败 taskID=%s: %v", newTaskID, err)
+	}
+
+	return newTaskID, nil
+}
+
+// ProcessTask Asynq 实际调用的统一处理函数
+// Worker 注册时统一使用此函数，内部自动分发到对应的 TaskHandler
+func ProcessTask(ctx context.Context, t *asynq.Task) error {
+	taskPayload := t.Payload()
+	ctx, taskPayload, hasRemoteTraceContext := extractTaskTraceContext(ctx, taskPayload)
+
+	// 初始化 Trace
+	ctx, span := otel_trace.Start(ctx, "TaskProcess_"+t.Type(), trace.WithSpanKind(trace.SpanKindConsumer))
+	defer span.End()
+
+	// 添加任务信息到 Span
+	span.SetAttributes(
+		attribute.String("task.type", t.Type()),
+		attribute.Int("task.payload_size", len(taskPayload)),
+		attribute.Bool("task.trace_context_propagated", hasRemoteTraceContext),
+		attribute.String("task.id", t.ResultWriter().TaskID()),
+	)
+
+	taskID := t.ResultWriter().TaskID()
+
+	// 注入 taskID 到 context
+	ctx = withTaskID(ctx, taskID)
+
+	// 查找处理器
+	handler, ok := getHandler(t.Type())
+	if !ok {
+		err := fmt.Errorf(errUnregisteredTaskHandler, t.Type())
+		logger.ErrorF(ctx, "[TaskExecutor] %v", err)
+		span.SetStatus(codes.Error, err.Error())
+		return err
+	}
+
+	// 加载或动态创建执行记录
+	now := time.Now()
+	execution, err := getOrCreateTaskExecution(ctx, taskID, t, taskPayload, now)
+	if err == nil {
+		updateExecutionOnStart(ctx, execution, now)
+	}
+
+	if execution != nil {
+		AppendLog(ctx, "[系统] 开始执行异步任务 [名称: %s, 类型: %s]，重试次数: %d/%d",
+			execution.TaskName, t.Type(), execution.RetryCount, execution.MaxRetry)
+	} else {
+		AppendLog(ctx, "[系统] 开始执行异步任务 [类型: %s]", t.Type())
+	}
+
+	// 开始计时
+	start := time.Now()
+
+	// 执行业务逻辑
+	result, execErr := handler.Execute(ctx, taskPayload)
+
+	// 计算耗时并归档记录
+	duration := time.Since(start)
+	finishTime := time.Now()
+
+	completeTaskExecution(ctx, execution, t, duration, finishTime, result, execErr, span)
+
+	if execution == nil && execErr != nil {
+		span.SetStatus(codes.Error, execErr.Error())
+		return execErr
+	}
+
+	return execErr
+}
+
+func injectTaskTraceContext(ctx context.Context, payload []byte) []byte {
+	carrier := propagation.MapCarrier{}
+	otel.GetTextMapPropagator().Inject(ctx, carrier)
+	if len(carrier) == 0 {
+		return payload
+	}
+
+	envelope := traceEnvelope{
+		WaveletTraceEnvelope: true,
+		Version:              traceEnvelopeVersion,
+		TraceContext:         map[string]string(carrier),
+		Payload:              payload,
+	}
+	data, err := json.Marshal(envelope)
+	if err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 序列化任务 Trace 上下文失败: %v", err)
+		return payload
+	}
+	return data
+}
+
+func extractTaskTraceContext(ctx context.Context, payload []byte) (context.Context, []byte, bool) {
+	var envelope traceEnvelope
+	if err := json.Unmarshal(payload, &envelope); err != nil {
+		return ctx, payload, false
+	}
+	if !envelope.WaveletTraceEnvelope || envelope.Version != traceEnvelopeVersion {
+		return ctx, payload, false
+	}
+	if len(envelope.TraceContext) == 0 {
+		return ctx, envelope.Payload, false
+	}
+
+	extractedCtx := otel.GetTextMapPropagator().Extract(ctx, propagation.MapCarrier(envelope.TraceContext))
+	return extractedCtx, envelope.Payload, true
+}
+
+func updateExecutionOnStart(ctx context.Context, execution *TaskExecution, now time.Time) {
+	if execution == nil {
+		return
+	}
+	dirty := false
+	if retryCount, hasRetry := asynq.GetRetryCount(ctx); hasRetry && execution.RetryCount != retryCount {
+		execution.RetryCount = retryCount
+		dirty = true
+	}
+	if execution.Status != TaskExecutionStatusRunning {
+		execution.Status = TaskExecutionStatusRunning
+		execution.StartedAt = &now
+		dirty = true
+	}
+	if dirty {
+		if updateErr := updateTaskExecution(ctx, execution); updateErr != nil {
+			logger.ErrorF(ctx, "[TaskExecutor] 更新执行状态失败 taskID=%s: %v", execution.TaskID, updateErr)
+		}
+	}
+}
+
+// getOrCreateTaskExecution 获取已有的任务执行记录，如果不存在则针对已知任务类型动态创建记录
+func getOrCreateTaskExecution(ctx context.Context, taskID string, t *asynq.Task, payload []byte, now time.Time) (*TaskExecution, error) {
+	execution, err := getTaskExecutionByTaskID(ctx, taskID)
+	if err == nil {
+		return execution, nil
+	}
+
+	meta := GetTaskMetaByAsynqTask(t.Type())
+	if meta == nil {
+		return nil, err
+	}
+
+	execution = &TaskExecution{
+		TaskID:      taskID,
+		TaskType:    meta.AsynqTask,
+		TaskName:    meta.Name,
+		Status:      TaskExecutionStatusRunning,
+		Retryable:   meta.Retryable,
+		MaxRetry:    meta.MaxRetry,
+		RetryCount:  0,
+		Payload:     string(payload),
+		TriggeredBy: "schedule",
+		StartedAt:   &now,
+	}
+
+	if createErr := createTaskExecution(ctx, execution); createErr != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 动态创建执行记录失败 taskID=%s: %v", taskID, createErr)
+		return nil, createErr
+	}
+
+	return execution, nil
+}
+
+// completeTaskExecution 完成并更新任务执行记录的状态和执行结果
+func completeTaskExecution(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, finishTime time.Time, result *TaskResult, execErr error, span trace.Span) {
+	if execution == nil {
+		return
+	}
+
+	execution.Duration = duration.Milliseconds()
+	execution.FinishedAt = &finishTime
+
+	if execErr != nil {
+		handleFailedTask(ctx, execution, t, duration, execErr, span)
+	} else {
+		handleSuccessfulTask(ctx, execution, t, duration, result)
+	}
+
+	if err := updateTaskExecution(ctx, execution); err != nil {
+		logger.ErrorF(ctx, "[TaskExecutor] 更新执行记录失败 taskID=%s: %v", execution.TaskID, err)
+	}
+	if shouldFlushTaskExecutionLog(ctx, execErr) {
+		if err := flushTaskExecutionLog(ctx, execution.TaskID); err != nil {
+			logger.ErrorF(ctx, "[TaskExecutor] 持久化任务日志失败 taskID=%s: %v", execution.TaskID, err)
+		}
+	}
+
+	notifyTaskCompleted(ctx, execution, result, execErr)
+}
+
+func notifyTaskCompleted(ctx context.Context, execution *TaskExecution, result *TaskResult, execErr error) {
+	completedHandlersMutex.RLock()
+	defer completedHandlersMutex.RUnlock()
+
+	if len(taskCompletedHandlers) == 0 {
+		return
+	}
+
+	asyncCtx := context.WithoutCancel(ctx)
+	for _, handler := range taskCompletedHandlers {
+		h := handler
+		util.Go(func() {
+			h(asyncCtx, execution, result, execErr)
+		})
+	}
+}
+
+func shouldFlushTaskExecutionLog(ctx context.Context, execErr error) bool {
+	if isTerminalTaskExecutionError(execErr) {
+		return true
+	}
+
+	retryCount, hasRetryCount := asynq.GetRetryCount(ctx)
+	maxRetry, hasMaxRetry := asynq.GetMaxRetry(ctx)
+	if !hasRetryCount || !hasMaxRetry {
+		return true
+	}
+	return retryCount >= maxRetry
+}
+
+func isTerminalTaskExecutionError(execErr error) bool {
+	return execErr == nil || errors.Is(execErr, asynq.SkipRetry)
+}
+
+func handleFailedTask(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, execErr error, span trace.Span) {
+	execution.Status = TaskExecutionStatusFailed
+	execution.ErrorMessage = execErr.Error()
+	logger.ErrorF(ctx, "[TaskExecutor] 任务处理失败 Type: %s TaskID: %s Duration: %d ms Error: %v", t.Type(), execution.TaskID, duration.Milliseconds(), execErr)
+	span.SetStatus(codes.Error, execErr.Error())
+	span.RecordError(execErr)
+
+	AppendLog(ctx, "[系统] 任务执行失败，耗时: %d ms，错误原因: %v", duration.Milliseconds(), execErr)
+}
+
+func handleSuccessfulTask(ctx context.Context, execution *TaskExecution, t *asynq.Task, duration time.Duration, result *TaskResult) {
+	execution.Status = TaskExecutionStatusSucceeded
+	execution.ErrorMessage = "" // 清除历史重试失败遗留的错误信息
+	if result != nil {
+		execution.Result = result.Message
+		if result.Detail != "" {
+			execution.Result = fmt.Sprintf("%s\n%s", result.Message, result.Detail)
+		}
+	}
+	logger.InfoF(ctx, "[TaskExecutor] 任务处理完成 Type: %s TaskID: %s Duration: %d ms", t.Type(), execution.TaskID, duration.Milliseconds())
+
+	resultMsg := "成功"
+	if result != nil {
+		resultMsg = result.Message
+	}
+	AppendLog(ctx, "[系统] 任务执行成功，耗时: %d ms，执行结果: %s", duration.Milliseconds(), resultMsg)
+}
+
+// generateTaskID 生成任务 ID
+func generateTaskID(taskType, triggeredBy string) string {
+	return fmt.Sprintf("%s_%s_%d", triggeredBy, taskType, idgen.NextUint64ID())
+}
+
+// generateRetryTaskID 生成重试任务 ID
+func generateRetryTaskID(originalTaskID string, retryCount int) string {
+	return fmt.Sprintf("retry_%d_%s", retryCount, originalTaskID)
+}