api

type ActivityInstance struct {
	ID                  string     `json:"id"`                            // 活动实例 ID
	ActivityID          string     `json:"activityId"`                    // 活动 ID
	ActivityName        string     `json:"activityName,omitempty"`        // 活动名称
	ActivityType        string     `json:"activityType,omitempty"`        // 活动类型
	ProcessDefinitionID string     `json:"processDefinitionId,omitempty"` // 流程定义 ID
	ProcessInstanceID   string     `json:"processInstanceId,omitempty"`   // 流程实例 ID
	ExecutionID         string     `json:"executionId,omitempty"`         // 执行 ID
	TaskID              string     `json:"taskId,omitempty"`              // 任务 ID
	Assignee            string     `json:"assignee,omitempty"`            // 处理人
	TenantID            string     `json:"tenantId,omitempty"`            // 租户
	StartTime           *time.Time `json:"startTime,omitempty"`           // 开始时间
	EndTime             *time.Time `json:"endTime,omitempty"`             // 结束时间
	DurationInMillis    *int64     `json:"durationInMillis,omitempty"`    // 持续时间
}

type AddSignRequest struct {
	TaskID    string   `json:"taskId"`              // 当前任务 Id（必填；首层加签时改造为父任务）
	Operator  string   `json:"operator"`            // 操作人（加签人身份 Id，必填）
	Assignees []string `json:"assignees"`           // 被加签人身份 Id 列表（必填，至少一人）
	ScopeType string   `json:"scopeType,omitempty"` // 作用域：后加签 "after" / 前加签 "before"（必填）
	Message   string   `json:"message,omitempty"`   // 加签意见（域服务意见留痕约束）
}

type AsyncVariableRequest struct {
	ProcessInstanceID string     // 实例标识，变量写入实例根作用域并忽略变量 scope
	ExecutionID       string     // 执行标识，支持统一的 local 或 global 作用域
	Variables         []Variable // 同一作业原子更新的变量
	CreateOnly        bool       // 排队前拒绝已存在的变量，对应集合 POST
	RequireExisting   bool       // 排队前要求变量存在，对应单变量 PUT
}

type Attachment struct {
	ID                string    `json:"id"`                          // 附件 ID
	TaskID            string    `json:"taskId,omitempty"`            // 任务 ID
	ProcessInstanceID string    `json:"processInstanceId,omitempty"` // 流程实例 ID
	Name              string    `json:"name"`                        // 名称
	Description       string    `json:"description,omitempty"`       // 描述
	Type              string    `json:"type,omitempty"`              // 类型
	URL               string    `json:"url,omitempty"`               // URL
	ContentURL        string    `json:"contentUrl,omitempty"`        // 内容下载地址
	Time              time.Time `json:"time"`                        // 创建时间
}

type AuditEvent struct {
	ID             int64     `json:"id"`                   // 事件 ID
	Time           time.Time `json:"time"`                 // 时间
	UserID         string    `json:"userId,omitempty"`     // 用户
	TenantID       string    `json:"tenantId,omitempty"`   // 租户
	Method         string    `json:"method"`               // HTTP 方法
	Path           string    `json:"path"`                 // 路径
	Status         int       `json:"status"`               // 状态码
	DurationMillis int64     `json:"durationMillis"`       // 耗时
	RemoteAddr     string    `json:"remoteAddr,omitempty"` // 客户端地址
}

type BackTaskVo struct {
	TaskID           string `json:"taskId"`                     // 当前任务 ID（必填）
	TargetActivityID string `json:"targetActivityId,omitempty"` // 退回目标节点 ID（空时由服务端计算可退节点）
	UserCode         string `json:"userCode"`                   // 操作人身份 Id（必填）
	Message          string `json:"message,omitempty"`          // 退回意见
	Type             string `json:"type,omitempty"`             // 意见类型，退回场景通常为 TH
}

type BaseProcessVo struct {
	TaskID            string `json:"taskId"`            // 任务 ID（必填）
	UserCode          string `json:"userCode"`          // 操作人身份 Id（必填）
	Message           string `json:"message"`           // 审批意见内容（必填）
	ProcessInstanceID string `json:"processInstanceId"` // 流程实例 ID（必填）
	Type              string `json:"type"`              // 意见类型 CommentTypeEnum 代码（必填，如 SP/TH/CH）
}

type Batch struct {
	ID        string     `json:"id"`                 // 批次 ID
	Type      string     `json:"type"`               // 批次类型
	Total     int        `json:"total"`              // 分片总数
	Completed int        `json:"completed"`          // 已完成分片数
	Status    string     `json:"status"`             // 批次状态
	StartTime time.Time  `json:"startTime"`          // 开始时间
	EndTime   *time.Time `json:"endTime,omitempty"`  // 结束时间
	TenantID  string     `json:"tenantId,omitempty"` // 租户
	Document  []byte     `json:"document,omitempty"` // 批次文档，旧快照可为空
}

type BatchPart struct {
	ID                string     `json:"id"`                          // 分片 ID
	BatchID           string     `json:"batchId"`                     // 所属批次 ID
	Type              string     `json:"type"`                        // 分片类型
	ProcessInstanceID string     `json:"processInstanceId,omitempty"` // 流程实例 ID
	Status            string     `json:"status"`                      // 分片状态
	StartTime         time.Time  `json:"startTime"`                   // 开始时间
	EndTime           *time.Time `json:"endTime,omitempty"`           // 结束时间
	ErrorMessage      string     `json:"errorMessage,omitempty"`      // 失败原因
	Document          []byte     `json:"document,omitempty"`          // 分片文档，旧快照可为空
}

type Comment struct {
	ID                string    `json:"id"`                          // 评论 ID
	TaskID            string    `json:"taskId,omitempty"`            // 任务 ID
	ProcessInstanceID string    `json:"processInstanceId,omitempty"` // 流程实例 ID
	Type              string    `json:"type"`                        // 评论类型
	Action            string    `json:"action,omitempty"`            // 动作，事件型记录使用
	Message           string    `json:"message"`                     // 内容
	FullMessage       string    `json:"fullMessage,omitempty"`       // 完整内容
	UserID            string    `json:"userId,omitempty"`            // 作者
	Time              time.Time `json:"time"`                        // 创建时间
}

type CompleteTaskRequest struct {
	UserID             string     // 操作人
	Variables          []Variable // 流程变量
	LocalVariables     []Variable // 任务局部变量
	TransientVariables []Variable // 瞬态变量，仅完成命令内可见
}

type CompleteTaskVo struct {
	BaseProcessVo                    // 继承基础字段
	Variables         map[string]any `json:"variables,omitempty"`         // 流程变量
	TargetActivityID  string         `json:"targetActivityId,omitempty"`  // 直送目标节点 ID（流程结束时为保留代号 end）
	CountersignResult int            `json:"countersignResult,omitempty"` // 会签结论：0 否决 / 1 通过
	// CountersignResultSet 标记 countersignResult 是否由调用方显式设置。
	// Java CompleteTaskVo 该字段为 Integer，null 时抛"未知会签任务执行结果"；
	// Go 裸 int 无法区分"未传"与"显式 0（否决）"，016 号审计引入本标记补齐语义：
	// 未设置时权重会签节点按 Java 抛 WORKFLOW-2010，而非静默记为否决并扣 rejectWeight。
	CountersignResultSet bool                 `json:"-"`
	SenderStepCode       string               `json:"senderStepCode,omitempty"` // 发送方步骤代号
	SenderStepName       string               `json:"senderStepName,omitempty"` // 发送方步骤名称
	Request              *NextActivityRequest `json:"request,omitempty"`        // 下一步预存请求（目标为 end 时可省略）
}

type CreateModelRequest struct {
	Name     string // 名称
	Key      string // Key
	Category string // 分类
	MetaInfo string // 元信息
	TenantID string // 租户
	Version  int    // 版本，0 使用默认值
}

type CreateTaskRequest struct {
	Name         string     // 名称
	Description  string     // 描述
	Assignee     string     // 处理人
	Owner        string     // 所有者
	Priority     int        // 优先级，0 使用默认值
	DueDate      *time.Time // 到期时间
	Category     string     // 分类
	FormKey      string     // 表单 Key
	ParentTaskID string     // 父任务 ID
	TenantID     string     // 租户
}

type DMNEngine interface {
	Engine // 聚合全部基础服务
	// DMNService 返回 DMN 服务。
	// @return DMN 服务
	DMNService() DMNService
}

type DMNService interface {
	// ListDecisionDefinitions 返回流程定义所在部署的决策定义。
	// @param ctx 上下文
	// @param processDefinitionID 流程定义 ID
	// @return 决策定义列表，按资源名与决策 ID 排序
	// @return 查询错误
	ListDecisionDefinitions(ctx context.Context, processDefinitionID string) ([]DecisionDefinition, error)
	// ListDecisionTables 返回流程定义所在部署的决策表定义。
	// @param ctx 上下文
	// @param processDefinitionID 流程定义 ID
	// @return 决策表定义列表，按资源名与决策 ID 排序
	// @return 查询错误
	ListDecisionTables(ctx context.Context, processDefinitionID string) ([]DecisionTableDefinition, error)
}

type DecisionDefinition struct {
	ID           string `json:"id"`                // 决策定义 ID，取 decision 的 id
	Key          string `json:"key"`               // 决策 Key，取 decision 的 id
	Name         string `json:"name"`              // 决策名称，取 decision 的 name
	DeploymentID string `json:"deploymentId"`      // 所在部署 ID
	ResourceName string `json:"resourceName"`      // 部署资源名
	TenantID     string `json:"tenantId"`          // 租户，沿用流程定义
	Version      int    `json:"version,omitempty"` // 版本，沿用所查询流程定义的版本
}

type DecisionTableDefinition struct {
	ID           string                `json:"id"`           // 决策表 ID，取 decisionTable 的 id，缺失时回退 decision 的 id
	Key          string                `json:"key"`          // 决策 Key，取 decision 的 id
	Name         string                `json:"name"`         // 决策名称，取 decision 的 name
	DeploymentID string                `json:"deploymentId"` // 所在部署 ID
	ResourceName string                `json:"resourceName"` // 部署资源名
	TenantID     string                `json:"tenantId"`     // 租户，沿用流程定义
	HitPolicy    string                `json:"hitPolicy"`    // 命中策略，取 decisionTable 的 hitPolicy
	Inputs       []DecisionTableInput  `json:"inputs"`       // 输入列，按文档顺序
	Outputs      []DecisionTableOutput `json:"outputs"`      // 输出列，按文档顺序
	RuleCount    int                   `json:"ruleCount"`    // 规则数量
}

type DecisionTableInput struct {
	ID         string `json:"id"`                   // 输入 ID
	Label      string `json:"label,omitempty"`      // 输入显示名
	Expression string `json:"expression,omitempty"` // 输入表达式文本
}

type DecisionTableOutput struct {
	ID   string `json:"id"`             // 输出 ID
	Name string `json:"name,omitempty"` // 输出名称
	Type string `json:"type,omitempty"` // 输出类型，兼容 type 与 typeRef 属性
}

type DelSignRequest struct {
	ParentTaskID string `json:"parentTaskId"`      // 父任务 Id（必填）
	SubTaskID    string `json:"subTaskId"`         // 待减掉的子任务 Id（必填）
	Operator     string `json:"operator"`          // 操作人身份 Id（必填）
	Message      string `json:"message,omitempty"` // 减签意见，空时使用默认文案
}

type Deployment struct {
	ID         string    `json:"id"`         // 部署 ID
	Name       string    `json:"name"`       // 部署名称
	TenantID   string    `json:"tenantId"`   // 租户
	DeployTime time.Time `json:"deployTime"` // 部署时间
}

type DeploymentRequest struct {
	Name      string            // 部署名称
	TenantID  string            // 租户
	Resources map[string][]byte // 资源名到内容
}

type Engine interface {
	// RepositoryService 返回仓库服务。
	// @return 仓库服务
	RepositoryService() RepositoryService
	// RuntimeService 返回运行时服务。
	// @return 运行时服务
	RuntimeService() RuntimeService
	// TaskService 返回任务服务。
	// @return 任务服务
	TaskService() TaskService
	// HistoryService 返回历史服务。
	// @return 历史服务
	HistoryService() HistoryService
	// ManagementService 返回管理服务。
	// @return 管理服务
	ManagementService() ManagementService
	// IdentityService 返回身份服务。
	// @return 身份服务
	IdentityService() IdentityService
	// FormService 返回表单服务。
	// @return 表单服务
	FormService() FormService
	// WorkflowExtService 返回 workflow 二次封装扩展服务（任意退回/撤回/直送/重置/软终止/重激活）。
	// @return 扩展服务
	WorkflowExtService() WorkflowExtService
	// AddTaskCreatedHook 注册任务创建全局钩子（TASK_CREATED），按注册顺序在创建任务的命令内同步执行。
	// @param hook 钩子函数
	AddTaskCreatedHook(hook TaskHook)
	// AddTaskCompletedHook 注册任务完成全局钩子（TASK_COMPLETED），按注册顺序在完成任务的命令内同步执行。
	// @param hook 钩子函数
	AddTaskCompletedHook(hook TaskHook)
	// Close 关闭引擎。
	// @param ctx 关闭上下文
	// @return 关闭错误
	Close(ctx context.Context) error
}

type Error struct {
	Code    string // 稳定错误码，如 ENGINE-0404
	Message string // 中文说明
	Cause   error  // 底层错误，可为空
}

type EventSubscription struct {
	ID                  string    `json:"id"`                            // 订阅 ID
	URL                 string    `json:"url,omitempty"`                 // 资源地址
	EventType           string    `json:"eventType"`                     // 事件类型
	EventName           string    `json:"eventName"`                     // 事件名
	ExecutionID         string    `json:"executionId,omitempty"`         // 执行 ID
	ProcessInstanceID   string    `json:"processInstanceId,omitempty"`   // 流程实例 ID
	ActivityID          string    `json:"activityId,omitempty"`          // 活动 ID
	ProcessDefinitionID string    `json:"processDefinitionId,omitempty"` // 流程定义 ID
	TenantID            string    `json:"tenantId,omitempty"`            // 租户
	Created             time.Time `json:"created"`                       // 创建时间
}

type ExecutionInfo struct {
	ProcessDefinitionKey string `json:"processDefinitionKey"`       // 流程定义 Key
	ID                   string `json:"id"`                         // 执行 ID
	ProcessInstanceID    string `json:"processInstanceId"`          // 流程实例 ID
	ProcessDefinitionID  string `json:"processDefinitionId"`        // 流程定义 ID
	ParentID             string `json:"parentId,omitempty"`         // 父执行 ID
	SuperExecutionID     string `json:"superExecutionId,omitempty"` // 父调用活动执行 ID
	TenantID             string `json:"tenantId,omitempty"`         // 租户标识
	Suspended            bool   `json:"suspended,omitempty"`        // 是否挂起
	ActivityID           string `json:"activityId,omitempty"`       // 当前活动 ID
	Active               bool   `json:"active"`                     // 是否活跃
	Ended                bool   `json:"ended"`                      // 是否结束
	Waiting              bool   `json:"waiting"`                    // 是否等待
}

type ExecutionListenerHook func(ctx context.Context, execution ListenerExecution, ctl ListenerControl) error

type ExecutionListenerRegistrar interface {
	// RegisterExecutionListenerHook 注册扩展执行监听器。
	// @param name 监听器名（BPMN class/delegateExpression 注册名）
	// @param hook 监听器钩子
	RegisterExecutionListenerHook(name string, hook ExecutionListenerHook)
}

type FormData struct {
	FormKey    string         `json:"formKey,omitempty"` // 表单 Key
	Properties []FormProperty `json:"formProperties"`    // 字段列表
}

type FormDefinition struct {
	Key          string         `json:"key"`          // 表单 Key
	Name         string         `json:"name"`         // 表单名称
	DeploymentID string         `json:"deploymentId"` // 所在部署 ID
	ResourceName string         `json:"resourceName"` // 部署资源名
	TenantID     string         `json:"tenantId"`     // 租户
	Fields       []FormProperty `json:"fields"`       // 字段列表
}

type FormProperty struct {
	ID         string      `json:"id"`                   // 字段 ID
	Name       string      `json:"name,omitempty"`       // 显示名
	Type       string      `json:"type,omitempty"`       // 类型
	Required   bool        `json:"required"`             // 是否必填
	Readable   bool        `json:"readable"`             // 是否可读
	Writable   bool        `json:"writable"`             // 是否可写
	Value      any         `json:"value,omitempty"`      // 当前值
	EnumValues []FormValue `json:"enumValues,omitempty"` // 枚举值
}

type FormService interface {
	// GetStartFormData 返回流程启动表单。
	// @param ctx 上下文
	// @param processDefinitionID 流程定义 ID
	// @return 表单数据
	// @return 查询错误
	GetStartFormData(ctx context.Context, processDefinitionID string) (FormData, error)
	// GetTaskFormData 返回任务表单。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 表单数据
	// @return 查询错误
	GetTaskFormData(ctx context.Context, taskID string) (FormData, error)
	// ListFormDefinitions 返回流程定义所在部署的表单定义。
	// @param ctx 上下文
	// @param processDefinitionID 流程定义 ID
	// @return 表单定义列表，按资源名排序
	// @return 查询错误
	ListFormDefinitions(ctx context.Context, processDefinitionID string) ([]FormDefinition, error)
	// SubmitTaskFormData 提交任务表单并完成任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param values 字段值
	// @return 提交错误
	SubmitTaskFormData(ctx context.Context, taskID string, values map[string]any) error
}

type FormValue struct {
	ID   string `json:"id"`   // 值 ID
	Name string `json:"name"` // 显示名
}

type Group struct {
	ID       string `json:"id"`                 // 组 ID
	Name     string `json:"name,omitempty"`     // 组名
	Type     string `json:"type,omitempty"`     // 组类型
	TenantID string `json:"tenantId,omitempty"` // 租户
}

type HistoricActivityInstance struct {
	ID                    string     `json:"id"`                              // 历史记录 ID
	Revision              int        `json:"revision,omitempty"`              // 乐观锁版本
	ProcessDefinitionID   string     `json:"processDefinitionId,omitempty"`   // 流程定义 ID
	ProcessInstanceID     string     `json:"processInstanceId"`               // 流程实例 ID
	ExecutionID           string     `json:"executionId,omitempty"`           // 执行 ID
	ActivityID            string     `json:"activityId"`                      // 活动 ID
	TaskID                string     `json:"taskId,omitempty"`                // 对应用户任务 ID
	CallProcessInstanceID string     `json:"callProcessInstanceId,omitempty"` // 调用活动实例 ID
	ActivityName          string     `json:"activityName"`                    // 活动名称
	ActivityType          string     `json:"activityType"`                    // 活动类型
	Assignee              string     `json:"assignee,omitempty"`              // 处理人
	CompletedBy           string     `json:"completedBy,omitempty"`           // 完成人
	StartTime             time.Time  `json:"startTime"`                       // 开始时间
	EndTime               *time.Time `json:"endTime,omitempty"`               // 结束时间
	TransactionOrder      int        `json:"transactionOrder,omitempty"`      // 事务顺序
	DurationMillis        int64      `json:"durationMillis"`                  // 持续时间毫秒
	DeleteReason          string     `json:"deleteReason,omitempty"`          // 删除原因
	TenantID              string     `json:"tenantId,omitempty"`              // 租户
}

type HistoricActivityInstanceFilter struct {
	ID                   string     // 历史活动 ID
	ProcessInstanceID    string     // 流程实例 ID
	ProcessDefinitionID  string     // 流程定义 ID
	ProcessDefinitionKey string     // 流程定义 Key
	ActivityID           string     // 活动 ID
	ActivityName         string     // 活动名称
	ActivityType         string     // 活动类型
	Assignee             string     // 处理人
	TenantID             string     // 租户，空表示不过滤
	StartedAfter         *time.Time // 开始时间下界，含边界
	StartedBefore        *time.Time // 开始时间上界，含边界
	FinishedAfter        *time.Time // 结束时间下界，含边界
	FinishedBefore       *time.Time // 结束时间上界，含边界
	Finished             *bool      // 是否已结束，空表示不过滤
	Start                int        // 偏移量
	Size                 int        // 每页数量
}

type HistoricDetail struct {
	ID                string    `json:"id"`                          // 明细 ID
	Type              string    `json:"type"`                        // 类型
	ProcessInstanceID string    `json:"processInstanceId,omitempty"` // 流程实例 ID
	ExecutionID       string    `json:"executionId,omitempty"`       // 执行 ID
	TaskID            string    `json:"taskId,omitempty"`            // 任务 ID
	ActivityID        string    `json:"activityId,omitempty"`        // 活动 ID
	Name              string    `json:"name"`                        // 变量名
	Revision          int       `json:"revision"`                    // 变量修订号
	VariableType      string    `json:"variableType,omitempty"`      // 变量类型
	Value             any       `json:"value,omitempty"`             // 变量值
	Time              time.Time `json:"time"`                        // 记录时间
}

type HistoricProcessInstance struct {
	ID                        string     `json:"id"`                                  // 实例 ID
	Revision                  int        `json:"revision,omitempty"`                  // 乐观锁版本
	ProcessDefinitionID       string     `json:"processDefinitionId"`                 // 流程定义 ID
	ProcessDefinitionKey      string     `json:"processDefinitionKey"`                // 流程定义 Key
	BusinessKey               string     `json:"businessKey"`                         // 业务键
	Name                      string     `json:"name"`                                // 名称
	TenantID                  string     `json:"tenantId"`                            // 租户
	StartTime                 time.Time  `json:"startTime"`                           // 开始时间
	EndTime                   *time.Time `json:"endTime,omitempty"`                   // 结束时间
	DurationMillis            int64      `json:"durationMillis,omitempty"`            // 持续时间毫秒
	StartUserID               string     `json:"startUserId,omitempty"`               // 发起人
	StartActivityID           string     `json:"startActivityId,omitempty"`           // 开始活动
	EndActivityID             string     `json:"endActivityId,omitempty"`             // 结束活动
	SuperProcessInstanceID    string     `json:"superProcessInstanceId,omitempty"`    // 父流程实例
	CallbackID                string     `json:"callbackId,omitempty"`                // 回调标识
	CallbackType              string     `json:"callbackType,omitempty"`              // 回调类型
	ReferenceID               string     `json:"referenceId,omitempty"`               // 外部引用
	ReferenceType             string     `json:"referenceType,omitempty"`             // 外部引用类型
	PropagatedStageInstanceID string     `json:"propagatedStageInstanceId,omitempty"` // 传播阶段实例
	BusinessStatus            string     `json:"businessStatus,omitempty"`            // 业务状态
	DueDate                   *time.Time `json:"dueDate,omitempty"`                   // 到期时间
	ClaimTime                 *time.Time `json:"claimTime,omitempty"`                 // 签收时间
	ClaimedBy                 string     `json:"claimedBy,omitempty"`                 // 签收人
	EndUserID                 string     `json:"endUserId,omitempty"`                 // 结束操作人
	State                     string     `json:"state,omitempty"`                     // 实例状态
	DeleteReason              string     `json:"deleteReason,omitempty"`              // 删除原因
	Ended                     bool       `json:"ended"`                               // 是否结束
}

type HistoricProcessInstanceFilter struct {
	ID                   string     // 流程实例 ID
	ProcessDefinitionID  string     // 流程定义 ID
	ProcessDefinitionKey string     // 流程定义 Key
	BusinessKey          string     // 业务键
	TenantID             string     // 租户，空表示不过滤
	StartedAfter         *time.Time // 开始时间下界，含边界
	StartedBefore        *time.Time // 开始时间上界，含边界
	FinishedAfter        *time.Time // 结束时间下界，含边界
	FinishedBefore       *time.Time // 结束时间上界，含边界
	Finished             *bool      // 是否已结束，空表示不过滤
	Start                int        // 偏移量
	Size                 int        // 每页数量
}

type HistoricTaskInstance struct {
	ID                        string     `json:"id"`                                  // 任务 ID
	Revision                  int        `json:"revision,omitempty"`                  // 乐观锁版本
	ProcessDefinitionID       string     `json:"processDefinitionId,omitempty"`       // 流程定义 ID
	TaskDefinitionID          string     `json:"taskDefinitionId,omitempty"`          // 任务定义 ID
	Name                      string     `json:"name"`                                // 名称
	ProcessInstanceID         string     `json:"processInstanceId"`                   // 流程实例 ID
	ExecutionID               string     `json:"executionId,omitempty"`               // 执行 ID
	ScopeID                   string     `json:"scopeId,omitempty"`                   // 作用域 ID
	SubScopeID                string     `json:"subScopeId,omitempty"`                // 子作用域 ID
	ScopeType                 string     `json:"scopeType,omitempty"`                 // 作用域类型
	ScopeDefinitionID         string     `json:"scopeDefinitionId,omitempty"`         // 作用域定义 ID
	PropagatedStageInstanceID string     `json:"propagatedStageInstanceId,omitempty"` // 传播阶段实例 ID
	State                     string     `json:"state,omitempty"`                     // 任务状态
	TaskDefinitionKey         string     `json:"taskDefinitionKey"`                   // 任务定义 Key
	ParentTaskID              string     `json:"parentTaskId,omitempty"`              // 父任务 ID
	Description               string     `json:"description,omitempty"`               // 描述
	Owner                     string     `json:"owner,omitempty"`                     // 所有者
	Assignee                  string     `json:"assignee,omitempty"`                  // 处理人
	FormKey                   string     `json:"formKey,omitempty"`                   // 表单 Key
	TenantID                  string     `json:"tenantId,omitempty"`                  // 租户
	DeleteReason              string     `json:"deleteReason,omitempty"`              // 删除原因
	StartTime                 time.Time  `json:"startTime"`                           // 开始时间
	InProgressTime            *time.Time `json:"inProgressTime,omitempty"`            // 开始处理时间
	InProgressStartedBy       string     `json:"inProgressStartedBy,omitempty"`       // 开始处理人
	ClaimTime                 *time.Time `json:"claimTime,omitempty"`                 // 签收时间
	ClaimedBy                 string     `json:"claimedBy,omitempty"`                 // 签收人
	SuspendedTime             *time.Time `json:"suspendedTime,omitempty"`             // 挂起时间
	SuspendedBy               string     `json:"suspendedBy,omitempty"`               // 挂起操作人
	EndTime                   *time.Time `json:"endTime,omitempty"`                   // 结束时间
	CompletedBy               string     `json:"completedBy,omitempty"`               // 完成人
	DurationMillis            int64      `json:"durationMillis"`                      // 持续时间毫秒
	Priority                  int        `json:"priority,omitempty"`                  // 优先级
	InProgressDueDate         *time.Time `json:"inProgressDueDate,omitempty"`         // 处理截止时间
	DueDate                   *time.Time `json:"dueDate,omitempty"`                   // 截止时间
	Category                  string     `json:"category,omitempty"`                  // 分类
	LastUpdatedTime           *time.Time `json:"lastUpdatedTime,omitempty"`           // 最后更新时间
}

type HistoricTaskInstanceFilter struct {
	ID                   string     // 历史/任务 ID
	Name                 string     // 任务名称
	Assignee             string     // 处理人
	TaskDefinitionKey    string     // 任务定义 Key
	ProcessInstanceID    string     // 流程实例 ID
	ProcessDefinitionID  string     // 流程定义 ID
	ProcessDefinitionKey string     // 流程定义 Key
	TenantID             string     // 租户，空表示不过滤
	StartedAfter         *time.Time // 开始时间下界，含边界
	StartedBefore        *time.Time // 开始时间上界，含边界
	FinishedAfter        *time.Time // 结束时间下界，含边界
	FinishedBefore       *time.Time // 结束时间上界，含边界
	Finished             *bool      // 是否已结束，空表示不过滤
	Start                int        // 偏移量
	Size                 int        // 每页数量
}

type HistoricTaskLog struct {
	ID                  int64     `json:"id"`                            // 日志 ID
	Type                string    `json:"type"`                          // 事件类型
	TaskID              string    `json:"taskId,omitempty"`              // 任务 ID
	Time                time.Time `json:"time"`                          // 时间
	UserID              string    `json:"userId,omitempty"`              // 操作人
	Data                string    `json:"data,omitempty"`                // 附加数据
	ExecutionID         string    `json:"executionId,omitempty"`         // 执行 ID
	ProcessInstanceID   string    `json:"processInstanceId,omitempty"`   // 实例 ID
	ProcessDefinitionID string    `json:"processDefinitionId,omitempty"` // 定义 ID
	TenantID            string    `json:"tenantId,omitempty"`            // 租户
}

type HistoricVariableInstance struct {
	ID                string    `json:"id"`                    // 历史变量 ID
	Name              string    `json:"name"`                  // 变量名
	Type              string    `json:"type,omitempty"`        // 变量类型
	ProcessInstanceID string    `json:"processInstanceId"`     // 流程实例 ID
	ExecutionID       string    `json:"executionId,omitempty"` // 执行 ID
	TaskID            string    `json:"taskId,omitempty"`      // 任务 ID
	Value             any       `json:"value,omitempty"`       // 变量值
	CreateTime        time.Time `json:"createTime"`            // 创建时间
	LastUpdatedTime   time.Time `json:"lastUpdatedTime"`       // 最后更新时间
}

type HistoricVariableInstanceFilter struct {
	ID                string // 历史/变量 ID
	Name              string // 变量名
	ProcessInstanceID string // 流程实例 ID
	ExecutionID       string // 执行 ID
	TaskID            string // 任务 ID
	VariableType      string // 变量类型
	Start             int    // 偏移量
	Size              int    // 每页数量
}

type HistoryService interface {
	// ListHistoricProcessInstances 返回历史流程实例。
	// @param ctx 上下文
	// @return 历史实例列表
	// @return 查询错误
	ListHistoricProcessInstances(ctx context.Context) ([]HistoricProcessInstance, error)
	// QueryHistoricProcessInstances 按条件分页查询历史实例；行模式下等值与时间条件可下推 SQL。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页历史实例
	// @return 查询错误
	QueryHistoricProcessInstances(ctx context.Context, filter HistoricProcessInstanceFilter) (Page[HistoricProcessInstance], error)
	// QueryHistoricTaskInstances 按条件分页查询历史任务；行模式下等值与时间条件可下推 SQL。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页历史任务
	// @return 查询错误
	QueryHistoricTaskInstances(ctx context.Context, filter HistoricTaskInstanceFilter) (Page[HistoricTaskInstance], error)
	// QueryHistoricActivityInstances 按条件分页查询历史活动；行模式下等值与时间条件可下推 SQL。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页历史活动
	// @return 查询错误
	QueryHistoricActivityInstances(ctx context.Context, filter HistoricActivityInstanceFilter) (Page[HistoricActivityInstance], error)
	// QueryHistoricVariableInstances 按条件分页查询历史变量；行模式下等值条件可下推 SQL。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页历史变量
	// @return 查询错误
	QueryHistoricVariableInstances(ctx context.Context, filter HistoricVariableInstanceFilter) (Page[HistoricVariableInstance], error)
	// ListHistoricActivityInstances 返回指定实例的历史活动。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 历史活动列表
	// @return 查询错误
	ListHistoricActivityInstances(ctx context.Context, processInstanceID string) ([]HistoricActivityInstance, error)
	// ListHistoricTaskInstances 返回历史任务。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 历史任务列表
	// @return 查询错误
	ListHistoricTaskInstances(ctx context.Context, processInstanceID string) ([]HistoricTaskInstance, error)
	// DeleteHistoricProcessInstance 删除历史流程实例及其关联记录。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 删除错误
	DeleteHistoricProcessInstance(ctx context.Context, processInstanceID string) error
	// DeleteHistoricTaskInstance 删除历史任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 删除错误
	DeleteHistoricTaskInstance(ctx context.Context, taskID string) error
	// DeleteHistoricDetail 删除历史变量明细。
	// @param ctx 上下文
	// @param detailID 明细 ID
	// @return 删除错误
	DeleteHistoricDetail(ctx context.Context, detailID string) error
	// DeleteHistoricTaskLog 删除任务日志。
	// @param ctx 上下文
	// @param logID 日志 ID
	// @return 删除错误
	DeleteHistoricTaskLog(ctx context.Context, logID int64) error
	// GetHistoricProcessInstance 查询历史流程实例。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 历史实例
	// @return 查询错误
	GetHistoricProcessInstance(ctx context.Context, processInstanceID string) (HistoricProcessInstance, error)
	// GetHistoricActivityInstance 查询历史活动。
	// @param ctx 上下文
	// @param activityID 历史活动 ID
	// @return 历史活动
	// @return 查询错误
	GetHistoricActivityInstance(ctx context.Context, activityID string) (HistoricActivityInstance, error)
	// GetHistoricVariableInstance 查询历史变量。
	// @param ctx 上下文
	// @param variableID 历史变量 ID
	// @return 历史变量
	// @return 查询错误
	GetHistoricVariableInstance(ctx context.Context, variableID string) (HistoricVariableInstance, error)
	// DeleteHistoricVariableInstance 删除历史变量。
	// @param ctx 上下文
	// @param variableID 历史变量 ID
	// @return 删除错误
	DeleteHistoricVariableInstance(ctx context.Context, variableID string) error
	// GetHistoricTaskInstance 查询历史任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 历史任务
	// @return 查询错误
	GetHistoricTaskInstance(ctx context.Context, taskID string) (HistoricTaskInstance, error)
	// ListHistoricTaskLogs 返回任务生命周期日志。
	// @param ctx 上下文
	// @param taskID 任务 ID，空串表示全部
	// @return 日志列表
	// @return 查询错误
	ListHistoricTaskLogs(ctx context.Context, taskID string) ([]HistoricTaskLog, error)
	// ListHistoricDetails 返回历史变量明细。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 明细列表
	// @return 查询错误
	ListHistoricDetails(ctx context.Context, processInstanceID string) ([]HistoricDetail, error)
	// GetHistoricDetail 查询历史变量明细。
	// @param ctx 上下文
	// @param detailID 明细 ID
	// @return 明细
	// @return 查询错误
	GetHistoricDetail(ctx context.Context, detailID string) (HistoricDetail, error)
	// GetHistoricVariableByName 按实例与变量名查询历史变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param name 变量名
	// @return 历史变量
	// @return 查询错误
	GetHistoricVariableByName(ctx context.Context, processInstanceID, name string) (HistoricVariableInstance, error)
	// GetHistoricTaskVariableByName 按任务与变量名查询历史变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param name 变量名
	// @return 历史变量
	// @return 查询错误
	GetHistoricTaskVariableByName(ctx context.Context, taskID, name string) (HistoricVariableInstance, error)
	// GetHistoricTaskFormData 返回历史任务表单。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 表单数据
	// @return 查询错误
	GetHistoricTaskFormData(ctx context.Context, taskID string) (FormData, error)
	// ListHistoricIdentityLinks 返回历史身份链接。
	// @param ctx 上下文
	// @param taskID 任务 ID，空串表示全部
	// @return 链接列表
	// @return 查询错误
	ListHistoricIdentityLinks(ctx context.Context, taskID string) ([]IdentityLink, error)
	// ListHistoricProcessIdentityLinks 返回流程实例的历史身份链接。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 链接列表
	// @return 查询错误
	ListHistoricProcessIdentityLinks(ctx context.Context, processInstanceID string) ([]IdentityLink, error)
	// ListHistoricVariableInstances 返回历史变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 历史变量列表
	// @return 查询错误
	ListHistoricVariableInstances(ctx context.Context, processInstanceID string) ([]HistoricVariableInstance, error)
}

type HookControl interface {
	// SetAssignee 命令内改写任务办理人（执行人重写入口）。
	// @param taskID 任务 ID
	// @param userID 用户 ID，空串表示清空办理人
	// @return 错误（任务不存在等）
	SetAssignee(taskID, userID string) error
	// SetCandidateUsers 命令内整体重写任务候选用户。
	// @param taskID 任务 ID
	// @param ids 候选用户 ID 列表，空列表表示清空
	// @return 错误（任务不存在等）
	SetCandidateUsers(taskID string, ids []string) error
	// SetCandidateGroups 命令内整体重写任务候选组。
	// @param taskID 任务 ID
	// @param ids 候选组 ID 列表，空列表表示清空
	// @return 错误（任务不存在等）
	SetCandidateGroups(taskID string, ids []string) error
	// SetVariable 设置流程实例级变量（写入实例根执行作用域）。
	// @param name 变量名
	// @param value 变量值
	// @return 错误（实例不存在等）
	SetVariable(name string, value any) error
	// Defer 登记命令提交成功后顺序执行的延迟动作（新命令上下文，锁外执行）。
	// 动作内可安全调用引擎公有 API（如 CompleteTask 驱动相邻同人自动办结）；
	// 命令失败回滚时不执行；动作 panic 或返回错误仅记录日志，不影响已完成的命令。
	// @param action 延迟动作，入参为原命令上下文
	Defer(action func(ctx context.Context) error)
}

type IdentityLink struct {
	ID                  string    `json:"id,omitempty"`                  // 关联 ID
	Type                string    `json:"type"`                          // 类型
	UserID              string    `json:"userId,omitempty"`              // 用户 ID
	GroupID             string    `json:"groupId,omitempty"`             // 组 ID
	TaskID              string    `json:"taskId,omitempty"`              // 任务 ID
	ProcessInstanceID   string    `json:"processInstanceId,omitempty"`   // 流程实例 ID
	ProcessDefinitionID string    `json:"processDefinitionId,omitempty"` // 流程定义 ID
	CreateTime          time.Time `json:"createTime,omitempty"`          // 创建时间
}

type IdentityService interface {
	// CreateUser 创建用户。
	// @param ctx 上下文
	// @param user 用户
	// @return 用户
	// @return 创建错误
	CreateUser(ctx context.Context, user User) (User, error)
	// GetUser 查询用户。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @return 用户
	// @return 查询错误
	GetUser(ctx context.Context, userID string) (User, error)
	// ListUsers 返回全部用户。
	// @param ctx 上下文
	// @return 用户列表
	// @return 查询错误
	ListUsers(ctx context.Context) ([]User, error)
	// UpdateUser 更新用户资料与角色。
	// @param ctx 上下文
	// @param user 用户
	// @return 用户
	// @return 更新错误
	UpdateUser(ctx context.Context, user User) (User, error)
	// GetUserInfo 返回用户信息键值。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @return 信息映射
	// @return 查询错误
	GetUserInfo(ctx context.Context, userID string) (map[string]string, error)
	// GetUserInfoEntries 返回包含原版空值键的用户信息，并复制可空值。
	// @param ctx 上下文
	// @param userID 用户标识
	// @return 包含空值键的信息映射
	// @return 查询错误
	GetUserInfoEntries(ctx context.Context, userID string) (map[string]*string, error)
	// GetUserInfoValue 返回单个用户信息。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param key 键
	// @return 值
	// @return 查询错误
	GetUserInfoValue(ctx context.Context, userID, key string) (string, error)
	// SetUserInfo 设置用户信息。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param key 键
	// @param value 值
	// @return 设置错误
	SetUserInfo(ctx context.Context, userID, key, value string) error
	// DeleteUserInfo 删除用户信息。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param key 键
	// @return 删除错误
	DeleteUserInfo(ctx context.Context, userID, key string) error
	// GetUserPicture 返回用户头像。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @return 图片数据
	// @return MIME 类型
	// @return 查询错误
	GetUserPicture(ctx context.Context, userID string) ([]byte, string, error)
	// SetUserPicture 设置用户头像。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param data 图片数据
	// @param mimeType MIME 类型
	// @return 设置错误
	SetUserPicture(ctx context.Context, userID string, data []byte, mimeType string) error
	// SetUserRoles 设置用户角色。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param roles 角色列表
	// @return 设置错误
	SetUserRoles(ctx context.Context, userID string, roles []string) error
	// DeleteUser 删除用户。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @return 删除错误
	DeleteUser(ctx context.Context, userID string) error
	// CreateRole 创建角色。
	// @param ctx 上下文
	// @param role 角色
	// @return 角色
	// @return 创建错误
	CreateRole(ctx context.Context, role Role) (Role, error)
	// GetRole 查询角色。
	// @param ctx 上下文
	// @param roleID 角色 ID
	// @return 角色
	// @return 查询错误
	GetRole(ctx context.Context, roleID string) (Role, error)
	// ListRoles 返回全部角色。
	// @param ctx 上下文
	// @return 角色列表
	// @return 查询错误
	ListRoles(ctx context.Context) ([]Role, error)
	// UpdateRole 更新角色。
	// @param ctx 上下文
	// @param role 角色
	// @return 角色
	// @return 更新错误
	UpdateRole(ctx context.Context, role Role) (Role, error)
	// DeleteRole 删除角色。
	// @param ctx 上下文
	// @param roleID 角色 ID
	// @return 删除错误
	DeleteRole(ctx context.Context, roleID string) error
	// CreateGroup 创建组。
	// @param ctx 上下文
	// @param group 组
	// @return 组
	// @return 创建错误
	CreateGroup(ctx context.Context, group Group) (Group, error)
	// UpdateGroup 更新组。
	// @param ctx 上下文
	// @param group 组
	// @return 组
	// @return 更新错误
	UpdateGroup(ctx context.Context, group Group) (Group, error)
	// GetGroup 查询组。
	// @param ctx 上下文
	// @param groupID 组 ID
	// @return 组
	// @return 查询错误
	GetGroup(ctx context.Context, groupID string) (Group, error)
	// ListGroups 返回全部组。
	// @param ctx 上下文
	// @return 组列表
	// @return 查询错误
	ListGroups(ctx context.Context) ([]Group, error)
	// DeleteGroup 删除组。
	// @param ctx 上下文
	// @param groupID 组 ID
	// @return 删除错误
	DeleteGroup(ctx context.Context, groupID string) error
	// AddMembership 添加成员关系。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param groupID 组 ID
	// @return 添加错误
	AddMembership(ctx context.Context, userID, groupID string) error
	// RemoveMembership 移除成员关系。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param groupID 组 ID
	// @return 移除错误
	RemoveMembership(ctx context.Context, userID, groupID string) error
	// UpdatePassword 重置用户密码。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param newPassword 新密码
	// @return 更新错误
	UpdatePassword(ctx context.Context, userID, newPassword string) error
	// ChangePassword 修改用户密码。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param oldPassword 旧密码
	// @param newPassword 新密码
	// @return 修改错误
	ChangePassword(ctx context.Context, userID, oldPassword, newPassword string) error
	// CheckPassword 校验用户密码。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @param password 密码
	// @return 校验错误
	CheckPassword(ctx context.Context, userID, password string) error
	// ListUserGroups 返回用户所属组。
	// @param ctx 上下文
	// @param userID 用户 ID
	// @return 组列表
	// @return 查询错误
	ListUserGroups(ctx context.Context, userID string) ([]Group, error)
	// ListMembers 返回组成员。
	// @param ctx 上下文
	// @param groupID 组 ID
	// @return 用户列表
	// @return 查询错误
	ListMembers(ctx context.Context, groupID string) ([]User, error)
}

type InjectRequest struct {
	InjectionType string `json:"injectionType,omitempty"` // 注入类型，当前仅支持 task
	ID            string `json:"id,omitempty"`            // 动态任务 ID
	Name          string `json:"name"`                    // 任务名称
	Assignee      string `json:"assignee,omitempty"`      // 处理人
	TaskID        string `json:"taskId,omitempty"`        // 并行注入的参考任务 ID
}

type InsertUserTaskRequest struct {
	AfterActivityID     string `json:"afterActivityId"`               // 原用户任务节点ID
	ID                  string `json:"id,omitempty"`                  // 新节点ID，留空自动生成
	Name                string `json:"name"`                          // 新节点名称
	Assignee            string `json:"assignee"`                      // 新节点办理人或表达式
	ProcessDefinitionID string `json:"processDefinitionId,omitempty"` // 可选预期定义，防止在旧版本上误操作
}

type JobInfo struct {
	ID                string    `json:"id"`                          // 作业 ID
	Type              string    `json:"type,omitempty"`              // 作业类型
	ProcessInstanceID string    `json:"processInstanceId,omitempty"` // 流程实例 ID
	ExecutionID       string    `json:"executionId,omitempty"`       // 执行 ID
	ActivityID        string    `json:"activityId,omitempty"`        // 活动 ID
	Retries           int       `json:"retries"`                     // 剩余重试次数
	Exception         string    `json:"exception,omitempty"`         // 最近异常
	DueDate           time.Time `json:"dueDate"`                     // 到期时间
	Executable        bool      `json:"executable,omitempty"`        // 是否已被移入可执行作业桶
}

type ListenerControl interface {
	// SetVariable 设置流程实例级变量（写入最近已存在作用域，语义与引擎 Execution.SetVariable 一致）。
	// @param name 变量名
	// @param value 变量值
	// @return 错误（实例不存在等）
	SetVariable(name string, value any) error
	// SetVariableLocal 设置当前执行作用域变量。
	// @param name 变量名
	// @param value 变量值
	// @return 错误（执行不存在等）
	SetVariableLocal(name string, value any) error
	// Defer 登记命令提交成功后顺序执行的延迟动作（新命令上下文，锁外执行）。
	// 命令失败回滚时不执行；动作 panic 或返回错误仅记录日志，不影响已完成的命令。
	// @param action 延迟动作，入参为原命令上下文
	Defer(action func(ctx context.Context) error)
}

type ListenerExecution struct {
	ExecutionID         string         // 执行 ID
	ActivityID          string         // 当前活动 ID（活动结束监听器下为离开的节点 ID）
	ProcessInstanceID   string         // 流程实例 ID
	ProcessDefinitionID string         // 流程定义 ID
	TenantID            string         // 租户
	MIChild             bool           // 是否多实例子执行（会签监听器区分根执行与实例执行用）
	Variables           map[string]any // 执行可见变量快照（含作用域链继承值）
}

type ManagementService interface {
	// EngineInfo 返回引擎版本与配置摘要。
	// @param ctx 上下文
	// @return 引擎信息
	// @return 查询错误
	EngineInfo(ctx context.Context) (map[string]any, error)
	// RunDueJobs 执行全部到期定时器作业。
	// @param ctx 上下文
	// @return 执行数量
	// @return 执行错误
	RunDueJobs(ctx context.Context) (int, error)
	// ListJobs 返回可执行作业。
	// @param ctx 上下文
	// @return 作业列表
	// @return 查询错误
	ListJobs(ctx context.Context) ([]JobInfo, error)
	// GetJob 查询可执行作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 作业信息
	// @return 查询错误
	GetJob(ctx context.Context, jobID string) (JobInfo, error)
	// GetDeadLetterJob 查询死信作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 作业信息
	// @return 查询错误
	GetDeadLetterJob(ctx context.Context, jobID string) (JobInfo, error)
	// SetJobRetries 设置作业重试次数。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @param retries 重试次数
	// @return 设置错误
	SetJobRetries(ctx context.Context, jobID string, retries int) error
	// ListDeadLetterJobs 返回死信作业。
	// @param ctx 上下文
	// @return 死信作业列表
	// @return 查询错误
	ListDeadLetterJobs(ctx context.Context) ([]JobInfo, error)
	// MoveDeadLetterJobToExecutable 将死信作业恢复为可执行作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @param retries 恢复后的重试次数
	// @return 恢复错误
	MoveDeadLetterJobToExecutable(ctx context.Context, jobID string, retries int) error
	// DeleteJob 删除可执行作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 删除错误
	DeleteJob(ctx context.Context, jobID string) error
	// DeleteTimerJob 删除定时器作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 删除错误
	DeleteTimerJob(ctx context.Context, jobID string) error
	// DeleteSuspendedJob 删除挂起作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 删除错误
	DeleteSuspendedJob(ctx context.Context, jobID string) error
	// DeleteDeadLetterJob 删除死信作业。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 删除错误
	DeleteDeadLetterJob(ctx context.Context, jobID string) error
	// MoveTimerJobToExecutable 将定时器作业移入可执行作业桶。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @return 移动错误
	MoveTimerJobToExecutable(ctx context.Context, jobID string) error
	// RescheduleTimerJob 修改定时器作业的到期时间。
	// @param ctx 上下文
	// @param jobID 作业 ID
	// @param dueDate RFC3339 到期时间
	// @return 修改错误
	RescheduleTimerJob(ctx context.Context, jobID, dueDate string) error
	// CreateProperty 创建自定义引擎属性。
	// @param ctx 上下文
	// @param name 名称
	// @param value 值
	// @return 创建错误
	CreateProperty(ctx context.Context, name, value string) error
	// UpdateProperty 更新自定义引擎属性。
	// @param ctx 上下文
	// @param name 名称
	// @param value 值
	// @return 更新错误
	UpdateProperty(ctx context.Context, name, value string) error
	// DeleteProperty 删除自定义引擎属性。
	// @param ctx 上下文
	// @param name 名称
	// @return 删除错误
	DeleteProperty(ctx context.Context, name string) error
	// Properties 返回引擎属性键值。
	// @param ctx 上下文
	// @return 属性映射
	// @return 查询错误
	Properties(ctx context.Context) (map[string]string, error)
	// TableCount 返回各 ACT_* 表的行数。
	// @param ctx 上下文
	// @return 表名到行数
	// @return 查询错误
	TableCount(ctx context.Context) (map[string]int64, error)
	// GetTableMetaData 返回表的列元数据。
	// @param ctx 上下文
	// @param tableName 表名
	// @return 列元数据
	// @return 查询错误
	GetTableMetaData(ctx context.Context, tableName string) (TableMetaData, error)
	// QueryTableData 分页查询表数据。
	// @param ctx 上下文
	// @param tableName 表名
	// @param start 偏移
	// @param size 每页数量
	// @param sortColumn 排序列，空串表示默认顺序
	// @param order 排序方向，asc 或 desc
	// @return 分页数据
	// @return 查询错误
	QueryTableData(ctx context.Context, tableName string, start, size int, sortColumn, order string) (Page[map[string]any], error)
	// ListBatches 返回全部批处理作业。
	// @param ctx 上下文
	// @return 批次列表
	// @return 查询错误
	ListBatches(ctx context.Context) ([]Batch, error)
	// GetBatch 查询批处理作业。
	// @param ctx 上下文
	// @param batchID 批次 ID
	// @return 批次
	// @return 查询错误
	GetBatch(ctx context.Context, batchID string) (Batch, error)
	// ListBatchParts 返回批次的分片列表。
	// @param ctx 上下文
	// @param batchID 批次 ID
	// @return 分片列表
	// @return 查询错误
	ListBatchParts(ctx context.Context, batchID string) ([]BatchPart, error)
	// GetBatchPart 查询批处理分片。
	// @param ctx 上下文
	// @param partID 分片 ID
	// @return 分片
	// @return 查询错误
	GetBatchPart(ctx context.Context, partID string) (BatchPart, error)
	// DeleteBatch 删除批次及其全部分片。
	// @param ctx 上下文
	// @param batchID 批次 ID
	// @return 删除错误
	DeleteBatch(ctx context.Context, batchID string) error
	// GetBatchDocument 返回批次文档。
	// @param ctx 上下文
	// @param batchID 批次 ID
	// @return 文档字节
	// @return 查询错误
	GetBatchDocument(ctx context.Context, batchID string) ([]byte, error)
	// GetBatchPartDocument 返回批次分片文档。
	// @param ctx 上下文
	// @param partID 分片 ID
	// @return 文档字节
	// @return 查询错误
	GetBatchPartDocument(ctx context.Context, partID string) ([]byte, error)
	// BatchMigrateProcessInstances 批量迁移流程实例并记录批次与分片。
	// @param ctx 上下文
	// @param targetDefinitionID 目标流程定义 ID
	// @param instanceIDs 流程实例 ID 列表
	// @param activityMappings 源活动 ID 到目标活动 ID
	// @return 最终批次
	// @return 迁移错误
	BatchMigrateProcessInstances(ctx context.Context, targetDefinitionID string, instanceIDs []string, activityMappings map[string]string) (Batch, error)
}

type MigrationRequest struct {
	ProcessInstanceID         string            // 源实例 ID
	TargetProcessDefinitionID string            // 目标流程定义 ID
	ActivityMappings          map[string]string // 源活动 ID 到目标活动 ID
}

type Model struct {
	ID             string    `json:"id"`                     // 模型 ID
	Name           string    `json:"name"`                   // 名称
	Key            string    `json:"key"`                    // Key
	Category       string    `json:"category,omitempty"`     // 分类
	Version        int       `json:"version"`                // 版本
	MetaInfo       string    `json:"metaInfo,omitempty"`     // 元信息
	DeploymentID   string    `json:"deploymentId,omitempty"` // 部署 ID
	TenantID       string    `json:"tenantId,omitempty"`     // 租户
	CreateTime     time.Time `json:"createTime"`             // 创建时间
	LastUpdateTime time.Time `json:"lastUpdateTime"`         // 最后更新时间
}

type ModelUpdate struct {
	Name         *string // 名称
	Key          *string // Key
	Category     *string // 分类
	MetaInfo     *string // 元信息
	DeploymentID *string // 部署 ID
	TenantID     *string // 租户
	Version      *int    // 版本
}

type NextActivityRequest struct {
	TaskID           string            `json:"taskId"`                   // 当前任务 ID（必填）
	NextActivityList []*NextActivityVo `json:"nextActivityList"`         // 下一步节点与处理人列表（必填）
	SendIdentityID   string            `json:"sendIdentityId,omitempty"` // 发送人身份 Id
	SendUserName     string            `json:"sendUserName,omitempty"`   // 发送人姓名
}

type NextActivityVo struct {
	ActivityID    string   `json:"activityId"`              // 目标节点 ID（流程结束填保留代号 end）
	ActivityName  string   `json:"activityName,omitempty"`  // 目标节点名称
	ExecutorIDs   []string `json:"executorIds,omitempty"`   // 处理人身份 Id 列表
	ExecutorNames []string `json:"executorNames,omitempty"` // 处理人姓名列表（展示用）
}

type Page[T any] struct {
	Data  []T    `json:"data"`            // 数据
	Total int64  `json:"total"`           // 总数
	Start int    `json:"start"`           // 偏移
	Size  int    `json:"size"`            // 每页数量
	Sort  string `json:"sort,omitempty"`  // 排序字段
	Order string `json:"order,omitempty"` // 排序方向
}

type PageQuery struct {
	Start int `json:"start"` // 偏移量，默认 0
	Size  int `json:"size"`  // 每页数量，默认 10
}

type ProcessDefinition struct {
	ID              string `json:"id"`                        // 流程定义 ID
	Key             string `json:"key"`                       // 流程定义 Key
	Name            string `json:"name"`                      // 名称
	Description     string `json:"description,omitempty"`     // 流程说明
	Version         int    `json:"version"`                   // 版本
	DeploymentID    string `json:"deploymentId"`              // 部署 ID
	ResourceName    string `json:"resourceName"`              // 资源名
	TenantID        string `json:"tenantId"`                  // 租户
	Suspended       bool   `json:"suspended"`                 // 是否挂起
	DerivedFrom     string `json:"derivedFrom,omitempty"`     // 直接来源定义，非空表示实例专用派生定义
	DerivedFromRoot string `json:"derivedFromRoot,omitempty"` // 最初来源定义
	DerivedVersion  int    `json:"derivedVersion,omitempty"`  // 派生次数，不参与普通定义版本选择
}

type ProcessInstance struct {
	ID                        string         `json:"id"`                                  // 实例 ID
	ProcessDefinitionID       string         `json:"processDefinitionId"`                 // 流程定义 ID
	ProcessDefinitionKey      string         `json:"processDefinitionKey"`                // 流程定义 Key
	BusinessKey               string         `json:"businessKey"`                         // 业务键
	Name                      string         `json:"name"`                                // 实例名称
	ActivityID                string         `json:"activityId,omitempty"`                // 根执行当前活动
	StartUserID               string         `json:"startUserId,omitempty"`               // 发起人
	BusinessStatus            string         `json:"businessStatus,omitempty"`            // 业务状态
	DueDate                   *time.Time     `json:"dueDate,omitempty"`                   // 截止时间
	ClaimTime                 *time.Time     `json:"claimTime,omitempty"`                 // 签收时间
	ClaimedBy                 string         `json:"claimedBy,omitempty"`                 // 签收人
	CallbackID                string         `json:"callbackId,omitempty"`                // 回调标识
	CallbackType              string         `json:"callbackType,omitempty"`              // 回调类型
	ReferenceID               string         `json:"referenceId,omitempty"`               // 关联标识
	ReferenceType             string         `json:"referenceType,omitempty"`             // 关联类型
	PropagatedStageInstanceID string         `json:"propagatedStageInstanceId,omitempty"` // 传播阶段标识
	SuperProcessInstanceID    string         `json:"superProcessInstanceId,omitempty"`    // 父流程实例标识
	TenantID                  string         `json:"tenantId"`                            // 租户
	StartTime                 time.Time      `json:"startTime"`                           // 开始时间
	EndTime                   *time.Time     `json:"endTime,omitempty"`                   // 结束时间
	Ended                     bool           `json:"ended"`                               // 是否结束
	Suspended                 bool           `json:"suspended"`                           // 是否挂起
	Variables                 map[string]any `json:"variables,omitempty"`                 // 变量快照
}

type ProcessInstanceFilter struct {
	ID                   string     // 流程实例 ID
	ProcessDefinitionID  string     // 流程定义 ID
	ProcessDefinitionKey string     // 流程定义 Key
	BusinessKey          string     // 业务键
	TenantID             string     // 租户，空表示不过滤
	Suspended            *bool      // 是否挂起，空表示不过滤
	StartedAfter         *time.Time // 开始时间下界，含边界
	StartedBefore        *time.Time // 开始时间上界，含边界
	Start                int        // 偏移量
	Size                 int        // 每页数量
}

type ProcessInstanceUpdate struct {
	Name           *string    // 实例名称
	BusinessKey    *string    // 业务键
	BusinessStatus *string    // 业务状态
	DueDate        *time.Time // 截止时间
	ClaimUserID    *string    // 签收人，空字符串表示取消签收
}

type R struct {
	Code         string `json:"code"`                   // 状态码："200" 成功 / "500" 失败
	Msg          string `json:"msg,omitempty"`          // 成功消息
	ErrorMessage string `json:"ErrorMessage,omitempty"` // 失败消息（字段名大写 E 兼容 Java 协议）
	Data         any    `json:"data,omitempty"`         // 业务数据
	Success      bool   `json:"success"`                // 是否成功
}

type RepositoryService interface {
	// Deploy 部署 BPMN 资源。
	// @param ctx 上下文
	// @param req 部署请求
	// @return 部署信息
	// @return 部署错误
	Deploy(ctx context.Context, req DeploymentRequest) (Deployment, error)
	// ListProcessDefinitions 返回全部流程定义。
	// @param ctx 上下文
	// @return 流程定义列表
	// @return 查询错误
	ListProcessDefinitions(ctx context.Context) ([]ProcessDefinition, error)
	// GetProcessDefinition 按 ID 查询流程定义。
	// @param ctx 上下文
	// @param id 流程定义 ID
	// @return 流程定义
	// @return 查询错误
	GetProcessDefinition(ctx context.Context, id string) (ProcessDefinition, error)
	// GetProcessDefinitionByKey 按 Key 查询最新流程定义。
	// @param ctx 上下文
	// @param key 流程定义 Key
	// @return 流程定义
	// @return 查询错误
	GetProcessDefinitionByKey(ctx context.Context, key string) (ProcessDefinition, error)
	// GetBpmnModel 返回流程定义对应的 BPMN 模型。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @return BPMN 模型
	// @return 查询错误
	GetBpmnModel(ctx context.Context, definitionID string) (*model.BpmnModel, error)
	// GetProcessDefinitionXML 返回流程定义原始 XML。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @return XML 内容
	// @return 查询错误
	GetProcessDefinitionXML(ctx context.Context, definitionID string) ([]byte, error)
	// ListDeployments 返回全部部署。
	// @param ctx 上下文
	// @return 部署列表
	// @return 查询错误
	ListDeployments(ctx context.Context) ([]Deployment, error)
	// GetDeployment 查询部署。
	// @param ctx 上下文
	// @param deploymentID 部署 ID
	// @return 部署信息
	// @return 查询错误
	GetDeployment(ctx context.Context, deploymentID string) (Deployment, error)
	// ListDeploymentResources 返回部署资源名列表。
	// @param ctx 上下文
	// @param deploymentID 部署 ID
	// @return 资源名列表
	// @return 查询错误
	ListDeploymentResources(ctx context.Context, deploymentID string) ([]string, error)
	// GetDeploymentResource 返回部署资源内容。
	// @param ctx 上下文
	// @param deploymentID 部署 ID
	// @param resourceName 资源名
	// @return 资源内容
	// @return 查询错误
	GetDeploymentResource(ctx context.Context, deploymentID, resourceName string) ([]byte, error)
	// DeleteDeployment 删除部署。
	// @param ctx 上下文
	// @param deploymentID 部署 ID
	// @param cascade 是否级联删除流程定义
	// @return 删除错误
	DeleteDeployment(ctx context.Context, deploymentID string, cascade bool) error
	// SuspendProcessDefinition 挂起流程定义。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @param includeInstances 是否同时挂起实例
	// @return 挂起错误
	SuspendProcessDefinition(ctx context.Context, definitionID string, includeInstances bool) error
	// ActivateProcessDefinition 激活流程定义。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @param includeInstances 是否同时激活实例
	// @return 激活错误
	ActivateProcessDefinition(ctx context.Context, definitionID string, includeInstances bool) error
	// ListModels 返回全部流程模型。
	// @param ctx 上下文
	// @return 模型列表
	// @return 查询错误
	ListModels(ctx context.Context) ([]Model, error)
	// GetModel 查询流程模型。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @return 模型
	// @return 查询错误
	GetModel(ctx context.Context, modelID string) (Model, error)
	// CreateModel 创建流程模型。
	// @param ctx 上下文
	// @param req 创建请求
	// @return 模型
	// @return 创建错误
	CreateModel(ctx context.Context, req CreateModelRequest) (Model, error)
	// UpdateModel 更新流程模型。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @param update 更新内容
	// @return 更新后的模型
	// @return 更新错误
	UpdateModel(ctx context.Context, modelID string, update ModelUpdate) (Model, error)
	// DeleteModel 删除流程模型。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @return 删除错误
	DeleteModel(ctx context.Context, modelID string) error
	// GetModelSource 返回模型编辑源。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @return 源内容
	// @return 查询错误
	GetModelSource(ctx context.Context, modelID string) ([]byte, error)
	// SetModelSource 设置模型编辑源。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @param source 源内容
	// @return 设置错误
	SetModelSource(ctx context.Context, modelID string, source []byte) error
	// GetModelSourceExtra 返回模型扩展源码。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @return 扩展源
	// @return 查询错误
	GetModelSourceExtra(ctx context.Context, modelID string) ([]byte, error)
	// SetModelSourceExtra 设置模型扩展源码。
	// @param ctx 上下文
	// @param modelID 模型 ID
	// @param source 扩展源
	// @return 设置错误
	SetModelSourceExtra(ctx context.Context, modelID string, source []byte) error
	// ListDefinitionIdentityLinks 返回流程定义候选发起人。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @return 链接列表
	// @return 查询错误
	ListDefinitionIdentityLinks(ctx context.Context, definitionID string) ([]IdentityLink, error)
	// GetDefinitionIdentityLink 查询单个候选发起人。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @param family users 或 groups
	// @param identityID 用户或组 ID
	// @return 链接
	// @return 查询错误
	GetDefinitionIdentityLink(ctx context.Context, definitionID, family, identityID string) (IdentityLink, error)
	// AddDefinitionIdentityLink 添加候选发起人。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @param link 链接
	// @return 创建后的链接
	// @return 创建错误
	AddDefinitionIdentityLink(ctx context.Context, definitionID string, link IdentityLink) (IdentityLink, error)
	// DeleteDefinitionIdentityLink 删除候选发起人。
	// @param ctx 上下文
	// @param definitionID 流程定义 ID
	// @param family users 或 groups
	// @param identityID 用户或组 ID
	// @return 删除错误
	DeleteDefinitionIdentityLink(ctx context.Context, definitionID, family, identityID string) error
}

type Role struct {
	ID          string   `json:"id"`                    // 角色 ID
	Name        string   `json:"name,omitempty"`        // 名称
	Permissions []string `json:"permissions,omitempty"` // 权限
	TenantID    string   `json:"tenantId,omitempty"`    // 租户
}

type RuntimeService interface {
	// UpdateProcessInstance 在单次事务中更新流程实例属性或签收状态。
	// @param ctx 请求上下文
	// @param id 实例标识
	// @param update 属性更新或签收请求
	// @return 更新后的实例
	// @return 更新错误
	UpdateProcessInstance(ctx context.Context, id string, update ProcessInstanceUpdate) (ProcessInstance, error)
	// SetVariablesAsync 在命令事务中排队变量更新，由作业执行器异步应用。
	// @param ctx 上下文
	// @param request 变量更新及请求阶段校验条件
	// @return 排队错误
	SetVariablesAsync(ctx context.Context, request AsyncVariableRequest) error
	// StartProcessInstance 启动流程实例。
	// @param ctx 上下文
	// @param req 启动请求
	// @return 流程实例
	// @return 启动错误
	StartProcessInstance(ctx context.Context, req StartRequest) (ProcessInstance, error)
	// GetProcessInstance 查询流程实例。
	// @param ctx 上下文
	// @param id 实例 ID
	// @return 流程实例
	// @return 查询错误
	GetProcessInstance(ctx context.Context, id string) (ProcessInstance, error)
	// ListExecutions 返回指定实例的执行树。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID，空串表示全部
	// @return 执行列表
	// @return 查询错误
	ListExecutions(ctx context.Context, processInstanceID string) ([]ExecutionInfo, error)
	// GetExecutionVariables 返回执行可见变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @return 变量快照
	// @return 查询错误
	GetExecutionVariables(ctx context.Context, executionID string) (map[string]any, error)
	// GetExecutionVariable 返回执行可见变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param name 变量名
	// @return 变量值
	// @return 查询错误
	GetExecutionVariable(ctx context.Context, executionID, name string) (any, error)
	// SetExecutionVariable 设置执行局部变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param name 变量名
	// @param value 变量值
	// @return 设置错误
	SetExecutionVariable(ctx context.Context, executionID, name string, value any) error
	// DeleteExecutionVariable 删除执行局部变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param name 变量名
	// @return 删除错误
	DeleteExecutionVariable(ctx context.Context, executionID, name string) error
	// DeleteAllExecutionVariables 清空执行局部变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @return 删除错误
	DeleteAllExecutionVariables(ctx context.Context, executionID string) error
	// DeleteAllInstanceVariables 清空流程实例变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 删除错误
	DeleteAllInstanceVariables(ctx context.Context, processInstanceID string) error
	// GetExecution 查询执行。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @return 执行信息
	// @return 查询错误
	GetExecution(ctx context.Context, executionID string) (ExecutionInfo, error)
	// ListProcessInstances 返回全部运行中实例。
	// @param ctx 上下文
	// @return 实例列表
	// @return 查询错误
	ListProcessInstances(ctx context.Context) ([]ProcessInstance, error)
	// QueryProcessInstances 按条件分页查询运行中实例；行模式下等值与时间条件可下推 SQL。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页实例
	// @return 查询错误
	QueryProcessInstances(ctx context.Context, filter ProcessInstanceFilter) (Page[ProcessInstance], error)
	// DeleteProcessInstance 删除流程实例。
	// @param ctx 上下文
	// @param id 实例 ID
	// @param reason 删除原因
	// @return 删除错误
	DeleteProcessInstance(ctx context.Context, id, reason string) error
	// GetVariables 返回实例可见变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 变量快照
	// @return 查询错误
	GetVariables(ctx context.Context, processInstanceID string) (map[string]any, error)
	// GetVariable 返回流程实例变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param name 变量名
	// @return 变量值
	// @return 查询错误
	GetVariable(ctx context.Context, processInstanceID, name string) (any, error)
	// SetVariable 设置流程实例变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param name 变量名
	// @param value 变量值
	// @return 设置错误
	SetVariable(ctx context.Context, processInstanceID, name string, value any) error
	// DeleteVariable 删除流程实例变量。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param name 变量名
	// @return 删除错误
	DeleteVariable(ctx context.Context, processInstanceID, name string) error
	// MessageEventReceived 投递消息，触发一个匹配订阅。
	// @param ctx 上下文
	// @param messageName 消息名
	// @param variables 变量
	// @return 触发数量
	// @return 投递错误
	MessageEventReceived(ctx context.Context, messageName string, variables []Variable) (int, error)
	// SignalEventReceived 广播信号，触发全部匹配订阅。
	// @param ctx 上下文
	// @param signalName 信号名
	// @param variables 变量
	// @return 触发数量
	// @return 投递错误
	SignalEventReceived(ctx context.Context, signalName string, variables []Variable) (int, error)
	// MessageEventReceivedForExecution 向指定执行投递消息。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param messageName 消息名
	// @param variables 变量
	// @return 投递错误
	MessageEventReceivedForExecution(ctx context.Context, executionID, messageName string, variables []Variable) error
	// SignalEventReceivedForExecution 向指定执行投递信号。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param signalName 信号名
	// @param variables 变量
	// @return 投递错误
	SignalEventReceivedForExecution(ctx context.Context, executionID, signalName string, variables []Variable) error
	// TriggerExecution 触发等待中的执行。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param variables 写入变量
	// @return 触发错误
	TriggerExecution(ctx context.Context, executionID string, variables []Variable) error
	// TriggerExecutionWithTransient 触发等待中的执行并写入瞬态变量。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param variables 持久变量
	// @param transientVariables 瞬态变量
	// @return 触发错误
	TriggerExecutionWithTransient(ctx context.Context, executionID string, variables, transientVariables []Variable) error
	// SuspendProcessInstance 挂起流程实例。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 挂起错误
	SuspendProcessInstance(ctx context.Context, processInstanceID string) error
	// ActivateProcessInstance 激活流程实例。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 激活错误
	ActivateProcessInstance(ctx context.Context, processInstanceID string) error
	// MigrateProcessInstance 将运行中实例迁移到目标流程定义。
	// @param ctx 上下文
	// @param req 迁移请求
	// @return 迁移错误
	MigrateProcessInstance(ctx context.Context, req MigrationRequest) error
	// ValidateMigration 校验实例迁移，不修改状态。
	// @param ctx 上下文
	// @param req 迁移请求
	// @return 校验消息
	// @return 查询错误
	ValidateMigration(ctx context.Context, req MigrationRequest) ([]string, error)
	// ChangeActivityState 将执行移动到新的活动。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @param activityIDs 目标活动 ID 列表
	// @return 迁移错误
	ChangeActivityState(ctx context.Context, executionID string, activityIDs []string) error
	// DoMoveActivity 普通节点跳转（对位 Java moveActivity：按来源活动定位执行并迁移到目标活动；
	// 挂起实例拒绝，多条并行分支收拢显式拒绝）。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param fromActivityID 来源活动 ID
	// @param toActivityID 目标活动 ID
	// @return 迁移错误
	DoMoveActivity(ctx context.Context, processInstanceID, fromActivityID, toActivityID string) error
	// DoMoveExecution 执行迁移（对位 Java moveExecution：无来源节点，把实例根执行迁移到目标活动）。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param toActivityID 目标活动 ID
	// @return 迁移错误
	DoMoveExecution(ctx context.Context, processInstanceID, toActivityID string) error
	// ChangeProcessInstanceState 将实例根执行移动到新的活动。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param activityIDs 目标活动 ID 列表
	// @return 迁移错误
	ChangeProcessInstanceState(ctx context.Context, processInstanceID string, activityIDs []string) error
	// ListInstanceIdentityLinks 返回流程实例身份链接。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 链接列表
	// @return 查询错误
	ListInstanceIdentityLinks(ctx context.Context, processInstanceID string) ([]IdentityLink, error)
	// AddInstanceIdentityLink 添加流程实例身份链接。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param link 链接
	// @return 创建后的链接
	// @return 创建错误
	AddInstanceIdentityLink(ctx context.Context, processInstanceID string, link IdentityLink) (IdentityLink, error)
	// DeleteInstanceIdentityLink 删除流程实例身份链接。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param family users 或 groups
	// @param identityID 用户或组 ID
	// @param linkType 链接类型
	// @return 删除错误
	DeleteInstanceIdentityLink(ctx context.Context, processInstanceID, family, identityID, linkType string) error
	// ListEventSubscriptions 返回事件订阅。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID，空串表示全部
	// @return 订阅列表
	// @return 查询错误
	ListEventSubscriptions(ctx context.Context, processInstanceID string) ([]EventSubscription, error)
	// ListActivityInstances 返回运行中活动实例。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID，空串表示全部
	// @return 活动实例列表
	// @return 查询错误
	ListActivityInstances(ctx context.Context, processInstanceID string) ([]ActivityInstance, error)
	// GetActiveActivityIDs 返回执行及子执行的活动 ID。
	// @param ctx 上下文
	// @param executionID 执行 ID
	// @return 活动 ID 列表
	// @return 查询错误
	GetActiveActivityIDs(ctx context.Context, executionID string) ([]string, error)
	// ListVariableInstances 返回运行时变量实例。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 变量实例列表
	// @return 查询错误
	ListVariableInstances(ctx context.Context, filter VariableInstanceFilter) ([]VariableInstance, error)
	// GetVariableInstance 查询运行时变量实例。
	// @param ctx 上下文
	// @param variableID 变量实例 ID
	// @return 变量实例
	// @return 查询错误
	GetVariableInstance(ctx context.Context, variableID string) (VariableInstance, error)
	// GetEventSubscription 查询事件订阅。
	// @param ctx 上下文
	// @param subscriptionID 订阅 ID
	// @return 订阅
	// @return 查询错误
	GetEventSubscription(ctx context.Context, subscriptionID string) (EventSubscription, error)
	// EvaluateConditions 显式求值流程实例的全部条件事件订阅。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @return 求值错误
	EvaluateConditions(ctx context.Context, processInstanceID string) error
	// InjectUserTask 在流程实例中注入动态用户任务。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param req 注入请求
	// @return 任务
	// @return 注入错误
	InjectUserTask(ctx context.Context, processInstanceID string, req InjectRequest) (Task, error)
	// InjectUserTaskAfter 为指定实例派生定义，在用户节点后插入新用户节点。
	// @param ctx 上下文
	// @param processInstanceID 运行实例ID
	// @param req 节点及预期定义
	// @return 实例专用派生定义
	// @return 校验或持久化错误
	InjectUserTaskAfter(ctx context.Context, processInstanceID string, req InsertUserTaskRequest) (ProcessDefinition, error)
}

type StartProcessInstanceVo struct {
	ProcessDefinitionKey string         `json:"processDefinitionKey"` // 流程定义 Key（必填）
	Title                string         `json:"title"`                // 实例标题（必填，同时写入实例名）
	Operator             string         `json:"operator"`             // 发起人身份 Id（必填）
	TenantID             string         `json:"tenantId"`             // 租户 = 业务系统代号 systemSymbol（必填）
	BusinessKey          string         `json:"businessKey"`          // 业务单据 ID（必填）
	Remark               string         `json:"remark,omitempty"`     // 备注
	Variables            map[string]any `json:"variables,omitempty"`  // 附加流程变量（entity/tableName 等由业务方注入）
}

type StartRequest struct {
	ProcessDefinitionKey string     // 流程定义 Key
	ProcessDefinitionID  string     // 流程定义 ID，优先于 Key
	MessageName          string     // 消息开始事件名称，无定义 ID 或 Key 时使用
	BusinessKey          string     // 业务键
	Name                 string     // 实例名称
	TenantID             string     // 租户
	UserID               string     // 发起人，用于参与者身份链接
	Variables            []Variable // 启动变量
	TransientVariables   []Variable // 瞬态变量，仅启动命令内可见
}

type TableInfo struct {
	Name  string `json:"name"`          // 表名
	Count int64  `json:"count"`         // 行数
	URL   string `json:"url,omitempty"` // 资源地址
}

type TableMetaData struct {
	TableName   string   `json:"tableName"`   // 表名
	ColumnNames []string `json:"columnNames"` // 列名
	ColumnTypes []string `json:"columnTypes"` // 列类型
}

type Task struct {
	ID                  string         `json:"id"`                        // 任务 ID
	ExecutionID         string         `json:"executionId,omitempty"`     // 所属执行 ID
	ClaimTime           *time.Time     `json:"claimTime,omitempty"`       // 最近签收时间
	Suspended           bool           `json:"suspended,omitempty"`       // 所属实例是否挂起
	Name                string         `json:"name"`                      // 任务名称
	Description         string         `json:"description"`               // 描述
	ProcessInstanceID   string         `json:"processInstanceId"`         // 流程实例 ID
	ProcessDefinitionID string         `json:"processDefinitionId"`       // 流程定义 ID
	TaskDefinitionKey   string         `json:"taskDefinitionKey"`         // BPMN 任务 ID
	Assignee            string         `json:"assignee,omitempty"`        // 处理人
	Owner               string         `json:"owner,omitempty"`           // 所有者
	DelegationState     string         `json:"delegationState,omitempty"` // 委派状态：PENDING/RESOLVED
	Priority            int            `json:"priority"`                  // 优先级
	FormKey             string         `json:"formKey,omitempty"`         // 表单 Key
	Category            string         `json:"category,omitempty"`        // 分类
	ParentTaskID        string         `json:"parentTaskId,omitempty"`    // 父任务 ID
	TenantID            string         `json:"tenantId,omitempty"`        // 租户
	CreateTime          time.Time      `json:"createTime"`                // 创建时间
	DueDate             *time.Time     `json:"dueDate,omitempty"`         // 到期时间
	CandidateUsers      []string       `json:"candidateUsers,omitempty"`  // 候选用户
	CandidateGroups     []string       `json:"candidateGroups,omitempty"` // 候选组
	Variables           map[string]any `json:"variables,omitempty"`       // 任务变量
}

type TaskEvent struct {
	ID                  int64     `json:"id"`                            // 事件 ID
	Action              string    `json:"action"`                        // 动作
	Timestamp           time.Time `json:"timestamp"`                     // 发生时间
	UserID              string    `json:"userId,omitempty"`              // 操作人
	TaskID              string    `json:"taskId,omitempty"`              // 任务 ID
	ExecutionID         string    `json:"executionId,omitempty"`         // 执行 ID
	ProcessInstanceID   string    `json:"processInstanceId,omitempty"`   // 流程实例 ID
	ProcessDefinitionID string    `json:"processDefinitionId,omitempty"` // 流程定义 ID
	TenantID            string    `json:"tenantId,omitempty"`            // 租户
	Data                string    `json:"data,omitempty"`                // 附加数据
}

type TaskFilter struct {
	Assignee             string // 处理人
	Owner                string // 所有者
	ProcessInstanceID    string // 流程实例 ID
	ProcessDefinitionKey string // 流程定义 Key
	CandidateUser        string // 候选人
	ParentTaskID         string // 父任务 ID
	DelegationState      string // 委派状态
	TenantID             string // 租户
	Start                int    // 偏移量
	Size                 int    // 每页数量
}

type TaskHook func(ctx context.Context, task *Task, ctl HookControl) error

type TaskListener func(ctx context.Context, task *Task) error

type TaskService interface {
	// ListTasks 按条件查询任务。
	// @param ctx 上下文
	// @param filter 查询条件
	// @return 分页结果
	// @return 查询错误
	ListTasks(ctx context.Context, filter TaskFilter) (Page[Task], error)
	// GetTask 查询任务。
	// @param ctx 上下文
	// @param id 任务 ID
	// @return 任务
	// @return 查询错误
	GetTask(ctx context.Context, id string) (Task, error)
	// CreateTask 创建独立任务。
	// @param ctx 上下文
	// @param req 创建请求
	// @return 任务
	// @return 创建错误
	CreateTask(ctx context.Context, req CreateTaskRequest) (Task, error)
	// UpdateTask 更新任务属性。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param update 更新内容
	// @return 更新后的任务
	// @return 更新错误
	UpdateTask(ctx context.Context, taskID string, update TaskUpdate) (Task, error)
	// DeleteTask 删除任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param cascadeHistory 是否级联删除历史
	// @param deleteReason 删除原因
	// @return 删除错误
	DeleteTask(ctx context.Context, taskID string, cascadeHistory bool, deleteReason string) error
	// ListSubTasks 返回子任务。
	// @param ctx 上下文
	// @param taskID 父任务 ID
	// @return 子任务列表
	// @return 查询错误
	ListSubTasks(ctx context.Context, taskID string) ([]Task, error)
	// Claim 签收任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 签收人
	// @return 签收错误
	Claim(ctx context.Context, taskID, userID string) error
	// Complete 完成任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param req 完成请求
	// @return 完成错误
	Complete(ctx context.Context, taskID string, req CompleteTaskRequest) error
	// GetTaskVariable 返回任务变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param name 变量名
	// @return 变量值
	// @return 查询错误
	GetTaskVariable(ctx context.Context, taskID, name string) (any, error)
	// GetTaskVariables 返回任务可见变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 变量快照
	// @return 查询错误
	GetTaskVariables(ctx context.Context, taskID string) (map[string]any, error)
	// SetTaskVariable 设置任务局部变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param name 变量名
	// @param value 变量值
	// @return 设置错误
	SetTaskVariable(ctx context.Context, taskID, name string, value any) error
	// DeleteTaskVariable 删除任务局部变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param name 变量名
	// @return 删除错误
	DeleteTaskVariable(ctx context.Context, taskID, name string) error
	// DeleteAllTaskVariables 清空任务局部变量。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 删除错误
	DeleteAllTaskVariables(ctx context.Context, taskID string) error
	// ListTaskEvents 返回任务事件。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 事件列表
	// @return 查询错误
	ListTaskEvents(ctx context.Context, taskID string) ([]TaskEvent, error)
	// GetTaskEvent 查询单个任务事件。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param eventID 事件 ID
	// @return 事件
	// @return 查询错误
	GetTaskEvent(ctx context.Context, taskID string, eventID int64) (TaskEvent, error)
	// DeleteTaskEvent 删除任务事件。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param eventID 事件 ID
	// @return 删除错误
	DeleteTaskEvent(ctx context.Context, taskID string, eventID int64) error
	// ListIdentityLinks 返回任务参与者关联。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 关联列表
	// @return 查询错误
	ListIdentityLinks(ctx context.Context, taskID string) ([]IdentityLink, error)
	// AddCandidateUser 添加候选用户。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 用户 ID
	// @return 添加错误
	AddCandidateUser(ctx context.Context, taskID, userID string) error
	// DeleteCandidateUser 移除候选用户。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 用户 ID
	// @return 删除错误
	DeleteCandidateUser(ctx context.Context, taskID, userID string) error
	// AddCandidateGroup 添加候选组。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param groupID 组 ID
	// @return 添加错误
	AddCandidateGroup(ctx context.Context, taskID, groupID string) error
	// DeleteCandidateGroup 移除候选组。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param groupID 组 ID
	// @return 删除错误
	DeleteCandidateGroup(ctx context.Context, taskID, groupID string) error
	// Delegate 委派任务。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 被委托人
	// @return 委派错误
	Delegate(ctx context.Context, taskID, userID string) error
	// Resolve 处理委派任务，将处理人恢复为所有者。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 操作人，非空时必须为所有者
	// @return 处理错误
	Resolve(ctx context.Context, taskID, userID string) error
	// ResolveWithVariables 处理委派任务并同步写入任务局部变量（对位 Activiti resolveTask(taskId, variables)，
	// 供 Java 契约 ProcessesUtil#resolveTask:2318 使用；变量写入与归还状态变更在同一命令事务内生效）。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 操作人，非空时必须为所有者
	// @param variables 任务局部变量集合（可空）
	// @return 处理错误
	ResolveWithVariables(ctx context.Context, taskID, userID string, variables []Variable) error
	// IsMultiInstanceLastPerson 判断任务是否为其节点的最后一名待办成员（对位 Java
	// ProcessesUtil#isMultiInstanceLastPerson：非会签用户任务恒 true；会签按完成条件比例
	// 以 (completed+1)/all 整数除法判定；无完成条件或非用户任务返回 false；任务不存在返回 false）。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 是否最后一名待办成员
	// @return 查询错误
	IsMultiInstanceLastPerson(ctx context.Context, taskID string) (bool, error)
	// AddComment 添加任务评论。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param userID 作者
	// @param message 内容
	// @return 评论
	// @return 添加错误
	AddComment(ctx context.Context, taskID, userID, message string) (Comment, error)
	// AddCommentDetail 添加评论并显式指定类型与完整原文（对位 Java AddHisCommentCmd：
	// TYPE_ 缺省 SP、MESSAGE_ 存归一化内容、FULL_MSG_ 存原文、ACTION_='AddComment'）。
	// @param ctx 上下文
	// @param taskID 任务 ID（任务级评论，可为空）
	// @param processInstanceID 流程实例 ID（taskID 为空时必填）
	// @param userID 作者
	// @param typ 类型代码（空时默认 SP）
	// @param message 归一化后的展示内容
	// @param fullMessage 原始内容
	// @return 评论
	// @return 添加错误
	AddCommentDetail(ctx context.Context, taskID, processInstanceID, userID, typ, message, fullMessage string) (Comment, error)
	// AddProcessComment 添加流程实例评论。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param userID 作者
	// @param message 内容
	// @return 评论
	// @return 添加错误
	AddProcessComment(ctx context.Context, processInstanceID, userID, message string) (Comment, error)
	// ListProcessComments 返回流程实例评论。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 评论列表
	// @return 查询错误
	ListProcessComments(ctx context.Context, processInstanceID string) ([]Comment, error)
	// ListInstanceComments 返回流程实例下的全部评论，含任务评论。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 评论列表
	// @return 查询错误
	ListInstanceComments(ctx context.Context, processInstanceID string) ([]Comment, error)
	// ListComments 返回任务评论。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 评论列表
	// @return 查询错误
	ListComments(ctx context.Context, taskID string) ([]Comment, error)
	// GetComment 查询单条评论。
	// @param ctx 上下文
	// @param commentID 评论 ID
	// @return 评论
	// @return 查询错误
	GetComment(ctx context.Context, commentID string) (Comment, error)
	// DeleteComment 删除评论。
	// @param ctx 上下文
	// @param commentID 评论 ID
	// @return 删除错误
	DeleteComment(ctx context.Context, commentID string) error
	// AddProcessAttachment 添加流程实例附件。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param attachment 附件
	// @return 附件
	// @return 添加错误
	AddProcessAttachment(ctx context.Context, processInstanceID string, attachment Attachment) (Attachment, error)
	// ListProcessAttachments 返回流程实例附件。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 附件列表
	// @return 查询错误
	ListProcessAttachments(ctx context.Context, processInstanceID string) ([]Attachment, error)
	// AddAttachment 添加任务附件。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param attachment 附件
	// @return 附件
	// @return 添加错误
	AddAttachment(ctx context.Context, taskID string, attachment Attachment) (Attachment, error)
	// DeleteAttachment 删除附件。
	// @param ctx 上下文
	// @param attachmentID 附件 ID
	// @return 删除错误
	DeleteAttachment(ctx context.Context, attachmentID string) error
	// ListAttachments 返回任务附件。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 附件列表
	// @return 查询错误
	ListAttachments(ctx context.Context, taskID string) ([]Attachment, error)
	// GetAttachment 查询单个附件。
	// @param ctx 上下文
	// @param attachmentID 附件 ID
	// @return 附件
	// @return 查询错误
	GetAttachment(ctx context.Context, attachmentID string) (Attachment, error)
	// SetAttachmentContent 设置附件二进制内容。
	// @param ctx 上下文
	// @param attachmentID 附件 ID
	// @param data 内容
	// @return 设置错误
	SetAttachmentContent(ctx context.Context, attachmentID string, data []byte) error
	// GetAttachmentContent 返回附件二进制内容。
	// @param ctx 上下文
	// @param attachmentID 附件 ID
	// @return 内容
	// @return 查询错误
	GetAttachmentContent(ctx context.Context, attachmentID string) ([]byte, error)
	// RegisterTaskListener 注册 BPMN 任务监听器。
	// @param name 监听器名（class/delegateExpression）
	// @param listener 监听器
	RegisterTaskListener(name string, listener TaskListener)
}

type TaskUpdate struct {
	Name         *string    // 名称
	Description  *string    // 描述
	Assignee     *string    // 处理人
	Owner        *string    // 所有者
	Priority     *int       // 优先级
	DueDate      *time.Time // 到期时间
	ClearDueDate bool       // 清空到期时间
	Category     *string    // 分类
	FormKey      *string    // 表单 Key
	UserID       string     // 操作人，用于审计日志
}

type User struct {
	ID             string     `json:"id"`                    // 用户 ID
	FirstName      string     `json:"firstName,omitempty"`   // 名
	LastName       string     `json:"lastName,omitempty"`    // 姓
	DisplayName    string     `json:"displayName,omitempty"` // 显示名
	Email          string     `json:"email,omitempty"`       // 邮箱
	Password       string     `json:"password,omitempty"`    // 明文密码（仅写入）
	PasswordHash   string     `json:"-"`                     // 密码哈希
	Roles          []string   `json:"roles,omitempty"`       // 角色
	Disabled       bool       `json:"disabled,omitempty"`    // 是否禁用
	FailedAttempts int        `json:"-"`                     // 连续失败次数
	LockedUntil    *time.Time `json:"-"`                     // 锁定截止时间
	TenantID       string     `json:"tenantId,omitempty"`    // 租户
}

type Variable struct {
	Name  string `json:"name"`            // 变量名
	Type  string `json:"type,omitempty"`  // 类型，留空由引擎推断
	Value any    `json:"value"`           // 变量值
	Scope string `json:"scope,omitempty"` // global 或 local
}

type VariableConflictError struct {
	Name        string // 冲突的变量名称
	ExecutionID string // 请求操作的执行标识
}

type VariableInstance struct {
	ID                string `json:"id"`                          // 变量实例 ID
	Name              string `json:"name"`                        // 变量名
	Type              string `json:"type,omitempty"`              // 变量类型
	Value             any    `json:"value,omitempty"`             // 变量值
	ProcessInstanceID string `json:"processInstanceId,omitempty"` // 流程实例 ID
	ExecutionID       string `json:"executionId,omitempty"`       // 执行 ID
	TaskID            string `json:"taskId,omitempty"`            // 任务 ID
	Scope             string `json:"scope,omitempty"`             // 作用域
}

type VariableInstanceFilter struct {
	ProcessInstanceID string // 流程实例 ID
	ExecutionID       string // 执行 ID
	TaskID            string // 任务 ID
	Name              string // 变量名
	NameLike          string // 变量名模糊匹配
}

type WorkflowExtService interface {
	// BackUserTaskToActivity 任意退回：把当前任务退回到目标活动。
	// @param ctx 上下文
	// @param taskID 当前运行任务 ID
	// @param targetActivityID 目标活动 ID
	// @return 实际落位节点 ID
	// @return 退回错误
	BackUserTaskToActivity(ctx context.Context, taskID, targetActivityID string) (string, error)
	// RollbackTask 撤回：把已完成的当前任务撤回到待办状态，删除其后继任务与历史。
	// @param ctx 上下文
	// @param taskID 已完成任务的 ID（历史任务 ID）
	// @param assignee 撤回后任务的办理人，空串取历史任务办理人
	// @return 撤回错误
	RollbackTask(ctx context.Context, taskID, assignee string) error
	// CompleteToTarget 直送：办结当前任务并把执行迁移到目标活动继续。
	// @param ctx 上下文
	// @param taskID 当前运行任务 ID
	// @param targetActivityID 目标活动 ID
	// @param variables 直送时写入的流程变量
	// @return 直送错误
	CompleteToTarget(ctx context.Context, taskID, targetActivityID string, variables map[string]any) error
	// ResetProcess 重置流程：清场全部活动任务并把全部执行迁回开始事件的首个出线目标。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @param operator 操作人（业务操作记录由 workflow 层落库）
	// @return 重置错误
	ResetProcess(ctx context.Context, processInstanceID, operator string) error
	// StopProcessToEvent 软终止：全部活动执行迁至首个正常结束事件走完，保留 end 事件历史。
	// @param ctx 上下文
	// @param processInstanceID 实例 ID
	// @return 终止错误
	StopProcessToEvent(ctx context.Context, processInstanceID string) error
	// ReactivateProcessInstance 历史实例复活：按历史实例重建运行实例并可指定落位活动。
	// @param ctx 上下文
	// @param historicProcessInstanceID 历史实例 ID
	// @param targetActivityID 落位活动 ID，空串表示回开始事件后首个用户任务
	// @param operator 操作人（重写发起人）
	// @return 复活错误
	ReactivateProcessInstance(ctx context.Context, historicProcessInstanceID, targetActivityID, operator string) error
}

type WorkflowFacade interface {

	// StartProcess 发起流程实例（注入 initiator/businessKey/title 等协议变量）。
	// @param ctx 上下文
	// @param vo 发起请求
	// @return 统一返回（data 含 processInstanceId）
	// @return 错误
	StartProcess(ctx context.Context, vo *StartProcessInstanceVo) (R, error)
	// StartProcessAndFirstStep 发起流程并预存首步下一步信息。
	// @param ctx 上下文
	// @param vo 发起请求
	// @return 统一返回
	// @return 错误
	StartProcessAndFirstStep(ctx context.Context, vo *StartProcessInstanceVo) (R, error)

	// Complete 办结任务（写意见、表单状态，按 request 预存下一步）。
	// @param ctx 上下文
	// @param vo 办结请求
	// @return 统一返回
	// @return 错误
	Complete(ctx context.Context, vo *CompleteTaskVo) (R, error)
	// BackToStepTask 退回任务到指定步骤（任意节点退回）。
	// @param ctx 上下文
	// @param vo 退回请求
	// @return 统一返回
	// @return 错误
	BackToStepTask(ctx context.Context, vo *BackTaskVo) (R, error)
	// BackTask 退回任务到上一节点（仅串行流程）。
	// @param ctx 上下文
	// @param vo 退回请求
	// @return 统一返回
	// @return 错误
	BackTask(ctx context.Context, vo *BackTaskVo) (R, error)
	// DoRollbackTask 撤回任务（发起人/特权人撤回已办任务，策略族执行）。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param taskID 待撤回任务 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoRollbackTask(ctx context.Context, processInstanceID, taskID, operator string) (R, error)
	// CompleteToTargetActivity 直送：办结并提交至指定目标节点。
	// @param ctx 上下文
	// @param vo 办结请求（TargetActivityID 必填）
	// @return 统一返回
	// @return 错误
	CompleteToTargetActivity(ctx context.Context, vo *CompleteTaskVo) (R, error)
	// DoResetProcess 重置流程实例（清空运行态回到发起节点）。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoResetProcess(ctx context.Context, processInstanceID, operator string) (R, error)

	// GetTodoTaskListByIdentityID 按身份 Id 分页查询待办任务。
	// @param ctx 上下文
	// @param identityID 身份 Id
	// @param query 分页参数
	// @return 统一返回（data 为分页任务列表）
	// @return 错误
	GetTodoTaskListByIdentityID(ctx context.Context, identityID string, query PageQuery) (R, error)
	// GetDoneTaskListByIdentityID 按身份 Id 分页查询已办任务。
	// @param ctx 上下文
	// @param identityID 身份 Id
	// @param query 分页参数
	// @return 统一返回（data 为分页任务列表）
	// @return 错误
	GetDoneTaskListByIdentityID(ctx context.Context, identityID string, query PageQuery) (R, error)

	// GetNextUserTaskAndUserList 推演当前任务之后的节点与候选处理人。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 统一返回（data 为节点与用户列表）
	// @return 错误
	GetNextUserTaskAndUserList(ctx context.Context, taskID string) (R, error)
	// SaveAgreeNextActivity 预存"同意"方向的下一步节点与处理人（目标为 end 时跳过）。
	// @param ctx 上下文
	// @param req 预存请求
	// @return 统一返回
	// @return 错误
	SaveAgreeNextActivity(ctx context.Context, req *NextActivityRequest) (R, error)

	// IsProcessDeployed 判断流程定义是否已部署。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param processDefinitionKey 流程定义 Key
	// @return 统一返回（data 为 bool）
	// @return 错误
	IsProcessDeployed(ctx context.Context, tenantID, processDefinitionKey string) (R, error)
	// IsExistRunningProcess 判断业务键下是否存在运行中实例。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param processDefinitionKey 流程定义 Key
	// @param businessKey 业务单据 ID
	// @return 统一返回（data 为 bool）
	// @return 错误
	IsExistRunningProcess(ctx context.Context, tenantID, processDefinitionKey, businessKey string) (R, error)
	// GetWorkflowStatusByBusinessID 查询业务单据的流程状态。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param processDefinitionKey 流程定义 Key
	// @param businessKey 业务单据 ID
	// @return 统一返回（data 为状态描述）
	// @return 错误
	GetWorkflowStatusByBusinessID(ctx context.Context, tenantID, processDefinitionKey, businessKey string) (R, error)
	// UpdateProcessGlobalVariable 更新流程实例全局变量。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param variables 变量名到值
	// @return 统一返回
	// @return 错误
	UpdateProcessGlobalVariable(ctx context.Context, processInstanceID string, variables map[string]any) (R, error)
	// GetProcessGlobalVariableByProcessInstanceID 按实例查询全局变量。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param names 变量名列表，nil 表示全部
	// @return 统一返回（data 为变量映射）
	// @return 错误
	GetProcessGlobalVariableByProcessInstanceID(ctx context.Context, processInstanceID string, names []string) (R, error)
	// GetProcessGlobalVariableByBusinessID 按业务键查询运行实例的全局变量。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param businessKey 业务单据 ID
	// @param names 变量名列表，nil 表示全部
	// @return 统一返回（data 为变量映射）
	// @return 错误
	GetProcessGlobalVariableByBusinessID(ctx context.Context, tenantID, businessKey string, names []string) (R, error)

	// UpdateWorkflowDocumentByProcessInstanceIDOrTaskID 按实例 ID 或任务 ID 回写业务表单状态。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID（与 taskID 至少一个非空）
	// @param taskID 任务 ID
	// @param document 回写数据
	// @return 统一返回
	// @return 错误
	UpdateWorkflowDocumentByProcessInstanceIDOrTaskID(ctx context.Context, processInstanceID, taskID string, document map[string]any) (R, error)

	// DoTaskOwnerAdjustment 按节点调整运行中任务的处理人。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param taskKey 目标节点 Key
	// @param fromOwner 原处理人，空表示不限
	// @param toOwner 新处理人
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoTaskOwnerAdjustment(ctx context.Context, processInstanceID, taskKey, fromOwner, toOwner, operator string) (R, error)
	// DoTaskOwnerAdjustmentByID 按任务 ID 调整处理人。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param toOwner 新处理人
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoTaskOwnerAdjustmentByID(ctx context.Context, taskID, toOwner, operator string) (R, error)

	// GetTaskMessageListByBusinessID 按业务单据查询任务消息扩展列表。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param businessKey 业务单据 ID
	// @return 统一返回（data 为消息列表）
	// @return 错误
	GetTaskMessageListByBusinessID(ctx context.Context, tenantID, businessKey string) (R, error)
	// GetTaskHistoryListByProcessInstanceID 按实例查询任务历史扩展列表。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @return 统一返回（data 为历史列表）
	// @return 错误
	GetTaskHistoryListByProcessInstanceID(ctx context.Context, processInstanceID string) (R, error)
	// GetTaskHistoryListByBusinessID 按业务单据查询任务历史扩展列表。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param businessKey 业务单据 ID
	// @return 统一返回（data 为历史列表）
	// @return 错误
	GetTaskHistoryListByBusinessID(ctx context.Context, tenantID, businessKey string) (R, error)
	// GetTaskHistoryListByTaskID 按任务查询历史扩展记录。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 统一返回（data 为历史记录）
	// @return 错误
	GetTaskHistoryListByTaskID(ctx context.Context, taskID string) (R, error)

	// GetTaskInfoByTaskID 按任务 ID 查询任务详情（含 workflow 扩展列）。
	// Java 方法名 geTaskInfoByTaskId（拼写保留）。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 统一返回（data 为任务详情）
	// @return 错误
	GetTaskInfoByTaskID(ctx context.Context, taskID string) (R, error)

	// GetBackNodes 查询任务的可退回节点列表（前端"退回"按钮数据源）。
	// @param ctx 上下文
	// @param taskID 当前任务 ID
	// @return 统一返回（data 为可退节点视图列表）
	// @return 错误
	GetBackNodes(ctx context.Context, taskID string) (R, error)

	// DoStopProcessInstance 软终止流程实例（按实例 ID，写终态留痕）。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param operator 操作人身份 Id
	// @param message 终止意见
	// @return 统一返回
	// @return 错误
	DoStopProcessInstance(ctx context.Context, processInstanceID, operator, message string) (R, error)
	// DoStopTaskByTaskID 按任务软终止其所在流程实例。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoStopTaskByTaskID(ctx context.Context, taskID, operator string) (R, error)
	// DoDeleteProcessInstance 删除流程实例（运行态删除 + 历史留痕）。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param operator 操作人身份 Id
	// @param reason 删除原因
	// @return 统一返回
	// @return 错误
	DoDeleteProcessInstance(ctx context.Context, processInstanceID, operator, reason string) (R, error)
	// DoDeleteProcessByBusinessID 按业务单据删除其流程实例。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param businessKey 业务单据 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoDeleteProcessByBusinessID(ctx context.Context, tenantID, businessKey, operator string) (R, error)
	// DoSuspendProcessInstance 挂起流程实例。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoSuspendProcessInstance(ctx context.Context, processInstanceID, operator string) (R, error)
	// DoActivateProcessInstance 恢复挂起的流程实例。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param operator 操作人身份 Id
	// @return 统一返回
	// @return 错误
	DoActivateProcessInstance(ctx context.Context, processInstanceID, operator string) (R, error)
	// DoReactivateProcess 重激活已结束实例到指定节点（原实例复活，ID 不变）。
	// @param ctx 上下文
	// @param historicProcessInstanceID 历史实例 ID
	// @param targetActivityID 重激活目标节点 ID（空表示回开始事件后首个用户任务）
	// @param operator 操作人身份 Id
	// @return 统一返回（data 含 processInstanceId）
	// @return 错误
	DoReactivateProcess(ctx context.Context, historicProcessInstanceID, targetActivityID, operator string) (R, error)

	// AddExecution 加签：为当前任务追加办理人（前加签/后加签）。
	// @param ctx 上下文
	// @param req 加签请求
	// @return 统一返回（data 为加签结果）
	// @return 错误
	AddExecution(ctx context.Context, req AddSignRequest) (R, error)
	// DelExecution 减签：移除被加签人子任务并按需恢复父任务。
	// @param ctx 上下文
	// @param req 减签请求
	// @return 统一返回（data 为减签结果）
	// @return 错误
	DelExecution(ctx context.Context, req DelSignRequest) (R, error)
	// AddMultiInstanceMember 向多实例（会签）活动动态追加一个实例成员。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param activityID 多实例活动 ID
	// @param assignee 新成员身份 Id
	// @return 统一返回
	// @return 错误
	AddMultiInstanceMember(ctx context.Context, processInstanceID, activityID, assignee string) (R, error)
	// RemoveMultiInstanceMember 移除多实例（会签）活动的一个实例成员。
	// @param ctx 上下文
	// @param processInstanceID 流程实例 ID
	// @param activityID 多实例活动 ID
	// @param assignee 成员身份 Id
	// @param executionID 被移除实例的执行 ID
	// @param completed 移除时是否视作已完成
	// @return 统一返回
	// @return 错误
	RemoveMultiInstanceMember(ctx context.Context, processInstanceID, activityID, assignee, executionID string, completed bool) (R, error)
	// CompleteSign 会签比例结论：按已办比例判定会签是否通过。
	// @param ctx 上下文
	// @param taskID 会签任务 ID
	// @param countersignResult 会签结论：0 否决 / 1 通过
	// @return 统一返回（data 为是否达成比例）
	// @return 错误
	CompleteSign(ctx context.Context, taskID string, countersignResult int) (R, error)

	// GetNextUserTaskAndUserListByKey 未发起实例按流程定义推演（不含办结伪节点）。
	// @param ctx 上下文
	// @param tenantID 租户（业务系统代号）
	// @param processDefinitionKey 流程定义 Key（取最新版本）
	// @param businessKey 业务单据 Id（预留透传）
	// @param vars 表单/条件变量
	// @return 统一返回（data 为节点与用户视图列表）
	// @return 错误
	GetNextUserTaskAndUserListByKey(ctx context.Context, tenantID, processDefinitionKey, businessKey string, vars map[string]any) (R, error)

	// DoAddComment 写入审批意见（对位 Java addComment → AddHisCommentCmd：TYPE_ 缺省 SP、
	// MESSAGE_ 压平截断 3900、FULL_MSG_ 存原文）。
	// @param ctx 上下文
	// @param taskID 任务 ID（可为空）
	// @param userID 作者身份 Id
	// @param processInstanceID 流程实例 ID（taskID 为空时必填）
	// @param typ 意见类型代码（空时默认 SP）
	// @param msg 意见内容
	// @return 统一返回（data 为落库评论）
	// @return 错误
	DoAddComment(ctx context.Context, taskID, userID, processInstanceID, typ, msg string) (R, error)
	// IsMultiInstanceLastPerson 判断会签任务是否为最后一名待办成员（对位
	// ProcessesUtil#isMultiInstanceLastPerson：非会签用户任务恒 true；会签按完成条件比例整数除法判定）。
	// @param ctx 上下文
	// @param taskID 任务 ID
	// @return 统一返回（data 为布尔值）
	// @return 错误
	IsMultiInstanceLastPerson(ctx context.Context, taskID string) (R, error)

	// TriggerDelegateScan 触发一次定时委托扫描（对位 Java
	// FlowableScheduleTask.scheduledDelegatedTask：扫描未委托活跃待办，getTaskConsignerId
	// 三级命中后按 doTaskOwnerAdjustmentById 语义改派）。
	// @param ctx 上下文
	// @return 统一返回（data 为扫描汇总 scanned/adjusted/failed/errors）
	// @return 错误
	TriggerDelegateScan(ctx context.Context) (R, error)
}