docs: 添加场景解决方案文档和导航

- 新增场景解决方案文档，展示常见需求的传统写法与使用 nex-lib 的对比
- 在首页、导航栏和指南目录中添加解决方案入口
- 补充 HTTP API 文档中的代码示例

Author: webkubor

docs/.vitepress/config.mts

@@ -38,6 +38,12 @@ export default defineConfig({
           { text: '为什么选择 NexLib', link: '/guide/why' },
         ]
       },
+      {
+        text: '方案',
+        items: [
+          { text: '场景解决方案', link: '/guide/scenarios' }
+        ]
+      },
       {
         text: 'API',
         items: [

docs/guide/api-http.md

@@ -19,12 +19,43 @@ await Http.get('https://example.com/api', { query: { q: 'x' }, timeoutMs: 1000 }
 ## withQuery(url, params)
 - 将对象转为查询参数并拼接到 URL
 
+::: code-group
+```ts [Example]
+import { withQuery } from 'nex-lib'
+withQuery('https://a.com/path', { a: 1, b: true, c: null })
+```
+```text [Output]
+https://a.com/path?a=1&b=true
+```
+:::
+
 ## toFormData(obj)
 - 将对象转为 `FormData`，值为对象时自动 JSON 序列化
 
+::: code-group
+```ts [Example]
+import { toFormData } from 'nex-lib'
+const fd = toFormData({ a: 1, b: 'x', c: { k: 'v' } })
+```
+```text [Output]
+FormData(a=1, b=x, c={"k":"v"}) // 展示性输出，实际为原生 FormData
+```
+:::
+
 ## withTimeout(promise, ms)
 - 为任意 Promise 添加超时（抛出 `Timeout` 错误）
 
+::: code-group
+```ts [Example]
+import { withTimeout } from 'nex-lib'
+const p = new Promise(resolve => setTimeout(resolve, 50))
+await withTimeout(p, 10)
+```
+```text [Output]
+Error: Timeout
+```
+:::
+
 ## withRetry(fn, times, delay)
 - 重试封装；与 `ObjectUtils.retry` 一致
 

docs/guide/index.md

@@ -102,6 +102,10 @@ const { format, getTimestamp, createWURL, ObjectUtils, StringUtils, ValidationUt
     <h3>URL</h3>
     <p>主域名、查询参数解析/追加、协议/路径/端口。</p>
   </a>
+  <a class="card" href="/guide/scenarios">
+    <h3>Solutions</h3>
+    <p>场景解决方案：代码节省对比与最佳实践。</p>
+  </a>
   <a class="card" href="/guide/api-http">
     <h3>HTTP</h3>
     <p>轻量 fetch 封装：超时/重试/查询/FormData。</p>

docs/guide/scenarios.md

@@ -0,0 +1,171 @@
+---
+outline: deep
+---
+
+# 场景解决方案（Solutions）
+
+从真实业务出发，展示“常见需求的传统写法 vs 使用 nex-lib 的写法”，并给出代码节省量参考。
+
+## 1）搜索框防抖（避免频繁请求）
+
+::: code-group
+```ts [Before]
+let timer: any
+function onInput(e: Event) {
+  const q = (e.target as HTMLInputElement).value
+  if (timer) clearTimeout(timer)
+  timer = setTimeout(() => {
+    fetch(`/api/search?q=${encodeURIComponent(q)}`)
+  }, 300)
+}
+```
+```ts [After]
+import { ObjectUtils } from 'nex-lib'
+const doSearch = ObjectUtils.debounce((q: string) => {
+  fetch(`/api/search?q=${encodeURIComponent(q)}`)
+}, 300)
+function onInput(e: Event) { doSearch((e.target as HTMLInputElement).value) }
+```
+```text [Reduction]
+约 12 行 → 4 行，节省 ~8 行
+```
+:::
+
+## 2）列表分页请求（查询参数 + 超时 + 重试）
+
+::: code-group
+```ts [Before]
+const url = new URL('/api/list', location.origin)
+url.searchParams.set('page', String(page))
+url.searchParams.set('size', String(size))
+const ac = new AbortController()
+const t = setTimeout(() => ac.abort(), 3000)
+try {
+  let tries = 0
+  while (tries < 3) {
+    try {
+      const res = await fetch(url.toString(), { signal: ac.signal })
+      if (!res.ok) throw new Error('http')
+      return await res.json()
+    } catch (e) { tries++; await new Promise(r => setTimeout(r, 500)) }
+  }
+} finally { clearTimeout(t) }
+```
+```ts [After]
+import { Http } from 'nex-lib'
+await Http.get('/api/list', {
+  query: { page, size },
+  timeoutMs: 3000,
+  retry: { times: 3, delay: 500 },
+})
+```
+```text [Reduction]
+约 28 行 → 6 行，节省 ~22 行
+```
+:::
+
+## 3）产品页 URL 参数管理（追加/替换/移除）
+
+::: code-group
+```ts [Before]
+const u = new URL(location.href)
+u.searchParams.set('sku', sku)
+u.searchParams.set('ref', ref)
+history.replaceState(null, '', u.toString())
+```
+```ts [After]
+import { createWURL } from 'nex-lib'
+const u = createWURL(location.href)
+history.replaceState(null, '', u.replaceParams({ sku, ref }))
+```
+```text [Reduction]
+约 8 行 → 3 行，节省 ~5 行
+```
+:::
+
+## 4）登录态存储与过期（TTL）
+
+::: code-group
+```ts [Before]
+localStorage.setItem('token', JSON.stringify({ v: token, expireAt: Date.now()+86400000 }))
+const raw = localStorage.getItem('token')
+if (raw) {
+  const obj = JSON.parse(raw)
+  if (Date.now() >= obj.expireAt) localStorage.removeItem('token')
+}
+```
+```ts [After]
+import { StorageUtils } from 'nex-lib'
+StorageUtils.setWithTTL('token', token, 86400000)
+StorageUtils.getWithTTL('token')
+```
+```text [Reduction]
+约 9 行 → 2 行，节省 ~7 行
+```
+:::
+
+## 5）倒计时与相对时间（展示友好）
+
+::: code-group
+```ts [Before]
+function fmt(ms: number) {
+  const s = Math.floor(ms/1000)
+  const h = String(Math.floor((s%86400)/3600)).padStart(2,'0')
+  const m = String(Math.floor((s%3600)/60)).padStart(2,'0')
+  const sec = String(s%60).padStart(2,'0')
+  return `${h}:${m}:${sec}`
+}
+```
+```ts [After]
+import { formatDuration, relativeTime, nowSeconds } from 'nex-lib'
+formatDuration(65000)
+relativeTime(nowSeconds()-120)
+```
+```text [Reduction]
+约 8 行 → 2 行，节省 ~6 行
+```
+:::
+
+## 6）复制分享链接（兼容权限）
+
+::: code-group
+```ts [Before]
+const ta = document.createElement('textarea')
+ta.value = url
+document.body.appendChild(ta)
+ta.select()
+document.execCommand('copy')
+document.body.removeChild(ta)
+```
+```ts [After]
+import { browserUtils } from 'nex-lib'
+await browserUtils.copyToClipboard(url)
+```
+```text [Reduction]
+约 6 行 → 1 行，节省 ~5 行
+```
+:::
+
+## 7）主题色工具（对比色与亮暗）
+
+::: code-group
+```ts [Before]
+function yiq(hex: string) {
+  const h = hex.replace('#','')
+  const r = parseInt(h.slice(0,2),16)
+  const g = parseInt(h.slice(2,4),16)
+  const b = parseInt(h.slice(4,6),16)
+  const v = (r*299 + g*587 + b*114)/1000
+  return v >= 128 ? '#000' : '#fff'
+}
+```
+```ts [After]
+import { ColorUtils } from 'nex-lib'
+ColorUtils.contrastColor('#ffcc00')
+ColorUtils.lighten('#333333', 0.5)
+ColorUtils.darken('#cccccc', 0.5)
+```
+```text [Reduction]
+约 10 行 → 3 行，节省 ~7 行
+```
+:::

docs/index.md

@@ -16,6 +16,9 @@ hero:
     - theme: brand
       text: API Docs
       link: /guide/api-time
+    - theme: brand
+      text: Solutions
+      link: /guide/scenarios
     - theme: alt
       text: Why Nex Lib?
       link: /guide/why