feat: PDF 电子书升级 — 专业封面 + 目录 + 作者(李强) + 元数据

- 封面：渐变色主题，标注作者李强、102 案例、8 大场景
- 目录：按分类排列，前置三篇指南
- 修复：过滤重定向页面，精准包含 102 个真实案例
- 页眉页脚：统一标题和页码
- 元数据：标题/作者/主题/关键词齐全
- 1.7 MB, 118 页
COMMITMSG && git push origin main 2>&1 | tail -3
__zcode_status=$?
if [ "$__zcode_status" -eq 0 ]; then pwd -P > '/var/folders/dj/m6cx71cs19n5w__rtgfl3n8m0000gn/T/zcode-b8ab4d6b-9d79-4ce2-a216-1cdc07c2d60c-cwd'; fi
exit "$__zcode_status"

Author: slowleelab

docs/public/sql-lab-cases.pdf

@@ -1,185 +1,170 @@
 /**
- * generate-pdf.js — 将 VitePress 文档站渲染为单个 PDF
- *
- * 用法:
- *   npm run docs:build   # 先构建
- *   npm run docs:pdf     # 再生成 PDF
- *
- * 输出: docs/public/sql-lab-cases.pdf
+ * generate-pdf.js — SQL Lab 电子书 PDF
+ * 封面 · 目录 · 作者(李强) · 元数据 · 页眉页脚
  */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs'
+import { writeFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'fs'
 import { resolve, dirname } from 'path'
 import { fileURLToPath } from 'url'
 import { createServer } from 'http'
 import { readFile } from 'fs/promises'
 import puppeteer from 'puppeteer'
 import { PDFDocument } from 'pdf-lib'
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const PROJECT_ROOT = resolve(__dirname, '..')
-const DIST_DIR = resolve(PROJECT_ROOT, 'docs/.vitepress/dist')
-const OUTPUT_FILE = resolve(PROJECT_ROOT, 'docs/public/sql-lab-cases.pdf')
-const BASE = '/sql-lab/'
-const PORT = 4173
-
-// ── 收集所有页面 URL ──
-function collectUrls() {
-  const guideUrls = [
-    '/guide/introduction',
-    '/guide/quick-start',
-    '/guide/how-to-read',
+const RD = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const DIST = resolve(RD, 'docs/.vitepress/dist')
+const OUT = resolve(RD, 'docs/public/sql-lab-cases.pdf')
+const AUTHOR = '李强'
+const PORT = 4175
+
+const CATEGORIES = [
+  { d: 'indexing', n: '一、索引设计与失效', s: 1, e: 18 },
+  { d: 'query-rewrite', n: '二、查询改写', s: 19, e: 32 },
+  { d: 'join', n: '三、JOIN 优化', s: 33, e: 41 },
+  { d: 'ddl', n: '四、DDL 与大表', s: 42, e: 51 },
+  { d: 'architecture', n: '五、架构级优化', s: 52, e: 62 },
+  { d: 'transaction', n: '六、事务与锁', s: 63, e: 71 },
+  { d: 'optimizer', n: '七、优化器与 8.0 新特性', s: 72, e: 80 },
+  { d: 'tidb', n: '八、TiDB 分布式优化', s: 81, e: 102 },
+]
+
+function collect() {
+  const guides = [
+    { u: '/guide/introduction', t: '项目介绍' },
+    { u: '/guide/quick-start', t: '快速开始' },
+    { u: '/guide/how-to-read', t: '如何阅读案例' },
   ]
-
-  const cats = ['indexing', 'query-rewrite', 'join', 'ddl',
-    'architecture', 'transaction', 'optimizer', 'tidb']
-
-  const urls = [...guideUrls]
-  for (const cat of cats) {
-    const d = resolve(DIST_DIR, 'cases', cat)
-    if (!existsSync(d)) continue
-    for (const f of readdirSync(d)) {
-      if (f.endsWith('.html')) {
-        urls.push(`/cases/${cat}/${f.replace('.html', '')}`)
+  const cases = []
+  for (const c of CATEGORIES) {
+    const dir = resolve(DIST, 'cases', c.d)
+    if (!existsSync(dir)) continue
+    for (const f of readdirSync(dir).filter(x => x.endsWith('.html'))) {
+      const slug = f.replace('.html', '')
+      const m = slug.match(/^(\d+)/)
+      if (!m) continue
+      const num = parseInt(m[1], 10)
+      if (num >= c.s && num <= c.e) {
+        // 跳过重定向页面
+        const fp = resolve(dir, f)
+        const content = readFileSync(fp, 'utf-8')
+        if (content.includes('http-equiv="refresh"')) continue
+        // 相同编号只保留第一个（实际案例优先于重定向）
+        if (cases.find(x => x.num === num)) continue
+        cases.push({ u: `/cases/${c.d}/${slug}`, num, cat: c.n, slug })
       }
     }
   }
-  return urls
+  cases.sort((a, b) => a.num - b.num)
+  return { guides, cases }
 }
 
-// ── VitePress 静态文件服务器 ──
 function startServer() {
-  return new Promise((resolvePromise, reject) => {
-    const server = createServer(async (req, res) => {
+  return new Promise((ok, fail) => {
+    const s = createServer(async (req, res) => {
       let url = new URL(req.url, `http://localhost:${PORT}`).pathname
-      if (url.startsWith(BASE)) url = url.slice(BASE.length - 1)
-      if (url === '' || url === '/') url = '/index.html'
-
-      let filePath = resolve(DIST_DIR, `.${url}`)
-      if (!existsSync(filePath)) filePath = `${filePath}.html`
-      if (!existsSync(filePath)) filePath = resolve(DIST_DIR, `.${url}/index.html`)
-
+      if (url.startsWith('/sql-lab/')) url = url.slice(9)
+      if (!url || url === '/') url = '/index.html'
+      let fp = resolve(DIST, `.${url}`)
+      if (!existsSync(fp)) { fp += '.html'; if (!existsSync(fp)) fp = resolve(DIST, `.${url}/index.html`) }
       try {
-        const content = await readFile(filePath)
-        const ext = filePath.endsWith('.html') ? 'text/html'
-          : filePath.endsWith('.js') ? 'application/javascript'
-          : filePath.endsWith('.css') ? 'text/css'
-          : filePath.endsWith('.svg') ? 'image/svg+xml'
-          : filePath.endsWith('.json') ? 'application/json'
-          : 'application/octet-stream'
-        res.writeHead(200, { 'Content-Type': ext })
-        res.end(content)
-      } catch {
-        res.writeHead(404)
-        res.end('Not Found')
-      }
+        const ct = await readFile(fp)
+        res.writeHead(200, { 'Content-Type': fp.endsWith('.html') ? 'text/html' : fp.endsWith('.js') ? 'text/javascript' : fp.endsWith('.css') ? 'text/css' : 'text/plain' })
+        res.end(ct)
+      } catch { res.writeHead(404); res.end('404') }
     })
-
-    server.listen(PORT, () => {
-      console.log(`  📡 http://localhost:${PORT}${BASE}`)
-      resolvePromise(server)
-    })
-    server.on('error', reject)
+    s.listen(PORT, () => ok(s))
+    s.on('error', fail)
   })
 }
 
-// ── 渲染单页为 PDF Buffer ──
-async function renderPage(browser, url, index, total) {
-  const page = await browser.newPage()
-  try {
-    const fullUrl = `http://localhost:${PORT}${BASE}${url.replace(/^\//, '')}`
-    process.stdout.write(`  [${String(index).padStart(3)}/${total}] ${fullUrl} `.padEnd(80) + '\r')
-
-    await page.goto(fullUrl, { waitUntil: 'networkidle0', timeout: 30000 })
-
-    // 移除导航栏、侧边栏、页脚
-    await page.evaluate(() => {
-      const remove = sel => document.querySelectorAll(sel).forEach(e => e.remove())
-      remove('.VPNav')
-      remove('.VPSidebar')
-      remove('.VPLocalNav')
-      remove('.VPFooter')
-      remove('.DocFooter')
-      remove('.edit-link')
-      remove('.prev-next')
-      remove('.VPDocAside')
-      remove('.VPNavScreen')
-    })
-
-    await page.evaluate(() => document.fonts.ready)
+async function htmlPdf(browser, html) {
+  const p = await browser.newPage()
+  try { await p.setContent(html, { waitUntil: 'load' }); await p.evaluate(() => document.fonts.ready); return await p.pdf({ format: 'A4', printBackground: true, margin: { top: 0, bottom: 0, left: 0, right: 0 } }) } finally { await p.close() }
+}
 
-    const pdfBuf = await page.pdf({
-      format: 'A4',
-      margin: { top: '20mm', bottom: '22mm', left: '18mm', right: '18mm' },
-      printBackground: true,
-      displayHeaderFooter: true,
-      headerTemplate: '<div style="font-size:8px;color:#999;text-align:center;width:100%;padding:4px 0;border-bottom:1px solid #e8e8e8">SQL Lab · MySQL + TiDB 优化实战案例集</div>',
-      footerTemplate: '<div style="font-size:8px;color:#999;text-align:center;width:100%;padding:4px 0;border-top:1px solid #e8e8e8"><span class="pageNumber"></span> / <span class="totalPages"></span></div>',
+async function pagePdf(browser, url, i, t) {
+  const p = await browser.newPage()
+  try {
+    const full = `http://localhost:${PORT}/sql-lab/${url.replace(/^\//, '')}`
+    process.stdout.write(`  [${String(i).padStart(3)}/${t}] ${url.slice(0, 60).padEnd(62)}\r`)
+    await p.goto(full, { waitUntil: 'networkidle0', timeout: 30000 })
+    await p.evaluate(() => {
+      for (const s of '.VPNav,.VPSidebar,.VPLocalNav,.VPFooter,.DocFooter,.edit-link,.prev-next,.VPDocAside,.VPNavScreen,.VPSkipLink'.split(',')) document.querySelectorAll(s).forEach(e => e.remove())
+      const d = document.querySelector('.VPDoc'); if (d) d.style.padding = '0 36px'
+      const c = document.querySelector('.VPContent'); if (c) c.style.paddingLeft = '0'
     })
+    await p.evaluate(() => document.fonts.ready)
+    const buf = await p.pdf({ format: 'A4', margin: { top: '22mm', bottom: '24mm', left: '18mm', right: '18mm' }, printBackground: true, displayHeaderFooter: true, headerTemplate: '<div style="font-size:7px;color:#bbb;text-align:center;width:100%;padding:4px 0;border-bottom:1px solid #eee">SQL Lab · MySQL + TiDB  优化实战案例集</div>', footerTemplate: '<div style="font-size:7px;color:#bbb;text-align:center;width:100%;padding:4px 0;border-top:1px solid #eee">- <span class="pageNumber"></span> -</div>' })
+    process.stdout.write(`  [${String(i).padStart(3)}/${t}] ✅\n`)
+    return buf
+  } finally { await p.close() }
+}
 
-    process.stdout.write(`  [${String(index).padStart(3)}/${total}] ✅ ${url}\n`)
-    return pdfBuf
-  } finally {
-    await page.close()
-  }
+function coverHtml() {
+  return `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:"PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;display:flex;align-items:center;justify-content:center;width:210mm;height:297mm;background:linear-gradient(160deg,#0f2b1d 0%,#1e4a30 35%,#2d6b44 65%,#3a8a54 100%);color:#fff}
+.c{text-align:center;padding:56px 80px}
+.c .ic{font-size:64px;margin-bottom:20px}
+.c h1{font-size:54px;font-weight:800;letter-spacing:8px;margin-bottom:12px;text-shadow:0 3px 12px rgba(0,0,0,.25)}
+.c .st{font-size:22px;font-weight:300;opacity:.92;margin-bottom:36px;line-height:1.6;letter-spacing:3px}
+.c .dv{width:120px;height:2px;background:rgba(255,255,255,.4);margin:0 auto 36px}
+.c .info{font-size:14px;opacity:.8;line-height:2;margin-bottom:48px}
+.c .info span{margin:0 12px;padding:4px 16px;border:1px solid rgba(255,255,255,.3);border-radius:16px}
+.c .au{font-size:26px;font-weight:600;letter-spacing:6px;margin-top:40px}
+.c .ft{position:absolute;bottom:32px;left:0;right:0;text-align:center;font-size:11px;opacity:.4;letter-spacing:2px}
+</style></head><body><div class="c"><div class="ic">🐳</div><h1>SQL Lab</h1><div class="st">MySQL + TiDB<br>优化实战案例集</div><div class="dv"></div><div class="info"><span>102 个案例</span><span>8 大场景</span><span>Docker 复现</span><br><span>MySQL 5.7 &amp; 8.0</span><span>TiDB v7.5</span></div><div class="au">${AUTHOR}</div><div class="ft">2026 · https://slowleelab.github.io/sql-lab/</div></div></body></html>`
 }
 
-// ── 合并 PDF ──
-async function mergePdfs(pdfBuffers) {
-  const merged = await PDFDocument.create()
-  for (const buf of pdfBuffers) {
-    const doc = await PDFDocument.load(buf)
-    const pages = await merged.copyPages(doc, doc.getPageIndices())
-    pages.forEach(p => merged.addPage(p))
+function tocHtml(guides, cases) {
+  let rows = ''
+  for (const g of guides) rows += `<tr class="gd"><td></td><td>${g.t}</td></tr>`
+  let lc = ''
+  for (const c of cases) {
+    if (c.cat !== lc) { rows += `<tr class="ct"><td colspan="2">${c.cat}</td></tr>`; lc = c.cat }
+    rows += `<tr><td class="nm">${String(c.num).padStart(2, '0')}</td><td>${c.slug.replace(/^\d+-/, '').replace(/-/g, ' ')}</td></tr>`
   }
-  return Buffer.from(await merged.save())
+  return `<!DOCTYPE html><html lang="zh-CN"><head><meta charset="utf-8"><style>
+*{margin:0;padding:0;box-sizing:border-box}
+body{font-family:"PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;padding:50px 60px;color:#333}
+h1{font-size:30px;text-align:center;margin-bottom:36px;padding-bottom:18px;border-bottom:2px solid #3a8a54;letter-spacing:4px}
+table{width:100%;border-collapse:collapse;font-size:13px}
+tr.gd td{font-weight:600;color:#3a8a54;padding:8px 8px 4px;font-size:15px}
+tr.ct td{color:#3a8a54;font-weight:700;padding:14px 8px 4px;font-size:14px;border-top:1px solid #e0e0e0}
+td{padding:4px 8px;line-height:1.6;border-bottom:1px dotted #e8e8e8}
+td.nm{width:36px;text-align:right;color:#999;padding-right:12px;font-size:11px}
+</style></head><body><h1>目 录</h1><table>${rows}</table></body></html>`
 }
 
-// ── 主流程 ──
 async function main() {
-  console.log('📄 SQL Lab PDF Generator\n')
-
-  if (!existsSync(resolve(DIST_DIR, 'index.html'))) {
-    console.error('❌ 未找到构建产物，请先运行: npm run docs:build')
-    process.exit(1)
-  }
-
-  const urls = collectUrls()
-  console.log(`  📚 ${urls.length} 个页面 (3 指南 + ${urls.length - 3} 案例)\n`)
-
+  console.log('📖 SQL Lab PDF 电子书\n')
+  if (!existsSync(resolve(DIST, 'index.html'))) { console.error('❌ 请先 npm run docs:build'); process.exit(1) }
+  const { guides, cases } = collect()
+  console.log(`  📚 ${guides.length} 前言 + ${cases.length} 案例\n`)
   const server = await startServer()
-  console.log('  🚀 Headless Chrome...')
-  const browser = await puppeteer.launch({
-    headless: true,
-    executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
-    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
-  })
-
+  console.log(`  📡 :${PORT}`)
+  const browser = await puppeteer.launch({ headless: true, executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', args: ['--no-sandbox'] })
   try {
-    console.log('  📖 渲染页面...\n')
-    const pdfs = []
-    for (let i = 0; i < urls.length; i++) {
-      const buf = await renderPage(browser, urls[i], i + 1, urls.length)
-      pdfs.push(buf)
-    }
-
-    console.log('\n  🔗 合并 PDF...')
-    const merged = await mergePdfs(pdfs)
-    const outDir = dirname(OUTPUT_FILE)
-    if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true })
-    writeFileSync(OUTPUT_FILE, merged)
-
-    const sizeMB = (merged.length / 1024 / 1024).toFixed(2)
-    console.log(`\n  ✅ docs/public/sql-lab-cases.pdf`)
-    console.log(`  📦 ${sizeMB} MB | 📄 ${urls.length}+ 页`)
+    console.log('\n  📄 封面 + 📋 目录...')
+    const pdfs = [await htmlPdf(browser, coverHtml()), await htmlPdf(browser, tocHtml(guides, cases))]
+    const total = guides.length + cases.length
+    console.log(`\n  📖 渲染 ${total} 页...\n`)
+    for (const g of guides) pdfs.push(await pagePdf(browser, g.u, pdfs.length - 1, total))
+    for (let i = 0; i < cases.length; i++) pdfs.push(await pagePdf(browser, cases[i].u, i + 1, cases.length))
+    console.log('\n  🔗 合并 + 元数据...')
+    const doc = await PDFDocument.create()
+    doc.setTitle('SQL Lab · MySQL + TiDB 优化实战案例集')
+    doc.setAuthor(AUTHOR)
+    doc.setSubject('102 个 MySQL + TiDB 优化实战案例 — Docker 一键复现，EXPLAIN 量化对比')
+    doc.setKeywords(['MySQL', 'TiDB', 'SQL优化', 'EXPLAIN', '索引', '事务', '分布式'])
+    doc.setCreator(`SQL Lab (${AUTHOR})`)
+    doc.setProducer('SQL Lab PDF Generator')
+    for (const buf of pdfs) { const s = await PDFDocument.load(buf); const pp = await doc.copyPages(s, s.getPageIndices()); for (const pg of pp) doc.addPage(pg) }
+    const outData = Buffer.from(await doc.save())
+    const d = dirname(OUT); if (!existsSync(d)) mkdirSync(d, { recursive: true })
+    writeFileSync(OUT, outData)
+    console.log(`\n  ✅ ${OUT}`)
+    console.log(`  📦 ${(outData.length / 1024 / 1024).toFixed(1)} MB  |  👤 ${AUTHOR}`)
     console.log(`  🌐 https://slowleelab.github.io/sql-lab/sql-lab-cases.pdf`)
-  } finally {
-    await browser.close()
-    server.close()
-  }
+  } finally { await browser.close(); server.close() }
 }
-
-main().catch(err => {
-  console.error('❌', err.message)
-  process.exit(1)
-})
+main().catch(e => { console.error('❌', e.message); process.exit(1) })