백엔드 주도 런타임 리팩터

백엔드 주도 런타임 리팩터은(는) 무엇을 하나요?

실행 진실이 어디에 살아있고 UI가 그것을 어떻게 읽는지 정확히 말할 수 있을 때만 리팩터링하십시오.

사용 시기

• UI가 백엔드가 이해하지 못하는 그래프, 단계 또는 공급자 선택을 합성합니다.
• 재시작 또는 재연결 시 프론트엔드가 권한을 캐시했기 때문에 보이는 런타임 상태가 변경됩니다.
• 이전 스키마와 새 스키마, 스타터 형식 또는 노드 유형이 활성 작성 경로에 공존합니다.
• 승인, 리뷰 또는 다운스트림 실행이 프론트엔드 전용 재구성에 의존합니다.

사용하지 말아야 할 경우

• 런타임 소유권 변경 없이 시각적 UI만 정리하는 경우.
• 백엔드 계약이 이미 권위적인 경우의 격리된 컴포넌트 리팩터.
• 분할 권한 경계를 삭제하기 전에 새 비즈니스 기능을 출시하는 경우.
• 아키텍처에 이미 하나의 진실 공급원이 있을 때의 순수 백엔드 성능 작업.

의사 결정 포인트

flowchart TD
  A[워크플로우 리팩터 요청] --> B{UI가 여전히 런타임 진실을 만들 수 있습니까?}
  B -->|아니오| C[더 좁은 도메인 또는 UI 스킬 사용]
  B -->|예| D[명령, 쿼리 및 이벤트 경계 인벤토리 작성]
  D --> E{모든 사용자 동작이 명령, 쿼리 또는 이벤트로 매핑됩니까?}
  E -->|아니오| F[기능 작업 전에 계약 동결]
  E -->|예| G[투영 상태를 백엔드 소유 상태에서 분할]
  G --> H{레거시 호환 경로가 여전히 활성화됩니까?}
  H -->|예| I[마이그레이션 가장자리로 이동하거나 삭제]
  H -->|아니오| J[평가자, 재생-안전 시작 쿼리 및 이벤트 구독 추가]
  I --> J
  J --> K[재연결, 승인 및 다운스트림 준비 상태 검증]

먼저 이 라우팅 모델을 사용하십시오:

• UI가 명령 -> 백엔드 전환 -> 쿼리 또는 이벤트 투영으로 설명될 수 없다면, 경계는 여전히 잘못된 것입니다.
• "임시 호환성" 경로가 핫 경로에 있다면, 기능이 아닌 리팩터 부채로 취급하십시오.
• 재시작 또는 재연결이 백엔드 진실만으로 가시 상태를 재구성할 수 없다면, 리팩터는 불완전한 것입니다.

작업 방법

1. 분할 뇌 인벤토리 작성

UI가 다음을 수행하는 모든 곳을 찾으십시오:

• 실행 진실을 생성하거나 변경함
• 백엔드가 알지 못하는 단계를 발명함
• 활성 코드 경로에서 실행을 시뮬레이션함
• 동일한 작성 경로에서 이전 스키마와 새 스키마를 유지함
• 추상 라우팅 계층과 정확한 공급자 ID를 혼합함

2. 계약 동결

세 가지 클래스만 정의하십시오:

• 명령: 시작, 중지, 승인, 재개, 변경
• 쿼리: 시작 상태, 리뷰 페이로드, 실행 스냅샷, 공급자 상태
• 이벤트: 권위적 전환, 평가자 판결, 게이트 상태, 재생 마커

UI 동작이 이 중 하나로 표현될 수 없다면, 아키텍처는 여전히 혼란스러운 것입니다.

3. 상태 소유권 정규화

스토어를 다음으로 분할하십시오:

• 계약 입력 상태
• 백엔드 스냅샷 투영 상태
• UI 레이아웃 상태

어떤 스토어도 런타임 진실과 레이아웃 문제를 동시에 소유하게 하지 마십시오.

4. 활성 호환성 경계 삭제

"당분간 둘 다 지원"보다 삭제를 선호하십시오.

일반적인 삭제 대상:

• 활성 작성에서의 단수형 및 복수형 스키마 호환성
• 활성 데스크탑 런타임에서의 브라우저 또는 데모 시뮬레이션
• 주요 경로에서의 더 이상 사용되지 않는 노드 유형
• 중복 리뷰 요약
• 여러 스타터 또는 가져오기 형식

5. 리팩터를 신뢰하기 전에 평가자 추가

모든 구현 노드는 다음을 가져야 합니다:

• 정확성을 위한 로컬 출력 평가자
• 계약 안전성을 위한 다운스트림 준비 평가자
• 백엔드 진실에서 재수화하는 재시작 또는 재연결 경로 (프론트엔드 추측이 아님)

실패 모드

권위로 가장하는 투영

증상: UI가 "읽기 전용"처럼 보이지만 로컬에서 단계, 그래프 또는 공급자 진실을 조용히 조립합니다.

수정: 해당 로직을 백엔드 명령 또는 쿼리로 이동하고 프론트엔드를 투영기로 취급하십시오.

호환성 경계 석회화

증상: "당분간 둘 다 지원"이 몇 주 동안 핫 경로에 남아 실제 아키텍처가 됩니다.

수정: 호환성을 명시적 삭제 날짜가 있는 단방향 마이그레이션 가장자리로 밀거나 지금 제거하십시오.

검사 불가능한 승인

증상: 사람이 검사할 수 없는 작업을 승인할 수 있습니다. 리뷰 페이로드가 부분적이거나 프론트엔드에서 합성되었기 때문입니다.

수정: 백엔드가 정확한 리뷰 페이로드를 방출해야 합니다. UI는 렌더링만 수행합니다.

재생에 적대적인 시작

증상: 앱을 다시 시작하면 프론트엔드가 권한을 캐시했기 때문에 가시 상태가 변경되거나 게이트 위치가 손실됩니다.

수정: 시작은 스토어 재구성이 아닌, 백엔드 진실에 대한 쿼리와 이벤트 재생이어야 합니다.

시볼레스

앱을 다시 시작할 때 새로운 백엔드 이벤트 없이 가시 런타임 상태가 변경된다면, 권한은 여전히 분할된 것입니다.

작업 예제

프론트엔드 소유 단계 로직이 있는 Tauri 워크플로우 편집기

문제:

• React 스토어가 그래프를 작성하고, 단계 상태를 추론하며, 공급자 계층을 정규화했습니다.
• 백엔드 실행은 다른 계약을 사용했기 때문에 리뷰와 재시작 흐름이 표류했습니다.

리팩터 경로:

1. UI가 실행 진실을 발명한 모든 곳을 인벤토리하십시오.
2. 런타임 상호작용을 명령, 쿼리 및 이벤트로 축소하십시오.
3. 공급자 정규화와 단계 전환을 백엔드 명령 뒤로 이동하십시오.
4. 활성 작성 경로에서 스타터 형식 결합을 삭제하십시오.
5. 평가자 게이트를 추가하여 다운스트림 작업이 백엔드 검증된 출력에서만 진행되도록 하십시오.

성공 조건:

• 재시작 시 UI가 백엔드 스냅샷과 이벤트에서 동일한 가시 상태를 재구성합니다.
• 승인 화면이 React 재구성이 아닌 백엔드가 방출한 리뷰 페이로드를 렌더링합니다.

포크 지침

작업이 깔끔하게 분리될 때 포크하십시오:

• 계약 레인: 분할 권한 경계를 인벤토리하고 명령, 쿼리 및 이벤트를 정의합니다.
• 삭제 레인: 호환성 계층, 더 이상 사용되지 않는 노드 유형 및 스타터 형식 결합을 제거합니다.
• 검증 레인: 평가자 게이트, 재생 테스트 및 재시작 또는 재연결 커버리지를 추가합니다.

최종 소유권 결정은 상위 레인에 두어 한 명의 행위자가 백엔드가 실제로 무엇을 소유할지 결정하도록 하십시오.

품질 게이트

• UI가 로컬에서 그래프, 단계, 공급자 또는 게이트 진실을 조작할 수 없습니다.
• 모든 사용자 동작이 명령, 쿼리 또는 이벤트로 매핑됩니다.
• 런타임 상태가 백엔드 진실만으로 재시작 및 재연결을 견딥니다.
• 리뷰 및 승인 페이로드가 백엔드에서 방출되고 UI에서 렌더링됩니다.
• 호환성 로직이 활성 경로가 아닌 마이그레이션 가장자리에만 존재합니다.
• 다운스트림 실행이 업스트림 계약 실패 시 중지됩니다.
• 정확한 공급자 ID 및 모델 선택이 계약 경계에서 보입니다.
• 테스트가 재시작, 재연결, 승인 및 평가자 실패 경로를 다룹니다.

참조 맵

• references/architecture-patterns.md — 백엔드 소유 워크플로우 계약 패턴 및 상태 소유권 분할.
• references/windags-lessons.md — 실제 분할 권한 런타임 마이그레이션에서 얻은 구체적인 교훈.