Refine web UI and usage docs

web/device_query.html

@@ -346,6 +346,10 @@
       margin-top: 12px;
       flex-wrap: wrap;
     }
+    .btns + .sub,
+    .btns + .field-tip {
+      margin-top: 10px;
+    }
     button {
       border: 0;
       border-radius: 10px;
@@ -558,6 +562,9 @@
       padding: 14px 16px;
       font-weight: 700;
       color: #1f355a;
+      user-select: none;
+      -webkit-user-select: none;
+      -webkit-tap-highlight-color: transparent;
     }
     .collapse-card summary::-webkit-details-marker {
       display: none;
@@ -660,33 +667,166 @@
       margin: 24px auto;
       padding: 0 16px 32px;
       display: grid;
+      grid-template-columns: 240px minmax(0, 1fr);
       gap: 16px;
     }
-    .doc-link-list {
-      display: flex;
-      flex-wrap: wrap;
-      gap: 10px;
-      margin-top: 12px;
+    .doc-sidebar {
+      align-self: start;
+      position: sticky;
+      top: calc(var(--nav-height) + 24px);
+      padding: 12px;
+      max-height: calc(100vh - var(--nav-height) - 40px);
+      overflow: hidden;
+      display: grid;
+      grid-template-rows: minmax(0, 1fr);
     }
-    .doc-link {
-      display: inline-flex;
-      align-items: center;
-      padding: 8px 12px;
+    .doc-preview {
+      min-width: 0;
+      padding: 18px;
+    }
+    .doc-toc {
+      min-height: 0;
+      overflow: auto;
+      display: grid;
+      gap: 8px;
+      padding-right: 4px;
+    }
+    .doc-toc-section {
+      display: grid;
+      gap: 6px;
+      padding: 8px 0 10px;
+      border-bottom: 1px solid #e7edf7;
+    }
+    .doc-toc-section:last-child {
+      border-bottom: 0;
+      padding-bottom: 0;
+    }
+    .doc-toc-title {
+      padding: 0 4px;
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: 0.02em;
+      color: #587095;
+      text-transform: uppercase;
+    }
+    .doc-toc-links {
+      display: grid;
+      gap: 6px;
+    }
+    .doc-toc-link {
+      display: block;
+      padding: 7px 10px;
       border-radius: 10px;
-      border: 1px solid #d7e2f3;
-      background: #f8fbff;
-      color: #204470;
+      color: #33527f;
       text-decoration: none;
       font-size: 13px;
-      font-weight: 700;
+      line-height: 1.45;
+      background: transparent;
+      border: 1px solid transparent;
     }
-    .doc-link:hover {
-      background: #eef5ff;
+    .doc-toc-link:hover {
+      background: #f4f8ff;
+      border-color: #e0e8f6;
     }
-    .doc-link.active {
-      background: #0f6fff;
-      border-color: #0f6fff;
-      color: #fff;
+    .doc-toc-link.level-2 {
+      font-weight: 600;
+      color: #28466f;
+    }
+    .doc-toc-link.level-3 {
+      margin-left: 0;
+      font-size: 12px;
+    }
+    .doc-toc-link.level-4 {
+      margin-left: 12px;
+      font-size: 12px;
+    }
+    .markdown-body {
+      color: #223047;
+      font-size: 14px;
+      line-height: 1.75;
+    }
+    .markdown-body > :first-child {
+      margin-top: 0;
+    }
+    .markdown-body > :last-child {
+      margin-bottom: 0;
+    }
+    .markdown-body h1,
+    .markdown-body h2,
+    .markdown-body h3,
+    .markdown-body h4 {
+      margin: 1.2em 0 0.55em;
+      color: #1b2a42;
+      line-height: 1.35;
+    }
+    .markdown-body h1 { font-size: 32px; }
+    .markdown-body h2 { font-size: 24px; }
+    .markdown-body h3 { font-size: 19px; }
+    .markdown-body h4 { font-size: 16px; }
+    .markdown-body p,
+    .markdown-body ul,
+    .markdown-body ol,
+    .markdown-body blockquote {
+      margin: 0 0 1em;
+    }
+    .markdown-body ul,
+    .markdown-body ol {
+      padding-left: 22px;
+    }
+    .markdown-body li + li {
+      margin-top: 4px;
+    }
+    .markdown-body blockquote {
+      padding: 10px 14px;
+      border-left: 4px solid #cddcf6;
+      border-radius: 0 10px 10px 0;
+      background: #f7faff;
+      color: #52627a;
+    }
+    .markdown-body pre {
+      margin: 0 0 1em;
+      white-space: pre-wrap;
+      word-break: break-word;
+      font-size: 13px;
+      line-height: 1.65;
+      background: #f6f8fb;
+      border: 1px solid var(--line);
+      border-radius: 12px;
+      padding: 14px;
+      overflow: auto;
+    }
+    .markdown-body pre code {
+      padding: 0;
+      border: 0;
+      background: transparent;
+      color: inherit;
+      font-size: inherit;
+    }
+    .markdown-body code {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 0.92em;
+      padding: 1px 6px;
+      border-radius: 6px;
+      background: #edf3ff;
+      color: #294f88;
+      border: 1px solid #d7e3fb;
+    }
+    .markdown-body hr {
+      border: 0;
+      border-top: 1px solid #d8e1ef;
+      margin: 1.2em 0;
+    }
+    .markdown-body a {
+      color: #0f6fff;
+      text-decoration: none;
+    }
+    .markdown-body a:hover {
+      text-decoration: underline;
+    }
+    .markdown-body h2,
+    .markdown-body h3,
+    .markdown-body h4 {
+      scroll-margin-top: calc(var(--nav-height) + 20px);
     }
     .doc-section + .doc-section {
       margin-top: 14px;
@@ -700,6 +840,13 @@
       .query-sidebar {
         position: static;
       }
+      .doc-grid {
+        grid-template-columns: 1fr;
+      }
+      .doc-sidebar {
+        position: static;
+        max-height: none;
+      }
       .search-layout {
         grid-template-columns: 1fr;
       }
@@ -722,7 +869,7 @@
       <a href="/web/device_query.html" class="brand">MobileModels</a>
       <a href="/web/device_query.html" class="item" id="topNavQuery">设备查询</a>
       <a href="/web/brand_management.html" class="item">数据管理</a>
-      <a href="/web/device_query.html?view=docs" class="item" id="topNavDocs">相关文档</a>
+      <a href="/web/device_query.html?view=docs" class="item" id="topNavDocs">使用文档</a>
     </div>
   </nav>
 
@@ -734,18 +881,20 @@
     </div>
   </div>
 
-  <div id="indexQueryPanel" class="page-panel hidden">
+    <div id="indexQueryPanel" class="page-panel hidden">
   <div class="wrap query-wrap">
     <aside class="query-sidebar">
-      <article class="card sidebar-card">
-        <h2 class="title">使用提示</h2>
-        <ul class="compact-note-list">
-          <li>基于 <code>dist/device_index.json</code> 快速识别，适合联调和比对。</li>
-          <li>Android / iOS / HarmonyOS 一般只需要平台和 <code>model_raw</code>。</li>
-          <li>也支持直接输入常见设备名，例如 <code>iPad mini 7</code>。</li>
-          <li>归一化规则：转小写，只保留字母数字和中文，去掉空格与标点。</li>
-        </ul>
-      </article>
+      <details class="card collapse-card sidebar-card" open>
+        <summary>使用提示</summary>
+        <div class="collapse-body">
+          <ul class="compact-note-list">
+            <li>基于 <code>dist/device_index.json</code> 快速识别，适合联调和比对。</li>
+            <li>Android / iOS / HarmonyOS 一般只需要平台和 <code>model_raw</code>。</li>
+            <li>也支持直接输入常见设备名，例如 <code>iPad mini 7</code>。</li>
+            <li>归一化规则：转小写，只保留字母数字和中文，去掉空格与标点。</li>
+          </ul>
+        </div>
+      </details>
     </aside>
 
       <section class="grid query-main">
@@ -850,7 +999,7 @@
         </div>
       </article>
 
-      <details class="card collapse-card">
+      <details class="card collapse-card" open>
         <summary>调试数据</summary>
         <div class="collapse-body">
           <div class="collapse-section">
@@ -878,7 +1027,7 @@
               </ul>
             </div>
             <div class="collapse-section">
-              <p class="section-label">登录设备管理取字段</p>
+              <p class="section-label">设备管理取字段</p>
               <ul class="compact-note-list">
                 <li>设备展示名：<code>device_name</code></li>
                 <li>品牌展示：<code>market_brand</code>；为空时使用 <code>brand</code></li>
@@ -926,15 +1075,17 @@ NOH-AL00  -> nohal00</pre>
           </div>
         </details>
 
-        <article class="card sidebar-card">
-          <h2 class="title">只读连接参数</h2>
-          <div id="sqlReadonlyInfo" class="credential-grid">
-            <div class="credential-item">
-              <span class="credential-label">Host</span>
-              <p class="credential-value">加载中...</p>
+        <details class="card collapse-card sidebar-card" open>
+          <summary>只读连接参数</summary>
+          <div class="collapse-body">
+            <div id="sqlReadonlyInfo" class="credential-grid">
+              <div class="credential-item">
+                <span class="credential-label">Host</span>
+                <p class="credential-value">加载中...</p>
+              </div>
             </div>
           </div>
-        </article>
+        </details>
       </aside>
 
       <section class="grid query-main">
@@ -1038,7 +1189,7 @@ NOH-AL00  -> nohal00</pre>
           </div>
         </article>
 
-        <details class="card collapse-card">
+        <details class="card collapse-card" open>
           <summary>调试信息</summary>
           <div class="collapse-body">
             <div class="collapse-section">
@@ -1058,24 +1209,28 @@ NOH-AL00  -> nohal00</pre>
   <div id="deviceNameSqlQueryPanel" class="page-panel hidden">
     <div class="wrap query-wrap">
       <aside class="query-sidebar">
-        <article class="card sidebar-card">
-          <h2 class="title">使用提示</h2>
-          <ul class="compact-note-list">
-            <li>这里只接受设备名称，例如 <code>iPad mini 7</code>、<code>iPhone SE 3</code>。</li>
-            <li>会先尝试别名映射，再做 <code>device_name</code> / <code>ver_name</code> 查询。</li>
-            <li>底层仍查询 <code>mobilemodels.mm_device_catalog</code>，用于和设备标识查询对齐。</li>
-            <li>只读连接参数固定展示在左侧，执行 SQL 和返回 JSON 保留在下方调试信息。</li>
-          </ul>
-        </article>
-        <article class="card sidebar-card">
-          <h2 class="title">只读连接参数</h2>
-          <div id="deviceNameSqlReadonlyInfo" class="credential-grid">
-            <div class="credential-item">
-              <span class="credential-label">Host</span>
-              <p class="credential-value">加载中...</p>
+        <details class="card collapse-card sidebar-card" open>
+          <summary>使用提示</summary>
+          <div class="collapse-body">
+            <ul class="compact-note-list">
+              <li>这里只接受设备名称，例如 <code>iPad mini 7</code>、<code>iPhone SE 3</code>。</li>
+              <li>会先尝试别名映射，再做 <code>device_name</code> / <code>ver_name</code> 查询。</li>
+              <li>底层仍查询 <code>mobilemodels.mm_device_catalog</code>，用于和设备标识查询对齐。</li>
+              <li>只读连接参数固定展示在左侧，执行 SQL 和返回 JSON 保留在下方调试信息。</li>
+            </ul>
+          </div>
+        </details>
+        <details class="card collapse-card sidebar-card" open>
+          <summary>只读连接参数</summary>
+          <div class="collapse-body">
+            <div id="deviceNameSqlReadonlyInfo" class="credential-grid">
+              <div class="credential-item">
+                <span class="credential-label">Host</span>
+                <p class="credential-value">加载中...</p>
+              </div>
             </div>
           </div>
-        </article>
+        </details>
       </aside>
 
       <section class="grid query-main">
@@ -1122,7 +1277,7 @@ NOH-AL00  -> nohal00</pre>
           </div>
         </article>
 
-        <details class="card collapse-card">
+        <details class="card collapse-card" open>
           <summary>调试信息</summary>
           <div class="collapse-body">
             <div class="collapse-section">
@@ -1141,20 +1296,12 @@ NOH-AL00  -> nohal00</pre>
 
   <div id="docsPanel" class="page-panel hidden">
     <div class="doc-grid">
-      <article class="card">
-        <h1 class="title">相关文档</h1>
-        <p class="sub">这里保留完整文档阅读；查询约定已经前移到各个查询页的使用提示里。</p>
-        <div class="doc-link-list">
-          <button type="button" class="doc-link active" data-doc-path="/docs/mysql-query-design.md" data-doc-title="MySQL 设计说明">MySQL 设计说明</button>
-          <button type="button" class="doc-link" data-doc-path="/docs/web-ui.md" data-doc-title="Web 使用说明">Web 使用说明</button>
-          <button type="button" class="doc-link" data-doc-path="/README.md" data-doc-title="项目 README">项目 README</button>
-        </div>
-      </article>
+      <aside class="card doc-sidebar">
+        <nav id="docPanelToc" class="doc-toc" aria-label="文档目录"></nav>
+      </aside>
 
-      <article class="card">
-        <h2 class="title" id="docPanelTitle">MySQL 设计说明</h2>
-        <p class="sub" id="docPanelPath">/docs/mysql-query-design.md</p>
-        <pre id="docPanelContent">加载中...</pre>
+      <article class="card doc-preview">
+        <div id="docPanelContent" class="markdown-body">加载中...</div>
       </article>
 
     </div>
@@ -1196,9 +1343,8 @@ NOH-AL00  -> nohal00</pre>
     const deviceNameSqlStatementEl = document.getElementById("deviceNameSqlStatement");
     const deviceNameSqlJsonOutputEl = document.getElementById("deviceNameSqlJsonOutput");
     const deviceNameSqlReadonlyInfoEl = document.getElementById("deviceNameSqlReadonlyInfo");
-    const docPanelTitleEl = document.getElementById("docPanelTitle");
-    const docPanelPathEl = document.getElementById("docPanelPath");
     const docPanelContentEl = document.getElementById("docPanelContent");
+    const docPanelTocEl = document.getElementById("docPanelToc");
     const indexQueryPanelEl = document.getElementById("indexQueryPanel");
     const sqlQueryPanelEl = document.getElementById("sqlQueryPanel");
     const deviceNameSqlQueryPanelEl = document.getElementById("deviceNameSqlQueryPanel");
@@ -2020,6 +2166,159 @@ NOH-AL00  -> nohal00</pre>
         .replace(/'/g, "&#39;");
     }
 
+    function renderInlineMarkdown(text) {
+      let html = escapeHtml(text || "");
+      html = html.replace(/`([^`]+)`/g, "<code>$1</code>");
+      html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+      html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2" target="_blank" rel="noreferrer">$1</a>');
+      return html;
+    }
+
+    function slugify(text) {
+      return String(text || "")
+        .toLowerCase()
+        .replace(/<[^>]+>/g, "")
+        .replace(/[^0-9a-z\u4e00-\u9fff]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "section";
+    }
+
+    function renderMarkdown(text) {
+      const normalized = String(text || "").replace(/\r\n/g, "\n");
+      const lines = normalized.split("\n");
+      const chunks = [];
+      const headingIds = new Map();
+      let i = 0;
+
+      while (i < lines.length) {
+        const line = lines[i];
+        const trimmed = line.trim();
+
+        if (!trimmed) {
+          i += 1;
+          continue;
+        }
+
+        if (trimmed.startsWith("```")) {
+          const lang = trimmed.slice(3).trim();
+          const codeLines = [];
+          i += 1;
+          while (i < lines.length && !lines[i].trim().startsWith("```")) {
+            codeLines.push(lines[i]);
+            i += 1;
+          }
+          if (i < lines.length) i += 1;
+          const className = lang ? ` class="language-${escapeHtml(lang)}"` : "";
+          chunks.push(`<pre><code${className}>${escapeHtml(codeLines.join("\n"))}</code></pre>`);
+          continue;
+        }
+
+        const heading = trimmed.match(/^(#{1,4})\s+(.*)$/);
+        if (heading) {
+          const level = heading[1].length;
+          const renderedText = renderInlineMarkdown(heading[2]);
+          const baseId = slugify(heading[2]);
+          const count = headingIds.get(baseId) || 0;
+          headingIds.set(baseId, count + 1);
+          const headingId = count ? `${baseId}-${count + 1}` : baseId;
+          chunks.push(`<h${level} id="${headingId}">${renderedText}</h${level}>`);
+          i += 1;
+          continue;
+        }
+
+        if (/^---+$/.test(trimmed) || /^___+$/.test(trimmed)) {
+          chunks.push("<hr />");
+          i += 1;
+          continue;
+        }
+
+        if (/^>\s?/.test(trimmed)) {
+          const quoteLines = [];
+          while (i < lines.length && /^>\s?/.test(lines[i].trim())) {
+            quoteLines.push(lines[i].trim().replace(/^>\s?/, ""));
+            i += 1;
+          }
+          chunks.push(`<blockquote>${renderInlineMarkdown(quoteLines.join(" "))}</blockquote>`);
+          continue;
+        }
+
+        if (/^[-*]\s+/.test(trimmed)) {
+          const items = [];
+          while (i < lines.length && /^[-*]\s+/.test(lines[i].trim())) {
+            items.push(lines[i].trim().replace(/^[-*]\s+/, ""));
+            i += 1;
+          }
+          chunks.push(`<ul>${items.map((item) => `<li>${renderInlineMarkdown(item)}</li>`).join("")}</ul>`);
+          continue;
+        }
+
+        if (/^\d+\.\s+/.test(trimmed)) {
+          const items = [];
+          while (i < lines.length && /^\d+\.\s+/.test(lines[i].trim())) {
+            items.push(lines[i].trim().replace(/^\d+\.\s+/, ""));
+            i += 1;
+          }
+          chunks.push(`<ol>${items.map((item) => `<li>${renderInlineMarkdown(item)}</li>`).join("")}</ol>`);
+          continue;
+        }
+
+        const paragraphLines = [];
+        while (i < lines.length) {
+          const candidate = lines[i];
+          const candidateTrim = candidate.trim();
+          if (!candidateTrim) break;
+          if (
+            candidateTrim.startsWith("```")
+            || /^(#{1,4})\s+/.test(candidateTrim)
+            || /^[-*]\s+/.test(candidateTrim)
+            || /^\d+\.\s+/.test(candidateTrim)
+            || /^>\s?/.test(candidateTrim)
+            || /^---+$/.test(candidateTrim)
+            || /^___+$/.test(candidateTrim)
+          ) {
+            break;
+          }
+          paragraphLines.push(candidateTrim);
+          i += 1;
+        }
+        chunks.push(`<p>${renderInlineMarkdown(paragraphLines.join(" "))}</p>`);
+      }
+
+      return chunks.join("");
+    }
+
+    function buildDocPanelToc(container) {
+      const headings = Array.from(container.querySelectorAll("h2, h3, h4"));
+      if (!headings.length) {
+        docPanelTocEl.innerHTML = `<div class="sub">当前文档没有可用目录。</div>`;
+        return;
+      }
+      const groups = [];
+      let currentGroup = null;
+      headings.forEach((heading) => {
+        const level = Number(heading.tagName.slice(1));
+        const item = {
+          id: heading.id,
+          text: escapeHtml(heading.textContent || ""),
+          level,
+        };
+        if (level === 2 || !currentGroup) {
+          currentGroup = { heading: item, children: [] };
+          groups.push(currentGroup);
+          return;
+        }
+        currentGroup.children.push(item);
+      });
+      docPanelTocEl.innerHTML = groups.map((group) => `
+        <section class="doc-toc-section">
+          <div class="doc-toc-title">${group.heading.text}</div>
+          <div class="doc-toc-links">
+            <a class="doc-toc-link level-${group.heading.level}" href="#${group.heading.id}">${group.heading.text}</a>
+            ${group.children.map((item) => `<a class="doc-toc-link level-${item.level}" href="#${item.id}">${item.text}</a>`).join("")}
+          </div>
+        </section>
+      `).join("");
+    }
+
     function activateTopTab(tabName) {
       document.querySelectorAll(".page-tab").forEach((el) => {
         const active = el.dataset.tab === tabName;
@@ -2066,14 +2365,7 @@ NOH-AL00  -> nohal00</pre>
     }
 
     async function loadDocInPanel(path, title) {
-      docPanelTitleEl.textContent = title || "相关文档";
-      docPanelPathEl.textContent = path || "";
-      docPanelContentEl.textContent = "加载中...";
-
-      document.querySelectorAll(".doc-link[data-doc-path]").forEach((el) => {
-        const active = el.dataset.docPath === path;
-        el.classList.toggle("active", active);
-      });
+      docPanelContentEl.innerHTML = "<p>加载中...</p>";
 
       try {
         const resp = await fetch(path, { cache: "no-store" });
@@ -2081,9 +2373,11 @@ NOH-AL00  -> nohal00</pre>
           throw new Error(`HTTP ${resp.status}`);
         }
         const text = await resp.text();
-        docPanelContentEl.textContent = text;
+        docPanelContentEl.innerHTML = renderMarkdown(text);
+        buildDocPanelToc(docPanelContentEl);
       } catch (err) {
-        docPanelContentEl.textContent = `加载失败\n${err.message || err}`;
+        docPanelContentEl.innerHTML = `<p>加载失败</p><pre>${escapeHtml(err.message || String(err))}</pre>`;
+        docPanelTocEl.innerHTML = "";
       }
     }
 
@@ -2308,10 +2602,6 @@ NOH-AL00  -> nohal00</pre>
           <span class="pill">命中方式: ${escapeHtml(output.match_strategy_label || strategyLabel)}</span>
         </div>
         <p class="sub">${description}</p>
-        <div class="helper-box">
-          <p class="helper-title">登录设备管理字段建议</p>
-          <p>推荐取 <code>device_name</code> / <code>market_brand</code>（为空退回 <code>brand</code>）/ <code>parent_brand</code>（为空退回 <code>manufacturer_brand</code>）/ <code>device_type</code>。</p>
-        </div>
         ${Array.isArray(output.resolved_device_names) && output.resolved_device_names.length
           ? `<div class="mono">设备名别名映射: ${escapeHtml(output.resolved_device_names.join(" | "))}</div>`
           : ""}
@@ -2439,19 +2729,13 @@ NOH-AL00  -> nohal00</pre>
       });
     });
 
-    document.querySelectorAll(".doc-link[data-doc-path]").forEach((el) => {
-      el.addEventListener("click", () => {
-        loadDocInPanel(el.dataset.docPath || "", el.dataset.docTitle || "相关文档");
-      });
-    });
-
     loadQueryFormState();
     bindQueryFormPersistence();
     loadActiveTopTab();
     syncReportPlatformUI();
     syncSqlPlatformUI();
     loadReadonlyInfo();
-    loadDocInPanel("/docs/mysql-query-design.md", "MySQL 设计说明");
+    loadDocInPanel("/README.md", "项目使用文档");
     loadIndexFromPath();
   </script>
 </body>