156 lines
6.6 KiB
Markdown
Executable File
156 lines
6.6 KiB
Markdown
Executable File
# Docs Guide
|
|
|
|
프로젝트 문서는 작업일지, 기능 문서, 컴포넌트 문서를 기본 축으로 운영합니다. 현재 메인 앱 `Docs` 화면은 `docs/**/*.md`를 동적으로 수집해 폴더별로 노출합니다.
|
|
|
|
## 0. 임시 로컬 모드
|
|
|
|
- 현재 저장소는 당분간 로컬 전용으로 운영합니다.
|
|
- 문서 정리나 Codex 작업 시 Git 원격 동기화, 브랜치 운영, 자동 merge 흐름은 기본 전제로 사용하지 않습니다.
|
|
- `Codex Live`, 일반 채팅, 작업메모 반영 요청은 **현재 프로젝트 루트의 로컬 `main` 작업본을 바로 수정**하는 방식으로 처리합니다.
|
|
- 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
|
|
- 예외 처리
|
|
- 테스트 포인트
|
|
|
|
## 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` 에서 관리합니다.
|
|
|
|
샘플 운영 규칙:
|
|
|
|
- `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`를 기준으로 동작
|
|
|
|
## 5. 프로젝트 종속 레이아웃
|
|
|
|
- 위치: `src/features/layout`
|
|
- 대상: 현재 프로젝트 화면에서만 사용하는 레이아웃
|
|
- 예시: 컴포넌트 샘플 목록, 위젯 샘플 목록, Docs markdown preview, Plan 게시판
|
|
|
|
프로젝트 종속 기능 규칙:
|
|
|
|
- 현재 프로젝트에서만 의미 있는 화면/기능은 `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` 방식으로 확인
|
|
|
|
## 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`에서 관리
|
|
- 현재 앱에는 목록/상세 보드, release 검수, 차트, 스케줄 화면이 함께 포함됨
|
|
- 기본 상태는 `등록`, `작업중`, `작업완료`, `릴리즈완료`, `완료`
|
|
- 자동화 진행은 `workerStatus`로 별도 관리하며 브랜치 준비, 자동 작업, release/main 반영 상태를 표현
|
|
- `작업시작` 이후에는 원본 요청(`작업 ID`, 원본 메모`)을 수정하지 않고 조치 이력으로 누적 기록
|
|
- 권한 토큰이 없으면 조회 중심으로 동작하며 민감 메모와 소스 작업 일부는 제한 또는 마스킹
|
|
- 관련 기능 문서는 `docs/features/plan-board-review.md`, `plan-automation.md`, `plan-schedule.md`, `plan-usage.md` 참고
|