# Plan 자동화 보드

## 목적

`src/features/planBoard`는 Plan 등록부터 자동 작업, release 검수, main 동기화 전 단계까지 한 화면 흐름으로 관리하는 기능 묶음입니다.
현재 문서는 기존 개선 제안 메모를 대신해 실제 구현 기준의 운영 문서로 사용합니다.

## 화면 구성

- `all`: 전체 자동화 목록
- `in-progress`: 완료 전 항목 중심 목록
- `error`: 열린 이슈가 있는 항목 중심 목록
- `done`: release 완료 기준 목록
- `board`: 상세 편집과 이력 조회 중심 보드
- `release-review`: release 검수 전용 화면
- `charts`: 최근 작업 추이 차트
- `schedule`: 반복 등록 스케줄 관리
- `history`: 향후 이력 확장 메뉴용 영역

라우팅과 메뉴 정의는 `src/app/main/routes.tsx`, `src/app/main/MainContent.tsx`에서 관리합니다.

## 문서 반영 방식

- 이 문서를 포함한 `docs/features/*.md`는 메인 앱 `Docs / 기능문서` 메뉴에서 자동 수집됩니다.
- 문서 추가만으로 별도 라우트를 만들지는 않으며, `Docs` 화면의 markdown 목록에 합류하는 방식입니다.
- 노출 순서와 폴더 라벨은 `src/app/main/layout/useMainLayoutData.ts`, `src/app/main/routes.tsx`에서 결정합니다.

## 상태 모델

기본 상태는 `src/features/planBoard/types.ts`에 정의되어 있습니다.

- `등록`
- `작업중`
- `작업완료`
- `릴리즈완료`
- `완료`

실제 자동화 진행은 별도 `workerStatus`로 관리합니다. 대표값은 다음과 같습니다.

- 진행: `브랜치생성중`, `자동작업중`, `release반영중`, `main반영중`
- 대기: `브랜치준비`, `release반영대기`, `main반영대기`
- 실패: `브랜치실패`, `자동작업실패`, `release반영실패`, `main반영실패`

즉, 사용자에게 보이는 업무 상태와 자동 워커 상태를 분리해서 표현합니다.

## 주요 사용 흐름

1. 작업을 등록하면 Plan 항목이 생성됩니다.
2. `작업시작` 또는 자동화에 따라 브랜치 준비와 작업이 진행됩니다.
3. 작업이 완료되면 release 반영 상태와 main 반영 대기 여부가 추적됩니다.
4. release 검수 화면에서 샘플/위젯/변경 파일을 확인하고 검수 상태를 갱신합니다.
5. 최종 완료 처리는 현재 worker 상태와 운영 설정을 기준으로 정리됩니다.

## 목록 기능

`PlanBoardPage.tsx` 기준으로 다음 기능이 구현되어 있습니다.

- 검색: `workId`, 메모, 상태, 브랜치, 워커 상태, 이슈 태그 검색
- 보조 필터: 작업자 상태, release 상태, main 상태, 이슈 상태
- 빠른 필터: 현재 작업중, 현재 release 상태, 현재 자동화 실패
- 정렬: 진행 목록에서는 자동화 우선순위를 먼저 적용하고, 그 외에는 최근 갱신순 정렬
- 페이지네이션: 목록 10개 단위

## 상세 기능

선택한 Plan 항목은 오버레이에서 상세 확인과 후속 조치를 처리합니다.

- 원본 요청 보기
- 작업 체크리스트
- 릴리즈 준비 요약
- 소스 작업 내역
- 조치 / 이슈 이력
- 추가 조치 기록
- 이슈 조치 기록
- 작업 소스 / diff / command log / 증적 / 파일 뷰어

원본 요청은 `startedAt` 이후 잠기며, 이후 변경은 조치 이력으로 누적합니다.

## 실행 액션

상태와 `workerStatus`에 따라 다음 액션 버튼이 조건부로 노출됩니다.

- `작업시작`
- `작업완료 처리`
- `브랜치 재시도`
- `작업 재처리`
- `release 반영 재시도`
- `작업취소`
- `main 일괄 반영 요청`

자동화 작업메모(`auto_worker`)의 Git 절차는 이 문서에서 고정 규칙으로 설명하지 않습니다. 세부 흐름은 실제 worker 구현과 현재 운영 설정을 확인합니다.

세부 액션은 `/plan/items/:id/actions/:action` API로 실행됩니다.

## 자동 새로고침과 알림

- 자동화가 진행/대기 상태일 때만 자동 조회 타이머가 동작합니다.
- 주기는 `appConfig.automation.autoRefreshIntervalSeconds`를 따릅니다.
- 길게 눌러 자동 조회 On/Off를 전환할 수 있습니다.
- 설정값에 따라 자동화 시작/실패 메시지를 toast로 알립니다.

## 권한 처리

권한 토큰이 없는 경우 조회 중심으로 동작합니다.

- 수정/삭제/조치/스케줄 저장 비활성화
- 민감한 요청 메모는 마스킹
- 소스 작업 상세/증적 확인 제한

토큰 처리와 헤더 부착은 `src/app/main/tokenAccess.ts`, `src/features/planBoard/api.ts`에서 담당합니다.

## 연관 문서

- 자동화/구현 방식: `docs/features/plan-automation.md`
- 스케줄 사용법: `docs/features/plan-schedule.md`
- 활용 가이드: `docs/features/plan-usage.md`
