boss-dashboard-guide (Docusaurus)

이 저장소는 포장보스 어드민(관리자용) 웹 서비스의 이용 가이드를 Docusaurus로 관리하고, routes.json(메뉴/URL 목록)과 코드 압축본(repomix)을 기반으로 페이지(URL pathname) 단위의 이용 가이드 문서를 생성/유지합니다.

• 문서 사이트는 GitHub Pages로 배포됩니다.
• 문서 구조는 서비스의 URL 구조(/a/b/c)와 동일하게 docs/a/b/c/index.md 형태로 관리됩니다.

---

배포된 문서(최종 결과)

• GitHub Pages: https://devadmin-riu.github.io/boss-dashboard-guide

---

주요 명령어(패키지 스크립트)

“가이드 생성/사이드바 생성/빌드”는 아래 스크립트로 모두 수행합니다.

목적	명령어	설명	비고
(선행) repomix 생성	npm run generate-repomix-outputs	[BE / FE / FE-URL 구조] 코드 압축본 생성 → generated/repomix-outputs/*.xml
(선행) routes 생성	npm run generate-routes	메뉴/URL 목록 생성 → generated/routes.json	codex 토큰 사용됨
(선행) sidebar 생성	npm run generate-tutorialSidebar	routes.json → generated/tutorialSidebar.json	결과물 내용은 sidebars.ts의 tutorialSidebar에 복사해야 함
(선행) 전체 생성	npm run generate:all	위 3개를 순차 실행(개별로 수행 필요 여부 판단 후 모두 수행 필요할 경우만 권장)
가이드 문서 생성	npm run build-guides	routes.json + repomix를 기반으로 docs/**/index.md 생성/갱신	codex 토큰 사용됨
로컬 개발 서버	npm run start	Docusaurus 개발 서버 실행(localhost:3000)

⚠️ 유의사항

routes.json 생성(npm run generate-routes) 시

• codex 토큰이 비교적 많이 사용되기 때문에, 대시보드 메뉴 및 URL 구조에 변경 사항이 크지 않다면 data/routes.source.json 파일을 기반으로 필요한 부분만 추출 또는 수정하고, 로컬의 generated/routes.json에 복사하여 이용하는 것을 권장

가이드 파일들 생성(npm run build-guides) 시

• 수십개의 가이드를 한 번에 생성하려고 하면 가이드 퀄리티가 현저히 떨어짐(모두 같은 내용만 반복하는 식으로 작성됨).
• generated/routes.json 내용에 가이드를 생성하려는 페이지만 남도록 수정 후, 가이드 파일 생성 명령어를 수행하는 것을 권장
• 대시보드 메뉴 기준 최상단 메뉴 단위(제품 관리, 견적 관리 등 한 번에 약 10여개 페이지)로 가이드 생성하는 것 권장

실행 순서

로컬에서 가이드 생성 및 확인 (최초)

npm ci
npm run generate:all
npm run build-guides
npm run start

로컬 가이드 생성 및 확인 (generated 폴더에 이미 routes.json 파일이 존재하는 경우)

(필요 시) npm ci
npm run build-guides
npm run start

---

문서(페이지) 생성 규칙

문서 경로 매핑

• 각 route의 path는 아래 규칙으로 문서 파일로 매핑됩니다.

route.path	문서 파일
/vendors	docs/vendors/index.md
/purchase-order/lines/track-inventory/draft	docs/purchase-order/lines/track-inventory/draft/index.md

front matter 규칙

각 index.md는 다음 front matter를 가집니다.

• title: menuLabel을 " > "로 이어붙인 값
  예) ["재고 발주 관리", "재고 발주"] → 재고 발주 관리 > 재고 발주
• slug: route의 path
• sidebar_position: route의 sidebarOrder - sidebars.ts에서 tutorialSidebar을 'autogenerated'로 반영할 때 쓰이는 요소. 현재는 수동으로 tutorialSidebar를 정의하고 있기 때문에 없어도 무방함.

---

배포 방식(GitHub Actions)

이 저장소는 GitHub Pages Source를 GitHub Actions로 설정했고, PR이 main에 merge되어 closed 될 때 워크플로우가 실행되어 사이트가 배포됩니다.

• 워크플로우: .github/workflows/deploy.yml
• 배포 정책: develop 브랜치에서 작업 후, develop → main 브랜치로 PR 생성 및 머지를 진행하여 자동 배포 동작되도록 합니다.

---

작업 시나리오별 가이드

특정 페이지 가이드만 수정(또는 최신화)하고 싶은 경우

1. 로컬의 generated/routes.json 파일에서 원하는 페이지의 pathname만 남기고 나머지는 제거한 뒤 저장
2. 터미널에서 npm run build-guides를 실행
3. 로컬(localhost:3000)에서 변경된 사항 확인
4. 변경된 diff를 확인 후 커밋, 푸시 후 main 브랜치로 PR 생성 - 메뉴 구조가 변경된 것이 아니므로 generated/routes.json 파일은 커밋에서 제외
5. PR 머지(머지 시 GitHub Actions로 자동 배포 진행됨)

페이지가 새로 추가된 경우

1. 추가된 페이지만 기존 generated/routes.json의 다른 요소와 동일한 형식으로 작성 후, 기존 다른 페이지는 제거한 뒤 저장
2. npm run generate-tutorialSidebar 실행 뒤, generated/tutorialSidebar.json 내용을 sidebars.ts의 tutorialSidebar 인자에서 적절한 위치에 복사 & 붙여넣기
3. 터미널에서 npm run build-guides를 실행
4. 로컬(localhost:3000)에서 변경된 사항 확인
5. 변경된 diff를 확인 후 커밋, 푸시 후 main 브랜치로 PR 생성 - 추가된 페이지 요소까지 generated/routes.json 파일에 추가하여 커밋에 포함
6. PR 머지(머지 시 GitHub Actions로 자동 배포 진행됨)

기존 URL 구조만 수정된 경우

1. 변경된 URL 구조대로 generated/routes.json 파일 수정
2. npm run generate-tutorialSidebar 실행 뒤, generated/tutorialSidebar.json 내용을 sidebars.ts의 tutorialSidebar 인자에 복사 & 붙여넣기
3. docs 폴더 내에도 변경된 URL 구조대로 폴더 및 index.md 파일 위치 변경
4. 로컬(localhost:3000)에서 변경된 사항 확인
5. 변경된 diff를 확인 후 모두 커밋, 푸시 후 main 브랜치로 PR 생성
6. PR 머지(머지 시 GitHub Actions로 자동 배포 진행됨)