产品管理系统设计文档

概述

产品管理系统是后台管理系统的核心模块之一，专为管理员设计，提供产品的增删改查功能。系统支持产品基本信息管理，包括产品名称、产品英文key、产品描述、是否显示、开发状态、访问权限、排序顺序、产品主页URL、产品Icon等字段。

注意：产品管理功能位于 apps/admin 目录下的管理后台项目中。

核心功能

1. 产品列表管理

• 产品列表展示（分页）
• 按关键词搜索（搜索产品名称、key或描述）
• 按是否显示筛选（全部、显示、隐藏）
• 产品信息展示（ID、产品名称、产品Key、产品描述、是否显示、开发状态、访问权限、排序顺序、主页URL、Icon、更新时间）
• 产品列表按排序顺序升序排列（数字越小越靠前），相同排序顺序按创建时间倒序排列

2. 产品新增功能

• 产品名称输入（必填）
• 产品英文key输入（必填，唯一，只能包含小写字母、数字和连字符）
• 产品描述输入（可选，最多310个字符，约150~155个汉字）
• 是否显示选择（默认显示）
• 开发状态选择（未开发、开发中、开发完毕，默认未开发）
• 访问权限选择（站长自用、内测、对外开放，默认站长自用）
• 排序顺序输入（可选，非负整数，默认0，数字越小越靠前）
• 产品主页URL输入（可选，URL格式验证）
• 产品Icon URL输入（可选，URL格式验证，支持预览）

3. 产品编辑功能

• 支持编辑产品的所有字段
• 产品英文key唯一性验证（不能与其他产品重复）
• 表单验证和错误提示

4. 产品删除功能

• 删除产品记录
• 删除前确认提示
• 删除后自动刷新列表

权限控制

访问权限

• 仅管理员可访问：产品管理功能需要超级管理员权限
• 路由级别权限控制：通过 requireAuth: [ROLE_SUPER_ADMIN] 配置
• 后端接口权限控制：所有产品管理接口都需要管理员权限验证

操作权限

• 产品新增：仅管理员可新增产品
• 产品编辑：仅管理员可编辑产品
• 产品删除：仅管理员可删除产品

数据库设计

产品管理系统主要使用以下数据表：

product（产品表）

存储产品的基本信息。

主要字段：

• id: 主键，自增
• name: 产品名称（varchar，非空）
• key: 产品英文key（varchar，非空，唯一，用于标识）
• description: 产品描述（varchar(310)，可选，150~155个汉字长度）
• is_visible: 是否显示（boolean，默认true）
• status: 产品开发状态（varchar(20)，非空，默认"not_started"）
  • not_started: 未开发
  • in_progress: 开发中
  • completed: 开发完毕
• access: 访问权限（varchar(20)，非空，默认"private"）
  • private: 站长自用（仅管理员可见）
  • beta: 内测（登录用户可见）
  • public: 对外开放（所有用户可见）
• sort_order: 排序顺序（integer，非空，默认0，数字越小越靠前）
• home_url: 产品主页URL（varchar(500)，可选）
• icon: 产品Icon（varchar(500)，可选）
• created_at: 创建时间
• updated_at: 更新时间

详细字段说明请参考 数据库设计文档。

业务流程

1. 产品列表查询流程

用户访问产品管理页面
  ↓
前端调用 apiGetProductList 接口
  ↓
后端验证权限（管理员）
  ↓
根据筛选条件查询产品列表（分页）
  ↓
返回产品列表数据
  ↓
前端展示产品列表

2. 产品新增流程

用户点击"新增产品"按钮
  ↓
打开新增对话框
  ↓
用户填写产品信息
  ↓
前端表单验证
  ↓
调用 apiAddProduct 接口
  ↓
后端验证权限和数据
  ↓
检查产品key是否已存在
  ↓
插入产品记录
  ↓
返回成功，刷新列表

3. 产品编辑流程

用户点击"编辑"按钮
  ↓
调用 apiGetProductInfo 接口获取产品详情
  ↓
填充表单数据
  ↓
用户修改产品信息
  ↓
前端表单验证
  ↓
调用 apiUpdateProduct 接口
  ↓
后端验证权限和数据
  ↓
检查产品是否存在
  ↓
检查产品key是否与其他产品冲突
  ↓
更新产品记录
  ↓
返回成功，刷新列表

4. 产品删除流程

用户点击"删除"按钮
  ↓
弹出确认对话框
  ↓
用户确认删除
  ↓
调用 apiDeleteProduct 接口
  ↓
后端验证权限
  ↓
检查产品是否存在
  ↓
删除产品记录
  ↓
返回成功，刷新列表

API 接口

产品相关接口

获取产品列表

• 路径：GET /api/products/products
• 参数：
  • pageNo：页码（可选，默认1）
  • pageSize：每页数量（可选，默认10）
  • keyword：关键词（可选，搜索产品名称、key或描述）
  • is_visible：是否显示（可选，0-隐藏，1-显示）
• 返回：产品列表和总数

获取产品详情

• 路径：GET /api/products/product-info
• 参数：
  • id：产品ID
• 返回：产品详细信息

添加产品

• 路径：POST /api/products/add-product
• 参数：产品完整信息（名称、key、描述、是否显示、开发状态、访问权限、排序顺序、主页URL、Icon等）
• 返回：成功或失败信息
• 约束：
  • 产品名称不能为空
  • 产品英文key不能为空，且唯一
  • 产品描述最多310个字符
  • 开发状态必须是：未开发、开发中或开发完毕（可选，默认未开发）
  • 访问权限必须是：站长自用、内测或对外开放（可选，默认站长自用）
  • 排序顺序必须为非负整数（可选，默认0）
  • 产品主页URL和Icon必须是有效的URL格式

更新产品

• 路径：POST /api/products/update-product
• 参数：产品完整信息（包含ID）
• 返回：成功或失败信息
• 约束：
  • 产品ID必须存在
  • 产品英文key不能与其他产品重复

删除产品

• 路径：POST /api/products/delete-product
• 参数：
  • id：产品ID
• 返回：成功或失败信息
• 约束：
  • 产品ID必须存在

主要涉及文件列表

后端文件

• src/models/Product.mts：产品表模型定义
• src/controllers/product.mts：产品管理控制器（包含查询、新增、更新、删除接口）
• src/routes/products.mts：产品管理路由配置

前端文件

• apps/admin/src/api/products.ts：产品相关API
• apps/admin/src/views/ProductsView/ProductsView.vue：产品管理页面组件
• apps/admin/src/router/index.ts：路由配置（包含产品管理路由）
• apps/admin/src/components/AdminLayout/AdminSidebar.vue：侧边栏菜单（包含产品管理菜单项）

类型定义文件

• typings/product.d.ts：产品相关类型定义
  • Product：产品实体类型
  • ProductListItem：产品列表项类型
  • ParamsApiGetProductList：查询产品列表参数类型
  • ReturnApiGetProductList：查询产品列表返回类型
  • ParamsApiGetProductInfo：查询产品详情参数类型
  • ReturnApiGetProductInfo：查询产品详情返回类型
  • ParamsApiAddProduct：添加产品参数类型
  • ParamsApiUpdateProduct：更新产品参数类型
  • ParamsApiDeleteProduct：删除产品参数类型

数据验证

前端验证

• 产品名称：必填
• 产品英文key：必填，只能包含小写字母、数字和连字符
• 产品描述：最多310个字符
• 排序顺序：非负整数（可选，默认0）
• 产品主页URL：URL格式验证
• 产品Icon URL：URL格式验证

后端验证

• 使用 Zod Schema 进行参数验证
• 产品名称不能为空
• 产品英文key不能为空，且唯一
• 产品描述最多310个字符
• 排序顺序必须为非负整数（可选，默认0）
• 产品主页URL和Icon最多500个字符
• 产品ID必须为正整数

访问权限说明

产品的访问权限（access 字段）决定了产品在首页的可见性：

• 站长自用（private）：仅管理员可以在首页看到该产品
• 内测（beta）：登录用户可以在首页看到该产品
• 对外开放（public）：所有用户（包括未登录用户）都可以在首页看到该产品

首页产品列表会根据当前用户的登录状态和权限自动过滤，只显示用户有权限查看的产品。

注意事项

1. 产品英文key唯一性：系统会检查产品英文key的唯一性，新增和更新时都会验证
2. 产品描述长度：产品描述限制为310个字符（约150~155个汉字），超出会提示错误
3. 开发状态：用于标识产品的开发进度，便于管理和展示
4. 访问权限：访问权限决定了产品在首页的可见性，需要根据实际需求合理设置
5. 排序功能：产品列表按 sort_order 字段升序排列，数字越小越靠前；相同排序顺序的产品按创建时间倒序排列
6. URL格式验证：产品主页URL和Icon URL必须是有效的URL格式
7. 权限控制：所有产品管理功能都需要超级管理员权限
8. 删除操作：删除产品是物理删除，删除前会弹出确认对话框