feat: refine codex live chat context flows
This commit is contained in:
211
docs/README.md
211
docs/README.md
@@ -1,184 +1,53 @@
|
||||
# Docs Guide
|
||||
# 프로젝트 구조
|
||||
|
||||
프로젝트 문서는 작업일지, 기능 문서, 컴포넌트 문서를 기본 축으로 운영합니다. 현재 메인 앱 `Docs` 화면은 `docs/**/*.md`를 동적으로 수집해 폴더별로 노출합니다.
|
||||
이 문서는 현재 저장소의 큰 구조만 빠르게 확인하기 위한 기준 문서입니다. `Docs` 화면도 이 문서만 기본으로 읽으며, 채팅/자동화용 세부 context는 각 관리 화면에서 개별 항목으로 관리합니다.
|
||||
|
||||
## 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/
|
||||
docs/
|
||||
etc/
|
||||
public/
|
||||
scripts/
|
||||
```
|
||||
|
||||
공통 플러그인 타입과 유틸은 `src/types/component-plugin.ts` 에서 관리합니다.
|
||||
- `src`: 메인 프런트엔드 소스
|
||||
- `docs`: 작업 템플릿과 작업일지 같은 보조 문서
|
||||
- `etc`: work-server, DB, 운영 보조 리소스
|
||||
- `public`: 정적 파일과 채팅 세션 리소스
|
||||
- `scripts`: 개발/운영 스크립트
|
||||
|
||||
패키지 기준 안내 문서:
|
||||
## 프런트엔드 구조
|
||||
|
||||
- `src/components/README.md`: 공통 컴포넌트 패키지 목적, 구조, export 규약
|
||||
- `src/widgets/README.md`: 공통 위젯 패키지 목적, registry, feature 규약
|
||||
```text
|
||||
src
|
||||
├─ app
|
||||
│ └─ main
|
||||
├─ components
|
||||
├─ widgets
|
||||
├─ features
|
||||
├─ views
|
||||
├─ layer
|
||||
└─ store
|
||||
```
|
||||
|
||||
샘플 운영 규칙:
|
||||
- `src/app/main`: 메인 앱 셸, 라우팅, 상단/사이드바, 채팅/문서 진입점
|
||||
- `src/components`: 공통 UI 조각
|
||||
- `src/widgets`: 공통 카드형 블록
|
||||
- `src/features`: 프로젝트 전용 기능
|
||||
- `src/views`: 플레이/샘플 성격의 화면
|
||||
- `src/layer`: 전역 레이어와 검색 같은 횡단 기능
|
||||
- `src/store`: 앱 전역 상태
|
||||
|
||||
- `samples/Sample.tsx`는 해당 컴포넌트의 가장 기본형만 표현
|
||||
- plugin/feature 예시는 `samples/*.tsx`로 분리
|
||||
- 샘플 목록에서는 같은 컴포넌트 기준으로 묶고 `base -> plugin -> feature` 순서로 정렬
|
||||
## 기능 배치 기준
|
||||
|
||||
## 4. 샘플/위젯 레이아웃
|
||||
- 화면 전용 로직은 `src/features`에 둡니다.
|
||||
- 여러 화면에서 재사용되는 UI는 `src/components` 또는 `src/widgets`에 둡니다.
|
||||
- 문서 렌더링과 샘플 수집 같은 앱 메타 기능은 `src/app/main`과 매니페스트에서 관리합니다.
|
||||
|
||||
- 컴포넌트 샘플 레이아웃: 좌측 컴포넌트 목록 + 우측 상세 카드
|
||||
- 상세 카드는 컴포넌트 하나당 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` 참고
|
||||
- 앱 `Docs` 메뉴는 구조 확인용 문서만 노출합니다.
|
||||
- 작업일지, 템플릿, 과거 설계 메모는 저장소에 남길 수 있어도 기본 문서 목록에서는 제외합니다.
|
||||
- 채팅 유형 context와 자동화 유형 context는 공용 문서가 아니라 각 관리 데이터에서 직접 관리합니다.
|
||||
|
||||
Reference in New Issue
Block a user