droboticflow/internal/api/review_session.go

387 lines
14 KiB
Go

package api
import (
"context"
"crypto/sha256"
"droboticflow/internal/domain"
"encoding/json"
"fmt"
"net/http"
"strconv"
"strings"
"time"
)
const reviewSessionLifetime = 45 * time.Second
func reviewSessionKey(item domain.HumanItemRecord) string {
return fmt.Sprintf("%s:%s:%s:%d", item.OrganizationID, item.ID, item.CurrentStageID, item.ReviewRound)
}
// Result identity excludes claim versions and page heartbeats, but includes the
// evidence and actual revisions, including legacy in-place annotation updates.
func (server *server) reviewResultVersion(ctx context.Context, item domain.HumanItemRecord) (string, error) {
values := []any{item.CurrentStageID, item.ReviewRound, item.CurrentRevision, item.Subject}
if item.LegacyTaskID != "" {
task, e := server.store.GetAnnotationTask(ctx, item.LegacyTaskID)
if e != nil {
return "", e
}
slices, e := server.store.ListSliceRevisions(ctx, item.OrganizationID, item.LegacyTaskID)
if e != nil {
return "", e
}
actions, e := server.store.ListAnnotationRevisions(ctx, item.OrganizationID, item.LegacyTaskID)
if e != nil {
return "", e
}
revision := 0
if task != nil {
revision = task.CurrentRevision
}
values = append(values, revision, slices, actions)
}
encoded, e := json.Marshal(values)
if e != nil {
return "", e
}
return fmt.Sprintf("%x", sha256.Sum256(encoded)), nil
}
func (server *server) loadReviewItemForRequest(w http.ResponseWriter, r *http.Request) (*domain.HumanItemRecord, bool) {
item, ok := server.loadHumanItemForRequest(w, r)
if !ok {
return nil, false
}
principal, _ := currentPrincipal(r)
batch, e := server.store.GetHumanBatch(r.Context(), item.BatchID)
if e != nil {
renderError(w, 500, e)
return nil, false
}
if batch == nil {
renderJSON(w, 404, map[string]string{"error": "Human batch not found"})
return nil, false
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if !found || (stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance) {
renderJSON(w, 409, map[string]string{"error": "当前任务已不在审查阶段", "code": "review_context_changed"})
return nil, false
}
if principal == nil || !server.canAccessHumanItem(r.Context(), r, *item, annotationRoleForHumanStage(stage)) {
renderJSON(w, 403, map[string]string{"error": "没有本环节的审查权限"})
return nil, false
}
if item.AssignedUserID != principal.User.ID || (item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress) {
renderJSON(w, 409, map[string]string{"error": "请先领取该审查任务", "code": "human_item_claim_required"})
return nil, false
}
if item.LatestAuthorUserID != "" && item.LatestAuthorUserID == principal.User.ID {
renderJSON(w, 403, map[string]string{"error": "不能审查本人提交的标注", "code": "separation_of_duties"})
return nil, false
}
return item, true
}
func (server *server) currentReviewItem(r *http.Request, expected domain.HumanItemRecord) (*domain.HumanItemRecord, bool) {
item, err := server.store.GetHumanItem(r.Context(), expected.ID)
principal, _ := currentPrincipal(r)
if err != nil || item == nil || principal == nil || item.OrganizationID != expected.OrganizationID || item.ProjectID != expected.ProjectID || item.BatchID != expected.BatchID || item.CurrentStageID != expected.CurrentStageID || item.ReviewRound != expected.ReviewRound || item.CurrentRevision != expected.CurrentRevision || item.Version != expected.Version || item.AssignedUserID != principal.User.ID || (item.LatestAuthorUserID != "" && item.LatestAuthorUserID == principal.User.ID) || (item.Status != domain.HumanItemClaimed && item.Status != domain.HumanItemInProgress) {
return nil, false
}
batch, err := server.store.GetHumanBatch(r.Context(), item.BatchID)
if err != nil || batch == nil {
return nil, false
}
stage, _, found := humanStage(batch, item.CurrentStageID)
if !found || (stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance) || !server.canAccessHumanItem(r.Context(), r, *item, annotationRoleForHumanStage(stage)) {
return nil, false
}
return item, true
}
func reviewSessionFailure(w http.ResponseWriter, code string) {
message := "当前页面已失去编辑权,请接管后继续。"
if code == "review_write_in_progress" {
message = "已有审查操作正在核对结果,请稍后重试。"
}
if code == "review_context_changed" {
message = "被审结果已变化,请重新打开任务核对。"
}
renderJSON(w, http.StatusConflict, map[string]string{"error": message, "code": code})
}
func sessionResponse(s domain.ReviewSession, page, user string) map[string]any {
return map[string]any{"itemId": s.ItemID, "stageId": s.StageID, "reviewRound": s.ReviewRound, "resultVersion": s.ResultVersion, "generation": s.Generation, "expiresAt": s.ExpiresAt, "writable": s.Enrolled && s.PageID == page && s.UserID == user && s.ExpiresAt > nowISO(), "busy": s.WriteID != ""}
}
func (server *server) handleReviewSession(w http.ResponseWriter, r *http.Request) {
item, ok := server.loadReviewItemForRequest(w, r)
if !ok {
return
}
principal, _ := currentPrincipal(r)
var input struct {
Action string `json:"action"`
PageID string `json:"pageId"`
Generation int `json:"generation"`
}
if r.Method == http.MethodGet {
input.PageID = r.URL.Query().Get("pageId")
} else if !decodeJSON(w, r, &input) {
return
}
input.PageID = strings.TrimSpace(input.PageID)
if len(input.PageID) < 1 || len(input.PageID) > 120 {
renderValidationError(w, validationIssue{Field: "pageId", Message: "pageId is required (maximum 120 characters)"})
return
}
if r.Method != http.MethodGet && input.Action != "acquire" && input.Action != "takeover" && input.Action != "renew" && input.Action != "release" {
renderValidationError(w, validationIssue{Field: "action", Message: "unknown session action"})
return
}
protocol := server.reviewDecisionProtocol(r.Context(), *item)
response := func(session domain.ReviewSession) map[string]any {
value := sessionResponse(session, input.PageID, principal.User.ID)
value["decisionProtocol"] = protocol
return value
}
resultVersion, e := server.reviewResultVersion(r.Context(), *item)
if e != nil {
renderError(w, 500, e)
return
}
for attempt := 0; attempt < 8; attempt++ {
old, e := server.store.GetReviewSession(r.Context(), reviewSessionKey(*item))
if e != nil {
renderError(w, 500, e)
return
}
if old == nil {
old = &domain.ReviewSession{ID: reviewSessionKey(*item), ItemID: item.ID, StageID: item.CurrentStageID, ReviewRound: item.ReviewRound, ResultVersion: resultVersion}
}
if r.Method == http.MethodGet {
if old.ResultVersion != resultVersion {
old.ExpiresAt = ""
}
renderJSON(w, 200, response(*old))
return
}
if input.Action == "acquire" || input.Action == "takeover" || input.Action == "renew" {
if strings.HasPrefix(old.WriteID, "review-operation-") {
op, err := server.store.GetReviewOperation(r.Context(), old.WriteID)
if err != nil {
renderError(w, 500, err)
return
}
if op != nil && strings.HasSuffix(op.Kind, "_draft") {
op = server.recoverDraftReviewOperation(r.Context(), op, item)
if op.Status == "completed" || op.Status == "failed_before_effects" {
continue
}
}
// The write fence only guards an UNKNOWN outcome. A formal
// decision that already settled — or a marker whose operation
// record vanished — must not fence the item forever: the page
// that owns the receipt may be gone (refresh, another device,
// cleared storage), leaving no other way to unblock saves and
// decisions. Clear it and retry the action; a genuinely
// in-flight decision (prepared/applying) stays fenced and is
// recovered by its dedicated reconcile route.
if op == nil || op.Status == "completed" || op.Status == "failed_before_effects" {
server.finishReviewWrite(reviewSessionKey(*item), old.WriteID)
continue
}
}
}
next := *old
mine := old.PageID == input.PageID && old.UserID == principal.User.ID
switch input.Action {
case "acquire", "takeover":
if old.WriteID != "" {
reviewSessionFailure(w, "review_write_in_progress")
return
}
if input.Action == "acquire" && old.PageID != "" && old.ExpiresAt > nowISO() && !mine {
renderJSON(w, 200, response(*old))
return
}
if input.Action == "takeover" || !mine || old.ExpiresAt <= nowISO() || old.ResultVersion != resultVersion {
next.Generation++
}
next.Enrolled = true
next.PageID = input.PageID
next.UserID = principal.User.ID
next.ResultVersion = resultVersion
next.ExpiresAt = time.Now().UTC().Add(reviewSessionLifetime).Format(time.RFC3339Nano)
case "renew":
if !mine || old.Generation != input.Generation || old.ExpiresAt <= nowISO() {
reviewSessionFailure(w, "review_session_lost")
return
}
if old.ResultVersion != resultVersion {
reviewSessionFailure(w, "review_context_changed")
return
}
next.ExpiresAt = time.Now().UTC().Add(reviewSessionLifetime).Format(time.RFC3339Nano)
case "release":
if !mine || old.Generation != input.Generation {
reviewSessionFailure(w, "review_session_lost")
return
}
if old.WriteID != "" {
reviewSessionFailure(w, "review_write_in_progress")
return
}
next.PageID = ""
next.ExpiresAt = ""
}
saved, e := server.store.CompareAndSwapReviewSession(r.Context(), next, old.Revision)
if e != nil {
renderError(w, 500, e)
return
}
if !saved {
continue
}
if _, valid := server.currentReviewItem(r, *item); !valid {
if next.PageID == input.PageID {
next.PageID = ""
next.ExpiresAt = ""
_, _ = server.store.CompareAndSwapReviewSession(r.Context(), next, old.Revision+1)
}
reviewSessionFailure(w, "review_context_changed")
return
}
renderJSON(w, 200, response(next))
return
}
reviewSessionFailure(w, "review_session_lost")
}
// beginReviewWrite is shared by drafts and formal decisions. Once a task has
// enrolled in page control, omitting headers cannot bypass it. A durable busy
// marker prevents takeover between validation and any accepted write effect.
// It deliberately never expires while an outcome is unknown.
func (server *server) beginReviewWrite(w http.ResponseWriter, r *http.Request, item domain.HumanItemRecord) (func(), bool) {
principal, _ := currentPrincipal(r)
page := r.Header.Get("X-Review-Page")
generation, _ := strconv.Atoi(r.Header.Get("X-Review-Generation"))
op := operationFromRequest(r)
for attempt := 0; attempt < 8; attempt++ {
old, err := server.store.GetReviewSession(r.Context(), reviewSessionKey(item))
if err != nil {
renderError(w, 500, err)
return nil, false
}
if old == nil && page == "" {
// Fence first enrollment against a legacy request already in flight.
batch, err := server.store.GetHumanBatch(r.Context(), item.BatchID)
if err != nil {
renderError(w, 500, err)
return nil, false
}
if batch != nil {
stage, _, found := humanStage(batch, item.CurrentStageID)
if found && stage.Kind != domain.HumanStageReview && stage.Kind != domain.HumanStageAcceptance {
return func() {}, true
}
}
resultVersion, err := server.reviewResultVersion(r.Context(), item)
if err != nil {
renderError(w, 500, err)
return nil, false
}
old = &domain.ReviewSession{ID: reviewSessionKey(item), ItemID: item.ID, StageID: item.CurrentStageID, ReviewRound: item.ReviewRound, ResultVersion: resultVersion}
}
legacy := old != nil && !old.Enrolled && page == ""
if old == nil || principal == nil || (!legacy && (old.UserID != principal.User.ID || old.PageID != page || old.Generation != generation || (old.ExpiresAt <= nowISO() && (op == nil || old.WriteID != op.ID)))) {
reviewSessionFailure(w, "review_session_lost")
return nil, false
}
if old.WriteID != "" && (op == nil || old.WriteID != op.ID) {
reviewSessionFailure(w, "review_write_in_progress")
return nil, false
}
next := *old
if legacy {
currentVersion, err := server.reviewResultVersion(r.Context(), item)
if err != nil {
renderError(w, 500, err)
return nil, false
}
next.ResultVersion = currentVersion
}
next.WriteID = domain.NewID("review-write")
if op != nil {
next.WriteID = op.ID
}
saved, err := server.store.CompareAndSwapReviewSession(r.Context(), next, old.Revision)
if err != nil {
renderError(w, 500, err)
return nil, false
}
if !saved {
continue
}
finish := func() { server.finishReviewWrite(next.ID, next.WriteID) }
fresh, valid := server.currentReviewItem(r, item)
if !valid {
finish()
reviewSessionFailure(w, "review_context_changed")
return nil, false
}
currentVersion, err := server.reviewResultVersion(r.Context(), *fresh)
if err != nil || currentVersion != next.ResultVersion {
finish()
reviewSessionFailure(w, "review_context_changed")
return nil, false
}
if op != nil && !strings.HasSuffix(op.Kind, "_draft") {
draft, err := server.loadCurrentReviewDraft(r.Context(), *fresh, principal.User.ID)
if err != nil {
finish()
renderError(w, 500, err)
return nil, false
}
if draft.Version != op.DraftVersion || draft.ResultVersion != op.ResultVersion || (op.Decision == "approved" && len(draft.Problems) > 0) {
finish()
renderJSON(w, 409, map[string]string{"code": "review_draft_conflict", "error": "草稿在提交前发生变化,请重新核对后确认"})
return nil, false
}
}
if op != nil && op.Kind == "quality" {
if err := server.freezeAcceptanceHandling(r.Context(), item, op); err != nil {
finish()
renderJSON(w, 409, map[string]string{"error": err.Error()})
return nil, false
}
}
return finish, true
}
reviewSessionFailure(w, "review_session_lost")
return nil, false
}
func (server *server) finishReviewWrite(key, writeID string) {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if strings.HasPrefix(writeID, "review-operation-") {
op, err := server.store.GetReviewOperation(ctx, writeID)
if err != nil || (op != nil && (op.Status == "prepared" || op.Status == "applying")) {
return
}
}
for i := 0; i < 8; i++ {
current, e := server.store.GetReviewSession(ctx, key)
if e != nil || current == nil || current.WriteID != writeID {
return
}
revision := current.Revision
current.WriteID = ""
ok, e := server.store.CompareAndSwapReviewSession(ctx, *current, revision)
if e != nil || ok {
return
}
}
}