feat(project): add help search and detailed guides

This commit is contained in:
2026-10-03 09:41:09 +09:00
parent 7647e4b20f
commit cd0a509215
7 changed files with 648 additions and 58 deletions
+81
View File
@@ -0,0 +1,81 @@
// 실제 Chromium + ERP 셸에서 검색·이동과 데스크톱/모바일 표시 검증(DB 미사용).
// python tests/js/render_help.py
// PJ_TEST_BROWSER=<설치된 Chrome 경로> node tests/js/help.browser.test.js (playwright 필요)
const assert = require("node:assert/strict");
const fs = require("node:fs");
const http = require("node:http");
const path = require("node:path");
const { chromium } = require("playwright");
const ROOT = path.resolve(__dirname, "../..");
const STATIC = path.join(ROOT, "app/static");
const OUT = path.join(__dirname, ".out");
const server = http.createServer(function (req, res) {
const url = new URL(req.url, "http://localhost");
if (url.pathname === "/project/help") {
res.setHeader("Content-Type", "text/html; charset=utf-8");
res.end(fs.readFileSync(path.join(OUT, "help_render.html"))); return;
}
const file = path.resolve(STATIC, "." + decodeURIComponent(url.pathname.slice(7)));
if (!url.pathname.startsWith("/static/") || !file.startsWith(STATIC + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile()) {
res.statusCode = 404; res.end(); return;
}
const types = { ".css": "text/css", ".js": "text/javascript", ".woff2": "font/woff2", ".woff": "font/woff", ".png": "image/png" };
res.setHeader("Content-Type", types[path.extname(file)] || "application/octet-stream");
fs.createReadStream(file).pipe(res);
});
(async function () {
let browser;
try {
await new Promise(resolve => server.listen(0, "127.0.0.1", resolve));
browser = await chromium.launch({ headless: true, executablePath: process.env.PJ_TEST_BROWSER || undefined });
const page = await browser.newPage({ viewport: { width: 1600, height: 1000 } });
const errors = [], mutations = [];
page.on("pageerror", e => errors.push(e.message));
page.on("request", r => { if (r.method() !== "GET") mutations.push(r.url()); });
await page.goto("http://127.0.0.1:" + server.address().port + "/project/help");
await page.locator("#pjh-query").waitFor({ state: "visible" });
await page.locator("#pjh-query").fill("셀 병합");
const first = page.locator("#pjh-results a").first();
assert.equal(await first.getAttribute("href"), "#goals-merge");
await page.screenshot({ path: path.join(OUT, "help-desktop.png") });
await first.click();
assert.equal(await page.evaluate(() => document.activeElement.id), "goals-merge");
assert.ok(await page.locator("#goals-merge").isVisible());
const rect = await page.locator("#goals-merge").boundingBox();
assert.ok(rect.y >= 0 && rect.y < 300, "앵커 이동 후 소제목이 화면 위에 표시");
await page.screenshot({ path: path.join(OUT, "help-goals.png") });
await page.keyboard.press("/");
await page.locator("#pjh-query").fill("쇼핑몰 연결");
await page.locator("#pjh-query").press("Enter");
assert.equal(await page.evaluate(() => document.activeElement.id), "meetings-markets");
await page.reload();
await page.locator("#pjh-query").waitFor({ state: "visible" });
assert.equal(await page.locator("#pjh-query").inputValue(), "쇼핑몰 연결");
assert.equal(await page.evaluate(() => document.activeElement.id), "meetings-markets");
await page.goBack();
assert.equal(await page.evaluate(() => document.activeElement.id), "goals-merge");
assert.equal(await page.locator("#pjh-query").inputValue(), new URL(page.url()).searchParams.get("q"), "뒤로 간 주소의 검색어 복원");
await page.setViewportSize({ width: 390, height: 844 });
await page.waitForFunction(() => document.querySelector(".erp-sidebar").getBoundingClientRect().right <= 1);
await page.keyboard.press("/");
await page.locator("#pjh-query").fill("회의록");
await page.screenshot({ path: path.join(OUT, "help-mobile.png") });
assert.ok(await page.locator("#pjh-query").isVisible(), "모바일에서 목차가 숨겨져도 검색 유지");
const widths = await page.evaluate(() => {
const nodes = [document.documentElement, document.querySelector(".erp-page"), document.querySelector(".pjh"), document.querySelector(".pjh-body")];
return nodes.map(n => ({ name: n.className || n.tagName, scroll: n.scrollWidth, client: n.clientWidth }));
});
assert.ok(widths.every(n => n.scroll <= n.client + 1), "모바일에서 가로 넘침 없음: " + JSON.stringify(widths));
await page.locator('#pjh-results a[href="#meetings-review"]').click();
assert.equal(await page.evaluate(() => document.activeElement.id), "meetings-review");
await page.screenshot({ path: path.join(OUT, "help-meeting-mobile.png") });
assert.deepEqual(errors, [], "브라우저 JS 오류 없음");
assert.deepEqual(mutations, [], "도움말 검색은 데이터 쓰기 요청 없음");
console.log("ALL PASS — Chromium 검색·Enter·새로고침·뒤로 가기·390px 모바일 레이아웃");
} finally {
if (browser) await browser.close();
await new Promise(resolve => server.close(resolve));
}
})().catch(function (e) { console.error(e); process.exitCode = 1; });
+100
View File
@@ -0,0 +1,100 @@
// python tests/js/render_help.py && node tests/js/help_ui.test.js (jsdom 필요)
const assert = require("node:assert/strict");
const fs = require("node:fs");
const path = require("node:path");
const { JSDOM } = require("jsdom");
const ROOT = path.resolve(__dirname, "../..");
const html = fs.readFileSync(path.join(__dirname, ".out/help_render.html"), "utf8");
const js = fs.readFileSync(path.join(ROOT, "app/static/project-help.js"), "utf8");
function boot(url) {
const dom = new JSDOM(html, { url: url || "http://localhost/project/help", runScripts: "outside-only" });
const w = dom.window;
w.HTMLElement.prototype.scrollIntoView = function () { w.lastScroll = this.id; };
w.eval(js);
return dom;
}
const dom = boot(), w = dom.window, d = w.document;
const input = d.getElementById("pjh-query");
function search(query) { input.value = query; input.dispatchEvent(new w.Event("input", { bubbles: true })); }
function links() { return Array.from(d.querySelectorAll("#pjh-results a")); }
function reset() { d.getElementById("pjh-search-clear").click(); }
assert.equal(d.querySelectorAll(".pjh-sec").length, 22);
assert.equal(d.querySelectorAll(".pjh-toc a").length, 22);
assert.equal(d.getElementById("pjh-search").hidden, false);
assert.equal(d.getElementById("pjh-results").hidden, true);
const ids = Array.from(d.querySelectorAll("[id]")).map(n => n.id);
assert.equal(new Set(ids).size, ids.length, "앵커 ID는 중복 없음");
Array.from(d.querySelectorAll('.pjh a[href^="#"]')).forEach(function (link) {
assert.ok(d.getElementById(link.getAttribute("href").slice(1)), "도움말 내부 링크 유효");
});
search("셀 병합");
assert.equal(links()[0].hash, "#goals-merge", "소제목 일치를 먼저 표시");
assert.ok(links()[0].querySelector("mark"));
assert.ok(d.querySelector("#goals mark"), "본문도 일치어 강조");
links()[0].click();
assert.equal(w.location.hash, "#goals-merge");
assert.equal(d.activeElement.id, "goals-merge", "결과 클릭은 해당 소제목에 포커스");
assert.equal(w.lastScroll, "goals-merge");
assert.equal(d.querySelector('.pjh-toc [aria-current="location"]').hash, "#goals");
assert.equal(new URL(w.location.href).searchParams.get("q"), "셀 병합");
search("7일 전");
assert.ok(links().some(a => a.hash === "#meetings-review"), "제목에 없는 본문 단어도 검색");
search("쇼핑몰 연결");
assert.equal(links()[0].hash, "#meetings-markets");
d.getElementById("pjh-search-form").dispatchEvent(new w.Event("submit", { bubbles: true, cancelable: true }));
assert.equal(d.activeElement.id, "meetings-markets", "Enter/submit은 첫 결과 이동");
const original = d.getElementById("meetings").textContent;
search("ROAS");
assert.ok(links().some(a => a.hash === "#goals-metrics"), "영문 대소문자 구분 안 함");
search("로아스");
assert.ok(links().length > 0, "한글 검색");
search("원");
assert.ok(links().length > 0, "한 글자 검색");
search(" 쇼핑몰 연결 ");
assert.equal(links()[0].hash, "#meetings-markets", "연속 공백·여러 단어 검색");
search("zz-no-help-match");
assert.equal(links().length, 0);
assert.match(d.getElementById("pjh-search-status").textContent, /결과가 없습니다/);
search("<img src=x onerror=alert(1)>");
assert.equal(links().length, 0, "HTML을 검색어 문자열로만 처리");
assert.equal(d.querySelector('img[src="x"]'), null);
search("[");
assert.equal(links().length, 0, "정규식 특수문자에도 예외 없음");
reset();
assert.equal(input.value, "");
assert.equal(d.getElementById("pjh-results").hidden, true);
assert.equal(d.querySelectorAll("mark.pjh-match").length, 0);
assert.equal(d.getElementById("meetings").textContent, original, "검색·초기화 뒤 원문 보존");
assert.equal(new URL(w.location.href).searchParams.has("q"), false);
assert.equal(d.activeElement, input);
search("분기");
input.dispatchEvent(new w.KeyboardEvent("keydown", { key: "Escape", bubbles: true, cancelable: true }));
assert.equal(input.value, "");
d.body.dispatchEvent(new w.KeyboardEvent("keydown", { key: "/", bubbles: true, cancelable: true }));
assert.equal(d.activeElement, input, "/ 단축키는 도움말 검색");
search("셀 병합");
input.dispatchEvent(new w.CompositionEvent("compositionstart", { bubbles: true }));
input.value = "회의록";
input.dispatchEvent(new w.Event("input", { bubbles: true }));
const before = w.location.hash;
d.getElementById("pjh-search-form").dispatchEvent(new w.Event("submit", { cancelable: true }));
assert.equal(w.location.hash, before, "한글 조합 중 submit은 이동 안 함");
assert.equal(links()[0].hash, "#goals-merge", "조합 중 검색 안 함");
input.dispatchEvent(new w.CompositionEvent("compositionend", { bubbles: true }));
assert.ok(links().some(a => a.hash === "#meetings-intro"), "조합 확정 뒤 검색");
const restored = boot("http://localhost/project/help?q=" + encodeURIComponent("쇼핑몰 연결") + "#meetings-markets");
assert.equal(restored.window.document.getElementById("pjh-query").value, "쇼핑몰 연결");
assert.equal(restored.window.document.activeElement.id, "meetings-markets", "공유 링크·새로고침 복원");
w.history.pushState(null, "", "/project/help?q=" + encodeURIComponent("셀 병합") + "#goals-merge");
w.dispatchEvent(new w.PopStateEvent("popstate"));
assert.equal(input.value, "셀 병합");
assert.equal(d.activeElement.id, "goals-merge", "뒤로 가기 위치·검색 복원");
restored.window.close();
dom.window.close();
console.log("ALL PASS — 도움말 검색·앵커·한글 조합·안전한 문자열·초기화·URL 복원");
+25
View File
@@ -0,0 +1,25 @@
"""실제 ERP 기본 템플릿으로 도움말을 렌더한다. DB·운영 사용자 데이터 미사용.
python tests/js/render_help.py -> tests/js/.out/help_render.html
"""
from pathlib import Path
import jinja2
ROOT = Path(__file__).resolve().parents[2]
env = jinja2.Environment(
loader=jinja2.ChoiceLoader([
jinja2.FileSystemLoader(ROOT / "app/modules/project/templates"),
jinja2.FileSystemLoader(ROOT / "app/templates"),
]),
autoescape=jinja2.select_autoescape(["html"]),
)
html = env.get_template("project/help.html").render(
user={"email": "reader@test.local", "name": "Reader", "is_super_admin": False},
is_admin=False, nav_items=[], force_sidebar_collapsed=True,
page_title="프로젝트 관리 도움말", page_subtitle="처음 쓰는 분을 위한 기능 안내",
)
out = ROOT / "tests/js/.out/help_render.html"
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(html, encoding="utf-8")
print("rendered:", out)