# 铜壶管理系统 - 商品展示、详情与订单管理设计文档

## 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. 月度和年度统计页面能正确统计每款商品数量、单价、小计与总价。