feat(가이드): 538-2 [?] = 넓은 모달 한 가이드 · 차례 묶음 → 페이지 → 기능 · 그림 · 주의/참고 · B01 [?]

- [?] = openModal wide · 왼쪽 차례(임도 설계 B → 안정성평가 E → 예정노선 D · 지금 페이지 펼침) · 오른쪽 = 모든 페이지 이어 그림 · 처음 = 보이는 data-help-topic 절 → 지금 페이지 절 → 맨 앞 · B05↔B06 짝 걷음 - 그리기: 덩어리마다 원문 줄(data-src) · `![설명](이름.webp)` → figure(loading=lazy · ?v=판) · 없는 그림 = 관리자 「그림 없음 — 더블클릭해 지정」 / 일반 「그림 준비 중」 · `> 주의:` · `> 참고:` 상자 · `[글](B06/00_설명서)` → 모달 안 이동 · 페이지를 안 넘기면(B01 지식 채팅) 옛 출력 그대로 - GET /api/help 에 페이지마다 그림 판 · GET /api/help/{page}/img/{name}(이름 규칙 · no-cache) · 옛 GET /api/help/{page} 걷음(모달이 한 가이드로 바뀜) - B01 대시보드 머리 역할 배지 왼쪽에 [?] - 시험 test_538_help_guide.py(변환 글 · 그림 404 · admin 칸) + helper_538_help_render.cjs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 08:47:38 +09:00
parent 0f32c241ca
commit 02f15c3d6a
6 changed files with 526 additions and 60 deletions
@@ -1,9 +1,11 @@
 /* =============================================================================
 * ui_template_help.ts
- * [?] 설명서(54-2) — 좌측 패널 아래 단추 묶음 맨 왼쪽 단추 + 모달(왼쪽 차례 · 오른쪽 글). B02~B09 공용.
- * 글 = `A05_EduDetail/guide/<페이지>/*.md` — 서버가 열 때마다 읽음(파일만 고치면 다음에 열 때 바뀜).
- * 페이지 = 주소(#/b05-…)의 B0N · 먼저 여는 항목 = 좌측 패널에서 보이는 `[data-help-topic]` 중 마지막
- * (지금 연 상자 · 구조물 종류) · 없으면 첫 파일(00_설명서).
+ * [?] 사용자 가이드(54-2 · 538) — 좌측 패널 아래 단추 묶음 맨 왼쪽 단추 + 넓은 모달(왼쪽 차례 · 오른쪽 가이드 통째).
+ * 글 = `A05_EduDetail/guide/<페이지>/*.md` — 서버가 열 때마다 읽음(`GET /api/help` 한 번에 모든 페이지).
+ * 차례 = 묶음(임도 설계 B → 안정성평가 E → 예정노선 D) → 페이지 → 기능 · 지금 페이지 펼침.
+ * 처음 자리 = 좌측 패널에서 보이는 `[data-help-topic]` 중 마지막 절(제 페이지 먼저 · 없으면 모든 페이지) ·
+ * 없으면 지금 페이지(#/b05-… → B05) 절 · 그것도 없으면 맨 앞.
+ * 시스템 관리자 = 더블클릭 바로 고침(`ui_template_help_edit.ts`).
 * 단추 자리 = `.ui-sidebar-actions` 안 `[data-help-row]`(없으면 그 줄 자신)의 맨 앞.
 * [<] [>](요구 280-2) = [?] 바로 뒤 · 단계 묶음(B05~B09 · D02~D04 · E02~E05 · 529-1) 주소만 · 누르면 `ui-step-nav` 를 올려 보냄 →
 * 진행 단계 틀(`createWorkflowLayout`)이 이웃 단계 단추를 누름(저장 · 막힘은 각 페이지 `onStepClick`).
@@ -14,14 +16,43 @@ import { API_BASE_URL, PLAN_STEP_ROUTES, ROUTES, STAB_STEP_ROUTES } from "@confi
 import { createButton, el } from "./ui_template_elements";
 import { openModal } from "./ui_template_modal";

-interface HelpItem {
+export interface HelpItem {
  key: string;
  title: string;
  text: string;
+  version: string;
 }

-const TEXT = { button: "?", tip: "설명서", title: "설명서", close: "닫기", empty: "설명 글 없음" };
+export interface HelpPage {
+  page: string;
+  title: string;
+  items: HelpItem[];
+  /** 그림 이름 → 판(고친 시각) */
+  images: Record<string, string>;
+}
+
+export interface HelpGuide {
+  pages: HelpPage[];
+  admin: boolean;
+}
+
+const TEXT = {
+  button: "?",
+  tip: "사용자 가이드",
+  title: "사용자 가이드",
+  close: "닫기",
+  empty: "가이드 글 없음",
+  imgMissing: "그림 없음 — 더블클릭해 지정",
+  imgPending: "그림 준비 중",
+};
 const STEP_TEXT = { prev: "<", next: ">", prevTip: "이전 단계", nextTip: "다음 단계" };
+/** 차례 묶음 — 페이지 머리 글자 */
+const GROUPS = [
+  { label: "임도 설계", prefix: "B" },
+  { label: "안정성평가", prefix: "E" },
+  { label: "예정노선", prefix: "D" },
+];
+const IMG_RE = /^[A-Za-z0-9_-]+\.(webp|png|jpg)$/;

 /** [<] [>] 를 붙이는 주소 묶음 — 묶음 안에서만 오감(b09-print · B03 · B04 · M01 · M02 · D01 · E01 뺌) */
 const STEP_NAV_GROUPS: ReadonlyArray<readonly string[]> = [
@@ -36,7 +67,7 @@ const STEP_NAV_GROUPS: ReadonlyArray<readonly string[]> = [
  STAB_STEP_ROUTES,
 ];

-/** 설명서 폴더 이름 = 주소 머리(#/b05-… → B05 · #/d02-… → D02) */
+/** 가이드 폴더 이름 = 주소 머리(#/b05-… → B05 · #/d02-… → D02) */
 function currentPage(): string {
  const head = /^#\/([bde]0\d)/i.exec(location.hash)?.[1];
  return head ? head.toUpperCase() : "";
@@ -49,18 +80,53 @@ function escapeHtml(text: string): string {
  );
 }

-function inline(text: string): string {
-  return escapeHtml(text)
+/** 가이드 안 링크 `[글](B06/00_설명서)` · `[글](B06)` — 파일 이름 속 괄호 한 겹까지 */
+const GOTO_RE = /\[([^\]]+)\]\(([BDE]\d{2}(?:\/(?:[^()]|\([^()]*\))+)?)\)/g;
+
+function inline(text: string, links = false): string {
+  const html = escapeHtml(text)
    .replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>")
    .replace(/`(.+?)`/g, "<code>$1</code>");
+  return links
+    ? html.replace(GOTO_RE, '<a href="#" class="ui-help-goto" data-help-goto="$2">$1</a>')
+    : html;
 }

-/** 메모장 글에 쓸 만큼만 — 제목(#) · 목록(- · 1.) · 문단 · **굵게** · `코드` */
-export function renderHelpMarkdown(text: string): string {
+/** 페이지를 넘긴 때만 — 덩어리 원문 줄(`data-src`) · 그림 · 주의/참고 상자 · 가이드 안 링크 */
+export interface HelpRenderContext {
+  page: string;
+  images: Record<string, string>;
+  admin: boolean;
+}
+
+function figure(alt: string, name: string, ctx: HelpRenderContext): string {
+  const version = ctx.images[name];
+  const img = version
+    ? `<img src="${API_BASE_URL}/help/${ctx.page}/img/${name}?v=${version}" alt="${escapeHtml(alt)}" loading="lazy">`
+    : `<div class="ui-help-figure__empty">${ctx.admin ? TEXT.imgMissing : TEXT.imgPending}</div>`;
+  const caption = alt ? `<figcaption>${inline(alt)}</figcaption>` : "";
+  return `<figure class="ui-help-figure" data-img="${name}">${img}${caption}</figure>`;
+}
+
+function note(lines: string[], src: string): string {
+  const body = lines.map((line) => line.replace(/^>\s?/, ""));
+  const head = /^(주의|참고)\s*[:：]\s*(.*)$/.exec(body[0]);
+  if (head) body[0] = head[2];
+  const kind = head?.[1] === "주의" ? "warn" : "info";
+  return `<aside class="ui-help-note ui-help-note--${kind}"${src}><strong>${head?.[1] ?? "참고"}</strong> ${body.map((line) => inline(line, true)).join("<br>")}</aside>`;
+}
+
+/** 메모장 글에 쓸 만큼만 — 제목(#) · 목록(- · 1.) · 표 · 문단 · **굵게** · `코드` (+ ctx 때 그림 · 상자 · 링크) */
+export function renderHelpMarkdown(text: string, ctx?: HelpRenderContext): string {
  const out: string[] = [];
  let list: "ul" | "ol" | null = null;
  let para: string[] = [];
+  let start = 0;
+  let end = 0;
+  let listAt = 0;
+  let listFrom = 0;
  const lines = text.split(/\r?\n/);
+  const src = (from: number, to: number): string => (ctx ? ` data-src="${from}-${to}"` : "");
  const cells = (line: string): string[] =>
    line
      .trim()
@@ -70,7 +136,8 @@ export function renderHelpMarkdown(text: string): string {
  const separator = (line: string): boolean =>
    cells(line).every((cell) => /^:?-{3,}:?$/.test(cell));
  const flush = (): void => {
-    if (para.length) out.push(`<p>${para.map(inline).join("<br>")}</p>`);
+    if (para.length)
+      out.push(`<p${src(start, end)}>${para.map((l) => inline(l, !!ctx)).join("<br>")}</p>`);
    para = [];
    if (list) out.push(`</${list}>`);
    list = null;
@@ -80,30 +147,49 @@ export function renderHelpMarkdown(text: string): string {
    const line = raw.trim();
    if (line.includes("|") && lines[index + 1]?.includes("|") && separator(lines[index + 1])) {
      flush();
+      const from = index;
      const headers = cells(line);
      const rows: string[][] = [];
      index += 2;
      while (index < lines.length && lines[index].includes("|")) rows.push(cells(lines[index++]));
      index -= 1;
      out.push(
-        `<div class="ui-markdown-table"><table><thead><tr>${headers.map((cell) => `<th>${inline(cell)}</th>`).join("")}</tr></thead><tbody>${rows.map((row) => `<tr>${headers.map((_, cell) => `<td>${inline(row[cell] ?? "")}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`,
+        `<div class="ui-markdown-table"${src(from, index)}><table><thead><tr>${headers.map((cell) => `<th>${inline(cell, !!ctx)}</th>`).join("")}</tr></thead><tbody>${rows.map((row) => `<tr>${headers.map((_, cell) => `<td>${inline(row[cell] ?? "", !!ctx)}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`,
      );
      continue;
    }
    const head = /^(#{1,4})\s+(.*)$/.exec(line);
    const item = /^(?:([-*])|\d+\.)\s+(.*)$/.exec(line);
+    const image = ctx && /^!\[([^\]]*)\]\(([^)\s]+)\)$/.exec(line);
    if (!line) flush();
-    else if (head) {
+    else if (ctx && line.startsWith(">")) {
      flush();
-      out.push(`<h${head[1].length + 1}>${inline(head[2])}</h${head[1].length + 1}>`);
+      const from = index;
+      while (lines[index + 1]?.trim().startsWith(">")) index += 1;
+      const quote = lines.slice(from, index + 1).map((l) => l.trim());
+      out.push(note(quote, src(from, index)));
+    } else if (image && IMG_RE.test(image[2])) {
+      flush();
+      out.push(figure(image[1], image[2], ctx).replace("<figure", `<figure${src(index, index)}`));
+    } else if (head) {
+      flush();
+      const level = head[1].length + 1;
+      out.push(`<h${level}${src(index, index)}>${inline(head[2], !!ctx)}</h${level}>`);
    } else if (item) {
      const kind = item[1] ? "ul" : "ol";
      if (para.length || list !== kind) flush();
-      if (!list) out.push(`<${kind}>`);
+      if (!list) {
+        listAt = out.length;
+        listFrom = index;
+        out.push("");
+      }
      list = kind;
-      out.push(`<li>${inline(item[2])}</li>`);
+      out.push(`<li>${inline(item[2], !!ctx)}</li>`);
+      out[listAt] = `<${kind}${src(listFrom, index)}>`;
    } else {
      if (list) flush();
+      if (!para.length) start = index;
+      end = index;
      para.push(line);
    }
  }
@@ -118,51 +204,111 @@ function visibleTopics(): string[] {
    .map((node) => node.dataset.helpTopic ?? "");
 }

-async function fetchItems(page: string): Promise<HelpItem[]> {
-  const response = await fetch(`${API_BASE_URL}/help/${page}`, {
+async function fetchGuide(): Promise<HelpGuide> {
+  const response = await fetch(`${API_BASE_URL}/help`, {
    credentials: "include",
    cache: "no-store",
  });
-  return response.ok ? ((await response.json()) as { items: HelpItem[] }).items : [];
+  return response.ok ? ((await response.json()) as HelpGuide) : { pages: [], admin: false };
 }

-/** B05 · B06 = 한 페이지(구조물 폼 공유) — 제 폴더 뒤에 짝 폴더 항목(짝의 설명서는 뺌)도 보임 */
-const PAIR: Record<string, string> = { B05: "B06", B06: "B05" };
+/** 한 기능 절 — 자리 이름 `B05/00_설명서` */
+export function renderHelpItem(page: HelpPage, item: HelpItem, admin: boolean): string {
+  const ctx = { page: page.page, images: page.images, admin };
+  return renderHelpMarkdown(item.text, ctx);
+}
+
+function anchorOf(page: string, key?: string): string {
+  return key ? `${page}/${key}` : page;
+}
+
+/** 처음 자리 — 보이는 주제(제 페이지 먼저 · 없으면 모든 페이지) → 지금 페이지 → 맨 앞 */
+function firstAnchor(pages: HelpPage[]): string {
+  const page = currentPage();
+  const topics = visibleTopics().reverse();
+  const own = pages.find((p) => p.page === page);
+  for (const scope of own ? [[own], pages] : [pages])
+    for (const key of topics) {
+      const hit = scope.find((p) => p.items.some((item) => item.key === key));
+      if (hit) return anchorOf(hit.page, key);
+    }
+  return own ? page : (pages[0]?.page ?? "");
+}

 async function openHelp(): Promise<void> {
-  const page = currentPage();
-  const pair = PAIR[page];
-  const [own, other] = await Promise.all([fetchItems(page), pair ? fetchItems(pair) : []]);
-  const items = [...own, ...other.filter((item) => !own.some((o) => o.key === item.key))];
-  const topics = visibleTopics();
-  const first = [...topics].reverse().find((key) => items.some((item) => item.key === key));
+  const guide = await fetchGuide();
+  const pages = GROUPS.flatMap((g) => guide.pages.filter((p) => p.page.startsWith(g.prefix)));
+  const start = firstAnchor(pages);
+  let flush = async (): Promise<boolean> => true;
  openModal({
-    title: `${TEXT.title} · ${page}`,
+    title: TEXT.title,
    closeLabel: TEXT.close,
    dialogClass: "ui-help",
+    wide: true,
+    beforeClose: () => flush(),
    mount: (body) => {
      const article = el("article", { className: "ui-help__text" });
      const toc = el("nav", { className: "ui-help__toc" });
-      const show = (key: string): void => {
-        const item = items.find((entry) => entry.key === key);
-        article.innerHTML = item ? renderHelpMarkdown(item.text) : `<p>${TEXT.empty}</p>`;
-        article.dataset.helpKey = key;
+      const tocPage = new Map<string, HTMLElement>();
+      const goTo = (anchor: string): void => {
+        const page = anchor.split("/")[0];
+        const target = article.querySelector<HTMLElement>(
+          `[data-help-anchor="${CSS.escape(anchor)}"]`,
+        );
+        target?.scrollIntoView({ block: "start" });
+        tocPage.forEach((box, key) => box.classList.toggle("is-open", key === page));
        toc
-          .querySelectorAll("button")
-          .forEach((b) => b.classList.toggle("is-active", b.dataset.helpKey === key));
+          .querySelectorAll<HTMLElement>("[data-help-goto]")
+          .forEach((b) => b.classList.toggle("is-active", b.dataset.helpGoto === anchor));
      };
-      for (const item of items) {
-        const link = el("button", {
-          className: "ui-help__link",
-          text: item.title,
-          attrs: { type: "button" },
-        });
-        link.dataset.helpKey = item.key;
-        link.addEventListener("click", () => show(item.key));
-        toc.append(link);
+      const link = (text: string, anchor: string, className: string): HTMLButtonElement => {
+        const button = el("button", { className, text, attrs: { type: "button" } });
+        button.dataset.helpGoto = anchor;
+        button.addEventListener("click", () => goTo(anchor));
+        return button;
+      };
+      for (const group of GROUPS) {
+        const own = pages.filter((p) => p.page.startsWith(group.prefix));
+        if (!own.length) continue;
+        toc.append(el("p", { className: "ui-help__group", text: group.label }));
+        for (const page of own) {
+          const subs = page.items
+            .filter((item) => item.key !== "00_설명서")
+            .map((item) => link(item.title, anchorOf(page.page, item.key), "ui-help__link--sub"));
+          const box = el("div", {
+            className: "ui-help__toc-page",
+            children: [
+              link(page.title, page.page, "ui-help__link"),
+              el("div", { className: "ui-help__subs", children: subs }),
+            ],
+          });
+          tocPage.set(page.page, box);
+          toc.append(box);
+        }
      }
+      for (const page of pages) {
+        const section = el("section", { className: "ui-help__page" });
+        section.dataset.helpAnchor = page.page;
+        for (const item of page.items) {
+          const part = el("section", { className: "ui-help__item" });
+          part.dataset.helpAnchor = anchorOf(page.page, item.key);
+          part.dataset.page = page.page;
+          part.dataset.key = item.key;
+          part.innerHTML = renderHelpItem(page, item, guide.admin);
+          section.append(part);
+        }
+        article.append(section);
+      }
+      if (!pages.length) article.append(el("p", { text: TEXT.empty }));
+      article.addEventListener("click", (ev) => {
+        const goto = (ev.target as HTMLElement).closest<HTMLElement>("a.ui-help-goto");
+        if (!goto) return;
+        ev.preventDefault();
+        goTo(goto.dataset.helpGoto ?? "");
+      });
      body.append(el("div", { className: "ui-help__grid", children: [toc, article] }));
-      show(first ?? items[0]?.key ?? "");
+      // 모달이 붙은 뒤 이동 — mount 는 붙기 전
+      requestAnimationFrame(() => goTo(start));
    },
  });
 }