droboticflow/internal/api/human_loop.go
2026-11-19 11:35:20 +08:00

3142 lines
128 KiB
Go

package api
import (
"context"
cryptorand "crypto/rand"
"droboticflow/internal/store"
"encoding/base64"
"encoding/binary"
"encoding/json"
"errors"
"fmt"
"log"
"net/http"
"reflect"
"slices"
"sort"
"strconv"
"strings"
"sync"
"time"
"droboticflow/internal/domain"
"github.com/go-chi/chi/v5"
)
func secureCaptureSamplingValue() (float64, error) {
var raw [8]byte
if _, err := cryptorand.Read(raw[:]); err != nil {
return 0, err
}
// Use the high 53 bits so every returned IEEE-754 value in [0,1) is
// uniformly representable.
value := binary.BigEndian.Uint64(raw[:]) >> 11
return float64(value) / float64(uint64(1)<<53), nil
}
func (server *server) ensureCaptureSamplingDecision(ctx context.Context, source *domain.HumanBatchRecord) (*domain.CaptureSamplingDecision, error) {
if source == nil || !domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
return nil, nil
}
capture, err := server.store.GetCaptureRecordByRunID(ctx, source.RunID)
if err != nil || capture == nil {
// Historical/manual v5.8 Runs predate Capture automation and retain the
// original all-acceptance behavior.
return nil, err
}
if capture.SamplingDecision != nil {
copy := *capture.SamplingDecision
return &copy, nil
}
probability := domain.DefaultAcceptanceSampleProbability
policyRevision := 0
var frozenSampleValue *float64
if policy, policyErr := server.store.GetWorkflowRuntimePolicy(ctx, source.WorkflowID); policyErr != nil {
return nil, policyErr
} else if policy != nil {
probability = policy.AcceptanceSampleProbability
policyRevision = policy.Revision
}
items, itemsErr := server.store.ListHumanItems(ctx, source.OrganizationID, domain.HumanItemQuery{BatchID: source.ID})
if itemsErr != nil {
return nil, itemsErr
}
for _, item := range items {
if item.AcceptanceSampleProbability != nil {
probability, policyRevision = *item.AcceptanceSampleProbability, item.AcceptancePolicyRevision
frozenSampleValue = item.AcceptanceSampleValue
break
}
if item.SubmittedAt != "" {
policy, err := server.store.GetWorkflowRuntimePolicy(ctx, source.WorkflowID)
if err != nil {
return nil, err
}
probability, policyRevision = acceptancePolicyAt(policy, item.SubmittedAt)
break
}
}
// Existing acceptance work is migration evidence that this Capture was
// already selected under the former 100% policy. Never sample it again.
if existing, existingErr := server.store.GetHumanBatch(ctx, fanyuV5PrePackageAcceptanceBatchID(source.ID)); existingErr != nil {
return nil, existingErr
} else if existing != nil {
probability = 1
policyRevision = 0
}
randomValue := 0.0
decisionValue := domain.CaptureSamplingSelected
if probability <= 0 {
randomValue = 1
decisionValue = domain.CaptureSamplingNotSelected
} else if probability < 1 {
if frozenSampleValue != nil {
randomValue = *frozenSampleValue
} else {
randomValue, err = secureCaptureSamplingValue()
if err != nil {
return nil, err
}
}
if randomValue >= probability {
decisionValue = domain.CaptureSamplingNotSelected
}
}
decision := domain.CaptureSamplingDecision{
Decision: decisionValue, Probability: probability, PolicyRevision: policyRevision,
RandomValue: randomValue, DecidedAt: nowISO(), DecidedByUserID: "system",
SourceHumanBatchID: source.ID,
}
created, err := server.store.SetCaptureSamplingDecisionIfAbsent(ctx, capture.ID, decision)
if err != nil {
return nil, err
}
if !created {
latest, loadErr := server.store.GetCaptureRecord(ctx, capture.ID)
if loadErr != nil || latest == nil || latest.SamplingDecision == nil {
return nil, loadErr
}
copy := *latest.SamplingDecision
return &copy, nil
}
return &decision, nil
}
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 {
ReviewDecisionInput
Version int `json:"version"`
Decision domain.HumanDecision `json:"decision"`
ReviewedRevision int `json:"reviewedRevision"`
RejectTargets []string `json:"rejectTargets"`
ReasonCodes []string `json:"reasonCodes"`
ProblemSliceIDs []string `json:"problemSliceIds,omitempty"`
Comment string `json:"comment"`
VideoQuality string `json:"videoQuality,omitempty"`
AnnotationAccuracy float64 `json:"annotationAccuracy,omitempty"`
AnnotationCompleteness float64 `json:"annotationCompleteness,omitempty"`
OverallGrade string `json:"overallGrade,omitempty"`
PoseDelivery domain.PoseDeliveryPolicy `json:"poseDelivery,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, *validationIssue) {
values := request.URL.Query()
query := domain.HumanItemQuery{
PluginID: values.Get("pluginId"), BatchID: values.Get("batchId"), ProjectID: values.Get("projectId"),
WorkflowID: values.Get("workflowId"), RunID: values.Get("runId"), CurrentStageID: values.Get("stageId"),
Status: domain.HumanItemStatus(values.Get("status")),
Search: strings.TrimSpace(values.Get("search")), Capture: strings.TrimSpace(values.Get("capture")), Category: strings.TrimSpace(values.Get("category")),
}
if len(query.Search) > 512 || len(query.Capture) > 512 {
return query, &validationIssue{Field: "search", Message: "search and capture must not exceed 512 bytes"}
}
// stageIds=a,b,c pushes the role workspace's stage set into the store
// query. The single-value stageId stays supported; combining both merges
// the sets.
if raw := strings.TrimSpace(values.Get("stageIds")); raw != "" {
for _, stage := range strings.Split(raw, ",") {
if stage = strings.TrimSpace(stage); stage != "" {
query.StageIDs = append(query.StageIDs, stage)
}
}
}
if query.CurrentStageID != "" && !slices.Contains(query.StageIDs, query.CurrentStageID) {
query.StageIDs = append(query.StageIDs, query.CurrentStageID)
}
// Reject malformed cursors like the runs endpoint instead of silently
// falling back to the first page.
cursor, err := decodeHumanItemCursor(values.Get("cursor"))
if err != nil {
return query, &validationIssue{Field: "cursor", Message: "cursor must be a valid opaque human item cursor"}
}
query.Cursor = cursor
return query, nil
}
const (
humanItemsDefaultLimit = 500
humanItemsMaxLimit = 1000
// Raw Mongo pages larger than the requested page absorb items dropped by
// the in-memory access filters without unbounded over-fetching.
humanItemsMaxFetchRounds = 6
)
func decodeHumanItemCursor(raw string) (*domain.HumanItemCursor, error) {
raw = strings.TrimSpace(raw)
if raw == "" {
return nil, nil
}
payload, err := base64.RawURLEncoding.DecodeString(raw)
if err != nil {
return nil, fmt.Errorf("cursor must be a valid opaque human item cursor")
}
var cursor domain.HumanItemCursor
if err := json.Unmarshal(payload, &cursor); err != nil {
return nil, fmt.Errorf("cursor must be a valid opaque human item cursor")
}
if strings.TrimSpace(cursor.CreatedAt) == "" || strings.TrimSpace(cursor.ID) == "" {
return nil, fmt.Errorf("cursor must include createdAt and id")
}
return &cursor, nil
}
func encodeHumanItemCursor(cursor *domain.HumanItemCursor) string {
if cursor == nil {
return ""
}
payload, err := json.Marshal(cursor)
if err != nil {
return ""
}
return base64.RawURLEncoding.EncodeToString(payload)
}
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
}
// Read path stays read-only (S4): release partitions are flushed by the
// item-acceptance write paths and by the background sweeper started in
// NewHandlerWithConfig (startHumanReleasePartitionSweeper).
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})
}
type humanItemListPage struct {
Items []domain.HumanItemRecord `json:"items"`
NextCursor string `json:"nextCursor,omitempty"`
HasMore bool `json:"hasMore,omitempty"`
}
func (page *humanItemListPage) response() map[string]any {
result := map[string]any{"items": page.Items, "filtersApplied": true}
if page.HasMore {
result["nextCursor"] = page.NextCursor
result["hasMore"] = true
}
return result
}
func (server *server) handleHumanItemsList(writer http.ResponseWriter, request *http.Request) {
page, _ := server.readHumanItemsList(writer, request)
if page != nil {
renderJSON(writer, http.StatusOK, page.response())
}
}
func (server *server) prepareHumanPoolRead(writer http.ResponseWriter, request *http.Request) (string, domain.HumanItemQuery, int, *http.Request, bool) {
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" && pool != "reviewed" {
renderValidationError(writer, validationIssue{Field: "pool", Message: "pool must be available, mine, reviewed, or all"})
return "", domain.HumanItemQuery{}, 0, request, false
}
if pool == "all" && !annotationManager(principal) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "only administrators may list all human items"})
return "", domain.HumanItemQuery{}, 0, request, false
}
query, queryIssue := parseHumanItemQuery(request)
if queryIssue != nil {
renderValidationError(writer, *queryIssue)
return "", domain.HumanItemQuery{}, 0, request, false
}
if pool == "reviewed" {
if principal == nil || (principal.User.Role != domain.UserRoleQualityReviewer && principal.User.Role != domain.UserRoleAcceptanceReviewer && !annotationManager(principal)) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "review history requires reviewer access"})
return "", domain.HumanItemQuery{}, 0, request, false
}
ids, err := server.store.ListReviewedHumanItemIDs(request.Context(), server.requestOrganizationID(request), principal.User.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return "", domain.HumanItemQuery{}, 0, request, false
}
query.IDs = ids
query.ReviewedPool = true
}
if pool == "mine" && principal != nil {
query.ActorUserID = principal.User.ID
query.MinePoolOnly = true
}
if view := strings.TrimSpace(request.URL.Query().Get("annotationView")); view != "" {
if pool != "mine" || !randomClaimAnnotator(principal) {
renderJSON(writer, 403, map[string]string{"error": "annotator mine view required"})
return "", domain.HumanItemQuery{}, 0, request, false
}
if view != "active" && view != "submitted" {
renderValidationError(writer, validationIssue{Field: "annotationView", Message: "annotationView must be active or submitted"})
return "", domain.HumanItemQuery{}, 0, request, false
}
query.AnnotationView = view
}
limit := humanItemsDefaultLimit
if rawLimit := strings.TrimSpace(request.URL.Query().Get("limit")); rawLimit != "" {
parsed, issue := parseDatabaseBrowserPageQuery(rawLimit, "limit", humanItemsDefaultLimit, 1, humanItemsMaxLimit)
if issue != nil {
renderValidationError(writer, *issue)
return "", domain.HumanItemQuery{}, 0, request, false
}
limit = parsed
}
// The handler-level "available" pool rule is pushed into the Mongo filter
// so unassigned/claimable pages do not drag assigned rows through the wire.
if pool == "available" && query.Status == "" {
query.UnassignedOnly = true
query.Statuses = []domain.HumanItemStatus{domain.HumanItemReady, domain.HumanItemRework, domain.HumanItemSubmitted}
}
if randomClaimAnnotator(principal) && query.ActorUserID == "" && (query.PluginID == "" || query.PluginID == "annotation-qa") {
query.BlindAnnotationActorID = principal.User.ID
}
// QC always needs a membership in the item's project. Restrict candidate
// reads to this necessary scope before pagination; supplier/stage/read/claim
// checks remain authoritative below. Shared acceptance is deliberately excluded.
if pool == "available" && query.PluginID == "annotation-qa" && principal != nil && principal.User.Role == domain.UserRoleQualityReviewer {
ctx, err := server.withHumanListReads(request.Context(), server.requestOrganizationID(request), query.ProjectID, nil)
if err != nil {
renderError(writer, 500, err)
return "", domain.HumanItemQuery{}, 0, request, false
}
request = request.WithContext(ctx)
access := server.acceptanceAccessFor(ctx, principal.User.ID)
if access.err != nil {
renderError(writer, 500, access.err)
return "", domain.HumanItemQuery{}, 0, request, false
}
if access.user != nil && access.user.Role == domain.UserRoleQualityReviewer {
roles, err := server.annotationMembershipsForUser(ctx, server.requestOrganizationID(request), "", principal.User.ID)
if err != nil {
renderError(writer, 500, err)
return "", domain.HumanItemQuery{}, 0, request, false
}
query.AvailableSupplierID = &access.user.SupplierID
query.AvailableProjectIDs = []string{}
seen := map[string]bool{}
for _, role := range roles {
if !seen[role.ProjectID] {
seen[role.ProjectID] = true
query.AvailableProjectIDs = append(query.AvailableProjectIDs, role.ProjectID)
}
}
sort.Strings(query.AvailableProjectIDs)
}
}
// List responses never need the workbench draft or disposition histories.
query.ListProjection = true
return pool, query, limit, request, true
}
func (server *server) readHumanItemsList(writer http.ResponseWriter, request *http.Request) (*humanItemListPage, *http.Request) {
request = request.WithContext(store.WithQueryReplicaPoolRead(request.Context()))
finishPrepare := store.ObserveReadPhase(request.Context(), "prepare")
pool, query, limit, request, ok := server.prepareHumanPoolRead(writer, request)
finishPrepare()
if !ok {
return nil, request
}
principal, _ := currentPrincipal(request)
fetchSize := limit
if fetchSize < 100 {
fetchSize = 100
}
filtered := make([]domain.HumanItemRecord, 0, limit)
batchByID := map[string]*domain.HumanBatchRecord{}
var nextCursor *domain.HumanItemCursor
hasMore := false
exhaustedAll := false
for round := 0; round < humanItemsMaxFetchRounds && len(filtered) < limit; round++ {
query.Limit = fetchSize
candidateQuery := query
candidateQuery.PoolCandidateProjection = true
finishQuery := store.ObserveReadPhase(request.Context(), "candidate_query")
items, err := server.store.ListHumanItems(request.Context(), server.requestOrganizationID(request), candidateQuery)
finishQuery()
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
finishContext := store.ObserveReadPhase(request.Context(), "list_context")
listCtx, listErr := server.withHumanListReads(request.Context(), server.requestOrganizationID(request), query.ProjectID, items)
finishContext()
if listErr != nil {
renderError(writer, http.StatusInternalServerError, listErr)
return nil, request
}
request = request.WithContext(listCtx)
if reviewedAcceptanceCategory(query) {
if err := server.projectReviewedAcceptanceStatuses(request.Context(), server.requestOrganizationID(request), items, batchByID); err != nil {
renderError(writer, 500, err)
return nil, request
}
}
finishHydrate := store.ObserveReadPhase(request.Context(), "hydrate")
items, err = server.hydrateHumanPoolPage(request, items, pool, query, limit-len(filtered), batchByID)
finishHydrate()
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
listCtx, listErr = server.withHumanListReads(request.Context(), server.requestOrganizationID(request), query.ProjectID, items)
if listErr != nil {
renderError(writer, http.StatusInternalServerError, listErr)
return nil, request
}
request = request.WithContext(listCtx)
pageExhausted := len(items) < fetchSize
pageFull := false
for index, item := range items {
item, visible, filterErr := server.filterHumanPoolItem(request, item, pool, query, batchByID)
if filterErr != nil {
renderError(writer, http.StatusInternalServerError, filterErr)
return nil, request
}
if !visible {
continue
}
filtered = append(filtered, item)
if len(filtered) >= limit {
// Continuation resumes right after the last returned item.
nextCursor = &domain.HumanItemCursor{CreatedAt: item.CreatedAt, ID: item.ID}
pageFull = true
// More rows exist if the raw page still has unconsumed items
// or the store itself is not exhausted.
hasMore = index < len(items)-1 || !pageExhausted
break
}
}
if pageFull {
break
}
if pageExhausted {
exhaustedAll = true
break
}
last := items[len(items)-1]
nextCursor = &domain.HumanItemCursor{CreatedAt: last.CreatedAt, ID: last.ID}
// Advance the raw fetch cursor so the next round continues strictly
// after this page; otherwise the same raw page repeats every round
// (t17 review finding) and items can be duplicated or starve the loop.
query.Cursor = nextCursor
}
// Fetch-round cap reached without exhausting the store: let the client
// continue from the last raw cursor instead of silently truncating.
if nextCursor != nil && !exhaustedAll && !hasMore && len(filtered) < limit {
hasMore = true
}
if pool == "reviewed" && poolReadMode(request) != humanPoolReadCount {
ids := make([]string, 0, len(filtered))
for _, item := range filtered {
ids = append(ids, item.ID)
}
events, err := server.store.ListLatestReviewEvents(request.Context(), server.requestOrganizationID(request), principal.User.ID, ids)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
for index := range filtered {
if event, ok := events[filtered[index].ID]; ok {
filtered[index].ReviewHistory = &domain.HumanReviewHistory{Decision: strings.TrimPrefix(event.EventType, "combined_quality_"), StageID: event.StageID, Revision: intValue(event.Payload["reviewedRevision"]), ReviewedAt: event.CreatedAt}
if event.Round > 0 || filtered[index].ReviewHistory.Revision > 0 {
round := event.Round
filtered[index].ReviewHistory.Round = &round
}
}
}
if !reviewedAcceptanceCategory(query) {
if err := server.projectReviewedAcceptanceStatuses(request.Context(), server.requestOrganizationID(request), filtered, batchByID); err != nil {
renderError(writer, 500, err)
return nil, request
}
}
}
if humanPoolMetadataOnly(request) {
page := &humanItemListPage{Items: filtered, HasMore: hasMore}
if hasMore {
page.NextCursor = encodeHumanItemCursor(nextCursor)
}
return page, request
}
server.primeAcceptanceSourcesForList(request.Context(), filtered)
resolver := newHumanDisplayResolver(server)
if err := resolver.primeRuns(request.Context(), filtered); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
for index := range filtered {
if err := resolver.enrichItem(request.Context(), &filtered[index]); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
server.anonymizeV58AcceptanceItem(request.Context(), &filtered[index])
if err := func() error {
if poolReadMode(request) == humanPoolReadSummary {
return nil
}
return server.projectRejectedAcceptanceData(request.Context(), &filtered[index])
}(); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, request
}
}
if request.URL.Query().Get("trace") == "1" {
traceCtx, cancelTrace := context.WithTimeout(request.Context(), 2*time.Second)
summaries, err := server.store.ListHumanTraceSummaries(traceCtx, server.requestOrganizationID(request), filtered)
cancelTrace()
if err != nil {
// Optional audit labels cannot hide an otherwise usable task pool.
log.Printf("[review-trace] list summary unavailable: %v", err)
}
for i := range filtered {
if summary, ok := summaries[filtered[i].ID]; ok {
filtered[i].TraceSummary = &summary
}
}
}
page := &humanItemListPage{Items: filtered, HasMore: hasMore}
if hasMore {
page.NextCursor = encodeHumanItemCursor(nextCursor)
}
return page, request
}
// filterHumanPoolItem is shared by metadata selection and final response checks.
// It must not inspect Subject.Payload or ProcessingJob.Input.
func (server *server) filterHumanPoolItem(request *http.Request, item domain.HumanItemRecord, pool string, query domain.HumanItemQuery, batchByID map[string]*domain.HumanBatchRecord) (domain.HumanItemRecord, bool, error) {
if item.QueryReplicaOmit {
return item, false, nil
}
principal, _ := currentPrincipal(request)
batch, loaded := batchByID[item.BatchID]
if !loaded {
var err error
batch, err = server.humanBatchForListRead(request.Context(), item.BatchID)
if err != nil {
return item, false, err
}
batchByID[item.BatchID] = batch
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if randomClaimAnnotator(principal) && item.PluginID == "annotation-qa" && annotationClaimStage(batch, item.CurrentStageID) && item.AssignedUserID != principal.User.ID && item.LatestAuthorUserID != principal.User.ID {
return item, false, nil
}
if !found || !server.canAccessHumanItem(request.Context(), request, item, "") {
return item, false, nil
}
isAuthor := principal != nil && item.LatestAuthorUserID == principal.User.ID
if pool != "reviewed" && !server.canAccessHumanItem(request.Context(), request, item, annotationRoleForHumanStage(stage)) && !isAuthor {
return item, false, nil
}
if reviewedAcceptanceCategory(query) && item.Status == domain.HumanItemAccepted {
status := item.ReviewHistoryStatus
if status == "" {
status = "accepted"
}
if query.Category != status {
return item, false, nil
}
}
if pool == "mine" {
isAssigned := principal != nil && item.AssignedUserID == principal.User.ID
isMySubmitted := isAuthor && (item.Status == domain.HumanItemReady || item.Status == domain.HumanItemSubmitted) && item.CurrentStageID == "quality_review"
if !isAssigned && !isMySubmitted && !(query.AnnotationView == "submitted" && isAuthor) {
return item, false, nil
}
}
if pool == "available" {
availableStatus := item.Status == domain.HumanItemReady || item.Status == domain.HumanItemRework || item.Status == domain.HumanItemSubmitted
if item.AssignedUserID != "" || !availableStatus {
return item, false, nil
}
}
// Server-side claim eligibility is authoritative for both review
// roles. Quality reviewers previously relied on a client-side
// membership guess in the project-scoped workspace; when the member
// fan-out is skipped or its load fails, that guess silently emptied
// the random-claim candidates while the pool count stayed non-zero
// (可见可领取数量却提示无可领取任务). Annotators keep the blind-pool
// contract and never receive candidate-level flags.
if poolReadMode(request) != humanPoolReadCount && principal != nil && (principal.User.Role == domain.UserRoleAcceptanceReviewer || principal.User.Role == domain.UserRoleQualityReviewer) {
claimable := item.AssignedUserID == "" && (item.Status == domain.HumanItemReady || item.Status == domain.HumanItemRework || item.Status == domain.HumanItemSubmitted) && server.canClaimHumanItem(request.Context(), request, item, annotationRoleForHumanStage(stage))
item.CanClaim = &claimable
}
return item, true, nil
}
// Hydrate only records that can reach this response. Any selected record that
// changes between reads sends this page through the original single-read path;
// stale metadata must not govern a newer assignment, stage or permission scope.
func (server *server) hydrateHumanPoolPage(request *http.Request, items []domain.HumanItemRecord, pool string, query domain.HumanItemQuery, remaining int, batches map[string]*domain.HumanBatchRecord) ([]domain.HumanItemRecord, error) {
if humanPoolMetadataOnly(request) {
return items, nil
}
ids := []string{}
selected := map[string]int{}
for index, item := range items {
_, visible, err := server.filterHumanPoolItem(request, item, pool, query, batches)
if err != nil {
return nil, err
}
if visible {
if poolReadMode(request) == humanPoolReadSummary && item.PoolSearchCurrent() {
continue
}
ids = append(ids, item.ID)
selected[item.ID] = index
if len(ids) == remaining {
break
}
}
}
if len(ids) == 0 {
return items, nil
}
full, err := server.store.ListHumanItems(request.Context(), server.requestOrganizationID(request), domain.HumanItemQuery{IDs: ids, ListProjection: true})
if err != nil {
return nil, err
}
stable := len(full) == len(ids)
for _, item := range full {
index, found := selected[item.ID]
if found {
item.ReviewHistoryStatus = items[index].ReviewHistoryStatus
}
if !found || !reflect.DeepEqual(items[index].PoolCandidate(), item.PoolCandidate()) {
stable = false
break
}
}
if !stable {
if replica, ok := server.store.(interface{ UsesQueryReplicaPool(context.Context) bool }); ok && replica.UsesQueryReplicaPool(request.Context()) {
return nil, store.ErrQueryReplicaNotReady
}
current, err := server.store.ListHumanItems(request.Context(), server.requestOrganizationID(request), query)
if err == nil && reviewedAcceptanceCategory(query) {
err = server.projectReviewedAcceptanceStatuses(request.Context(), server.requestOrganizationID(request), current, batches)
}
return current, err
}
for _, item := range full {
item.ReviewHistoryStatus = items[selected[item.ID]].ReviewHistoryStatus
items[selected[item.ID]] = item
}
return items, nil
}
func acceptanceIdentifiersEmpty(item *domain.HumanItemRecord) bool {
return item == nil || item.SupplierID == "" && item.LegacyAssignment == nil && item.WorkgroupID == "" && item.VendorID == ""
}
func (server *server) anonymizeV58AcceptanceItem(ctx context.Context, item *domain.HumanItemRecord) {
if acceptanceIdentifiersEmpty(item) {
return
}
batch, err := server.humanBatchForListRead(ctx, item.BatchID)
if err != nil || batch == nil || strings.TrimSpace(batch.SourceBatchID) == "" {
return
}
source, err := server.humanBatchForListRead(ctx, batch.SourceBatchID)
if err != nil || source == nil || !domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
return
}
item.SupplierID = ""
item.LegacyAssignment = nil
item.WorkgroupID = ""
item.VendorID = ""
}
func (server *server) humanItemDetail(ctx context.Context, item domain.HumanItemRecord) (map[string]any, error) {
if err := server.projectRejectedAcceptanceData(ctx, &item); err != nil {
return nil, err
}
if err := newHumanDisplayResolver(server).enrichItem(ctx, &item); err != nil {
return nil, err
}
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
}
server.anonymizeV58AcceptanceItem(ctx, &item)
result := map[string]any{"item": item, "batch": batch, "attempts": attempts, "events": events, "rejects": rejects}
if item.CurrentStageID == fanyuV5PrePackageAcceptanceStageID {
reviews, err := server.acceptanceReviewSummaries(ctx, item)
if err != nil {
return nil, err
}
result["acceptanceReviews"] = reviews
}
return result, nil
}
func (server *server) handleHumanItemGet(writer http.ResponseWriter, request *http.Request) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
// Lightweight read-only diagnostics use the same task authorization gate.
// Do not load annotation histories, evidence projections or signed URLs.
if request.URL.Query().Get("view") == "diagnostics" {
renderJSON(writer, http.StatusOK, map[string]any{"item": map[string]any{
"id": item.ID, "videoAvailable": strings.TrimSpace(item.RunID) != "" && strings.TrimSpace(item.Subject.ArtifactID) != "",
}})
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
}
artifactID := strings.TrimSpace(item.Subject.ArtifactID)
if strings.EqualFold(strings.TrimSpace(request.URL.Query().Get("side")), "right") && item.Subject.Payload != nil {
artifactID = strings.TrimSpace(fmt.Sprint(item.Subject.Payload["rightArtifactId"]))
}
if strings.TrimSpace(item.RunID) == "" || artifactID == "" {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human item subject artifact not found"})
return
}
server.serveRunArtifactContent(writer, request, item.RunID, 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
}
if err := server.projectRejectedAcceptanceData(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
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
}
run, err := server.loadRun(request.Context(), runID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if run == nil || run.OrganizationID != item.OrganizationID || run.ProjectID != item.ProjectID {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human evidence run not found"})
return
}
server.serveRunArtifactContent(writer, request, runID, artifactID)
}
func (server *server) loadHumanItemEvidenceManifest(writer http.ResponseWriter, request *http.Request) (*domain.RunRecord, *domain.ExecutionArtifact, runArtifactManifestDocument, bool) {
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return nil, nil, runArtifactManifestDocument{}, false
}
if err := server.projectRejectedAcceptanceData(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, nil, runArtifactManifestDocument{}, false
}
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 item"})
return nil, nil, runArtifactManifestDocument{}, false
}
run, err := server.loadRun(request.Context(), runID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, nil, runArtifactManifestDocument{}, false
}
if run == nil || run.OrganizationID != item.OrganizationID || run.ProjectID != item.ProjectID {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human evidence run not found"})
return nil, nil, runArtifactManifestDocument{}, false
}
manifest := runArtifactByID(run, artifactID)
if manifest == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human evidence artifact not found"})
return nil, nil, runArtifactManifestDocument{}, false
}
cacheKey := humanEvidenceKey(item, run, manifest)
if cacheKey == "" {
return run, manifest, server.runArtifactManifestDocumentWithContext(request.Context(), run, manifest), true
}
indexStarted := time.Now()
document, hit, cacheErr := server.humanEvidenceIndexes.get(request.Context(), cacheKey, func(ctx context.Context) runArtifactManifestDocument {
return server.runArtifactManifestDocumentWithContext(ctx, run, manifest)
})
if cacheErr != nil {
renderError(writer, http.StatusInternalServerError, cacheErr)
return nil, nil, runArtifactManifestDocument{}, false
}
if hit {
writer.Header().Set("Server-Timing", fmt.Sprintf("evidence_index;dur=%.2f;desc=hit", float64(time.Since(indexStarted).Microseconds())/1000))
} else {
writer.Header().Set("Server-Timing", fmt.Sprintf("evidence_index;dur=%.2f;desc=load", float64(time.Since(indexStarted).Microseconds())/1000))
}
return run, manifest, document, true
}
func (server *server) handleHumanItemEvidenceMembers(writer http.ResponseWriter, request *http.Request) {
run, manifest, document, ok := server.loadHumanItemEvidenceManifest(writer, request)
if !ok {
return
}
response, issues := pagedResponse(request, document.Members, 30, 200, false)
if len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
response["runId"] = run.ID
response["artifactId"] = artifactResponseID(run.ID, manifest.NodeID, *manifest)
response["schemaVersion"] = document.SchemaVersion
response["recognized"] = document.Recognized
response["message"] = document.Message
response["summary"] = document.Summary
renderJSON(writer, http.StatusOK, response)
}
func (server *server) handleHumanItemEvidenceMemberContent(writer http.ResponseWriter, request *http.Request) {
run, _, document, ok := server.loadHumanItemEvidenceManifest(writer, request)
if !ok {
return
}
// Cached indexes must not retain a file path or connection that became unsafe.
for index := range document.Members {
member := &document.Members[index]
if member.ID != chi.URLParam(request, "memberId") {
continue
}
if member.contentArtifact != nil && strings.HasPrefix(member.contentArtifact.Path, "/") {
if !server.cachedEvidenceFileAvailable(run, member.contentArtifact) {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Evidence file is no longer available"})
return
}
}
if member.bosObject != nil && member.bosObject.connection != nil {
connection, err := server.store.GetStorageConnection(request.Context(), member.bosObject.connection.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if connection == nil || connection.OrganizationID != run.OrganizationID || connection.Provider != domain.StorageProviderBOS || (connection.Bucket != "" && connection.Bucket != member.bosObject.bucket) {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Evidence storage is no longer available"})
return
}
location := *member.bosObject
location.connection = connection
member.bosObject = &location
}
}
server.serveRunArtifactManifestMemberContent(writer, request, run, document)
}
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, "") {
if server.acceptanceAuthorizationDenied(writer, request) {
return nil, false
}
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "project human-task membership 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 isFanyuV58ThreeRoleBatch(batch *domain.HumanBatchRecord) bool {
return batch != nil && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages)
}
func annotationRoleForHumanStage(stage domain.HumanStageDefinition) domain.AnnotationAssignmentRole {
return domain.AnnotationRoleForHumanStage(stage)
}
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 randomClaimAnnotator(principal) && item.PluginID == "annotation-qa" && item.AssignedUserID != principal.User.ID && item.LatestAuthorUserID != principal.User.ID {
batch, err := server.humanBatchForListRead(ctx, item.BatchID)
if err != nil || batch == nil || annotationClaimStage(batch, item.CurrentStageID) {
return false
}
}
if item.PluginID == "human-loop-core" {
return principal.User.Role == domain.UserRoleAdmin || (requiredRole != "" && principal.User.Role == domain.UserRole(requiredRole)) || (requiredRole == "" && (principal.User.Role == domain.UserRoleQualityReviewer || principal.User.Role == domain.UserRoleAcceptanceReviewer))
}
if annotationManager(principal) {
return true
}
if allowed, handled := server.sharedAcceptanceAccess(ctx, principal.User.ID, item, false); handled {
return allowed && (requiredRole == "" || requiredRole == domain.AnnotationRoleAcceptanceReviewer)
}
memberships, err := server.annotationMembershipsForUser(ctx, item.OrganizationID, item.ProjectID, principal.User.ID)
if err != nil {
return false
}
profile := item.ProcessingProfile
if profile == "" {
if batch, e := server.humanBatchForListRead(ctx, item.BatchID); e == nil && batch != nil && batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) {
profile = domain.ProcessingProfileRawHuman
}
}
legacy := domain.AnnotationTaskRecord{ID: item.LegacyTaskID, ProjectID: item.ProjectID, SupplierID: item.SupplierID, ProcessingScope: item.ProcessingScope, ProcessingProfile: profile, WorkgroupID: item.WorkgroupID, VendorID: item.VendorID}
if batch, e := server.humanBatchForListRead(ctx, item.BatchID); e == nil && batch != nil {
legacy.SupplierPool = batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages)
}
legacy.SupplierPoolClosed = item.Status == domain.HumanItemAccepted || item.Status == domain.HumanItemRejected || item.Status == domain.HumanItemCancelled
if requiredRole != "" {
return membershipHasRole(memberships, legacy, requiredRole)
}
return membershipAllowsTaskRead(memberships, legacy)
}
func (server *server) canClaimHumanItem(ctx context.Context, request *http.Request, item domain.HumanItemRecord, requiredRole domain.AnnotationAssignmentRole) bool {
if item.CurrentStageID == domain.FanyuV58StageAnnotationCombined && (item.ReworkRoutingPending || (item.InheritedRework && item.AssignedUserID == "")) {
return false
}
if item.AccountHandoff != nil && item.AccountHandoff.Pending {
return false
}
principal, ok := currentPrincipal(request)
if !ok || principal == nil {
return false
}
if requiredRole == domain.AnnotationRoleAnnotator && item.PluginID == "annotation-qa" && item.LegacyTaskID != "" {
task, err := server.store.GetAnnotationTask(ctx, item.LegacyTaskID)
if err != nil || task == nil {
return false
}
validation, err := server.annotationSourceValidationForTask(ctx, *task, &item, false)
if err != nil || validation.blocked() {
return false
}
}
// Role changes must not let an author claim their own quality review.
if requiredRole == domain.AnnotationRoleQualityReviewer && item.LatestAuthorUserID != "" && item.LatestAuthorUserID == principal.User.ID {
return false
}
if item.PluginID == "human-loop-core" {
return requiredRole != "" && principal.User.Role == domain.UserRole(requiredRole)
}
if allowed, handled := server.sharedAcceptanceAccess(ctx, principal.User.ID, item, true); handled {
return allowed && requiredRole == domain.AnnotationRoleAcceptanceReviewer
}
memberships, err := server.annotationMembershipsForUser(ctx, item.OrganizationID, item.ProjectID, principal.User.ID)
if err != nil {
return false
}
// Resolve the batch through the request-scoped list-read cache: inside a
// pool listing the batches are bulk-prefetched, so per-item claim checks
// must not fall back to one store read per item (N+1 permission reads).
batch, batchErr := server.humanBatchForListRead(ctx, item.BatchID)
if batchErr != nil || batch == nil {
batch = nil
}
profile := item.ProcessingProfile
if profile == "" && batch != nil && batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) {
profile = domain.ProcessingProfileRawHuman
}
legacy := domain.AnnotationTaskRecord{ID: item.LegacyTaskID, ProjectID: item.ProjectID, SupplierID: item.SupplierID, ProcessingScope: item.ProcessingScope, ProcessingProfile: profile, WorkgroupID: item.WorkgroupID, VendorID: item.VendorID}
if batch != nil {
legacy.SupplierPool = batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages)
}
legacy.SupplierPoolClosed = item.Status == domain.HumanItemAccepted || item.Status == domain.HumanItemRejected || item.Status == domain.HumanItemCancelled
return membershipHasRole(memberships, legacy, requiredRole)
}
func (server *server) canAccessCurrentHumanStage(ctx context.Context, request *http.Request, item domain.HumanItemRecord) bool {
batch, err := server.humanBatchForListRead(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) {
reads, _ := ctx.Value(annotationReadCacheKey{}).(*annotationRequestReads)
key := task.OrganizationID + ":" + task.ID
if reads != nil {
if cached, ok := reads.items[key]; ok {
return annotationRequestItemCopy(cached), nil
}
}
if cache, ok := ctx.Value(humanListReadsKey{}).(*humanListReads); ok && cache.organization == task.OrganizationID && (cache.project == "" || cache.project == task.ProjectID) {
for _, item := range cache.itemsByTask[task.ID] {
if item.PluginID == "annotation-qa" && item.ProjectID == task.ProjectID && (task.WorkflowID == "" || item.WorkflowID == task.WorkflowID) && (task.RunID == "" || item.RunID == task.RunID) {
copy := item
return &copy, nil
}
}
return nil, nil
}
items, err := server.store.ListHumanItems(ctx, task.OrganizationID, domain.HumanItemQuery{
PluginID: "annotation-qa", ProjectID: task.ProjectID, WorkflowID: task.WorkflowID, RunID: task.RunID, LegacyTaskID: task.ID, ListProjection: reads != nil && reads.summary,
})
if err != nil {
return nil, err
}
for index := range items {
if items[index].LegacyTaskID == task.ID {
copy := items[index]
if reads != nil {
reads.items[key] = annotationRequestItemCopy(&copy)
}
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
}
domain.CompactHumanAnnotationHistory(item)
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.HumanItemCancelled:
task.Status = domain.AnnotationTaskStatusRejected
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
case item.Status == domain.HumanItemRework || (item.ReviewRound > 0 && item.CurrentStageID == domain.FanyuV58StageAnnotationCombined):
task.Status = domain.AnnotationTaskStatusRework
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()
if isFanyuV58ThreeRoleBatch(batch) {
if err := server.freezeSubmissionAcceptancePolicy(ctx, item); err != nil {
return err
}
}
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) {
started := time.Now()
defer func() {
log.Printf("[api] review_latency operation=handleHumanItemClaim item=%s total_ms=%d", chi.URLParam(request, "id"), time.Since(started).Milliseconds())
}()
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.canClaimHumanItem(request.Context(), request, *item, annotationRoleForHumanStage(stage)) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "human stage role is required"})
return
}
if principal, _ := currentPrincipal(request); randomClaimAnnotator(principal) && item.PluginID == "annotation-qa" && annotationClaimStage(batch, item.CurrentStageID) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "请选择项目后随机领取,不能指定任务领取", "code": "random_claim_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)
boundSupplierID := ""
if domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) && item.CurrentStageID == domain.FanyuV58StageAnnotationCombined && strings.TrimSpace(item.SupplierID) == "" {
if principal.User.Role == domain.UserRoleAnnotator {
boundSupplierID = strings.TrimSpace(principal.User.SupplierID)
}
if boundSupplierID == "" {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "标注员必须在项目中绑定有效供应商后才能领取 Capture", "code": "supplier_membership_required"})
return
}
supplier, supplierErr := server.store.GetSupplier(request.Context(), boundSupplierID)
if supplierErr != nil || supplier == nil || supplier.OrganizationID != item.OrganizationID || !strings.EqualFold(strings.TrimSpace(supplier.Status), "active") {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "标注员所属供应商不可用", "code": "supplier_inactive"})
return
}
item.SupplierID = boundSupplierID
}
previousVersion := item.Version
item.AssignedUserID = principal.User.ID
item.Status = domain.HumanItemClaimed
item.ClaimedAt = nowISO()
item.Version++
updated, err := server.store.ClaimHumanItemVersioned(request.Context(), *item, previousVersion, domain.UserRole(annotationRoleForHumanStage(stage)))
if errors.Is(err, store.ErrHumanClaimConflict) {
renderJSON(writer, 409, map[string]string{"error": "账号权限或任务状态已变化,请刷新后重试"})
return
}
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
}
if fresh, err := server.store.GetHumanItem(request.Context(), item.ID); err != nil || fresh == nil {
renderError(writer, 500, fmt.Errorf("领取已处理,请刷新核对"))
return
} else {
item = fresh
}
if boundSupplierID != "" {
batch.SupplierID = boundSupplierID
batch.UpdatedAt = nowISO()
if err := server.store.UpsertHumanBatch(request.Context(), *batch); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if strings.TrimSpace(item.LegacyTaskID) != "" {
task, taskErr := server.store.GetAnnotationTask(request.Context(), item.LegacyTaskID)
if taskErr != nil {
renderError(writer, http.StatusInternalServerError, taskErr)
return
}
if task != nil {
task.SupplierID = boundSupplierID
task.UpdatedAt = nowISO()
if taskErr = server.store.UpsertAnnotationTask(request.Context(), *task); taskErr != nil {
renderError(writer, http.StatusInternalServerError, taskErr)
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, map[string]any{"supplierId": boundSupplierID})
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
}
if principal, _ := currentPrincipal(request); annotationWorkerCannotRelease(principal) && item.PluginID == "annotation-qa" {
code := "human_task_release_forbidden"
if randomClaimAnnotator(principal) {
code = "annotator_release_forbidden"
}
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "标注员、质检员和验收员领取后不能主动释放任务;请继续处理或联系管理员改派", "code": code})
return
}
if rejectPendingCombinedSubmission(writer, item) {
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
// Discard the annotator's workspace, never its submitted audit revisions.
// Deleting revisions reused numbers already referenced by rejection records and
// made the next quality review fail with "already exists for this revision".
if item.LegacyTaskID != "" && (item.CurrentStageID == domain.FanyuV58StageAnnotationCombined || item.CurrentStageID == "split_annotation" || item.CurrentStageID == "semantic_annotation") {
if item.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
delete(item.Subject.Payload, "annotationDraft")
delete(item.Subject.Payload, "annotationWorkspace")
delete(item.Subject.Payload, "materialization")
item.Subject.Payload["sliceWorkflow"] = map[string]any{"status": "editing", "phase": "slice", "discardedWorkspace": true, "revision": item.CurrentRevision}
}
item.AssignedUserID = ""
item.ClaimedAt = ""
if item.CurrentStageID == domain.FanyuV58StageAnnotationCombined || item.CurrentStageID == "split_annotation" || item.CurrentStageID == "semantic_annotation" {
if item.ReviewRound > 0 {
item.Status = domain.HumanItemRework
} else {
item.Status = domain.HumanItemReady
}
} 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.AnnotationRoleAnnotator:
return role == domain.UserRoleAnnotator
case domain.AnnotationRoleQualityReviewer:
return role == domain.UserRoleQualityReviewer
case domain.AnnotationRoleAcceptanceReviewer:
return role == domain.UserRoleAcceptanceReviewer
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/supplier 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
}
if rejectPendingCombinedSubmission(writer, item) {
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 || item.Status == domain.HumanItemCancelled {
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)
boundSupplierID := ""
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 {
if domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) && item.CurrentStageID == domain.FanyuV58StageAnnotationCombined && strings.TrimSpace(item.SupplierID) == "" {
if user.Role == domain.UserRoleAnnotator {
boundSupplierID = strings.TrimSpace(user.SupplierID)
}
if boundSupplierID == "" {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "标注员必须绑定有效供应商"})
return
}
item.SupplierID = boundSupplierID
}
memberships, membershipErr := server.annotationMembershipsForUser(request.Context(), item.OrganizationID, item.ProjectID, user.ID)
if membershipErr != nil {
renderError(writer, http.StatusInternalServerError, membershipErr)
return
}
legacy := domain.AnnotationTaskRecord{ID: item.LegacyTaskID, ProjectID: item.ProjectID, SupplierID: item.SupplierID, ProcessingScope: item.ProcessingScope, ProcessingProfile: item.ProcessingProfile, SupplierPool: batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages), WorkgroupID: item.WorkgroupID, VendorID: item.VendorID}
legacy.SupplierPoolClosed = item.Status == domain.HumanItemAccepted || item.Status == domain.HumanItemRejected || item.Status == domain.HumanItemCancelled
if shared, handled := server.sharedAcceptanceAccess(request.Context(), user.ID, *item, true); (handled && !shared) || (!handled && !membershipHasRole(memberships, legacy, requiredRole)) {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "assigned user lacks the required project 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
}
var updated bool
var updateErr error
if assignedUserID != "" {
updated, updateErr = server.store.ClaimHumanItemVersioned(request.Context(), *item, previousVersion, domain.UserRole(requiredRole))
} else {
updated, updateErr = server.store.UpdateHumanItemVersioned(request.Context(), *item, previousVersion)
}
if errors.Is(updateErr, store.ErrHumanClaimConflict) {
renderJSON(writer, 409, map[string]string{"error": "账号权限或任务状态已变化,请刷新后重试"})
return
}
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
}
if fresh, err := server.store.GetHumanItem(request.Context(), item.ID); err != nil || fresh == nil {
renderError(writer, 500, fmt.Errorf("领取已处理,请刷新核对"))
return
} else {
item = fresh
}
if boundSupplierID != "" {
batch.SupplierID = boundSupplierID
batch.UpdatedAt = nowISO()
_ = server.store.UpsertHumanBatch(request.Context(), *batch)
if strings.TrimSpace(item.LegacyTaskID) != "" {
if task, taskErr := server.store.GetAnnotationTask(request.Context(), item.LegacyTaskID); taskErr == nil && task != nil {
task.SupplierID = boundSupplierID
task.UpdatedAt = nowISO()
_ = server.store.UpsertAnnotationTask(request.Context(), *task)
}
}
}
_ = 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 isFanyuV58ThreeRoleBatch(batch) {
if err := server.freezeSubmissionAcceptancePolicy(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
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) {
started := time.Now()
defer func() {
log.Printf("[api] review_latency operation=handleHumanItemDecision item=%s total_ms=%d", chi.URLParam(request, "id"), time.Since(started).Milliseconds())
}()
var payload humanDecisionRequest
if !decodeJSON(writer, request, &payload) {
return
}
if server.replayReviewDecision(writer, request, chi.URLParam(request, "id"), payload.ReviewDecisionInput, payload) {
return
}
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var prepared bool
request, prepared = server.prepareReviewDecision(writer, request, *item, "acceptance", payload.ReviewDecisionInput, payload, string(payload.Decision))
if !prepared {
return
}
defer server.finishReviewDecisionPreparation(request)
finishReviewWrite, writeAllowed := server.beginReviewWrite(writer, request, *item)
if !writeAllowed {
return
}
defer finishReviewWrite()
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
}
strictSourceBatch, v58AggregateAcceptance, sourceErr := v58AggregateSourceBatch(request.Context(), server, batch)
if sourceErr != nil {
renderError(writer, http.StatusInternalServerError, sourceErr)
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 v58AggregateAcceptance {
if err := server.requireAcceptanceSourceReady(request.Context(), strictSourceBatch); err != nil {
renderJSON(writer, http.StatusConflict, map[string]string{"error": err.Error(), "code": "acceptance_source_not_ready"})
return
}
}
if payload.Decision != domain.HumanDecisionApproved && payload.Decision != domain.HumanDecisionRejected {
renderValidationError(writer, validationIssue{Field: "decision", Message: "decision must be approved or rejected"})
return
}
if isFanyuV58ThreeRoleBatch(batch) && item.CurrentStageID == domain.FanyuV58StageQualityReview && payload.Decision == domain.HumanDecisionApproved &&
(len(payload.ProblemSliceIDs) > 0 || len(payload.ReasonCodes) > 0 || strings.TrimSpace(payload.Comment) != "") {
renderValidationError(writer, validationIssue{Field: "decision", Message: "存在问题标记或错误备注,请清除后通过,或选择打回"})
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 v58AggregateAcceptance && batch.ProcessingProfile != domain.ProcessingProfileRawHuman && payload.Decision == domain.HumanDecisionApproved {
if !validPoseDeliveryDecision(payload.PoseDelivery.Headpose) || !validPoseDeliveryDecision(payload.PoseDelivery.Handpose) {
renderValidationError(writer, validationIssue{Field: "poseDelivery", Message: "headpose and handpose must be include or exclude"})
return
}
if (payload.PoseDelivery.Headpose == domain.PoseDeliveryExclude || payload.PoseDelivery.Handpose == domain.PoseDeliveryExclude) && len(payload.PoseDelivery.ReasonCodes) == 0 {
renderValidationError(writer, validationIssue{Field: "poseDelivery.reasonCodes", Message: "pose exclusion requires at least one reason code"})
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
decisionOriginalItem := *item
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
}
if v58AggregateAcceptance {
if item.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
if batch.ProcessingProfile != domain.ProcessingProfileRawHuman {
item.Subject.Payload["poseDelivery"] = payload.PoseDelivery
} else {
delete(item.Subject.Payload, "poseDelivery")
}
}
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 v58AggregateAcceptance {
rejectAllowedStages = []string{domain.FanyuV58StageQualityReview}
payload.RejectTargets = []string{domain.FanyuV58StageQualityReview}
}
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++
if operationFromRequest(request) != nil && v58AggregateAcceptance {
server.planAcceptanceReviewDecision(writer, request, decisionOriginalItem, *item, batch, strictSourceBatch, payload)
return
}
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
}
}
if v58AggregateAcceptance && payload.Decision == domain.HumanDecisionRejected {
if err := server.routeV58AcceptanceRejection(request.Context(), strictSourceBatch, principal.User.ID, payload.ReasonCodes, payload.Comment); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
batch.Status = domain.HumanBatchBlocked
_ = server.store.UpsertHumanBatch(request.Context(), *batch)
}
_ = 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) routeV58AcceptanceRejection(ctx context.Context, source *domain.HumanBatchRecord, actorUserID string, reasonCodes []string, comment string) error {
if source == nil || !domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
return fmt.Errorf("v5.8 aggregate acceptance source batch is unavailable")
}
items, err := server.store.ListHumanItems(ctx, source.OrganizationID, domain.HumanItemQuery{BatchID: source.ID})
if err != nil {
return err
}
for index := range items {
item := items[index]
if strings.TrimSpace(item.ReleasePartitionID) != "" {
return fmt.Errorf("v5.8 accepted item %s was already released before final acceptance", item.ID)
}
previousVersion := item.Version
item.CurrentStageID = domain.FanyuV58StageQualityReview
item.Status = domain.HumanItemSubmitted
item.AssignedUserID = ""
item.ClaimedAt = ""
item.AcceptedAt = ""
item.AcceptedByUserID = ""
item.RejectedAt = ""
item.ReviewRound++
item.Version++
item.UpdatedAt = nowISO()
updated, updateErr := server.store.UpdateHumanItemVersioned(ctx, item, previousVersion)
if updateErr != nil || !updated {
if updateErr != nil {
return updateErr
}
return fmt.Errorf("v5.8 item %s version conflict during whole-batch rejection", item.ID)
}
if strings.TrimSpace(item.LegacyTaskID) != "" {
task, taskErr := server.store.GetAnnotationTask(ctx, item.LegacyTaskID)
if taskErr != nil {
return taskErr
}
if task != nil {
task.Status = domain.AnnotationTaskStatusPendingQuality
task.AssignedUserID = ""
if taskErr = server.store.UpsertAnnotationTask(ctx, *task); taskErr != nil {
return taskErr
}
}
}
_ = server.store.UpsertHumanStageAttempt(ctx, domain.HumanStageAttemptRecord{OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: item.CurrentStageID, Round: item.ReviewRound, Status: item.Status})
_ = server.appendHumanEvent(ctx, item, "aggregate_acceptance_rejected", actorUserID, map[string]any{"reasonCodes": reasonCodes, "comment": strings.TrimSpace(comment), "routedToStage": domain.FanyuV58StageQualityReview})
}
source.Status = domain.HumanBatchActive
source.AcceptedCount = 0
source.UpdatedAt = nowISO()
return server.store.UpsertHumanBatch(ctx, *source)
}
func (server *server) handleHumanRejectsList(writer http.ResponseWriter, request *http.Request) {
query := parseHumanRejectQuery(request)
paged := request.URL.Query().Get("limit") != ""
limit := 0
if paged {
var err error
limit, err = strconv.Atoi(request.URL.Query().Get("limit"))
if err != nil || limit < 1 || limit > 100 {
renderJSON(writer, 400, map[string]string{"error": "limit must be between 1 and 100"})
return
}
query.Limit = limit + 1
}
if cursor := request.URL.Query().Get("cursor"); cursor != "" {
var key []string
raw, err := base64.RawURLEncoding.DecodeString(cursor)
if !paged || err != nil || json.Unmarshal(raw, &key) != nil || len(key) != 2 || key[0] == "" || key[1] == "" {
renderJSON(writer, 400, map[string]string{"error": "invalid cursor"})
return
}
query.BeforeTime, query.BeforeID = key[0], key[1]
}
items, err := server.store.ListHumanRejects(request.Context(), server.requestOrganizationID(request), query)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
nextCursor := ""
if paged && len(items) > limit {
items = items[:limit]
last := items[len(items)-1]
raw, _ := json.Marshal([]string{last.CreatedAt, last.ID})
nextCursor = base64.RawURLEncoding.EncodeToString(raw)
}
// Resolve the page's tasks and memberships once; retain legacy package fallback.
ids := []string{}
for _, reject := range items {
ids = append(ids, reject.ItemID)
}
tasks := map[string]domain.HumanItemRecord{}
if len(ids) > 0 {
rows, e := server.store.ListHumanItems(request.Context(), server.requestOrganizationID(request), domain.HumanItemQuery{IDs: ids, ListProjection: true})
if e != nil {
renderError(writer, 500, e)
return
}
ctx, e := server.withHumanListReads(request.Context(), server.requestOrganizationID(request), query.ProjectID, rows)
if e != nil {
renderError(writer, 500, e)
return
}
request = request.WithContext(ctx)
for _, row := range rows {
tasks[row.ID] = row
}
}
principal, _ := currentPrincipal(request)
if !annotationManager(principal) {
filtered := make([]domain.HumanRejectRecord, 0, len(items))
for _, reject := range items {
task, found := tasks[reject.ItemID]
allowed := false
if found {
allowed = server.canAccessHumanItem(request.Context(), request, task, "")
} else {
allowed = server.canAccessHumanReject(request, reject)
}
if allowed {
filtered = append(filtered, reject)
}
}
items = filtered
}
resolver := newHumanDisplayResolver(server)
for index := range items {
var err error
if task, found := tasks[items[index].ItemID]; found {
err = resolver.enrichItem(request.Context(), &task)
items[index].Display = task.Display
} else {
err = resolver.enrichReject(request.Context(), &items[index])
}
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
renderJSON(writer, http.StatusOK, map[string]any{"items": items, "nextCursor": nextCursor})
}
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": "project human-task membership is required"})
return
}
if err := newHumanDisplayResolver(server).enrichReject(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
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})
}
type humanEscalationDecisionRequest struct {
Version int `json:"version"`
Action string `json:"action"`
TargetStageID string `json:"targetStageId,omitempty"`
Comment string `json:"comment"`
}
func (server *server) handleHumanEscalationDecision(writer http.ResponseWriter, request *http.Request) {
principal, ok := currentPrincipal(request)
if !ok || !isOrganizationAdmin(principal) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "organization admin is required"})
return
}
item, ok := server.loadHumanItemForRequest(writer, request)
if !ok {
return
}
var payload humanEscalationDecisionRequest
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.HumanItemEscalated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "human item is not escalated"})
return
}
payload.Action = strings.ToLower(strings.TrimSpace(payload.Action))
payload.Comment = strings.TrimSpace(payload.Comment)
if payload.Comment == "" || (payload.Action != "reopen" && payload.Action != "close") {
renderValidationError(writer, validationIssue{Field: "escalation", Message: "action (reopen or close) and comment are required"})
return
}
previousVersion := item.Version
if payload.Action == "reopen" {
batch, err := server.store.GetHumanBatch(request.Context(), item.BatchID)
if err != nil || batch == nil {
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
} else {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "human batch not found"})
}
return
}
target := strings.TrimSpace(payload.TargetStageID)
if target == "" {
target = batch.Stages[0].ID
}
if _, _, exists := humanStage(batch, target); !exists {
renderValidationError(writer, validationIssue{Field: "targetStageId", Message: "target stage is not configured for this batch"})
return
}
item.CurrentStageID = target
item.Status = domain.HumanItemRework
item.AssignedUserID = ""
item.ClaimedAt = ""
if item.MaxReworkRounds <= item.ReviewRound {
item.MaxReworkRounds = item.ReviewRound + 1
}
batch.Status = domain.HumanBatchActive
_ = server.store.UpsertHumanBatch(request.Context(), *batch)
} else {
item.Status = domain.HumanItemRejected
item.RejectedAt = 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
}
_ = server.appendHumanEvent(request.Context(), *item, "escalation_"+payload.Action, principal.User.ID, map[string]any{"comment": payload.Comment, "targetStageId": item.CurrentStageID})
rejects, _ := server.store.ListHumanRejects(request.Context(), item.OrganizationID, domain.HumanRejectQuery{ItemID: item.ID})
for _, reject := range rejects {
if reject.Status != domain.HumanRejectEscalated {
continue
}
reject.Status = domain.HumanRejectResolved
reject.Version++
reject.ReopenComment = payload.Comment
reject.UpdatedAt = nowISO()
_ = server.store.UpsertHumanReject(request.Context(), reject)
}
renderJSON(writer, http.StatusOK, item)
}
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
}
func validPoseDeliveryDecision(value domain.PoseDeliveryDecision) bool {
return value == domain.PoseDeliveryInclude || value == domain.PoseDeliveryExclude
}
func acceptancePayloadHasMaterializedSlices(payload map[string]any) bool {
normalized, _ := normalizeStructuredValue(payload).(map[string]any)
items, _ := normalized["items"].([]any)
if len(items) == 0 {
return false
}
for _, rawItem := range items {
item, _ := rawItem.(map[string]any)
materialization, _ := item["materialization"].(map[string]any)
if strings.TrimSpace(fmt.Sprint(materialization["artifactId"])) == "" {
return false
}
}
return true
}
func v58AggregateSourceBatch(ctx context.Context, server *server, batch *domain.HumanBatchRecord) (*domain.HumanBatchRecord, bool, error) {
if batch == nil || strings.TrimSpace(batch.SourceBatchID) == "" {
return nil, false, nil
}
source, err := server.humanBatchForListRead(ctx, batch.SourceBatchID)
if err != nil || source == nil {
return source, false, err
}
return source, domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages), nil
}
func sampledManualAcceptanceItems(items []domain.HumanItemRecord) []domain.HumanItemRecord {
selected := make([]domain.HumanItemRecord, 0, len(items))
for _, item := range items {
if item.AcceptanceSampleProbability == nil || item.AcceptanceSampleValue == nil || *item.AcceptanceSampleValue < *item.AcceptanceSampleProbability {
selected = append(selected, item)
}
}
return selected
}
// 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
}
}
samplingDecision, samplingErr := server.ensureCaptureSamplingDecision(ctx, source)
if samplingErr != nil {
return false, samplingErr
}
if samplingDecision != nil && samplingDecision.Decision == domain.CaptureSamplingNotSelected {
return true, nil
}
if samplingDecision == nil && domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
// New manual Runs use the same per-Capture draw frozen at submission.
// Historical items without a frozen draw retain full acceptance.
items = sampledManualAcceptanceItems(items)
if len(items) == 0 {
return true, nil
}
}
batchID := fanyuV5PrePackageAcceptanceBatchID(source.ID)
acceptanceBatch, err := server.store.GetHumanBatch(ctx, batchID)
if err != nil {
return false, err
}
if acceptanceBatch == nil {
now := nowISO()
stage := domain.HumanStageDefinition{ID: fanyuV5PrePackageAcceptanceStageID, Label: "包前最终验收(仅确认)", Kind: domain.HumanStageAcceptance, RequiredRole: "quality_reviewer", EditorSchema: "acceptance-statistics/v1", ConfirmOnly: true}
if domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
stage = domain.HumanStageDefinition{ID: fanyuV5PrePackageAcceptanceStageID, Label: "整包最终验收", Kind: domain.HumanStageAcceptance, RequiredRole: "acceptance_reviewer", EditorSchema: "acceptance-package/v2", RejectTargets: []string{domain.FanyuV58StageQualityReview}}
}
acceptanceBatch = &domain.HumanBatchRecord{
ProcessingProfile: source.ProcessingProfile,
ID: batchID, OrganizationID: source.OrganizationID, PluginID: source.PluginID,
ProjectID: source.ProjectID, WorkflowID: source.WorkflowID, RunID: source.RunID, ContractRevision: source.ContractRevision,
GateNodeID: source.GateNodeID + "-prepackage-acceptance", SourceBatchID: source.ID,
Status: domain.HumanBatchActive, ItemCount: 1, MaxReworkRounds: 0,
Stages: []domain.HumanStageDefinition{stage},
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 && acceptanceItem.Status == domain.HumanItemAccepted {
return true, nil
}
if acceptanceItem != nil && acceptanceItem.Status != domain.HumanItemRejected && acceptancePayloadHasMaterializedSlices(acceptanceItem.Subject.Payload) {
return false, 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"]
materialization, _ := humanItem.Subject.Payload["materialization"].(map[string]any)
if strings.TrimSpace(fmt.Sprint(materialization["artifactId"])) == "" {
return false, fmt.Errorf("fanyu v5 acceptance materialized slice evidence missing for task %s", task.ID)
}
acceptanceSlices := append([]domain.SliceSegment(nil), latestSlices.Segments...)
if domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
for i := range acceptanceSlices {
acceptanceSlices[i].DiscardedByUserID = ""
}
}
aggregate = append(aggregate, map[string]any{
"taskId": task.ID, "runId": task.RunID, "sourceHumanItemId": humanItem.ID,
"annotationRevision": latestRevision.Revision,
"clipArtifactId": task.ArtifactID, "sourceVideo": task.SourceVideo,
"clipStart": task.ClipStart, "clipEnd": task.ClipEnd,
"finalSlices": acceptanceSlices, "annotation": latestRevision.Segments,
"poseSummary": poseSummary, "materialization": materialization,
})
}
now := nowISO()
if acceptanceItem == nil {
supplierID := items[0].SupplierID
legacyAssignment := items[0].LegacyAssignment
workgroupID, vendorID := items[0].WorkgroupID, items[0].VendorID
if domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages) {
// Platform acceptance is project-scoped and intentionally anonymized.
supplierID, workgroupID, vendorID = "", "", ""
legacyAssignment = nil
}
acceptanceItem = &domain.HumanItemRecord{
ProcessingProfile: source.ProcessingProfile,
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, "strictThreeRole": domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages)}},
CurrentStageID: fanyuV5PrePackageAcceptanceStageID, Status: domain.HumanItemReady,
SupplierID: supplierID, LegacyAssignment: legacyAssignment,
WorkgroupID: workgroupID, VendorID: vendorID, MaxReworkRounds: source.MaxReworkRounds, Version: 1, CreatedAt: now, UpdatedAt: now,
}
} else {
acceptanceItem.Subject.Payload = map[string]any{"sourceBatchId": source.ID, "items": aggregate, "statistics": statistics, "strictThreeRole": domain.IsFanyuV58ThreeRoleHumanLoop(source.Stages)}
acceptanceItem.Status = domain.HumanItemReady
acceptanceItem.AssignedUserID = ""
acceptanceItem.ClaimedAt = ""
acceptanceItem.AcceptedAt = ""
acceptanceItem.AcceptedByUserID = ""
acceptanceItem.RejectedAt = ""
acceptanceItem.Version++
acceptanceItem.UpdatedAt = now
acceptanceBatch.Status = domain.HumanBatchActive
_ = server.store.UpsertHumanBatch(ctx, *acceptanceBatch)
}
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 aggregatePrePackageAcceptanceBatch(batch *domain.HumanBatchRecord) bool {
return batch != nil && strings.TrimSpace(batch.SourceBatchID) != "" && len(batch.Stages) == 1 && batch.Stages[0].ID == fanyuV5PrePackageAcceptanceStageID
}
func (server *server) flushHumanReleasePartitions(ctx context.Context, batch *domain.HumanBatchRecord, force bool) error {
if batch == nil || batch.Status == domain.HumanBatchBlocked || batch.Status == domain.HumanBatchCompleted || batch.ReleasePolicy == "" || aggregatePrePackageAcceptanceBatch(batch) {
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)
allAccepted := len(items) > 0
allTerminal := len(items) > 0
for _, item := range items {
if item.Status != domain.HumanItemAccepted {
allAccepted = false
}
if item.Status != domain.HumanItemAccepted && item.Status != domain.HumanItemRejected && item.Status != domain.HumanItemEscalated && item.Status != domain.HumanItemCancelled {
allTerminal = false
}
if item.Status == domain.HumanItemAccepted && item.ReleasePartitionID == "" {
accepted = append(accepted, item)
}
}
if batch.RequirePrePackageAcceptance {
if !allAccepted {
return nil
}
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)
}
// humanReleaseFlushSweepInterval is how often the background sweeper looks for
// batches whose PartitionMaxWaitSeconds wait window expired without a further
// item write. The write paths already flush on every item acceptance, so this
// interval only adds latency for the wait-expiry case that the old
// GET /api/human-batches flush used to cover opportunistically.
const humanReleaseFlushSweepInterval = 60 * time.Second
// One sweeper per process: NewHandlerWithConfig also runs in every test, and a
// single loop is enough for the whole API (flushHumanReleasePartitions is
// idempotent across replicas, same as it was across concurrent GETs).
var humanReleaseFlushSweeperOnce sync.Once
// startHumanReleasePartitionSweeper moves release-partition flushing off the
// GET read path (S4): item-acceptance write paths flush immediately, and this
// periodic sweep covers wait-expiry batches within one interval.
func (server *server) startHumanReleasePartitionSweeper() {
humanReleaseFlushSweeperOnce.Do(func() {
go func() {
ticker := time.NewTicker(humanReleaseFlushSweepInterval)
defer ticker.Stop()
for range ticker.C {
server.sweepHumanReleasePartitions()
}
}()
})
}
func (server *server) sweepHumanReleasePartitions() {
listCtx, listCancel := context.WithTimeout(context.Background(), 30*time.Second)
ids, err := server.store.ListHumanBatchIDsAwaitingRelease(listCtx)
listCancel()
if err != nil {
log.Printf("[human-release-sweeper] list awaiting batches: %v", err)
return
}
for _, id := range ids {
batchCtx, batchCancel := context.WithTimeout(context.Background(), 30*time.Second)
batch, err := server.store.GetHumanBatch(batchCtx, id)
if err != nil {
batchCancel()
log.Printf("[human-release-sweeper] get batch %s: %v", id, err)
continue
}
if batch == nil || batch.Status == domain.HumanBatchBlocked || batch.Status == domain.HumanBatchCompleted || batch.ReleasePolicy == "" || aggregatePrePackageAcceptanceBatch(batch) {
batchCancel()
continue
}
if batch.RequirePrePackageAcceptance {
acceptanceItem, acceptanceErr := server.store.GetHumanItem(batchCtx, fanyuV5PrePackageAcceptanceItemID(batch.ID))
if acceptanceErr != nil {
batchCancel()
log.Printf("[human-release-sweeper] get prepackage acceptance item for batch %s: %v", id, acceptanceErr)
continue
}
// Skip only when an existing pre-package acceptance item is still
// awaiting final approval (ready/in_progress) and already has its
// materialized slice payload. If the acceptance item does not exist
// yet (e.g. a crash or timeout occurred after the last source item was
// accepted), or was rejected/missing materialized slices, fall through
// to flushHumanReleasePartitions so ensureFanyuV5PrePackageAcceptance
// can recover once all source items are accepted.
if acceptanceItem != nil && acceptanceItem.Status != domain.HumanItemAccepted && acceptanceItem.Status != domain.HumanItemRejected && acceptancePayloadHasMaterializedSlices(acceptanceItem.Subject.Payload) {
batchCancel()
continue
}
}
if err := server.flushHumanReleasePartitions(batchCtx, batch, false); err != nil {
log.Printf("[human-release-sweeper] flush batch %s: %v", id, err)
}
batchCancel()
}
}
// History grants read access only; mutation handlers retain current-stage checks.
func (server *server) canReadReviewedHumanItem(ctx context.Context, request *http.Request, item domain.HumanItemRecord) bool {
principal, ok := currentPrincipal(request)
if !ok || principal == nil || request.Method != http.MethodGet || !server.canAccessHumanItem(ctx, request, item, "") {
return false
}
if principal.User.Role != domain.UserRoleQualityReviewer && principal.User.Role != domain.UserRoleAcceptanceReviewer {
return false
}
ids, err := server.store.ListReviewedHumanItemIDs(ctx, item.OrganizationID, principal.User.ID)
if err != nil {
return false
}
for _, id := range ids {
if id == item.ID {
return true
}
}
return false
}