1.0.1 初始化铜壶管理系统项目并配置容器化

This commit is contained in:
Hongying Li
2026-04-12 18:28:37 +08:00
parent 72239c24fd
commit 5dd16d9809
129 changed files with 15165 additions and 0 deletions

View File

@@ -0,0 +1,394 @@
# 铜壶管理系统 - 商品展示、详情与订单管理设计文档
## 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. 月度和年度统计页面能正确统计每款商品数量、单价、小计与总价。