droboticflow-new/internal/api/human_loop.go
2026-08-25 04:17:45 +08:00

1703 lines
67 KiB
Go

package api
import (
"context"
"fmt"
"net/http"
"reflect"
"sort"
"strconv"
"strings"
"time"
"droboticflow/internal/domain"
"github.com/go-chi/chi/v5"
)
type humanVersionRequest struct {
Version int `json:"version"`
}
type humanAssignmentRequest struct {
Version int `json:"version"`
AssignedUserID string `json:"assignedUserId"`
}
type humanSubmissionRequest struct {
Version int `json:"version"`
SubmissionRef string `json:"submissionRef"`
Revision int `json:"revision"`
DurationSeconds int64 `json:"durationSeconds"`
}
type humanDecisionRequest struct {
Version int `json:"version"`
Decision domain.HumanDecision `json:"decision"`
ReviewedRevision int `json:"reviewedRevision"`
RejectTargets []string `json:"rejectTargets"`
ReasonCodes []string `json:"reasonCodes"`
Comment string `json:"comment"`
VideoQuality string `json:"videoQuality,omitempty"`
AnnotationAccuracy float64 `json:"annotationAccuracy,omitempty"`
AnnotationCompleteness float64 `json:"annotationCompleteness,omitempty"`
OverallGrade string `json:"overallGrade,omitempty"`
}
type humanReopenRequest struct {
ItemVersion int `json:"itemVersion"`
RejectVersion int `json:"rejectVersion"`
TargetStageID string `json:"targetStageId"`
Comment string `json:"comment"`
}
func parseHumanBatchQuery(request *http.Request) domain.HumanBatchQuery {
query := request.URL.Query()
return domain.HumanBatchQuery{
PluginID: query.Get("pluginId"), ProjectID: query.Get("projectId"), WorkflowID: query.Get("workflowId"),
RunID: query.Get("runId"), Status: domain.HumanBatchStatus(query.Get("status")),
}
}
func parseHumanItemQuery(request *http.Request) domain.HumanItemQuery {
query := request.URL.Query()
return domain.HumanItemQuery{
PluginID: query.Get("pluginId"), BatchID: query.Get("batchId"), ProjectID: query.Get("projectId"),
WorkflowID: query.Get("workflowId"), RunID: query.Get("runId"), CurrentStageID: query.Get("stageId"),
Status: domain.HumanItemStatus(query.Get("status")),
}
}
func parseHumanRejectQuery(request *http.Request) domain.HumanRejectQuery {
query := request.URL.Query()
return domain.HumanRejectQuery{
BatchID: query.Get("batchId"), ItemID: query.Get("itemId"), ProjectID: query.Get("projectId"),
WorkflowID: query.Get("workflowId"), RunID: query.Get("runId"), Status: domain.HumanRejectStatus(query.Get("status")),
}
}
func (server *server) handleHumanBatchesList(writer http.ResponseWriter, request *http.Request) {
items, err := server.store.ListHumanBatches(request.Context(), server.requestOrganizationID(request), parseHumanBatchQuery(request))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
for index := range items {
if err := server.flushHumanReleasePartitions(request.Context(), &items[index], false); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
principal, _ := currentPrincipal(request)
if !annotationManager(principal) {
filtered := make([]domain.HumanBatchRecord, 0, len(items))
for _, batch := range items {
batchItems, listErr := server.store.ListHumanItems(request.Context(), batch.OrganizationID, domain.HumanItemQuery{BatchID: batch.ID})
if listErr != nil {
renderError(writer, http.StatusInternalServerError, listErr)
return
}
for _, item := range batchItems {
if server.canAccessHumanItem(request.Context(), request, item, "") {
filtered = append(filtered, batch)
break
}
}
}
items = filtered
}
renderJSON(writer, http.StatusOK, map[string]any{"items": items})
}
func (server *server) handleHumanItemsList(writer http.ResponseWriter, request *http.Request) {
pool := strings.TrimSpace(request.URL.Query().Get("pool"))
principal, _ := currentPrincipal(request)
if pool == "" {
if annotationManager(principal) {
pool = "all"
} else {
pool = "available"
}
}
if pool != "available" && pool != "mine" && pool != "all" {
renderValidationError(writer, validationIssue{Field: "pool", Message: "pool must be available, mine, or all"})
return
}
if pool == "all" && !annotationManager(principal) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "only administrators may list all human items"})
return
}
items, err := server.store.ListHumanItems(request.Context(), server.requestOrganizationID(request), parseHumanItemQuery(request))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
filtered := make([]domain.HumanItemRecord, 0, len(items))
batchByID := map[string]*domain.HumanBatchRecord{}
for _, item := range items {
batch, loaded := batchByID[item.BatchID]
if !loaded {
batch, err = server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
batchByID[item.BatchID] = batch
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if !found || !server.canAccessHumanItem(request.Context(), request, item, annotationRoleForHumanStage(stage)) {
continue
}
if pool == "mine" && (principal == nil || item.AssignedUserID != principal.User.ID) {
continue
}
if pool == "available" {
availableStatus := item.Status == domain.HumanItemReady || item.Status == domain.HumanItemRework || item.Status == domain.HumanItemSubmitted
if item.AssignedUserID != "" || !availableStatus {
continue
}
}
filtered = append(filtered, item)
}
renderJSON(writer, http.StatusOK, map[string]any{"items": filtered})
}
func (server *server) humanItemDetail(ctx context.Context, item domain.HumanItemRecord) (map[string]any, error) {
batch, err := server.store.GetHumanBatch(ctx, item.BatchID)
if err != nil {
return nil, err
}
attempts, err := server.store.ListHumanStageAttempts(ctx, item.OrganizationID, item.ID)
if err != nil {
return nil, err
}
events, err := server.store.ListHumanEvents(ctx, item.OrganizationID, item.ID)
if err != nil {
return nil, err
}
rejects, err := server.store.ListHumanRejects(ctx, item.OrganizationID, domain.HumanRejectQuery{ItemID: item.ID})
if err != nil {
return nil, err
}
return map[string]any{"item": item, "batch": batch, "attempts": attempts, "events": events, "rejects": rejects}, nil
}
func (server *server) handleHumanItemGet(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
detail, err := server.humanItemDetail(request.Context(), *item)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, detail)
}
func (server *server) handleHumanItemSubjectContent(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
if strings.TrimSpace(item.RunID) == "" || strings.TrimSpace(item.Subject.ArtifactID) == "" {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human item subject artifact not found"})
return
}
server.serveRunArtifactContent(writer, request, item.RunID, item.Subject.ArtifactID)
}
func humanEvidenceArtifactRunIDs(value any, inheritedRunID string, destination map[string]string) {
switch typed := normalizeStructuredValue(value).(type) {
case map[string]any:
runID := inheritedRunID
if rawRunID, exists := typed["runId"]; exists && rawRunID != nil {
if candidate := strings.TrimSpace(fmt.Sprint(rawRunID)); candidate != "" {
runID = candidate
}
}
for key, item := range typed {
if key == "artifactId" || key == "clipArtifactId" {
if id := strings.TrimSpace(fmt.Sprint(item)); id != "" {
destination[id] = runID
}
}
humanEvidenceArtifactRunIDs(item, runID, destination)
}
case []any:
for _, item := range typed {
humanEvidenceArtifactRunIDs(item, inheritedRunID, destination)
}
case []map[string]any:
for _, item := range typed {
humanEvidenceArtifactRunIDs(item, inheritedRunID, destination)
}
}
}
// handleHumanItemEvidenceContent is a role-scoped artifact proxy for the
// aggregate v5 acceptance workbench. It never grants an acceptance reviewer
// general run-artifact access: only references embedded in their claimed item
// payload can be opened.
func (server *server) handleHumanItemEvidenceContent(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
artifactID := strings.TrimSpace(chi.URLParam(request, "artifactId"))
allowed := map[string]string{}
if item.Subject.Payload != nil {
humanEvidenceArtifactRunIDs(item.Subject.Payload, item.RunID, allowed)
}
runID, exists := allowed[artifactID]
if !exists || strings.TrimSpace(runID) == "" {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "artifact is not scoped to this human acceptance item"})
return
}
server.serveRunArtifactContent(writer, request, runID, artifactID)
}
func (server *server) loadHumanItemForRequest(writer http.ResponseWriter, request *http.Request) (*domain.HumanItemRecord, bool) {
item, err := server.store.GetHumanItem(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, false
}
if item == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human item not found"})
return nil, false
}
if !server.ensureTenantAccess(writer, request, item.OrganizationID, "Human item") {
return nil, false
}
if !server.canAccessHumanItem(request.Context(), request, *item, "") {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "human workgroup access is required"})
return nil, false
}
return item, true
}
func humanStage(batch *domain.HumanBatchRecord, stageID string) (domain.HumanStageDefinition, int, bool) {
if batch == nil {
return domain.HumanStageDefinition{}, -1, false
}
for index, stage := range batch.Stages {
if stage.ID == stageID {
return stage, index, true
}
}
return domain.HumanStageDefinition{}, -1, false
}
func isFanyuV5FourStageBatch(batch *domain.HumanBatchRecord) bool {
return batch != nil && domain.IsFanyuV5FourStageHumanLoop(batch.Stages)
}
func annotationRoleForHumanStage(stage domain.HumanStageDefinition) domain.AnnotationAssignmentRole {
switch stage.ID {
case "split_annotation", domain.FanyuV5StageCutAdjustment:
return domain.AnnotationRoleCutter
case "split_quality_review", domain.FanyuV5StageCutReview, domain.FanyuV5StageSemanticAnnotation:
return domain.AnnotationRoleAnnotator
case "quality_review", domain.FanyuV5StageSemanticReview, "acceptance", fanyuV5PrePackageAcceptanceStageID:
return domain.AnnotationRoleQualityReviewer
}
switch stage.RequiredRole {
case "cutter":
return domain.AnnotationRoleCutter
case "quality_reviewer":
return domain.AnnotationRoleQualityReviewer
case "acceptance_reviewer":
return domain.AnnotationRoleQualityReviewer
default:
return domain.AnnotationRoleAnnotator
}
}
func (server *server) canAccessHumanItem(ctx context.Context, request *http.Request, item domain.HumanItemRecord, requiredRole domain.AnnotationAssignmentRole) bool {
principal, ok := currentPrincipal(request)
if !ok || principal == nil {
return false
}
if item.PluginID == "human-loop-core" {
return principal.User.Role == domain.UserRoleAdmin || principal.User.Role == domain.UserRoleQualityReviewer || principal.User.Role == domain.UserRoleAcceptanceReviewer || principal.User.Role == domain.UserRoleQAReviewer || principal.User.Role == domain.UserRoleAuditor
}
if annotationManager(principal) {
return true
}
memberships, err := server.annotationMembershipsForUser(ctx, item.OrganizationID, item.ProjectID, principal.User.ID)
if err != nil {
return false
}
legacy := domain.AnnotationTaskRecord{ProjectID: item.ProjectID, WorkgroupID: item.WorkgroupID, VendorID: item.VendorID}
if requiredRole != "" {
return membershipHasRole(memberships, legacy, requiredRole)
}
return membershipAllowsTaskRead(memberships, legacy)
}
func (server *server) canAccessCurrentHumanStage(ctx context.Context, request *http.Request, item domain.HumanItemRecord) bool {
batch, err := server.store.GetHumanBatch(ctx, item.BatchID)
if err != nil || batch == nil {
return false
}
stage, _, found := humanStage(batch, item.CurrentStageID)
return found && server.canAccessHumanItem(ctx, request, item, annotationRoleForHumanStage(stage))
}
func (server *server) appendHumanEvent(ctx context.Context, item domain.HumanItemRecord, eventType string, actorID string, payload map[string]any) error {
return server.store.AppendHumanEvent(ctx, domain.HumanEventRecord{
OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, StageID: item.CurrentStageID,
Round: item.ReviewRound, EventType: eventType, ActorUserID: actorID, ItemVersion: item.Version, Payload: payload,
})
}
func (server *server) humanItemForLegacyTask(ctx context.Context, task domain.AnnotationTaskRecord) (*domain.HumanItemRecord, error) {
items, err := server.store.ListHumanItems(ctx, task.OrganizationID, domain.HumanItemQuery{
PluginID: "annotation-qa", ProjectID: task.ProjectID, WorkflowID: task.WorkflowID, RunID: task.RunID,
})
if err != nil {
return nil, err
}
for index := range items {
if items[index].LegacyTaskID == task.ID {
copy := items[index]
return &copy, nil
}
}
return nil, nil
}
func (server *server) requireLegacyHumanItemClaim(writer http.ResponseWriter, request *http.Request, task domain.AnnotationTaskRecord, stageID string) (*domain.HumanItemRecord, bool) {
item, err := server.humanItemForLegacyTask(request.Context(), task)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, false
}
if item == nil {
renderJSON(writer, http.StatusConflict, map[string]string{
"error": "Human item is required before modifying an annotation task",
"code": "human_item_required",
})
return nil, false
}
principal, ok := currentPrincipal(request)
if !ok || principal == nil || item.AssignedUserID != principal.User.ID || (item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress) {
renderJSON(writer, http.StatusConflict, map[string]string{
"error": "Human item must be claimed by the current user before this operation",
"code": "human_item_claim_required",
})
return nil, false
}
if strings.TrimSpace(stageID) != "" && item.CurrentStageID != stageID {
renderJSON(writer, http.StatusConflict, map[string]string{
"error": "Human item is not in the required stage",
"code": "human_item_stage_conflict",
})
return nil, false
}
return item, true
}
func (server *server) syncLegacyTaskFromHumanItem(ctx context.Context, item domain.HumanItemRecord) error {
if item.LegacyTaskID == "" {
return nil
}
task, err := server.store.GetAnnotationTask(ctx, item.LegacyTaskID)
if err != nil || task == nil {
return err
}
task.CurrentRevision = item.CurrentRevision
task.AssignedUserID = item.AssignedUserID
switch {
case item.Status == domain.HumanItemAccepted:
task.Status = domain.AnnotationTaskStatusAccepted
case item.Status == domain.HumanItemRejected:
task.Status = domain.AnnotationTaskStatusRejected
case item.Status == domain.HumanItemEscalated:
task.Status = domain.AnnotationTaskStatusRejected
case item.Status == domain.HumanItemRework:
task.Status = domain.AnnotationTaskStatusRework
case item.CurrentStageID == "split_quality_review" || item.CurrentStageID == "quality_review" ||
item.CurrentStageID == domain.FanyuV5StageCutReview || item.CurrentStageID == domain.FanyuV5StageSemanticReview:
task.Status = domain.AnnotationTaskStatusPendingQuality
case item.CurrentStageID == "acceptance":
task.Status = domain.AnnotationTaskStatusPendingAcceptance
default:
task.Status = domain.AnnotationTaskStatusPendingAnnotation
}
if err := server.store.UpsertAnnotationTask(ctx, *task); err != nil {
return err
}
if task.Status == domain.AnnotationTaskStatusAccepted {
return server.queueAcceptedAnnotationGateRun(ctx, *task)
}
return nil
}
func allowedHumanReopenStages(batch *domain.HumanBatchRecord, rejectedStageID string) []string {
_, rejectedIndex, found := humanStage(batch, rejectedStageID)
if !found {
return nil
}
items := make([]string, 0, rejectedIndex+1)
for index, stage := range batch.Stages {
if index > rejectedIndex {
break
}
if stage.Kind == domain.HumanStageAcceptance || stage.Kind == domain.HumanStageApproval {
continue
}
items = append(items, stage.ID)
}
return items
}
func containsHumanStage(items []string, target string) bool {
for _, item := range items {
if item == target {
return true
}
}
return false
}
func (server *server) syncLegacyAuditTaskFromHumanItem(ctx context.Context, item domain.HumanItemRecord) error {
if item.LegacyAuditTaskID == "" || (item.Status != domain.HumanItemAccepted && item.Status != domain.HumanItemRejected) {
return nil
}
task, err := server.store.GetAuditTask(ctx, item.LegacyAuditTaskID)
if err != nil || task == nil {
return err
}
if item.Status == domain.HumanItemAccepted {
task.Status = domain.AuditStatusApproved
} else {
task.Status = domain.AuditStatusRejected
}
task.UpdatedAt = nowISO()
if err := server.store.UpsertAuditTask(ctx, *task); err != nil {
return err
}
run, err := server.store.GetRun(ctx, task.RunID)
if err != nil || run == nil {
return err
}
run.Status = domain.RunStatusQueued
run.UpdatedAt = nowISO()
return server.store.UpsertRun(ctx, *run)
}
func (server *server) syncHumanItemFromLegacyRevision(ctx context.Context, task domain.AnnotationTaskRecord, revision domain.AnnotationRevisionRecord) error {
item, err := server.humanItemForLegacyTask(ctx, task)
if err != nil || item == nil {
return err
}
semanticReviewStageID := "quality_review"
batch, batchErr := server.store.GetHumanBatch(ctx, item.BatchID)
if batchErr != nil {
return batchErr
}
if isFanyuV5FourStageBatch(batch) {
semanticReviewStageID = domain.FanyuV5StageSemanticReview
}
previousVersion := item.Version
item.CurrentRevision = revision.Revision
item.LatestAuthorUserID = revision.AuthorUserID
item.CurrentStageID = semanticReviewStageID
item.Status = domain.HumanItemSubmitted
item.SubmittedAt = nowISO()
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(ctx, *item, previousVersion)
if err != nil || !updated {
return err
}
_ = server.store.UpsertHumanStageAttempt(ctx, domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: domain.FanyuV5StageSemanticAnnotation, Round: item.ReviewRound,
Status: domain.HumanItemSubmitted, AssigneeUserID: revision.AuthorUserID, SubmissionRef: revision.ID,
})
return server.appendHumanEvent(ctx, *item, "submitted", revision.AuthorUserID, map[string]any{
"submissionRef": revision.ID, "revision": revision.Revision, "stage": domain.FanyuV5StageSemanticAnnotation,
})
}
func (server *server) syncHumanItemFromLegacyReview(ctx context.Context, task domain.AnnotationTaskRecord, review domain.AnnotationReviewRecord, rejectTargets []string, reasonCodes []string) error {
item, err := server.humanItemForLegacyTask(ctx, task)
if err != nil || item == nil {
return err
}
batch, err := server.store.GetHumanBatch(ctx, item.BatchID)
if err != nil || batch == nil {
return err
}
previousVersion := item.Version
stageID := "quality_review"
if review.Stage == domain.AnnotationReviewStageAcceptance {
stageID = "acceptance"
} else if review.Stage == domain.AnnotationReviewStageSplitQuality {
stageID = "split_quality_review"
}
item.CurrentStageID = stageID
if review.Decision == domain.AnnotationReviewApproved {
_, stageIndex, found := humanStage(batch, stageID)
if found && stageIndex+1 < len(batch.Stages) {
item.CurrentStageID = batch.Stages[stageIndex+1].ID
item.Status = domain.HumanItemReady
} else {
item.Status = domain.HumanItemAccepted
item.AcceptedAt = nowISO()
}
} else {
allowed := allowedHumanReopenStages(batch, stageID)
if len(rejectTargets) == 0 {
rejectTargets = allowed
}
for _, target := range rejectTargets {
if !containsHumanStage(allowed, target) {
return nil
}
}
item.Status = domain.HumanItemRejected
item.RejectedAt = nowISO()
}
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(ctx, *item, previousVersion)
if err != nil || !updated {
return err
}
_ = server.store.UpsertHumanBatch(ctx, *batch)
if len(reasonCodes) == 0 && review.Decision == domain.AnnotationReviewRejected {
reasonCodes = []string{"legacy_reject"}
}
_ = server.store.UpsertHumanStageAttempt(ctx, domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: stageID, Round: item.ReviewRound,
Status: item.Status, AssigneeUserID: review.ReviewerUserID, ReviewedRevision: review.Revision,
Decision: domain.HumanDecision(review.Decision), RejectTargets: rejectTargets, ReasonCodes: reasonCodes, Comment: review.Comment,
})
if review.Decision == domain.AnnotationReviewRejected {
_ = server.store.UpsertHumanReject(ctx, domain.HumanRejectRecord{
OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, ProjectID: item.ProjectID,
WorkflowID: item.WorkflowID, RunID: item.RunID, StageID: stageID, AttemptRound: item.ReviewRound,
ReviewedRevision: review.Revision, RejectedByUserID: review.ReviewerUserID, ReasonCodes: reasonCodes,
Comment: review.Comment, AllowedReopenStages: allowedHumanReopenStages(batch, stageID), Status: domain.HumanRejectOpen,
})
}
eventType := string(review.Decision)
if err := server.appendHumanEvent(ctx, *item, eventType, review.ReviewerUserID, map[string]any{
"reviewedRevision": review.Revision, "rejectTargets": rejectTargets, "reasonCodes": reasonCodes,
"comment": review.Comment, "source": "annotation-qa",
}); err != nil {
return err
}
if item.Status == domain.HumanItemAccepted {
return server.flushHumanReleasePartitions(ctx, batch, false)
}
return nil
}
func (server *server) handleHumanItemClaim(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanVersionRequest
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
batch, err := server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if batch == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if !found {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": "Human stage is not configured"})
return
}
if !server.canAccessHumanItem(request.Context(), request, *item, annotationRoleForHumanStage(stage)) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "human stage role is required"})
return
}
if item.Status != domain.HumanItemReady && item.Status != domain.HumanItemRework && item.Status != domain.HumanItemSubmitted {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item cannot be claimed from current status"})
return
}
principal, _ := currentPrincipal(request)
previousVersion := item.Version
item.AssignedUserID = principal.User.ID
item.Status = domain.HumanItemClaimed
item.ClaimedAt = nowISO()
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
attempt := domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound,
Status: domain.HumanItemClaimed, AssigneeUserID: principal.User.ID,
}
if err := server.store.UpsertHumanStageAttempt(request.Context(), attempt); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
_ = server.appendHumanEvent(request.Context(), *item, "claimed", principal.User.ID, nil)
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, item)
}
func (server *server) handleHumanItemRelease(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanVersionRequest
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
principal, _ := currentPrincipal(request)
if principal == nil || (principal.User.Role != domain.UserRoleAdmin && item.AssignedUserID != principal.User.ID) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "only the claimant or an administrator may release this item"})
return
}
if item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item cannot be released from current status"})
return
}
previousVersion := item.Version
item.AssignedUserID = ""
item.ClaimedAt = ""
if item.ReviewRound > 0 {
item.Status = domain.HumanItemRework
} else {
item.Status = domain.HumanItemReady
}
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound,
Status: item.Status,
})
_ = server.appendHumanEvent(request.Context(), *item, "released", principal.User.ID, nil)
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, item)
}
func userRoleSupportsAnnotationAssignment(role domain.UserRole, assignmentRole domain.AnnotationAssignmentRole) bool {
if role == domain.UserRoleAdmin {
return true
}
switch assignmentRole {
case domain.AnnotationRoleCutter:
return role == domain.UserRoleCutter
case domain.AnnotationRoleAnnotator:
return role == domain.UserRoleAnnotator || role == domain.UserRoleDataOperator
case domain.AnnotationRoleQualityReviewer, domain.AnnotationRoleAcceptanceReviewer:
return role == domain.UserRoleQualityReviewer || role == domain.UserRoleAcceptanceReviewer ||
role == domain.UserRoleQAReviewer || role == domain.UserRoleAuditor || role == domain.UserRoleComplianceAuditor
default:
return false
}
}
func unassignedHumanItemStatus(item domain.HumanItemRecord, stage domain.HumanStageDefinition) domain.HumanItemStatus {
if item.ReviewRound > 0 {
return domain.HumanItemRework
}
if (stage.Kind == domain.HumanStageReview || stage.Kind == domain.HumanStageAcceptance) && item.CurrentRevision > 0 {
return domain.HumanItemSubmitted
}
return domain.HumanItemReady
}
// handleHumanItemAssignment gives administrators one audited control for
// moving a task between an eligible user and the shared pool. It never bypasses
// the stage role, project/workgroup/vendor membership, tenant, or optimistic
// version checks used by normal self-service claims.
func (server *server) handleHumanItemAssignment(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanAssignmentRequest
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
if item.Status == domain.HumanItemAccepted || item.Status == domain.HumanItemRejected || item.Status == domain.HumanItemEscalated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "terminal human items cannot be reassigned"})
return
}
batch, err := server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if !found {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": "Human stage is not configured"})
return
}
requiredRole := annotationRoleForHumanStage(stage)
assignedUserID := strings.TrimSpace(payload.AssignedUserID)
if assignedUserID != "" {
user, loadErr := server.store.GetUser(request.Context(), assignedUserID)
if loadErr != nil {
renderError(writer, http.StatusInternalServerError, loadErr)
return
}
if user == nil || user.OrganizationID != item.OrganizationID || user.Status == domain.UserStatusDisabled {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "assigned user must be an active user in the same organization"})
return
}
if !userRoleSupportsAnnotationAssignment(user.Role, requiredRole) {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "assigned user role does not match the current human stage"})
return
}
if user.Role != domain.UserRoleAdmin {
memberships, membershipErr := server.annotationMembershipsForUser(request.Context(), item.OrganizationID, item.ProjectID, user.ID)
if membershipErr != nil {
renderError(writer, http.StatusInternalServerError, membershipErr)
return
}
legacy := domain.AnnotationTaskRecord{ProjectID: item.ProjectID, WorkgroupID: item.WorkgroupID, VendorID: item.VendorID}
if !membershipHasRole(memberships, legacy, requiredRole) {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "assigned user lacks the required project workgroup role"})
return
}
}
}
principal, _ := currentPrincipal(request)
previousVersion := item.Version
previousAssignee := item.AssignedUserID
item.AssignedUserID = assignedUserID
item.Version++
if assignedUserID == "" {
item.ClaimedAt = ""
item.Status = unassignedHumanItemStatus(*item, stage)
} else {
item.ClaimedAt = nowISO()
item.Status = domain.HumanItemClaimed
}
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
if updateErr != nil {
renderError(writer, http.StatusInternalServerError, updateErr)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound,
Status: item.Status, AssigneeUserID: item.AssignedUserID,
})
eventType := "admin_reassigned"
if assignedUserID == "" {
eventType = "admin_returned_to_pool"
}
actorID := ""
if principal != nil {
actorID = principal.User.ID
}
_ = server.appendHumanEvent(request.Context(), *item, eventType, actorID, map[string]any{
"previousAssignedUserId": previousAssignee,
"assignedUserId": assignedUserID,
"requiredRole": requiredRole,
})
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, item)
}
func (server *server) handleHumanItemSubmission(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanSubmissionRequest
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
batch, err := server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if batch == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
stage, stageIndex, found := humanStage(batch, item.CurrentStageID)
if !found || stage.Kind != domain.HumanStageAnnotation {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Current human stage does not accept annotation submissions"})
return
}
principal, _ := currentPrincipal(request)
if !server.canAccessHumanItem(request.Context(), request, *item, annotationRoleForHumanStage(stage)) || item.AssignedUserID != principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "Human item assignee permission required"})
return
}
if item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item cannot be submitted from current status"})
return
}
if strings.TrimSpace(payload.SubmissionRef) == "" || payload.Revision <= 0 {
renderValidationError(writer,
validationIssue{Field: "submissionRef", Message: "submissionRef is required"},
validationIssue{Field: "revision", Message: "revision must be positive"},
)
return
}
previousStage := item.CurrentStageID
previousVersion := item.Version
item.CurrentRevision = payload.Revision
item.LatestAuthorUserID = principal.User.ID
item.SubmittedAt = nowISO()
if stageIndex+1 >= len(batch.Stages) {
item.Status = domain.HumanItemAccepted
item.AcceptedAt = nowISO()
} else {
item.CurrentStageID = batch.Stages[stageIndex+1].ID
item.Status = domain.HumanItemReady
}
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
if err != nil || !updated {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
}
return
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: previousStage, Round: item.ReviewRound,
Status: domain.HumanItemSubmitted, AssigneeUserID: principal.User.ID, SubmissionRef: payload.SubmissionRef,
})
_ = server.appendHumanEvent(request.Context(), *item, "submitted", principal.User.ID, map[string]any{
"submissionRef": payload.SubmissionRef, "revision": payload.Revision, "durationSeconds": payload.DurationSeconds,
})
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, item)
}
func earliestRejectTarget(batch *domain.HumanBatchRecord, allowed []string, requested []string) (string, bool) {
allowedSet := make(map[string]struct{}, len(allowed))
for _, item := range allowed {
allowedSet[item] = struct{}{}
}
requestedSet := make(map[string]struct{}, len(requested))
for _, item := range requested {
if _, ok := allowedSet[item]; !ok {
return "", false
}
requestedSet[item] = struct{}{}
}
for _, stage := range batch.Stages {
if _, ok := requestedSet[stage.ID]; ok {
return stage.ID, true
}
}
return "", false
}
func (server *server) handleHumanItemDecision(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanDecisionRequest
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
batch, err := server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if batch == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
stage, stageIndex, found := humanStage(batch, item.CurrentStageID)
if !found || (stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance && stage.Kind != domain.HumanStageApproval) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Current human stage does not accept decisions"})
return
}
principal, _ := currentPrincipal(request)
if !server.canAccessHumanItem(request.Context(), request, *item, annotationRoleForHumanStage(stage)) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "Human review role is required"})
return
}
if item.AssignedUserID != principal.User.ID {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item must be claimed before review", "code": "human_item_claim_required"})
return
}
if item.LatestAuthorUserID != "" && item.LatestAuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own annotation", "code": "separation_of_duties"})
return
}
if item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item cannot be reviewed from current status"})
return
}
if payload.Decision != domain.HumanDecisionApproved && payload.Decision != domain.HumanDecisionRejected {
renderValidationError(writer, validationIssue{Field: "decision", Message: "decision must be approved or rejected"})
return
}
if stage.ConfirmOnly && payload.Decision != domain.HumanDecisionApproved {
renderValidationError(writer, validationIssue{Field: "decision", Message: "this acceptance stage is confirm-only and does not allow reject or rework"})
return
}
if stage.ConfirmOnly && (strings.TrimSpace(payload.VideoQuality) == "" || strings.TrimSpace(payload.OverallGrade) == "" || payload.AnnotationAccuracy < 0 || payload.AnnotationAccuracy > 100 || payload.AnnotationCompleteness < 0 || payload.AnnotationCompleteness > 100) {
renderValidationError(writer, validationIssue{Field: "statistics", Message: "confirm-only acceptance requires videoQuality, overallGrade and annotation accuracy/completeness in [0,100]"})
return
}
previousStage := item.CurrentStageID
previousVersion := item.Version
if stage.ConfirmOnly {
if item.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
statistics, _ := item.Subject.Payload["statistics"].(map[string]any)
if statistics == nil {
statistics = map[string]any{}
}
statistics["videoQuality"] = strings.TrimSpace(payload.VideoQuality)
statistics["annotationAccuracy"] = payload.AnnotationAccuracy
statistics["annotationCompleteness"] = payload.AnnotationCompleteness
statistics["overallGrade"] = strings.TrimSpace(payload.OverallGrade)
item.Subject.Payload["statistics"] = statistics
}
eventType := string(payload.Decision)
automaticReworkTarget := ""
rejectAllowedStages := []string(nil)
if payload.Decision == domain.HumanDecisionApproved {
if stageIndex+1 >= len(batch.Stages) {
item.Status = domain.HumanItemAccepted
item.AcceptedAt = nowISO()
item.AcceptedByUserID = principal.User.ID
} else {
item.CurrentStageID = batch.Stages[stageIndex+1].ID
item.Status = domain.HumanItemReady
}
} else {
if len(payload.ReasonCodes) == 0 || strings.TrimSpace(payload.Comment) == "" {
renderValidationError(writer,
validationIssue{Field: "reasonCodes", Message: "at least one reason code is required for rejection"},
validationIssue{Field: "comment", Message: "comment is required for rejection"},
)
return
}
rejectAllowedStages = allowedHumanReopenStages(batch, previousStage)
if isFanyuV5FourStageBatch(batch) {
if len(stage.RejectTargets) == 0 {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "v5 review stage has no configured rework target", "code": "human_item_stage_contract"})
return
}
automaticReworkTarget = stage.RejectTargets[0]
if len(payload.RejectTargets) > 0 {
if len(payload.RejectTargets) != 1 || !allowedFanyuV5RejectTarget(payload.RejectTargets[0], stage.RejectTargets) {
renderValidationError(writer, validationIssue{Field: "rejectTargets", Message: "v5 review reject target is not allowed for the current stage"})
return
}
automaticReworkTarget = payload.RejectTargets[0]
} else {
payload.RejectTargets = []string{automaticReworkTarget}
}
rejectAllowedStages = append([]string(nil), stage.RejectTargets...)
item.CurrentStageID = automaticReworkTarget
item.ReviewRound++
if item.ReviewRound > item.MaxReworkRounds {
item.Status = domain.HumanItemEscalated
batch.Status = domain.HumanBatchBlocked
} else {
item.Status = domain.HumanItemRework
}
} else {
for _, target := range payload.RejectTargets {
if !containsHumanStage(rejectAllowedStages, target) {
renderValidationError(writer, validationIssue{Field: "rejectTargets", Message: "rejectTargets must contain only current or earlier reopen stages"})
return
}
}
item.Status = domain.HumanItemRejected
item.RejectedAt = nowISO()
}
}
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
updated, err := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
if err != nil || !updated {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
}
return
}
_ = server.store.UpsertHumanBatch(request.Context(), *batch)
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: previousStage, Round: item.ReviewRound,
Status: item.Status, AssigneeUserID: principal.User.ID, ReviewedRevision: payload.ReviewedRevision,
Decision: payload.Decision, RejectTargets: payload.RejectTargets, ReasonCodes: payload.ReasonCodes, Comment: strings.TrimSpace(payload.Comment),
})
if payload.Decision == domain.HumanDecisionRejected {
reject := domain.HumanRejectRecord{
OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, ProjectID: item.ProjectID,
WorkflowID: item.WorkflowID, RunID: item.RunID, StageID: previousStage, AttemptRound: item.ReviewRound,
ReviewedRevision: payload.ReviewedRevision, RejectedByUserID: principal.User.ID, ReasonCodes: payload.ReasonCodes,
Comment: strings.TrimSpace(payload.Comment), AllowedReopenStages: rejectAllowedStages, Status: domain.HumanRejectOpen,
}
if automaticReworkTarget != "" {
reject.ReopenCount = 1
reject.ReopenedByUserID = principal.User.ID
reject.ReopenTargetStageID = automaticReworkTarget
reject.ReopenComment = "automatic v5 rework routing"
reject.ReopenedAt = nowISO()
if item.Status == domain.HumanItemEscalated {
reject.Status = domain.HumanRejectEscalated
} else {
reject.Status = domain.HumanRejectReopened
}
}
if err := server.store.UpsertHumanReject(request.Context(), reject); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
_ = server.appendHumanEvent(request.Context(), *item, eventType, principal.User.ID, map[string]any{
"decision": payload.Decision, "reviewedRevision": payload.ReviewedRevision, "rejectTargets": payload.RejectTargets,
"reasonCodes": payload.ReasonCodes, "comment": strings.TrimSpace(payload.Comment), "routedToStage": automaticReworkTarget, "videoQuality": payload.VideoQuality, "annotationAccuracy": payload.AnnotationAccuracy, "annotationCompleteness": payload.AnnotationCompleteness, "overallGrade": payload.OverallGrade,
})
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if err := server.syncLegacyAuditTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item.Status == domain.HumanItemAccepted {
if strings.TrimSpace(batch.SourceBatchID) != "" {
sourceBatch, sourceErr := server.store.GetHumanBatch(request.Context(), batch.SourceBatchID)
if sourceErr != nil {
renderError(writer, http.StatusInternalServerError, sourceErr)
return
}
if sourceBatch != nil {
if flushErr := server.flushHumanReleasePartitions(request.Context(), sourceBatch, true); flushErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("release confirmed pre-package partition: %w", flushErr))
return
}
}
} else {
if flushErr := server.flushHumanReleasePartitions(request.Context(), batch, false); flushErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("release accepted human partition: %w", flushErr))
return
}
}
}
renderJSON(writer, http.StatusOK, item)
}
func (server *server) handleHumanRejectsList(writer http.ResponseWriter, request *http.Request) {
items, err := server.store.ListHumanRejects(request.Context(), server.requestOrganizationID(request), parseHumanRejectQuery(request))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
principal, _ := currentPrincipal(request)
if !annotationManager(principal) {
filtered := make([]domain.HumanRejectRecord, 0, len(items))
for _, reject := range items {
if server.canAccessHumanReject(request, reject) {
filtered = append(filtered, reject)
}
}
items = filtered
}
renderJSON(writer, http.StatusOK, map[string]any{"items": items})
}
func (server *server) canAccessHumanReject(request *http.Request, reject domain.HumanRejectRecord) bool {
item, err := server.store.GetHumanItem(request.Context(), reject.ItemID)
if err == nil && item != nil {
return server.canAccessHumanItem(request.Context(), request, *item, "")
}
itemPackage, packageErr := server.store.GetDeliveryPackage(request.Context(), reject.ItemID)
return packageErr == nil && itemPackage != nil && server.deliveryPackageReviewer(request, *itemPackage)
}
func (server *server) handleHumanRejectGet(writer http.ResponseWriter, request *http.Request) {
item, err := server.store.GetHumanReject(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human reject record not found"})
return
}
if !server.ensureTenantAccess(writer, request, item.OrganizationID, "Human reject record") {
return
}
principal, _ := currentPrincipal(request)
if !annotationManager(principal) && !server.canAccessHumanReject(request, *item) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "human workgroup access is required"})
return
}
renderJSON(writer, http.StatusOK, item)
}
func (server *server) handleHumanRejectReopen(writer http.ResponseWriter, request *http.Request) {
reject, err := server.store.GetHumanReject(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if reject == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human reject record not found"})
return
}
if !server.ensureTenantAccess(writer, request, reject.OrganizationID, "Human reject record") {
return
}
var payload humanReopenRequest
if !decodeJSON(writer, request, &payload) {
return
}
if reject.Version != payload.RejectVersion {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human reject version conflict", "code": "version_conflict"})
return
}
if reject.Status != domain.HumanRejectOpen {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human reject record is not open", "code": "reject_not_open"})
return
}
if !containsHumanStage(reject.AllowedReopenStages, strings.TrimSpace(payload.TargetStageID)) {
renderValidationError(writer, validationIssue{Field: "targetStageId", Message: "targetStageId must be an allowed current or earlier stage"})
return
}
if strings.TrimSpace(payload.Comment) == "" {
renderValidationError(writer, validationIssue{Field: "comment", Message: "comment is required when reopening rejected work"})
return
}
item, err := server.store.GetHumanItem(request.Context(), reject.ItemID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item == nil {
server.reopenRejectedDeliveryPackage(writer, request, reject, payload)
return
}
if item.Version != payload.ItemVersion {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
if item.Status != domain.HumanItemRejected {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item is not in the reject zone", "code": "item_not_rejected"})
return
}
principal, _ := currentPrincipal(request)
previousItemVersion := item.Version
item.ReviewRound++
item.Version++
item.RejectedAt = ""
eventType := "reopened"
if item.ReviewRound > item.MaxReworkRounds {
item.Status = domain.HumanItemEscalated
reject.Status = domain.HumanRejectEscalated
eventType = "escalated"
if batch, loadErr := server.store.GetHumanBatch(request.Context(), item.BatchID); loadErr == nil && batch != nil {
batch.Status = domain.HumanBatchBlocked
_ = server.store.UpsertHumanBatch(request.Context(), *batch)
}
} else {
item.CurrentStageID = strings.TrimSpace(payload.TargetStageID)
item.Status = domain.HumanItemRework
item.AssignedUserID = ""
item.ClaimedAt = ""
reject.Status = domain.HumanRejectReopened
}
updated, err := server.store.UpdateHumanItemVersioned(request.Context(), *item, previousItemVersion)
if err != nil || !updated {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
}
return
}
previousRejectVersion := reject.Version
reject.Version++
reject.ReopenCount++
reject.ReopenedByUserID = principal.User.ID
reject.ReopenTargetStageID = strings.TrimSpace(payload.TargetStageID)
reject.ReopenComment = strings.TrimSpace(payload.Comment)
reject.ReopenedAt = nowISO()
updated, err = server.store.UpdateHumanRejectVersioned(request.Context(), *reject, previousRejectVersion)
if err != nil || !updated {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human reject version conflict", "code": "version_conflict"})
}
return
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound,
Status: item.Status, AssigneeUserID: item.AssignedUserID,
})
_ = server.appendHumanEvent(request.Context(), *item, eventType, principal.User.ID, map[string]any{
"rejectId": reject.ID, "targetStageId": payload.TargetStageID, "comment": strings.TrimSpace(payload.Comment),
})
if err := server.syncLegacyTaskFromHumanItem(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, map[string]any{"item": item, "reject": reject})
}
func (server *server) reopenRejectedDeliveryPackage(writer http.ResponseWriter, request *http.Request, reject *domain.HumanRejectRecord, payload humanReopenRequest) {
item, err := server.store.GetDeliveryPackage(request.Context(), reject.ItemID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Rejected human item or delivery package not found"})
return
}
if item.Version != payload.ItemVersion {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Delivery package version conflict", "code": "version_conflict"})
return
}
if item.Status != domain.DeliveryPackageRejected {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Delivery package is not rejected", "code": "package_not_rejected"})
return
}
principal, _ := currentPrincipal(request)
reopened := make([]string, 0, len(item.ItemIDs))
for _, itemID := range item.ItemIDs {
humanItem, loadErr := server.store.GetHumanItem(request.Context(), itemID)
if loadErr != nil {
renderError(writer, http.StatusInternalServerError, loadErr)
return
}
if humanItem == nil {
continue
}
previousVersion := humanItem.Version
humanItem.ReviewRound++
humanItem.Version++
humanItem.AcceptedAt = ""
humanItem.ReleasePartitionID = ""
if humanItem.ReviewRound > humanItem.MaxReworkRounds {
humanItem.Status = domain.HumanItemEscalated
reject.Status = domain.HumanRejectEscalated
} else {
humanItem.CurrentStageID = strings.TrimSpace(payload.TargetStageID)
humanItem.Status = domain.HumanItemRework
humanItem.AssignedUserID = ""
humanItem.ClaimedAt = ""
reject.Status = domain.HumanRejectReopened
}
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *humanItem, previousVersion)
if updateErr != nil || !updated {
if updateErr != nil {
renderError(writer, http.StatusInternalServerError, updateErr)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
}
return
}
_ = server.appendHumanEvent(request.Context(), *humanItem, "reopened", principal.User.ID, map[string]any{"rejectId": reject.ID, "deliveryPackageId": item.ID, "targetStageId": payload.TargetStageID})
_ = server.syncLegacyTaskFromHumanItem(request.Context(), *humanItem)
reopened = append(reopened, humanItem.ID)
}
previousRejectVersion := reject.Version
reject.Version++
reject.ReopenCount++
reject.ReopenedByUserID = principal.User.ID
reject.ReopenTargetStageID = strings.TrimSpace(payload.TargetStageID)
reject.ReopenComment = strings.TrimSpace(payload.Comment)
reject.ReopenedAt = nowISO()
updated, err := server.store.UpdateHumanRejectVersioned(request.Context(), *reject, previousRejectVersion)
if err != nil || !updated {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human reject version conflict", "code": "version_conflict"})
}
return
}
renderJSON(writer, http.StatusOK, map[string]any{"package": item, "reject": reject, "reopenedItemIds": reopened})
}
func (server *server) handleHumanItemEvents(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
items, err := server.store.ListHumanEvents(request.Context(), item.OrganizationID, item.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, map[string]any{"items": items})
}
func parseISOTime(value string) time.Time {
parsed, _ := time.Parse(time.RFC3339Nano, value)
return parsed
}
const fanyuV5PrePackageAcceptanceStageID = "prepackage_acceptance"
func fanyuV5PrePackageAcceptanceBatchID(sourceBatchID string) string {
return "human-batch-fanyu-v5-prepackage-acceptance-" + strings.TrimSpace(sourceBatchID)
}
func fanyuV5PrePackageAcceptanceItemID(sourceBatchID string) string {
return "human-item-fanyu-v5-prepackage-acceptance-" + strings.TrimSpace(sourceBatchID)
}
func acceptanceEvidenceCount(value any) int {
switch typed := value.(type) {
case int:
return typed
case int32:
return int(typed)
case int64:
return int(typed)
case float64:
return int(typed)
case float32:
return int(typed)
default:
return 0
}
}
func acceptanceArtifactRefs(value any) []map[string]any {
refs := make([]map[string]any, 0)
switch typed := value.(type) {
case []map[string]any:
return append(refs, typed...)
case []any:
for _, item := range typed {
if ref, ok := item.(map[string]any); ok {
refs = append(refs, ref)
}
}
return refs
}
raw := reflect.ValueOf(value)
if !raw.IsValid() || (raw.Kind() != reflect.Slice && raw.Kind() != reflect.Array) {
return refs
}
for index := 0; index < raw.Len(); index++ {
item := raw.Index(index).Interface()
if ref, ok := item.(map[string]any); ok {
refs = append(refs, ref)
}
}
return refs
}
// ensureFanyuV5PrePackageAcceptance creates exactly one vendor-scoped,
// partition-level acceptance item after every source item has passed the cut
// and semantic-review loop. Optional hand/head prelabels and their rendered
// evidence are carried into this confirmation step for human quality review.
func (server *server) ensureFanyuV5PrePackageAcceptance(ctx context.Context, source *domain.HumanBatchRecord) (bool, error) {
if source == nil || !source.RequirePrePackageAcceptance {
return true, nil
}
items, err := server.store.ListHumanItems(ctx, source.OrganizationID, domain.HumanItemQuery{BatchID: source.ID})
if err != nil || len(items) == 0 {
return false, err
}
for _, item := range items {
if item.Status != domain.HumanItemAccepted {
return false, nil
}
}
batchID := fanyuV5PrePackageAcceptanceBatchID(source.ID)
acceptanceBatch, err := server.store.GetHumanBatch(ctx, batchID)
if err != nil {
return false, err
}
if acceptanceBatch == nil {
now := nowISO()
acceptanceBatch = &domain.HumanBatchRecord{
ID: batchID, OrganizationID: source.OrganizationID, PluginID: source.PluginID,
ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID,
GateNodeID: source.GateNodeID + "-prepackage-acceptance", SourceBatchID: source.ID,
Status: domain.HumanBatchActive, ItemCount: 1, MaxReworkRounds: 0,
Stages: []domain.HumanStageDefinition{{ID: fanyuV5PrePackageAcceptanceStageID, Label: "包前最终验收(仅确认)", Kind: domain.HumanStageAcceptance, RequiredRole: "quality_reviewer", EditorSchema: "acceptance-statistics/v1", ConfirmOnly: true}},
CreatedAt: now, UpdatedAt: now,
}
if err := server.store.UpsertHumanBatch(ctx, *acceptanceBatch); err != nil {
return false, err
}
}
acceptanceID := fanyuV5PrePackageAcceptanceItemID(source.ID)
acceptanceItem, err := server.store.GetHumanItem(ctx, acceptanceID)
if err != nil {
return false, err
}
if acceptanceItem != nil {
return acceptanceItem.Status == domain.HumanItemAccepted, nil
}
aggregate := make([]map[string]any, 0, len(items))
statistics := map[string]any{
"taskCount": len(items), "sliceCount": 0, "annotationSegmentCount": 0,
"headposeEnabled": false, "handposeEnabled": false,
"headposeFrameCount": 0, "handposeFrameCount": 0,
"headposeAvailable": false, "handposeAvailable": false,
"handPrelabelEnabled": false, "handPrelabelAvailable": false, "handPrelabelFrameCount": 0,
"headposeArtifacts": []map[string]any{}, "handPrelabelArtifacts": []map[string]any{},
"headposeRenderArtifacts": []map[string]any{}, "handPrelabelRenderArtifacts": []map[string]any{},
}
seenPoseArtifacts := map[string]map[string]struct{}{
"headposeArtifacts": {},
"handPrelabelArtifacts": {},
"headposeRenderArtifacts": {},
"handPrelabelRenderArtifacts": {},
}
mergePoseRefs := func(poseSummary map[string]any, sourceKey string, targetKey string, countKey string) {
for _, ref := range acceptanceArtifactRefs(poseSummary[sourceKey]) {
artifactID := strings.TrimSpace(fmt.Sprint(ref["artifactId"]))
if artifactID == "" {
continue
}
if _, exists := seenPoseArtifacts[targetKey][artifactID]; exists {
continue
}
seenPoseArtifacts[targetKey][artifactID] = struct{}{}
statistics[targetKey] = append(statistics[targetKey].([]map[string]any), ref)
if countKey != "" {
statistics[countKey] = acceptanceEvidenceCount(statistics[countKey]) + acceptanceEvidenceCount(ref["frameCount"])
}
}
}
for _, humanItem := range items {
if strings.TrimSpace(humanItem.LegacyTaskID) == "" {
return false, fmt.Errorf("fanyu v5 source item %s has no annotation task", humanItem.ID)
}
task, taskErr := server.store.GetAnnotationTask(ctx, humanItem.LegacyTaskID)
if taskErr != nil || task == nil {
return false, taskErr
}
slices, sliceErr := server.store.ListSliceRevisions(ctx, task.OrganizationID, task.ID)
revisions, revisionErr := server.store.ListAnnotationRevisions(ctx, task.OrganizationID, task.ID)
if sliceErr != nil || revisionErr != nil || len(slices) == 0 || len(revisions) == 0 {
return false, fmt.Errorf("fanyu v5 acceptance evidence missing for task %s", task.ID)
}
latestSlices := slices[len(slices)-1]
var latestRevision *domain.AnnotationRevisionRecord
for index := range revisions {
if revisions[index].Revision == task.CurrentRevision {
copy := revisions[index]
latestRevision = &copy
}
}
if latestRevision == nil {
return false, fmt.Errorf("fanyu v5 acceptance has no current annotation revision for task %s", task.ID)
}
statistics["sliceCount"] = statistics["sliceCount"].(int) + len(latestSlices.Segments)
statistics["annotationSegmentCount"] = statistics["annotationSegmentCount"].(int) + len(latestRevision.Segments)
poseSummary := task.PoseSummary
for _, key := range []string{"headposeEnabled", "headposeAvailable", "handposeEnabled", "handposeAvailable", "handPrelabelEnabled", "handPrelabelAvailable"} {
if enabled, _ := poseSummary[key].(bool); enabled {
statistics[key] = true
}
}
mergePoseRefs(poseSummary, "headposeArtifacts", "headposeArtifacts", "headposeFrameCount")
handPrelabelKey := "handPrelabelArtifacts"
if len(acceptanceArtifactRefs(poseSummary[handPrelabelKey])) == 0 {
handPrelabelKey = "handposeArtifacts"
}
mergePoseRefs(poseSummary, handPrelabelKey, "handPrelabelArtifacts", "handPrelabelFrameCount")
mergePoseRefs(poseSummary, "headposeRenderArtifacts", "headposeRenderArtifacts", "")
mergePoseRefs(poseSummary, "handPrelabelRenderArtifacts", "handPrelabelRenderArtifacts", "")
statistics["handposeEnabled"] = statistics["handPrelabelEnabled"]
statistics["handposeAvailable"] = statistics["handPrelabelAvailable"]
statistics["handposeFrameCount"] = statistics["handPrelabelFrameCount"]
aggregate = append(aggregate, map[string]any{"taskId": task.ID, "runId": task.RunID, "clipArtifactId": task.ArtifactID, "sourceVideo": task.SourceVideo, "clipStart": task.ClipStart, "clipEnd": task.ClipEnd, "finalSlices": latestSlices.Segments, "annotation": latestRevision.Segments, "poseSummary": poseSummary})
}
now := nowISO()
acceptanceItem = &domain.HumanItemRecord{
ID: acceptanceID, OrganizationID: source.OrganizationID, PluginID: source.PluginID, BatchID: batchID,
ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID, GateNodeID: acceptanceBatch.GateNodeID,
Subject: domain.HumanSubjectRef{ItemKey: source.ID, MediaType: "application/json", Payload: map[string]any{"sourceBatchId": source.ID, "items": aggregate, "statistics": statistics}},
CurrentStageID: fanyuV5PrePackageAcceptanceStageID, Status: domain.HumanItemReady,
WorkgroupID: items[0].WorkgroupID, VendorID: items[0].VendorID, MaxReworkRounds: 0, Version: 1, CreatedAt: now, UpdatedAt: now,
}
if err := server.store.UpsertHumanItem(ctx, *acceptanceItem); err != nil {
return false, err
}
if err := server.store.AppendHumanEvent(ctx, domain.HumanEventRecord{OrganizationID: acceptanceItem.OrganizationID, BatchID: acceptanceItem.BatchID, ItemID: acceptanceItem.ID, StageID: acceptanceItem.CurrentStageID, EventType: "created", ActorUserID: "system", ItemVersion: acceptanceItem.Version, Payload: map[string]any{"sourceBatchId": source.ID, "statistics": statistics}, CreatedAt: now}); err != nil {
return false, err
}
return false, nil
}
func (server *server) flushHumanReleasePartitions(ctx context.Context, batch *domain.HumanBatchRecord, force bool) error {
if batch == nil || batch.Status == domain.HumanBatchBlocked {
return nil
}
items, err := server.store.ListHumanItems(ctx, batch.OrganizationID, domain.HumanItemQuery{BatchID: batch.ID})
if err != nil {
return err
}
accepted := make([]domain.HumanItemRecord, 0)
allTerminal := len(items) > 0
for _, item := range items {
if item.Status != domain.HumanItemAccepted && item.Status != domain.HumanItemRejected && item.Status != domain.HumanItemEscalated {
allTerminal = false
}
if item.Status == domain.HumanItemAccepted && item.ReleasePartitionID == "" {
accepted = append(accepted, item)
}
}
if batch.RequirePrePackageAcceptance {
confirmed, acceptanceErr := server.ensureFanyuV5PrePackageAcceptance(ctx, batch)
if acceptanceErr != nil {
return acceptanceErr
}
if !confirmed {
return nil
}
}
if len(accepted) == 0 {
return nil
}
sort.Slice(accepted, func(i, j int) bool { return accepted[i].AcceptedAt < accepted[j].AcceptedAt })
if batch.ReleasePolicy == domain.HumanReleaseAllAccepted && !allTerminal && !force {
return nil
}
oldest := parseISOTime(accepted[0].AcceptedAt)
waitExpired := !oldest.IsZero() && time.Since(oldest) >= time.Duration(batch.PartitionMaxWaitSeconds)*time.Second
if batch.ReleasePolicy == domain.HumanReleaseAcceptedPartition && len(accepted) < batch.PartitionMaxItems && !waitExpired && !allTerminal && !force {
return nil
}
limit := batch.PartitionMaxItems
if limit <= 0 || batch.ReleasePolicy == domain.HumanReleaseAllAccepted {
limit = len(accepted)
}
for len(accepted) > 0 {
count := limit
if count > len(accepted) {
count = len(accepted)
}
chunk := accepted[:count]
accepted = accepted[count:]
itemIDs := make([]string, 0, len(chunk))
for _, item := range chunk {
itemIDs = append(itemIDs, item.ID)
}
sort.Strings(itemIDs)
digest := domain.HumanReleaseManifestDigest(itemIDs)
sequence := batch.NextPartitionSequence + 1
uniqueKey := strings.Join([]string{batch.GateNodeID, strconv.Itoa(sequence), digest}, ":")
existing, err := server.store.GetReleasePartitionByUniqueKey(ctx, batch.OrganizationID, uniqueKey)
if err != nil {
return err
}
partition := domain.ReleasePartitionRecord{
OrganizationID: batch.OrganizationID, BatchID: batch.ID, GateNodeID: batch.GateNodeID, Sequence: sequence,
UniqueKey: uniqueKey, ManifestDigest: digest, ItemIDs: itemIDs, Status: domain.ReleasePartitionPending,
}
if existing != nil {
partition = *existing
} else if err := server.store.UpsertReleasePartition(ctx, partition); err != nil {
return err
}
stored, err := server.store.GetReleasePartitionByUniqueKey(ctx, batch.OrganizationID, uniqueKey)
if err != nil {
return err
}
if stored != nil {
partition = *stored
}
for index := range chunk {
previousVersion := chunk[index].Version
chunk[index].ReleasePartitionID = partition.ID
chunk[index].Version++
if _, err := server.store.UpdateHumanItemVersioned(ctx, chunk[index], previousVersion); err != nil {
return err
}
}
batch.NextPartitionSequence = sequence
batch.ReleasedCount += len(chunk)
}
batch.AcceptedCount = 0
for _, item := range items {
if item.Status == domain.HumanItemAccepted {
batch.AcceptedCount++
}
}
if allTerminal {
batch.Status = domain.HumanBatchCompleted
}
return server.store.UpsertHumanBatch(ctx, *batch)
}