Files
sodalive-backend-spring-boot/docs/20261117_관리자번역후보선택/frontend-implementation-prompt.md
T

32 KiB

관리자 번역 후보 선택 프론트엔드 구현 지시

별도 프론트엔드 저장소에서 이 기능을 실제로 구현하라. 이 파일, 사용자가 별도로 제공하는 API 계약 파일, 그리고 네가 작업하는 프론트엔드 저장소만 근거로 삼는다. 제공된 API 계약 외의 백엔드 저장소 PRD·계획·검증 기록·소스, 다른 컴퓨터의 절대 경로, 이전 대화나 숨은 세션 지식에 의존하지 않는다. 아래 지시로 프론트엔드 저장소 안에 새로 만드는 문서는 이후 작업의 기준으로 사용한다. API 계약이 없으면 파일 위치만 물어보고 네트워크 계약을 추측하지 않는다. 계약과 아래 제품 요구가 충돌하면 충돌한 항목만 구체적으로 기록하고 해당 작업을 멈춘 뒤 질문한다.

1. 목표와 경계

  • 관리자 콘텐츠 상세와 시리즈 상세에 각각 진입 버튼을 두고, 하나의 공유 요청 생성·검토·후보 선택 workflow를 구현한다.
  • 기존 프론트엔드의 접근성, 라우팅, API client, 캐시, 상태 관리, 디자인 구성요소, 테스트 관례를 재사용한다. 새 의존성 및 무관한 리팩터링은 피한다.
  • 일반 관리자 화면에서 동작하는 완성 기능을 만든다. 스텁, 빈 동작, 가짜 성공, 운영용 mock fallback은 허용하지 않는다.
  • 서버 API는 ADMIN 전용이며 별도 feature flag 없이 배포된 애플리케이션 기동 시 등록된다. 프론트엔드에 서버 기능 활성화 토글이나 설정 단계를 만들지 않는다. 버튼 표시만으로 해당 환경의 배포·연결 준비를 완료했다고 판단하지 않는다.
  • 사용자가 제공하는 API 계약이 endpoint, DTO, envelope, 오류 및 타입의 기준이다. 아래 요약은 사용 흐름과 제품 요구를 자립적으로 전달한다.
  • 서버의 9개 endpoint는 구현됐고 기존 backend 최종 검토에서 승인됐다. 이후 사용자 요청으로 활성화 플래그를 제거했다. 이 기록을 이 저장소의 구현이나 검증 결과로 주장하지 않는다.
  • 운영 DDL 반영과 배포는 완료되지 않았다. 새 writer의 작업 생성 전 세 신규 테이블, 원문 언어 포함 queue unique index, 구 writer·in-flight 작업 종료 및 구 unique index 제거가 필요하다. 자동 DDL이나 별도 활성화 단계는 없다. 이 운영 전제는 백엔드 운영자가 처리하며 프론트엔드에서 실행하지 않는다. 실제 UI와 프론트엔드 구현도 아직 없다.

2. 구현 전 필수 문서와 조사

2.1 저장소 파악

코드를 수정하기 전에 프론트엔드 저장소의 AGENTS.md, README, package/build 설정, 테스트 및 개발 명령을 읽는다. 실제 버튼이 놓일 콘텐츠 상세·시리즈 상세, 기존 API client/envelope/auth, 관리자 role 처리, base URL 환경변수, query/cache 패턴, 번역 언어 및 Unicode 유틸리티, 디자인 구성요소, 테스트 명령을 찾는다. 파일 경로와 명령은 실제 확인한 값만 쓴다.

기존 diff를 먼저 확인해 사용자·다른 작업의 변경과 이번 변경을 구분한다. 자신이 만들지 않은 변경을 덮어쓰거나 되돌리지 않는다.

사용자가 제공한 API 계약 파일을 찾아 읽는다. 파일명이 정해져 있다고 가정하지 않는다. 없다면 구현 전 파일 위치를 요청한다. endpoint나 DTO를 상상해 진행하지 않는다.

2.2 코드 작성 전 문서 다섯 개

실제 프론트엔드 저장소의 기존 문서 규칙을 우선 확인한다. 아래 산출물을 그 규칙을 따르는 한 곳에 만들거나 기존 것을 재사용한다. 기존 규칙이 다른 경로를 요구하면 실제 경로를 사용하고 다섯 문서의 canonical mapping을 한 번 기록한다. 중복 계획을 만들지 않는다.

  1. docs/20261118_관리자번역언어선택/api-contract.md
    • 제공된 계약을 의미 변경 없이 그대로 복사한다. 이미 존재하면 내용과 provenance를 확인해 재사용한다.
    • 사용자 파일을 덮어쓰지 않는다. 원본 경로와 provenance는 progress.md에 기록하고 계약 문서 본문에는 추가하지 않는다.
  2. docs/20261118_관리자번역언어선택/prd.md
    • 이 프롬프트의 제품 요구에서 생성한다. 외부 PRD가 필요하다고 가정하지 않는다.
  3. docs/20261118_관리자번역언어선택/plan-task.md
    • 실제 발견한 프론트엔드 파일 경로, 라우트, 명령을 포함하는 작은 단계와 의존성, acceptance criteria, 증거를 쓴다.
    • 체크박스와 고유 Goal ID를 사용하고 활성 Goal은 하나만 둔다. 각 작업에 정확한 경로, focused 검증과 기대 결과를 적는다.
    • 알 수 없는 값은 placeholder로 채우거나 이미 확인한 것처럼 쓰지 않는다.
  4. docs/20261118_관리자번역언어선택/verification.md
    • 코드 작성 전에 검증 행렬을 만든다. 각 행은 NOT_RUN, BLOCKED, PASS, FAIL 중 하나로 표시하며 기대 assertion, 환경, 명령/증거 경로를 적는다.
    • 기존 API client와 envelope, 인증, 관리자 역할, base URL 환경변수, schema availability, connectivity, Unicode 범위 도구, query/cache, 디자인 요소, 테스트 명령을 사전 조사한다.
    • 사전 connectivity 확인은 안전한 read-only 요청만 사용한다. 유료 provider 요청, 생성·적용·취소 같은 mutation, 배포나 운영 변경을 사전 점검으로 실행하지 않는다. 알려진 테스트 requestId가 없으면 임의 ID나 존재하지 않는 목록 endpoint로 API 준비 완료를 판단하지 않는다.
    • 실제 API 연동 준비가 확인되지 않으면 해당 항목은 BLOCKED로 둔다. UI와 단위 테스트 작업은 계속한다.
    • fixture/mock 테스트와 실제 서버 검증을 별도 행으로 구분한다.
  5. docs/20261118_관리자번역언어선택/progress.md
    • 승인 범위, 확정 결정, 현재 및 다음 Goal, 완료 Goal, 변경 파일, 가정·결정·차단 요소, 스크린샷 경로를 기록한다.
    • 실행한 정확한 명령과 결과, 실제 API 대 fixture 구분을 누적한다. 마지막 requestId는 테스트용만 허용하며 secret은 절대 기록하지 않는다.

다섯 문서가 작성되고 최초 계획 및 검증 기준이 기록될 때까지 production code를 수정하지 않는다. 이후 각 milestone마다 계획 체크박스, progress, verification을 갱신한다. 이미 완료한 목표와 근거는 삭제하거나 과거 PASS를 현재 코드의 증거로 재사용하지 않는다.

장기 작업 재개 시 다섯 문서를 모두 읽고 현재 diff와 테스트 산출물을 확인한다. 실제 evidence에 맞는 첫 미완료 Goal부터 이어가며, 이미 확인된 인터뷰나 완료 작업을 반복하지 않는다. 기존 계획과 사용자 지시가 다르면 사용자 지시가 우선이다. 충돌 우선순위는 사용자 지시, API HTTP 계약, 제품 요구, 실행 계획 순서다. 충돌한 작업만 멈춰 기록한다.

3. API 사용 요약

Base path는 /admin/audio-content/translation-requests다. Endpoint·필드명·타입은 제공된 API 계약을 기준으로 한다. 아래 제품 동작과 실질적인 충돌이 있으면 요구사항을 임의로 바꾸지 말고 해당 항목을 기록해 확인한다.

Method Path 역할
POST / CONTENT 또는 SERIES 요청 생성
GET /{requestId} 상태, revision, progress, receipt 조회
GET /{requestId}/contents snapshot 및 현재 데이터 cursor 조회
GET /{requestId}/grouping 제목 그룹과 template 조회
PUT /{requestId}/grouping 전체 grouping 검토·교체
POST /{requestId}/generate 동결 manifest의 후보 생성 시작
GET /{requestId}/candidates 후보 cursor 조회
POST /{requestId}/apply 선택 subset을 한 번 적용
POST /{requestId}/cancel 미적용 요청 취소, body 없음
  • 모든 호출은 ADMIN 권한을 요구한다. 기존 auth를 쓰고 role이 없으면 버튼을 숨기며 직접 진입도 차단한다. 서버 설정을 변경하지 않는다.
  • 성공 및 business failure는 success, message, data, errorProperty envelope를 사용한다. HTTP 200만으로 성공 처리하지 말고 success도 확인한다.
  • ID는 API의 signed 64-bit numeric Long과 저장소 관례를 따른다. 정밀도를 잃는 JS number 처리를 피하되, 계약/기존 repo가 정한 안전한 직렬화 방식을 사용한다. 임의 string 변환 계약을 만들지 않는다.
  • 생성 body는 clientRequestId: UUID와 scope 합 타입 {type: CONTENT, contentId} 또는 {type: SERIES, seriesId}다.
  • grouping PUT은 expectedRevision, 전체 groups(groupId, memberContentIds, sharedParts의 partId 및 contentId/startCodePoint/endCodePoint occurrences), 전체 individualContentIds를 보낸다.
  • generate body는 {expectedRevision}이다. 최초 요청 body와 revision을 보존한다.
  • apply body는 operationId: UUID, expectedRevision, selections 배열이다. FIELD 선택은 kind: "FIELD", contentId, field: "title" | "detail" | "tags", targetLanguage, candidateId를 가진다. 그룹 선택은 kind: "TITLE_GROUP", groupId, targetLanguage, commonCandidateId와 모든 member의 {contentId, candidateId: 후보 ID 또는 null} residualChoices를 가진다. 이 표기는 타입 요약이며 실제 JSON은 계약에 맞춰 생성한다.
  • 콘텐츠 페이지는 afterContentId, 후보 페이지는 afterCandidateId, 기본 size 50, 최대 100을 사용한다. nextAfter...가 null일 때만 끝이다. 한 페이지를 전체로 간주하지 않는다.
  • 후보 ID는 고정이고 같은 ID의 상태·결과가 갱신된다. READY 진입 때 이미 읽은 페이지를 다시 받아 ID 기준으로 갱신한다. revision, cursor, 요청 ID를 임의로 섞지 않는다.

4. 제품 동작과 상태 흐름

요청 scope는 콘텐츠 하나 또는 생성 시점의 활성 시리즈 구성원 전체다. 비활성 구성원은 제외한다. 필드는 제목, 상세, 태그다. 대상 언어는 ko, en, ja에서 각 콘텐츠의 source language를 제외한다. 요청 본문에서 필드·언어를 골라 서버 작업을 줄이지 않는다.

source language가 이미 있으면 사용하며 프론트에서 재감지·전환하지 않는다. 준비 중에는 기존 번역이 보존된다. 모든 nonblank 필드, 모든 대상 언어, 서버 manifest의 모든 provider에 대해 fresh generation을 수행한다. provider 목록은 동적 manifest를 사용한다. 현재 backend context에 알려진 AWS와 Papago를 하드코딩하거나 둘만 가정하지 않는다. API key를 프론트에 두지 않고 cache flush나 startup blocking을 추가하지 않는다.

요청 상태 전이:

PREPARING -> READY_TO_GENERATE
PREPARING -> REVIEW_REQUIRED (series)
PREPARING -> FAILED | CANCELLED
REVIEW_REQUIRED -> READY_TO_GENERATE | CANCELLED
READY_TO_GENERATE -> GENERATING | CANCELLED
GENERATING -> READY | CANCELLED
READY -> APPLIED | CANCELLED
APPLIED, FAILED, CANCELLED are terminal
  • 요청 생성 시 intent마다 UUID를 한 번 만든다. 생성 POST의 결과가 불확실하고 requestId도 받지 못했다면 같은 UUID와 원래 body로 재시도한다. requestId가 있으면 기존 요청 상태를 조회할 수 있다. UUID 검색이나 생성 receipt 조회 API를 새로 가정하지 않으며 UUID를 자동 교체하지 않는다.
  • PREPARING은 요약 조회를 polling한다. 한 요청당 중복 polling은 금지한다. 1초 간격으로 겹치지 않게 실행하고 unmount, request 변경, terminal 상태에서 멈춘다.
  • 단건은 READY_TO_GENERATE가 되면 명시적인 generate 버튼을 제공한다. 시리즈는 분석 그룹을 조회하고 관리자가 전체 구성을 확인·확정해야 한다. 모두 개별 처리로 분류한 경우도 review PUT이 필수다.
  • 시리즈 grouping은 서버 분석을 그대로 검토·수정한다. 전체 활성 scope를 빠짐없이 한 번씩 그룹 또는 individual에 배치한다. 그룹은 최소 2명, 단일 source language이며 모든 멤버가 정확히 같은 원문 substring을 가져야 한다.
  • 관리자는 그룹, 공통 구간, span을 조정하고 멤버를 individual로 제외하거나 요청을 취소할 수 있다. 고정 EP 정규식, 자체 regroup 알고리즘, 서버 분석을 대체하는 프론트 분석을 만들지 않는다.
  • span은 Unicode code point 기준 0-based start inclusive/end exclusive다. JavaScript UTF-16 offset과 동일하다고 가정하지 않는다. 브라우저 선택 offset은 기존 변환 유틸 또는 지원 target의 Intl.Segmenter 등으로 grapheme 경계를 확인하며, emoji ZWJ와 combining mark를 시험한다. 임의의 오프셋을 제출하지 않는다.
  • 그룹 편집이 저장되면 최신 revision을 쓴다. GENERATING 진입 후 편집은 금지이며, 변경하려면 취소 후 새 요청을 만든다.
  • generate 호출이 불확실하면 같은 원래 expectedRevision과 body를 재전송한다. accepted replay는 최신 revision으로 새 요청처럼 바꾸지 않는다. 현재 새 mutation만 최신 revision을 쓴다.
  • GENERATING은 요약과 필요한 후보 페이지를 polling하며 progress를 표시한다. READY 진입 시 이미 읽은 후보 페이지를 갱신하고 나머지는 필요에 따라 cursor로 읽는다. 모든 후보를 매초 전부 내려받지 않는다. 선택할 그룹의 모든 구성원과 필수 후보를 확보하기 전에는 그 그룹 적용을 허용하지 않는다. polling 중 generate를 다시 보내거나 READY 상태를 자동 적용하지 않는다.
  • READY는 모두 성공했다는 뜻이 아니다. 모든 후보 실패 또는 빈 결과여도 READY일 수 있다. emptyFields는 paid candidate가 없는 명시 상태로 표시한다.
  • 생성 이후 grouping 변경은 안 된다. 재검토가 필요하면 cancel 후 새 요청을 시작한다.

5. 비교, 미리보기와 적용

  • 콘텐츠 snapshot의 제목·상세·태그, source language, 기존 번역, 현재 활성/eligible 여부, source fingerprint 변경 가능성을 보여준다. snapshot 값과 조회 시점 current 값은 구별한다.
  • 후보를 필드, 대상 언어, provider 단위로 비교한다. 원문, 현재 값, AWS/Papago 등 manifest에 포함된 provider 후보를 나란히 확인할 수 있게 한다.
  • 기존 번역 출처는 실제 provenance가 없으면 UNKNOWN으로 표시한다. 기존 값을 provider에 귀속시키지 않는다.
  • 동일 문자열 dedup은 같은 unit과 target language 안에서만 허용한다. 모든 provider ID/version provenance와 실제 selectable candidateId를 보존한다. 다른 unit/언어의 문자열은 합치지 않는다.
  • 선택 가능한 것은 SUCCEEDED 후보뿐이다. pending, running, failed, discarded는 비활성화한다. 값이 같은 provider 결과를 묶어 보여도 선택되는 실제 candidate ID를 분명히 한다.
  • FIELD는 콘텐츠·필드·언어마다 후보 하나를 고른다. grouped title을 FIELD로 우회해 apply하지 않는다.
  • GROUP_COMMON은 group+language 단위 공통 후보 하나를 선택하고 모든 멤버 residual 선택을 완전하게 제공한다. 전부 literal인 멤버는 candidateId null을 사용한다. residual은 멤버마다 다른 provider를 선택할 수 있다.
  • 그룹의 일부 멤버만 적용하는 선택은 불가하다. 일부만 분리하려면 generation 전 grouping에서 제외한다.
  • candidate의 전체 translatedValues 배열을 타입에 맞춰 보존한다. 임의 boolean 조합 상태로 여러 unit 타입을 섞지 않는다.
  • 그룹 제목 미리보기는 API templates.segments의 순서대로 이어 붙인다. LITERAL은 sourceText, SHARED는 선택 공통 후보의 translatedValues[valueIndex], RESIDUAL은 해당 멤버 선택의 같은 인덱스를 쓴다.
  • 미리보기에서 trim, 공백 삽입, 값 대체, 문자열 전체 replace를 하지 않는다. residual 구문 내부 공백을 유지한다. 모든 segments를 연결한 원문 재구성이 정확한지 확인한다.
  • 후보 문자열은 HTML로 해석하지 않고 text로 출력한다. 긴 제목과 큰 body가 잘리지 않게 검토·비교할 수 있어야 한다.
  • 자유 형식 번역 텍스트 편집은 만들지 않는다. 원문 그룹과 spans 편집은 제공한다.
  • apply 전에 선택한 그룹의 전체 구성원과 미선택 필드·언어를 포함해 정확한 영향 범위를 확인시킨다. 그룹 내부의 일부 구성원만 미선택으로 두는 적용은 허용하지 않는다. 확인 화면에 다음 문구를 그대로 표시한다: 선택한 항목만 적용하고 이 요청을 종료합니다. 선택하지 않은 후보는 폐기되며, 해당 필드의 기존 번역은 유지됩니다.
  • apply는 one-shot이며 비어 있지 않은 selections만 보낸다. operationId는 사용자 확정 직전에 UUID로 만든다. 적용 결과가 불확실하면 requestId로 상태·applyReceipt를 조회하거나 원래 operationId·expectedRevision·선택 body 전체를 보존해 재전송한다. polling에서 새 revision을 받았다는 이유로 재시도 body를 바꾸지 않는다. 적용 결과가 불확실한 동안 선택 편집을 잠근다.
  • 성공 후 receipt를 표시하고 request를 닫는다. 생략된 값은 기존 값을 유지한다. 서버가 부분 적용을 원자적으로 처리하며, 성공한 경우에만 해당 콘텐츠/시리즈 query cache를 무효화 또는 재조회한다. 낙관적으로 원본을 덮어쓰지 않는다.
  • 적용 뒤 source 변경 시 해당 필드 보호 해제는 서버가 처리한다. 이를 프론트에서 미리 처리하지 않는다.

6. 취소, 오류와 복구

  • 미적용 상태와 READY에서 취소를 제공한다. APPLIED와 FAILED는 취소하지 않는다.
  • 취소는 요청 취소 확정이지 이미 전송된 provider 비용의 환불이나 외부 요청 중단을 뜻하지 않는다. UI 닫힘을 서버 취소 성공으로 간주하지 않는다.
  • 화면 이탈 시 기존 앱의 unsaved draft 경고 방식을 재사용한다. requestId를 URL에 보존해 기존 요청을 재개할 수 있게 한다. history list API나 서버 draft API를 새로 만들지 않는다.
  • 새로고침 뒤 local 미제출 선택은 사라질 수 있음을 알린다. 기존 저장소 draft 방식이 있다면 재사용한다.
  • 안정 오류는 개별 문구/복구에 매핑한다.
    • REVISION_CONFLICT: 최신 request/grouping을 다시 읽고 사용자 편집을 조용히 덮지 않는다.
    • INVALID_GROUPING, INCOMPLETE_TITLE_GROUP: 입력을 유지하고 수정 가능하게 표시한다.
    • SOURCE_CHANGED, MEMBERSHIP_CHANGED: 이전 후보를 재사용하지 말고 새 요청을 안내한다. 기존 요청은 nonterminal이면 필요 시 취소한다.
    • REQUEST_NOT_READY, REQUEST_CLOSED: 상태를 다시 읽는다.
    • CANDIDATE_NOT_SELECTABLE, IDEMPOTENCY_CONFLICT: 잘못된 후보를 자동 대체하지 않고 원인과 재조회 방법을 알린다.
    • EMPTY_SCOPE, LANGUAGE_DETECTION_FAILED, UNSUPPORTED_SOURCE_LANGUAGE, PREPARATION_INTERRUPTED: 요청 준비 실패를 분명히 표시한다.
  • HTTP 404는 원인을 확정할 수 없다. route 미배포, 네트워크·프록시 경로 또는 base URL·요청 경로를 확인하도록 “API를 사용할 수 없음, 배포·연결 경로 확인 필요”로 표시한다. 기능 OFF 상태나 활성화 설정을 원인으로 안내하지 않는다. fake success/fallback을 만들지 않는다.
  • 실제 서버가 없는 경우 fixture/mock은 테스트나 명시적 개발 모드에만 격리한다. production fallback으로 쓰거나 live integration PASS라고 주장하지 않는다.

7. 검증 계획과 완료 기준

문서 verification.md를 코드 전에 만들고 아래 다섯 그룹의 예상 assertion을 실제 도구와 파일 경로에 연결한다. 구현 과정의 각 검증을 실행 즉시 기록한다. 기존 실패는 그대로 보고하며 테스트를 삭제·skip·약화하지 않는다. 기대값만 echo하는 mock 테스트는 근거가 아니다.

  1. Lifecycle, idempotency, polling, cancel
    • 두 scope 생성, 상태 전이, 겹치지 않는 polling과 terminal/unmount stop, 동일 UUID/body 재시도, generate replay, 취소 경계를 검증한다.
  2. Grouping, coverage, Unicode, preview
    • scope 완전 분류, 그룹 최소 멤버, source language 동일성, exact shared spans, emoji ZWJ/combining boundary, literal/shared/residual 연결과 내부 공백을 검증한다.
  3. Field/group selection, partial apply, provenance
    • selectable 상태, 모든 residual 선택, 그룹 원자성, 일부 필드 적용, 미선택 보존 문구, 같은 결과 dedup 후 provenance/candidate ID 보존, UNKNOWN 출처를 검증한다.
  4. Errors, races, unknown outcome, HTTP envelope
    • revision conflict 후 refresh, source/membership 변경, incomplete grouping, HTTP 200 business failure, 네트워크 불확실 retry, apply 잠금, 404 API unavailable 상태를 검증한다.
  5. 기존 UI 회귀, 접근성, 화면 크기
    • 상세/시리즈 기존 동작, role guard와 직접 라우트, keyboard/focus, text escaping, 긴 제목 및 큰 body, responsive layout을 검증한다.

실제 저장소에서 확인한 focused test, lint, typecheck, build 명령만 실행한다. 무필터 전체 테스트와 범위 밖 전체 빌드는 프로젝트 규칙이 허용하지 않으면 실행하지 않는다. 테스트 fixture 검증은 fixture로 표기한다. 실제 API E2E는 안전하고 승인된 비운영 테스트 환경과 식별 가능한 fixture가 있을 때만 수행한다. 운영 예시 ID를 넣거나 유료/운영 mutation을 하지 않는다. 환경이 없으면 순수 UI와 unit 작업은 진행하고 실제 연동을 BLOCKED 또는 미검증으로 남긴다.

UI가 변경되면 실제 구현 화면을 desktop과 mobile에서 열어 확인하고 스크린샷 경로를 기록한다. 빈 화면, 겹침, 잘림, 읽기 어려운 상태를 확인한다. 자동 테스트만으로 수동 화면 evidence를 대신하지 않는다.

완료는 동작 구현, 다섯 문서 갱신, 실제로 실행한 focused 검증 기록, 실제 화면 검토 및 남은 제한 보고를 모두 충족해야 한다. API 미연동을 성공으로 표현하지 않는다. 보고에는 수정 파일, 정확한 명령과 결과, fixture 대 실제 API 구분, 미검증 환경, 남은 blocker와 스크린샷 경로를 포함한다. commit, deploy, 운영 변경은 별도 명시 승인 없이는 하지 않는다.

8. 진행 원칙

  • 먼저 문서와 조사를 완료한 뒤 계획의 첫 Goal을 시작한다. 반복 인터뷰는 저장소나 계약에서 답을 찾을 수 없는 핵심 결정에만 한정하고, 질문도 그 미지수만 묻는다.
  • 완료한 Goal마다 계획, progress, verification을 같은 시점에 갱신한다. 증거가 없는 체크박스나 PASS는 남기지 않는다.
  • 정확한 실제 파일, 명령, 결과만 기록한다. backend 역사적 검증을 frontend evidence로 복사하지 않는다.
  • 이 프롬프트를 또 다른 구현 프롬프트로 바꾸지 않는다. bootstrap 문서를 만들고 그 계획에 따라 실제 frontend 기능을 구현한다.

9. 화면별 acceptance criteria

콘텐츠 상세와 시리즈 상세

  • 두 상세 화면에는 기존 권한 및 버튼 패턴에 맞는 번역 후보 선택 진입점을 둔다.
  • 콘텐츠 진입은 현재 콘텐츠 ID를 CONTENT scope로 전달한다.
  • 시리즈 진입은 series ID를 SERIES scope로 전달한다. 개별 활성 멤버를 프론트에서 수집해 요청 대상을 축소하지 않는다.
  • 하나의 공유 workflow를 열되, 현재 상세 화면의 context와 돌아갈 위치를 잃지 않는다.
  • ADMIN이 아닌 사용자는 기능 버튼을 보지 못하고, URL을 직접 열어도 인증된 기존 접근 거부 흐름을 따른다.
  • 요청 진행 중 같은 요청을 여러 번 생성하는 중복 click을 막는다. 생성의 unknown outcome에서는 기존 UUID를 보존한다.

준비 및 grouping 검토

  • PREPARING 화면은 준비 중임을 표시하고 서버 요약을 재조회한다. 비어 있는 snapshot을 완성 데이터처럼 보여주지 않는다.
  • FAILED에는 API의 failure code를 사람이 이해할 수 있는 상태로 나타내고 재시작은 새 요청을 통해서만 한다.
  • 시리즈 REVIEW_REQUIRED에서 모든 snapshot 멤버를 식별하고, 그룹/개별 배정이 전체 scope를 덮는지 사용자에게 보여준다.
  • 그룹 멤버, 원문 제목, 공통 span, residual과 literal 분할을 검토할 수 있어야 한다.
  • 편집은 원문 구간 선택에 한정한다. 번역문을 직접 편집하는 입력창은 두지 않는다.
  • span을 제출하기 직전에 code point start/end, nonempty substring, grapheme 경계, 각 멤버의 substring 동등성을 확인한다.
  • 저장 중에는 중복 PUT을 막고 저장 결과의 최신 revision을 사용한다. 충돌이면 서버 최신 grouping을 읽되 사용자 변경을 자동 폐기하지 않는다.
  • 검토 완료 버튼은 전체 coverage가 유효할 때만 활성화한다. 모든 individual 구성도 서버에 review PUT을 보내야 한다.
  • group과 개별 처리의 제외는 서버에 저장된 후에만 확정 표시한다.

후보 생성 및 비교

  • READY_TO_GENERATE에서는 시작 전 scope, 필드, source/target language, 동적 provider manifest를 간단히 요약한다.
  • generate 전송 이후 버튼을 잠그고, progress total, terminal, succeeded, failed를 서버 응답 기준으로 표시한다.
  • GENERATING과 READY 간 경합에서도 상태를 최신화한다. 늦게 도착한 이전 polling 응답이 새 상태를 덮지 않도록 request identity를 확인한다.
  • cursor pagination은 반복 cursor 및 중복 응답에서도 ID 기준 병합으로 안정적이어야 한다. 페이지 로드 실패를 전체 결과 완료로 표시하지 않는다.
  • 후보 실패는 다른 provider의 성공을 숨기거나 대체하지 않는다. provider/version과 실패 상태를 알 수 있는 곳에 둔다.
  • 같은 텍스트 결과를 묶었을 때 선택은 정확한 성공 candidate ID 하나에 연결되어야 하며, 출처 표시는 모든 동등 candidate를 포함한다.
  • emptyFields와 literal-only residual에는 후보 선택을 요구하지 않는다. 빈 후보를 성공 상태로 만들어 apply할 수 있게 하지 않는다.
  • 후보 페이지를 다시 읽을 때 현재 선택 candidate가 더 이상 selectable이 아니면 선택을 해제하고 사용자에게 알린다.

적용 확인, receipt와 종료

  • 선택 누락, 중복, 다른 언어/단위의 후보 ID는 프론트에서 제출하지 않는다. 서버 검증을 대신한다고 가정하지도 않는다.
  • grouped title 미리보기는 각 그룹 멤버의 template마다 개별적으로 재구성한다. 공통 결과 하나를 모든 전체 제목으로 대체하지 않는다.
  • 적용 요약은 선택된 콘텐츠·필드·언어, 공통 그룹 전체 멤버, residual source, provider provenance를 구분한다.
  • 미선택 필드가 유지됨과 선택하지 않은 후보가 폐기됨을 확인 단계에서 함께 알린다.
  • 확인 취소는 API 호출을 보내지 않고, 확인 후에는 operation ID 및 canonical body를 고정해 한 번 전송한다.
  • 적용 실패 시 서버가 실패를 반환하면 현재 request 상태와 선택을 유지할 수 있는지 계약에 따라 처리한다. 이미 적용된 receipt를 실패로 표시하지 않는다.
  • apply 응답의 immutable receipt를 보여주고, 재조회 시에도 같은 결과를 표시한다. receipt의 applied fields와 provider source를 candidate 페이지가 바뀌어도 잃지 않는다.
  • 성공 이후 영향받은 content 및 series 화면의 기존 query cache만 갱신한다. 실패나 unknown outcome에서 기존 데이터를 낙관적으로 변경하지 않는다.
  • 취소 요청은 서버 응답 전까지 취소 완료로 표시하지 않는다. 취소 전에 전송 승인을 받은 provider 호출은 계속될 수 있고 이미 발생한 비용을 되돌리지 못함을 사용자에게 설명한다.

10. 문서와 검증 기록 형식

plan-task.md에는 저장소가 지원하는 형식을 따르되 실제 이 구현을 재개할 수 있는 정보를 남긴다.

  • 상단에 현재 상태, 현재 활성 Goal, 다음 Goal을 기록한다.
  • 각 Phase에는 결과와 선행 의존성을 기록한다.
  • 각 Task에는 고유 ID, 목적, 시작 조건, 완료 증거, 범위 밖, 실제 파일 경로, 테스트 우선 절차와 focused 명령을 적는다.
  • 테스트 가능한 작업은 실패하는 assertion부터 작성하고 실패를 확인한 후 최소 구현, 통과 확인과 회귀를 기록한다.
  • 테스트가 불가능한 작업에는 구체적인 사유와 대체 증거를 적는다.
  • 하나의 Task 또는 Gate Goal만 active로 둔다. 성공한 Goal은 즉시 체크하고 그 Goal의 검증 결과를 progress에도 남긴다.
  • 전체 사용자 테스트를 실행하지 않았다면 결과처럼 기록하지 않는다. 프로젝트가 지정한 사용자 실행 명령과 범위를 구분해 둔다.

verification.md의 초기 표에는 적어도 다음 열을 둔다.

검증 대상 기대 assertion 환경·fixture 실제 명령 또는 수동 절차 상태 증거
문서 bootstrap 다섯 문서와 실제 경로가 확인됨 local repo 확인 후 입력 NOT_RUN 경로
API 준비도 auth, base URL, route/schema 사전조건을 안전하게 확인 read-only 실제 확인 명령 NOT_RUN 또는 BLOCKED 결과
lifecycle 및 retry 상태·UUID·revision 불변 fixture 또는 승인된 test API 명시 focused test NOT_RUN 결과 파일
grouping 및 Unicode coverage, span, grapheme, preview 일치 fixture 명시 focused test NOT_RUN 결과 파일
apply와 provenance 부분 적용 및 source 보존 fixture 또는 승인된 test API 명시 focused test NOT_RUN 결과 파일
오류와 UI 회귀 envelope, 오류, role, keyboard, layout fixture/local UI 실제 명령·화면 확인 NOT_RUN 결과 및 screenshot
live API 통합 실제 서버가 있다면 read-only/승인된 test scope에서 확인 환경 이름과 fixture 정확한 요청 경로 BLOCKED 또는 NOT_RUN 결과

표의 행을 모두 실제 환경에 맞게 구체화한다. 행 예시는 완료 증거가 아니다. PASS는 assertion 또는 수동 관찰 evidence가 있을 때만 쓴다. FAIL은 문제와 재현 절차를 남기고 수정 전 기록을 보존한다. BLOCKED에는 무엇이 없어서 막혔는지 쓴다.

progress.md는 실행 가능한 재개 노트로 작성한다.

  • 승인된 범위와 현재 단계, 다음 단계, 활성 Goal을 먼저 보여준다.
  • 확정 제품 결정과 API 계약 의존성을 간결하게 적는다.
  • 완료 Goal별 실제 수정 파일과 검증 결과를 연결한다.
  • 각 명령은 정확한 working directory와 결과/종료 상태를 기록한다.
  • fixture 테스트와 live API 검증을 구분하고, 미실행 검증을 표시한다.
  • 미해결 blocker, 가정, 사용자 질문과 답, 스크린샷 경로를 누적한다.
  • requestId 기록이 필요한 경우 테스트 식별자만 쓰고 토큰, cookie, authorization header, API key, 개인정보를 기록하지 않는다.

11. 구현 완료 보고 형식

작업 종료 시 사용자에게 결과를 한국어로 짧게 보고한다. 코드 완료와 문서 완료를 구분하고 아래 정보를 빠뜨리지 않는다.

  1. 구현된 동작과 주요 진입 경로.
  2. 변경 파일 목록과 다섯 문서의 실제 위치.
  3. 실제 실행한 focused test, lint, typecheck, build 명령 및 각 결과.
  4. fixture/mock 검증과 실제 API 검증의 구분. 운영이 아닌 실제 서버 확인이 없으면 미검증으로 표시.
  5. 화면 확인의 desktop/mobile 범위와 스크린샷 경로.
  6. 남은 blocker, 환경 제약, 실제로 실행하지 않은 검증.

미완료 항목을 완료로 포장하지 않는다. 전체 검증이 불가능하더라도 안전하게 분리 가능한 UI와 테스트 구현을 마치고, 미검증 범위를 명시한다. backend 과거 검증 숫자나 리뷰 승인 문구를 frontend 성공 증거로 재사용하지 않는다.