导航系统设计文档

概述

导航系统是一个科研网址导航站，用于管理和展示各类科研相关的网站资源。系统支持分类管理、网站管理、用户收藏等功能。

功能特性

1. 分类管理

• 支持多级分类（最多3级）
• 分类排序功能
• 分类启用/禁用状态管理
• 分类描述信息

2. 网站管理

• 网站基本信息管理（名称、URL、简介、图标）
• 网站分类关联
• 审核状态管理（待审核、通过、拒绝）
• 网站状态管理（正常、失效）
• 访问次数统计
• 排序权重设置
• 提交者信息记录

3. 用户收藏

• 用户可收藏感兴趣的网站
• 收藏备注功能
• 收藏列表查询
• 收藏状态显示

4. 前端功能

• 导航页面展示（按分类展示网站）
• 用户收藏的网站优先显示
• 添加网址功能（用户可提交新网站）
• 收藏/取消收藏功能
• 访问次数统计

数据库设计

1. nav_category（分类表）

字段名	类型	说明
id	integer	主键
name	string	分类名称
slug	string	分类标识（用于URL）
description	string(500)	分类描述
sort_order	integer	排序顺序
is_active	boolean	是否启用
parent_id	integer	父分类ID（null表示顶级分类）
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

2. nav_website（网站表）

字段名	类型	说明
id	integer	主键
name	string	网站名称
url	string(500)	网站URL
description	string(1000)	网站简介
icon_url	string(500)	网站图标URL
category_id	integer	网站所属分类ID
visit_count	integer	访问次数
audit_status	integer	审核状态（0-待审核，1-通过，2-拒绝）
status	integer	网站状态（0-正常，1-失效）
submitter_id	integer	提交者ID（null表示系统添加）
sort_weight	integer	排序权重（分类内显示顺序）
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

3. nav_user_collect（用户收藏表）

字段名	类型	说明
user_id	integer	用户ID
website_id	integer	网站ID
note	string(500)	收藏备注
collected_at	timestamp	收藏时间

唯一索引：(user_id, website_id)

API接口

分类管理接口

• GET /api/nav/nav-categories：获取所有分类（公开接口）
• GET /api/nav/nav-categories/admin：获取所有分类（管理后台）
• POST /api/nav/add-nav-category：添加分类
• POST /api/nav/update-nav-category：更新分类
• POST /api/nav/delete-nav-category：删除分类

网站管理接口

• GET /api/nav/nav-websites：查询网站列表（公开接口）
• GET /api/nav/nav-websites/admin：查询网站列表（管理后台）
• GET /api/nav/nav-website-info：获取网站详情
• POST /api/nav/add-nav-website：添加网站（用户可提交）
• POST /api/nav/update-nav-website：更新网站
• POST /api/nav/delete-nav-website：删除网站
• POST /api/nav/audit-nav-website：审核网站
• GET /api/nav/increment-nav-website-visit：增加访问次数
• GET /api/nav/nav-websites-by-category：获取分类下的网站列表（用于导航页面）

用户收藏接口

• GET /api/nav/nav-user-collects：查询用户收藏列表
• POST /api/nav/add-nav-user-collect：添加收藏
• POST /api/nav/delete-nav-user-collect：删除收藏
• POST /api/nav/update-nav-user-collect-note：更新收藏备注

前端页面

1. 导航页面（nav.ejs）

• 路径：/nav
• 功能：
  • 展示所有分类和网站
  • 用户收藏的网站优先显示
  • 添加网址功能（需要登录）
  • 收藏/取消收藏功能（需要登录）
  • 访问次数统计

2. 管理后台页面

分类管理页面

• 路径：/nav/categories
• 功能：
  • 分类列表展示（树形结构）
  • 新增分类
  • 编辑分类
  • 删除分类

网站管理页面

• 路径：/nav/websites
• 功能：
  • 网站列表展示（分页）
  • 筛选功能（分类、关键词、审核状态、网站状态）
  • 新增网站
  • 编辑网站
  • 删除网站
  • 审核网站（通过/拒绝）

相关文件

后端文件

• src/models/NavCategory.mts：分类表模型
• src/models/NavWebsite.mts：网站表模型
• src/models/NavUserCollect.mts：用户收藏表模型
• src/services/navCategory.mts：分类服务层
• src/services/navWebsite.mts：网站服务层
• src/services/navUserCollect.mts：用户收藏服务层
• src/controllers/navCategory.mts：分类控制器
• src/controllers/navWebsite.mts：网站控制器
• src/controllers/navUserCollect.mts：用户收藏控制器
• src/routes/navCategory.mts：分类路由
• src/routes/navWebsite.mts：网站路由
• src/routes/navUserCollect.mts：用户收藏路由
• src/controllers/root.mts：导航页面控制器（cVisitNav）

前端文件

• apps/admin/src/views/NavCategoryView/NavCategoryView.vue：分类管理页面
• apps/admin/src/views/NavWebsiteView/NavWebsiteView.vue：网站管理页面
• apps/admin/src/api/navCategory.ts：分类API
• apps/admin/src/api/navWebsite.ts：网站API
• views/nav.ejs：导航页面模板

类型定义

• typings/nav-category.d.ts：分类类型定义
• typings/nav-website.d.ts：网站类型定义
• typings/nav-user-collect.d.ts：用户收藏类型定义
• typings/knex.d.ts：Knex类型定义（已更新）

业务规则

分类管理

1. 分类支持最多3级嵌套
2. 分类名称和标识（slug）全局唯一
3. 删除分类前需检查：
   • 是否有子分类
   • 是否有网站使用该分类
4. 编辑分类时不能修改父分类（防止循环引用）

网站管理

1. 用户提交的网站需要审核，系统添加的网站直接通过
2. 只有审核通过的网站才会在前端显示
3. 网站按以下顺序排序：
   • 用户收藏的网站优先（如果用户已登录）
   • 然后按排序权重（sort_weight）降序
   • 最后按访问次数（visit_count）降序
4. 访问网站时自动增加访问次数

用户收藏

1. 每个用户对每个网站只能收藏一次
2. 用户收藏的网站在导航页面优先显示
3. 用户可以添加收藏备注

注意事项

1. 数据库表通过 src/models/index.mts 自动创建，无需手动创建迁移文件
2. 类型定义已同步更新到 typings/knex.d.ts
3. 前端管理页面需要管理员权限才能访问
4. 用户提交的网站需要管理员审核后才能显示
5. 导航页面支持未登录用户访问，但添加网址和收藏功能需要登录