feat: add scoped task source tracing and SDK examples

pulse/service/source.go

@@ -0,0 +1,43 @@
+package service
+
+import (
+	"context"
+	core "git.yuntuo.hk/k2safe/orbit/model"
+	"git.yuntuo.hk/k2safe/orbit/platform/auth"
+	"time"
+)
+
+// TaskSourceView 只读的直接来源，不遍历整条重试链，也不授予来源资源管理权限。
+type TaskSourceView struct {
+	// TaskID 本次已授权查询的任务标识。
+	TaskID core.ID `json:"task_id"`
+	// Kind 当前支持DIRECT、MANUAL_RETRY、SCHEDULE；分别是普通受理、人工派生、计划触发。
+	Kind string `json:"kind"`
+	// RetryOf 人工重试的直接原任务，限同一命名空间及队列；其他种类省略。
+	RetryOf *core.ID `json:"retry_of,omitempty"`
+	// Schedule 计划触发的固定来源，仅SCHEDULE返回，不包含任务模板或计划配置。
+	Schedule *TaskScheduleSource `json:"schedule,omitempty"`
+}
+
+// TaskScheduleSource 关联已生成任务的触发记录及当时的不可变计划版本。
+type TaskScheduleSource struct {
+	// ScheduleID 原计划标识，不因发布新版本而变化。
+	ScheduleID core.ID `json:"schedule_id"`
+	// ScheduleVersion 触发时使用的固定版本，JSON字符串避免精度丢失。
+	ScheduleVersion uint64 `json:"schedule_version,string"`
+	// OccurrenceID 唯一关联该任务的触发记录标识。
+	OccurrenceID core.ID `json:"occurrence_id"`
+	// ScheduledAt 原计划时间，UTC微秒精度，不等于实际受理/执行时间。
+	ScheduledAt time.Time `json:"scheduled_at"`
+	// Decision FIRED为单点触发，COALESCED为合并触发；跳过不会产生任务。
+	Decision string `json:"decision"`
+	// CoveredUntil 合并范围的排除边界，仅COALESCED返回。
+	CoveredUntil *time.Time `json:"covered_until,omitempty"`
+}
+
+func (s *Service) GetTaskSource(ctx context.Context, t auth.Token, id core.ID) (TaskSourceView, error) {
+	if err := validateHistoryIDs(id); err != nil {
+		return TaskSourceView{}, err
+	}
+	return s.store.GetTaskSource(ctx, t, id)
+}

pulse/service/types.go

@@ -224,6 +224,7 @@ type QueueResult struct {
 
 // Store 实现命名空间隔离、事务授权与持久化，不在事务外产生业务副作用。
 type Store interface {
+	GetTaskSource(context.Context, auth.Token, core.ID) (TaskSourceView, error)
 	ReviewTask(context.Context, auth.Token, core.ID, string, ReviewInput) (ReviewResult, error)
 	RetryTask(context.Context, auth.Token, core.ID, string, ManualRetryInput) (ManualRetryResult, error)
 	ListTaskOperations(context.Context, auth.Token, core.ID, HistoryPageInput) (TaskOperationPage, error)