생성 워크플로 앱에서 OpenAPI로 백엔드와 프런트엔드를 맞추기

## 백엔드 API를 바꿀 때마다 OpenAPI 타입과 클라이언트 다시 생성하기 백엔드 API를 변경할 때마다 저장소의 OpenAPI 업데이트 명령을 실행한다. 생성된 스키마와 프런트엔드 타입을 나중에 정리할 항목이 아니라 같은 변경의 일부로 취급한다. 프런트엔드 코드는 생성된 OpenAPI 클라이언트를 통해 백엔드 엔드포인트를 호출해야 한다. 생성된 요청 및 응답 계약을 중복하는 수기 작성 service 래퍼를 추가하지 않는다. 백엔드의 책임을 엄격하게 구분한다. - API 계층은 입력 구문 분석, 인증과 권한 부여, 응답 구성을 담당한다. - service 계층은 비즈니스 규칙, 상태 전이, 데이터 조정을 담당한다. 입출력 DTO와 공급자 구성을 포함한 계층 간 생성 계약은 공유 contracts 모듈에 둔다. task 모듈에는 작업 래핑, 배분, 실행 조정만 두고 공유 DTO 정의는 두지 않는다. integration 모듈은 공유 contracts에 의존할 수 있지만 task 내부 타입 모듈에는 의존해서는 안 된다. API, 타입, 상태 모델이 변경되면 백엔드 구현, OpenAPI 문서, 생성된 프런트엔드 타입, 클라이언트 사용부, 직접 관련된 문서를 함께 업데이트한다. ## 함수마다 주석을 달고 현재 사실과 앞으로의 계획을 다른 문서로 나누기 프런트엔드 스타일이 두 번 이상 반복되면 또 복사하기보다 재사용 가능한 컴포넌트나 공유 스타일 구조를 우선한다. 모든 함수, 클래스 또는 이에 준하는 코드 블록에는 무엇을 하는지와 왜 존재하는지를 설명하는 주석이 필요하다. 복잡한 로직은 관련 매개변수, 반환 동작, 핵심 내부 결정도 문서화해야 한다. 주석을 구현과 동기화한다. 문서를 작성하기 전에 분류한다. - `guide`는 작업 수행 방법이나 기능 통합 방법을 설명한다. - `architecture`는 현재 구현된 시스템을 기록한다. - `plans`는 향후 작업, 단계별 과제, 변경 제안을 기록한다. - `reference`는 조회할 수 있는 안정적인 사실을 담는다. - `blog`는 릴리스 노트를 담는다. 현재 경계, 구현된 상태 전이, 실제 동작은 architecture 문서에 둔다. 아직 설계 중이거나 진행 중인 작업은 plans에 둔다. 운영 절차와 개발 워크플로는 guide에 둔다. 현재 사실과 향후 의도를 하나의 사용법 문서에 섞지 않는다. 같은 주제를 다루더라도 architecture와 plans로 나눈다. 작업에서 명시적으로 요구하지 않는 한 확정된 과거 릴리스 노트를 수정하지 않는다. ## 작업 센터는 가볍게 두고 워크플로 화면마다 역할 나누기 주요 사용자 워크플로를 책임이 명확한 화면으로 분리한다. - 준비 페이지는 도메인 데이터를 추출하고 후보를 확인하며 기본 정보를 수정한 뒤 항목을 `ready`로 전환한다. - 생성 작업공간은 출력 준비도를 확인하고 핵심 자산과 매개변수를 관리하며 생성을 시작하고 결과를 제시한다. - 작업 센터는 상태, 진행률, 성공, 실패, 취소, 돌아가기 링크처럼 가볍고 일반적인 작업 정보만 표시한다. 도메인별 요약, 프롬프트 디버깅 맥락, 자산 매핑 또는 다른 상세 정보를 일반 작업 센터에 두지 않는다. 관련 준비, 생성, 실행 또는 진단 패널에 유지한다. 추출 도구를 생성 작업공간에 남겨 두는 경우 바로가기나 진단 수단으로만 제공한다. 주요 확인 화면인 준비 페이지를 대체해서는 안 된다. 책임 경계가 변경되면 관련 UI와 architecture 문서를 모두 업데이트한다. 작업 센터를 재설계하더라도 새로운 비즈니스 상세 페이지로 만들어서는 안 된다. ## 항목 상태는 정보 확인에만 쓰고 생성 진행에는 쓰지 않기 도메인 항목의 기본 상태는 정보 확인 상태에만 사용한다. - `pending`은 추출 또는 확인 작업이 남아 있음을 의미한다. - `ready`는 필수 정보 확인이 끝나 후속 준비를 시작할 수 있음을 의미한다. 이 상태를 런타임 생성 상태에 사용하지 않는다. `generating` 같은 값은 작업 시스템과 런타임 요약에 속한다. 출력 준비도는 별도의 차원으로 표현한다. 항목이 후속 준비에 대해 `ready`라고 해서 생성에 필요한 모든 조건을 충족한다고 보장되지는 않는다. 모든 사용자 인터페이스는 다음을 구분해야 한다. 1. 정보 확인 상태. 2. 런타임 작업 상태. 3. 출력 생성 준비도. 상태 의미가 변경되면 백엔드 동작, OpenAPI, 생성된 프런트엔드 타입, 상태 레이블, 탐색 조건, 개발 문서를 동기화한다. ## 준비 페이지에서 확인한 뒤 생성 작업공간으로 안내하기 표준 흐름은 다음과 같다. 1. 소스 콘텐츠에서 작업 항목을 추출한다. 2. 준비 페이지에서 추출된 자산, 대화 또는 기타 필수 정보를 확인하고 수정한다. 3. 생성 작업공간으로 이동해 핵심 자산, 참조 자료, 출력 매개변수, 준비도를 확인한다. 4. 생성 작업공간에서 생성을 시작한다. 5. 도메인 작업공간에서 결과를 확인하고 작업 센터는 일반적인 작업 진행 상황 확인에만 사용한다. 준비 페이지는 추출, 확인, 수정을 담당한다. 생성 작업공간은 생성 준비, 실행, 결과 검토를 담당한다. 준비가 성공하면 사용자를 생성 작업공간으로 명확히 안내한다. 작업공간에서 항목이 `ready`가 아니라고 판단되면 명확한 설명과 함께 사용자를 준비 단계로 돌려보낸다. 상호작용을 변경할 때 이 흐름을 우선한다. 편의를 위한 바로가기가 정식 다음 단계를 가리거나 준비와 생성을 하나의 모호한 화면으로 합쳐서는 안 된다. ## 변경할 때마다 architecture 문서를 고치고 릴리스 노트에 바로 쓸 수 있는 이전 절차 쓰기 architecture 문서에는 현재 실제로 유효한 동작만 포함한다. plans에는 진행 중인 작업, 단계별 과제, 우선순위, 향후 실행 경로를 포함한다. 코드 동작, 상태 의미, 페이지 책임이 변경되면 같은 작업에서 architecture 문서를 업데이트한다. 계획의 범위, 우선순위, 순서가 변경되면 plans를 업데이트한다. 구현이 끝난 계획은 architecture로 옮기거나 릴리스 노트로 만든다. 오래된 architecture 또는 plans 문서가 남아 있으면 해당 작업을 미완료로 간주한다. 릴리스 노트에는 `title`, `date`, `description`, `tags`, `authors`의 frontmatter가 있어야 한다. 해당하지 않는 절만 생략하고 다음과 같은 안정적인 순서를 사용한다. 1. 주요 내용. 2. 추가, 변경, 수정. 3. 호환성을 깨는 변경과 지원 중단. 4. 보안과 알려진 문제. 5. 마이그레이션 안내와 되돌리기 지침. 6. 호환성 표, 검증 명령, 업그레이드 점검표. 7. 참고 자료, 기여자 안내, 감사의 말. 릴리스 노트는 유지관리자 관점으로 작성한다. 결론과 실행 가능한 정보를 먼저 제시하고, 짧은 문단과 목록을 사용하며, 용어를 일관되게 유지한다. 새로운 기능, 동작 변경, 호환성 위험, 알려진 문제를 명확히 구분한다. 마이그레이션 단계, 되돌리기 단계, 검증 명령은 모호하지 않고 그대로 사용할 수 있어야 한다. ## 생성된 타입과 문서가 코드와 맞을 때만 완료하기 적용되는 모든 조건을 충족한 경우에만 작업이 완료된다. 1. 구현이 존재하며 명백한 임시 자리표시자나 더 이상 필요 없는 호환성 코드가 남아 있지 않다. 2. 새 함수와 클래스 및 변경된 함수와 클래스에 정확하고 유용한 주석이 있다. 3. API 변경에 맞춰 OpenAPI, 생성된 프런트엔드 타입, 생성된 클라이언트 사용부가 업데이트되었다. 4. 현재 동작은 architecture 문서에, 향후 작업은 plans에 반영되었다. 5. 준비, 생성, 작업 센터의 책임이 계속 분리되어 있다. 6. 프런트엔드 변경이 저장소의 TypeScript 무출력 검사를 통과한다. 7. 백엔드 변경이 관련 테스트 또는 최소한 문서화된 구문 및 import 검사를 통과한다. 8. 완료 보고서에 변경 내용과 통과한 검증 결과가 명시되어 있다. 9. 남은 작업이나 후속 권고 사항이 별도로 나열되어 있다. 코드, 계약, 생성된 타입, 문서, 상태 의미 또는 워크플로 화면이 서로 일치하지 않는 동안에는 완료를 선언하지 않는다.