395 lines
21 KiB
Markdown
395 lines
21 KiB
Markdown
# 铜壶管理系统 - 商品展示、详情与订单管理设计文档
|
||
|
||
## 1. 项目概述
|
||
本项目面向内部商品管理、销售下单与库房贴标场景，建设一套网页端铜壶管理系统。系统需要支持商品目录管理、款式展示、商品详情维护、订单创建、订单完成流转、标签按量导出、月度/年度统计分析，以及多用户登录和权限分级控制。
|
||
|
||
本次设计明确以下前提：
|
||
1. 采用前后端分离架构，前端独立部署，后端提供 API 服务。
|
||
2. 商品上传图片必须存入数据库，不直接依赖本地磁盘路径。
|
||
3. 标签文件下载由后端统一生成和输出。
|
||
4. 订单在填写快递单号前属于未完成状态，可编辑、可删除；填写快递单号并确认后才算完成。
|
||
5. 系统支持两类用户：管理员与普通用户；管理员拥有全量权限，普通用户权限由管理员创建和分配。
|
||
|
||
---
|
||
|
||
## 2. 设计原则
|
||
1. **前后端职责清晰**：前端负责页面展示、交互与状态管理；后端负责业务规则、数据持久化、文件处理、标签生成与统计计算。
|
||
2. **左侧目录常驻**：详情页不采用遮挡主界面的弹窗形式，而是采用系统内部独立详情路由，左侧目录固定保留。
|
||
3. **媒体数据统一管理**：图片采用数据库二进制存储，列表页与详情页通过独立接口读取缩略图或原图。
|
||
4. **订单闭环管理**：订单从加购、创建、编辑、完成、统计形成闭环，并保留详情追溯能力。
|
||
5. **权限前后端一致**：前端负责菜单、页面和按钮级可见性控制，后端负责接口级鉴权，避免仅前端隐藏导致越权。
|
||
6. **非商品类目可轻量处理**：如商标图片、宣传物料等类目可以不进入商品详情业务流程，仅提供预览或下载。
|
||
|
||
---
|
||
|
||
## 3. 总体架构设计
|
||
|
||
### 3.1 系统组成
|
||
系统拆分为三个核心层：
|
||
* **前端管理端**：负责登录页、权限菜单、目录树、商品卡片墙、商品详情编辑、订单列表、订单详情、统计报表、用户管理等页面。
|
||
* **后端服务端**：负责认证鉴权、用户管理、类目管理、商品管理、图片上传入库、订单流转、标签文件导出、统计报表接口。
|
||
* **数据库**：保存用户账号、权限数据、业务数据、订单数据、图片二进制内容、标签文件元数据及必要日志。
|
||
|
||
### 3.2 建议技术选型
|
||
为保证后续开发效率与维护性，建议采用以下技术栈：
|
||
* **前端**：Vue 3 + Vite + Vue Router + Pinia + Element Plus
|
||
* **后端**：Spring Boot + Spring Security + JWT + MyBatis-Plus + Spring Validation
|
||
* **数据库**：SQLite 3
|
||
* **标签导出**：后端使用 PDF 模板生成库输出 PDF，或按需打包 ZIP
|
||
|
||
### 3.3 部署方式
|
||
* 前端作为独立静态站点部署，可通过 Nginx 提供访问。
|
||
* 后端独立部署为 API 服务，对外提供 RESTful 接口。
|
||
* SQLite 作为本地数据库文件随同后端部署，统一负责业务表与图片二进制数据存储。
|
||
* 前端与后端通过 HTTP API 通信，不直接访问数据库。
|
||
* 为降低写入锁竞争，系统建议采用单机单实例部署，避免多节点同时写入同一个 SQLite 文件。
|
||
|
||
---
|
||
|
||
## 4. 页面信息架构与导航设计
|
||
|
||
### 4.1 页面布局
|
||
系统采用“左侧目录树 + 右侧主内容区 + 顶部功能区”的布局：
|
||
* **左侧目录树**：显示所有型号、类目以及对应款式子节点。
|
||
* **右侧主内容区**：根据当前路由显示款式墙、商品详情页、订单列表、订单详情或统计页面。
|
||
* **顶部功能区**：显示当前待下单商品数量、当前登录用户、退出登录入口；管理员可从顶部进入用户管理页面。
|
||
|
||
### 4.2 路由建议
|
||
建议前端至少包含以下页面路由：
|
||
* `/login`：登录页
|
||
* `/categories/:categoryId`：某个型号或类目的款式墙页面
|
||
* `/products/:productId`：某个款式的独立详情页
|
||
* `/orders`：订单列表页
|
||
* `/orders/:orderId`：订单详情页
|
||
* `/statistics`：统计分析页
|
||
* `/system/users`：用户管理页，仅管理员可访问
|
||
|
||
### 4.3 左侧目录交互规则
|
||
* 点击型号节点：右侧显示该型号下全部款式卡片。
|
||
* 点击款式子节点：右侧直接跳转到该产品详情页。
|
||
* 点击不需要详情页的类目：右侧显示素材列表、预览区或下载按钮，不进入商品业务详情页。
|
||
* 左侧目录支持新增、编辑、删除、排序。
|
||
* 某型号下的产品款式支持新增、编辑、删除，新增后自动同步到目录子节点。
|
||
|
||
### 4.4 权限展示规则
|
||
* 未登录用户只能访问登录页，不能直接进入业务页面。
|
||
* 登录后前端根据当前用户权限动态渲染菜单、页面入口和操作按钮。
|
||
* 管理员可见全部模块，包括商品管理、订单管理、统计和用户管理。
|
||
* 普通用户只显示已授权模块；即使手动输入地址，后端接口仍需再次校验权限。
|
||
|
||
---
|
||
|
||
## 5. 核心功能模块设计
|
||
|
||
### 5.1 用户登录与权限管理
|
||
系统需要支持多用户登录，并采用“管理员 + 普通用户”的两类用户模型：
|
||
* **管理员用户**：默认拥有全部页面查看、数据编辑、订单处理、统计查看、用户管理和权限分配能力。
|
||
* **普通用户**：账号由管理员创建，权限由管理员按需分配，不默认拥有全部功能。
|
||
* **登录方式**：采用用户名与密码登录，后端签发登录令牌，前端通过路由守卫校验登录状态。
|
||
* **用户管理**：管理员可以新增普通用户、编辑基础信息、重置密码、启用/停用账号、分配权限。
|
||
* **权限粒度**：至少区分页面访问权限与操作权限，例如商品查看、商品编辑、附件上传、订单查看、订单处理、订单完成、统计查看、用户管理。
|
||
* **典型普通用户示例**：
|
||
* 客户用户：可浏览商品列表与商品详情，仅查看商品图片画廊，不展示基础资料与标签信息，不可编辑商品，不可处理订单。
|
||
* 打包工用户：可查看订单列表与订单详情，可处理未完成订单、填写快递单号并完成订单，可按需下载标签，不可编辑商品和用户。
|
||
|
||
### 5.2 左侧目录结构管理
|
||
目录管理模块需要满足以下能力：
|
||
* 支持多级树形结构，至少包含“型号/类目/款式”三级概念。
|
||
* 创建类目时必须配置 `requires_detail_page`，明确该类目是否进入商品详情流程。
|
||
* 标准商品类目进入商品管理流程；非标准类目进入素材预览/下载流程。
|
||
* 左侧目录支持实时刷新，确保新增产品后可直接点击进入详情页。
|
||
|
||
### 5.3 主界面：款式墙
|
||
当左侧选中某个需要详情页的型号或商品类目时，右侧显示该型号下的款式卡片墙：
|
||
* 卡片显示商品缩略图、款式名称、SKU、库存状态、批发价、库存数量。
|
||
* 状态标签区分为：可售、停产、库存多、库存少。
|
||
* 卡片右下角提供快捷加购按钮，点击后加入待下单列表。
|
||
* 点击卡片主体跳转到独立商品详情页。
|
||
* 支持搜索、按状态筛选、按名称筛选、分页或懒加载。
|
||
|
||
### 5.4 款式详情页
|
||
商品详情页采用**独立页面路由**，不是浏览器弹出窗口，也不是遮挡主界面的弹窗。进入详情页后，左侧目录继续保留，用户可以在目录与详情之间快速切换。
|
||
|
||
详情页需要支持以下编辑和展示能力：
|
||
* 基础信息：型号、款式名称、SKU、批发价、库存数量、库存状态、备注。
|
||
* 图片管理：支持上传产品缩略图、原图和多张详情图；支持设置主图、调整顺序、删除图片。
|
||
* 原图下载：点击图片可下载数据库中保存的原图。
|
||
* 标签文件管理：支持上传标签模板文件，支持预览文件信息与重新上传。
|
||
* 下单操作：支持输入数量后加入订单。
|
||
|
||
建议详情页分为以下区域：
|
||
1. **基础资料区**：编辑 SKU、名称、价格、库存和状态。
|
||
2. **图片管理区**：上传缩略图、上传原图、多图列表、主图设置、拖拽调整图片顺序、原图下载。
|
||
3. **标签文件区**：上传标签模板、查看模板版本、下载模板。
|
||
4. **操作区**：保存、返回列表、加入订单。
|
||
|
||
权限补充要求：
|
||
* 只拥有商品查看权限的普通用户进入商品详情时，仅展示全部商品图片，不展示基础资料、标签信息以及原图/标签下载入口。
|
||
* 只有拥有商品编辑或附件管理权限的用户才可修改商品基础信息、上传图片和更新标签文件。
|
||
|
||
### 5.5 订单中心与订单列表页
|
||
订单模块从“类似购物车”的待下单中心演进为正式订单管理模块。
|
||
|
||
订单列表页需要包含：
|
||
* 全部订单
|
||
* 未完成订单
|
||
* 已完成订单
|
||
* 月度统计入口
|
||
* 年度统计入口
|
||
|
||
订单列表页功能要求：
|
||
* 展示订单编号、创建时间、商品款式数量合计、订单总价、订单状态、快递单号。
|
||
* 未完成订单允许继续编辑商品数量、删除商品、删除整单。
|
||
* 已完成订单默认只允许查看详情；管理员额外保留删除整单能力。
|
||
* 页面支持按订单状态、日期范围、关键词筛选。
|
||
* 无订单权限的用户不显示订单入口；只有拥有订单查看权限的用户才可访问订单列表。
|
||
|
||
### 5.6 订单详情页
|
||
订单详情页用于查看和处理单个订单的完整内容，需要单独页面展示，而不是仅在右侧侧边栏中查看。
|
||
|
||
订单详情页至少包含以下信息：
|
||
* 订单基础信息：订单号、创建时间、状态、快递单号、完成时间。
|
||
* 商品明细：产品型号、款式名称、SKU、数量、单价、小计。
|
||
* 金额汇总：商品总数量、订单总价。
|
||
* 标签下载：从订单详情页统一触发，不再放在右侧订单摘要中。
|
||
|
||
订单详情页业务规则：
|
||
* 未完成订单：可编辑商品数量、删除商品、删除订单、填写快递单号。
|
||
* 已完成订单：信息只读，保留标签文件下载能力；管理员可删除整单。
|
||
* 点击“完成订单”前必须填写快递单号；填写成功后订单状态更新为已完成。
|
||
* 只有拥有订单处理权限的用户才可修改订单明细；只有拥有订单完成权限的用户才可填写快递单号并完成订单。
|
||
|
||
### 5.7 标签按量下载
|
||
标签下载是本系统的关键业务功能，必须由后端统一计算和输出：
|
||
* 系统读取订单中每个款式的购买数量。
|
||
* 按数量复制对应款式的标签模板内容。
|
||
* 输出为可打印的 PDF，或按客户需求输出 ZIP 包。
|
||
* 标签下载入口放在订单详情页中，由用户针对单个订单执行。
|
||
|
||
### 5.8 月度与年度统计
|
||
统计页面需要支持月度与年度两个维度，并输出：
|
||
* 每款产品的销量数量
|
||
* 每款产品的单价
|
||
* 每款产品的小计金额
|
||
* 当前月份总销售额
|
||
* 当前年份总销售额
|
||
|
||
统计页面建议支持以下筛选条件：
|
||
* 年份
|
||
* 月份
|
||
* 型号/类目
|
||
* 款式名称或 SKU
|
||
* 建议仅管理员或拥有统计查看权限的用户访问
|
||
|
||
---
|
||
|
||
## 6. 媒体与附件存储设计
|
||
|
||
### 6.1 图片入库要求
|
||
根据本项目要求，商品图片必须存数据库，不依赖磁盘目录路径。建议采用“业务表 + 文件表分离”的方式：
|
||
* 商品表只保留业务字段和主图引用，不直接保存大体积二进制字段。
|
||
* 文件表单独保存图片二进制内容、缩略图二进制内容、文件元数据。
|
||
* 列表查询只返回文件 ID、文件名称和访问接口，不在列表接口中直接返回 BLOB 内容。
|
||
* SQLite 附件表使用 BLOB 字段保存文件内容，建议控制单张图片大小并定期归档历史数据。
|
||
|
||
### 6.2 图片处理建议
|
||
* 上传原图后，由后端生成缩略图并一并入库。
|
||
* 前端列表页默认加载缩略图接口，详情页按需加载原图接口。
|
||
* 同一款式支持多图，需支持主图标识与排序。
|
||
* 建议对图片大小、格式进行限制，例如 JPG、PNG、WEBP，单张不超过 10MB。
|
||
|
||
### 6.3 标签文件处理建议
|
||
标签文件可与图片共用统一附件表，通过 `file_role` 字段区分图片与标签模板：
|
||
* 图片文件：`COVER`、`DETAIL`
|
||
* 标签文件：`LABEL_TEMPLATE`
|
||
|
||
对于标签模板文件，建议保存文件元数据与二进制内容，便于后端统一生成导出内容与备份。
|
||
|
||
---
|
||
|
||
## 7. 关键数据模型建议
|
||
|
||
### 7.1 类目表 Category
|
||
* `id`：主键
|
||
* `parent_id`：父级类目 ID
|
||
* `name`：类目名称
|
||
* `sort_no`：排序号
|
||
* `requires_detail_page`：是否需要详情页
|
||
* `category_type`：类目类型，区分商品类目与素材类目
|
||
* `created_at`：创建时间
|
||
* `updated_at`：更新时间
|
||
|
||
### 7.2 商品表 ProductItem
|
||
* `id`：主键
|
||
* `category_id`：所属类目 ID
|
||
* `sku`：商品 SKU
|
||
* `name`：款式名称
|
||
* `model_name`：所属型号名称快照或冗余字段
|
||
* `status`：状态，建议值为 `AVAILABLE`、`DISCONTINUED`、`HIGH_STOCK`、`LOW_STOCK`
|
||
* `wholesale_price`：批发价格
|
||
* `stock_quantity`：库存数量
|
||
* `cover_asset_id`：主图附件 ID
|
||
* `remark`：备注
|
||
* `created_at`：创建时间
|
||
* `updated_at`：更新时间
|
||
|
||
### 7.3 附件表 FileAsset
|
||
* `id`：主键
|
||
* `business_type`：业务类型，如 `PRODUCT`
|
||
* `business_id`：业务对象 ID
|
||
* `file_role`：文件角色，如 `COVER`、`DETAIL`、`LABEL_TEMPLATE`
|
||
* `file_name`：文件名
|
||
* `mime_type`：文件类型
|
||
* `file_size`：文件大小
|
||
* `content_blob`：原始二进制内容
|
||
* `preview_blob`：缩略图或预览二进制内容
|
||
* `sort_no`：排序号
|
||
* `is_primary`：是否主图
|
||
* `sha256`：文件摘要
|
||
* `created_at`：创建时间
|
||
|
||
### 7.4 订单表 Order
|
||
* `id`：主键
|
||
* `order_no`：订单编号
|
||
* `status`：订单状态，建议值为 `PENDING`、`COMPLETED`、`CANCELLED`
|
||
* `total_quantity`：商品总数量
|
||
* `total_amount`：订单总金额
|
||
* `express_no`：快递单号
|
||
* `remark`：订单备注
|
||
* `created_at`：创建时间
|
||
* `completed_at`：完成时间
|
||
|
||
### 7.5 订单明细表 OrderItem
|
||
* `id`：主键
|
||
* `order_id`：订单 ID
|
||
* `product_id`：商品 ID
|
||
* `product_name_snapshot`：商品名称快照
|
||
* `sku_snapshot`：SKU 快照
|
||
* `model_name_snapshot`：型号名称快照
|
||
* `unit_price`：下单时单价快照
|
||
* `quantity`：数量
|
||
* `line_amount`：小计金额
|
||
|
||
### 7.6 订单日志表 OrderOperationLog（建议）
|
||
* `id`：主键
|
||
* `order_id`：订单 ID
|
||
* `operation_type`：操作类型
|
||
* `operation_content`：操作内容
|
||
* `created_at`：操作时间
|
||
|
||
### 7.7 用户表 UserAccount
|
||
* `id`：主键
|
||
* `username`：登录账号
|
||
* `password_hash`：密码哈希值
|
||
* `display_name`：显示名称
|
||
* `user_type`：用户类型，建议值为 `ADMIN`、`NORMAL`
|
||
* `status`：账号状态，建议值为 `ENABLED`、`DISABLED`
|
||
* `last_login_at`：最近登录时间
|
||
* `created_by`：创建人 ID
|
||
* `created_at`：创建时间
|
||
* `updated_at`：更新时间
|
||
|
||
### 7.8 用户权限表 UserPermission
|
||
* `id`：主键
|
||
* `user_id`：用户 ID
|
||
* `permission_code`：权限编码，如 `PRODUCT_VIEW`、`PRODUCT_EDIT`、`ASSET_UPLOAD`、`ORDER_VIEW`、`ORDER_PROCESS`、`ORDER_COMPLETE`、`STATISTICS_VIEW`、`USER_MANAGE`
|
||
* `permission_name`：权限名称
|
||
* `created_at`：创建时间
|
||
|
||
说明：管理员默认拥有全量权限；普通用户通过权限表进行授权。
|
||
|
||
---
|
||
|
||
## 8. 接口规划建议
|
||
|
||
### 8.1 认证与用户接口
|
||
* `POST /api/auth/login`：用户名密码登录
|
||
* `POST /api/auth/logout`：退出登录
|
||
* `GET /api/auth/me`：获取当前登录用户及权限
|
||
* `GET /api/users`：分页查询用户列表，仅管理员可用
|
||
* `POST /api/users`：新增普通用户，仅管理员可用
|
||
* `PUT /api/users/{id}`：编辑用户基础信息，仅管理员可用
|
||
* `PUT /api/users/{id}/password`：重置用户密码，仅管理员可用
|
||
* `PUT /api/users/{id}/status`：启用或停用用户，仅管理员可用
|
||
* `PUT /api/users/{id}/permissions`：分配用户权限，仅管理员可用
|
||
|
||
### 8.2 类目接口
|
||
* `GET /api/categories/tree`：获取类目树
|
||
* `POST /api/categories`：新增类目
|
||
* `PUT /api/categories/{id}`：编辑类目
|
||
* `DELETE /api/categories/{id}`：删除类目
|
||
|
||
### 8.3 商品接口
|
||
* `GET /api/categories/{id}/products`：获取某类目下商品列表
|
||
* `GET /api/products/{id}`：获取商品详情
|
||
* `POST /api/products`：新增商品
|
||
* `PUT /api/products/{id}`：编辑商品
|
||
* `DELETE /api/products/{id}`：删除商品
|
||
|
||
### 8.4 附件接口
|
||
* `GET /api/products/{id}/assets`：获取商品附件元数据列表
|
||
* `POST /api/products/{id}/assets`：上传商品图片或标签文件
|
||
* `GET /api/products/{id}/assets/{assetId}/download`：获取原图或标签文件下载流
|
||
* `PUT /api/products/{id}/assets/{assetId}/primary`：将图片附件设为主图
|
||
* `PUT /api/products/{id}/assets/image-order`：按拖拽结果更新商品图片顺序
|
||
* `DELETE /api/products/{id}/assets/{assetId}`：删除附件
|
||
|
||
### 8.5 订单接口
|
||
* `POST /api/orders`：创建订单
|
||
* `GET /api/orders`：查询订单列表
|
||
* `GET /api/orders/{id}`：查询订单详情
|
||
* `PUT /api/orders/{id}`：编辑未完成订单
|
||
* `DELETE /api/orders/{id}`：删除未完成订单；管理员可删除已完成订单
|
||
* `POST /api/orders/{id}/complete`：填写快递单号并完成订单
|
||
* `GET /api/orders/{id}/labels/download`：按当前订单数量导出标签文件
|
||
|
||
### 8.6 统计接口
|
||
* `GET /api/statistics/monthly`：月度统计
|
||
* `GET /api/statistics/yearly`：年度统计
|
||
|
||
---
|
||
|
||
## 9. 关键业务规则
|
||
1. 所有业务接口默认要求登录后访问；登录成功后才能进入系统主界面。
|
||
2. 管理员用户拥有全部页面查看、数据编辑、订单处理、统计查看和用户管理权限。
|
||
3. 普通用户账号必须由管理员创建，权限必须由管理员分配；未授权功能默认不可访问。
|
||
4. 前端必须根据权限控制菜单、路由和按钮显示，后端必须同步校验接口权限，不能只依赖前端隐藏。
|
||
5. `requires_detail_page = false` 的类目不进入商品详情页，不要求维护价格、库存等业务字段。
|
||
6. 商品详情页必须支持直接上传图片和标签文件，并支持多图管理。
|
||
7. 只拥有商品查看权限的普通用户可以浏览商品详情，但不可编辑商品、上传附件或删除数据。
|
||
8. 停产商品默认不可直接加入订单；如需下单，应由后端做显式校验或弹出确认。
|
||
9. 下单数量不得超过库存数量，库存不足时必须提示并拦截。
|
||
10. 未完成订单允许编辑、删除；已完成订单默认只允许查看，但管理员可删除整单。
|
||
11. 只有拥有订单处理或订单完成权限的用户才可修改订单、填写快递单号并完成订单。
|
||
12. 标签下载入口统一放在订单详情页，不保留在右侧订单摘要中。
|
||
13. 统计页面仅管理员或拥有统计查看权限的用户可访问。
|
||
14. 统计数据建议基于订单明细快照字段计算，避免商品后续改价影响历史统计结果。
|
||
15. 所有附件列表接口默认只返回元数据，不直接返回数据库二进制内容。
|
||
|
||
---
|
||
|
||
## 10. 非功能要求
|
||
1. **性能**：商品列表与订单列表接口不得直接加载 BLOB 字段；图片通过独立接口按需读取。
|
||
2. **安全**：上传接口需校验文件类型、大小与权限；下载接口需校验访问权限；密码必须加密存储；登录接口需具备基础防暴力破解能力。
|
||
3. **稳定性**：订单创建、订单完成、库存扣减等操作必须在事务中处理；SQLite 建议启用 WAL 模式并控制并发写入。
|
||
4. **备份**：由于图片保存在 SQLite 数据库文件中，备份策略必须覆盖数据库主文件及其相关日志文件。
|
||
5. **可维护性**：接口统一返回结构，前后端统一错误码与提示文案。
|
||
|
||
---
|
||
|
||
## 11. 验收标准
|
||
1. 系统支持用户名密码登录，未登录状态不能直接进入业务页面。
|
||
2. 管理员用户可查看和编辑全部模块，并可进入用户管理页面。
|
||
3. 管理员可创建普通用户、重置密码、启用或停用账号，并分配权限。
|
||
4. 仅拥有商品查看权限的普通用户只能浏览商品列表和商品详情，不显示编辑、上传、删除按钮。
|
||
5. 拥有订单处理权限的打包工用户可查看订单、填写快递单号并完成订单，但不可编辑商品和用户。
|
||
6. 左侧目录支持类目与商品节点的新增、编辑、删除、跳转。
|
||
7. 商品卡片墙可正常展示缩略图、状态、价格、库存并支持快捷加购。
|
||
8. 商品详情页可编辑 SKU、价格、库存状态、库存数量，并支持多图上传与标签文件上传。
|
||
9. 图片上传后保存在数据库中，刷新页面后仍可读取和下载原图。
|
||
10. 订单列表页支持全部、未完成、已完成筛选。
|
||
11. 未完成订单可编辑和删除；填写快递单号后可完成订单并转为只读。
|
||
12. 订单详情页可查看完整商品明细并执行标签按量下载。
|
||
13. 月度和年度统计页面能正确统计每款商品数量、单价、小计与总价。
|
||
|