ai-code-app/docs/features/plan-automation.md

Plan 자동화와 구현 방식

목적

Plan 자동화 기능의 데이터 구조, API 연동 방식, release 검수 연계 방식을 정리합니다.

구현 위치

• 화면 진입: 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 기록과 상세 상단 상태 영역에 함께 표기합니다.

차트 집계 방식

charts.tsx는 Plan 전체 목록을 주기적으로 다시 불러와 최근 성과를 집계합니다.

• 일별 최근 7일
• 주별 최근 8주
• 등록 수
• 기능확인완료 수
• 작업완료 수
• main 반영 수

현재 스냅샷은 전체, 등록, 작업중, 기능확인완료, 완료, main반영 개수를 함께 제공합니다.

검색/진입 연계

통합 검색 옵션은 src/app/main/mainView/searchOptions.ts에서 정의합니다.

• 자동화 / 자동화
• 자동화 / plan
• 자동화 / release 검수

검색에서 선택하면 해당 메뉴로 이동하고 필요한 경우 문서/컴포넌트 위치로 스크롤합니다.

유지보수 메모

• 상태 문자열과 워커 상태 문자열은 문자열 상수 기반이라 백엔드와 값이 어긋나지 않게 같이 관리해야 합니다.
• 스케줄 API는 여러 경로 후보를 순차 시도하므로 서버 경로 통합 시 api.ts 정리가 필요합니다.
• release 검수 메타데이터 스키마를 늘릴 때는 ReleaseReviewPage의 진행률 계산 규칙도 같이 점검해야 합니다.