NAV 导航主题 使用说明

适用于 Zsens Admin（host = community）的导航站主题。首页覆盖社区广场模板，渲染「分组 + 站点卡片」导航首页，并提供分类目录、热门榜、站点详情、前台提交收录与后台审核等能力。

• 主题包名：nav
• 版本：0.0.02
• 依赖：community >= 1.0.0
• 主题目录：themes/nav/

一、功能概览

前台

后台

二、安装与启用

方式一：后台应用中心（推荐）

1. 确认 themes/nav/ 已上传至项目根目录；
2. 后台 → 应用中心 → 找到「NAV导航主题」→ 安装；
3. 安装完成后点击「启用」（同一 community 宿主下同时只能启用一个主题）。

方式二：命令行（保数据、幂等）

php themes/nav/bin/register.php

脚本会依次完成：补 plugin 表记录 → 建表与种子数据 → 生成路由胶水 plugins/nav/routes.php → 注册后台三个菜单 → 启用主题 → 重建合并模板缓存。重复执行不会清空数据。

安装做了什么

• 执行 install.sql 建 4 张表（表前缀由系统数据库配置自动补全，如 zsensnavgroup）
• 写入路由胶水文件 plugins/nav/routes.php（卸载时自动删除）
• 注册后台菜单与权限规则
• 首次安装时写入默认数据：5 个分组 / 62 个站点（开发工具、AI 与模型、资讯阅读、论坛门户、高校）
• 复制 static/theme.css、static/theme.js 到 public/static/nav/

三、前台访问路径

若主题未启用，前台这些页面会 302 跳回首页，避免模板解析错位；后台管理页不受影响。

四、后台设置项说明

搜索引擎示例：

百度|https://www.baidu.com/s?wd={q}
必应|https://www.bing.com/search?q={q}
Google|https://www.google.com/search?q={q}

五、日常运营

添加/修改站点

后台「导航管理」→ 选择左侧分组 → 「新建链接」。填 URL 后若名称/图标留空，保存时会自动抓取站点标题与 favicon。

• 抓取图标与简介：列表行内「抓取」按钮，重新抓取 icon 与 description；名称为空时用页面标题补齐
• 上下架：行内开关，下架后前台不显示
• 删除分组：分组下仍有链接时会被拒绝，需先清空或删除链接

审核提交

前台提交的网址进入「收录审核」的待审核列表。通过时：

1. 选择入库分组；选「自动」则按提交者填写的期望分组名匹配，找不到就自动新建分组
2. 若该网址已在导航中，只把提交记录标记为已通过，不重复入库

图标本地化

抓取到的 favicon 会下载到 public/uploads/nav/icons/（超过 512KB 丢弃）。抓取失败不影响保存，前台图标按三级兜底显示：图片地址 → ri- 图标类名 → 名称首字母色块。

六、数据表

表名会自动补系统前缀（默认 zsens_）。

管理员在前台登录时身份为 adminid，云端同步以负数 -adminid 存储，与普通会员区分。

七、目录结构

themes/nav/
├── plugin.json                 主题元信息（name/title/version/host/entry）
├── theme.json                  前台资源声明（css/js）
├── icon.svg                    主题图标
├── install.sql                 建表语句（裸表名，运行时自动补前缀）
├── ThemePlugin.php             生命周期、配置 schema、路由胶水、菜单、种子数据
├── bin/register.php            命令行部署脚本（幂等）
├── service/
│   ├── NavData.php             分组/链接查询、热门、搜索、统计、用户配置读写
│   └── FetchMeta.php           TDK 与 favicon 抓取（cURL → stream → PowerShell 兜底）
├── controller/
│   ├── front/                  前台控制器：Directory、Submit、Api
│   └── admin/                  后台控制器：Base、Index、Links、Review
├── view/
│   ├── front/                  layout、index、directory、hot、site、submit、_panels
│   └── admin/                  config、links、review
├── static/
│   ├── theme.css               明暗双主题 + 全部组件样式
│   └── theme.js                搜索/联想/外观/自定义导航/云端同步/点击统计
└── README.md                   本文件

八、常见问题

Q：启用主题后首页仍是社区默认样式？

先确认后台应用中心显示该主题为「已启用」；若曾手工拷贝目录，执行 php themes/nav/bin/register.php 补齐记录并重建缓存。

Q：前台页面 302 跳回首页？

说明当前活动主题不是 nav。切回本主题即可。

Q：图标抓不到 / 显示裂图？

部分站点有防盗链或超时。可在后台点「抓取」重试，或手动填写图标地址；也可直接留空，前台会自动显示首字母色块。

Q：修改了 CSS/JS 不生效？

静态资源地址带 ?v=版本号，升级 plugin.json 的 version 即可刷新浏览器缓存。

Q：访客看到的外观与后台默认不一致？

外观设置（明暗、壁纸、圆角）优先读取访客本地保存值，清除浏览器缓存或点「恢复默认」后回到站点默认。

Q：卸载主题会不会丢数据？

卸载会删除路由胶水文件与菜单，4 张数据表按系统卸载策略处理；如需保留数据，卸载前先导出 /nav/export.json 或备份数据库。