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

docs/features/plan-board-review.md

@@ -0,0 +1,114 @@
+# 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. main 반영이 끝나면 최종 완료 흐름으로 정리됩니다.
+
+## 목록 기능
+
+`PlanBoardPage.tsx` 기준으로 다음 기능이 구현되어 있습니다.
+
+- 검색: `workId`, 메모, 상태, 브랜치, 워커 상태, 이슈 태그 검색
+- 보조 필터: 작업자 상태, release 상태, main 상태, 이슈 상태
+- 빠른 필터: 현재 작업중, 현재 release 상태, 현재 자동화 실패
+- 정렬: 진행 목록에서는 자동화 우선순위를 먼저 적용하고, 그 외에는 최근 갱신순 정렬
+- 페이지네이션: 목록 10개 단위
+
+## 상세 기능
+
+선택한 Plan 항목은 오버레이에서 상세 확인과 후속 조치를 처리합니다.
+
+- 원본 요청 보기
+- 작업 체크리스트
+- 릴리즈 준비 요약
+- 소스 작업 내역
+- 조치 / 이슈 이력
+- 추가 조치 기록
+- 이슈 조치 기록
+- 작업 소스 / diff / command log / 증적 / 파일 뷰어
+
+원본 요청은 `startedAt` 이후 잠기며, 이후 변경은 조치 이력으로 누적합니다.
+
+## 실행 액션
+
+상태와 `workerStatus`에 따라 다음 액션 버튼이 조건부로 노출됩니다.
+
+- `작업시작`
+- `작업완료 처리`
+- `브랜치 재시도`
+- `작업 재처리`
+- `release 반영 재시도`
+- `작업취소`
+- `main 일괄 반영 요청`
+
+세부 액션은 `/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`

docs/features/plan-schedule.md

@@ -0,0 +1,98 @@
+# Plan 스케줄 사용법
+
+## 목적
+
+반복적으로 등록되는 자동화 요청을 수동 입력 없이 생성하기 위한 스케줄 화면 사용법과 제약을 정리합니다.
+
+## 구현 위치
+
+- 화면: `src/features/planBoard/PlanSchedulePage.tsx`
+- API: `src/features/planBoard/api.ts`
+
+## 제공 기능
+
+- 스케줄 목록 조회
+- 신규 스케줄 등록
+- 기존 스케줄 수정/삭제
+- 즉시 실행 옵션 설정
+- 활성/비활성 전환
+- 반복 주기 또는 매일 실행 시간 설정
+- 다음 실행 예정 시각 계산 표시
+
+## 입력 항목
+
+- `workId`: 반복 등록할 작업 ID
+- `note`: 매번 생성될 요청 메모
+- `automationType`: 자동화 유형
+  - `plan`: Markdown 스타일 Plan 문서 등록/접수
+  - `auto_worker`: 실제 자동 작업 실행
+  - `command_execution`, `non_source_work`: 기존 분류 유지
+- `releaseTarget`: 반영 대상 브랜치
+- `jangsingProcessingRequired`: 기능동작확인 필요 여부
+- `autoDeployToMain`: main 자동 반영 대상 여부
+- `enabled`: 스케줄 사용 여부
+- `immediateRunEnabled`: 생성 직후 바로 등록 허용 여부
+
+## 스케줄 모드
+
+### 1. 반복 주기
+
+`interval` 모드입니다.
+
+- 값 + 단위로 반복 주기 설정
+- 단위: `minute`, `hour`, `day`, `week`, `month`
+- 내부 저장은 `repeatIntervalMinutes` 기준
+
+### 2. 매일 시간
+
+`daily` 모드입니다.
+
+- `HH:mm` 형식 시간 사용
+- 시간 계산은 `Asia/Seoul` 기준
+- 하루 1회 등록에 적합
+
+## 유효성 규칙
+
+현재 화면에서 다음 검사를 수행합니다.
+
+- 작업 ID 필수
+- 메모 필수
+- 같은 작업 ID 중복 금지
+- `interval` 모드 최소 10분 이상
+- 비활성 스케줄은 자동 등록되지 않음을 경고
+
+## 다음 실행 시각 계산
+
+다음 실행 시각은 화면에서 즉석 계산해 보여줍니다.
+
+- 비활성 상태면 `중지`
+- 직전 등록 이력이 없고 즉시 실행이 켜져 있으면 현재 시각 기준
+- `daily`는 오늘 KST 실행 여부를 보고 오늘 또는 다음 날 시각 결정
+- `interval`은 마지막 등록 시각 또는 생성 시각 기준으로 다음 주기를 계산
+
+## 추천 운영 방식
+
+- 자주 반복되는 운영 작업은 고정 `workId`로 등록
+- 사람이 검토해야 하는 작업은 `autoDeployToMain`을 끄고 release 검수 단계에서 확인
+- 단순 알림성/반복성 작업은 `immediateRunEnabled`를 켜서 누락 없이 시작
+- 짧은 주기 스케줄은 10분 이상으로 유지해 중복 생성 위험을 낮춤
+
+## API 경로 메모
+
+스케줄 API는 서버 구현 차이를 흡수하기 위해 여러 경로를 순차 시도합니다.
+
+- `/plan/scheduled-tasks`
+- `/plan/schedule/tasks`
+- `/plan/schedule`
+- `/plan/schedules`
+- `/plans/...` 변형 경로
+
+서버 경로가 고정되면 후보 경로를 줄여도 됩니다.
+
+## 테스트 포인트
+
+- interval/daily 전환 시 값 보존이 자연스러운지 확인
+- 같은 `workId` 중복 저장이 막히는지 확인
+- KST 기준 다음 실행 시각이 기대와 일치하는지 확인
+- 비활성 스케줄이 자동 생성되지 않는지 확인
+- 토큰 없는 사용자에게 저장/삭제가 제한되는지 확인

docs/features/plan-usage.md

@@ -0,0 +1,58 @@
+# Plan 활용 가이드
+
+## 목적
+
+운영자, 검수자, 개발자가 현재 Plan 기능을 어떤 순서로 써야 하는지 정리한 실무 가이드입니다.
+
+## 빠른 진입
+
+- 전체 목록 확인: `자동화 / 자동화`
+- 상세 처리 중심: `자동화 / plan`
+- release 검수: `자동화 / release 검수`
+- 추이 확인: `자동화 / 차트`
+- 반복 등록: `자동화 / 스케줄`
+
+통합 검색에서도 `plan`, `release 검수`, `스케줄`로 바로 이동할 수 있습니다.
+
+## 운영자 기준 사용 순서
+
+1. `자동화 / 자동화`에서 작업을 찾습니다.
+2. 필요하면 빠른 필터로 `현재 작업중`, `현재 release 상태`, `현재 자동화 실패`를 좁힙니다.
+3. 상세 오버레이에서 현재 상태, 이슈, 최근 소스 작업을 확인합니다.
+4. 상황에 맞는 액션을 실행합니다.
+5. 후속 설명은 조치 기록 또는 이슈 조치 기록으로 남깁니다.
+
+## 검수자 기준 사용 순서
+
+1. `release 검수`에서 `main 대기` 필터를 우선 봅니다.
+2. 검수 메모와 변경 파일, 관련 컴포넌트/위젯 샘플을 확인합니다.
+3. 확인한 항목은 체크 상태로 반영합니다.
+4. 이상 없으면 `검수완료`, 수정이 필요하면 `수정필요`로 저장합니다.
+
+## 개발자 기준 확인 포인트
+
+- 실패 상태면 `workerStatus`와 `lastError`를 먼저 확인
+- 브랜치 누락 계열 실패는 `브랜치 재시도` 또는 `작업 재처리` 판단
+- release/main 반영 관련 문제는 상세의 소스 작업 내역과 diff를 먼저 확인
+- 메모 원문이 잠겨 있으면 추가 조치 기록으로 정정 사유를 남김
+
+## 권한 없는 사용자 동작
+
+- 목록과 검수 현황은 조회 가능
+- 민감 메모는 마스킹
+- 상세 수정/삭제/조치 실행은 제한
+- 소스 작업 상세와 증적 확인도 제한될 수 있음
+
+## 문서와 화면을 함께 운영하는 방법
+
+- 기능 변경 시 `docs/features`를 먼저 갱신
+- 새 문서를 만들면 앱 `Docs / 기능문서`에 자동 노출되는지 함께 확인
+- 증적이 필요한 변경은 Plan 상세의 Preview, diff, 파일 목록으로 확인
+- 작업일지에는 어떤 기능 문서를 왜 수정했는지 함께 남김
+
+## 추천 문서 읽기 순서
+
+1. `docs/features/plan-board-review.md`
+2. `docs/features/plan-automation.md`
+3. `docs/features/plan-schedule.md`
+4. `docs/features/plan-usage.md`

docs/features/project-setup.md

@@ -0,0 +1,100 @@
+# 프로젝트 구성 개요
+
+## 목적
+
+현재 저장소의 화면 구조와 문서 체계를 빠르게 파악하기 위한 최신 개요 문서입니다.
+
+## 기술 스택
+
+- React
+- Vite
+- TypeScript
+- Ant Design
+- Recharts
+- React Router
+
+## 최상위 앱 구조
+
+- `src/app/main`: 메인 앱 프레임, 상단 메뉴, 사이드바, 본문, 검색 연동
+- `src/features`: 프로젝트 전용 기능 화면
+- `src/components`: 재사용 가능한 UI 컴포넌트
+- `src/widgets`: 샘플/위젯 단위 UI
+- `docs`: 기능/컴포넌트/작업일지 문서
+- `etc/servers/work-server`: Plan API 연동 서버 자산
+
+## 현재 주요 기능 축
+
+### Docs
+
+- `docs/**/*.md`를 수집해 문서 화면에 노출
+- 작업일지, 기능 문서, 컴포넌트 문서를 같은 흐름으로 탐색
+- `docs/features` 아래 문서는 `Docs / 기능문서` 메뉴에서 동적으로 확인 가능
+
+### APIs
+
+- 컴포넌트 샘플
+- 위젯 샘플
+
+### Plans
+
+- Plan 자동화 목록/상세
+- release 검수
+- 차트
+- 스케줄
+- 히스토리 확장 영역
+
+### Chat
+
+- Codex Live
+- 에러 로그
+
+`Codex Live`는 현재 프로젝트 환경의 `main_project`를 기준 저장소로 사용합니다. 소스 수정이 필요하면 **현재 프로젝트 루트의 로컬 `main` 작업본을 바로 수정**합니다.
+
+일반 채팅 요청과 작업메모 반영 요청도 같은 기준을 따르며, 별도 브랜치 생성 없이 현재 프로젝트 루트에서 바로 수정하는 것을 기본 동작으로 사용합니다.
+
+채팅에서 제공되는 파일/문서/이미지/코드 리소스와 첨부 파일은 세션별로 `public/.codex_chat/<chat-session-id>/resource/...` 아래에 노출됩니다.
+
+### Play
+
+- Layout Editor
+- 저장된 레이아웃 기록
+
+## Plan 기능 구조
+
+Plan 관련 코드는 `src/features/planBoard`에 집중되어 있습니다.
+
+- `PlanBoardPage.tsx`: 자동화 목록과 상세 편집
+- `ReleaseReviewPage.tsx`: release 검수
+- `PlanSchedulePage.tsx`: 반복 등록 스케줄
+- `charts.tsx`: 작업 추이 차트
+- `api.ts`: API 통신
+- `types.ts`: 상태/타입 정의
+
+## 문서 구조
+
+- `docs/worklogs`: 날짜별 작업 기록
+- `docs/features`: 기능 설명과 운영 가이드
+- `docs/components`: 공통 컴포넌트 설명
+- `docs/templates`: 기능/작업일지 템플릿
+
+현재 `docs/features`의 핵심 문서는 다음과 같습니다.
+
+- `project-setup.md`
+- `search-layer.md`
+- `plan-board-review.md`
+- `plan-automation.md`
+- `plan-schedule.md`
+- `plan-usage.md`
+
+## 검색/문서 연계
+
+- 통합 검색 옵션은 `src/app/main/mainView/searchOptions.ts`에서 구성
+- 문서, Plan 화면, 컴포넌트 샘플, 위젯 샘플을 하나의 검색 엔트리로 제공
+- 선택 시 해당 메뉴와 포커스 대상으로 바로 이동
+
+## 운영 메모
+
+- 기능 문서는 구현 파일명과 메뉴명을 그대로 써서 찾기 쉽게 유지
+- `docs/features` 변경분이 보이지 않으면 현재 선택한 Docs 폴더가 `기능문서`인지 먼저 확인
+- Plan 관련 변경은 문서와 라우팅/검색 옵션을 함께 확인
+- 스케줄, release 검수, 차트처럼 화면이 분리된 기능은 개별 문서를 유지

docs/features/search-layer.md

@@ -0,0 +1,22 @@
+# Search Layer
+
+## 목적
+
+통합 검색 모달의 열기/닫기와 검색 옵션 목록을 전역 레이어에서 관리합니다.
+
+## 구조
+
+- `src/layer/search/context`
+- `src/layer/search/hooks`
+- `src/layer/search/types`
+
+## 역할 분리
+
+- `layer/search`: 검색 모달 렌더링, open/close, 옵션 등록
+- `layer/gesture`: 제스처 감지와 검색 열기 트리거
+- `store/appStore`: 현재 페이지와 포커스된 컴포넌트 상태 관리
+
+## 메모
+
+- 검색 UI는 페이지 내부에 직접 두지 않고 레이어에서 렌더링
+- 페이지는 검색 옵션만 계산해서 레이어에 전달