ai-code-app/docs/README.md

# Docs Guide

프로젝트 문서는 작업일지, 기능 문서, 컴포넌트 문서를 기본 축으로 운영합니다. 현재 메인 앱 `Docs` 화면은 `docs/**/*.md`를 동적으로 수집해 폴더별로 노출합니다.

## 0. 임시 로컬 모드

- 현재 저장소는 당분간 로컬 전용으로 운영합니다.
- 문서 정리나 Codex 작업 시 Git 원격 동기화, 브랜치 운영, 자동 merge 흐름은 기본 전제로 사용하지 않습니다.
- `Codex Live`, 일반 채팅, 일반 작업메모 반영 요청은 **현재 프로젝트 루트의 로컬 `main` 작업본을 바로 수정**하는 방식으로 처리합니다.
- 자동화 작업메모도 별도 브랜치 흐름을 이 문서에 고정하지 않고, 실제 운영 설정과 요청 문맥을 기준으로 처리합니다.
- 자동화와 `Codex Live`는 별개로 취급하며, 자동화는 선택된 자동화 유형 context만 우선 참조합니다.
- Git 관련 작업은 사용자가 명시적으로 요청할 때만 수행합니다.

## 1. 작업일지

- 위치: `docs/worklogs`
- 규칙: 날짜별 1개 Markdown 파일 작성
- 파일명 예시: `2026-03-31.md`
- 템플릿: `docs/templates/worklog-template.md`
- 권장 기록 범위: 구현 내용, 구조 변경, 빌드/배포 이슈, Git 작업 내역
- 최근 작업일지는 날짜별로 계속 누적 기록
- 화면 캡처는 `docs/assets/worklogs/YYYY-MM-DD/` 아래에 저장하고 작업일지에서 상대 경로로 연결
- 캡처는 전체 화면보다 작업한 컴포넌트 영역 단위 이미지를 우선 사용
- 메뉴/기능 증적이 필요하면 `capture:menu`, `capture:feature` 스크립트로 화면 단위 캡처를 함께 남김
- 화면 캡처를 남기지 못한 날에도 `## 화면 캡처` 섹션은 유지하고, 미첨부 사유를 한 줄로 기록
- 문서 최신화 작업을 수행한 날에는 어떤 문서를 왜 수정했는지 함께 기록

권장 항목:

- 오늘 작업한 내용
- 이슈 및 해결 과정
- 결정 사항
- 상세 작업 내역

## 2. 기능 문서

- 위치: `docs/features`
- 규칙: 기능 단위로 Markdown 파일 작성
- 파일명 예시: `auth.md`, `dashboard.md`
- 템플릿: `docs/templates/feature-template.md`
- 권장 기록 범위: 기능 목적, 화면 흐름, API/상태, 테스트 포인트
- `docs/features/*.md`를 추가하거나 수정하면 앱 `Docs / 기능문서` 메뉴에 반영됨
- `src/features/**/*.md`는 프로젝트 내부 전용 설명 문서용이며 메인 `Docs` 메뉴의 기본 수집 대상은 아님

권장 항목:

- 기능 목적
- 주요 화면/흐름
- 데이터 구조 및 API
- 예외 처리
- 테스트 포인트

현재 주요 기능 문서:

- `docs/features/work-request-board.md`: 작업 요청 게시글, 하위 요청, 순차 자동화 접수
- `docs/features/plan-board-review.md`: Plan 게시판과 상세 처리
- `docs/features/plan-automation.md`: 자동화 처리 흐름과 worker 기준
- `docs/features/plan-schedule.md`: 반복 등록과 스케줄 관리
- `docs/features/plan-usage.md`: 운영자/검수자 활용 순서

## 3. 컴포넌트 문서

- 위치: `docs/components`
- 규칙: 컴포넌트별 1개 Markdown 파일 작성
- 파일명 예시: `status-badge.md`, `user-card.md`
- 대표 샘플: 각 컴포넌트의 `samples/Sample.tsx`
- 확장 샘플: `samples/*.tsx`

권장 항목:

- 목적
- 폴더 구조
- UI props
- plugin input/output 규칙
- plugin 합성 규칙
- Sample 활용 예시

현재 기준 주요 컴포넌트 구조:

```text
src/components
├─ markdownPreview
├─ navigation
├─ previewer
├─ search
├─ status-badge
└─ window
```

공통 플러그인 타입과 유틸은 `src/types/component-plugin.ts` 에서 관리합니다.

패키지 기준 안내 문서:

- `src/components/README.md`: 공통 컴포넌트 패키지 목적, 구조, export 규약
- `src/widgets/README.md`: 공통 위젯 패키지 목적, registry, feature 규약

샘플 운영 규칙:

- `samples/Sample.tsx`는 해당 컴포넌트의 가장 기본형만 표현
- plugin/feature 예시는 `samples/*.tsx`로 분리
- 샘플 목록에서는 같은 컴포넌트 기준으로 묶고 `base -> plugin -> feature` 순서로 정렬

## 4. 샘플/위젯 레이아웃

- 컴포넌트 샘플 레이아웃: 좌측 컴포넌트 목록 + 우측 상세 카드
- 상세 카드는 컴포넌트 하나당 1개
- 카드 내부는 `Base Sample` 아래에 `Plugin Samples`, `Feature Samples`를 순차적으로 배치
- 위젯 샘플은 `widgets/**/samples/*.tsx` 기준으로 별도 수집
- 실제 샘플 엔트리 로딩은 `src/app/manifests/samples.manifest.ts`, `src/samples/registry.ts`를 기준으로 동작
- 위젯 공통 계약과 메타데이터 규약은 `src/widgets/README.md`, `src/widgets/registry.ts`, `src/widgets/core`를 함께 기준으로 봅니다

## 5. 프로젝트 종속 레이아웃

- 위치: `src/features/layout`
- 대상: 현재 프로젝트 화면에서만 사용하는 레이아웃
- 예시: 컴포넌트 샘플 목록, 위젯 샘플 목록, Docs markdown preview, Plan 게시판
- `Layout Editor`의 기능 명세는 위젯 기본 스펙 정의가 아니라, 현재 레이아웃에 배치된 컴포넌트의 화면 역할과 상호작용을 기술하는 데이터로 취급
- 따라서 컴포넌트 간 이벤트/상태 연결과 API 연결 흐름도 `Layout Editor` 기능 명세에서 구현 가능한 범위로 본다
- 따라서 샘플 메타나 위젯 기본 기능을 `Layout Editor` 기능 명세에 자동 주입하지 않음
- `Layout Editor` 구현은 공통 위젯/컴포넌트 본체 직접 수정보다 `props` 전달과 feature 레이어 조합을 우선한다
- 공통 위젯/컴포넌트 변경이 필요하면 기본값 `props`를 기존 동작과 동일하게 유지해 기존 화면 영향이 없도록 설계한다

프로젝트 종속 기능 규칙:

- 현재 프로젝트에서만 의미 있는 화면/기능은 `src/features` 아래에 둠
- 예: `Plan 게시판`, 대시보드 feature 샘플, 앱 전용 레이아웃
- 공통 컴포넌트/위젯으로 재사용 가능한 항목은 `src/components`, `src/widgets`에 유지

메인 화면 분리 규칙:

- 위치: `src/app/main`
- 구성: `MainView`, `MainHeader`, `MainSidebar`, `MainContent`
- 목적: 상단 메뉴, 사이드바, 본문, 검색/문서/Plan 흐름을 앱 레벨에서 분리

## 6. Markdown Preview

- 공통 markdown preview는 `src/components/markdownPreview` 아래에서 관리
- `basePath`를 받아 특정 폴더 아래 markdown 문서를 재사용 가능하게 렌더링
- `docs` 문서 영역은 좌측 폴더/문서 트리 + 우측 markdown 카드 목록 구조 사용
- 문서 수집 매니페스트는 `src/app/manifests/docs.manifest.ts`에서 관리
- `docs/features`, `docs/components`, `docs/worklogs`, `docs/templates`는 폴더 단위로 자동 분류됨
- `docs/worklogs`는 최신 날짜가 먼저 보이도록 역순 정렬

## 7. 대시보드 위젯/데이터

- 대시보드 카드 위젯은 `src/widgets/dashboard-report-card`
- 위젯 샘플과 프로젝트 종속 샘플은 분리
- 재사용 가능한 샘플 데이터는 `src/data` 아래에서 관리
- 프로젝트 전용 대시보드 샘플은 `src/features/dashboard`에 둠

## 8. 배포 메모

- Nexus publish 대상 registry는 `package.json`의 `publishConfig.registry`
- alpha 버전 배포는 `npm publish --tag alpha`
- Nexus 인증은 `~/.npmrc`의 `username / _password(base64) / email` 방식으로 확인

## 8-1. 웹푸쉬 작업 메모

- 동일한 웹푸쉬를 새 알림으로 교체하려면 DB에서 이전 알림을 지우지 말고 `POST /api/notifications/send` 호출 시 `data.notificationKey` 또는 `threadId`를 고정값으로 보냅니다.
- 서비스워커는 같은 `notificationKey`를 `tag`로 사용하므로 같은 브라우저의 이전 알림이 자동으로 대체됩니다.
- 특정 브라우저 클라이언트에만 보내려면 같은 API payload에 `targetClientIds: ['클라이언트ID']`를 넣습니다.
- 대상 클라이언트 ID가 필요하면 `web_push_subscriptions.device_id`를 조회하고, raw SQL 대신 `/api/crud/web_push_subscriptions/select` 같은 기존 CRUD API를 우선 사용합니다.

## 9. etc 운영 기준

- 부가 서버/DB/타언어 프로젝트는 `etc` 아래에서 분리 관리
- 서버 예시: `etc/servers/work-server`
- DB 예시: `etc/db/work-db`
- `etc` 내부 비밀값과 생성물은 커밋 제외
  - `.env`
  - `node_modules`
  - `dist`
  - `*.log`

## 10. Plan 기능 문서 메모

- `Plan` 기능은 `src/features/planBoard`에서 관리
- `작업 요청` 기능은 `src/features/board`에서 관리하며 게시글 1건에 N개 하위 요청을 둘 수 있습니다.
- 현재 앱에는 목록/상세 보드, release 검수, 차트, 스케줄 화면이 함께 포함됨
- 기본 상태는 `등록`, `작업중`, `작업완료`, `릴리즈완료`, `완료`
- 자동화 진행은 `workerStatus`로 별도 관리하며 브랜치 준비, 자동 작업, release/main 반영, 프로젝트 루트 pull 완료 상태를 포함한 흐름을 표현
- `작업시작` 이후에는 원본 요청(`작업 ID`, 원본 메모`)을 수정하지 않고 조치 이력으로 누적 기록
- 권한 토큰이 없으면 조회 중심으로 동작하며 민감 메모와 소스 작업 일부는 제한 또는 마스킹
- 관련 기능 문서는 `docs/features/work-request-board.md`, `plan-board-review.md`, `plan-automation.md`, `plan-schedule.md`, `plan-usage.md` 참고