# 부록. 프론트·백엔드 공통 원칙 후보 사용자 결정(2026-11-01): 프론트·백엔드에 공통인 실무 원칙은 `desktop-server-git/design-docs/`에 둔다. 그 위치는 이 repo 밖이라 여기서 쓰지 않는다. 이 매뉴얼을 쓰며 나온 **후보만** 적는다. 옮길 때는 원칙 문장만 옮기고, 이 repo의 장은 그 원칙을 가리키도록 바꾼다(두 벌을 두지 않는다). | # | 후보 원칙 | 이 repo에서 드러난 곳 | 프론트 쪽 짝 | | --- | --- | --- | --- | | 1 | 결과를 증명할 수 없으면 "모른다"로 분류한다. "실패(재시도 가능)"로 적지 않는다 | 05장, `DB_COMPLETION_UNKNOWN`, outbox ambiguous | 요청 분류기의 timeout·네트워크 오류 처리 | | 2 | 같은 요청의 재전송은 같은 멱등성 키로. 새 키는 새 작업이다 | `docs/web/http-contract.md` 2절 | 재시도 정책, 409 in-flight 처리 | | 3 | 중복·경쟁은 저장소의 제약이 막는다. 앞선 조회는 빠른 거절일 뿐이다 | 04장 | 낙관적 UI 갱신과 서버 409 | | 4 | 같은 규칙을 두 곳에 쓰지 않는다. 쓸 수밖에 없으면 하나가 다른 하나를 검사한다 | DTO 검증 vs aggregate(02장), 오류 코드 registry 대조 테스트 | 폼 검증 스키마 vs 서버 검증 | | 5 | 실패는 클라이언트 탓/서버 탓으로 먼저 나누고, 클라이언트에는 안정된 코드만 보낸다 | 06장 | 오류 코드 → 화면 문구 매핑 | | 6 | 권한이 없으면 닫힌 쪽이 기본이다(매핑 전 403, 남의 것은 404) | 07장 | 권한 없는 메뉴·라우트 숨김과 서버 거절 | | 7 | 계약은 버전·schema·해시로 고정하고, 바꾸면 소비자 계약 테스트가 깨진다 | 09장, Envelope wire 테스트 | 응답 스키마 strict 파싱 | | 8 | 포트(경계)마다 대역 하나, 대역과 실제가 같은 계약 테스트를 통과한다 | 08장 | API mock과 실제 서버의 계약 테스트 | | 9 | 선택 기능은 한 줄로 켜고 한 줄로 끈다. 그 기능을 아는 곳은 자기 자신뿐이다 | 10장 | feature flag·라우트 모듈 | | 10 | 위험은 코드에 드러나야 한다: 의도한 제약·생략은 주석과 테스트 이름에 적는다 | 생성 명령 템플릿의 Javadoc(`NOT_IDEMPOTENT` 이유 등) | 같음 | | 11 | 게이트는 지우지 않고 단계를 지정한다(PR / main / nightly) | 08장 lane 단계, `verifyStrictLaneStages` | 프론트 CI 단계 | | 12 | 선택지가 여럿이면 고른 것·버린 것·이유를 남긴다 | 각 장의 「고른 형태와 버린 대안」 | 같음 |