droboticflow/internal/api/annotation_operations.go
d-robotics 63512da71f
Some checks failed
web-ci / checks (push) Waiting to run
web-ci / checks (pull_request) Has been cancelled
🐛 Preserve confirmed annotation frames and enforce v4 time evidence
2026-10-22 12:54:08 +08:00

3915 lines
178 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

package api
import (
"context"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"log"
"math"
"net/http"
"os"
"path/filepath"
"sort"
"strconv"
"strings"
"sync"
"time"
"droboticflow/internal/domain"
"droboticflow/internal/store"
"github.com/go-chi/chi/v5"
"go.mongodb.org/mongo-driver/mongo"
)
type asynchronousAnnotationResponseWriter struct {
header http.Header
status int
body strings.Builder
}
func (writer *asynchronousAnnotationResponseWriter) Header() http.Header {
if writer.header == nil {
writer.header = http.Header{}
}
return writer.header
}
func (writer *asynchronousAnnotationResponseWriter) WriteHeader(status int) {
if writer.status == 0 {
writer.status = status
}
}
func (writer *asynchronousAnnotationResponseWriter) Write(payload []byte) (int, error) {
if writer.status == 0 {
writer.status = http.StatusOK
}
return writer.body.Write(payload)
}
func deprecatedAnnotationEndpoint(next http.HandlerFunc) http.HandlerFunc {
return func(writer http.ResponseWriter, request *http.Request) {
writer.Header().Set("Deprecation", "true")
writer.Header().Set("Sunset", "Wed, 18 Feb 2027 00:00:00 GMT")
writer.Header().Add("Link", `</api/plugins/annotation-qa>; rel="successor-version"`)
next(writer, request)
}
}
func annotationManager(principal *authenticatedPrincipal) bool {
if principal == nil {
return false
}
return isOrganizationAdmin(principal)
}
func annotationPrincipalUserID(principal *authenticatedPrincipal) string {
if principal == nil {
return ""
}
return principal.User.ID
}
func annotationRoleValid(role domain.AnnotationAssignmentRole) bool {
switch role {
case domain.AnnotationRoleAnnotator, domain.AnnotationRoleQualityReviewer, domain.AnnotationRoleAcceptanceReviewer:
return true
default:
return false
}
}
func annotationTaskStatusValid(status domain.AnnotationTaskStatus) bool {
switch status {
case domain.AnnotationTaskStatusPendingAnnotation, domain.AnnotationTaskStatusPendingQuality,
domain.AnnotationTaskStatusPendingAcceptance, domain.AnnotationTaskStatusRework,
domain.AnnotationTaskStatusAccepted, domain.AnnotationTaskStatusRejected:
return true
default:
return false
}
}
type annotationProjectRole struct {
ProjectID string
UserID string
SupplierID string
Role domain.AnnotationAssignmentRole
AccountRole domain.UserRole
AuthorizationMode string
GrantStatus string
DrainTaskIDs map[string]bool
}
func (server *server) annotationMembershipsForUser(ctx context.Context, organizationID string, projectID string, userID string) ([]annotationProjectRole, error) {
cache, ok := ctx.Value(humanListReadsKey{}).(*humanListReads)
if !ok {
return server.loadAnnotationMembershipsForUser(ctx, organizationID, projectID, userID)
}
key := humanListMembershipKey{organizationID, projectID, userID}
if result, found := cache.memberships[key]; found {
return result.roles, result.err
}
// Derive per-project roles from the request-scoped organization-wide
// snapshot instead of repeating GetUser+ListProjectMembers+GetSupplier+
// ListSupplierProjectAuthorizations for every project. Both store queries
// treat projectID="" as "the full organization set", and
// loadAnnotationMembershipsForUser only filters those lists by
// project/supplier/user, so filtering the (org, "", user) roles by project
// is exactly the (org, projectID, user) result.
if trimmed := strings.TrimSpace(projectID); trimmed != "" {
if base, found := cache.memberships[humanListMembershipKey{organizationID, "", userID}]; found && base.err == nil {
derived := deriveMembershipRolesForProject(base.roles, trimmed)
cache.memberships[key] = humanListMembershipResult{derived, nil}
return derived, nil
}
}
roles, err := server.loadAnnotationMembershipsForUser(ctx, organizationID, projectID, userID)
cache.memberships[key] = humanListMembershipResult{roles, err}
return roles, err
}
func deriveMembershipRolesForProject(roles []annotationProjectRole, projectID string) []annotationProjectRole {
derived := make([]annotationProjectRole, 0)
for _, role := range roles {
if role.ProjectID == projectID {
derived = append(derived, role)
}
}
return derived
}
func (server *server) loadAnnotationMembershipsForUser(ctx context.Context, organizationID string, projectID string, userID string) ([]annotationProjectRole, error) {
filtered := make([]annotationProjectRole, 0)
accountRole := domain.UserRole("")
var account *domain.UserRecord
if user, userErr := server.store.GetUser(ctx, userID); userErr != nil {
return nil, userErr
} else if user != nil {
accountRole = user.Role
account = user
}
projectMembers, err := server.store.ListProjectMembers(ctx, organizationID, projectID)
if err != nil {
return nil, err
}
for _, member := range projectMembers {
if account == nil || !annotationOrganizationEqual(account.OrganizationID, organizationID) || account.Status == domain.UserStatusDisabled || member.UserID != userID || member.SupplierID == "" || member.SupplierID != account.SupplierID {
continue
}
for _, role := range domain.AccountProductionRoles(*account) {
filtered = append(filtered, annotationProjectRole{
ProjectID: member.ProjectID, UserID: member.UserID, SupplierID: member.SupplierID, Role: role, AccountRole: accountRole, AuthorizationMode: "legacy",
})
}
}
if account == nil || !annotationOrganizationEqual(account.OrganizationID, organizationID) || account.Status == domain.UserStatusDisabled || account.DeletedAt != "" || account.SupplierID == "" {
return nil, nil
}
supplier, err := server.store.GetSupplier(ctx, account.SupplierID)
if err != nil {
return nil, err
}
if supplier == nil || !annotationOrganizationEqual(supplier.OrganizationID, organizationID) || !strings.EqualFold(supplier.Status, "active") {
// Old member-scoped workflows retain their existing access model.
// Strict Fanyu tasks reject this legacy-only role below.
return filtered, nil
}
grants, err := server.store.ListSupplierProjectAuthorizations(ctx, organizationID, projectID)
if err != nil {
return nil, err
}
for _, grant := range grants {
if grant.SupplierID != account.SupplierID {
continue
}
drain := map[string]bool{}
for _, id := range grant.DrainTaskIDs {
drain[id] = true
}
for _, role := range domain.AccountProductionRoles(*account) {
merged := false
for index := range filtered {
if filtered[index].ProjectID == grant.ProjectID && filtered[index].SupplierID == grant.SupplierID && filtered[index].Role == role {
filtered[index].AuthorizationMode = "both"
filtered[index].GrantStatus = grant.Status
filtered[index].DrainTaskIDs = drain
merged = true
break
}
}
if !merged {
filtered = append(filtered, annotationProjectRole{ProjectID: grant.ProjectID, UserID: account.ID, SupplierID: grant.SupplierID, Role: role, AccountRole: accountRole, AuthorizationMode: "supplier_grant", GrantStatus: grant.Status, DrainTaskIDs: drain})
}
}
}
return filtered, nil
}
func membershipAllowsTask(memberships []annotationProjectRole, task domain.AnnotationTaskRecord) bool {
// Never reinterpret historical internal tasks as public tasks before an
// approved data migration. New tasks only use ordinary supplier ownership.
if task.ProcessingScope == "internal" && task.SupplierID == "" {
return false
}
for _, membership := range memberships {
if membership.ProjectID != task.ProjectID {
continue
}
if task.SupplierPool {
if membership.AuthorizationMode != "supplier_grant" && membership.AuthorizationMode != "both" {
continue
}
if membership.GrantStatus != "active" && (task.SupplierID == "" || !membership.DrainTaskIDs[task.ID] || task.SupplierPoolClosed || task.Status == domain.AnnotationTaskStatusAccepted || task.Status == domain.AnnotationTaskStatusRejected) {
continue
}
} else if membership.AuthorizationMode == "supplier_grant" {
continue
}
taskSupplierID := task.SupplierID
if taskSupplierID != "" {
// Current ProjectMember routing is supplier-scoped. An unscoped member
// must never become a wildcard across suppliers.
if strings.TrimSpace(membership.SupplierID) != taskSupplierID {
continue
}
}
return true
}
return false
}
func membershipAllowsTaskRead(memberships []annotationProjectRole, task domain.AnnotationTaskRecord) bool {
for _, membership := range memberships {
if membershipAllowsTask([]annotationProjectRole{membership}, task) {
return true
}
}
return false
}
func membershipHasRole(memberships []annotationProjectRole, task domain.AnnotationTaskRecord, role domain.AnnotationAssignmentRole) bool {
for _, membership := range memberships {
if membership.Role == role && membershipAllowsTask([]annotationProjectRole{membership}, task) {
return true
}
}
return false
}
func (server *server) taskUsesSupplierPool(ctx context.Context, task domain.AnnotationTaskRecord) (bool, bool, error) {
if task.ProcessingProfile != domain.ProcessingProfileRawHuman && task.ProcessingProfile != "" {
return false, false, nil
}
item, err := server.humanItemForLegacyTask(ctx, task)
if err != nil || item == nil {
return false, false, err
}
batch, err := server.humanBatchForListRead(ctx, item.BatchID)
if err != nil || batch == nil {
return false, false, err
}
closed := item.Status == domain.HumanItemAccepted || item.Status == domain.HumanItemRejected || item.Status == domain.HumanItemCancelled
return batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages), closed, nil
}
func (server *server) getAnnotationTaskForAccess(ctx context.Context, id string) (*domain.AnnotationTaskRecord, error) {
task, err := server.store.GetAnnotationTask(ctx, id)
if err != nil || task == nil {
return task, err
}
task.SupplierPool, task.SupplierPoolClosed, err = server.taskUsesSupplierPool(ctx, *task)
return task, err
}
func (server *server) ensureAnnotationTaskAccess(writer http.ResponseWriter, request *http.Request, task domain.AnnotationTaskRecord) (*authenticatedPrincipal, []annotationProjectRole, bool) {
principal, ok := currentPrincipal(request)
if !ok || principal == nil {
renderJSON(writer, http.StatusUnauthorized, map[string]string{"error": "login is required"})
return nil, nil, false
}
if !server.ensureTenantAccess(writer, request, task.OrganizationID, "Annotation task") {
return nil, nil, false
}
if annotationManager(principal) {
return principal, nil, true
}
memberships, err := server.annotationMembershipsForUser(request.Context(), task.OrganizationID, task.ProjectID, principal.User.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, nil, false
}
if task.ProcessingProfile == "" && task.ID != "" {
linked, lookupErr := server.humanItemForLegacyTask(request.Context(), task)
if lookupErr != nil {
renderError(writer, http.StatusInternalServerError, lookupErr)
return nil, nil, false
}
if linked != nil {
batch, batchErr := server.store.GetHumanBatch(request.Context(), linked.BatchID)
if batchErr != nil {
renderError(writer, http.StatusInternalServerError, batchErr)
return nil, nil, false
}
if batch != nil && batch.ProcessingProfile == domain.ProcessingProfileRawHuman && domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) {
task.ProcessingProfile = domain.ProcessingProfileRawHuman
task.SupplierPool = true
task.SupplierPoolClosed = linked.Status == domain.HumanItemAccepted || linked.Status == domain.HumanItemRejected || linked.Status == domain.HumanItemCancelled
}
}
}
if task.ProcessingProfile == domain.ProcessingProfileRawHuman && !task.SupplierPool {
task.SupplierPool, task.SupplierPoolClosed, err = server.taskUsesSupplierPool(request.Context(), task)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil, nil, false
}
}
if !membershipAllowsTaskRead(memberships, task) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "project annotation membership is required"})
return nil, nil, false
}
return principal, memberships, true
}
func annotationOrganizationEqual(left string, right string) bool {
return normalizedTenantID(left) == normalizedTenantID(right)
}
type annotationTemplateInput struct {
ProjectID string `json:"projectId"`
Name string `json:"name"`
Version int `json:"version"`
Labels []domain.SemanticLabelDefinition `json:"labels"`
Phrases []string `json:"phrases,omitempty"`
Prelabel domain.AnnotationPrelabelSettings `json:"prelabel"`
HumanStages []domain.HumanStageDefinition `json:"humanStages,omitempty"`
}
func validateHumanStages(stages []domain.HumanStageDefinition) []validationIssue {
if len(stages) == 0 {
return nil
}
issues := make([]validationIssue, 0)
seen := map[string]int{}
for index, stage := range stages {
stage.ID = strings.TrimSpace(stage.ID)
if stage.ID == "" || strings.TrimSpace(stage.Label) == "" || strings.TrimSpace(stage.RequiredRole) == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("humanStages.%d", index), Message: "id, label and requiredRole are required"})
}
if previous, exists := seen[stage.ID]; exists {
issues = append(issues, validationIssue{Field: fmt.Sprintf("humanStages.%d.id", index), Message: fmt.Sprintf("stage id duplicates humanStages.%d", previous)})
}
seen[stage.ID] = index
if stage.Kind != domain.HumanStageAnnotation && stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance {
issues = append(issues, validationIssue{Field: fmt.Sprintf("humanStages.%d.kind", index), Message: "kind must be annotation, review, or acceptance"})
}
for _, target := range stage.RejectTargets {
targetIndex, exists := seen[target]
if !exists || targetIndex >= index {
issues = append(issues, validationIssue{Field: fmt.Sprintf("humanStages.%d.rejectTargets", index), Message: "reject target must reference an earlier stage"})
}
}
}
return issues
}
func validateAnnotationLabels(labels []domain.SemanticLabelDefinition) []validationIssue {
issues := make([]validationIssue, 0)
seenIDs := map[string]struct{}{}
seenNames := map[string]struct{}{}
for index := range labels {
labels[index].ID = strings.TrimSpace(labels[index].ID)
labels[index].Name = strings.TrimSpace(labels[index].Name)
if labels[index].ID == "" || labels[index].Name == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("labels.%d", index), Message: "id and name are required"})
continue
}
idKey := strings.ToLower(labels[index].ID)
nameKey := strings.ToLower(labels[index].Name)
if _, ok := seenIDs[idKey]; ok {
issues = append(issues, validationIssue{Field: fmt.Sprintf("labels.%d.id", index), Message: "label id must be unique"})
}
if _, ok := seenNames[nameKey]; ok {
issues = append(issues, validationIssue{Field: fmt.Sprintf("labels.%d.name", index), Message: "label name must be unique"})
}
seenIDs[idKey] = struct{}{}
seenNames[nameKey] = struct{}{}
}
return issues
}
func (server *server) handleAnnotationTemplatesList(writer http.ResponseWriter, request *http.Request) {
projectID := strings.TrimSpace(request.URL.Query().Get("projectId"))
items, err := server.store.ListAnnotationTemplates(request.Context(), server.requestOrganizationID(request), projectID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
principal, _ := currentPrincipal(request)
if !annotationManager(principal) && principal != nil {
memberships, loadErr := server.annotationMembershipsForUser(request.Context(), server.requestOrganizationID(request), projectID, principal.User.ID)
if loadErr != nil {
renderError(writer, http.StatusInternalServerError, loadErr)
return
}
projects := map[string]struct{}{}
for _, membership := range memberships {
projects[membership.ProjectID] = struct{}{}
}
filtered := items[:0]
visibility := map[string]bool{}
for _, item := range items {
if strings.TrimSpace(item.ProjectID) == "" {
filtered = append(filtered, item)
continue
}
visible, seen := visibility[item.ProjectID]
if !seen {
visible = server.projectVisibleToRequest(request, server.requestOrganizationID(request), item.ProjectID)
visibility[item.ProjectID] = visible
}
if !visible {
continue
}
if _, ok := projects[item.ProjectID]; ok {
filtered = append(filtered, item)
}
}
items = filtered
}
renderJSON(writer, http.StatusOK, map[string]any{"items": items})
}
func (server *server) handleAnnotationTemplateCreate(writer http.ResponseWriter, request *http.Request) {
principal, _ := currentPrincipal(request)
var payload annotationTemplateInput
if !decodeJSON(writer, request, &payload) {
return
}
payload.ProjectID = strings.TrimSpace(payload.ProjectID)
payload.Name = strings.TrimSpace(payload.Name)
issues := validateHumanStages(payload.HumanStages)
if payload.ProjectID == "" {
issues = append(issues, validationIssue{Field: "projectId", Message: "projectId is required"})
}
if payload.Name == "" {
issues = append(issues, validationIssue{Field: "name", Message: "name is required"})
}
if payload.Version <= 0 {
issues = append(issues, validationIssue{Field: "version", Message: "version must be positive"})
}
if payload.Prelabel.MinimumConfidence < 0 || payload.Prelabel.MinimumConfidence > 1 || math.IsNaN(payload.Prelabel.MinimumConfidence) {
issues = append(issues, validationIssue{Field: "prelabel.minimumConfidence", Message: "minimumConfidence must be between 0 and 1"})
}
if len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
project, err := server.store.GetProject(request.Context(), payload.ProjectID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if project == nil || !server.filterByTenant(request, project.OrganizationID) {
renderValidationError(writer, validationIssue{Field: "projectId", Message: "project not found"})
return
}
labels, labelErr := server.projectAnnotationLabelDefinitions(request.Context(), project.OrganizationID, project.ID)
if labelErr != nil {
renderError(writer, http.StatusInternalServerError, labelErr)
return
}
if len(labels) == 0 {
renderValidationError(writer, validationIssue{Field: "labels", Message: "请先在项目的语义标签页启用组织标签"})
return
}
payload.Labels = labels
if issues := validateAnnotationLabels(payload.Labels); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
item := domain.AnnotationTemplateRecord{
ID: domain.NewID("annotation-template"),
OrganizationID: project.OrganizationID,
ProjectID: project.ID,
Name: payload.Name,
Version: payload.Version,
Status: domain.AnnotationTemplateDraft,
Labels: payload.Labels,
Phrases: payload.Phrases,
Prelabel: payload.Prelabel,
HumanStages: payload.HumanStages,
CreatedByUserID: annotationPrincipalUserID(principal),
CreatedAt: nowISO(),
}
if len(item.HumanStages) == 0 {
item.HumanStages = domain.DefaultAnnotationHumanStages()
}
if err := server.store.UpsertAnnotationTemplate(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
saved, err := server.store.GetAnnotationTemplate(request.Context(), item.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusCreated, saved)
}
func (server *server) handleAnnotationTemplatePublish(writer http.ResponseWriter, request *http.Request) {
item, err := server.store.GetAnnotationTemplate(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item == nil || !server.ensureTenantAccess(writer, request, item.OrganizationID, "Annotation template") {
if item == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation template not found"})
}
return
}
principal, _ := currentPrincipal(request)
item.Status = domain.AnnotationTemplatePublished
item.PublishedByUserID = annotationPrincipalUserID(principal)
item.PublishedAt = nowISO()
if err := server.store.UpsertAnnotationTemplate(request.Context(), *item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
renderJSON(writer, http.StatusOK, item)
}
type annotationTaskInput struct {
ProjectID string `json:"projectId"`
DataTaskID string `json:"dataTaskId,omitempty"`
WorkflowID string `json:"workflowId,omitempty"`
RunID string `json:"runId,omitempty"`
NodeID string `json:"nodeId,omitempty"`
ArtifactID string `json:"artifactId,omitempty"`
SourceVideo string `json:"sourceVideo"`
ClipStart float64 `json:"clipStart"`
ClipEnd float64 `json:"clipEnd"`
TemplateID string `json:"templateId"`
SupplierID string `json:"supplierId"`
AssignedUserID string `json:"assignedUserId,omitempty"`
}
// annotationTaskListRecord keeps task-pool routing server-authoritative without
// persisting UI-only state on AnnotationTaskRecord. The workbench uses it to
// show a task only in the matching human stage queue.
type annotationTaskListRecord struct {
domain.AnnotationTaskRecord
HumanStageID string `json:"humanStageId,omitempty"`
SliceCount int `json:"sliceCount"`
CompletedSliceCount int `json:"completedSliceCount"`
PendingSliceCount int `json:"pendingSliceCount"`
AnnotationEventCount int `json:"annotationEventCount"`
}
type annotationTaskListProgress struct {
SliceCount int
CompletedSliceCount int
PendingSliceCount int
AnnotationEventCount int
}
func annotationTaskProgress(sliceRevision *domain.SliceRevisionRecord, annotationRevision *domain.AnnotationRevisionRecord) annotationTaskListProgress {
progress := annotationTaskListProgress{}
if annotationRevision != nil {
progress.AnnotationEventCount = len(annotationRevision.Segments)
}
if sliceRevision == nil {
return progress
}
progress.SliceCount = len(sliceRevision.Segments)
for _, slice := range sliceRevision.Segments {
completed := slice.IsDiscarded() || slice.AnnotationStatus == domain.SliceAnnotationLabeled || slice.AnnotationStatus == domain.SliceAnnotationEmptyConfirmed
if slice.AnnotationStatus == "" && annotationRevision != nil {
for _, segment := range annotationRevision.Segments {
if segment.Start >= slice.Start && segment.End <= slice.End {
completed = true
break
}
}
}
if completed {
progress.CompletedSliceCount++
} else {
progress.PendingSliceCount++
}
}
return progress
}
type annotationTaskListPage struct {
Items []annotationTaskListRecord
NextCursor string
HasMore bool
}
func annotationTaskPage(records []annotationTaskListRecord, raw []domain.AnnotationTaskRecord, limit int64, ids []string) *annotationTaskListPage {
cursor, more := taskPageCursor(raw, limit, ids)
return &annotationTaskListPage{Items: records, NextCursor: cursor, HasMore: more}
}
func (server *server) handleAnnotationTasksList(writer http.ResponseWriter, request *http.Request) {
page := server.readAnnotationTasksList(writer, request)
if page == nil {
return
}
response := map[string]any{"items": page.Items}
if page.HasMore {
response["nextCursor"] = page.NextCursor
response["hasMore"] = true
}
renderJSON(writer, http.StatusOK, response)
}
func (server *server) readAnnotationTasksList(writer http.ResponseWriter, request *http.Request) *annotationTaskListPage {
started := time.Now()
var listTasksMs, humanItemsMs, listReadsMs, reviewedMs, filterMs, sliceRevisionsMs, annotationRevisionsMs, draftsMs int64
defer func() {
log.Printf("[api] annotation_tasks_list_latency operation=handleAnnotationTasksList project=%s total_ms=%d listTasks_ms=%d humanItems_ms=%d listReads_ms=%d reviewed_ms=%d filter_ms=%d sliceRevisions_ms=%d annotationRevisions_ms=%d drafts_ms=%d",
request.URL.Query().Get("projectId"), time.Since(started).Milliseconds(), listTasksMs, humanItemsMs, listReadsMs, reviewedMs, filterMs, sliceRevisionsMs, annotationRevisionsMs, draftsMs)
}()
projectID := strings.TrimSpace(request.URL.Query().Get("projectId"))
status := domain.AnnotationTaskStatus(strings.TrimSpace(request.URL.Query().Get("status")))
supplierID := strings.TrimSpace(request.URL.Query().Get("supplierId"))
workflowID := strings.TrimSpace(request.URL.Query().Get("workflowId"))
runID := strings.TrimSpace(request.URL.Query().Get("runId"))
nodeID := strings.TrimSpace(request.URL.Query().Get("nodeId"))
artifactID := strings.TrimSpace(request.URL.Query().Get("artifactId"))
rawLimit := strings.TrimSpace(request.URL.Query().Get("limit"))
rawCursor := strings.TrimSpace(request.URL.Query().Get("cursor"))
// ids=a,b,c serves pool-item joins: the client's pool page already decided
// which human items it can see, so the task fetch targets exactly their
// legacyTaskIds instead of a newest-first window that may not contain
// them (the join regression behind 任务关联数据缺失).
requestedIDs := []string{}
if rawIDs := strings.TrimSpace(request.URL.Query().Get("ids")); rawIDs != "" {
for _, id := range strings.Split(rawIDs, ",") {
if id = strings.TrimSpace(id); id != "" {
requestedIDs = append(requestedIDs, id)
}
}
}
var cursorCreatedAt, cursorID string
if rawCursor != "" {
payload, cursorErr := base64.RawURLEncoding.DecodeString(rawCursor)
if cursorErr == nil {
var cursor struct {
CreatedAt string `json:"createdAt"`
ID string `json:"id"`
}
if jsonErr := json.Unmarshal(payload, &cursor); jsonErr == nil && cursor.ID != "" {
cursorCreatedAt, cursorID = cursor.CreatedAt, cursor.ID
}
}
}
principal, _ := currentPrincipal(request)
isManager := annotationManager(principal)
// Equality filters are pushed into the store query: the database narrows
// the task set instead of the handler post-filtering an organization-wide
// scan. The createdAt-descending indexes back the sort. An explicit limit
// pages the pool; without one the response keeps the legacy unbounded
// shape so existing consumers are untouched.
segment := time.Now()
var limit int64
if parsed, issue := parseDatabaseBrowserPageQuery(rawLimit, "limit", 0, 1, 10000); issue == nil && rawLimit != "" {
limit = int64(parsed)
}
if len(requestedIDs) > 0 {
limit = 0
}
items, err := server.store.ListAnnotationTasksFiltered(request.Context(), server.requestOrganizationID(request), store.AnnotationTaskFilter{
ProjectID: projectID, Status: string(status), SupplierID: supplierID, WorkflowID: workflowID, RunID: runID, NodeID: nodeID, ArtifactID: artifactID, IDs: requestedIDs,
Limit: limit, CursorCreatedAt: cursorCreatedAt, CursorID: cursorID,
})
listTasksMs = time.Since(segment).Milliseconds()
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil
}
// Human items are joined to the fetched task set via the
// organizationId+legacyTaskId index. The projection drops draft payloads;
// progress drafts are loaded later for the filtered tasks only.
segment = time.Now()
taskIDs := make([]string, 0, len(items))
for _, item := range items {
taskIDs = append(taskIDs, item.ID)
}
humanItems, humanItemsErr := server.store.ListHumanItemsByLegacyTaskIDs(request.Context(), server.requestOrganizationID(request), taskIDs)
humanItemsMs = time.Since(segment).Milliseconds()
if humanItemsErr != nil {
renderError(writer, http.StatusInternalServerError, humanItemsErr)
return nil
}
humanItemByTaskID := make(map[string]domain.HumanItemRecord, len(humanItems))
for _, humanItem := range humanItems {
if strings.TrimSpace(humanItem.LegacyTaskID) != "" {
humanItemByTaskID[humanItem.LegacyTaskID] = humanItem
}
}
// Managers never consult memberships, stage access, supplier pools or
// review history on this path, so the request-scoped list-reads snapshot
// (batch access records, per-task item lookups) is skipped entirely.
if !isManager && principal != nil && len(humanItems) > 0 {
segment = time.Now()
listCtx, listErr := server.withHumanListReads(request.Context(), server.requestOrganizationID(request), projectID, humanItems)
listReadsMs = time.Since(segment).Milliseconds()
if listErr != nil {
renderError(writer, http.StatusInternalServerError, listErr)
return nil
}
request = request.WithContext(listCtx)
}
var memberships []annotationProjectRole
if !isManager && principal != nil {
memberships, err = server.annotationMembershipsForUser(request.Context(), server.requestOrganizationID(request), projectID, principal.User.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil
}
}
reviewedIDs := map[string]bool{}
if principal != nil && (principal.User.Role == domain.UserRoleQualityReviewer || principal.User.Role == domain.UserRoleAcceptanceReviewer) {
segment = time.Now()
ids, historyErr := server.store.ListReviewedHumanItemIDs(request.Context(), server.requestOrganizationID(request), principal.User.ID)
reviewedMs = time.Since(segment).Milliseconds()
if historyErr != nil {
renderError(writer, http.StatusInternalServerError, historyErr)
return nil
}
for _, id := range ids {
reviewedIDs[id] = true
}
}
type filteredTask struct {
task domain.AnnotationTaskRecord
humanStageID string
}
filteredTasks := make([]filteredTask, 0, len(items))
segment = time.Now()
for _, item := range items {
linkedHumanItem, hasHumanItem := humanItemByTaskID[item.ID]
if randomClaimAnnotator(principal) && !hasHumanItem && item.AssignedUserID != principal.User.ID {
continue
}
if !isManager {
item.SupplierPool, item.SupplierPoolClosed, err = server.taskUsesSupplierPool(request.Context(), item)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return nil
}
if !membershipAllowsTaskRead(memberships, item) {
continue
}
if hasHumanItem {
isAuthor := principal != nil && linkedHumanItem.LatestAuthorUserID == principal.User.ID
if !server.canAccessCurrentHumanStage(request.Context(), request, linkedHumanItem) && !isAuthor && !reviewedIDs[linkedHumanItem.ID] {
continue
}
}
}
filteredTasks = append(filteredTasks, filteredTask{task: item, humanStageID: linkedHumanItem.CurrentStageID})
}
filterMs = time.Since(segment).Milliseconds()
if len(filteredTasks) == 0 {
// An authorization-empty page is not the end of the list: the store
// window may contain only tasks this role cannot read while the
// caller's own tasks sit on later pages (e.g. an annotator whose
// rework/claimed tasks are older than the newest import wave). Keep
// the paging metadata so limited consumers can continue.
return annotationTaskPage([]annotationTaskListRecord{}, items, limit, requestedIDs)
}
// Progress is derived only after all query and authorization filters have
// been applied. Revisions are fetched per filtered task (batched $in) so
// the query no longer scans the whole organization.
filteredTaskIDs := make([]string, 0, len(filteredTasks))
seenTaskIDs := make(map[string]struct{}, len(filteredTasks))
for _, item := range filteredTasks {
if _, seen := seenTaskIDs[item.task.ID]; seen {
continue
}
seenTaskIDs[item.task.ID] = struct{}{}
filteredTaskIDs = append(filteredTaskIDs, item.task.ID)
}
// Both reads use the already authorized task IDs and are independent.
// Join before deriving progress or touching the request-scoped read cache.
// Keep concurrency bounded to two reads per request and preserve both errors.
var sliceRevisions []domain.SliceRevisionRecord
var annotationRevisions []domain.AnnotationRevisionRecord
var sliceRevisionsErr, annotationRevisionsErr error
progressContext := request.Context()
progressOrganizationID := server.requestOrganizationID(request)
var progressReads sync.WaitGroup
progressReads.Add(2)
go func() {
defer progressReads.Done()
started := time.Now()
sliceRevisions, sliceRevisionsErr = server.store.ListLatestSliceProgressByTaskIDs(progressContext, progressOrganizationID, filteredTaskIDs)
sliceRevisionsMs = time.Since(started).Milliseconds()
}()
go func() {
defer progressReads.Done()
started := time.Now()
annotationRevisions, annotationRevisionsErr = server.store.ListLatestAnnotationProgressByTaskIDs(progressContext, progressOrganizationID, filteredTaskIDs)
annotationRevisionsMs = time.Since(started).Milliseconds()
}()
progressReads.Wait()
if sliceRevisionsErr != nil || annotationRevisionsErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("load annotation task progress: slices=%v annotations=%v", sliceRevisionsErr, annotationRevisionsErr))
return nil
}
latestSliceByTaskID := make(map[string]*domain.SliceRevisionRecord, len(filteredTasks))
for index := range sliceRevisions {
revision := &sliceRevisions[index]
current := latestSliceByTaskID[revision.TaskID]
if current == nil || revision.Revision > current.Revision {
latestSliceByTaskID[revision.TaskID] = revision
}
}
latestAnnotationByTaskID := make(map[string]*domain.AnnotationRevisionRecord, len(filteredTasks))
for index := range annotationRevisions {
revision := &annotationRevisions[index]
// Revision zero is the system-owned Qwen suggestion. It must not make
// an untouched human slice look completed in the task pool.
if revision.Revision <= 0 || strings.TrimSpace(revision.AuthorUserID) == "system" {
continue
}
current := latestAnnotationByTaskID[revision.TaskID]
if current == nil || revision.Revision > current.Revision {
latestAnnotationByTaskID[revision.TaskID] = revision
}
}
// In-progress drafts still drive pool progress, but they are now fetched
// per filtered task instead of riding an organization-wide scan. Only
// tasks whose human item was touched after its latest slice revision can
// hold a fresher draft; older drafts are superseded by the revision.
segment = time.Now()
draftTaskIDs := make([]string, 0, len(filteredTasks))
seenDraftTaskIDs := make(map[string]struct{}, len(filteredTasks))
for _, item := range filteredTasks {
humanItem, exists := humanItemByTaskID[item.task.ID]
if !exists {
continue
}
if _, seen := seenDraftTaskIDs[item.task.ID]; seen {
continue
}
seenDraftTaskIDs[item.task.ID] = struct{}{}
latest := latestSliceByTaskID[item.task.ID]
if latest == nil || strings.TrimSpace(humanItem.UpdatedAt) > strings.TrimSpace(latest.CreatedAt) {
draftTaskIDs = append(draftTaskIDs, item.task.ID)
}
}
draftProgressByTaskID := map[string]domain.HumanItemDraftProgress{}
if len(draftTaskIDs) > 0 {
drafts, draftsErr := server.store.ListHumanItemDraftProgress(request.Context(), server.requestOrganizationID(request), draftTaskIDs)
if draftsErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("load annotation task drafts: %w", draftsErr))
return nil
}
for _, draft := range drafts {
draftProgressByTaskID[draft.LegacyTaskID] = draft
}
}
draftsMs = time.Since(segment).Milliseconds()
filtered := make([]annotationTaskListRecord, 0, len(filteredTasks))
for _, item := range filteredTasks {
sliceRevision := latestSliceByTaskID[item.task.ID]
annotationRevision := latestAnnotationByTaskID[item.task.ID]
if draft, exists := draftProgressByTaskID[item.task.ID]; exists && len(draft.SliceSegments) > 0 {
sliceRevision = &domain.SliceRevisionRecord{TaskID: item.task.ID, Segments: draft.SliceSegments}
annotationRevision = &domain.AnnotationRevisionRecord{TaskID: item.task.ID, Segments: draft.Segments}
}
progress := annotationTaskProgress(sliceRevision, annotationRevision)
filtered = append(filtered, annotationTaskListRecord{
AnnotationTaskRecord: item.task,
HumanStageID: item.humanStageID,
SliceCount: progress.SliceCount,
CompletedSliceCount: progress.CompletedSliceCount,
PendingSliceCount: progress.PendingSliceCount,
AnnotationEventCount: progress.AnnotationEventCount,
})
}
return annotationTaskPage(filtered, items, limit, requestedIDs)
}
// taskPageCursor derives the continuation cursor from the raw store page.
// It exists only for explicitly limited, windowed requests (not ids joins)
// and only when the store actually filled the page — otherwise the list is
// exhausted. Both the filtered-empty early exit and the success path must
// agree on it, or a filtered-empty page would silently truncate paging.
func taskPageCursor(items []domain.AnnotationTaskRecord, limit int64, requestedIDs []string) (string, bool) {
if limit <= 0 || len(requestedIDs) > 0 || len(items) != int(limit) {
return "", false
}
last := items[len(items)-1]
payload, err := json.Marshal(map[string]string{"createdAt": last.CreatedAt, "id": last.ID})
if err != nil {
return "", false
}
return base64.RawURLEncoding.EncodeToString(payload), true
}
func (server *server) handleAnnotationTaskGet(writer http.ResponseWriter, request *http.Request) {
item, err := server.getAnnotationTaskForAccess(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": "Annotation task not found"})
return
}
if _, _, ok := server.ensureAnnotationTaskAccess(writer, request, *item); !ok {
return
}
linkedHumanItem, linkedErr := server.humanItemForLegacyTask(request.Context(), *item)
if linkedErr != nil {
renderError(writer, http.StatusInternalServerError, linkedErr)
return
}
principal, _ := currentPrincipal(request)
isAuthor := principal != nil && linkedHumanItem != nil && linkedHumanItem.LatestAuthorUserID == principal.User.ID
if randomClaimAnnotator(principal) && linkedHumanItem == nil && item.AssignedUserID != principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "请先选择项目随机领取任务", "code": "random_claim_required"})
return
}
if linkedHumanItem != nil && !annotationManager(principal) && !server.canAccessCurrentHumanStage(request.Context(), request, *linkedHumanItem) && !isAuthor && !server.canReadReviewedHumanItem(request.Context(), request, *linkedHumanItem) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "current human stage role is required"})
return
}
item.ContinuousActions = server.continuousActionsForItem(request.Context(), linkedHumanItem)
// Polling must not load histories, enrich media, recover state, or rebuild
// timelines. A transition/interrupted job asks the client to fetch detail once.
if request.URL.Query().Get("view") == "summary" {
renderJSON(writer, http.StatusOK, map[string]any{"task": item})
return
}
if request.URL.Query().Get("view") == "status" {
status := map[string]any{"taskId": item.ID, "taskStatus": item.Status}
if progress, ok := server.materializationProgress.Load(item.OrganizationID + ":" + item.ID); ok {
status["progress"] = progress
}
if linkedHumanItem != nil {
w := mapValue(linkedHumanItem.Subject.Payload["sliceWorkflow"])
status["itemId"], status["version"] = linkedHumanItem.ID, linkedHumanItem.Version
status["stage"], status["status"] = linkedHumanItem.CurrentStageID, linkedHumanItem.Status
status["sliceStatus"], status["error"] = w["status"], w["error"]
status["pendingSubmissionId"] = linkedHumanItem.PendingCombinedSubmissionID
if linkedHumanItem.PendingCombinedSubmissionID != "" {
_, active := server.combinedSubmissionJobs.Load(linkedHumanItem.OrganizationID + ":" + linkedHumanItem.PendingCombinedSubmissionID)
status["needsRefresh"] = !active
}
if stringValue(w["status"]) == "processing" {
lease, err := time.Parse(time.RFC3339Nano, stringValue(w["leaseExpiresAt"]))
if err != nil || time.Now().After(lease) {
status["needsRefresh"] = true
}
}
if j := linkedHumanItem.ProcessingJob; j != nil {
status["progress"] = map[string]any{"stage": j.Stage, "completedSlices": j.CompletedSlices, "totalSlices": j.TotalSlices, "startedAt": j.CreatedAt, "attempt": j.Attempt}
if durableAnnotationActive(linkedHumanItem) {
status["needsRefresh"] = false
}
if j.Status == "failed" {
status["error"] = j.Error
}
}
}
renderJSON(writer, http.StatusOK, status)
return
}
if linkedHumanItem != nil {
if err := newHumanDisplayResolver(server).enrichItem(request.Context(), linkedHumanItem); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
if linkedHumanItem != nil && request.URL.Query().Get("view") != "history" {
if err := server.recoverInterruptedSlice(request.Context(), linkedHumanItem, time.Now()); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if linkedHumanItem.PendingCombinedSubmissionID != "" {
jobKey := linkedHumanItem.OrganizationID + ":" + linkedHumanItem.PendingCombinedSubmissionID
_, jobActive := server.combinedSubmissionJobs.Load(jobKey)
if !jobActive && !durableAnnotationActive(linkedHumanItem) {
revisions, _ := server.store.ListAnnotationRevisions(request.Context(), item.OrganizationID, item.ID)
submissionRevisionFound := false
submissionCreatedAt := ""
for _, r := range revisions {
if r.ID == "annotation-"+linkedHumanItem.PendingCombinedSubmissionID {
submissionRevisionFound = true
submissionCreatedAt = r.CreatedAt
break
}
}
now := nowISO()
expectedVersion := linkedHumanItem.Version
if submissionRevisionFound {
linkedHumanItem.CurrentStageID = "quality_review"
linkedHumanItem.Status = domain.HumanItemReady
linkedHumanItem.AssignedUserID = ""
linkedHumanItem.ClaimedAt = ""
linkedHumanItem.SubmittedAt = now
if submissionCreatedAt != "" {
linkedHumanItem.SubmittedAt = submissionCreatedAt
}
if err := server.freezeSubmissionAcceptancePolicy(request.Context(), linkedHumanItem); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
linkedHumanItem.PendingCombinedSubmissionID = ""
linkedHumanItem.PendingCombinedPayloadSHA = ""
linkedHumanItem.Version++
linkedHumanItem.UpdatedAt = now
_, _ = server.store.UpdateHumanItemVersioned(request.Context(), *linkedHumanItem, expectedVersion)
item.Status = domain.AnnotationTaskStatusPendingQuality
item.AssignedUserID = ""
_ = server.store.UpsertAnnotationTask(request.Context(), *item)
} else {
linkedHumanItem.PendingCombinedSubmissionID = ""
linkedHumanItem.PendingCombinedPayloadSHA = ""
linkedHumanItem.Version++
linkedHumanItem.UpdatedAt = now
_, _ = server.store.UpdateHumanItemVersioned(request.Context(), *linkedHumanItem, expectedVersion)
}
}
}
}
revisions, revisionsErr := server.store.ListAnnotationRevisions(request.Context(), item.OrganizationID, item.ID)
sliceRevisions, sliceRevisionsErr := server.store.ListSliceRevisions(request.Context(), item.OrganizationID, item.ID)
reviews, reviewsErr := server.store.ListAnnotationReviews(request.Context(), item.OrganizationID, item.ID)
if revisionsErr != nil || sliceRevisionsErr != nil || reviewsErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("load annotation task history: slices=%v revisions=%v reviews=%v", sliceRevisionsErr, revisionsErr, reviewsErr))
return
}
// Only the published data is editable/viewable. Generation numbers fence
// asynchronous writes; they are not a history selector for employees.
if linkedHumanItem != nil {
generation := intValue(mapValue(linkedHumanItem.Subject.Payload["materialization"])["revision"])
if generation > 0 {
currentSlices := make([]domain.SliceRevisionRecord, 0, 1)
currentAnnotations := make([]domain.AnnotationRevisionRecord, 0, 1)
for _, r := range sliceRevisions {
if r.Revision == generation {
currentSlices = append(currentSlices, r)
}
}
for _, r := range revisions {
if r.Revision == generation {
currentAnnotations = append(currentAnnotations, r)
}
}
sliceRevisions, revisions = currentSlices, currentAnnotations
}
}
if linkedHumanItem != nil && principal != nil {
claimable := false
availableStatus := linkedHumanItem.Status == domain.HumanItemReady || linkedHumanItem.Status == domain.HumanItemRework || linkedHumanItem.Status == domain.HumanItemSubmitted
if linkedHumanItem.AssignedUserID == "" && availableStatus {
batch, batchErr := server.humanBatchForListRead(request.Context(), linkedHumanItem.BatchID)
if batchErr != nil {
renderError(writer, http.StatusInternalServerError, batchErr)
return
}
if stage, _, found := humanStage(batch, linkedHumanItem.CurrentStageID); found {
claimable = server.canClaimHumanItem(request.Context(), request, *linkedHumanItem, annotationRoleForHumanStage(stage))
}
}
linkedHumanItem.CanClaim = &claimable
}
editorState, readinessErr := server.annotationEditorStateForTask(request.Context(), *item, linkedHumanItem)
if readinessErr != nil {
renderError(writer, http.StatusInternalServerError, readinessErr)
return
}
renderJSON(writer, http.StatusOK, map[string]any{"task": item, "sliceRevisions": sliceRevisions, "revisions": revisions, "reviews": reviews, "humanItem": linkedHumanItem, "editorState": editorState})
}
func annotationFrameTimelinePayload(camera string, rows []hardwarePTSRow) (map[string]any, error) {
if len(rows) < 2 {
return nil, fmt.Errorf("%s PTS requires at least two frames", camera)
}
coverageEndUS, err := ptsCoverageEnd(rows)
if err != nil {
return nil, err
}
originUS := rows[0].TimestampUS
boundaries := make([]float64, 0, len(rows)+1)
for _, row := range rows {
boundaries = append(boundaries, float64(row.TimestampUS-originUS)/1_000_000.0)
}
boundaries = append(boundaries, float64(coverageEndUS-originUS)/1_000_000.0)
return map[string]any{
"camera": camera,
"frameCount": len(rows),
"originTimestampUs": originUS,
"coverageEndTimestampUs": coverageEndUS,
"boundariesSeconds": boundaries,
}, nil
}
func (server *server) buildAnnotationFrameTimeline(ctx context.Context, task domain.AnnotationTaskRecord, camera string) (map[string]any, error) {
run, err := server.store.GetRun(ctx, task.RunID)
if err != nil {
return nil, fmt.Errorf("load annotation run: %w", err)
}
if run == nil {
return nil, fmt.Errorf("annotation run %s was not found", task.RunID)
}
var execution *domain.NodeExecutionRecord
for index := range run.NodeExecutions {
if run.NodeExecutions[index].NodeID == task.NodeID {
copy := run.NodeExecutions[index]
execution = &copy
break
}
}
if execution == nil {
return nil, fmt.Errorf("annotation human-gate execution is unavailable")
}
videoPort, timestampPort, side, artifactID := "fullLeftVideos", "leftTimestamps", "left", task.ArtifactID
if camera == "right" {
videoPort, timestampPort, side, artifactID = "fullRightVideos", "rightTimestamps", "right", task.RightArtifactID
}
videoArtifact := artifactByID(artifactsForTarget(*execution, videoPort), artifactID)
if videoArtifact == nil {
videoArtifact = artifactByID(execution.InputArtifacts, artifactID)
}
if videoArtifact == nil {
return nil, fmt.Errorf("%s source video is unavailable", side)
}
collectionID := artifactCollectionID(*videoArtifact)
ptsArtifact := matchingArtifact(artifactsForTarget(*execution, timestampPort), collectionID, side, "pts")
if ptsArtifact == nil {
return nil, fmt.Errorf("%s PTS artifact is unavailable", side)
}
ptsPath, err := server.safeMaterializationSourcePath(ptsArtifact)
if err != nil {
return nil, err
}
rows, err := readHardwarePTS(ptsPath)
if err != nil {
return nil, err
}
leftRows := rows
leftVideo := artifactByID(artifactsForTarget(*execution, "fullLeftVideos"), task.ArtifactID)
if leftVideo == nil {
leftVideo = artifactByID(execution.InputArtifacts, task.ArtifactID)
}
readPTS := func(port, side string) ([]hardwarePTSRow, error) {
a := matchingArtifact(artifactsForTarget(*execution, port), collectionID, side, "pts")
p, e := server.safeMaterializationSourcePath(a)
if e != nil {
return nil, e
}
return readHardwarePTS(p)
}
if camera == "right" {
leftRows, err = readPTS("leftTimestamps", "left")
if err != nil {
return nil, err
}
}
rightRows, err := readPTS("rightTimestamps", "right")
if err != nil {
return nil, err
}
imuArtifact := matchingArtifact(artifactsForTarget(*execution, "imu"), collectionID, "imu", ".csv")
imuPath, err := server.safeMaterializationSourcePath(imuArtifact)
if err != nil {
return nil, err
}
indexScratch, err := os.MkdirTemp("", "annotation-index-")
if err != nil {
return nil, err
}
defer os.RemoveAll(indexScratch)
imuPath, err = server.localAnnotationSource(ctx, task.OrganizationID, imuPath, filepath.Join(indexScratch, "imu.csv"))
if err != nil {
return nil, err
}
imuSummary, err := scanHardwareIMU(ctx, imuPath, nil)
if err != nil {
return nil, err
}
leftPath, err := server.safeMaterializationSourcePath(leftVideo)
if err != nil {
return nil, err
}
duration, err := ffprobeDurationSeconds(ctx, leftPath)
if err != nil {
return nil, err
}
leftEnd, err := ptsCoverageEnd(leftRows)
if err != nil {
return nil, err
}
rightEnd, err := ptsCoverageEnd(rightRows)
if err != nil {
return nil, err
}
imuEnd, err := imuSummary.coverageEnd()
if err != nil {
return nil, err
}
start, end := max(leftRows[0].TimestampUS, rightRows[0].TimestampUS, imuSummary.first), min(leftEnd, rightEnd, imuEnd)
grid, err := newAnnotationBoundaryGrid(leftRows, rightRows, start, end, duration)
if err != nil {
return nil, err
}
rightVideo := matchingArtifact(artifactsForTarget(*execution, "fullRightVideos"), collectionID, "right", ".mp4")
rightPath, err := server.safeMaterializationSourcePath(rightVideo)
if err != nil {
return nil, err
}
rightDuration, err := ffprobeDurationSeconds(ctx, rightPath)
if err != nil {
return nil, err
}
lc, err := ffprobeDeclaredFrameCount(ctx, leftPath)
if err != nil || lc != len(leftRows) {
return nil, fmt.Errorf("左视频与 PTS 帧数不匹配,不能建立统一边界")
}
rc, err := ffprobeDeclaredFrameCount(ctx, rightPath)
if err != nil || rc != len(rightRows) {
return nil, fmt.Errorf("右视频与 PTS 帧数不匹配,不能建立统一边界")
}
rightSeconds := make([]float64, len(grid.Timestamps))
for i, f := range grid.RightFrames {
rightSeconds[i] = float64(f) * rightDuration / float64(len(rightRows))
}
return map[string]any{"camera": camera, "frameCount": len(rows), "leftFrameCount": lc, "rightFrameCount": rc, "originTimestampUs": grid.Origin, "coverageEndTimestampUs": end, "boundariesSeconds": grid.Seconds, "rightBoundariesSeconds": rightSeconds, "boundaryTimestampUs": grid.Timestamps, "leftFrameIndices": grid.LeftFrames, "rightFrameIndices": grid.RightFrames, "rangeStartSecond": grid.Seconds[0], "rangeEndSecond": grid.Seconds[len(grid.Seconds)-1], "boundaryContract": "hardware-frame-v1", "ptsToMediaScale": grid.Scale}, nil
}
func (server *server) handleAnnotationTaskFrameTimelineGet(writer http.ResponseWriter, request *http.Request) {
item, err := server.getAnnotationTaskForAccess(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": "Annotation task not found"})
return
}
if _, _, ok := server.ensureAnnotationTaskAccess(writer, request, *item); !ok {
return
}
linkedHumanItem, linkedErr := server.humanItemForLegacyTask(request.Context(), *item)
if linkedErr != nil {
renderError(writer, http.StatusInternalServerError, linkedErr)
return
}
principal, _ := currentPrincipal(request)
if linkedHumanItem != nil && !annotationManager(principal) && !server.canAccessCurrentHumanStage(request.Context(), request, *linkedHumanItem) && !server.canReadReviewedHumanItem(request.Context(), request, *linkedHumanItem) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "current human stage role is required"})
return
}
camera := strings.ToLower(strings.TrimSpace(request.URL.Query().Get("camera")))
if camera == "" {
camera = "left"
}
if camera != "left" && camera != "right" {
renderValidationError(writer, validationIssue{Field: "camera", Message: "camera must be left or right"})
return
}
payload, err := server.annotationFrameTimelineForTask(request.Context(), *item, camera)
if err != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": err.Error()})
return
}
if request.URL.Query().Get("encoding") == "compact" {
payload, err = server.compactAnnotationTimelines.get(request.Context(), stringValue(payload["sourceFingerprint"])+":"+camera, func(context.Context) (map[string]any, error) { return compactAnnotationTimeline(payload) })
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
renderJSON(writer, http.StatusOK, payload)
}
func (server *server) handleAnnotationTaskCreate(writer http.ResponseWriter, request *http.Request) {
var payload annotationTaskInput
if !decodeJSON(writer, request, &payload) {
return
}
payload.ProjectID = strings.TrimSpace(payload.ProjectID)
payload.DataTaskID = strings.TrimSpace(payload.DataTaskID)
payload.WorkflowID = strings.TrimSpace(payload.WorkflowID)
payload.RunID = strings.TrimSpace(payload.RunID)
payload.NodeID = strings.TrimSpace(payload.NodeID)
payload.ArtifactID = strings.TrimSpace(payload.ArtifactID)
payload.SourceVideo = strings.TrimSpace(payload.SourceVideo)
payload.TemplateID = strings.TrimSpace(payload.TemplateID)
payload.SupplierID = strings.TrimSpace(payload.SupplierID)
if payload.ProjectID == "" || payload.SourceVideo == "" || payload.TemplateID == "" || payload.SupplierID == "" || payload.ClipStart < 0 || payload.ClipEnd <= payload.ClipStart {
renderValidationError(writer, validationIssue{Field: "task", Message: "projectId, sourceVideo, templateId, supplierId and a valid clip range are required"})
return
}
project, projectErr := server.store.GetProject(request.Context(), payload.ProjectID)
template, templateErr := server.store.GetAnnotationTemplate(request.Context(), payload.TemplateID)
supplier, supplierErr := server.store.GetSupplier(request.Context(), payload.SupplierID)
if projectErr != nil || templateErr != nil || supplierErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("load annotation task references: project=%v template=%v supplier=%v", projectErr, templateErr, supplierErr))
return
}
if project == nil || template == nil || supplier == nil || template.ProjectID != project.ID || !annotationOrganizationEqual(project.OrganizationID, template.OrganizationID) || !annotationOrganizationEqual(project.OrganizationID, supplier.OrganizationID) || !strings.EqualFold(strings.TrimSpace(supplier.Status), "active") {
renderValidationError(writer, validationIssue{Field: "task", Message: "project, template and active supplier are incompatible"})
return
}
members, membersErr := server.store.ListProjectMembers(request.Context(), project.OrganizationID, project.ID)
if membersErr != nil {
renderError(writer, http.StatusInternalServerError, membersErr)
return
}
if !supplierHasProductionHumanRoles(members, supplier.ID) {
renderValidationError(writer, validationIssue{Field: "supplierId", Message: "supplier project members must cover annotator, quality reviewer and acceptance reviewer"})
return
}
if template.Status != domain.AnnotationTemplatePublished {
renderValidationError(writer, validationIssue{Field: "templateId", Message: "template must be published before task assignment"})
return
}
item := domain.AnnotationTaskRecord{
ID: domain.NewID("annotation-task"),
OrganizationID: project.OrganizationID,
ProjectID: project.ID,
DataTaskID: payload.DataTaskID,
WorkflowID: payload.WorkflowID,
RunID: payload.RunID,
NodeID: payload.NodeID,
ArtifactID: payload.ArtifactID,
SourceVideo: payload.SourceVideo,
ClipStart: payload.ClipStart,
ClipEnd: payload.ClipEnd,
TemplateID: template.ID,
TemplateVersion: template.Version,
SupplierID: supplier.ID,
AssignedUserID: "",
Status: domain.AnnotationTaskStatusPendingAnnotation,
CreatedAt: nowISO(),
}
if strings.TrimSpace(payload.AssignedUserID) != "" {
renderValidationError(writer, validationIssue{Field: "assignedUserId", Message: "new tasks enter the available pool and cannot be pre-assigned"})
return
}
if err := server.store.UpsertAnnotationTask(request.Context(), item); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
principal, _ := currentPrincipal(request)
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), item.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{
ID: domain.NewID("annotation-worklog"), OrganizationID: item.OrganizationID, ProjectID: item.ProjectID,
TaskID: item.ID, UserID: annotationPrincipalUserID(principal), SupplierID: item.SupplierID,
EventType: "created", Mode: taskMode, Temporary: isTemp, TemplateVersion: item.TemplateVersion, OutputDelta: 0, CreatedAt: nowISO(),
})
renderJSON(writer, http.StatusCreated, item)
}
type annotationRevisionInput struct {
Segments []domain.AnnotationSegment `json:"segments"`
ObjectHints []string `json:"objectHints,omitempty"`
ChangeReason string `json:"changeReason,omitempty"`
DurationSeconds int64 `json:"durationSeconds,omitempty"`
}
type sliceRevisionInput struct {
Segments []domain.SliceSegment `json:"segments"`
Operations []domain.SliceOperation `json:"operations,omitempty"`
ChangeReason string `json:"changeReason,omitempty"`
DurationSeconds int64 `json:"durationSeconds,omitempty"`
}
// combinedAnnotationSubmissionInput is the v5 atomic annotator submission.
// Slice correction and semantic labels are persisted together only after both
// validate, so a quality reviewer never receives one without the other.
type combinedAnnotationSubmissionInput struct {
ConsolidateInvalidSliceIDs []string `json:"consolidateInvalidSliceIds,omitempty"`
// Set only by the internal cut job; never accepted from JSON.
sliceOnly bool
Version int `json:"version"`
SliceSegments []domain.SliceSegment `json:"sliceSegments"`
SliceOperations []domain.SliceOperation `json:"sliceOperations,omitempty"`
Segments []domain.AnnotationSegment `json:"segments"`
ObjectHints []string `json:"objectHints,omitempty"`
ChangeReason string `json:"changeReason,omitempty"`
DurationSeconds int64 `json:"durationSeconds,omitempty"`
RequireSliceCompletion bool `json:"requireSliceCompletion,omitempty"`
}
type combinedAnnotationDraftInput struct {
Version int `json:"version"`
SliceSegments []domain.SliceSegment `json:"sliceSegments"`
Operations []domain.SliceOperation `json:"operations,omitempty"`
SliceOperations []domain.SliceOperation `json:"sliceOperations,omitempty"`
Segments []domain.AnnotationSegment `json:"segments"`
Statuses map[string]domain.SliceAnnotationStatus `json:"statuses,omitempty"`
}
type sliceConfirmationInput struct {
ReconfirmSaved bool `json:"reconfirmSaved,omitempty"`
SnapshotContentSHA string `json:"snapshotContentSha256,omitempty"`
RecoverExisting bool `json:"recoverExisting,omitempty"`
RetryFailed bool `json:"retryFailed,omitempty"`
RetryWorkspace map[string]any `json:"retryWorkspace,omitempty"`
Version int `json:"version"`
SliceSegments []domain.SliceSegment `json:"sliceSegments"`
SliceOperations []domain.SliceOperation `json:"sliceOperations,omitempty"`
ChangeReason string `json:"changeReason,omitempty"`
}
type sliceResetInput struct {
Version int `json:"version"`
ResetToUnifiedRange bool `json:"resetToUnifiedRange"`
}
func (payload combinedAnnotationDraftInput) normalizedOperations() []domain.SliceOperation {
if payload.Operations != nil {
return domain.CompactSliceOperations(payload.Operations)
}
if payload.SliceOperations != nil {
return domain.CompactSliceOperations(payload.SliceOperations)
}
return []domain.SliceOperation{}
}
func (payload combinedAnnotationDraftInput) normalizedSegments() []domain.AnnotationSegment {
if payload.Segments == nil {
return []domain.AnnotationSegment{}
}
return payload.Segments
}
func (payload combinedAnnotationDraftInput) normalizedStatuses() map[string]domain.SliceAnnotationStatus {
statuses := make(map[string]domain.SliceAnnotationStatus, len(payload.SliceSegments)+len(payload.Statuses))
for _, slice := range payload.SliceSegments {
if slice.AnnotationStatus != "" {
statuses[strings.TrimSpace(slice.ID)] = slice.AnnotationStatus
}
}
for id, status := range payload.Statuses {
statuses[strings.TrimSpace(id)] = status
}
return statuses
}
func (payload combinedAnnotationDraftInput) normalizedSliceSegments() []domain.SliceSegment {
slices := append([]domain.SliceSegment(nil), payload.SliceSegments...)
statuses := payload.normalizedStatuses()
for index := range slices {
if status, exists := statuses[strings.TrimSpace(slices[index].ID)]; exists {
slices[index].AnnotationStatus = status
}
}
return slices
}
func clearCombinedAnnotationDraft(item *domain.HumanItemRecord) {
if item == nil || item.Subject.Payload == nil {
return
}
delete(item.Subject.Payload, "annotationDraft")
delete(item.Subject.Payload, "annotationWorkspace")
}
// annotationWorkspacePayload keeps the confirmed in-progress annotation state
// between explicit user confirmations. Autosaved annotationDraft is separate;
// only historical records without a confirmed workspace use it as a fallback.
func annotationWorkspacePayload(item *domain.HumanItemRecord) map[string]any {
if item == nil || item.Subject.Payload == nil {
return map[string]any{}
}
if workspace := mapValue(item.Subject.Payload["annotationWorkspace"]); len(workspace) > 0 {
return workspace
}
return mapValue(item.Subject.Payload["annotationDraft"])
}
func pendingSliceStatuses(slices []domain.SliceSegment) map[string]domain.SliceAnnotationStatus {
statuses := make(map[string]domain.SliceAnnotationStatus, len(slices))
for _, slice := range slices {
statuses[slice.ID] = domain.SliceAnnotationPending
}
return statuses
}
func descriptionOnlySlices(slices []domain.SliceSegment) []domain.SliceSegment {
result := append([]domain.SliceSegment(nil), slices...)
for index := range result {
result[index].TaskLabelID = ""
result[index].TaskLabel = ""
result[index].AnnotationStatus = domain.SliceAnnotationPending
if result[index].IsDiscarded() {
result[index].Name = ""
}
}
return result
}
func fanyuV5CombinedSubmissionID(itemID string, version int) string {
return "fanyu-v5-combined-" + itemID + "-v" + strconv.Itoa(version)
}
func fanyuV5CombinedPayloadSHA(payload combinedAnnotationSubmissionInput) (string, error) {
// Version is a CAS transport field, not semantic submission content. A
// reload after reservation observes n+1 and must still resume the same
// pending payload rather than create a second revision pair.
payload.Version = 0
canonical, err := json.Marshal(payload)
if err != nil {
return "", err
}
digest := sha256.Sum256(canonical)
return hex.EncodeToString(digest[:]), nil
}
func fanyuV5CombinedSubmissionIsRework(revisions []domain.AnnotationRevisionRecord, status domain.AnnotationTaskStatus) bool {
if status == domain.AnnotationTaskStatusRework {
return true
}
for _, revision := range revisions {
// Revision zero is the system-owned Qwen suggestion. It is context for
// the first human submission, not a prior human output or rework round.
if revision.Revision > 0 && strings.TrimSpace(revision.AuthorUserID) != "system" {
return true
}
}
return false
}
func validateFanyuV5CombinedSemanticSegments(segments []domain.AnnotationSegment, slices []domain.SliceSegment, template *domain.AnnotationTemplateRecord) []validationIssue {
return validateFanyuV5CombinedSemanticSegmentsWithRequireDesc(segments, slices, template, true)
}
func validateDraftFanyuV5CombinedSemanticSegments(segments []domain.AnnotationSegment, slices []domain.SliceSegment, template *domain.AnnotationTemplateRecord) []validationIssue {
return validateFanyuV5CombinedSemanticSegmentsWithRequireDesc(segments, slices, template, false)
}
func validateFanyuV5CombinedSemanticSegmentsWithRequireDesc(segments []domain.AnnotationSegment, slices []domain.SliceSegment, template *domain.AnnotationTemplateRecord, requireDescription bool) []validationIssue {
issues := make([]validationIssue, 0)
if template == nil {
return append(issues, validationIssue{Field: "template", Message: "a published description dictionary is required"})
}
descriptionOnly := template.Version >= 6
if !descriptionOnly && len(template.Labels) != 22 {
return append(issues, validationIssue{Field: "template", Message: "v5 requires the published 22-class template"})
}
labels := map[string]string{}
for _, label := range template.Labels {
labels[label.ID] = label.Name
}
for index, slice := range slices {
labelID := strings.TrimSpace(slice.TaskLabelID)
label := strings.TrimSpace(slice.TaskLabel)
if descriptionOnly && (labelID != "" || label != "") {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.taskLabel", index), Message: "description-only slices must not carry task labels"})
} else if !descriptionOnly && slice.AnnotationStatus == domain.SliceAnnotationLabeled && (labels[labelID] == "" || labels[labelID] != label) {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.taskLabel", index), Message: "taskLabelId/taskLabel must exactly match the published v5 22-class template"})
}
if slice.AnnotationStatus == domain.SliceAnnotationEmptyConfirmed && (labelID != "" || label != "") {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.taskLabel", index), Message: "an empty-confirmed slice must not keep a task label"})
}
}
for index, segment := range segments {
if requireDescription && descriptionOnly && strings.TrimSpace(segment.Description) == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.description", index), Message: "every JSON annotation must contain a description"})
}
if descriptionOnly && strings.TrimSpace(segment.LabelID) != "" && labels[strings.TrimSpace(segment.LabelID)] == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.descriptionTemplateId", index), Message: "description template must come from the published dictionary"})
}
contained := 0
for _, slice := range slices {
if segment.Start >= slice.Start && segment.End <= slice.End {
if slice.IsDiscarded() {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "舍弃片段不能包含当前有效标注"})
}
contained++
}
}
if contained != 1 {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "semantic segment must be fully contained in exactly one submitted final slice"})
}
}
return issues
}
func annotationTemplateWithTaskSnapshot(template *domain.AnnotationTemplateRecord, task *domain.AnnotationTaskRecord) *domain.AnnotationTemplateRecord {
if template == nil || task == nil || len(task.LabelSnapshot) == 0 {
return template
}
copy := *template
copy.Labels = append([]domain.SemanticLabelDefinition(nil), task.LabelSnapshot...)
return &copy
}
func validateRequiredSliceCompletion(slices []domain.SliceSegment, segments []domain.AnnotationSegment, descriptionOnly bool) []validationIssue {
issues := make([]validationIssue, 0)
for index, slice := range slices {
contained := 0
for _, segment := range segments {
if segment.Start >= slice.Start && segment.End <= slice.End {
contained++
}
}
if slice.IsDiscarded() {
if contained != 0 {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d", index), Message: "舍弃片段不能包含当前有效标注"})
}
continue
}
switch slice.AnnotationStatus {
case domain.SliceAnnotationLabeled:
if descriptionOnly && contained == 0 {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.annotationStatus", index), Code: "slice_description_required", Message: "labeled slice must contain at least one JSON description"})
} else if !descriptionOnly && (strings.TrimSpace(slice.TaskLabelID) == "" || strings.TrimSpace(slice.TaskLabel) == "") {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.taskLabel", index), Code: "slice_task_label_required", Message: "labeled slice must select a task label"})
}
case domain.SliceAnnotationEmptyConfirmed:
if contained != 0 {
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.annotationStatus", index), Code: "empty_slice_has_annotations", Message: "empty_confirmed slice must not contain semantic segments"})
}
case "", domain.SliceAnnotationPending:
issues = append(issues, validationIssue{Field: fmt.Sprintf("sliceSegments.%d.annotationStatus", index), Code: "slice_annotation_pending", Message: "every slice must be labeled or explicitly confirmed empty"})
}
}
return issues
}
// Explicit task submission confirms intentionally blank slices without turning
// them into invalid annotations or discarded delivery intervals. Drafts stay
// pending until submission; legacy task-label workflows retain their rules.
func confirmOptionalDescriptions(slices []domain.SliceSegment, segments []domain.AnnotationSegment) []domain.SliceSegment {
confirmed := append([]domain.SliceSegment(nil), slices...)
for i := range confirmed {
if confirmed[i].IsDiscarded() {
continue
}
confirmed[i].AnnotationStatus = domain.SliceAnnotationEmptyConfirmed
for _, segment := range segments {
if segment.Start >= confirmed[i].Start && segment.End <= confirmed[i].End {
confirmed[i].AnnotationStatus = domain.SliceAnnotationLabeled
break
}
}
}
return confirmed
}
func validateDraftStatuses(statuses map[string]domain.SliceAnnotationStatus, slices []domain.SliceSegment) []validationIssue {
if len(statuses) == 0 {
return nil
}
known := make(map[string]struct{}, len(slices))
for _, slice := range slices {
known[strings.TrimSpace(slice.ID)] = struct{}{}
}
issues := make([]validationIssue, 0)
for id, status := range statuses {
if _, exists := known[strings.TrimSpace(id)]; !exists {
issues = append(issues, validationIssue{Field: "statuses." + id, Message: "draft status must reference a submitted slice id"})
}
if status != domain.SliceAnnotationPending && status != domain.SliceAnnotationLabeled && status != domain.SliceAnnotationEmptyConfirmed {
issues = append(issues, validationIssue{Field: "statuses." + id, Message: "annotation status must be pending, labeled, or empty_confirmed"})
}
}
return issues
}
// reserveFanyuV5CombinedSubmission wins a CAS before either revision write.
// A retry with the same payload token can resume; a different same-version
// submission cannot overwrite partial or completed revision records.
func (server *server) reserveFanyuV5CombinedSubmission(ctx context.Context, item domain.HumanItemRecord, expectedVersion int, submissionID string, payloadSHA string, jobs ...*domain.AnnotationProcessingJob) (*domain.HumanItemRecord, bool, error) {
if item.PendingCombinedSubmissionID != "" {
// Older clients could keep confirming descriptions after a submission
// reserved its version. That writer can no longer finish its CAS. Only
// an explicit resubmission using the current version may supersede it;
// never reuse its immutable revision/artifact IDs for the new payload.
prefix := "fanyu-v5-combined-" + item.ID + "-v"
reservedVersion, parseErr := strconv.Atoi(strings.TrimPrefix(item.PendingCombinedSubmissionID, prefix))
invalidated := strings.HasPrefix(item.PendingCombinedSubmissionID, prefix) && parseErr == nil &&
(item.Version > reservedVersion+1 || (item.PendingCombinedPayloadSHA == "" && expectedVersion == item.Version))
if invalidated {
if expectedVersion != item.Version || submissionID != fanyuV5CombinedSubmissionID(item.ID, expectedVersion) {
return nil, false, fmt.Errorf("combined submission version conflict")
}
item.PendingCombinedSubmissionID = ""
item.PendingCombinedPayloadSHA = ""
} else {
if item.PendingCombinedPayloadSHA == payloadSHA {
if len(jobs) > 0 && jobs[0] != nil && (item.ProcessingJob == nil || item.ProcessingJob.ID != item.PendingCombinedSubmissionID) {
adopted := item
job := *jobs[0]
job.ID = item.PendingCombinedSubmissionID
adopted.ProcessingJob = &job
ok, e := server.store.UpdateHumanItemVersioned(ctx, adopted, item.Version)
if e != nil {
return nil, false, e
}
if !ok {
return nil, false, fmt.Errorf("combined submission adoption conflict")
}
return &adopted, true, nil
}
return &item, true, nil
}
return nil, false, fmt.Errorf("a different combined submission is already reserved")
}
}
if item.Version == expectedVersion {
reserved := item
reserved.Version++
reserved.PendingCombinedSubmissionID = submissionID
reserved.PendingCombinedPayloadSHA = payloadSHA
if len(jobs) > 0 && jobs[0] != nil {
reserved.ProcessingJob = jobs[0]
if jobs[0].Kind == "submit" {
reserved.Subject.Payload = mapValue(item.Subject.Payload)
if reserved.Subject.Payload == nil {
reserved.Subject.Payload = map[string]any{}
}
in := jobs[0].Input
reserved.Subject.Payload["annotationWorkspace"] = map[string]any{"sliceSegments": in["sliceSegments"], "operations": in["sliceOperations"], "segments": in["segments"], "userId": jobs[0].ActorID, "savedAt": nowISO()}
}
}
updated, err := server.store.UpdateHumanItemVersioned(ctx, reserved, item.Version)
if err != nil {
return nil, false, err
}
if updated {
return &reserved, false, nil
}
}
current, err := server.store.GetHumanItem(ctx, item.ID)
if err != nil || current == nil {
return nil, false, err
}
if current.PendingCombinedSubmissionID == submissionID && current.PendingCombinedPayloadSHA == payloadSHA {
return current, true, nil
}
return nil, false, fmt.Errorf("combined submission version conflict")
}
func rejectPendingCombinedSubmission(writer http.ResponseWriter, item *domain.HumanItemRecord) bool {
if item == nil || item.PendingCombinedSubmissionID == "" {
return false
}
renderJSON(writer, http.StatusConflict, map[string]string{
"error": "任务正在提交质检,暂不能修改、重新切片或释放任务。",
"code": "combined_submission_in_progress",
})
return true
}
func (server *server) handleCombinedAnnotationDraftPut(writer http.ResponseWriter, request *http.Request) {
probe := newAnnotationWriteTiming("draft", chi.URLParam(request, "id"))
defer probe.finish()
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
humanItem, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, domain.FanyuV58StageAnnotationCombined)
if !claimed {
return
}
if rejectPendingCombinedSubmission(writer, humanItem) {
return
}
if stringValue(mapValue(humanItem.Subject.Payload["sliceWorkflow"])["status"]) == "processing" ||
(humanItem.ProcessingJob != nil && humanItem.ProcessingJob.Kind == "slice" && (humanItem.ProcessingJob.Status == "queued" || humanItem.ProcessingJob.Status == "running")) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "切片正在后台处理,已保存内容仍保留,请完成后再编辑", "code": "slice_processing"})
return
}
probe.loaded()
var payload combinedAnnotationDraftInput
if !decodeJSON(writer, request, &payload) {
return
}
issues := validateSliceSegments(payload.SliceSegments, *task)
canonical, dispositionIssues := server.canonicalSliceDispositions(request.Context(), humanItem, payload.SliceSegments, payload.normalizedOperations())
if len(dispositionIssues) > 0 {
renderValidationError(writer, dispositionIssues...)
return
}
payload.SliceSegments = canonical
payload.Operations = domain.CheckpointSliceOperations(decodeMaterializationValue[domain.SliceSegment](annotationWorkspacePayload(humanItem)["sliceSegments"]), canonical, payload.normalizedOperations())
payload.SliceOperations = nil
if server.continuousActionsForItem(request.Context(), humanItem) {
payload.Segments = fillPendingActionGaps(payload.SliceSegments, payload.Segments)
payload.Statuses = continuousSliceStatuses(payload.SliceSegments, payload.Segments)
issues = append(issues, validateContinuousActions(payload.SliceSegments, payload.Segments, false)...)
issues = append(issues, server.continuousActionFrameIssues(request.Context(), *task, humanItem, payload.Segments)...)
}
issues = append(issues, validateDraftCombinedAnnotationEvents(payload.Segments, *task)...)
issues = append(issues, validateDraftStatuses(payload.Statuses, payload.SliceSegments)...)
template, templateErr := server.store.GetAnnotationTemplate(request.Context(), task.TemplateID)
if templateErr != nil {
renderError(writer, http.StatusInternalServerError, templateErr)
return
}
template = annotationTemplateWithTaskSnapshot(template, task)
issues = append(issues, server.canonicalActionDictionaries(request.Context(), humanItem, payload.Segments)...)
issues = append(issues, validateDraftFanyuV5CombinedSemanticSegments(payload.Segments, payload.SliceSegments, template)...)
if len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if payload.Version != humanItem.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
probe.validated()
now := nowISO()
draft := map[string]any{
"sliceSegments": payload.normalizedSliceSegments(),
"operations": payload.normalizedOperations(),
"segments": payload.normalizedSegments(),
"statuses": payload.normalizedStatuses(),
"userId": principal.User.ID,
"savedAt": now,
"savedVersion": humanItem.Version + 1,
}
if humanItem.Subject.Payload == nil {
humanItem.Subject.Payload = map[string]any{}
}
humanItem.Subject.Payload["annotationDraft"] = draft
expectedVersion := humanItem.Version
humanItem.Version++
humanItem.UpdatedAt = now
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *humanItem, expectedVersion)
probe.written()
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
}
renderJSON(writer, http.StatusOK, map[string]any{"item": humanItem, "draft": draft})
}
// handleAnnotationConfirmationCreate persists only an explicit per-description
// confirmation from the Capture workbench. It deliberately does not expose a
// draft concept or autosave endpoint to the product UI.
func (server *server) handleAnnotationConfirmationCreate(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
item, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, domain.FanyuV58StageAnnotationCombined)
if !claimed {
return
}
sliceWorkflow := mapValue(item.Subject.Payload["sliceWorkflow"])
if rejectPendingCombinedSubmission(writer, item) {
return
}
ready, readinessErr := server.legacyAnnotationConfirmationReady(request.Context(), *task, item)
if readinessErr != nil {
renderError(writer, http.StatusInternalServerError, readinessErr)
return
}
if !ready {
renderJSON(writer, http.StatusConflict, map[string]string{
"error": "all Capture slices must be materialized before descriptions can be confirmed",
"code": "slice_materialization_required",
})
return
}
var payload combinedAnnotationDraftInput
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
}
slices := descriptionOnlySlices(payload.normalizedSliceSegments())
canonical, dispositionIssues := server.canonicalSliceDispositions(request.Context(), item, slices, payload.normalizedOperations())
if len(dispositionIssues) > 0 {
renderValidationError(writer, dispositionIssues...)
return
}
slices = canonical
if stringValue(sliceWorkflow["boundaryContract"]) == "hardware-frame-v1" {
timeline, e := server.annotationFrameTimelineForTask(request.Context(), *task, "left")
if e != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": e.Error()})
return
}
grid := annotationBoundaryGrid{Seconds: timeline["boundariesSeconds"].([]float64), Timestamps: timeline["boundaryTimestampUs"].([]int64)}
for i := range slices {
a, e := grid.resolve(slices[i].Start)
if e != nil {
renderValidationError(writer, validationIssue{Field: "sliceSegments", Message: e.Error()})
return
}
b, e := grid.resolve(slices[i].End)
if e != nil || b <= a {
renderValidationError(writer, validationIssue{Field: "sliceSegments", Message: "切片边界必须包含有效帧"})
return
}
slices[i].Start, slices[i].End = grid.Seconds[a], grid.Seconds[b]
slices[i].StartTimestampUS, slices[i].EndTimestampUS = grid.Timestamps[a], grid.Timestamps[b]
}
for i := range payload.Segments {
a, e := grid.resolve(payload.Segments[i].Start)
if e != nil {
renderValidationError(writer, validationIssue{Field: "segments", Message: e.Error()})
return
}
b, e := grid.resolve(payload.Segments[i].End)
if e != nil || b <= a {
renderValidationError(writer, validationIssue{Field: "segments", Message: "动作边界必须包含有效帧"})
return
}
payload.Segments[i].Start, payload.Segments[i].End = grid.Seconds[a], grid.Seconds[b]
payload.Segments[i].StartTimestampUS, payload.Segments[i].EndTimestampUS = grid.Timestamps[a], grid.Timestamps[b]
}
}
issues := validateSliceSegments(slices, *task)
if server.continuousActionsForItem(request.Context(), item) {
payload.Segments = fillPendingActionGaps(slices, payload.Segments)
payload.Statuses = continuousSliceStatuses(slices, payload.Segments)
issues = append(issues, validateContinuousActions(slices, payload.Segments, false)...)
}
issues = append(issues, validateCompleteSliceCoverage(slices, *task)...)
issues = append(issues, validateDraftCombinedAnnotationEvents(payload.Segments, *task)...)
template, templateErr := server.store.GetAnnotationTemplate(request.Context(), task.TemplateID)
if templateErr != nil {
renderError(writer, http.StatusInternalServerError, templateErr)
return
}
template = annotationTemplateWithTaskSnapshot(template, task)
issues = append(issues, server.canonicalActionDictionaries(request.Context(), item, payload.Segments)...)
issues = append(issues, validateDraftFanyuV5CombinedSemanticSegments(payload.Segments, slices, template)...)
if len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if item.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
now := nowISO()
workspace := map[string]any{
"sliceSegments": slices,
"operations": payload.normalizedOperations(),
"segments": payload.normalizedSegments(),
"statuses": payload.normalizedStatuses(),
"userId": principal.User.ID,
"confirmedAt": now,
}
delete(item.Subject.Payload, "annotationDraft")
item.Subject.Payload["annotationWorkspace"] = workspace
expectedVersion := item.Version
item.Version++
item.UpdatedAt = now
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, expectedVersion)
if updateErr != nil {
renderError(writer, http.StatusInternalServerError, updateErr)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
_ = server.appendHumanEvent(request.Context(), *item, "annotation_description_confirmed", principal.User.ID, map[string]any{"descriptionCount": len(payload.Segments)})
renderJSON(writer, http.StatusOK, map[string]any{"item": item, "workspace": workspace})
}
func (server *server) finishSliceConfirmation(ctx context.Context, taskID string, itemID string, requestID string, payload sliceConfirmationInput, revision int, actorUserID string) {
ctx, cancel := context.WithTimeout(ctx, 24*time.Hour)
defer cancel()
task, taskErr := server.getAnnotationTaskForAccess(ctx, taskID)
item, itemErr := server.store.GetHumanItem(ctx, itemID)
if taskErr != nil || itemErr != nil || task == nil || item == nil {
return
}
w := mapValue(item.Subject.Payload["sliceWorkflow"])
if stringValue(w["requestId"]) != requestID || stringValue(w["status"]) != "processing" {
return
}
done := make(chan struct{})
heartbeatStopped := make(chan struct{})
if _, durable := ctx.Value(annotationJobLeaseKey{}).(annotationJobLease); durable {
close(heartbeatStopped)
} else {
go func() { defer close(heartbeatStopped); server.keepSliceLease(ctx, cancel, itemID, requestID, done) }()
}
slices := descriptionOnlySlices(payload.SliceSegments)
sliceRevision := domain.SliceRevisionRecord{
ID: "slice-confirmation-" + requestID, OrganizationID: task.OrganizationID, TaskID: task.ID,
Revision: revision, Segments: slices, Operations: payload.SliceOperations, AuthorUserID: actorUserID,
ChangeReason: strings.TrimSpace(payload.ChangeReason), CreatedAt: nowISO(),
}
processErr := validateSliceCompletionSnapshot(item, payload)
var materialization *humanSliceMaterialization
if processErr == nil {
materialization, processErr = server.materializeCombinedSliceSubmission(ctx, *task, *item, combinedAnnotationSubmissionInput{sliceOnly: true, SliceSegments: slices, Segments: []domain.AnnotationSegment{}}, revision)
}
close(done)
<-heartbeatStopped
if _, durable := ctx.Value(annotationJobLeaseKey{}).(annotationJobLease); durable && (ctx.Err() != nil || server.assertAnnotationLease(ctx) != nil) {
return
}
// Persist failure even when ffmpeg was cancelled by the deadline/lease.
ctx, cleanup := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
defer cleanup()
current, currentErr := server.store.GetHumanItem(ctx, itemID)
if currentErr != nil || current == nil {
return
}
if lease, ok := ctx.Value(annotationJobLeaseKey{}).(annotationJobLease); ok && (current.ProcessingJob == nil || current.ProcessingJob.Owner != lease.Owner) {
return
}
workflow := mapValue(current.Subject.Payload["sliceWorkflow"])
if strings.TrimSpace(fmt.Sprint(workflow["requestId"])) != requestID || stringValue(workflow["status"]) != "processing" {
return
}
if processErr == nil {
processErr = validateSliceCompletionSnapshot(current, payload)
}
if processErr == nil {
processErr = server.store.UpsertSliceRevision(ctx, sliceRevision)
}
now := nowISO()
if processErr != nil {
log.Printf("[api] finishSliceConfirmation failed for task=%s item=%s requestID=%s: %v", taskID, itemID, requestID, processErr)
workflow["status"] = "failed"
workflow["error"] = processErr.Error()
workflow["updatedAt"] = now
} else {
log.Printf("[api] finishSliceConfirmation succeeded for task=%s item=%s requestID=%s revision=%d slices=%d", taskID, itemID, requestID, revision, len(materialization.Slices))
materialization.Payload["confirmationSnapshotSha256"] = payload.SnapshotContentSHA
workflow = map[string]any{
"status": "completed", "phase": "annotate", "requestId": requestID, "revision": revision,
"boundaryContract": "hardware-frame-v1",
"sliceCount": len(materialization.Slices), "materialization": materialization.Payload, "updatedAt": now,
}
workflow["snapshotContentSha256"] = payload.SnapshotContentSHA
if payload.RetryFailed {
workflow["retryOf"] = w["retryOf"]
}
workspace := map[string]any{
"sliceSegments": materialization.Slices, "operations": payload.SliceOperations,
"segments": []domain.AnnotationSegment{}, "statuses": pendingSliceStatuses(materialization.Slices),
"userId": actorUserID, "savedAt": now,
"confirmationSnapshotSha256": payload.SnapshotContentSHA,
}
if payload.RetryFailed {
// Retry only regenerated physical media; retained semantic work and
// disposition evidence belong to the saved snapshot, not the cut job.
retained := payload.RetryWorkspace
workspace["segments"] = retained["segments"]
workspace["statuses"] = retained["statuses"]
}
delete(current.Subject.Payload, "annotationDraft")
current.Subject.Payload["annotationWorkspace"] = workspace
current.Subject.Payload["materialization"] = materialization.Payload
task.CoverageStartSecond = materialization.CoverageStartSecond
task.CoverageEndSecond = materialization.CoverageEndSecond
task.CoverageMode = "full_common_range"
_ = server.store.UpsertAnnotationTask(ctx, *task)
_ = server.appendHumanEvent(ctx, *current, "slice_materialized_for_annotation", actorUserID, materialization.Payload)
}
current.Subject.Payload["sliceWorkflow"] = workflow
expectedVersion := current.Version
current.Version++
current.UpdatedAt = now
published, publishErr := server.store.UpdateHumanItemVersioned(ctx, *current, expectedVersion)
if published && publishErr == nil && processErr == nil {
server.cleanupReplacedAnnotationData(ctx, *task, itemID, revision)
}
}
func (server *server) handleSliceConfirmationCreate(writer http.ResponseWriter, request *http.Request) {
probe := newAnnotationWriteTiming("slice-confirmation", chi.URLParam(request, "id"))
defer probe.finish()
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
item, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, domain.FanyuV58StageAnnotationCombined)
if !claimed {
return
}
probe.loaded()
var payload sliceConfirmationInput
if rejectPendingCombinedSubmission(writer, item) {
return
}
if !decodeJSON(writer, request, &payload) {
return
}
payload.RetryWorkspace = nil // Private durable snapshot is always server-owned.
payload.SnapshotContentSHA = ""
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
if payload.ReconfirmSaved && (payload.RetryFailed || payload.RecoverExisting) {
renderJSON(writer, http.StatusBadRequest, map[string]string{"error": "请选择一种切片生成操作", "code": "slice_confirmation_mode_invalid"})
return
}
var retained combinedAnnotationDraftInput
if payload.ReconfirmSaved {
workflow := mapValue(item.Subject.Payload["sliceWorkflow"])
job := item.ProcessingJob
if stringValue(workflow["status"]) != "failed" || (job != nil && (job.Status == "queued" || job.Status == "running" || job.Kind != "slice")) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "只有生成失败且未在后台处理的任务可以重新确认", "code": "slice_retry_unavailable"})
return
}
var recoveryErr error
payload, retained, recoveryErr = retainedSliceRecoveryInput(item, payload.Version)
if recoveryErr != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": recoveryErr.Error(), "code": "slice_retry_workspace_invalid"})
return
}
payload.ReconfirmSaved = true
payload.ChangeReason = "按当前已保存内容重新确认切片生成"
} else if payload.RecoverExisting {
ready, err := server.legacyAnnotationConfirmationReady(request.Context(), *task, item)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if ready || !legacyGenerationRecoveryCandidate(*task, item) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "当前任务不需要恢复历史切片生成,已有内容仍保留", "code": "slice_recovery_unavailable"})
return
}
var recoveryErr error
payload, retained, recoveryErr = retainedSliceRecoveryInput(item, payload.Version)
if recoveryErr != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": recoveryErr.Error(), "code": "slice_retry_workspace_invalid"})
return
}
payload.RecoverExisting = true
payload.ChangeReason = "恢复历史切片生成并保留已有标注"
} else if payload.RetryFailed {
workflow := mapValue(item.Subject.Payload["sliceWorkflow"])
job := item.ProcessingJob
if stringValue(workflow["status"]) != "failed" || (job != nil && (job.Status == "queued" || job.Status == "running" || job.Kind != "slice")) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "只有失败且未在后台处理的切片任务可以重试", "code": "slice_retry_unavailable"})
return
}
var retryErr error
recoverExisting := boolValue(workflow["recoverExisting"])
payload, retained, retryErr = retainedSliceRetryInput(item, payload.Version)
payload.RecoverExisting = recoverExisting
if retryErr != nil {
if errors.Is(retryErr, errSliceSnapshotConflict) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": retryErr.Error(), "code": "slice_retry_snapshot_conflict"})
return
}
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": retryErr.Error(), "code": "slice_retry_workspace_invalid"})
return
}
}
if !payload.RetryFailed && stringValue(mapValue(item.Subject.Payload["sliceWorkflow"])["status"]) == "failed" {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "请按已保存内容重新确认生成,已有标注仍保留", "code": "slice_retry_snapshot_conflict"})
return
}
payload.SliceSegments = descriptionOnlySlices(payload.SliceSegments)
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
if stringValue(mapValue(item.Subject.Payload["sliceWorkflow"])["status"]) == "processing" {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "切片仍在处理中,请等待完成或返回调整切片", "code": "slice_processing"})
return
}
canonical, dispositionIssues := server.canonicalSliceDispositions(request.Context(), item, payload.SliceSegments, payload.SliceOperations)
if len(dispositionIssues) > 0 {
renderValidationError(writer, dispositionIssues...)
return
}
payload.SliceSegments = canonical
payload.SliceOperations = domain.CheckpointSliceOperations(decodeMaterializationValue[domain.SliceSegment](annotationWorkspacePayload(item)["sliceSegments"]), canonical, payload.SliceOperations)
timeline, timelineErr := server.annotationFrameTimelineForTask(request.Context(), *task, "left")
if timelineErr != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": "无法校验统一帧边界:" + timelineErr.Error(), "code": "frame_boundaries_unavailable"})
return
}
task.CoverageStartSecond = floatValue(timeline["rangeStartSecond"])
task.CoverageEndSecond = floatValue(timeline["rangeEndSecond"])
task.CoverageMode = "full_common_range"
issues := validateSliceSegments(payload.SliceSegments, *task)
issues = append(issues, validateCompleteSliceCoverage(payload.SliceSegments, *task)...)
if payload.RetryFailed {
issues = append(issues, retainedSliceRetryIssues(retained, payload.SliceSegments, *task, timeline)...)
template, templateErr := server.store.GetAnnotationTemplate(request.Context(), task.TemplateID)
if templateErr != nil {
renderError(writer, http.StatusInternalServerError, templateErr)
return
}
issues = append(issues, validateDraftFanyuV5CombinedSemanticSegments(retained.Segments, payload.SliceSegments, annotationTemplateWithTaskSnapshot(template, task))...)
}
if len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if payload.Version != item.Version {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
sliceRevisions, revisionErr := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
if revisionErr != nil {
renderError(writer, http.StatusInternalServerError, revisionErr)
return
}
revision := 1
previous := mapValue(item.Subject.Payload["sliceWorkflow"])
retryOf := sliceRetryFailureEvidence(item)
if issues := server.validateProjectSliceNames(request.Context(), item, payload.SliceSegments, "confirm"); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if stringValue(previous["status"]) == "processing" {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "切片仍在处理中,请等待完成或返回调整切片", "code": "slice_processing"})
return
}
if prior := intValue(previous["revision"]); prior >= revision {
revision = prior + 1
}
for _, existing := range sliceRevisions {
if existing.Revision >= revision {
revision = existing.Revision + 1
}
}
probe.validated()
requestID := domain.NewID("slice-materialization")
contentSHA, hashErr := sliceWorkspaceContentSHA(sliceConfirmationWorkspace(payload))
if hashErr != nil {
renderError(writer, http.StatusUnprocessableEntity, hashErr)
return
}
payload.SnapshotContentSHA = contentSHA
if payload.ReconfirmSaved {
prior, archiveErr := compactSliceWorkspaceForArchive(annotationWorkspacePayload(item))
if archiveErr != nil {
renderError(writer, http.StatusUnprocessableEntity, archiveErr)
return
}
archive := map[string]any{"requestId": requestID, "selectedContentSha256": contentSHA, "previousWorkspace": prior}
if job := item.ProcessingJob; job != nil && job.Input != nil {
if raw := mapValue(job.Input["retryWorkspace"]); len(raw) > 0 {
previousInput, err := compactSliceWorkspaceForArchive(raw)
if err != nil {
renderError(writer, http.StatusUnprocessableEntity, err)
return
}
archive["previousFailedSnapshot"] = previousInput
}
}
encoded, err := json.Marshal(archive)
if err != nil || len(encoded) > 8<<20 {
renderJSON(writer, http.StatusRequestEntityTooLarge, map[string]string{"error": "历史快照过大,无法完整保留,未开始重新生成", "code": "slice_snapshot_archive_too_large"})
return
}
if err := server.appendHumanEvent(request.Context(), *item, "slice_reconfirmation_snapshot_prepared", principal.User.ID, archive); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
}
now := nowISO()
if item.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
item.Subject.Payload["sliceWorkflow"] = map[string]any{
"status": "processing", "phase": "materializing", "requestId": requestID, "revision": revision,
"sliceCount": len(payload.SliceSegments), "startedAt": now,
"snapshotContentSha256": contentSHA,
"leaseExpiresAt": time.Now().Add(sliceLeaseDuration).Format(time.RFC3339Nano),
}
if payload.RetryFailed {
// Keep the original snapshot intact while queued/running; all workbench
// mutations remain blocked by the existing processing guard.
workflow := mapValue(item.Subject.Payload["sliceWorkflow"])
workflow["retryOf"] = retryOf
if payload.RecoverExisting {
workflow["recoverExisting"] = true
}
item.Subject.Payload["sliceWorkflow"] = workflow
} else {
delete(item.Subject.Payload, "annotationDraft")
item.Subject.Payload["annotationWorkspace"] = map[string]any{
"sliceSegments": payload.SliceSegments, "operations": payload.SliceOperations,
"segments": []domain.AnnotationSegment{}, "statuses": pendingSliceStatuses(payload.SliceSegments),
"userId": principal.User.ID, "savedAt": now,
}
}
if server.externalAnnotationProcessor {
job, err := server.newAnnotationProcessingJob(request.Context(), *task, principal.User.ID, requestID, "slice", payload, revision)
if err != nil {
renderError(writer, http.StatusUnprocessableEntity, err)
return
}
item.ProcessingJob = job
}
expectedVersion := item.Version
item.Version++
item.UpdatedAt = now
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, expectedVersion)
probe.written()
if updateErr != nil {
renderError(writer, http.StatusInternalServerError, updateErr)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
_ = server.appendHumanEvent(request.Context(), *item, "slice_confirmation_started", principal.User.ID, map[string]any{"requestId": requestID, "revision": revision, "sliceCount": len(payload.SliceSegments), "retryOf": mapValue(item.Subject.Payload["sliceWorkflow"])["retryOf"]})
if !server.externalAnnotationProcessor {
go server.finishSliceConfirmation(context.WithoutCancel(withoutAnnotationReadCache(request.Context())), task.ID, item.ID, requestID, payload, revision, principal.User.ID)
}
renderJSON(writer, http.StatusAccepted, map[string]any{"item": item, "sliceWorkflow": item.Subject.Payload["sliceWorkflow"]})
}
// The reslice write path is scoped to first-pass tasks (spec
// rework-ux-adjust D1, revised 2026-10-14): a task that has never been
// submitted for review may still wipe the workspace for a fresh slicing
// pass, appending sliceResetHistory audit evidence as before. Tasks with
// submission history keep the in-place editing contract (R3-2:a) and are
// refused with 409 slice_reset_disabled without any mutation.
func (server *server) handleSliceResetCreate(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
item, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, domain.FanyuV58StageAnnotationCombined)
if !claimed {
return
}
if rejectPendingCombinedSubmission(writer, item) {
return
}
annotationRevisions, revisionsErr := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
if revisionsErr != nil {
renderError(writer, http.StatusInternalServerError, revisionsErr)
return
}
if task.CurrentRevision > 0 || fanyuV5CombinedSubmissionIsRework(annotationRevisions, task.Status) {
renderJSON(writer, http.StatusConflict, map[string]any{
"code": "slice_reset_disabled",
"error": "重新切片仅适用于从未送检的任务:已送检任务请改用原地切片结构编辑(调整边界、合并或舍弃)完成调整",
})
return
}
var payload sliceResetInput
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.Subject.Payload == nil {
item.Subject.Payload = map[string]any{}
}
draft := annotationWorkspacePayload(item)
slices := descriptionOnlySlices(decodeMaterializationValue[domain.SliceSegment](draft["sliceSegments"]))
if len(slices) == 0 {
revisions, revisionErr := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
if revisionErr != nil {
renderError(writer, http.StatusInternalServerError, revisionErr)
return
}
if len(revisions) > 0 {
slices = descriptionOnlySlices(revisions[len(revisions)-1].Segments)
}
}
now := nowISO()
// Retain the prior workspace as audit evidence, but detach every action
// archive from the new editing epoch so restore cannot revive reset text.
resetHistory, _ := normalizeStructuredValue(item.Subject.Payload["sliceResetHistory"]).([]any)
resetHistory = append(resetHistory, map[string]any{"workspace": draft, "actorUserId": principal.User.ID, "at": now, "itemVersion": item.Version + 1, "resetToUnifiedRange": payload.ResetToUnifiedRange})
for i := range slices {
slices[i].DiscardedAnnotations = nil
}
resetDraft := map[string]any{
"sliceSegments": slices, "operations": []domain.SliceOperation{}, "segments": []domain.AnnotationSegment{},
"statuses": pendingSliceStatuses(slices), "userId": principal.User.ID, "savedAt": now,
}
if payload.ResetToUnifiedRange {
timeline, e := server.annotationFrameTimelineForTask(request.Context(), *task, "left")
if e != nil {
renderJSON(writer, http.StatusUnprocessableEntity, map[string]string{"error": e.Error()})
return
}
slices = []domain.SliceSegment{{ID: domain.NewID("slice"), Start: floatValue(timeline["rangeStartSecond"]), End: floatValue(timeline["rangeEndSecond"])}}
resetDraft["sliceSegments"] = slices
resetDraft["statuses"] = pendingSliceStatuses(slices)
}
delete(item.Subject.Payload, "annotationDraft")
delete(item.Subject.Payload, sliceRestoreEvidenceKey)
delete(item.Subject.Payload, sliceArchiveEditsKey)
delete(item.Subject.Payload, sliceMergeEvidenceKey)
item.Subject.Payload["sliceResetHistory"] = resetHistory
item.Subject.Payload["annotationWorkspace"] = resetDraft
if item.ProcessingJob != nil {
item.ProcessingJob.Status = "cancelled"
item.ProcessingJob.Input = nil
item.ProcessingJob.Owner = ""
}
item.Subject.Payload["sliceWorkflow"] = map[string]any{"status": "editing", "phase": "slice", "resetAt": now, "resetFromVersion": payload.Version, "resetToUnifiedRange": payload.ResetToUnifiedRange, "revision": intValue(mapValue(item.Subject.Payload["sliceWorkflow"])["revision"])}
expectedVersion := item.Version
item.Version++
item.UpdatedAt = now
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, expectedVersion)
if updateErr != nil {
renderError(writer, http.StatusInternalServerError, updateErr)
return
}
if !updated {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
_ = server.appendHumanEvent(request.Context(), *item, "annotation_discarded_for_reslice", principal.User.ID, map[string]any{"discardedAnnotationCount": len(decodeMaterializationValue[domain.AnnotationSegment](draft["segments"]))})
renderJSON(writer, http.StatusOK, map[string]any{"item": item, "workspace": resetDraft})
}
func (server *server) handleCombinedAnnotationSubmission(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !annotationManager(principal) && !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
humanItem, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, "annotation_combined")
if !claimed {
return
}
batch, err := server.store.GetHumanBatch(request.Context(), humanItem.BatchID)
if err != nil || batch == nil || len(batch.Stages) < 2 || batch.Stages[0].ID != "annotation_combined" || batch.Stages[1].ID != "quality_review" {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "combined annotation is only available for the v5 combined task contract"})
return
}
var payload combinedAnnotationSubmissionInput
if !decodeJSON(writer, request, &payload) {
return
}
canonical, dispositionIssues := server.canonicalSliceDispositions(request.Context(), humanItem, payload.SliceSegments, payload.SliceOperations)
if len(dispositionIssues) > 0 {
renderValidationError(writer, dispositionIssues...)
return
}
payload.SliceSegments = canonical
payload.SliceOperations = domain.CheckpointSliceOperations(decodeMaterializationValue[domain.SliceSegment](annotationWorkspacePayload(humanItem)["sliceSegments"]), canonical, payload.SliceOperations)
if issues := validateSliceSegments(payload.SliceSegments, *task); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) {
if issues := validateCompleteSliceCoverage(payload.SliceSegments, *task); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
}
continuousActions := server.continuousActionsForItem(request.Context(), humanItem)
if continuousActions {
payload.Segments = fillPendingActionGaps(payload.SliceSegments, payload.Segments)
for i := range payload.Segments {
if payload.Segments[i].IsInvalid && strings.TrimSpace(payload.Segments[i].Description) == "" {
payload.Segments[i].Description = "无效片段"
}
}
if issues := server.continuousActionFrameIssues(request.Context(), *task, humanItem, payload.Segments); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if issues := validateContinuousActions(payload.SliceSegments, payload.Segments, true); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
}
if issues := validateCombinedAnnotationEventsWithRequireDesc(payload.Segments, *task, !continuousActions); len(issues) > 0 && !allSlicesDiscarded(payload.SliceSegments, payload.Segments) {
renderValidationError(writer, issues...)
return
}
if task.TemplateVersion >= 6 {
payload.SliceSegments = confirmOptionalDescriptions(payload.SliceSegments, payload.Segments)
}
template, templateErr := server.store.GetAnnotationTemplate(request.Context(), task.TemplateID)
if templateErr != nil {
renderError(writer, http.StatusInternalServerError, templateErr)
return
}
template = annotationTemplateWithTaskSnapshot(template, task)
if issues := server.canonicalActionDictionaries(request.Context(), humanItem, payload.Segments); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if issues := validateFanyuV5CombinedSemanticSegmentsWithRequireDesc(payload.Segments, payload.SliceSegments, template, !continuousActions); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if domain.IsFanyuV58ThreeRoleHumanLoop(batch.Stages) {
if issues := validateDescriptionIntervals(payload.SliceSegments, payload.Segments, task.TemplateVersion < 6 && !continuousActions); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
}
if payload.RequireSliceCompletion && !continuousActions {
if issues := validateRequiredSliceCompletion(payload.SliceSegments, payload.Segments, task.TemplateVersion >= 6); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
}
if issues := server.validateProjectSliceNames(request.Context(), humanItem, payload.SliceSegments, "submit"); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
// Original slices, names, disposition and actions have all been validated.
// Only an explicit user selection may change the outer partition. Retain
// action IDs, descriptions, invalid flags and absolute timestamp boundaries.
if len(payload.ConsolidateInvalidSliceIDs) > 0 {
merged, operations, mergeErr := consolidateInvalidActionSlices(payload.SliceSegments, payload.Segments, payload.ConsolidateInvalidSliceIDs)
if mergeErr != nil {
renderValidationError(writer, validationIssue{Field: "consolidateInvalidSliceIds", Message: mergeErr.Error()})
return
}
if issues := validateDescriptionIntervals(merged, payload.Segments, false); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
payload.SliceSegments = merged
payload.SliceOperations = append(payload.SliceOperations, operations...)
}
payloadSHA, hashErr := fanyuV5CombinedPayloadSHA(payload)
if hashErr != nil {
renderError(writer, http.StatusInternalServerError, hashErr)
return
}
submissionRef := fanyuV5CombinedSubmissionID(humanItem.ID, payload.Version)
var processingJob *domain.AnnotationProcessingJob
if server.externalAnnotationProcessor && strings.Contains(strings.ToLower(request.Header.Get("Prefer")), "respond-async") {
processingJob, err = server.newAnnotationProcessingJob(request.Context(), *task, principal.User.ID, submissionRef, "submit", payload, 0)
if err != nil {
renderError(writer, http.StatusUnprocessableEntity, err)
return
}
}
reservedItem, resumed, reserveErr := server.reserveFanyuV5CombinedSubmission(request.Context(), *humanItem, payload.Version, submissionRef, payloadSHA, processingJob)
if reserveErr != nil || reservedItem == nil {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item version conflict", "code": "version_conflict"})
return
}
humanItem = reservedItem
if resumed {
submissionRef = humanItem.PendingCombinedSubmissionID
}
if strings.Contains(strings.ToLower(request.Header.Get("Prefer")), "respond-async") {
if !server.externalAnnotationProcessor {
jobKey := humanItem.OrganizationID + ":" + submissionRef
if _, loaded := server.combinedSubmissionJobs.LoadOrStore(jobKey, struct{}{}); !loaded {
backgroundRequest := request.Clone(context.WithoutCancel(withoutAnnotationReadCache(request.Context())))
go func() {
defer server.combinedSubmissionJobs.Delete(jobKey)
freshTask, te := server.getAnnotationTaskForAccess(backgroundRequest.Context(), task.ID)
freshItem, he := server.store.GetHumanItem(backgroundRequest.Context(), humanItem.ID)
if te != nil || he != nil || freshTask == nil || freshItem == nil || freshItem.PendingCombinedSubmissionID != submissionRef {
return
}
server.completeCombinedAnnotationSubmission(&asynchronousAnnotationResponseWriter{}, backgroundRequest, freshTask, freshItem, payload, principal, submissionRef, resumed)
}()
}
}
renderJSON(writer, http.StatusAccepted, map[string]any{"item": humanItem, "submissionId": submissionRef, "status": "processing", "idempotent": resumed})
return
}
server.completeCombinedAnnotationSubmission(writer, request, task, humanItem, payload, principal, submissionRef, resumed)
}
func (server *server) completeCombinedAnnotationSubmission(writer http.ResponseWriter, request *http.Request, task *domain.AnnotationTaskRecord, humanItem *domain.HumanItemRecord, payload combinedAnnotationSubmissionInput, principal *authenticatedPrincipal, submissionRef string, resumed bool) {
if err := server.assertAnnotationLease(request.Context()); err != nil {
renderError(writer, http.StatusConflict, err)
return
}
sliceRevisions, sliceErr := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
annotationRevisions, annotationErr := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
reviews, reviewErr := server.store.ListAnnotationReviews(request.Context(), task.OrganizationID, task.ID)
if sliceErr != nil || annotationErr != nil || reviewErr != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("load combined annotation revisions: slices=%v annotations=%v reviews=%v", sliceErr, annotationErr, reviewErr))
return
}
sliceID := "slice-" + submissionRef
annotationID := "annotation-" + submissionRef
// Older releases could delete revision documents while retaining reviews.
// Their audit references remain a lower bound even when history is sparse.
revisionNumber := max(1, task.CurrentRevision+1, humanItem.CurrentRevision+1)
for _, review := range reviews {
revisionNumber = max(revisionNumber, review.Revision+1, review.NextRevision)
}
for _, revision := range annotationRevisions {
if revision.Revision >= revisionNumber {
revisionNumber = revision.Revision + 1
}
}
for _, revision := range sliceRevisions {
if revision.Revision >= revisionNumber {
revisionNumber = revision.Revision + 1
}
}
for _, revision := range annotationRevisions {
if revision.ID == annotationID {
revisionNumber = revision.Revision
}
}
for _, revision := range sliceRevisions {
if revision.ID == sliceID {
revisionNumber = revision.Revision
}
}
isRework := task.CurrentRevision > 0 || fanyuV5CombinedSubmissionIsRework(annotationRevisions, task.Status)
now := nowISO()
sliceRevision := domain.SliceRevisionRecord{ID: sliceID, OrganizationID: task.OrganizationID, TaskID: task.ID, Revision: revisionNumber, Segments: payload.SliceSegments, Operations: payload.SliceOperations, AuthorUserID: principal.User.ID, ChangeReason: submissionRef + ":" + strings.TrimSpace(payload.ChangeReason), DurationSeconds: payload.DurationSeconds, CreatedAt: now}
annotationRevision := domain.AnnotationRevisionRecord{ID: annotationID, OrganizationID: task.OrganizationID, TaskID: task.ID, Revision: revisionNumber, TemplateVersion: task.TemplateVersion, Segments: payload.Segments, ObjectHints: payload.ObjectHints, AuthorUserID: principal.User.ID, ChangeReason: submissionRef + ":" + strings.TrimSpace(payload.ChangeReason), IsRework: isRework, CountsAsOutput: !isRework, DurationSeconds: payload.DurationSeconds, CreatedAt: now}
materialization, materializationErr := server.materializeCombinedSliceSubmission(request.Context(), *task, *humanItem, payload, revisionNumber)
if request.Context().Err() != nil {
renderError(writer, http.StatusConflict, request.Context().Err())
return
}
if materializationErr != nil {
previousVersion := humanItem.Version
humanItem.PendingCombinedSubmissionID = ""
humanItem.PendingCombinedPayloadSHA = ""
humanItem.Version++
_, _ = server.store.UpdateHumanItemVersioned(request.Context(), *humanItem, previousVersion)
_ = server.appendHumanEvent(request.Context(), *humanItem, "slice_materialization_failed", principal.User.ID, map[string]any{"revision": revisionNumber, "error": materializationErr.Error()})
renderJSON(writer, http.StatusUnprocessableEntity, map[string]any{"error": "真实切片生成失败:" + materializationErr.Error(), "code": "slice_materialization_failed"})
return
}
if len(materialization.Slices) > 0 {
sliceRevision.Segments = materialization.Slices
}
if materialization.Segments != nil {
annotationRevision.Segments = materialization.Segments
}
if materialization.CoverageEndSecond > materialization.CoverageStartSecond {
task.CoverageStartSecond = materialization.CoverageStartSecond
task.CoverageEndSecond = materialization.CoverageEndSecond
task.CoverageMode = "full_common_range"
}
// 送检结构变更摘要(Q7:b,票 07):服务端从"退回基线 vs 提交工作区"计算,
// 随送检记录落库,首标(无退回基线)不附。以 materialization 之后的权威切片
// 结构为准(ADR 0006 复审以保存后差异为准)。
if humanItem.ReviewRound > 0 {
baseline, baselineErr := server.store.GetReworkBaseline(request.Context(), store.ReworkBaselineID(humanItem.ID, humanItem.ReviewRound))
if baselineErr != nil {
renderError(writer, http.StatusInternalServerError, baselineErr)
return
}
if baseline != nil {
summary := structureChangeSummary(baseline.Slices, sliceRevision.Segments)
sliceRevision.StructureChangeSummary = &summary
}
}
if err := server.store.UpsertSliceRevision(request.Context(), sliceRevision); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if err := server.store.UpsertAnnotationRevision(request.Context(), annotationRevision); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
previousVersion := humanItem.Version
if err := server.assertAnnotationLease(request.Context()); err != nil {
renderError(writer, http.StatusConflict, err)
return
}
humanItem.CurrentRevision = annotationRevision.Revision
humanItem.CurrentStageID = "quality_review"
humanItem.Status = domain.HumanItemReady
humanItem.AssignedUserID = ""
humanItem.ClaimedAt = ""
humanItem.SubmittedAt = now
humanItem.AcceptedAt = ""
humanItem.AcceptedByUserID = ""
humanItem.RejectedAt = ""
if err := server.freezeSubmissionAcceptancePolicy(request.Context(), humanItem); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
humanItem.LatestAuthorUserID = principal.User.ID
if humanItem.Subject.Payload == nil {
humanItem.Subject.Payload = map[string]any{}
}
if len(payload.ConsolidateInvalidSliceIDs) > 0 {
humanItem.Subject.Payload["preserveAnnotationRevisionHistory"] = true
}
humanItem.Subject.Payload["materialization"] = materialization.Payload
if workflow := mapValue(humanItem.Subject.Payload["sliceWorkflow"]); len(workflow) > 0 {
workflow["materialization"] = materialization.Payload
workflow["revision"] = annotationRevision.Revision
humanItem.Subject.Payload["sliceWorkflow"] = workflow
}
clearCombinedAnnotationDraft(humanItem)
humanItem.PendingCombinedSubmissionID = ""
humanItem.PendingCombinedPayloadSHA = ""
humanItem.Version++
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
}
// Publish the legacy task only after the authoritative HumanItem CAS wins.
// A failed CAS must never make the task appear ready for quality review.
task.CurrentRevision = annotationRevision.Revision
task.Status = domain.AnnotationTaskStatusPendingQuality
task.AssignedUserID = ""
task.UpdatedAt = now
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
server.cleanupReplacedAnnotationData(request.Context(), *task, humanItem.ID, annotationRevision.Revision)
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{OrganizationID: humanItem.OrganizationID, ItemID: humanItem.ID, StageID: "annotation_combined", Round: humanItem.ReviewRound, Status: domain.HumanItemSubmitted, AssigneeUserID: principal.User.ID, SubmissionRef: submissionRef})
_ = server.appendHumanEvent(request.Context(), *humanItem, "combined_submitted", principal.User.ID, map[string]any{"submissionRef": submissionRef, "sliceRevision": sliceRevision.Revision, "annotationRevision": annotationRevision.Revision})
_ = server.appendHumanEvent(request.Context(), *humanItem, "slice_materialized", principal.User.ID, materialization.Payload)
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
outputDelta := int64(0)
if annotationRevision.CountsAsOutput {
outputDelta = 1
}
videoSeconds := 0.0
for _, slice := range sliceRevision.Segments {
videoSeconds += math.Max(0, slice.End-slice.Start)
}
submissionKind := "first"
if annotationRevision.IsRework {
submissionKind = "rework"
}
outputDurationSeconds := payload.DurationSeconds
if outputDurationSeconds <= 0 {
outputDurationSeconds = int64(math.Round(videoSeconds))
}
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{ID: submissionRef + ":worklog", SubmissionID: submissionRef, SubmissionKind: submissionKind, VideoSeconds: &videoSeconds, OrganizationID: task.OrganizationID, ProjectID: task.ProjectID, TaskID: task.ID, UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID, EventType: "combined_submitted", Mode: taskMode, Temporary: isTemp, Revision: annotationRevision.Revision, TemplateVersion: task.TemplateVersion, DurationSeconds: outputDurationSeconds, OutputDelta: outputDelta, CreatedAt: now})
status := http.StatusCreated
if resumed {
status = http.StatusOK
}
renderJSON(writer, status, map[string]any{"task": task, "sliceRevision": sliceRevision, "revision": annotationRevision, "humanItem": humanItem, "materialization": materialization.Payload, "idempotent": resumed})
}
type annotationTaskRejectInput struct {
ReasonCodes []string `json:"reasonCodes"`
Comment string `json:"comment"`
}
func (server *server) handleAnnotationTaskReject(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !annotationManager(principal) && !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
if _, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, ""); !claimed {
return
}
var payload annotationTaskRejectInput
if !decodeJSON(writer, request, &payload) {
return
}
if len(payload.ReasonCodes) == 0 || strings.TrimSpace(payload.Comment) == "" {
renderValidationError(writer, validationIssue{Field: "rejection", Message: "reasonCodes and comment are required"})
return
}
item, err := server.humanItemForLegacyTask(request.Context(), *task)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item == nil {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item is required for a workflow-visible rejection", "code": "human_item_required"})
return
}
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
}
previousVersion := item.Version
item.Status = domain.HumanItemRejected
item.RejectedAt = nowISO()
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
}
allowed := allowedHumanReopenStages(batch, item.CurrentStageID)
reject := domain.HumanRejectRecord{OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, ProjectID: item.ProjectID, WorkflowID: item.WorkflowID, RunID: item.RunID, StageID: item.CurrentStageID, AttemptRound: item.ReviewRound, RejectedByUserID: principal.User.ID, ReasonCodes: payload.ReasonCodes, Comment: strings.TrimSpace(payload.Comment), AllowedReopenStages: allowed, Status: domain.HumanRejectOpen}
if err := server.store.UpsertHumanReject(request.Context(), reject); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
task.Status = domain.AnnotationTaskStatusRejected
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
_ = server.appendHumanEvent(request.Context(), *item, "rejected", principal.User.ID, map[string]any{"reasonCodes": payload.ReasonCodes, "comment": strings.TrimSpace(payload.Comment)})
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "item": item})
}
func annotationTaskEditableRange(task domain.AnnotationTaskRecord) (float64, float64) {
if task.CoverageEndSecond > task.CoverageStartSecond {
return task.CoverageStartSecond, task.CoverageEndSecond
}
if task.SourceIsFullVideo && task.SourceDurationSeconds > 0 {
return 0, task.SourceDurationSeconds
}
return task.ClipStart, task.ClipEnd
}
const sliceCoverageToleranceSeconds = 0.001
func validateCompleteSliceCoverage(segments []domain.SliceSegment, task domain.AnnotationTaskRecord) []validationIssue {
if len(segments) == 0 {
return []validationIssue{{Field: "sliceCoverage", Code: "full_coverage_required", Message: "切片必须完整覆盖同步视频区间"}}
}
sorted := append([]domain.SliceSegment(nil), segments...)
sort.Slice(sorted, func(left, right int) bool { return sorted[left].Start < sorted[right].Start })
allowedStart, allowedEnd := annotationTaskEditableRange(task)
issues := make([]validationIssue, 0)
if math.Abs(sorted[0].Start-allowedStart) > sliceCoverageToleranceSeconds {
issues = append(issues, validationIssue{Field: "sliceCoverage.start", Code: "full_coverage_required", Message: fmt.Sprintf("首个切片必须从 %.3fs 开始", allowedStart)})
}
for index := 1; index < len(sorted); index++ {
delta := sorted[index].Start - sorted[index-1].End
if math.Abs(delta) <= 0.000001 {
continue
}
if delta > 0 {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Code: "slice_coverage_gap", Message: fmt.Sprintf("切片之间存在 %.3fs–%.3fs 的未覆盖区间", sorted[index-1].End, sorted[index].Start)})
} else {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Code: "slice_coverage_overlap", Message: fmt.Sprintf("切片在 %.3fs–%.3fs 发生重叠", sorted[index].Start, sorted[index-1].End)})
}
}
if math.Abs(sorted[len(sorted)-1].End-allowedEnd) > sliceCoverageToleranceSeconds {
issues = append(issues, validationIssue{Field: "sliceCoverage.end", Code: "full_coverage_required", Message: fmt.Sprintf("末个切片必须覆盖到 %.3fs", allowedEnd)})
}
return issues
}
func validateSliceSegments(segments []domain.SliceSegment, task domain.AnnotationTaskRecord) []validationIssue {
issues := make([]validationIssue, 0)
if len(segments) == 0 {
return append(issues, validationIssue{Field: "segments", Message: "at least one corrected slice is required"})
}
sorted := append([]domain.SliceSegment(nil), segments...)
sort.Slice(sorted, func(i, j int) bool { return sorted[i].Start < sorted[j].Start })
allowedStart, allowedEnd := annotationTaskEditableRange(task)
seenIDs := make(map[string]struct{}, len(sorted))
for index, segment := range sorted {
id := strings.TrimSpace(segment.ID)
if sliceDisposition(segment) != "keep" && sliceDisposition(segment) != "discard" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.deliveryDisposition", index), Message: "切片用途必须为 keep 或 discard"})
}
if segment.IsDiscarded() && strings.TrimSpace(segment.DiscardReason) == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.discardReason", index), Message: "舍弃片段必须填写原因"})
}
if id == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "slice id is required"})
} else if _, exists := seenIDs[id]; exists {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "slice ids must be unique"})
} else {
seenIDs[id] = struct{}{}
}
if segment.AnnotationStatus != "" && segment.AnnotationStatus != domain.SliceAnnotationPending && segment.AnnotationStatus != domain.SliceAnnotationLabeled && segment.AnnotationStatus != domain.SliceAnnotationEmptyConfirmed {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.annotationStatus", index), Message: "annotation status must be pending, labeled, or empty_confirmed"})
}
if math.IsNaN(segment.Start) || math.IsNaN(segment.End) || segment.Start < allowedStart || segment.End > allowedEnd || segment.End <= segment.Start {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "slice must be finite and inside the Capture common range"})
}
if index > 0 && segment.Start < sorted[index-1].End {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "corrected slices must not overlap"})
}
}
return issues
}
func (server *server) handleSliceRevisionCreate(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !annotationManager(principal) && !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
humanItem, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, "")
if !claimed {
return
}
batch, batchErr := server.store.GetHumanBatch(request.Context(), humanItem.BatchID)
if batchErr != nil {
renderError(writer, http.StatusInternalServerError, batchErr)
return
}
if batch == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
cutAdjustmentStageID := "split_annotation"
cutReviewStageID := "split_quality_review"
if isFanyuV5FourStageBatch(batch) {
cutAdjustmentStageID = domain.FanyuV5StageCutAdjustment
cutReviewStageID = domain.FanyuV5StageCutReview
}
if humanItem.CurrentStageID != cutAdjustmentStageID {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item is not in the cut-adjustment stage", "code": "human_item_stage_conflict"})
return
}
var payload sliceRevisionInput
if !decodeJSON(writer, request, &payload) {
return
}
if issues := validateSliceSegments(payload.Segments, *task); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
existing, err := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
revision := domain.SliceRevisionRecord{
ID: domain.NewID("slice-revision"), OrganizationID: task.OrganizationID, TaskID: task.ID, Revision: len(existing) + 1,
Segments: payload.Segments, Operations: payload.Operations, AuthorUserID: principal.User.ID,
ChangeReason: strings.TrimSpace(payload.ChangeReason), DurationSeconds: payload.DurationSeconds, CreatedAt: nowISO(),
}
if err := server.store.UpsertSliceRevision(request.Context(), revision); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
task.AssignedUserID = ""
task.Status = domain.AnnotationTaskStatusPendingQuality
task.UpdatedAt = nowISO()
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
item, err := server.humanItemForLegacyTask(request.Context(), *task)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if item != nil {
previousVersion := item.Version
item.CurrentStageID = cutReviewStageID
item.Status = domain.HumanItemReady
item.AssignedUserID = ""
item.ClaimedAt = ""
item.LatestAuthorUserID = principal.User.ID
item.Version++
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, 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.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: cutAdjustmentStageID, Round: item.ReviewRound, Status: domain.HumanItemSubmitted, AssigneeUserID: principal.User.ID, SubmissionRef: revision.ID})
_ = server.appendHumanEvent(request.Context(), *item, "submitted", principal.User.ID, map[string]any{"submissionRef": revision.ID, "sliceRevision": revision.Revision})
}
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{ID: domain.NewID("annotation-worklog"), OrganizationID: task.OrganizationID, ProjectID: task.ProjectID, TaskID: task.ID, UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID, EventType: "slice_submitted", Mode: taskMode, Temporary: isTemp, Revision: revision.Revision, TemplateVersion: task.TemplateVersion, DurationSeconds: payload.DurationSeconds, OutputDelta: 0, CreatedAt: nowISO()})
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "sliceRevision": revision})
}
func validateCombinedAnnotationEvents(segments []domain.AnnotationSegment, task domain.AnnotationTaskRecord) []validationIssue {
return validateCombinedAnnotationEventsWithRequireDesc(segments, task, true)
}
func validateDraftCombinedAnnotationEvents(segments []domain.AnnotationSegment, task domain.AnnotationTaskRecord) []validationIssue {
return validateCombinedAnnotationEventsWithRequireDesc(segments, task, false)
}
func validateCombinedAnnotationEventsWithRequireDesc(segments []domain.AnnotationSegment, task domain.AnnotationTaskRecord, requireDescription bool) []validationIssue {
issues := make([]validationIssue, 0)
sorted := append([]domain.AnnotationSegment(nil), segments...)
sort.Slice(sorted, func(left int, right int) bool { return sorted[left].Start < sorted[right].Start })
allowedStart, allowedEnd := annotationTaskEditableRange(task)
seenIDs := make(map[string]struct{}, len(sorted))
for index, segment := range sorted {
id := strings.TrimSpace(segment.ID)
if id == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "annotation event id is required"})
} else if _, exists := seenIDs[id]; exists {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "annotation event ids must be unique"})
} else {
seenIDs[id] = struct{}{}
}
if requireDescription && strings.TrimSpace(segment.Description) == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.description", index), Message: "event description is required"})
}
if task.TemplateVersion < 6 {
switch strings.TrimSpace(segment.Handedness) {
case "left", "right", "both":
default:
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.handedness", index), Message: "event handedness must be left, right, or both"})
}
}
if segment.Start < allowedStart || segment.End > allowedEnd || segment.End <= segment.Start || math.IsNaN(segment.Start) || math.IsNaN(segment.End) {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "event must be finite and inside the clip range"})
}
if segment.Confidence < 0 || segment.Confidence > 1 || math.IsNaN(segment.Confidence) {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.confidence", index), Message: "confidence must be between 0 and 1"})
}
if index > 0 && segment.Start < sorted[index-1].End {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "events must not overlap"})
}
}
return issues
}
func validateAnnotationSegments(segments []domain.AnnotationSegment, task domain.AnnotationTaskRecord) []validationIssue {
issues := make([]validationIssue, 0)
sorted := append([]domain.AnnotationSegment(nil), segments...)
sort.Slice(sorted, func(left int, right int) bool { return sorted[left].Start < sorted[right].Start })
allowedStart, allowedEnd := annotationTaskEditableRange(task)
seenIDs := make(map[string]struct{}, len(sorted))
for index, segment := range sorted {
id := strings.TrimSpace(segment.ID)
if id == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "annotation segment id is required"})
} else if _, exists := seenIDs[id]; exists {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.id", index), Message: "annotation segment ids must be unique"})
} else {
seenIDs[id] = struct{}{}
}
if strings.TrimSpace(segment.LabelID) == "" || strings.TrimSpace(segment.Label) == "" {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "labelId and label are required"})
}
if segment.Start < allowedStart || segment.End > allowedEnd || segment.End <= segment.Start || math.IsNaN(segment.Start) || math.IsNaN(segment.End) {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "segment must be finite and inside the clip range"})
}
if segment.Confidence < 0 || segment.Confidence > 1 || math.IsNaN(segment.Confidence) {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d.confidence", index), Message: "confidence must be between 0 and 1"})
}
if index > 0 && segment.Start < sorted[index-1].End {
issues = append(issues, validationIssue{Field: fmt.Sprintf("segments.%d", index), Message: "segments must not overlap"})
}
}
return issues
}
func (server *server) handleAnnotationRevisionCreate(writer http.ResponseWriter, request *http.Request) {
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
if !annotationManager(principal) && !membershipHasRole(memberships, *task, domain.AnnotationRoleAnnotator) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "annotator assignment is required"})
return
}
humanItem, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, "semantic_annotation")
if !claimed {
return
}
var payload annotationRevisionInput
if !decodeJSON(writer, request, &payload) {
return
}
if issues := server.canonicalActionDictionaries(request.Context(), humanItem, payload.Segments); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
if issues := validateAnnotationSegments(payload.Segments, *task); len(issues) > 0 {
renderValidationError(writer, issues...)
return
}
existingRevisions, err := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
isRework := len(existingRevisions) > 0 || task.Status == domain.AnnotationTaskStatusRework
revisionNumber := len(existingRevisions) + 1
revision := domain.AnnotationRevisionRecord{
ID: domain.NewID("annotation-revision"), OrganizationID: task.OrganizationID, TaskID: task.ID,
Revision: revisionNumber, TemplateVersion: task.TemplateVersion, Segments: payload.Segments, ObjectHints: payload.ObjectHints,
AuthorUserID: principal.User.ID, ChangeReason: strings.TrimSpace(payload.ChangeReason),
IsRework: isRework, CountsAsOutput: !isRework, DurationSeconds: payload.DurationSeconds, CreatedAt: nowISO(),
}
if err := server.store.UpsertAnnotationRevision(request.Context(), revision); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
task.CurrentRevision = revisionNumber
task.Status = domain.AnnotationTaskStatusPendingQuality
task.AssignedUserID = principal.User.ID
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
eventType := "annotation_submitted"
submissionKind := "first"
if isRework {
eventType = "rework_submitted"
submissionKind = "rework"
}
outputDelta := int64(0)
if revision.CountsAsOutput {
outputDelta = 1
}
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{
ID: revision.ID + ":worklog", SubmissionID: revision.ID, SubmissionKind: submissionKind, OrganizationID: task.OrganizationID, ProjectID: task.ProjectID,
TaskID: task.ID, UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID,
EventType: eventType, Mode: taskMode, Temporary: isTemp, Revision: revisionNumber, TemplateVersion: task.TemplateVersion,
DurationSeconds: payload.DurationSeconds, OutputDelta: outputDelta, CreatedAt: nowISO(),
})
if err := server.syncHumanItemFromLegacyRevision(request.Context(), *task, revision); err != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("sync human item revision: %w", err))
return
}
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "revision": revision})
}
type annotationReviewInput struct {
ReviewDecisionInput
Stage domain.AnnotationReviewStage `json:"stage"`
Decision domain.AnnotationReviewDecision `json:"decision"`
Comment string `json:"comment,omitempty"`
DurationSeconds int64 `json:"durationSeconds,omitempty"`
RejectTargets []string `json:"rejectTargets,omitempty"`
ReasonCodes []string `json:"reasonCodes,omitempty"`
ProblemSliceIDs []string `json:"problemSliceIds,omitempty"`
VideoQuality string `json:"videoQuality,omitempty"`
AnnotationAccuracy float64 `json:"annotationAccuracy,omitempty"`
AnnotationCompleteness float64 `json:"annotationCompleteness,omitempty"`
OverallGrade string `json:"overallGrade,omitempty"`
}
func (server *server) queueAcceptedAnnotationGateRun(ctx context.Context, task domain.AnnotationTaskRecord) error {
if task.Status != domain.AnnotationTaskStatusAccepted || strings.TrimSpace(task.RunID) == "" || strings.TrimSpace(task.NodeID) == "" {
return nil
}
tasks, err := server.store.ListAnnotationTasks(ctx, task.OrganizationID, task.ProjectID)
if err != nil {
return err
}
matched := 0
for _, candidate := range tasks {
if candidate.RunID != task.RunID || candidate.NodeID != task.NodeID {
continue
}
matched++
if candidate.Status != domain.AnnotationTaskStatusAccepted {
return nil
}
}
if matched == 0 {
return nil
}
batches, err := server.store.ListHumanBatches(ctx, task.OrganizationID, domain.HumanBatchQuery{RunID: task.RunID})
if err != nil {
return err
}
for index := range batches {
batch := &batches[index]
if batch.GateNodeID != task.NodeID || batch.ReleasePolicy != domain.HumanReleaseAcceptedPartition {
continue
}
if err := server.flushHumanReleasePartitions(ctx, batch, true); err != nil {
return err
}
run, err := server.store.GetRun(ctx, task.RunID)
if err != nil || run == nil {
return err
}
for executionIndex := range run.NodeExecutions {
if run.NodeExecutions[executionIndex].NodeID == task.NodeID {
run.NodeExecutions[executionIndex].Status = domain.NodeExecutionStatusCompleted
run.NodeExecutions[executionIndex].EndedAt = nowISO()
run.NodeExecutions[executionIndex].Logs = append(run.NodeExecutions[executionIndex].Logs, domain.LogEntryRecord{
Timestamp: nowISO(), Level: "INFO", Message: "All human items accepted and partitioned", Operator: run.NodeExecutions[executionIndex].NodeLabel,
})
}
}
run.Status = domain.RunStatusCompleted
run.CurrentNodeID = ""
run.EndedAt = nowISO()
run.UpdatedAt = nowISO()
if err := server.store.UpsertRun(ctx, *run); err != nil {
return err
}
return server.store.UpdateWorkflowRunState(ctx, run.WorkflowID, domain.WorkflowStatusCompleted, run.ID, nowISO())
}
run, err := server.store.GetRun(ctx, task.RunID)
if err != nil || run == nil {
return err
}
if (run.Status != domain.RunStatusWaitingForAudit && run.Status != domain.RunStatusWaitingForHuman) || run.CurrentNodeID != task.NodeID {
return nil
}
run.Status = domain.RunStatusQueued
run.UpdatedAt = nowISO()
return server.store.UpsertRun(ctx, *run)
}
func fanyuV5FourStageReviewRoute(stage domain.AnnotationReviewStage) (reviewStageID string, defaultRejectTarget string, allowedRejectTargets []string, ok bool) {
switch stage {
case domain.AnnotationReviewStageSplitQuality:
return domain.FanyuV5StageCutReview, domain.FanyuV5StageCutAdjustment, []string{domain.FanyuV5StageCutAdjustment}, true
case domain.AnnotationReviewStageQuality:
return domain.FanyuV5StageSemanticReview, domain.FanyuV5StageSemanticAnnotation, []string{domain.FanyuV5StageSemanticAnnotation, domain.FanyuV5StageCutAdjustment}, true
default:
return "", "", nil, false
}
}
func allowedFanyuV5RejectTarget(target string, allowed []string) bool {
for _, candidate := range allowed {
if candidate == target {
return true
}
}
return false
}
// handleFanyuV5FourStageReview implements the supplier-facing rejection loop
// as an immediate, auditable rework transition. We deliberately do not leave
// a v5 review failure in the generic reject zone: cut review must go straight
// back to cut adjustment. Semantic review defaults to semantic annotation but
// may return to cut adjustment when the slice boundary itself is wrong. The
// HumanReject record remains append-only evidence of the chosen route.
func (server *server) handleFanyuV5FourStageReview(writer http.ResponseWriter, request *http.Request, task *domain.AnnotationTaskRecord, principal *authenticatedPrincipal, item *domain.HumanItemRecord, batch *domain.HumanBatchRecord, payload annotationReviewInput) bool {
if task == nil || item == nil || batch == nil || !isFanyuV5FourStageBatch(batch) {
return false
}
reviewStageID, rejectTargetStageID, allowedRejectTargets, routed := fanyuV5FourStageReviewRoute(payload.Stage)
if !routed {
renderValidationError(writer, validationIssue{Field: "stage", Message: "v5 requires cut review or semantic review before aggregate acceptance"})
return true
}
if item.CurrentStageID != reviewStageID {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "v5 item is not in the requested review stage", "code": "human_item_stage_conflict"})
return true
}
reviewRevision := task.CurrentRevision
if payload.Stage == domain.AnnotationReviewStageSplitQuality {
sliceRevisions, sliceErr := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
if sliceErr != nil {
renderError(writer, http.StatusInternalServerError, sliceErr)
return true
}
if len(sliceRevisions) == 0 {
renderValidationError(writer, validationIssue{Field: "revision", Message: "a cut adjustment is required before cut review"})
return true
}
latestSlice := sliceRevisions[len(sliceRevisions)-1]
reviewRevision = latestSlice.Revision
if latestSlice.AuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own cut adjustment", "code": "separation_of_duties"})
return true
}
} else {
if task.CurrentRevision <= 0 {
renderValidationError(writer, validationIssue{Field: "revision", Message: "a semantic annotation is required before semantic review"})
return true
}
revisions, revisionErr := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
if revisionErr != nil {
renderError(writer, http.StatusInternalServerError, revisionErr)
return true
}
for _, revision := range revisions {
if revision.Revision == task.CurrentRevision && revision.AuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own semantic annotation", "code": "separation_of_duties"})
return true
}
}
}
if payload.Decision != domain.AnnotationReviewApproved && payload.Decision != domain.AnnotationReviewRejected {
renderValidationError(writer, validationIssue{Field: "decision", Message: "decision must be approved or rejected"})
return true
}
if payload.Decision == domain.AnnotationReviewRejected {
if strings.TrimSpace(payload.Comment) == "" || len(payload.ReasonCodes) == 0 {
renderValidationError(writer, validationIssue{Field: "rejection", Message: "reasonCodes and comment are required for rework"})
return true
}
if len(payload.RejectTargets) > 0 {
if len(payload.RejectTargets) != 1 || !allowedFanyuV5RejectTarget(payload.RejectTargets[0], allowedRejectTargets) {
renderValidationError(writer, validationIssue{Field: "rejectTargets", Message: "v5 review reject target is not allowed for the current stage"})
return true
}
rejectTargetStageID = payload.RejectTargets[0]
}
}
existing, existingErr := server.store.ListAnnotationReviews(request.Context(), task.OrganizationID, task.ID)
if existingErr != nil {
renderError(writer, http.StatusInternalServerError, existingErr)
return true
}
for _, review := range existing {
if review.Revision == reviewRevision && review.Stage == payload.Stage {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "review already exists for this revision and stage"})
return true
}
}
now := nowISO()
review := domain.AnnotationReviewRecord{
ID: domain.NewID("annotation-review"), OrganizationID: task.OrganizationID, TaskID: task.ID,
Revision: reviewRevision, Stage: payload.Stage, Decision: payload.Decision, ReviewerUserID: principal.User.ID,
Comment: strings.TrimSpace(payload.Comment), VideoQuality: strings.TrimSpace(payload.VideoQuality),
AnnotationAccuracy: payload.AnnotationAccuracy, AnnotationCompleteness: payload.AnnotationCompleteness,
OverallGrade: strings.TrimSpace(payload.OverallGrade), ReasonCodes: payload.ReasonCodes, CreatedAt: now,
}
if payload.Decision == domain.AnnotationReviewRejected {
review.RejectTargets = []string{rejectTargetStageID}
if payload.Stage == domain.AnnotationReviewStageQuality {
review.NextRevision = task.CurrentRevision + 1
}
task.Status = domain.AnnotationTaskStatusRework
task.AssignedUserID = ""
} else if payload.Stage == domain.AnnotationReviewStageSplitQuality {
// A cut has no semantic revision yet; the next available task is the
// semantic annotation stage, not a re-run of automatic rough cutting.
task.CurrentRevision = 0
task.Status = domain.AnnotationTaskStatusPendingAnnotation
task.AssignedUserID = ""
} else {
task.Status = domain.AnnotationTaskStatusAccepted
task.AssignedUserID = ""
}
if err := server.store.UpsertAnnotationReview(request.Context(), review); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
previousVersion := item.Version
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
if payload.Decision == domain.AnnotationReviewRejected {
item.ReviewRound++
item.CurrentStageID = rejectTargetStageID
if item.ReviewRound > item.MaxReworkRounds {
item.Status = domain.HumanItemEscalated
task.Status = domain.AnnotationTaskStatusRejected
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
} else {
item.Status = domain.HumanItemRework
}
} else if payload.Stage == domain.AnnotationReviewStageSplitQuality {
item.CurrentStageID = domain.FanyuV5StageSemanticAnnotation
item.Status = domain.HumanItemReady
} else {
item.Status = domain.HumanItemAccepted
item.AcceptedAt = now
item.AcceptedByUserID = principal.User.ID
}
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, 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 true
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{
OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: reviewStageID, Round: item.ReviewRound,
Status: item.Status, AssigneeUserID: principal.User.ID, ReviewedRevision: review.Revision,
Decision: domain.HumanDecision(payload.Decision), RejectTargets: review.RejectTargets, ReasonCodes: review.ReasonCodes, Comment: review.Comment,
})
if payload.Decision == domain.AnnotationReviewRejected {
_ = server.store.UpsertHumanReject(request.Context(), domain.HumanRejectRecord{
OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, ProjectID: item.ProjectID,
WorkflowID: item.WorkflowID, RunID: item.RunID, StageID: reviewStageID, AttemptRound: item.ReviewRound,
ReviewedRevision: review.Revision, RejectedByUserID: principal.User.ID, ReasonCodes: review.ReasonCodes,
Comment: review.Comment, AllowedReopenStages: append([]string(nil), allowedRejectTargets...), Status: domain.HumanRejectReopened,
ReopenCount: 1, ReopenedByUserID: principal.User.ID, ReopenTargetStageID: rejectTargetStageID,
ReopenComment: "automatic v5 rework routing", ReopenedAt: now,
})
}
eventType := reviewStageID + "_" + string(payload.Decision)
_ = server.appendHumanEvent(request.Context(), *item, eventType, principal.User.ID, map[string]any{
"reviewedRevision": review.Revision, "rejectTargets": review.RejectTargets, "reasonCodes": review.ReasonCodes,
"comment": review.Comment, "routedToStage": rejectTargetStageID,
})
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{
ID: domain.NewID("annotation-worklog"), OrganizationID: task.OrganizationID, ProjectID: task.ProjectID, TaskID: task.ID,
UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID,
EventType: eventType, Mode: taskMode, Temporary: isTemp, Revision: review.Revision, TemplateVersion: task.TemplateVersion,
DurationSeconds: payload.DurationSeconds, OutputDelta: 0, CreatedAt: now,
})
if item.Status == domain.HumanItemAccepted {
if err := server.flushHumanReleasePartitions(request.Context(), batch, false); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
}
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "review": review, "humanItem": item})
return true
}
func (server *server) handleFanyuV5CombinedQualityReview(writer http.ResponseWriter, request *http.Request, task *domain.AnnotationTaskRecord, principal *authenticatedPrincipal, item *domain.HumanItemRecord, batch *domain.HumanBatchRecord, payload annotationReviewInput) bool {
if task == nil || item == nil || batch == nil || !batch.RequirePrePackageAcceptance {
return false
}
if payload.Stage != domain.AnnotationReviewStageQuality {
renderValidationError(writer, validationIssue{Field: "stage", Message: "v5 per-clip tasks only accept the combined quality review; final acceptance is a separate aggregate task"})
return true
}
if item.CurrentStageID != "quality_review" || task.CurrentRevision <= 0 {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "v5 task is not ready for combined quality review"})
return true
}
revisions, err := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
for _, revision := range revisions {
if revision.Revision == task.CurrentRevision && revision.AuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own combined annotation", "code": "separation_of_duties"})
return true
}
}
structuredDecision := operationFromRequest(request) != nil && operationFromRequest(request).Draft.ModelVersion == 2
if payload.Decision == domain.AnnotationReviewRejected && (len(payload.ReasonCodes) == 0 || (!structuredDecision && (strings.TrimSpace(payload.Comment) == "" || len(payload.ProblemSliceIDs) == 0))) {
renderValidationError(writer, validationIssue{Field: "rejection", Message: "reasonCodes, comment and at least one problemSliceId are required for v5 combined quality rework"})
return true
}
if payload.Decision != domain.AnnotationReviewApproved && payload.Decision != domain.AnnotationReviewRejected {
renderValidationError(writer, validationIssue{Field: "decision", Message: "decision must be approved or rejected"})
return true
}
existing, err := server.store.ListAnnotationReviews(request.Context(), task.OrganizationID, task.ID)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
for _, review := range existing {
// Final acceptance can reopen quality without changing annotation data.
// Preserve the previous decision while allowing this new review round.
// Legacy records have round zero, matching the original quality pass.
if review.Stage == domain.AnnotationReviewStageQuality && review.Revision == task.CurrentRevision && review.ReviewRound == item.ReviewRound {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "本轮质检已提交,请刷新查看最新状态", "code": "quality_review_already_submitted"})
return true
}
}
if operationFromRequest(request) != nil {
server.planQualityReviewDecision(writer, request, *task, *item, batch, payload)
return true
}
returnAuthor := ""
if payload.Decision == domain.AnnotationReviewRejected && reworkReturnMode() == "directed" {
var err error
returnAuthor, err = server.reworkAuthor(request.Context(), *item)
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
}
now := nowISO()
review := domain.AnnotationReviewRecord{ID: domain.NewID("annotation-review"), OrganizationID: task.OrganizationID, TaskID: task.ID, Revision: task.CurrentRevision, Stage: domain.AnnotationReviewStageQuality, Decision: payload.Decision, ReviewerUserID: principal.User.ID, Comment: strings.TrimSpace(payload.Comment), VideoQuality: strings.TrimSpace(payload.VideoQuality), AnnotationAccuracy: payload.AnnotationAccuracy, AnnotationCompleteness: payload.AnnotationCompleteness, OverallGrade: strings.TrimSpace(payload.OverallGrade), ReasonCodes: payload.ReasonCodes, ProblemSliceIDs: payload.ProblemSliceIDs, CreatedAt: now}
review.ReviewRound = item.ReviewRound
if payload.Decision == domain.AnnotationReviewRejected {
review.NextRevision = task.CurrentRevision + 1
review.RejectTargets = []string{"annotation_combined"}
task.Status = domain.AnnotationTaskStatusRework
task.AssignedUserID = returnAuthor
} else {
// Quality approval is not packaging approval. The root task is accepted
// and waits for the one aggregate pre-package acceptance item.
task.Status = domain.AnnotationTaskStatusAccepted
task.AssignedUserID = ""
}
if err := server.store.UpsertAnnotationReview(request.Context(), review); err != nil {
if mongo.IsDuplicateKeyError(err) {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "本轮质检已提交,请刷新查看最新状态", "code": "quality_review_already_submitted"})
return true
}
renderError(writer, http.StatusInternalServerError, err)
return true
}
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
previousVersion := item.Version
item.AssignedUserID = ""
item.ClaimedAt = ""
item.Version++
if payload.Decision == domain.AnnotationReviewRejected {
item.ReviewRound++
item.CurrentStageID = "annotation_combined"
if item.ReviewRound > item.MaxReworkRounds {
item.Status = domain.HumanItemEscalated
task.Status = domain.AnnotationTaskStatusRejected
_ = server.store.UpsertAnnotationTask(request.Context(), *task)
} else {
item.Status = domain.HumanItemRework
item.AssignedUserID = returnAuthor
if returnAuthor != "" {
item.Status = domain.HumanItemClaimed
item.ClaimedAt = now
}
}
} else {
item.Status = domain.HumanItemAccepted
item.AcceptedAt = now
}
updated, updateErr := server.store.UpdateHumanItemVersioned(request.Context(), *item, 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 true
}
_ = server.store.UpsertHumanStageAttempt(request.Context(), domain.HumanStageAttemptRecord{OrganizationID: item.OrganizationID, ItemID: item.ID, StageID: "quality_review", Round: item.ReviewRound, Status: item.Status, AssigneeUserID: principal.User.ID, ReviewedRevision: review.Revision, Decision: domain.HumanDecision(payload.Decision), RejectTargets: review.RejectTargets, ReasonCodes: review.ReasonCodes, ProblemSliceIDs: review.ProblemSliceIDs, Comment: review.Comment})
if payload.Decision == domain.AnnotationReviewRejected {
status := domain.HumanRejectReopened
if item.Status == domain.HumanItemEscalated {
status = domain.HumanRejectEscalated
}
_ = server.store.UpsertHumanReject(request.Context(), domain.HumanRejectRecord{
OrganizationID: item.OrganizationID, BatchID: item.BatchID, ItemID: item.ID, ProjectID: item.ProjectID,
WorkflowID: item.WorkflowID, RunID: item.RunID, StageID: "quality_review", AttemptRound: item.ReviewRound,
ReviewedRevision: review.Revision, RejectedByUserID: principal.User.ID, ReasonCodes: review.ReasonCodes,
ProblemSliceIDs: review.ProblemSliceIDs, Comment: review.Comment,
AllowedReopenStages: []string{"annotation_combined"}, Status: status,
ReopenCount: 1, ReopenedByUserID: principal.User.ID, ReopenTargetStageID: "annotation_combined",
ReopenComment: "automatic v5.8 Capture rework routing", ReopenedAt: now,
})
}
_ = server.appendHumanEvent(request.Context(), *item, "combined_quality_"+string(payload.Decision), principal.User.ID, map[string]any{"reviewedRevision": review.Revision, "reasonCodes": review.ReasonCodes, "problemSliceIds": review.ProblemSliceIDs, "comment": review.Comment})
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{ID: domain.NewID("annotation-worklog"), OrganizationID: task.OrganizationID, ProjectID: task.ProjectID, TaskID: task.ID, UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID, EventType: "quality_" + string(payload.Decision), Mode: taskMode, Temporary: isTemp, Revision: review.Revision, TemplateVersion: task.TemplateVersion, DurationSeconds: payload.DurationSeconds, OutputDelta: 0, CreatedAt: now})
if payload.Decision == domain.AnnotationReviewApproved {
if err := server.flushHumanReleasePartitions(request.Context(), batch, false); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return true
}
}
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "review": review, "humanItem": item})
return true
}
func (server *server) handleAnnotationReviewCreate(writer http.ResponseWriter, request *http.Request) {
started := time.Now()
defer func() {
log.Printf("[api] review_latency operation=annotation_review task=%s total_ms=%d", chi.URLParam(request, "id"), time.Since(started).Milliseconds())
}()
task, err := server.getAnnotationTaskForAccess(request.Context(), chi.URLParam(request, "id"))
if err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Annotation task not found"})
return
}
principal, memberships, ok := server.ensureAnnotationTaskAccess(writer, request, *task)
if !ok {
return
}
var payload annotationReviewInput
if !decodeJSON(writer, request, &payload) {
return
}
if payload.Decision == domain.AnnotationReviewApproved && (len(payload.ProblemSliceIDs) > 0 || len(payload.ReasonCodes) > 0 || (payload.Stage == domain.AnnotationReviewStageQuality && task.TemplateVersion >= 6 && strings.TrimSpace(payload.Comment) != "")) {
renderValidationError(writer, validationIssue{Field: "decision", Message: "存在问题标记或错误备注,请清除后通过,或选择打回"})
return
}
if payload.Stage != domain.AnnotationReviewStageSplitQuality && payload.Stage != domain.AnnotationReviewStageQuality && payload.Stage != domain.AnnotationReviewStageAcceptance && string(payload.Stage) != "split_quality_review" && string(payload.Stage) != "quality_review" {
renderValidationError(writer, validationIssue{Field: "stage", Message: "stage must be split_quality, quality or acceptance"})
return
}
if string(payload.Stage) == "split_quality_review" {
payload.Stage = domain.AnnotationReviewStageSplitQuality
} else if string(payload.Stage) == "quality_review" {
payload.Stage = domain.AnnotationReviewStageQuality
}
if payload.Decision != domain.AnnotationReviewApproved && payload.Decision != domain.AnnotationReviewRejected {
renderValidationError(writer, validationIssue{Field: "decision", Message: "decision must be approved or rejected"})
return
}
requiredRole := domain.AnnotationRoleQualityReviewer
if payload.Stage == domain.AnnotationReviewStageSplitQuality {
requiredRole = domain.AnnotationRoleAnnotator
} else if payload.Stage == domain.AnnotationReviewStageAcceptance {
requiredRole = domain.AnnotationRoleAcceptanceReviewer
}
if !annotationManager(principal) && !membershipHasRole(memberships, *task, requiredRole) {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": string(requiredRole) + " assignment is required"})
return
}
if server.replayReviewDecision(writer, request, task.ID, payload.ReviewDecisionInput, payload) {
return
}
humanItem, claimed := server.requireLegacyHumanItemClaim(writer, request, *task, "")
if !claimed {
return
}
var prepared bool
request, prepared = server.prepareReviewDecision(writer, request, *humanItem, "quality", payload.ReviewDecisionInput, payload, string(payload.Decision))
if !prepared {
return
}
defer server.finishReviewDecisionPreparation(request)
finishReviewWrite, writeAllowed := server.beginReviewWrite(writer, request, *humanItem)
if !writeAllowed {
return
}
defer finishReviewWrite()
batch, batchErr := server.store.GetHumanBatch(request.Context(), humanItem.BatchID)
if batchErr != nil {
renderError(writer, http.StatusInternalServerError, batchErr)
return
}
if batch == nil {
renderJSON(writer, http.StatusNotFound, map[string]string{"error": "Human batch not found"})
return
}
requiredStageID := "quality_review"
if payload.Stage == domain.AnnotationReviewStageAcceptance {
requiredStageID = "acceptance"
} else if payload.Stage == domain.AnnotationReviewStageSplitQuality {
requiredStageID = "split_quality_review"
}
if isFanyuV5FourStageBatch(batch) {
if stageID, _, _, routed := fanyuV5FourStageReviewRoute(payload.Stage); routed {
requiredStageID = stageID
}
}
if humanItem.CurrentStageID != requiredStageID {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "Human item is not in the required review stage", "code": "human_item_stage_conflict"})
return
}
if isFanyuV5FourStageBatch(batch) {
if server.handleFanyuV5FourStageReview(writer, request, task, principal, humanItem, batch, payload) {
return
}
}
if batch != nil {
if server.handleFanyuV5CombinedQualityReview(writer, request, task, principal, humanItem, batch, payload) {
return
}
}
reviewRevision := task.CurrentRevision
if payload.Stage == domain.AnnotationReviewStageSplitQuality {
sliceRevisions, sliceErr := server.store.ListSliceRevisions(request.Context(), task.OrganizationID, task.ID)
if sliceErr != nil {
renderError(writer, http.StatusInternalServerError, sliceErr)
return
}
if len(sliceRevisions) == 0 {
renderValidationError(writer, validationIssue{Field: "revision", Message: "a slice revision is required before split quality review"})
return
}
latestSlice := sliceRevisions[len(sliceRevisions)-1]
reviewRevision = latestSlice.Revision
if latestSlice.AuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own clip", "code": "separation_of_duties"})
return
}
} else {
if task.CurrentRevision <= 0 {
renderValidationError(writer, validationIssue{Field: "revision", Message: "an annotation revision is required before review"})
return
}
revisions, revisionErr := server.store.ListAnnotationRevisions(request.Context(), task.OrganizationID, task.ID)
if revisionErr != nil {
renderError(writer, http.StatusInternalServerError, revisionErr)
return
}
for _, revision := range revisions {
if revision.Revision == task.CurrentRevision && revision.AuthorUserID == principal.User.ID {
renderJSON(writer, http.StatusForbidden, map[string]string{"error": "A submitter cannot review their own annotation", "code": "separation_of_duties"})
return
}
}
}
if payload.Decision == domain.AnnotationReviewRejected && strings.TrimSpace(payload.Comment) == "" {
renderValidationError(writer, validationIssue{Field: "comment", Message: "comment is required for rejection"})
return
}
existing, existingErr := server.store.ListAnnotationReviews(request.Context(), task.OrganizationID, task.ID)
if existingErr != nil {
renderError(writer, http.StatusInternalServerError, existingErr)
return
}
for _, review := range existing {
if review.Revision == reviewRevision && review.Stage == payload.Stage {
renderJSON(writer, http.StatusConflict, map[string]string{"error": "review already exists for this revision and stage"})
return
}
}
review := domain.AnnotationReviewRecord{
ID: domain.NewID("annotation-review"), OrganizationID: task.OrganizationID, TaskID: task.ID,
Revision: reviewRevision, Stage: payload.Stage, Decision: payload.Decision,
ReviewerUserID: principal.User.ID, Comment: strings.TrimSpace(payload.Comment), CreatedAt: nowISO(),
VideoQuality: strings.TrimSpace(payload.VideoQuality), AnnotationAccuracy: payload.AnnotationAccuracy,
AnnotationCompleteness: payload.AnnotationCompleteness, OverallGrade: strings.TrimSpace(payload.OverallGrade),
ReasonCodes: payload.ReasonCodes, RejectTargets: payload.RejectTargets,
}
if payload.Stage == domain.AnnotationReviewStageSplitQuality {
if payload.Decision == domain.AnnotationReviewRejected {
if len(review.RejectTargets) == 0 {
review.RejectTargets = []string{"split_annotation"}
}
task.Status = domain.AnnotationTaskStatusRework
task.AssignedUserID = ""
} else {
task.CurrentRevision = 0
task.Status = domain.AnnotationTaskStatusPendingAnnotation
task.AssignedUserID = ""
}
} else if payload.Decision == domain.AnnotationReviewRejected {
review.NextRevision = task.CurrentRevision + 1
if len(review.RejectTargets) == 0 {
review.RejectTargets = []string{"semantic_annotation"}
}
task.Status = domain.AnnotationTaskStatusRework
task.AssignedUserID = ""
} else if payload.Stage == domain.AnnotationReviewStageQuality {
task.Status = domain.AnnotationTaskStatusAccepted
} else {
task.Status = domain.AnnotationTaskStatusAccepted
}
if err := server.store.UpsertAnnotationReview(request.Context(), review); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if err := server.store.UpsertAnnotationTask(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, err)
return
}
if task.Status == domain.AnnotationTaskStatusAccepted {
if err := server.queueAcceptedAnnotationGateRun(request.Context(), *task); err != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("resume annotation workflow: %w", err))
return
}
}
eventType := string(payload.Stage) + "_" + string(payload.Decision)
taskMode, isTemp := server.resolveTaskRunMode(request.Context(), task.RunID)
_ = server.store.UpsertAnnotationWorklogEvent(request.Context(), domain.AnnotationWorklogEventRecord{
ID: domain.NewID("annotation-worklog"), OrganizationID: task.OrganizationID, ProjectID: task.ProjectID,
TaskID: task.ID, UserID: principal.User.ID, SupplierID: task.SupplierID, WorkgroupID: task.WorkgroupID, VendorID: task.VendorID,
EventType: eventType, Mode: taskMode, Temporary: isTemp, Revision: task.CurrentRevision, TemplateVersion: task.TemplateVersion,
DurationSeconds: payload.DurationSeconds, OutputDelta: 0, CreatedAt: nowISO(),
})
if err := server.syncHumanItemFromLegacyReview(request.Context(), *task, review, review.RejectTargets, payload.ReasonCodes); err != nil {
renderError(writer, http.StatusInternalServerError, fmt.Errorf("sync human item review: %w", err))
return
}
renderJSON(writer, http.StatusCreated, map[string]any{"task": task, "review": review})
}
func (server *server) resolveTaskRunMode(ctx context.Context, runID string) (domain.RunMode, bool) {
if strings.TrimSpace(runID) == "" {
return domain.RunModeProduction, false
}
run, err := server.store.GetRun(ctx, strings.TrimSpace(runID))
if err != nil || run == nil {
return domain.RunModeProduction, false
}
mode := run.Mode
if mode == "" {
mode = domain.RunModeProduction
}
return mode, mode == domain.RunModeDebug
}