v0.13.0: 前台导航修复（loader 服务函数化防客户端退化）、全站图片占位图+懒加载、favicon、分页圆点、导航 1400px 居中、缺失图片补齐脚本

docs/admin-crm.md

@@ -1,8 +1,28 @@
 # 后台（Admin / CRM）与 MCP 说明
 
+> v0.13.0 起：前台导航修复（loader 服务函数化）、全站图片占位图 + 懒加载、favicon。
 > v0.12.0 起：PG 16 → 18.6（增量备份能力）、备份系统（全量/增量/S3）、用户权限分层。
 > v0.11.0 起：后台按「功能接近原版 WordPress + 现代化 CRM 界面」重做一轮，并新增站点管理 MCP 服务器。
 
+## 前台约定（v0.13.0 起生效）
+
+- **TanStack Start loader 是同构运行的**：客户端导航（点击 LOGO / `<Link>` / 分页）会在浏览器重跑一遍
+  loader。凡直接调用 `db`/查询层的写法（依赖 `bun:sql`，客户端是 stub）全部失败，页面退化为空数据。
+  **loader 的数据获取必须走 `createServerFn`**（服务端执行返回纯 JSON）；`redirect()/notFound()` 不能在
+  serverFn 内抛给 Router，用协议标记（如 `$.tsx` 的 `__redirect/__notFound`）回传后由 loader 本地抛出。
+  已改造：`loadHomePage`（/）、`loadCatchAll`（/$）、`loadProduct`、`loadCollectionCategory`、`loadShopData`、
+  `loadSearchData`、`loadContactData`、`loadBlogPost`、`loadSolutionPage`、`loadBlogArchive`、`loadSolutionArchive`、
+  `loadCollection`（/collection/）等；购物车/结账/账户本来就用 serverFn（getCart/getCurrentUser/getMyOrders）。
+- **图片占位图与懒加载**：`public/uploads/placeholder.jpg`（灰底 + 低透明度 LOGO，300×260，ImageMagick 生成）；
+  全部前台 `<img>` 由 Layout 内联脚本补 `loading="lazy" decoding="async"`（MutationObserver 覆盖新增节点），
+  加载完成前显示占位背景（`app.css` 的 `.ds-site img` 规则；作用域为 Layout 的 `<main class="ds-site">`）。
+  注意透明 PNG 加载完成后会透出占位图——导出透明图时慎用。
+- **缺失图片补齐**：`bun run scripts/sync-missing-uploads.ts` 幂等——扫库（contents/products/media）引用路径，
+  与 public/uploads 比对，缺失文件从原站下载（v0.13.0 补回 90 张；原站已失效 38 张不可恢复，走占位图）。
+- **favicon**：`public/favicon.ico`（原站 32×32 PNG 转 ICO，ImageMagick）+ `apple-touch-icon.png`（LOGO 180×180），
+  根路由 `head().links` 注入。
+- **导航宽度**：Header 顶栏与主导航行统一 `max-w-[1400px] mx-auto` 居中（2026-11-04 用户指定，原站基准）。
+
 ## 用户权限分层（RBAC）
 
 两类用户：**普通用户**（customer，仅商城账号）与**后台用户**（admin > manager > editor）。能力矩阵（`src/server/auth.ts` requireCapability）：