feat(web): 地址栏驱动视图，刷新详情页不再回首页

- 新增 data/view.ts 与 useViewRoute：视图与地址双向同步，支持前进后退
- 条目地址带上所属分组，刷新 / 收藏后「返回」有确定落点
- 服务端只把 /c/** 回落到 index.html，其余路径仍返回 404
- 明细页返回按钮去掉左侧箭头图标

stash-web/src/data/local.ts

@@ -17,12 +17,14 @@ export type HostedProject = {
 /**
  * 把托管项目映射成应用条目。
  *
- * id 直接用路由地址，保证同一项目在前端各处（首页卡片、明细、详情）唯一。
+ * id 用项目名（就是目录名）：它在前端各处（首页卡片、明细、详情）唯一，
+ * 又正好是可以直接放进地址栏的一段——条目详情地址是 `/c/local/<分组>/i/<项目名>`。
+ * 访问地址仍然用 `route_path`（`/demo/`），两者不再混用。
  * 本地项目没有封面图，详情页会退化成字符头像。
  */
 function toLocalItem(project: HostedProject): AppItem {
   return {
-    id: project.route_path,
+    id: project.name,
     name: project.name,
     desc: project.route_path,
     icon: project.name.slice(0, 1).toUpperCase(),

stash-web/src/data/nav.ts

@@ -1,8 +1,8 @@
 /**
- * 侧栏分类导航的数据结构。
+ * 导航目标。
  *
- * 导航数据存在内容库的 `nav_entry` 表里（自引用树），随 `/api/catalog` 一起下发；
- * 这里只保留类型定义和空模型兜底，不再有写死的导航常量。
+ * 侧栏现在直接由内容树（分区 → 分组）派生，不再有独立的导航数据模型；
+ * 这里只保留「点击后要去哪」的最小类型。
  */
 
 export type NavTarget = {
@@ -10,26 +10,3 @@ export type NavTarget = {
   /** 指定后明细页只展示该分组 */
   groupId?: string
 }
-
-/** 一个可点击的导航叶子 */
-export type NavLeaf = {
-  id: string
-  label: string
-  target: NavTarget
-}
-
-/** 可折叠分组：本身不可点击，只负责收纳叶子 */
-export type NavGroupNode = {
-  id: string
-  label: string
-  leaves: NavLeaf[]
-}
-
-/** 侧栏的完整数据模型：顶层直达项 + 可折叠分组 */
-export type NavModel = {
-  topLevel: NavLeaf[]
-  groups: NavGroupNode[]
-}
-
-/** 内容库还没有导航数据时的兜底，避免渲染时到处判空 */
-export const EMPTY_NAV: NavModel = { topLevel: [], groups: [] }

stash-web/src/data/types.ts

@@ -30,10 +30,12 @@ export type AppItem = {
   likes?: number
 }
 
-/** 应用分组：明细页按组展示，首页取所有分组的前几项做预览 */
+/** 应用分组：明细页按组展示，首页按展示块取其中一组做预览 */
 export type AppGroup = {
   id: string
   name: string
+  /** 是否出现在侧栏；缺省视为 true */
+  showInSidebar?: boolean
   items: AppItem[]
 }
 
@@ -63,12 +65,6 @@ export type RelatedItem = {
   icon?: string
 }
 
-/** 文章正文块：段落 / 小标题 / 配图 */
-export type ArticleBlock =
-  | { type: 'paragraph'; text: string }
-  | { type: 'heading'; text: string }
-  | { type: 'image'; src: string }
-
 /** 图文条目（报道） */
 export type ArticleItem = {
   id: string
@@ -77,8 +73,18 @@ export type ArticleItem = {
   cover: string
   /** 详情页标题下的元信息，如 ['2 年前', 'CES 现场报道'] */
   meta?: string[]
-  /** 详情页正文 */
-  blocks?: ArticleBlock[]
+  /** 详情页正文：一整段 Markdown（一篇一段文本，不再拆块） */
+  body?: string
+}
+
+/** 首页展示块：分区卡片展示哪个节点、显示几条 */
+export type SectionBlock = {
+  /** 要展示的节点业务键：通常是分组；电影/文章这类无分组的填分区自己 */
+  nodeKey: string
+  /** 块标题，缺省用节点标题 */
+  title?: string
+  /** 卡片显示几条，缺省用分类的 previewLimit 或默认值 */
+  previewLimit?: number
 }
 
 /** 应用类分类：内部按分组组织 */
@@ -95,6 +101,10 @@ export type AppCategory = {
   previewLimit?: number
   /** 首页预览为空时的提示文案 */
   emptyText?: string
+  /** 是否出现在侧栏；缺省视为 true */
+  showInSidebar?: boolean
+  /** 首页卡片展示哪一块内容 */
+  block?: SectionBlock
 }
 
 /** 海报类分类：竖版海报网格 */
@@ -107,6 +117,10 @@ export type PosterCategory = {
   items: PosterItem[]
   /** 首页预览条数，默认 6 */
   previewLimit?: number
+  /** 是否出现在侧栏；缺省视为 true */
+  showInSidebar?: boolean
+  /** 首页卡片展示哪一块内容 */
+  block?: SectionBlock
 }
 
 /** 图文类分类：上图下文卡片网格 */
@@ -119,6 +133,10 @@ export type ArticleCategory = {
   items: ArticleItem[]
   /** 首页预览条数，默认 4 */
   previewLimit?: number
+  /** 是否出现在侧栏；缺省视为 true */
+  showInSidebar?: boolean
+  /** 首页卡片展示哪一块内容 */
+  block?: SectionBlock
 }
 
 export type Category = AppCategory | PosterCategory | ArticleCategory

stash-web/src/data/view.ts

@@ -0,0 +1,124 @@
+/**
+ * 视图与地址的对应关系：地址栏是唯一的视图状态源。
+ *
+ * 控制台是单页应用，但「当前在哪一页」写在 URL 里，所以刷新、收藏、
+ * 前进后退都不会丢上下文。服务端对应的规则在 `src/server.rs`：
+ * `/c/**` 没有实体文件时回落到内嵌的 `index.html`，由前端按 pathname 重新出页面。
+ *
+ * 路由形状（各段都是业务键，也就是接口 JSON 里的 `id`）：
+ *
+ *   /                              首页
+ *   /c/<分区>                       分类明细
+ *   /c/<分区>/<分组>                只展示该分组
+ *   /c/<分区>/i/<条目>              条目详情，返回 → 分类明细
+ *   /c/<分区>/<分组>/i/<条目>       条目详情，返回 → 该分组
+ *
+ * 条目地址带上它自己所在的分组，URL 才是自解释的：刷新之后点「返回」
+ * 仍然落回条目所属的分组，而不是去猜一个返回目标。
+ *
+ * 这里只做「地址 ↔ 视图」的纯转换，读写 history 的部分在 `useViewRoute.ts`。
+ */
+
+export type DetailRoute = {
+  type: 'detail'
+  categoryId: string
+  /** 指定后明细页只展示该分组 */
+  groupId?: string
+}
+
+export type ItemRoute = {
+  type: 'item'
+  categoryId: string
+  itemId: string
+  /**
+   * 条目所在的分组（应用才有）。
+   *
+   * 它只描述「条目在哪」，不描述「从哪来」：返回目标由它推导，
+   * 这样同一个条目永远只有一个地址，刷新和分享都不会跑偏。
+   */
+  groupId?: string
+}
+
+export type View =
+  | { type: 'home' }
+  | DetailRoute
+  | ItemRoute
+
+/** 前端路由前缀；改动这里要同步 `src/server.rs` 的 `SPA_PREFIXES`。 */
+const CATEGORY_PREFIX = '/c/'
+/** 前缀去掉两侧斜杠后的那一段，拼地址时当第一个路径段用 */
+const CATEGORY_SEGMENT = CATEGORY_PREFIX.slice(1, -1)
+/** 条目段标记：`/c/<分区>[/<分组>]/i/<条目>` */
+const ITEM_MARK = 'i'
+
+/** 首页视图；未知地址一律归到这里 */
+export const HOME_VIEW: View = { type: 'home' }
+
+/** 把视图转成地址。 */
+export function viewPath(view: View): string {
+  if (view.type === 'home') return '/'
+
+  const segments = [CATEGORY_SEGMENT, encodeSegment(view.categoryId)]
+  if (view.groupId !== undefined) segments.push(encodeSegment(view.groupId))
+  if (view.type === 'item') segments.push(ITEM_MARK, encodeSegment(view.itemId))
+
+  return `/${segments.join('/')}`
+}
+
+/**
+ * 把地址解析成视图；看不懂的地址（段数不对、百分号编码非法）按首页处理。
+ *
+ * 这里只做形状校验，不判断分类 / 条目是否真的存在——那是数据层的事，
+ * 而且首屏还没拿到内容库时，它们本来就「暂时不存在」。
+ */
+export function parseViewPath(pathname: string): View {
+  if (!pathname.startsWith(CATEGORY_PREFIX)) return HOME_VIEW
+
+  const segments = pathname
+    .slice(CATEGORY_PREFIX.length)
+    .split('/')
+    .filter((segment) => segment !== '')
+
+  const [categorySegment] = segments
+  if (categorySegment === undefined) return HOME_VIEW
+
+  const categoryId = decodeSegment(categorySegment)
+  if (categoryId === undefined) return HOME_VIEW
+
+  if (segments.length === 1) return { type: 'detail', categoryId }
+
+  if (segments.length === 2) {
+    const groupId = decodeSegment(segments[1])
+    if (groupId === undefined) return HOME_VIEW
+    return { type: 'detail', categoryId, groupId }
+  }
+
+  if (segments.length === 3 && segments[1] === ITEM_MARK) {
+    const itemId = decodeSegment(segments[2])
+    if (itemId === undefined) return HOME_VIEW
+    return { type: 'item', categoryId, itemId }
+  }
+
+  if (segments.length === 4 && segments[2] === ITEM_MARK) {
+    const groupId = decodeSegment(segments[1])
+    const itemId = decodeSegment(segments[3])
+    if (groupId === undefined || itemId === undefined) return HOME_VIEW
+    return { type: 'item', categoryId, itemId, groupId }
+  }
+
+  return HOME_VIEW
+}
+
+/** 单个路径段编码：id 里可能带斜杠、空格、中文 */
+function encodeSegment(value: string): string {
+  return encodeURIComponent(value)
+}
+
+/** 解码单个路径段；百分号编码非法时返回 undefined */
+function decodeSegment(segment: string): string | undefined {
+  try {
+    return decodeURIComponent(segment)
+  } catch {
+    return undefined
+  }
+}