149 lines
5.8 KiB
Markdown
Executable File
149 lines
5.8 KiB
Markdown
Executable File
# Plan 자동화와 구현 방식
|
|
|
|
## 목적
|
|
|
|
Plan 자동화 기능의 데이터 구조, API 연동 방식, release 검수 연계 방식을 정리합니다.
|
|
|
|
현재 문서는 자동화 브랜치 전략 자체를 고정 규칙으로 설명하지 않습니다. 자동화 처리 방식은 실제 서버 설정, 요청 문맥, 현재 운영 규칙을 함께 확인해 판단합니다. 반면 `Codex Live`나 일반 수동 요청은 로컬 작업본 기준으로 처리합니다.
|
|
|
|
## 구현 위치
|
|
|
|
- 화면 진입: `src/app/main/MainContent.tsx`
|
|
- 메뉴/라우팅: `src/app/main/routes.tsx`
|
|
- 메인 보드: `src/features/planBoard/PlanBoardPage.tsx`
|
|
- release 검수: `src/features/planBoard/ReleaseReviewPage.tsx`
|
|
- 스케줄: `src/features/planBoard/PlanSchedulePage.tsx`
|
|
- 차트: `src/features/planBoard/charts.tsx`
|
|
- API 클라이언트: `src/features/planBoard/api.ts`
|
|
- 빠른 필터: `src/features/planBoard/quickFilters.ts`
|
|
- 메모 마스킹: `src/features/planBoard/noteMasking.ts`
|
|
|
|
## 데이터 모델
|
|
|
|
핵심 타입은 `src/features/planBoard/types.ts`에 있습니다.
|
|
|
|
- `PlanItem`: 보드의 기본 작업 항목
|
|
- `PlanDraft`: 생성/수정용 초안
|
|
- `PlanIssueHistory`: 이슈 이력
|
|
- `PlanActionHistory`: 조치 이력
|
|
- `PlanSourceWorkHistory`: 브랜치, diff, preview, 파일 스냅샷 등 소스 작업 증적
|
|
- `PlanReleaseReview`: release 검수 상태와 메타데이터
|
|
- `PlanReleaseReviewBoardItem`: 검수 화면용 합성 모델
|
|
|
|
자동화 유형 값은 다음 기준으로 사용합니다.
|
|
|
|
- `plan`: Markdown 스타일 Plan 문서 등록 및 접수용
|
|
- `auto_worker`: 실제 Codex 자동 작업 실행용
|
|
- `command_execution`, `non_source_work`: 기존 실행 분류 유지
|
|
|
|
기존 저장값인 `plan_registration`, `general_development`는 서버에서 각각 `plan`, `auto_worker`로 정규화합니다.
|
|
|
|
## API 연동 방식
|
|
|
|
기본 API 베이스 URL 규칙:
|
|
|
|
- `VITE_WORK_SERVER_URL`이 있으면 그 값을 사용
|
|
- 없으면 `/api` 사용
|
|
- `/api`가 실패하면 브라우저 origin 기준 `3100/api`로 fallback 재시도
|
|
|
|
요청 공통 규칙:
|
|
|
|
- GET은 기본 `no-store`
|
|
- 타임아웃 8초
|
|
- 등록된 토큰이 있으면 `X-Access-Token` 헤더 추가
|
|
- 클라이언트 식별 헤더는 `appendClientIdHeader`로 추가
|
|
|
|
## 주요 엔드포인트
|
|
|
|
- `POST /plan/setup`: 초기 테이블/구성 준비
|
|
- `GET /plan/items`: Plan 목록 조회
|
|
- `POST /plan/items`: Plan 등록
|
|
- `PATCH /plan/items/:id`: Plan 수정
|
|
- `DELETE /plan/items/:id`: Plan 삭제
|
|
- `POST /plan/items/:id/actions/:action`: 상태 전이/재처리 액션
|
|
- `GET /plan/items/:id/issues`: 이슈 이력
|
|
- `POST /plan/items/:id/issues/action`: 이슈 조치
|
|
- `GET /plan/items/:id/actions`: 조치 이력
|
|
- `POST /plan/items/:id/actions/note`: 추가 조치 메모
|
|
- `GET /plan/items/:id/source-works`: 소스 작업 이력
|
|
- `GET /plan/items/:id/source-works/:sourceWorkId`: 특정 소스 작업 상세
|
|
- `GET /plan/release-reviews`: release 검수 목록
|
|
- `PATCH /plan/release-reviews/:planItemId`: release 검수 상태 저장
|
|
|
|
## 빠른 필터 규칙
|
|
|
|
`quickFilters.ts`에서 다음 조건을 별도 유틸로 관리합니다.
|
|
|
|
- `working`: 상태가 `작업중`
|
|
- `release-pending-main`: `릴리즈완료`이거나 main 반영 대기/진행/실패 상태
|
|
- `automation-failed`: 워커 실패 상태 집합에 포함
|
|
|
|
이 구조 덕분에 사이드바, 검색, deep link가 같은 기준을 공유합니다.
|
|
|
|
## release 검수 방식
|
|
|
|
release 검수 화면은 Plan 본문과 분리되어 있지만 같은 데이터 축을 사용합니다.
|
|
|
|
- 검수 필터: 전체, main 대기, 검수완료, 수정필요
|
|
- 검수 메모 저장
|
|
- 관련 컴포넌트/위젯 샘플 바로 열기
|
|
- 체크된 페이지/샘플 ID 기반 진행률 계산
|
|
- 전체 대상 확인 시 자동으로 `approved`
|
|
- 일부 확인 또는 메모 작성 시 `reviewing`
|
|
- 수정 요청 상태에서 체크가 덜 끝난 경우 `changes-requested` 유지
|
|
|
|
검수 메타데이터에는 다음 값이 들어갈 수 있습니다.
|
|
|
|
- `summary`
|
|
- `pageSelectionIds`
|
|
- `checkedPageSelectionIds`
|
|
- `docIds`
|
|
- `componentIds`
|
|
- `widgetIds`
|
|
|
|
## 소스 작업 증적
|
|
|
|
Plan 상세에서는 최신 자동 작업 결과를 탭 형태로 확인할 수 있습니다.
|
|
|
|
- 작업란
|
|
- 전체소스
|
|
- diff
|
|
- 커맨드 로그
|
|
- 증적 Preview
|
|
- 파일 목록
|
|
|
|
`PlanSourceWorkHistory`에는 브랜치명, 커밋 해시, preview URL, 변경 파일, diff 텍스트, 파일 스냅샷이 포함됩니다.
|
|
|
|
Codex 실행 로그에 `tokens used`가 잡히면 source work 기록과 상세 상단 상태 영역에 함께 표기합니다.
|
|
|
|
자동화 작업의 Git 절차나 동기화 순서는 이 문서에 고정 규칙으로 적지 않습니다. 필요 시 실제 worker 구현과 현재 설정값을 함께 확인합니다.
|
|
|
|
## 차트 집계 방식
|
|
|
|
`charts.tsx`는 Plan 전체 목록을 주기적으로 다시 불러와 최근 성과를 집계합니다.
|
|
|
|
- 일별 최근 7일
|
|
- 주별 최근 8주
|
|
- 등록 수
|
|
- 기능확인완료 수
|
|
- 작업완료 수
|
|
- main 반영 수
|
|
|
|
현재 스냅샷은 전체, 등록, 작업중, 기능확인완료, 완료, main반영 개수를 함께 제공합니다.
|
|
|
|
## 검색/진입 연계
|
|
|
|
통합 검색 옵션은 `src/app/main/mainView/searchOptions.ts`에서 정의합니다.
|
|
|
|
- `자동화 / 자동화`
|
|
- `자동화 / plan`
|
|
- `자동화 / release 검수`
|
|
|
|
검색에서 선택하면 해당 메뉴로 이동하고 필요한 경우 문서/컴포넌트 위치로 스크롤합니다.
|
|
|
|
## 유지보수 메모
|
|
|
|
- 상태 문자열과 워커 상태 문자열은 문자열 상수 기반이라 백엔드와 값이 어긋나지 않게 같이 관리해야 합니다.
|
|
- 스케줄 API는 여러 경로 후보를 순차 시도하므로 서버 경로 통합 시 `api.ts` 정리가 필요합니다.
|
|
- release 검수 메타데이터 스키마를 늘릴 때는 `ReleaseReviewPage`의 진행률 계산 규칙도 같이 점검해야 합니다.
|