Initial import

docs/features/plan-automation.md

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