diff --git a/docs/raw/요구_1025/_분석_359-A_외부조사.md b/docs/raw/요구_1025/_분석_359-A_외부조사.md new file mode 100644 index 000000000..bc55458e0 --- /dev/null +++ b/docs/raw/요구_1025/_분석_359-A_외부조사.md @@ -0,0 +1,197 @@ +# 359-A 사용자 가이드 — 외부 조사 (Altair Flux 도움말 · 라이브러리) + +조사일 2026-10-26 · 코드 고침 없음 · 라이센스는 GitHub API · npm 레지스트리 · LICENSE 원문으로 확인함. + +--- + +## ① 결론 다섯 줄 + +1. 우리 프로그램에는 이미 [?] 설명서 모달이 있음 — 왼쪽 차례 + 오른쪽 글 · `resources/help/<페이지>/*.md` · 화면에서 연 상자에 맞는 주제를 먼저 여는 문맥 도움말까지 됨. 새 틀을 들이지 말고 이것을 키우는 것이 최소 길임. +2. 외부 「가이드 만들기」 라이브러리는 많지만 맞는 것이 없음 — 문서 사이트 생성기(MkDocs · Docusaurus · VitePress · Sphinx 등)는 빌드 때 만드는 별도 사이트라서 「관리자가 사이트에서 바로 고침」 · 「모달 안에 띄움」과 안 맞고, 그나마 맞는 Docsify 는 따로 도는 SPA 임. +3. 안내 투어 중 상용 무료는 Driver.js(MIT)뿐 — Shepherd.js(v14부터) · Intro.js 는 AGPL+유료로 바뀌어 못 씀. 편집기 중 CKEditor 5 · TinyMCE 는 GPL+유료라 못 씀 · Toast UI Editor 는 보관(archived)됨. +4. Altair Flux 도움말은 유료 도구 Oxygen XML WebHelp(DITA)로 만든 정적 사이트임 — 가져올 것은 「화면 통째 캡처 + 노란 테두리 + 번호 원 + 번호 표」 그림 꼴과 「들어가는 길 · 단계 표 · 주의 상자」 글 꼴 · 버릴 것은 6단 깊이 목차와 내용 없는 목록 페이지. +5. 권하는 구성 = 새 의존성 0 — 기존 모달 + 자체 마크다운 변환기에 그림 · 주의 상자 · 링크만 더함 · 관리자 고침은 글 상자 + 미리보기 · 그림 교체는 올리기 · 그림 생산은 이미 깔린 Playwright(Apache-2.0) 자동 캡처 스크립트. + +--- + +## ② Altair Flux 도움말 분석 + +조사한 페이지 +- 첫 화면 https://help.altair.com/flux/Flux/Help/english/index.htm +- 책 첫 페이지(목록형) https://help.altair.com/flux/Flux/Help/english/UserGuide/English/topics/FluxGuideDutilisation1.htm +- 중간 목록 페이지 …/topics/GeometrieSketcher2D.htm · …/topics/Superviseur.htm · …/topics/PresentationGenerale2.htm · …/topics/SketcherFluxLesOutilsDeCreation.htm +- 화면 설명 페이지(번호 구역) …/topics/LancerLeSuperviseurFlux.htm +- 조작 절차 페이지 …/topics/OutilsDeCreationPolyligne.htm +- How-to 목록 …/topics/HowTo.htm · 문서 들어가는 길 …/topics/GuideDutilisation.htm + +### 만든 도구 + +- HTML 머리 `generator = DITA-OT` · 주석 `Oxygen version 25.1` · `oxygen-webhelp/…` 스크립트 · jQuery 3.7.1 — **Oxygen XML WebHelp(유료 상용) + DITA XML 원본(.dita)** 을 정적 HTML 로 찍어 낸 것임. +- 서버 없이 도는 정적 사이트 · 검색은 미리 만든 색인(`search/index/keywords.js`)을 브라우저가 읽음. +- 글을 고치려면 원본 XML 을 고쳐 다시 찍어야 함 — 「사이트에서 바로 고침」 없음. + +### 정보 구조 + +- 머리 = 제품 로고 + 「Altair Flux 2026 Documentation」 + 연도 판 표시(2026) + 검색 상자. +- 왼쪽 목차 첫 단 = 책 19권(Welcome · User guide · What's New · How to · Videos · Supervisor · Flux · Skew · 재료 · 예제 · 매크로 · PyFlux · 설치 · 시작 안내 등). +- 깊이 = 최대 6단 — 예: Home → Flux → Construction of a Flux project → Geometry: Sketcher (2D) → Flux Sketcher: creation tools → Creation tools: polyline. +- 중간 단 페이지 대부분이 「Introduction 한 문단 + Contents 링크 목록」뿐 — 실제 내용까지 3~4번 눌러야 함. +- 「원리(Principles)」 와 「소프트웨어 조작(Software aspects)」 을 짝 페이지로 나눔 — 예: Geometry: principles / Geometry: software aspects. +- 판 = 연도별 하위 주소(2021.help.altair.com · 2023.help.altair.com/2023.1/…)로 옛 판을 따로 둠. +- 언어 = 주소의 언어 폴더(`english` · `UserGuide/English`) · 일부 형제 제품은 `ja_jp` 폴더 · 화면에 언어 고르기 없음. + +### 주제 페이지 꼴 (세 가지) + +| 꼴 | 예 | 짜임 | +| --- | --- | --- | +| 목록형(허브) | Supervisor · Sketcher(2D) | 제목 → 한 줄 요약 → Introduction → Contents(하위 링크 목록) | +| 화면 설명형 | Environment of Flux Supervisor | Access(여는 길) → 창 전체 캡처 1장 → 「Zone \| Function」 표(1~9) · 표 안에 작은 단추 그림 → Note 상자 | +| 조작 절차형 | Creation tools: polyline | 소개 한 문단 → 「Access \| Cursor」 표(도구 단추 그림 16 px + 메뉴 길 `Construction → Line → Polyline`) → 「Stage \| Description」 단계 표(1 … n-1 · n) → 그리는 동안 보이는 정보(목록 + 작은 그림 2장) → 단축키 | + +공통 +- 맨 위 빵부스러기 · 이전/다음 단추(아이콘 · 주제 제목 툴팁) · 오른쪽 「On this page」 절 차례 · 아래 저작권. +- 주의 상자 = DITA note(「Note:」 머리) · 모든 페이지 위에 사이트 공지 띠(3D 판 폐지 안내). +- 관련 링크 = 본문 끝 링크 목록 또는 머리 아이콘 링크. +- 인쇄 단추 있음(`wh_print_link`) · 목차 · 머리는 인쇄 때 숨김(`d-print-none`) · How-to 는 문서마다 HTML · PDF 두 아이콘 · 일부는 PDF 만. + +### 그림 쓰는 법 + +- 화면 설명 그림 = 프로그램 창 통째 캡처 · 원본 1950×988 px 을 폭 900 으로 보임(약 2배 해상도 — 고해상 화면에서도 또렷). +- 콜아웃 꼴 = 구역마다 **노란 둥근 사각 테두리** · 창 밖 여백에 **검은 원 번호(1~9)** · 화살표 없이 구역 가까이 두거나 점선 지시선 하나 · 번호는 바로 아래 표의 「Zone」 칸과 짝. +- 절차 그림 = 작은 부분 캡처(약 300×220 px) · 도구 단추 아이콘은 글 안에 16~34 px 로 박음. +- 그림 번호 「Figure N」 · 캡션 없음 — 「아래 그림」 으로만 부름 · 대체 글(alt) 거의 없음. +- 그림 파일 이름 = `<주제>_img00N_en.png` — 주제마다 묶임 · 언어 꼬리표. + +### 탐색 · 문맥 도움말 + +- 검색 = 머리 검색 상자 → 따로 결과 페이지(`search.htm?searchQuery=`) · 브라우저 안 색인. +- 문맥 도움말 = 프로그램 Supervisor 의 [?] 아이콘 → 로컬 설명서 / 온라인 설명서 고름. 형제 제품 Feko 는 F1 = 고른 대화상자 · 패널의 주제로 바로 · 연결 없으면 첫 화면(https://help.altair.com/feko/topics/feko/bank/help_feko_c-cadfeko.htm). Flux 2021 판 안내에 「대화상자 옆 auto-documentation(Picture 단추 · 폭 400 px)」 언급이 검색에 잡히나 지금 판 페이지는 확인 안 됨. + +### 가져올 것 + +- **화면 설명형 꼴** — 「창 통째 캡처 + 노란 테두리 + 번호 원 + 번호 표」. 우리 페이지(좌측 패널 · 지도/도면 · 단추 묶음)를 한 장으로 보이기에 가장 알맞음. +- **조작 절차형 꼴** — 「여는 길(단추 그림 + 메뉴 길) → 단계 표 → 그동안 보이는 것 → 단축키」. +- **주의 상자** — 「주의 · 참고」 두 가지만. +- **2배 해상도 캡처 · 폭 900 안팎 표시**. +- **이전/다음 · 절 차례 · 인쇄** — 모달 안에서 차례 단추로 갈음 · 인쇄는 브라우저 인쇄. +- **문맥 도움말** — 이미 있음(`data-help-topic`) · 넓히면 됨. +- **그림 파일을 주제별로 묶는 이름 규칙**. + +### 버릴 것 + +- 6단 깊이 목차 · 내용 없는 목록(허브) 페이지 — 우리는 「그룹(설계 · 평가) → 페이지 → 주제 → 절」 3단까지. +- 원리 / 조작 페이지 쪼개기 — 우리 설명서는 이미 「칸 뜻 · 쓰인 방법과 근거」 로 나눔 · 더 쪼개지 않음. +- 따로 떨어진 문서 사이트 · 판별 하위 주소 · 연도 판 표시. +- 페이지마다 같은 공지 띠. +- 캡션 · 대체 글 없는 그림 — 우리는 그림마다 한 줄 설명(대체 글 겸함). +- PDF 만 있는 문서 · 유료 Oxygen · DITA XML 원본 · jQuery. + +--- + +## ③ 라이브러리 표 + +「상용 가능」 = BSD · MIT · Apache 만 ○ · 「스택 맞음」 = 프레임워크 없는 TS + Vite 화면 안에 넣을 수 있나. + +### ① 정적 문서 사이트 생성기 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 스택 맞음 | 출처 | +| --- | --- | --- | --- | --- | --- | +| MkDocs | 마크다운 → 정적 사이트(파이썬) | BSD-2-Clause | ○ | ✕ 별도 사이트 · 빌드 필요 | https://github.com/mkdocs/mkdocs | +| Material for MkDocs | MkDocs 테마 | MIT | ○ | ✕ · 2025-11 유지보수 모드(새 기능 끝 · 2026-11 까지 보안 고침) | https://github.com/squidfunk/mkdocs-material | +| Zensical | Material 팀의 후속 생성기 | MIT | ○ | ✕ 별도 사이트 · 새 도구 | https://github.com/zensical/zensical | +| Docusaurus | 문서 사이트(React) | MIT | ○ | ✕ React | https://github.com/facebook/docusaurus | +| VitePress | 문서 사이트(Vue + Vite) | MIT | ○ | ✕ Vue | https://github.com/vuejs/vitepress | +| Starlight | 문서 사이트(Astro) | MIT | ○ | ✕ Astro | https://github.com/withastro/starlight | +| Sphinx | 문서 사이트 · PDF(파이썬 · reST) | BSD-2-Clause | ○ | ✕ 별도 사이트 | https://github.com/sphinx-doc/sphinx | +| Docsify | 빌드 없이 브라우저가 마크다운을 바로 그림 | MIT | ○ | △ 따로 도는 SPA · 모달 안에 넣기 어려움 | https://github.com/docsifyjs/docsify | +| Oxygen XML WebHelp (Altair 가 씀) | DITA → 웹 도움말 | 유료 상용 | ✕ | ✕ | https://www.oxygenxml.com/xml_webhelp.html | + +→ 모두 「빌드 때 찍는 별도 사이트」 · 관리자 바로 고침이 없음 · 우리 모달과 겹침. 쓸 것 없음. + +### ② 앱 안 안내 투어 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 스택 맞음 | 출처 | +| --- | --- | --- | --- | --- | --- | +| Driver.js 1.10 | 화면 요소 강조 · 단계 투어 · 의존성 없음 | MIT | ○ | ○ 순수 TS | https://github.com/kamranahmedse/driver.js (지금 nilbuild/driver.js) | +| Shepherd.js 15 | 단계 투어 | AGPL-3.0 + 유료(v14부터) | ✕ | ○ | https://github.com/shipshapecode/shepherd · LICENSE.md | +| Intro.js 8 | 단계 투어 | AGPL-3.0 + 유료(v2부터) | ✕ | ○ | https://github.com/usablica/intro.js · license.md | +| Reactour | 단계 투어 | MIT | ○ | ✕ React | https://github.com/elrumordelaluz/reactour | + +### ③ 관리자 바로 편집용 편집기 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 스택 맞음 | 출처 | +| --- | --- | --- | --- | --- | --- | +| TipTap 3 (core · starter-kit · @tiptap/markdown) | 위지윅 편집기(ProseMirror 위) | MIT(Pro 확장 · 협업 · AI 는 유료 — 안 씀) | ○ | ○ 순수 JS 사용 가능 | https://github.com/ueberdosis/tiptap | +| ProseMirror | 편집기 엔진 | MIT | ○ | ○ 손이 많이 감 | https://github.com/ProseMirror/prosemirror (GitHub 은 보관 · 본 저장소 code.haverbeke.berlin 로 옮김) | +| Milkdown 7 (@milkdown/kit) | 마크다운 그대로 위지윅 | MIT | ○ | △ kit 은 됨 · 완성판 @milkdown/crepe 는 Vue · KaTeX · CodeMirror 를 끌고 옴 | https://github.com/Milkdown/milkdown | +| Quill 2 | 리치텍스트(HTML · Delta) | BSD-3-Clause | ○ | ○ · 마크다운 안 맞음 | https://github.com/slab/quill | +| Editor.js | 블록 편집기(JSON 출력) | Apache-2.0 | ○ | ○ · 마크다운 아님 → 변환 필요 | https://github.com/codex-team/editor.js | +| Lexical | 편집기 엔진(Meta) | MIT | ○ | △ React 위주 | https://github.com/facebook/lexical | +| Toast UI Editor | 마크다운 + 위지윅 | MIT | ○ | ✕ 2024 보관 · 2023 뒤 출시 없음 | https://github.com/nhn/tui.editor | +| CKEditor 5 | 리치텍스트 | GPL-2.0+ 또는 유료 | ✕ | — | https://github.com/ckeditor/ckeditor5 · packages/ckeditor5/LICENSE.md | +| TinyMCE 8 | 리치텍스트 | GPL-2.0+ 또는 유료(v7부터) | ✕ | — | https://github.com/tinymce/tinymce · LICENSE.md | + +### ④ 문서 안 검색 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 스택 맞음 | 출처 | +| --- | --- | --- | --- | --- | --- | +| lunr.js | 브라우저 전문 검색 | MIT | ○ | ○ · 2024 뒤 멈춤 · 한글 형태소 없음 | https://github.com/olivernn/lunr.js | +| FlexSearch | 빠른 전문 검색 | Apache-2.0 | ○ | ○ | https://github.com/nextapps-de/flexsearch | +| MiniSearch 7 | 작은 전문 검색(접두 · 오타 허용) | MIT | ○ | ○ | https://github.com/lucaong/minisearch | +| Pagefind | 빌드된 HTML 색인 검색 | MIT | ○ | ✕ 빌드 산출물 전제 · 바로 고친 글 못 따라감 | https://github.com/Pagefind/pagefind | + +→ 글 양이 페이지 19 × 파일 몇 개 · 수십 KB 수준. 한글은 조사가 붙어(「임도를」) 낱말 색인보다 **문자열 포함 찾기**가 더 잘 맞음 — 라이브러리 불필요. + +### ⑤ 화면 캡처 · 그림 번호 자동화 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 스택 맞음 | 출처 | +| --- | --- | --- | --- | --- | --- | +| Playwright(파이썬) 1.62 | 브라우저 자동 조작 · 캡처 · `device_scale_factor` 2배 · `screenshot(clip · mask · style · type="webp")` | Apache-2.0 | ○ | ○ **이미 requirements.txt 에 있음** | https://github.com/microsoft/playwright | +| shot-scraper | Playwright 위 캡처 CLI · YAML 로 여러 장 · JS 주입 · 선택자 자르기 | Apache-2.0 | ○ | △ 참고용 — 같은 일을 Playwright 로 직접 | https://github.com/simonw/shot-scraper | +| Annotorious 3 | 그림 위 영역 표시 · 편집 | BSD-3-Clause | ○ | △ 관리자가 콜아웃을 끌어 옮길 때만 | https://github.com/annotorious/annotorious | +| marker.js 2 | 그림 위 표시 그리기 | Linkware(화면에 링크 표시 조건) | ✕ | — | https://github.com/ailon/markerjs2 | + +### 덧붙임 — 글 그리기 · 안전 + +| 이름 | 용도 | 라이센스 | 상용 가능 | 비고 | 출처 | +| --- | --- | --- | --- | --- | --- | +| marked 18 | 마크다운 → HTML | MIT | ○ | 기존 자체 변환기로 충분 · 쓰면 DOMPurify 필요 | https://github.com/markedjs/marked | +| markdown-it 15 | 마크다운 → HTML | MIT | ○ | 위와 같음 | https://github.com/markdown-it/markdown-it | +| DOMPurify 3 | HTML 소독 | MPL-2.0 또는 Apache-2.0(고를 수 있음 → Apache) | ○ | 원 HTML 을 허용할 때만 | https://github.com/cure53/DOMPurify | +| medium-zoom | 그림 눌러 크게 | MIT | ○ | 네이티브 `` 로 갈음 가능 | https://github.com/francoischalifour/medium-zoom | + +--- + +## ④ 권하는 구성 + +**기존 [?] 모달을 키움 · 새 의존성 0.** + +| 부분 | 어떻게 | 직접 만드는 까닭 | +| --- | --- | --- | +| 모달 · 차례 · 문맥 | 지금 `ui_template_help.ts`(왼쪽 차례 · 오른쪽 글 · `data-help-topic` 로 먼저 열 주제) 그대로 · 차례에 그룹(설계 · 평가) 머리와 주제 안 절 차례만 더함 | 이미 있음 · 모든 페이지 좌측 패널 아래 [?] 자리도 이미 있음 | +| 글 원본 | 지금 `resources/help/<페이지>/*.md` 유지 | 메모장으로 고칠 수 있음 · 시험(`test_54_2_help_files.py`)도 있음 | +| 글 꼴 | Flux 세 꼴을 우리 틀로 — `00_설명서`(화면 한눈에: 통째 캡처 + 번호 표) · 조작 주제(여는 길 → 단계 표 → 보이는 것 → 주의) · `10_칸_뜻` · `20_쓰인_방법과_근거` | 꼴은 문서 규칙일 뿐 · 코드 아님 | +| 변환기 | 지금 자체 변환기(HTML 을 먼저 막고 굵게 · 코드 · 제목 · 목록 · 표만 받음)에 세 가지만 더함 — 그림 `![설명](파일)` · 주의 상자 `> 주의:` · 다른 주제 링크 | marked · markdown-it 를 들이면 원 HTML 허용 → DOMPurify 까지 필요 · 지금 변환기는 원래 안전 | +| 그림 | 주제 옆 `img/` 폴더 · 서버가 정해진 폴더에서만 내줌 · 눌러 크게 = 네이티브 `` | 몇 줄 | +| 관리자 바로 교정 | 시스템 관리자에게만 모달에 [고치기] — 글 상자(마크다운) + 옆 미리보기(같은 변환기) + [저장] · 서버는 `require_system_admin` 로 막음 | 위지윅 편집기(TipTap)는 의존성 묶음이 큼 · 관리자 한 사람이 쓰는 글에 과함 | +| 그림 교체 | 그림마다 [바꾸기] → 파일 고르기 · 서버가 형식(png · webp · jpg) · 크기 · 파일 이름 검사 후 덮음 | 몇 줄 | +| 검색 | 모달 위 찾기 칸 → 서버가 모든 페이지 글에서 문자열 포함 찾기 → 결과 누르면 그 페이지 · 주제로 | 한글 조사 문제 · 글 양 작음 | +| 인쇄 · PDF | 모달에 [인쇄] → 지금 주제(또는 페이지 전체) 인쇄용 CSS · 브라우저 「PDF 로 저장」 | 브라우저 기능 | +| 그림 생산 | Playwright 캡처 스크립트 하나 — 찍을 목록(주소 · 앞 조작 · 번호 붙일 화면 요소 선택자 · 자르기)을 JSON 으로 · 2배 해상도 · 찍기 전에 화면에 노란 테두리 + 번호 원을 덧씌워 그림에 박음 · `img/` 에 저장 | 이미 깔림 · 화면이 바뀌면 다시 돌리면 끝 · 콜아웃 그리기 라이브러리 불필요 | +| 화면에서 보기(선택) | 번호 표의 줄을 누르면 모달을 접고 실제 화면 요소를 잠깐 강조 | CSS 테두리 몇 줄 · 다단계 투어가 필요해질 때만 Driver.js(MIT) | + +--- + +## ⑤ 정할 거리 + +1. **관리자가 고친 글 · 그림 저장 자리** — git 안 `resources/help` 직접 고침 / 기본값은 git · 고친 판은 DB(또는 storage) 덮어쓰기 층 → **덮어쓰기 층** 권함(배포 서버 고침이 싱크 · 배포에 안 덮이고 미커밋으로 받기를 막지 않음 · [기본값으로] 단추). +2. **편집기** — 글 상자 + 미리보기 / TipTap 위지윅 → **글 상자 + 미리보기** 권함. +3. **콜아웃** — 캡처 때 그림에 박기 / 화면에서 SVG 로 덧그리고 관리자가 옮김 → **캡처 때 박기 + 그림 아래 번호 표** 권함. +4. **그림 생산** — 손 캡처 / Playwright 자동 스크립트 → **자동 스크립트** 권함(화면 바뀌면 다시 찍음 · 「그림 최대한 많이」에 맞음). +5. **가이드 모양** — 모달만 / 모달 + 따로 「전체 설명서」 페이지 → **모달만 + [인쇄]** 권함. +6. **안내 투어** — Driver.js 넣음 / 안 넣음 → **지금 안 넣음** 권함(「화면에서 보기」 강조만 직접). +7. **검색 범위** — 지금 페이지만 / 모든 페이지 → **모든 페이지** 권함. +8. **그림 형식 · 크기** — PNG / WebP · 2배 캡처 → **WebP · 2배 캡처 · 폭 900 안팎 표시** 권함. +9. **고침 이력** — 판마다 보관 · 되돌리기 / 마지막 판 + [기본값으로]만 → **마지막 판 + [기본값으로]** 권함. +10. **언어** — 한국어만 / 다국어 틀 → **한국어만** 권함(폴더 이름에 언어 꼬리표를 붙일 여지만 둠). +11. **대상 페이지** — 설계(B02~B09) · 예정노선(D01~D04) · 평가(E01~E07) 전부 / 설계 · 평가 먼저 → 요구 원문대로 **설계 · 평가 먼저** 권함(예정노선 묶음은 사용자 확인). diff --git a/docs/raw/요구_1025/_분석_359-B_코드현황.md b/docs/raw/요구_1025/_분석_359-B_코드현황.md new file mode 100644 index 000000000..e1c1b521b --- /dev/null +++ b/docs/raw/요구_1025/_분석_359-B_코드현황.md @@ -0,0 +1,141 @@ +# 요구 359-B 코드 현황 — 사용자 가이드(그림 + 설명 · [?] 모달 · 관리자 바로 교정) + +조사 = 읽기만 · 코드 고침 0 · DB 는 읽기 전용 접속(SELECT 만) · 사용자 프로젝트(엄상준_검증 · 박동철_검증) 열지 않음. + +## ① 결론 다섯 줄 + +1. [?] 설명서 틀은 이미 있음 — 좌측 패널 아래 [?] → 모달(왼쪽 차례 · 오른쪽 글) · 글 = `resources/help/<페이지>/*.md` 를 서버가 열 때마다 읽음 · B02~B09 · D01~D04 · E01~E07 에 붙어 있음 · 그림 · 링크 · 편집 기능은 없음. +2. 글 상태가 갈림 — D · E 34 문서는 내용이 참(55~243 줄) · B02~B09 는 B03 · B05(구조물 12) · B06 을 빼면 제목 네 줄 뼈대뿐(각 9 줄) · B01 대시보드 · B10 · B11 은 [?] 자체가 없음(서버 페이지 규칙도 B02~B09 · D01~D04 · E01~E07 만 받음). +3. A05_EduDetail 은 로그인 전 공개 「교육 안내」 카드 셋(105 줄)뿐 — 그림 · 문서 자리 없음 · Vite 는 `publicDir: false` 이고 `/static` 은 빌드 결과만 내보내므로, A05 폴더 안 그림은 **API 길(`/api/help/…/img/…`)로 서버가 읽어 주는 방식**이 맞음(관리자 교체도 같은 길). +4. 관리자 바로 고침 선례 = M02 시스템 층(시스템 관리자가 화면에서 고치면 서버가 git 추적 파일 `resources/master_template/` 에 원자 쓰기 · 판 sha256 16 자 · 다르면 409) · 그림 올리기 선례 = B01 회사 자산(UploadFile · 확장자 · 2 MB 검사) — 둘을 그대로 본뜨면 됨. +5. 「용화」 라는 이름의 프로젝트는 없음 — 지역 = 용화 인 ROAD 16 개가 모두 같은 원본 복제(10-17)이고 모두 창 · 검증자 배정분 · PLAN(예정노선) 프로젝트 0 개 · STABILITY 1 개(검증_sub7 것 · 단계 전부 NOT_STARTED) → 가이드 전용 복제(`tools_clone_project.py`) + E · D 가이드 프로젝트 새로 만들기가 필요 · 캡처는 Playwright 1.62(설치됨 · Edge 채널 선례 둘)로 자동화 가능. + +## ② 항목별 현황(근거) + +### 1. 지금 [?] 도움말 체계 + +- 단추 자리 — `ui_template/ui_template_overlay.ts:119-139` `splitSidebarActions` 가 `.ui-sidebar-actions` 를 찾아 `placeHelpButton` 호출(`:133`) → `ui_template/ui_template_help.ts:202-221` 이 `[data-help-row]`(없으면 줄 자신) 맨 앞에 [?] · 단계 묶음 주소면 [<] [>] 도 붙임. +- 직접 붙이는 페이지 — B02 `B02_ProjRegister_UI_Page.ts:304` · D01 `D01_PlanRegister_UI_Page.ts:137` · E01 `E01_StabRegister_UI_Page.ts:83`(`createHelpButton()`). +- 페이지 열쇠 — `ui_template_help.ts:40-43` 주소 머리 `#/[bde]0N` → `B05` 등 · B05 ↔ B06 짝 폴더 함께 보임(`:130`). +- 기능별 바로 열기 — 패널 요소에 `data-help-topic` 을 달면 [?] 가 그 항목부터 염(`:114-119` · `:138`) · 지금 쓰는 곳 = B05 구조물 폼 `B05_Profile_UI_Structures_Panel.ts:243`(`구조물_<종류>`) · B06 표준 횡단 `B06_Section_UI_Standard_Panel.ts:315`. → 가이드의 「기능별」 연결에 그대로 씀. +- 그리기 — `renderHelpMarkdown`(`:59-112`) = 제목(#~####) · 목록(- · 1.) · 문단 · 표 · **굵게** · `코드` 만 · HTML 이스케이프 먼저(`:45-56`) · **그림(`![]()`) · 링크 · 줄 안 그림 없음**. +- 모달 — `openModal`(`ui_template_modal.ts:13-28`) · `dialogClass: "ui-help"` · 폭 `min(960px, 92vw)` · 높이 80vh(`ui_template_help.css`) · 모달은 `actions`(머리 단추 자리) · `wide`(96vw×94vh) · `beforeClose`(닫기 전 물음)를 이미 받음 → 관리자 [고치기] 단추 · 안 저장 경고에 그대로 씀. +- 서버 — `common_util/common_util_help_router.py`(34 줄) · `GET /api/help/{page}` · 폴더 = `resources/help` · 페이지 규칙 `^(B0[2-9]|D0[1-4]|E0[1-7])$`(`:17`) · 파일 이름 순서 = 차례 · 제목 = 첫 `# ` 줄 · 매번 파일 읽음(캐시 없음) · 등록 `main.py:553` `dependencies=protected`(로그인만). +- 파일 꼴 — `resources/help/<페이지>/<번호>_<이름>.md` · `00_설명서.md` 가 첫 항목 · 번호 관례 = 00 설명서 · 10 칸 뜻 · 20 쓰인 방법과 근거 · 30 사용자 확정 전 값 · B05 = `구조물_<종류>.md` 12 개 · B06 = `표준_횡단면.md`. +- 문서 수(파일 · 줄) — B02 1·9 · B03 4·24 · B04 1·9 · B05 13·83 · B06 2·18 · B07 1·9 · B08 1·9 · B09 1·9 · D01 2·71 · D02 3·118 · D03 3·153 · D04 3·163 · E01 1·55 · E02 4·243 · E03 3·223 · E04 4·223 · E05 2·121 · E06 3·197 · E07 4·221 (모두 56 파일). B02 · B04 · B05 · B07 · B08 · B09 `00_설명서` = 「이 화면에서 하는 일 · 작업 순서 · 버튼 · 주의할 점」 제목만. +- 시험 — `resources/tester/test_54_2_help_files.py` · B02~B09 첫 항목 = 00_설명서 · 이름 순 · 파일 고침 즉시 반영 · 나쁜 페이지 거절(B01 · B10 · `../B05` 등) · D · E 설명서 400 자 넘음 · **명사형 종결 검사(합니다 · 해요 · 한다 등 금지)** · 화면 점검 = `resources/tester/ui_checks/54-2_도움말.js`(orca eval). +- 다른 도움말 — M02 카드 [?](`M02_MasterTemplete_CardHelp.ts` 118 줄 · 설명 · 단축키 · 기능 · 사용법 네 절 · 코드 안 글) · `docs/guide/B05_B06/` 는 **개발자용 손글**(사용자 가이드 아님). + +### 2. A05_EduDetail + +- 지금 = 로그인 전 공개 페이지 「교육 안내」 — 머리글 · 과정 카드 셋(기초 · 실무 · 심화) · [교육 문의하기] → A08(`A05_EduDetail_UI_Page.ts:100-105` · 글 `ui_template_locale_a.ts:146-167`) · 파일 둘(ts 105 줄 · css 86 줄)뿐 · 위 메뉴 「교육」(`A00_Common/app_shell.ts:144`) · 주소 `a05-edu-detail`(공개 · `PROTECTED_ROUTES` 밖). +- 정적 자원 길 — Vite `root: "A00_Common"` · `publicDir: false` · 프록시 `/api` · `/b07-cad` 만(`vite.config.ts:20-56`) · 서버 `/static` = 빌드 결과 `config/node_modules/.build`(`config_system.py:48-49` · `main.py:368-372`) · `/b07-cad` = 별도 정적 마운트(`main.py:393`). +- 알맞은 꼴 — 그림 · 글을 `A05_EduDetail/guide/<페이지>/` 에 두고 서버 API 가 읽어 줌(지금 `resources/help` 처럼). 이유 = ① 관리자 교체가 런타임에 바로 보여야 함(Vite import 는 빌드 때 굳음) ② `/api` 는 개발(Vite 프록시) · 배포(같은 출처) 모두 같은 주소 ③ `` 는 같은 출처라 로그인 쿠키가 따라감. +- 서버 자동 재시작 영향 없음 — 감시 = `*.py` 만(`config_dev_server.py:200-235`) · md · png 쓰기로 서버가 다시 안 뜸. +- A05 공개 페이지에 전체 가이드 목차를 둘지 = 정할 거리(지금 help API 는 로그인 필요). + +### 3. 페이지 목록 + +③ 표 참조. + +### 4. 관리자 바로 편집 + +- 역할 판정 — 서버 `common_util/common_util_auth.py:167-172` `require_system_admin`(role = `SYSTEM_ADMIN` 아니면 403) · 등록 예 `main.py:530` `system_admin_only = [Depends(verify_session), Depends(require_system_admin)]` · 화면 = `fetchDashboardMe().role === "SYSTEM_ADMIN"`(`ui_template_workflow_layout.ts:12-15` · `:172-178` 선례). +- 읽기 · 쓰기 갈라 붙인 선례 — `m02_so_router`(쓰기 · 시스템 관리자) · `m02_so_read_router`(읽기 · 로그인)(`main.py:540-541`) → help 도 읽기 라우터(지금) + 쓰기 라우터(새 · 시스템 관리자) 둘. +- 화면에서 고친 값을 git 추적 파일에 바로 쓰는 선례 — M02 시스템 층(`M02_Template_Layers.py:4` · `SYSTEM_ROOT = resources/master_template` `:40`) · 판 = sha256 앞 16 자 · 다르면 `StaleTemplate` → 409(`:44-49`) · 원자 쓰기 `common_util_json.atomic_write_json` · 글 파일 원자 쓰기 = `M02_DF_Router.py:79-86`(임시 파일 → `os.replace`). +- 그림 올리기 선례 — `B01_Dashboard_Router_Assets.py:52-80`(`UploadFile` · 확장자 png · jpg · webp · svg · 2 MB · 빈 파일 거절) · 내려주기 `:121-129`(`Response(content, media_type)`). +- 글 편집 UI 선례 — 내용 편집기(contenteditable) 선례 사실상 없음(`B06_Section_UI_Cross_Detail.ts:106` 한 칸뿐) · 마크다운 글을 textarea 로 고치고 옆에 미리보기가 가장 작은 길(그리기 함수 `renderHelpMarkdown` 재사용). +- 저장 자리 갈래 = ④ 참조. + +### 5. 「용화」 프로젝트(DB 읽기) + +- 이름 「용화」 프로젝트 없음(삭제분 포함) · 지역(region) = 용화 인 프로젝트 17 개 · 회사 1 「캐미팩토리」 · 모두 `storage/1/3/`. +- ROAD 16 개 = 10-17 22:28:49 한꺼번에 복제된 같은 용화 원본 · 모두 OWNERS 표에 창 · 검증자 배정(검증_랩탑메인 · sub1~8 · sub2b · sub2c · 데스크탑메인 · 데스크탑서브 · 엄상준_검증 · 박동철_검증) + 브레인 것 `검증_브레인232`. +- 가장 많이 진행된 것 + - `검증_sub6` `8b98ca75-c572-4002-8468-2adae4323414` · WF5_COMPLETE · B03 · B04 완료 · B05 · B06 IN_PROGRESS · B07 · B08 · B09 COMPLETE · 3.1 GB · sub6 창 배정분(쓰는 중). + - `검증_브레인232` `7c34ad71-f5c4-4e59-b61d-03085060c07d` · B03~B06 COMPLETE · B07 IN_PROGRESS · B08 STALE · B09 NOT_STARTED · 3.4 GB · 브레인 것. + - `검증_랩탑메인` `dad81824-…` · B05 · B06 IN_PROGRESS · B07~B09 NOT_STARTED. +- D(예정노선) — `project_kind='PLAN'` 0 개 · `plan_route_years` 0 행 → 새로 만들어야 함 · 만들기 = 산림청(시스템 관리자 · *.go.kr)만(`D01_PlanRegister_Router.py:31-38`) · 지형은 지점 기준으로 서버가 받음(`D03_PlanAnalysis_Terrain.py:1-12`). +- E(안정성평가) — STABILITY 1 개 `검증_sub7 안정성평가(E04 검증)` `bb765959-…` · 원본 검증_sub7 · 네 단계 NOT_STARTED · 41 MB · sub7 창 것 → 가이드용은 가이드 ROAD 복제본을 원본으로 E01 에서 새로 만듦(복사본 = `E01_StabRegister/source/` · `E01_StabRegister_Source.py:1-6`). +- 복제 도구 — `db_management/tools_clone_project.py`(DB 12 표 + storage 통째 · 원본은 읽기만 · 「원본을 얼린 뒤 뜰 것」) · storage 는 시놀로지가 데스크탑으로 옮김(3 GB 번짐 · 메모리 project_storage_synology_sync). + +### 6. 캡처 자동화 + +- Playwright 1.62.0 설치(`requirements.txt:32`) · 번들 chromium 안 받음 → 시스템 Edge(`channel="msedge"`) · 없으면 chrome — 선례 `B08_Quantity_Milestone_Capture.py:31-37`(카카오 지도 헤드리스 캡처 · 1200×800 PNG) · `common_util_print_pdf.py:25-27`(HTML → PDF) · 둘 다 서버 안 스레드에선 드라이버를 못 띄워 자식 프로세스로 돌림. +- 헤드 공용 드라이버 — `.claude/browser_driver.py`(202 줄 · 명령 파일 방식 · `tmp/browser/shots/` · `set_viewport_size` 금지 → `resize`) · 지금 지침은 화면 검증 = ORCA 내장 브라우저라 일괄 캡처는 별도 헤드리스 스크립트가 맞음. +- 로그인 — `POST /api/auth/login/request`(`A06_Login_Router.py:58-106`) · 개발 환경 `AUTH_OTP_DISABLED` 면 메일 인증 없이 세션 쿠키 바로 · 계정 = `tmp/aislo_cred.json`(있음 · 값 안 봄) → Playwright `context.request.post` 한 번이면 쿠키가 컨텍스트에 남음 · 현재 프로젝트 = localStorage `frd_current_project_id`(`config_frontend.ts:29`). +- Pillow 12.3 설치 — 번호 콜아웃을 그림 위에 덧그릴 때 씀 · 또는 화면에 번호 표지 DOM 을 잠깐 넣고 찍음(새 의존성 0). + +## ③ 페이지 · 기능 목록 표 + +- [?] 자동 = 좌측 패널(`createWorkflowOverlays`)이 있는 페이지 · [<] [>] = B05~B09 · D02~D04 · E02~E07 · 직접 붙임 = B02 · D01 · E01 · 좌측 패널 없는 페이지(B01 · B10 · B11) = [?] 없음. +- E05 = [?] [<] [>] 가 첫 줄(내보내기)에 붙고 둘째 줄은 스크롤 나눔 밖(`ui_template_overlay.ts:124-131`). +- `b09-print`(인쇄 미리보기) = `ROUTES` 에 없음 · 도움말은 B09 것을 씀. + +| 페이지 | 하는 일 | 좌측 패널 · 화면 구역 | 단추~ | 모달~ | [?] | +| --- | --- | --- | --- | --- | --- | +| B01 | 대시보드 | 역할별 카드 6~10(리소스 현황 · 시스템 설정 · 프로젝트 · 받은 예정노선 · 임시 보관함 · 사용자 · 가입 요청 · 회사 · 기본정보 · 보안 · 시스템 로그) · 지식 채팅 | 60 | 16 | 없음 | +| B02 | 프로젝트 등록 | 양식 12 칸 | 3 | 0 | 직접 | +| B03 | 파일 업로드 | 업로드 띠 · 계획노선 자료 · 지형 자료(LAS) · 예정노선에서 가져오기 | 14 | 3 | 자동([?]만) | +| B04 | 전처리 | 입력 포인트클라우드 · 지표면 분석 · 모델 표시 · 시점 제어 · 3D 둘 · 도엽등고 · 2D 지도 | 15 | 2 | 자동([?]만) | +| B05 | 노선 · 종단 설계 | 구조물 배치 · 페이지 설정 · 노선 추천 · 평면 편집 · 종단 · 배수유역도 · 유토곡선 · 도구 줄 | 50 | 6 + 창 분할 3 | 자동 + [<][>] | +| B06 | 횡단 설계 | 구조물 배치 · 횡단 보기 설정 · 표준 횡단면 · 측점 카드 · 상세 · 표 위 CAD | 16 | 3 | 자동 + [<][>] | +| B07 | 상세설계 CAD | 도면 목록 7 묶음(⚙ 설정) · 도각 편집 · CAD 리본 5 탭 | 12 + CAD | 4 | 자동 + [<][>] | +| B08 | 수량산출 | 구조물 집계표 · 자재 · 토공 · 수리집수면적표 · 거리이정표 | 26 | 9 | 자동 + [<][>] | +| B09 | 원가계산 | 데이터 점검 · 공기 옵션 · 탭 8 + 하위 18 · 박스/호표 · 하이퍼링크/팝업 | 20 | 3 + 팝업 | 자동 + [<][>] | +| b09-print | 인쇄 미리보기 | 영역 · 쪽 목록 · PDF/엑셀 다운로드 | 5 | 0 | 자동([?]만) | +| B10 | 결재 | 세금계산서 · 계좌 안내 | 1 | 0 | 없음 | +| B11 | 처리 상태 | 결재 단계 · 결과물 받기 | 1 | 0 | 없음 | +| D01 | 예정노선 등록 | 양식 | 3 | 0 | 직접 | +| D02 | 기준 지정 | 연도 지점 · 카카오 지도 | 2 + 지점마다 | 0 | 자동 + [<][>] | +| D03 | 노선 분석 | 지형 · 연도별 노선 · 평면 지도 · 지반 횡단 · 3D | 5 | 1 | 자동 + [<][>] | +| D04 | 확정 · 내보내기 | 확정할 연도 · 연도 표 · 업체 | 5 | 1 | 자동 + [<][>] | +| E01 | 안정성평가 생성 | 양식 | 3 | 0 | 직접 | +| E02 | 지반 조건 | 지반물성치 · 층 두께 · 구간 덮어쓰기 · 기준안전율 · 노면 하중 · 지진 · 지하수 | 14 | 1 | 자동 + [<][>] | +| E03 | 2D 해석 | 조건 · 정렬 · 측점 목록 · 위험 띠 · 횡단 그림 · 해석 결과 · 보강 검토 · 확률 · 민감도 · 3D | 12 | 0 | 자동 + [<][>] | +| E04 | 3D 해석 | 구간 · 탐색 설정 · 고급 설정 · 진행 · 평면 지도 · 3D · 결과 | 6 | 0 | 자동 + [<][>] | +| E05 | 보고서 | 내장 엑셀 · 시트 탭 · 낡음 띠 · PDF 미리보기 | 7 | 2 | 자동(첫 줄) | +| E06 | 암반 해석 | 절리군 · 해석 설정 · 스테레오넷 · 결과 표 | 8 | 1 | 자동 + [<][>] | +| E07 | 광역 위험 | 토층 물성 · 시나리오 · 노선 띠 · 격자 · SINMAP 지도 · 측점 표 | 4 + 토글 | 0 | 자동 + [<][>] | + +## ④ 저장 · 편집 구조 갈래와 권하는 쪽 + +자리 사실 — 시놀로지는 뿌리 파일 · `.claude` · `storage` 만 랩탑 ↔ 데스크탑으로 옮김(A0x · resources 제외) · DB 는 한 개 공유 · 데스크탑 메인 = 임시 배포(전역 깃 싱크 때만 바뀜) · 싱크 점검이 데스크탑 미커밋을 보면 멈춤(`.claude/git-sync-all.ps1:19` 허용 = config/package*.json 만 · `:105-107`). + +| 갈래 | 자리 | 좋은 점 | 걸림 | +| --- | --- | --- | --- | +| A git 파일 하나 | 글 `resources/help/<페이지>/*.md`(지금) · 그림 `A05_EduDetail/guide/<페이지>/` · 관리자 고침 = 서버가 그 파일에 원자 쓰기 | 사용자가 지목한 자리 그대로 · M02 시스템 층과 같은 길(선례 · 「마스터 파일은 그냥 푸시」) · 이력 = git · 코드와 한 벌로 배포 · 새 표 0 · 지금 라우터 · 시험 확장만 | 고친 PC 폴더에만 생김 → 커밋 · push 해야 다른 PC 에 감 · 데스크탑 임시 배포에서 고치면 싱크 점검이 멈춤 → 싱크 스크립트에 가이드 폴더 「사용자 편집」 커밋 갈래 필요 · 그림 바꿀 때마다 git 커짐(.git 이미 7.2 GB · WebP 200 장 ≈ 20 MB/벌) | +| B git 바탕 + storage 덧층 | 바탕 = A 자리 · 고친 글 · 바꾼 그림 = `storage/_program/guide/<페이지>/` · 읽기 = 덧층 우선(M02 층 방식) | 어느 PC 에서 고쳐도 시놀로지로 양쪽에 보임 · git 미커밋 0 · 싱크 스크립트 안 고침 · 배포 때 자료 자리라 코드 갱신에 안 덮임 | 고친 글이 git 이력 밖(시놀로지 버전 기록만) · 바탕을 새로 고치면 덧층이 가림 → 「덧층을 바탕으로 올리기」 걸음 필요 · storage 지우기도 번짐 · 서브 폴더 storage = 정션이라 시험은 임시 storage 로만 | +| C DB 표 + 그림 storage | `help_docs`(페이지 · 열쇠 · 글 · 판 · 고친 사람 · 시각) + 그림 storage | DB 하나라 즉시 공유 · 고친 이력 행 | 새 표 · 마이그레이션(공유 DB · 알림) · git 바탕과 이중 · 시험에 DB 필요 · 그림은 결국 storage | + +권함 = **A**. 이유 — 사용자 지목 자리 · 이미 도는 M02 시스템 층과 같은 운영(한 정책) · 코드가 가장 작음. 조건 — 관리자 고침은 랩탑 메인에서가 기본 · 데스크탑 임시 배포에서 고친 글 · 그림은 전역 깃 싱크가 「사용자 편집」 커밋으로 올림(겹치면 랩탑 판 우선 · 메모리 feedback_master_edits_push 와 같음). 데스크탑에서 고칠 일이 잦다고 하면 B 로 바꿈(배포 뒤에도 B 가 맞음 — 배포 정책 정할 때 M02 시스템 층과 함께 다시 봄). + +편집 꼴 — 마크다운 그대로(HTML 편집기 안 씀): 모달 머리 [고치기](시스템 관리자만 · `openModal.actions`) → 글 칸(textarea) + 옆 미리보기(`renderHelpMarkdown` 재사용) · [저장] = `PUT /api/help/{page}/{key}`(판 맞춤 · 다르면 409) · 안 저장 닫기 = `beforeClose` 물음 · 그림 = 고치기 상태에서 그림 눌러 [그림 바꾸기](같은 파일 이름에 덮어 글은 안 바뀜 · 주소 뒤 `?v=<판>` 로 캐시 깸) · [그림 넣기] = 올린 뒤 글 칸 커서 자리에 `![설명](파일)` 넣음. 이스케이프 먼저 하는 지금 그리기라 글에 HTML 을 넣어도 실행 안 됨. + +## ⑤ 캡처 방법 + +- 도구 — Playwright 파이썬 · 헤드리스 Edge(`channel="msedge"` · 없으면 chrome · 선례 둘과 같음) · 새 컨텍스트 뷰포트 1600×900 고정(공용 헤드 창이 아니라 `set_viewport_size` 금지와 무관). +- 차례 — ① 서버(랩탑 메인 8000 · 5173) ② `context.request.post("/api/auth/login/request", 계정 파일)` → 세션 쿠키 ③ localStorage `frd_current_project_id` = 가이드 프로젝트 ④ 장면마다 `goto #/<주소>` → 준비 기다림(요소 · 지도 `tilesloaded` · 3D 첫 그림) → 조작(패널 펼침 · 카드 열기 · 모달 열기) ⑤ 전체 = `page.screenshot` · 부분 = `locator.screenshot`(패널 · 모달 · 단추 줄) ⑥ 번호 콜아웃 = 대상 요소 `bounding_box` 자리에 동그라미 번호 DOM 을 잠깐 넣고 찍은 뒤 지움(새 의존성 0 · Pillow 로 덧그리기도 가능) ⑦ Pillow 로 WebP(품질 85) → `A05_EduDetail/guide/<페이지>/<페이지>_<장면>.webp`. +- 장면 목록 = 페이지별 표(파일 이름 · 주소 · 조작 · 번호 붙일 선택자 · 번호별 설명 한 줄) — 화면이 바뀌면 다시 돌려 일괄 갱신 · 관리자가 손으로 바꾼 그림은 건너뜀(바꾼 그림 표시). +- 걸림 — 3D · CAD(WebGL) 헤드리스 = 소프트웨어 그리기라 느림 → 기다림 늘림 · 안 되면 헤드 모드 · B07 CAD = iframe `/b07-cad` → `frame_locator` · 카카오 지도 = localhost:5173 출처면 키 도메인 검사 통과(B08 선례) · 조작이 캐시(sessionStorage)를 바꿈 → 가이드 전용 프로젝트에서만 · [저장] · [확정] · [초기화] · 추천 [적용]은 확인창까지만 찍고 취소. +- 스크립트 자리 — CLAUDE.md 규칙상 지킴 시험이 아니므로 `resources/tester` 밖 · 다시 돌릴 도구라 `tmp/`(사라짐)보다 저장소 안 도구 자리(예 `A05_EduDetail/guide/_capture.py` 또는 `db_management/` 처럼 tools) = 정할 거리. +- 원본 자료 — 가이드 전용 용화 복제(ROAD) · 그 복제를 원본으로 만든 E 프로젝트 · 용화 둘레 지점으로 만든 D 프로젝트. 창 배정 프로젝트 · 사용자 프로젝트로 찍지 않음. + +## ⑥ 계획 걸음 후보 + +한 줄 = 무엇 · 어디 · 무엇으로 확인. + +1. 가이드 전용 용화 복제 · `db_management/tools_clone_project.py <원본> "가이드_용화"`(원본 = 검증_sub6 B07~B09 완료 또는 검증_브레인232 · 원본 창 쉬는 때) · DB 행 · storage 폴더 · B02~B09 화면 열림. +2. E 가이드 프로젝트 · E01 에서 가이드_용화 원본 · E02~E07 한 번씩 돌림 · 단계 상태 · 각 화면 결과 보임. +3. D 가이드 프로젝트 · D01(시스템 관리자) 용화 둘레 지점 · D02 지점 · D03 분석 · D04 · `plan_route_years` 행 · 화면. +4. 그림 자리 + 내려주기 · `A05_EduDetail/guide/<페이지>/` + `GET /api/help/{page}/img/{name}`(이름 규칙 · 경로 탈출 막음 · 로그인) · `test_54_2_help_files.py` 그림 시험. +5. 그리기에 그림 · `renderHelpMarkdown` 에 `![설명](파일)` → `
` + `ui_template_help.css` 그림 폭 · 시험(변환 문자열) + ORCA 모달에 그림 보임. +6. [?] 빠진 페이지 · B01 대시보드 · B10 · B11(서버 페이지 규칙 `common_util_help_router.py:17` · 단추 자리) · `test_54_2` 페이지 목록 · ORCA. +7. 관리자 글 고침 · 쓰기 라우터(`require_system_admin`) `PUT /api/help/{page}/{key}`(판 · 409 · 원자 쓰기) + 모달 [고치기] · 미리보기 · `beforeClose` · 시험(403 · 409 · 쓰기) + ORCA 실제 고침 → 원래 글로 되돌림. +8. 관리자 그림 교체 · `POST /api/help/{page}/img`(UploadFile · png · jpg · webp · 크기 한도 · 같은 이름 덮기) + [그림 바꾸기] · 캐시 깸 · 시험 + ORCA. +9. 캡처 스크립트 · Playwright 헤드리스 Edge · 장면 목록 · 번호 콜아웃 · WebP · B02 한 페이지 장면 그림이 생기고 크기 · 번호 자리가 맞음. +10. 페이지별 글 + 그림 채움 · B01 → B09 → E01~E07 → D01~D04 · 기능마다 `data-help-topic` 달기 · `test_54_2` 명사형 검사 + 「글이 가리킨 그림 = 실제 파일」 검사. +11. (A 갈래면) 싱크 처리 · `.claude/git-sync-all.ps1` 데스크탑 가이드 폴더 미커밋 → 「사용자 편집」 커밋 · `-Check` 실행. +12. (정할 거리면) A05 공개 페이지 가이드 목차 · `A05_EduDetail_UI_Page.ts` · 읽기 길 공개 여부 · ORCA. + +정할 거리 — 대상 페이지 범위(B01 · B10 · B11 · D · M 포함?) · 글 자리(`resources/help` 그대로 vs A05 로 옮김) · 저장 갈래(A 권함 vs B) · 캡처 원본 프로젝트(검증_sub6 vs 검증_브레인232 복제) · D 가이드 프로젝트 새로 만듦 · 캡처 스크립트 자리 · A05 공개 목차 여부. diff --git a/docs/raw/요구_1025/요구서_359_사용자가이드.md b/docs/raw/요구_1025/요구서_359_사용자가이드.md new file mode 100644 index 000000000..d71d59774 --- /dev/null +++ b/docs/raw/요구_1025/요구서_359_사용자가이드.md @@ -0,0 +1,82 @@ +# 요구서 359 — 사용자 가이드(페이지 · 기능별 그림 + 설명) + +원문 = `사용자요구_1025.md` 요구 359 · 근거 분석 = `_분석_359-A_외부조사.md`(Altair Flux · 라이브러리) · `_분석_359-B_코드현황.md`(지금 도움말 · 페이지 목록 · 용화 프로젝트) · 계획 = `PLAN.md` 538~542. + +## 1. 사전조사 결과 (요구 359-7) + +- 「가이드 만들기」 외부 라이브러리 — 맞는 것 없음. + - 문서 사이트 생성기(MkDocs · Docusaurus · VitePress · Sphinx · Docsify) = 따로 도는 사이트 · 빌드 때 굳음 → 「모달 안」 · 「사이트에서 바로 고침」과 안 맞음. + - 안내 투어 = Driver.js(MIT)만 상용 무료 · Shepherd.js · Intro.js = AGPL + 유료. + - 편집기 = CKEditor 5 · TinyMCE = GPL + 유료 · Toast UI Editor = 보관(개발 멈춤). +- 우리 프로그램에 이미 [?] 설명서 모달이 있음 — 좌측 패널 아래 [?] · 왼쪽 차례 + 오른쪽 글 · 글 = `resources/help/<페이지>/*.md` · B02~B09 · D01~D04 · E01~E07 에 붙어 있음 · 그림 · 고침 기능 없음. +- 글 상태 — D · E 34 문서는 내용 있음 · B02~B09 는 B03 · B05 구조물 · B06 표준 횡단 빼고 제목 뼈대뿐. +- 결론 = **기존 [?] 모달을 키움 · 새 라이브러리 0** — 그림 생산은 이미 깔린 Playwright(Apache-2.0) · 그림 다듬기는 Pillow(설치됨). + +## 2. Altair Flux 에서 가져올 것 (요구 359-3) + +- 화면 한눈에 꼴 — 화면 통째 그림 + 구역마다 노란 테두리 + 검은 번호 원 → 그림 아래 「번호 · 하는 일」 표. +- 조작 꼴 — 여는 길(단추 · 메뉴) → 단계 표(1 · 2 · 3 …) → 그동안 보이는 것(작은 그림) → 주의. +- 주의 상자 = 「주의 · 참고」 둘만 · 그림 = 2배 해상도로 찍어 폭 900 안팎으로 보임 · 그림 이름은 주제별로 묶음. +- 버릴 것 = 6단 깊은 차례 · 내용 없는 목록 페이지 · 따로 떨어진 문서 사이트. + +## 3. 만들 것 + +### 3-1. 가이드 글 (페이지마다) + +| 파일 | 내용 | +| --- | --- | +| `00_설명서.md` | 화면 한눈에 — 통째 그림(번호) + 번호 표 + 작업 순서 | +| `01~09_<기능>.md` | 기능별 조작 — 여는 길 → 단계 표 → 그림 → 주의 · 패널 카드 · 모달마다 하나 | +| `10_칸_뜻.md` · `20_쓰인_방법과_근거.md` · `30_사용자_확정_전_값.md` | 있는 페이지는 그대로 · 그림만 더함 | + +- 그림 최대한 많이 — 페이지마다 통째 1장 + 카드 · 모달 · 단계마다 부분 그림 · 모두 150장 안팎. +- 기능별 열기 — 패널 카드 · 모달에 주제 표시를 달아 [?] 가 그 기능 주제부터 엶(지금 B05 구조물에 쓰는 방식). +- 글 = 명사형 종결(지금 시험이 검사). + +### 3-2. 그림 자리 (요구 359-1) + +- `A05_EduDetail/guide/<페이지>/` — 그림(WebP) · 찍을 장면 목록(`_scenes.json`) · 손으로 바꾼 그림 목록(`_manual.json`). +- 서버가 그 폴더에서만 내줌(`/api/help/<페이지>/img/<이름>` · 로그인 · 경로 탈출 막음) — 관리자가 바꾸면 새로고침 없이 바로 보임. + +### 3-3. [?] 모달 (요구 359-2) + +- 지금 모달 그대로 · 글에 그림 · 주의/참고 상자 · 다른 주제 링크를 그림 · 그림 누르면 새 탭에 원본. +- [?] 가 없는 대시보드(B01)에 [?] 하나 더함(머리 자리). + +### 3-4. 시스템 관리자 바로 고침 (요구 359-4 · 6) + +- 모달 머리에 [고치기](시스템 관리자만) → 글 상자(마크다운) + 옆 미리보기 → [저장] · 남이 먼저 고쳤으면 「다시 불러오기」 안내 · 안 저장 닫기 = 물음. +- 그림마다 [그림 바꾸기](png · jpg · webp · 5 MB · 같은 이름에 덮음) · [그림 넣기](올리고 글 칸에 그림 줄 넣음). +- 손으로 바꾼 그림은 표시 → 자동 캡처를 다시 돌려도 안 덮음. +- 저장 = 그 서버 폴더의 git 파일에 바로 씀(M02 마스터 시스템 층과 같은 길) → 깃 싱크가 「사용자 편집」 커밋으로 올림. + +### 3-5. 그림 만들기 (요구 359-6) + +- 원본 = 용화 노선 — 가이드 전용 복제 「가이드_용화」(검증_sub6 복제 · B07~B09 완료분) · E = 그 복제로 E01 생성 · E02~E07 돌림 · D = 용화 둘레 지점으로 새 예정노선(3 연도). +- 자동 캡처 스크립트 — 헤드리스 Edge · 장면 목록대로 화면 열기 · 카드 펼치기 · 모달 열기 → 노란 테두리 + 번호 원을 덧씌워 찍음 → WebP · 화면이 바뀌면 다시 돌리면 끝. +- [저장] · [확정] · [초기화] · 추천 [적용]은 확인창까지만 찍고 취소 · 밝은 테마. + +## 4. 정함(브레인 · 사용자가 바꿀 수 있음) + +| 번호 | 정할 거리 | 정함 | 다른 길 | +| --- | --- | --- | --- | +| 1 | 관리자가 고친 글 · 그림 저장 자리 | git 파일 직접(M02 시스템 층과 같음 · 이력 = git) · 데스크탑에서 고친 것은 전역 깃 싱크가 올림 · 겹치면 사용자 편집 우선 | DB · storage 덧층(어느 PC 든 바로 공유 · 이력 없음) | +| 2 | 편집기 | 글 상자 + 미리보기 | 위지윅(TipTap · 의존성 큼) | +| 3 | 번호 표시 | 캡처 때 그림에 박음 + 그림 아래 번호 표 | 화면에서 덧그림(관리자가 옮김) | +| 4 | 대상 페이지 | B01~B09 · E01~E07 먼저 → D01~D04 다음 · B10 · B11(빈 화면) · M(관리자) 뺌 | D 빼기 | +| 5 | 원본 프로젝트 | 「가이드_용화」 복제(약 3 GB · 시놀로지로 데스크탑에도 번짐) | 검증_브레인232 그대로 씀 | +| 6 | 그림 형식 | WebP · 2배 캡처 · 폭 900 표시 | PNG | +| 7 | 고침 이력 | 마지막 판만(되돌리기 = git) | 판마다 보관 | +| 8 | 언어 | 한국어만 | 다국어 틀 | + +## 5. 이번에 안 넣는 것 (필요하면 뒤에) + +- 안내 투어(Driver.js) · 모든 페이지 글 찾기 · [인쇄] · A05 교육 페이지(로그인 전 공개)에 가이드 목차. + +## 6. 쓰는 라이브러리 (상용 조건) + +| 라이브러리 | 쓰는 곳 | 라이센스 | 상태 | +| --- | --- | --- | --- | +| Playwright(파이썬) | 자동 캡처 | Apache-2.0 | 설치됨 | +| Pillow | WebP 저장 · 자르기 | MIT-CMU(HPND) | 설치됨 | +| 새 라이브러리 | — | — | 0 |