how2ice/ai-code-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: refine codex live chat context flows

Browse Source
This commit is contained in:
how2ice
2026-05-08 21:15:51 +09:00
parent 82c0d8a197
commit 442879313f
92 changed files with 14815 additions and 7314 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/README.md
View File

@@ -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는 공용 문서가 아니라 각 관리 데이터에서 직접 관리합니다.

137
docs/components/component-addition-suggestions.md
View File

@@ -1,137 +0,0 @@
# 신규 컴포넌트 후보 2차 정리
## 신규 컴포넌트 후보 7차 제안
### 목적
현재 `release` 브랜치 기준으로 기존 컴포넌트와 겹치지 않는 신규 공통 컴포넌트 후보를 제안합니다.
이 글은 검토용 plan 게시판 작성만 수행하며, 자동화 접수는 하지 않고 미접수 상태로 유지합니다.
### 공통 설계 원칙
- 샘플(`samples`)을 제외한 컴포넌트와 위젯에는 API 호출이나 화면 전용 로직을 직접 넣지 않습니다.
- 컴포넌트와 위젯은 최대한 멍청하게 설계하고, 직관적인 props를 받아 직관적인 UI 동작만 수행해야 합니다.
- 기능 처리와 비즈니스 로직은 `src/features` 또는 해당 화면 전용 패키지 레벨에서 담당해야 합니다.
- 공통 컴포넌트와 위젯은 여러 곳에서 재사용되므로, 수정 시에는 기존 동작을 바꾸지 않는 범위에서만 보완해야 합니다.
### release 기준 확인
- 이미 존재: Dashboard Report Card, Progress/MultiProgress, Search Command, Popup/Select/CheckCombo 입력, Markdown Preview, Previewer/Codex Diff, Status Badge, Window, DataListTable, EmbeddedMap, TextMemo/GPS/API 샘플 위젯
- 제안 방향: Plan/Board/History 화면에서 반복될 가능성이 높지만 아직 공통 컴포넌트로 분리되지 않은 조합형 UI
### 신규 후보
#### 1. Query Filter Builder UI
복수 조건 필터를 행 단위로 추가하고 저장할 수 있는 필터 빌더 컴포넌트입니다.
- 적용 위치: Plan Board 고급 필터, History 검색, Board 검색
- 주요 props: `fields`, `operators`, `value`, `onChange`, `presets`, `compact`
- 기대 효과: 화면마다 흩어질 수 있는 필터 조건 UI를 일관된 패턴으로 정리
#### 2. Timeline Activity Feed UI
작업 상태 변경, 접수, release/main 반영, 오류 이벤트를 시간순으로 보여주는 활동 피드 컴포넌트입니다.
- 적용 위치: Plan 상세, History 상세, 자동화 실행 이력
- 주요 props: `items`, `groupByDate`, `statusResolver`, `dense`, `renderMeta`
- 기대 효과: 로그성 텍스트를 추적 가능한 UI로 전환하고 최근 변경 맥락을 빠르게 파악
#### 3. Evidence Attachment Strip UI
스크린샷, diff, 로그, 링크 같은 증빙 자료를 한 줄 카드 목록으로 노출하는 첨부 스트립 컴포넌트입니다.
- 적용 위치: Plan 검증 증빙, Preview 결과, History 상세
- 주요 props: `attachments`, `onPreview`, `onDownload`, `maxVisible`, `variant`
- 기대 효과: 증빙 자료 표시와 미리보기 진입점을 공통화
### 우선순위 제안
1. Query Filter Builder UI
2. Timeline Activity Feed UI
3. Evidence Attachment Strip UI
우선 1번을 먼저 검토하는 것이 좋습니다. Plan Board와 History에서 필터 조건이 계속 늘어날 가능성이 높아 재사용 효과가 가장 큽니다.
## 목적
기존에 개발 완료된 `FormField`, `StateKit`, `DataListTable`과 이미 개발 접수된 `Action Toolbar UI`, `Detail Inspector Panel`, `Timeline / Activity Log UI`, `Confirm Dialog UI`, `Notification Toast / Action Feedback UI`, `Date Range Input`, `File Attachment List`, `Component Usage Doc Card`, `Split Pane Layout`은 이번 후보에서 제외합니다.
이번 문서는 현재 코드베이스와 기존 Board/Plan 접수 이력에 없는 신규 공통 컴포넌트만 다시 추려 이후 Plan 후속 작업 후보를 만드는 목적입니다.
## 제외 기준
- 이미 구현 완료된 공통 컴포넌트는 중복 후보로 다시 올리지 않음
- 이미 Board/Plan에서 개발 접수된 컴포넌트는 신규 후보에서 제외
- 앱 전용 화면 조합보다 여러 기능에서 재사용 가능한 공통 UI를 우선 선정
## 신규 후보
### 1. Drawer / Side Sheet UI
본문 흐름을 끊지 않고 우측 또는 하단에서 보조 편집 화면을 여는 컴포넌트입니다.
- 적용 위치: Plan 상세 보조 편집, 설정 화면, 모바일 상세 패널
- 주요 props: `open`, `placement`, `width`, `title`, `footer`, `onClose`
- 기대 효과: 전체 화면 전환 없이 보조 작업을 열고 닫는 패턴을 공통화
### 2. Description List / Key Value Summary UI
상세 정보 화면에서 라벨과 값을 읽기 전용으로 정리하는 컴포넌트입니다.
- 적용 위치: Plan 메타 정보, 방문 이력 상세, 앱 설정 요약
- 주요 props: `items`, `columns`, `size`, `labelWidth`, `copyable`
- 기대 효과: 상세 화면마다 반복되는 메타 정보 레이아웃을 줄임
### 3. Stepper / Process Flow UI
등록, 작업중, `release` 반영, `main` 반영 같은 단계를 순서형으로 보여주는 컴포넌트입니다.
- 적용 위치: Plan 상태 흐름, 배포 진행 표시, 자동화 단계 요약
- 주요 props: `steps`, `current`, `status`, `direction`, `compact`
- 기대 효과: 텍스트 상태 나열보다 현재 단계와 다음 단계를 직관적으로 전달
### 4. Tag Input UI
여러 키워드나 라벨을 직접 추가하고 삭제하는 입력 컴포넌트입니다.
- 적용 위치: Board 태그, 검색 조건 저장, 증적 분류, 빠른 필터 조합
- 주요 props: `value`, `suggestions`, `maxTags`, `allowCustom`, `onChange`
- 기대 효과: 다중 조건 입력을 `select`와 별도로 다뤄 반복 필터 구성이 쉬워짐
### 5. Breadcrumb / Context Path UI
현재 위치와 상위 경로를 짧게 보여주는 탐색 보조 컴포넌트입니다.
- 적용 위치: Docs 상세, Components 샘플 상세, History 상세 진입 경로
- 주요 props: `items`, `separator`, `compact`, `onNavigate`
- 기대 효과: 깊은 메뉴 구조에서 현재 위치 파악과 상위 이동 비용을 낮춤
### 6. Property Grid UI
설정값이나 옵션 목록을 2열 또는 다열로 배치해 빠르게 편집하는 설정형 컴포넌트입니다.
- 적용 위치: 앱 설정, 자동화 설정, 위젯 옵션 편집
- 주요 props: `sections`, `fields`, `columns`, `readonly`, `onChange`
- 기대 효과: 설정 폼을 긴 세로 나열 대신 밀도 있게 구성 가능
## 권장 진행 순서
1. `Description List / Key Value Summary UI`
2. `Stepper / Process Flow UI`
3. `Drawer / Side Sheet UI`
4. `Tag Input UI`
5. `Property Grid UI`
6. `Breadcrumb / Context Path UI`
## 검증 기준
- 모바일 폭에서 `drawer`, `stepper`, `property grid`가 가로 넘침 없이 동작하는지 확인
- Plan 상세와 설정 화면에 붙였을 때 기존 `antd` 기본 컴포넌트 조합보다 반복 코드가 줄어드는지 확인
- 읽기 전용 화면과 편집 화면에서 같은 컴포넌트를 무리 없이 재사용할 수 있는지 확인
## 메모
- 다음 후보 구현 시에는 `samples/BaseSample.tsx`, `samples/Sample.tsx`, 필요 시 `plugins/*.plugin.ts`를 같은 묶음으로 준비
- Docs 문서에는 목적, 주요 props, 적용 위치, 확장 포인트를 함께 기록

1
docs/test001.md
View File

@@ -1 +0,0 @@
테스트MD자동 생성 입니다.