# 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`의 진행률 계산 규칙도 같이 점검해야 합니다.