teapot_system/商品详情与订单页面设计文档.md

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

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