UI가 임시 상태를 적용하고, 서버의 진실과 조정하며, 충돌 또는 실패 시 롤백하고, 사용자가 오래된 낙관적 데이터를 조용히 신뢰하지 않도록 내구성 있는 증거를 표시하는 방식을 명세합니다.
패키지 상태: AI 지원 참조 패키지. 정적 패키지 검증은 통과했으나, 구현 시나리오는 실행되지 않았으며 안정적 도입 전 인간 도메인 검토가 필요합니다.
결정 사항
응답성 있는 변이(mutation)에 대해 낙관적 UI 업데이트를 적용하되, 서버 응답을 권위 있는 것으로 처리합니다. 모든 낙관적 변경은 클라이언트 변이 식별자를 가지며, 복원 가능한 스냅샷을 보존하고, 성공, 롤백, 충돌 또는 불확실한 타임아웃 상태로 명시적 사용자 피드백과 함께 조정됩니다.
범위
- 임시 적용 규칙, 대기 표시기, 스냅샷 저장.
- 성공, 실패, 충돌, 타임아웃 시 조정.
- 서버 멱등성과 일치하는 클라이언트 변이 식별자를 사용한 멱등 재시도.
- 적용, 성공, 롤백, 충돌 비율에 대한 텔레메트리.
이 블록에 포함되지 않는 항목
- 오프라인 큐 지속성 (오프라인 변이 큐 블록 참조).
- 서버 측 낙관적 잠금 스키마 (낙관적 잠금 블록 참조).
- 일반 폼 검증 UX.
계약
- 낙관적 적용은 클라이언트 계약에서 명시적으로 낙관적이라 표시된 변이에만 발생하며, 읽기 경로는 절대 낙관적으로 조작되지 않습니다.
- 각 변이는 안정적인 클라이언트 변이 ID를 생성하며, 최종 조정 시점까지 모든 재시도에 전송됩니다.
- UI는 적용 전에 롤백 스냅샷을 저장하며, 실패한 조정은 스냅샷 필드를 정확히 복원합니다.
- 서버 충돌(프로필 선택: HTTP 409)은 동시 로컬 편집을 조용히 덮어쓰지 않는 충돌 UX 경로를 트리거합니다.
- 프로필 타임아웃을 초과하는 조정은 불확실 상태에 들어가며, 무기한 대기 대신 ID별 조회(fetch-by-id) 또는 폴링으로 해결됩니다.
- 성공적인 조정은 대기 상태를 해제하고, 엔티티 버전 메타데이터를 포함한 서버 값을 표시 필드로 교체합니다.
구현 지침
- 낙관적 변이 미들웨어를 중앙 집중화하여 모든 기능이 조정 의미론을 공유하도록 합니다.
- 서버가 지원하는 경우 클라이언트 변이 ID를 API 멱등 키와 일치시킵니다.
- 정책이 요구하지 않는 한 전체 뷰를 차단하지 말고 미묘한 대기 표시를 사용합니다.
example.yaml에 나열된 텔레메트리 이벤트를 발행하여 작업을 검토합니다.
실패 처리 및 안전장치
- 중복 성공 응답은 UI 상태 머신에서 부작용을 중복 적용하지 않아야 합니다.
- 미확정 임시 ID에 의존하는 낙관적 변이를 연쇄하지 말고, 의존 변이는 선행 변이 조정 완료를 기다리거나 안정적인 서버 ID를 참조합니다.
- 충돌 시 편집 손실을 방지하기 위해 맹목적 재시도보다 서버 차이(diff)를 보여주는 것을 선호합니다.
검증 및 운영
- 변이 유형별 롤백 비율, 충돌 비율, 불확실 타임아웃 비율을 모니터링합니다.
- 자동화 테스트는 성공, 실패, 충돌, 타임아웃, 멱등 재시도 경로를 포함합니다.
- 롤백 비율이 높은 변이는 서버 또는 검증 문제를 검토합니다.
이 패키지 내 실행 가능한 예제들은 픽스처 및 수용 계약입니다. 도입 전 패키지 구조를 검증하고, 대상 저장소에서 시나리오를 구현 및 실행하세요.
도입 가정
example.yaml의 타임아웃, 상태 코드, 헤더 이름은 작업 보드 SPA를 위한 프로필 선택이며 보편적 기본값이 아닙니다.- 팀은 엔티티 버전 필드를 API 스키마에 매핑해야 합니다.
참고 문헌
- 외부 규범적 출처는 필요 없으며, 도입 시 API 멱등 블록과 멱등 동작을 일치시키세요.