办公用品直售推荐系统全栈实战：SpringBoot+Vue前后端分离设计

1. 项目概述

1.1 核心需求解析

办公用品直售系统这个方向其实一直很有搞头。大多数企业采购日常办公用品的流程还很原始——行政翻商品目录、人工比价、邮件审批、月底对账，效率低不说，采购记录还不透明。平时咱们做管理系统做得多了，这次我决定动手做一个真正能落地的“日常办公用品直售推荐系统”，核心解决三个问题：让行政人员能在一个系统里完成选品、下单、审批、收货的全流程；让管理层实时掌握各科室的办公用品消耗和开支情况；通过推荐功能把高频用品、同类替代品推到用户面前，减少重复搜索和决策成本。

技术选型上我直接定了前后端分离架构：SpringBoot做后端服务、Vue做前端界面、MyBatis负责数据持久层、MySQL存业务数据。这套组合是目前中小型管理系统最主流、也最容易招到人维护的方案。前后端分离的好处不只是“看起来专业”，更重要的是前端静态资源可以独立部署到Nginx，后端服务独立扩容，开发调试互不干扰，接口层面的耦合降到了最低。

这篇内容我打算从架构设计、核心模块实现、推荐逻辑、部署上线到踩坑排查，完整梳理一遍。适合正在做毕业设计、想练手全栈项目、或者公司内部需要搞一套采购管理系统的朋友参考。代码量不小，但每一步我都会写清楚“为什么这么做”的思路，而不是贴一堆代码让你自己猜。

1.2 技术栈全景与角色定位

先看一下这次项目的整体技术组合，每层选什么、解决什么问题，给还没开工的同学一个全局视角：

这个选型的核心逻辑就两条：第一，团队成员熟悉度优先，招人容易、出问题网上资料多；第二，生态成熟度优先，Element UI + SpringBoot + MyBatis 这种组合经过大量生产项目验证，坑基本都被踩平了。如果你非要用 MyBatis-Plus 或 JPA，问题也不大，但下面讲的代码和配置你得多做一层适配。

2. 项目整体设计与思路拆解

2.1 业务模块划分

办公用品直售系统不是简单的CRUD堆砌，我拿到需求后第一件事是梳理角色和核心流程。系统里一共有三种角色：管理员负责商品上下架、分类管理、订单处理和数据统计；普通员工浏览商品、加购下单、查看自己的订单和推荐商品；财务/审批人（这里我简化成管理员兼任）负责审核采购单、确认付款状态。

围绕这三个角色，系统拆成了以下几个核心模块：

• 用户认证模块：登录、注册、JWT令牌签发与校验、角色权限控制。
• 商品管理模块：商品分类、品牌维护、库存管理、商品上下架状态切换。
• 推荐模块：基于用户浏览记录和购买历史的协同过滤推荐，按热度推荐，按部门常用品类推荐。
• 购物车与订单模块：加入购物车、修改数量、批量下单、订单状态流转（待付款/已付款/已发货/已完成）。
• 数据统计模块：商品销量排行、分类消耗占比、各部门采购金额统计。

模块划分的原则是高内聚低耦合，这一点在前后端分离项目里更关键。前端每个页面只调自己业务域下的接口，后端每个Controller只处理单一资源，这样后面加功能、修Bug都不容易互相踩脚。

2.2 前后端分离的接口设计规范

接口设计是前后端分离项目的命脉。我这次统一采用RESTful风格，/api作为统一前缀，版本号也放在路径里，比如管理端接口统一走/api/admin/**，客户端接口走/api/portal/**。返回结构统一封装：

{ "code": 200, "message": "操作成功", "data": { "total": 100, "list": [] } }

这个封装看着简单，但它解决了一个非常大的痛点：前端不用再为每个接口单独处理异常分支。Axios响应拦截器里统一判断code，不是200就直接弹错误提示，正常数据直接从data字段取。状态码定义我也做了一套约定：200成功、400参数错误、401未登录、403无权限、500服务器异常，前后端按这个约定沟通，全是哑谜的情况基本消失。

前端路由设计上采用动态路由注册。用户登录之后，后端根据角色返回可访问的路由表，前端用router.addRoutes动态挂载。这样做的好处是菜单和权限天然联动——普通用户根本不会看到管理后台的入口，权限控制前置到了路由层面，后端接口再加一层校验，双保险。

2.3 为什么选MyBatis而不是JPA

我知道很多人纠结过这个问题。JPA/Hibernate开发效率高，不用写SQL，但碰到多表联查、动态条件排序这种场景反而麻烦，而且SQL不可见导致性能调优困难。MyBatis的核心优势是SQL完全可控，你能精确掌握每条SQL的执行计划，慢查询一抓一个准。对于订单列表这种带多条件筛选、排序、分页的查询，MyBatis的动态SQL写起来非常自然。

比如商品列表查询，我写了这么一段动态SQL：

<select id="selectProductPage" resultType="com.yunyi.office.entity.Product"> SELECT p.*, c.name AS category_name FROM product p LEFT JOIN category c ON p.category_id = c.id <where> <if test="keyword != null and keyword != ''"> AND (p.name LIKE CONCAT('%', #{keyword}, '%') OR p.brand LIKE CONCAT('%', #{keyword}, '%')) </if> <if test="categoryId != null"> AND p.category_id = #{categoryId} </if> <if test="status != null"> AND p.status = #{status} </if> </where> ORDER BY p.sales_volume DESC, p.create_time DESC </select>

<where>标签会自动处理首个条件前的AND，<if>做条件动态拼接，这段SQL既避免了写死多套查询接口，又能应对组合筛选。用到后面你会体会到，MyBatis的XML写法虽然“啰嗦”，但排查问题时极其舒服——直接把XML里的SQL粘到Navicat里一跑就知道问题在哪了。

3. 核心功能模块实现详解

3.1 登录鉴权模块：Spring Security还是JWT拦截器？

很多教程一上来就上Spring Security + JWT全家桶，配置类写一大堆，新手直接懵。这个项目我采取的是轻量级方案：自定义拦截器 + JWT工具类，代码量少、逻辑直观、完全够用。

JWT（JSON Web Token）说白了就是服务端签发给客户端的一张“通行证”，客户端每次请求把Token放在请求头里，服务端校验签名和过期时间，就能确认用户身份。它最大的优势是服务端无状态，不用在Session里存登录信息，方便前后端分离部署和横向扩展。

JWT生成的核心代码大概这样：

public String generateToken(Integer userId, String username, String role) { return Jwts.builder() .setSubject(username) .claim("userId", userId) .claim("role", role) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 2)) .signWith(SignatureAlgorithm.HS256, secretKey) .compact(); }

我在这里设置了2小时过期时间，实际项目中可以根据安全要求调整。拦截器里校验Token的方法是重写preHandle，从请求头拿Authorization字段，剥掉Bearer前缀后解析。解析失败或过期直接返回401状态码，前端Axios响应拦截器收到401就跳转登录页。

权限这块我做了两层：拦截器只负责“是否登录”，角色的精细控制通过**方法级的自定义注解@RequireRole("ADMIN")**完成。管理员接口打上注解，拦截器检测到注解后比对当前用户角色，不匹配返回403。这种方式比Spring Security的注解配置更轻，也更直观。

注意：JWT密钥必须放到配置文件里，别写死在代码里。如果项目要上生产，建议将密钥长度调整到至少32字节，并定期轮换。

3.2 商品管理模块：分类、库存与图片存储方案

商品管理是直售系统的地基，核心表设计有四张：分类表(category)、商品表(product)、库存表(stock)、商品图片表(product_image)。分类和商品是典型的一对多关系，商品和图片是一对多关系。图片存储方案一开始我纠结过是存本地路径还是存MinIO对象存储，为了控制部署复杂度，最终选择了本地目录存储 + 数据库存相对路径的方案，部署时再映射一个虚拟路径到静态资源目录。

上传接口的关键逻辑是：接收MultipartFile → 校验文件类型和大小（只允许jpg、png，最大5MB）→ 生成UUID文件名 → 保存到指定磁盘目录 → 返回访问URL。这里有个细节：文件名必须重新生成，不能用用户上传的原始文件名，否则会有路径穿越漏洞和重名覆盖问题。

商品列表查询我加了一个实用的设计：上下架状态和时间戳联动。自动上架定时任务，每晚零点检查，把到达上架时间且库存大于0的商品自动改为上架状态。这个功能是参考电商系统的秒杀上架逻辑做的，行政人员不用守着电脑手动点上架，体验好很多。

3.3 推荐模块：从“猜你喜欢”到办公场景落地

说到推荐系统，很多同学第一反应就是复杂的机器学习模型、协同过滤、Embedding，项目一下子变得“高大上”起来。但在这个办公用品直售场景里，用户量级和商品量级决定了太复杂的推荐算法纯属杀鸡用牛刀。我采用的是“规则引擎 + 简单统计”的混合推荐策略，效果稳定且解释性强。

推荐策略我设计了三种模式，前端推荐位轮流展示：

• 热门推荐：读取最近7天销量最高的前10件商品，适合新人进入系统时展示，无冷启动问题。
• 同类推荐：用户浏览某个商品时，推荐同分类下、价格区间接近、评价较好的其他商品，SQL里直接关联查询就好。
• 历史偏好推荐：统计该用户之前的订单商品分类分布，找出占比最高的两三个分类，推荐这些分类下用户未购买过但评分不错的商品。

第三种策略的SQL实现很直观：

SELECT p.id, p.name, p.price, p.image_url FROM product p WHERE p.category_id IN ( SELECT oi.category_id FROM order_item oi JOIN orders o ON oi.order_id = o.id WHERE o.user_id = #{userId} GROUP BY oi.category_id ORDER BY COUNT(*) DESC LIMIT 2 ) AND p.id NOT IN ( SELECT oi.product_id FROM order_item oi JOIN orders o ON oi.order_id = o.id WHERE o.user_id = #{userId} ) AND p.status = 1 LIMIT 6

这SQL一眼就能看懂：先算用户最常买的两类商品，再把这两类里他还没买过的东西捞出来。用户画像数据的采集也简单——在商品详情页埋一个浏览记录接口，每次点击详情都往后端记录一条浏览日志，用于后续的分析和推荐位权重调整。

3.4 购物车与订单模块：事务与状态机设计

购物车和订单是事务操作最密集的区域，也是最容易出Bug的地方。购物车我用了Redis缓存 + MySQL持久化双写方案：用户加购时先写Redis（加快购物车页面响应速度），同时异步同步到MySQL表，防止Redis数据丢失造成购物车清空。

下单的核心流程是这样的：

1. 前端提交购物车选中的商品ID列表。
2. 后端开启事务，逐条锁定库存（SELECT ... FOR UPDATE，或者用乐观锁版本号防止超卖）。
3. 生成订单主记录和订单明细记录，计算总金额，生成订单号。
4. 扣减库存，清空对应购物车项。
5. 事务提交，返回订单号。

订单状态我用一个status字段管理，数值含义如下表：

状态流转的核心逻辑我放在了状态机类里，而不是散落在各个Service方法中。每个状态定义允许的“下一个状态集合”，非法流转直接抛异常。这样改状态就变成了一张表驱动的决策，新增状态只要加节点和连线，代码改动力度大大减少。

4. 数据库设计实战

4.1 核心表结构设计

数据库是整个系统的“地基”。我直接贴出核心表结构的DDL，大家可以参考着建表：

CREATE TABLE `user` ( `id` INT NOT NULL AUTO_INCREMENT, `username` VARCHAR(50) NOT NULL UNIQUE, `password` VARCHAR(255) NOT NULL COMMENT 'BCrypt加密存储', `real_name` VARCHAR(50) DEFAULT NULL, `department` VARCHAR(100) DEFAULT NULL COMMENT '部门', `role` TINYINT DEFAULT 1 COMMENT '1-普通用户 2-管理员', `status` TINYINT DEFAULT 1 COMMENT '1-正常 0-禁用', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `product` ( `id` INT NOT NULL AUTO_INCREMENT, `category_id` INT NOT NULL, `name` VARCHAR(100) NOT NULL, `brand` VARCHAR(50) DEFAULT NULL, `price` DECIMAL(10,2) NOT NULL, `stock` INT DEFAULT 0, `sales_volume` INT DEFAULT 0, `image_url` VARCHAR(255) DEFAULT NULL, `detail` TEXT, `status` TINYINT DEFAULT 1 COMMENT '1-上架 0-下架', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_category` (`category_id`), KEY `idx_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; CREATE TABLE `orders` ( `id` INT NOT NULL AUTO_INCREMENT, `order_no` VARCHAR(32) NOT NULL UNIQUE COMMENT '业务订单号', `user_id` INT NOT NULL, `total_amount` DECIMAL(10,2) NOT NULL, `status` TINYINT DEFAULT 0, `receiver_name` VARCHAR(50) NOT NULL, `receiver_phone` VARCHAR(20) NOT NULL, `receiver_address` VARCHAR(255) NOT NULL, `remark` VARCHAR(255) DEFAULT NULL, `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP, `pay_time` DATETIME DEFAULT NULL, PRIMARY KEY (`id`), KEY `idx_user` (`user_id`), KEY `idx_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

这里我特意用了utf8mb4字符集，而不是utf8。原因是utf8在MySQL里最多存3字节字符，存不了emoji和生僻字，utf8mb4才是真正的完整Unicode支持。办公用品描述里万一出现####符号，你用utf8就直接报错。

4.2 索引设计与性能考虑

索引设计是这个项目性能优化的核心。我遵循了几个基本原则：查询频率高的字段建索引，区分度低的字段不建索引，联合索引遵守最左前缀法则。

订单表的核心查询场景是“某个用户查看自己的订单列表”，所以user_id建索引是必须的。但还有一个高频场景是管理员端按状态筛选订单，所以status字段也建了索引。商品表按分类筛选、按状态筛选是高频操作，category_id和status就分别建了索引。

分页查询上有个坑值得提醒：LIMIT偏移量过大会导致深分页问题，比如翻到第100页时，LIMIT 990, 10需要先扫描前面990条记录再丢弃，非常浪费。这个项目里订单列表我改成了基于游标的分页，前端传来的不是页码而是上一页最后一条记录的ID，SQL变成WHERE id < #{lastId} ORDER BY id DESC LIMIT 10。数据量几万条的时候感受不出来，几十万条以上差距就非常明显了。

4.3 初始化数据与SQL脚本实践

项目里我准备了一份完整的初始化SQL脚本，包含建库建表、基础分类数据、测试账号和一批示例商品数据。这些数据看起来普通，但里面有几个细节：密码字段全部用BCrypt加密后的字符串，不会出现明文密码（哪怕只是测试数据也不能偷懒写明文）；商品图片路径用的是相对路径，方便部署到不同环境时拼接IP；订单数据特意造了跨越最近30天的记录，方便统计模块测试“近7天销量”“本月采购额”这类时间窗口查询。

导入数据的顺序也要注意：先建库、再建表、然后插入基础数据和用户数据。使用Navicat直接运行SQL脚本是最省事的，命令行方式则用mysql -u root -p < init.sql。如果不小心导错了，直接删库重建，开发阶段不用怕。

5. 部署全流程实战

5.1 环境准备：JDK、Maven、MySQL、Node.js

这环节看着基础，但版本不兼容能把人折腾疯。我推荐一套稳定版本组合：JDK 1.8 / Maven 3.6.x / MySQL 5.7或8.0 / Node.js 14.x / npm 6.x。Spring Boot 2.3.x官方支持JDK 8到JDK 14，但JDK 8最稳，生产环境也最常见，别去追新。

JDK安装完一定要配好环境变量JAVA_HOME，命令行输java -version能出来版本才算配好。Maven装好后，conf/settings.xml里记得配置阿里云镜像，否则下载依赖的速度会让你怀疑人生。MySQL安装这步，Windows用户直接装MySQL Installer，一路Next，但要注意选对字符集，安装时默认是utf8mb4一般没问题，但如果是5.7老版本，务必检查my.ini里的character-set-server配置。Linux用户用rpm包安装或者yum安装都行，装完数据库初始化时设置密码，记住默认端口3306，别跟其他服务冲突。

5.2 后端打包与启动

后端项目的构建用Maven。命令行进入项目根目录（就是在pom.xml所在目录），执行打包命令：

mvn clean package -DskipTests

-DskipTests会跳过单元测试，如果你的测试代码里连了数据库，不跳过很容易在打包阶段报连接错误。打包完成后，target目录下会生成一个xxxxxxxx.jar，这个jar包就是可以独立运行的后端服务了。

启动有两种方式，开发环境用mvn spring-boot:run，方便热调试；生产环境直接java -jar跑jar包，简单粗暴。注意java -jar启动时，数据库连接信息和Redis地址要提前改好。我习惯把不同环境的配置拆成application-dev.yml和application-prod.yml，启动时用--spring.profiles.active=prod指定环境，避免每次发布前手忙脚乱改配置。

为了部署管理方便，我写了一个start.sh启动脚本，内容大概是这样：

#!/bin/bash APP_NAME=office-supply-system.jar nohup java -jar /opt/office/${APP_NAME} \ --spring.profiles.active=prod \ --server.port=8080 \ > /opt/office/logs/app.log 2>&1 & echo "App started, pid: $!"

nohup+ 后台运行是关键，否则你关掉终端服务就停了。日志重定向到文件，方便排查问题，这是上线后无数次要用的操作，别嫌麻烦。

5.3 前端打包与部署到Nginx

前端打包前先检查vue.config.js里的代理配置。开发环境通过proxy把接口请求转发到http://localhost:8080，解决跨域问题；但打包后这个代理就失效了，所以生产环境的前端请求必须走完整的后端地址，或者在Nginx里配置反向代理。

我在axios的封装文件里用环境变量区分请求地址：

const baseURL = process.env.NODE_ENV === 'production' ? 'http://你的服务器IP:8080/api' : '/api' // 开发环境由vue.config.js代理转发

执行打包构建：

npm run build

打包完成后，dist目录就是纯静态文件，包括index.html、css、js等。把dist目录下的所有文件拷贝到Nginx的html目录（或者你自己指定的站点目录），然后配置Nginx：

server { listen 80; server_name your-domain.com; location / { root /usr/share/nginx/html; index index.html index.htm; # 前端路由history模式需要这个配置 try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

这个配置解决两个核心问题：try_files指令是Vue Router使用history模式时必须要配的，否则刷新页面会404；location /api/把前端发来的/api请求转发到后端的8080端口，前后端在同一个域下通信，规避跨域。如果你的系统要配HTTPS，再在server块里加SSL证书配置，跟这个不冲突。

5.4 Docker化部署思路

Docker部署可以让环境配置和扩展变得非常简单。我给项目写了两份Dockerfile，一份给后端、一份给前端Nginx。后端Dockerfile核心就三步：基础镜像用openjdk:8-jdk-alpine，把jar包拷贝进去，然后执行启动命令。前端Dockerfile基于nginx:alpine镜像，把dist目录里的文件拷贝到Nginx的/usr/share/nginx/html。

最省事的是用docker-compose.yml一键编排，把MySQL、Redis、后端、前端四个服务一起启动：

version: '3.8' services: mysql: image: mysql:5.7 environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: office_supply volumes: - ./mysql-data:/var/lib/mysql ports: - "3306:3306" backend: build: ./backend environment: SPRING_PROFILES_ACTIVE: prod ports: - "8080:8080" depends_on: - mysql frontend: build: ./frontend ports: - "80:80" depends_on: - backend

用docker-compose up -d一键启动所有服务，再也不用担心环境不一致的“我本地跑得好好的啊”问题了。但提醒一句：Docker容器里连MySQL时，localhost是容器自身的地址，要连mysql服务名，而不是localhost。这个错我在第一次部署时踩过，整整查了一个小时。

6. 常见问题与排查技巧实录

6.1 后端启动报错：数据库连接失败

最常见的启动报错就是Communications link failure，或者Access denied for user 'root'@'localhost'。前者通常意味着数据库没起来、端口不对或者MySQL拒绝远程连接。后者就是密码错了、或者密码对但MySQL用户表里该用户不允许从当前主机登录。

排查顺序我一般这么走：先telnet 127.0.0.1 3306确认端口通不通，再用命令行登录MySQL试试能不能用配置文件里的账号密码连接。如果本地命令行能连而程序连不上，大概率是jdbc.url里写的地址有问题——比如在云服务器上写localhost没问题，但连接字符串里带了serverTimezone=Asia/Shanghai而服务器时区不对，也会报错。

MySQL 8.0的加密规则是个隐藏坑。MySQL 8.0默认使用caching_sha2_password插件，而某些老版本的JDBC驱动只支持mysql_native_password，连接时会报Public Key Retrieval is not allowed。解决方案是连接串上加allowPublicKeyRetrieval=true，或者把用户的插件改成mysql_native_password：

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的密码';

6.2 Vue前端白屏与路由404

前端打包后扔到Nginx，访问首页一切正常，但一刷新页面就404，这几乎是每个用history路由的Vue项目都会踩的坑。原因前面提到过：Nginx配置里没有try_files $uri $uri/ /index.html;这一行，Nginx收到/order/list路径的请求后在自己的目录里找order/list文件，找不到就返回404。

解决办法就是加上那行配置后nginx -s reload。还有一个更隐蔽的问题：如果前端打包后图片资源路径不对，白屏或图片全挂。检查一下vue.config.js里publicPath配置，必须设为'./'（相对路径）或空字符串，不能默认的'/'。否则把dist部署到子目录时，资源路径是从根目录开始找的，一旦域名根目录下没有对应文件，全部资源请求都会404。

6.3 MyBatis相关配置与调优

MyBatis配置里有几个容易忽略但影响很大的点。

第一个是驼峰映射。数据库字段一般是create_time，Java实体属性是createTime，如果MyBatis不开启驼峰映射，查询结果里create_time字段就映射不到createTime属性上，返回给前端就是null。必须在application.yml里配置：

mybatis: configuration: map-underscore-to-camel-case: true

第二个是SQL日志打印。开发阶段强烈建议开启控制台SQL日志，不然调试SQL极其痛苦：

mybatis: configuration: log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

开启后，每次执行SQL都会把完整SQL和参数打印到控制台，排查问题时直接拿这条SQL去数据库工具里执行，效率提升一大截。生产环境记得关掉，否则日志量会非常恐怖。

第三个是关于MyBatis的二级缓存。一级缓存默认开启，同一个SqlSession内有效，但Spring里每次Mapper调用基本都是新Session，一级缓存意义不大。二级缓存要跨Session共享，配置了<cache/>后还要注意实体类必须实现Serializable接口。我这次项目没有开启二级缓存——办公用品系统的读多写少场景确实存在，但数据一致性更重要，尤其库存和订单状态不能接受缓存延迟。真要优化性能，加Redis做业务缓存就可以了，比MyBatis二级缓存好控制得多。

6.4 跨域请求的三种典型场景

跨域是前后端分离项目绕不开的问题。你可能会遇到三种情况：

场景一：本地开发联调，前端在8080端口，后端在8081端口。这种最简单，Vue CLI项目里直接在vue.config.js配置devServer代理：

devServer: { proxy: { '/api': { target: 'http://localhost:8081', changeOrigin: true } } }

场景二：后端线上单独部署，Nginx只托管前端静态页。Nginx配置里用proxy_pass转发/api到后端地址，同时保留前端路由的try_files。这种方案的好处是浏览器看到的请求是同源的，不触发跨域。

场景三：前后端域名不同，比如前端shop.example.com、后端api.example.com。这种必须靠后端开启CORS：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); } }

这里有个坑：allowCredentials(true)时，allowedOrigins不能使用*，必须用allowedOriginPatterns或在配置中写具体域名，否则浏览器会直接拦截响应。

6.5 前端调用接口常见报错处理

Axios封装的响应拦截器是我调试接口的第一道防线。我在拦截器里统一处理了HTTP状态码：401跳到登录页并清空本地登录态；403提示“没有权限”；500弹“服务器开小差了，请稍后重试”。这些提示信息让前端人员能第一时间定位问题方向，不用每次都打开F12看Network面板。

还有一类报错很磨人：请求正常返回，但页面数据不渲染。大部分情况是后端返回的字段名和前端用的不一致，比如后端返回createTime，前端写成了create_time。解决这类问题的唯一有效手段是查接口文档或直接看浏览器Network里的响应体，前后端接口文档必须跟上，哪怕用最简单的Markdown表格记录也要写。我这次项目虽然没有引入Swagger，但接口文档单独维护了一份，不然联调阶段一天能被问八遍“这个接口的参数是什么来着”。

7. 推荐算法细节与个性化落地

7.1 基于物品的协同过滤简化版

如果要给推荐模块加一点“算法含量”，我选择了基于物品的协同过滤（Item-based CF）的简化版本。核心思路是：如果用户A买了商品X和Y，用户B买了商品X，那么给B推荐Y，因为X和Y之间有相似性。放在办公用品场景里就是——买了A4复印纸的人，大概率也需要买签字笔；买了档案盒的人，往往也需要买文件夹。

物品相似度的计算我不打算引入复杂的Spark或Mahout，直接用SQL和Java内存计算，商品量级在几千到几万时完全扛得住。

计算过程分两步：

1. 每晚定时任务从订单明细表提取“商品-用户”共现矩阵。
2. 用余弦相似度公式计算商品间的相似度，结果存入product_similarity表。

余弦相似度的公式是cos(a,b) = (a·b) / (|a| × |b|)，其中向量a、b分别表示两个商品被哪些用户购买过的“稀疏向量”。我用Java实现了一个简化版：

public double cosineSimilarity(Map<Integer, Integer> userRates1, Map<Integer, Integer> userRates2) { Set<Integer> intersection = new HashSet<>(userRates1.keySet()); intersection.retainAll(userRates2.keySet()); double dotProduct = 0; double norm1 = 0; double norm2 = 0; for (Integer userId : intersection) { dotProduct += userRates1.get(userId) * userRates2.get(userId); } for (double value : userRates1.values()) { norm1 += value * value; } for (double value : userRates2.values()) { norm2 += value * value; } if (norm1 == 0 || norm2 == 0) return 0; return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2)); }

每天凌晨两点执行一次相似度计算任务，结果更新到数据库。用户浏览商品详情时，后端从这个表里取相似度排前N个的商品返回。

7.2 推荐效果的评估与调优

做完推荐功能，我总得验证它到底有没有用。我设置了一张recommend_log表，记录每次推荐的“曝光”情况：给谁推荐了哪些商品、用户有没有点击、点击之后有没有加购下单。这样就能统计两个指标：曝光点击率（CTR）和点击购买转化率（CVR）。

用SQL统计点击率：

SELECT COUNT(DISTINCT CASE WHEN clicked = 1 THEN user_id END) / COUNT(DISTINCT user_id) AS ctr, COUNT(DISTINCT CASE WHEN ordered = 1 THEN user_id END) / COUNT(DISTINCT user_id) AS cvr FROM recommend_log WHERE create_time >= DATE_SUB(NOW(), INTERVAL 7 DAY);

上线跑了一周后的数据显示：热门推荐位的CTR在8%左右，同类推荐在6%左右，历史偏好推荐在11%左右。说明“根据用户历史行为推荐”确实更精准。于是我调整了推荐位权重，把历史偏好的展示比例提高了，整体点击率上升了大概3个百分点。这就是数据驱动的价值——不要拍脑袋决定功能优先级，先用日志数据说话。

7.3 冷启动问题的处理策略

推荐系统里最经典的问题是冷启动：新用户没有历史行为，新商品没有购买记录，推荐什么？我这套系统对冷启动的处理比较务实：

• 用户冷启动：注册进入系统时，引导选择“所属部门”，部门信息决定了初始推荐池（设计部推马克笔和绘图纸，行政部推订书机和文件夹）。用户第一次浏览商品、第一次下单之后，逐渐切回历史偏好推荐。
• 商品冷启动：新上架商品没有销量，很难进入热门榜。我设计了一个“新品推荐位”，上架30天内销量未起色的商品可以加权展示，权重按天数递减。这个逻辑在SQL里实现很简单，ORDER BY里加一个带时间衰减的排序字段即可。

这套冷启动策略的效果做测试也简单——注册五个不同部门的新账号，看首页推荐是否不同；上架五件新商品，看新品位是否展示。跑通就算合格。

8. 系统安全与性能加固

8.1 密码加密与SQL注入防护

系统的安全设计不能等上线前才想。用户密码我全部用BCrypt加密存储，Spring Security自带BCryptPasswordEncoder可以直接用，这个算法的好处是每次加密结果都带随机盐，相同密码加密后的字符串也不一样，彩虹表攻击拿你没办法。

登录认证成功后，我还会校验用户状态——被管理员禁用的用户即使密码对也不能登录，返回明确提示“账号已被禁用，请联系管理员”。

SQL注入防护主要靠MyBatis的#{}预编译机制。MyBatis中#{}和${}有本质区别：#{}会生成PreparedStatement的占位符?，参数由数据库驱动处理，不存在注入可能；${}是直接字符串拼接，除非是做动态表名、排序列名这类场景，否则绝不使用。我在项目里给动态排序专门做了白名单校验，前端传的排序列名只有id、price、sales_volume、create_time这几个可信值，其他一律按默认排序处理。

8.2 接口限流与操作日志

管理员接口被暴力刷是一个非常现实的风险。我写了简易的接口限流拦截器，基于Redis的INCR和EXPIRE命令实现：同一个IP在1分钟内访问超过60次，后续请求直接返回“操作过于频繁”。这个值对正常用户完全够用，但对爬虫和恶意请求就是一道明显的门槛。

操作日志这块我用AOP实现，自定义了一个@OperationLog注解标记在需要记录的方法上。谁、在什么时间、对哪个资源做了什么操作，这些信息都异步写入operation_log表。这对排查“是谁改了下架状态”“谁删了某个商品”这类问题极其重要，尤其是管理后台没人认账的时候。

8.3 读写分离与MySQL性能调优思路

当系统用户量增大到一定程度，可以把MySQL配置为主从复制，后端通过AOP切换数据源实现读写分离。读请求走从库、写请求走主库，主从延时一般在毫秒级，对系统业务完全够用。Spring Boot里配置两个数据源，分别指向主库和从库，再用@DataSource注解标记Service方法走哪个库即可。

MySQL本身的调优我做了几件基础的事：把innodb_buffer_pool_size调整到物理内存的70%左右；慢查询日志打开，设置long_query_time = 1，每秒执行超过1秒的SQL都会记录到日志里。上线初期跑几天，看一眼慢查询日志，揪出几个漏建索引的查询场景，性能基本就稳了。这一步一定要做，我发现项目里最容易慢的查询是订单明细表的大范围GROUP BY统计，后来加了联合索引，查询时间从1.8秒降到了0.2秒。

9. 项目源码结构与开发辅助工具

9.1 后端包结构模板

一个好的包结构能让项目后期维护省掉无数心思。我的后端包结构如下：

com.yunyi.office ├── config // 配置类：跨域、拦截器、WebMvc ├── controller // 接口层：只做参数接收和响应封装 ├── service // 业务逻辑层：事务、状态机、推荐计算 ├── mapper // MyBatis数据访问接口 ├── entity // 数据库实体类 ├── dto // 前端交互的数据传输对象 ├── vo // 视图对象：组合查询结果的封装 ├── common // 通用类：返回结果封装、常量、异常处理 ├── utils // 工具类：JWT、文件上传、时间处理 ├── annotation // 自定义注解 └── aspect // AOP切面：操作日志、权限校验

controller只做一件事：接收参数、校验格式、调用Service、封装返回。业务逻辑全部在service层，数据访问全部在mapper层。实体类（Entity）和前端展示对象（VO）严格分离，不要图省事直接拿Entity往前端返回。比如商品表里有detail大字段，列表页用不上，返回给前端浪费流量；更重要的是，如果实体类和前端展示混在一起，加一个字段就会牵一发动全身，体验很酸爽。

9.2 前端组件化封装思路

前端的组件化程度直接决定你会不会在一个页面里改到怀疑人生。我这次把两个最常用的功能封装成了公共组件：分页表格组件和文件上传组件。

分页表格组件封装了Element UI的el-table+el-pagination，通过props接收fetchData函数和查询参数，组件内部管理当前页码、每页条数、loading状态。业务页面要展示订单列表、商品列表、用户列表时，只需要传入对应的API函数，几十行代码搞定一个列表页。

<template> <div> <common-table :fetch-data="fetchProducts" :query-params="queryParams" /> </div> </template> <script> import CommonTable from '@/components/CommonTable.vue' export default { components: { CommonTable }, methods: { fetchProducts(params) { return api.getProductList(params) } } } </script>

这个组件的价值在于：列表页都是相似的套路——条件筛选、表格展示、分页控制、操作按钮。封装一次，后面所有列表页复用，改组件样式和逻辑一处生效，全局同步。

9.3 使用Navicat管理数据库的实践经验

数据库管理工具我用的是Navicat，但我要提两个使用中的关键点。第一，写SQL查询前先看清当前连接的数据库，别开着生产环境连接执行DELETE语句，手一抖可能就凉了。我习惯在测试环境数据库名字上加“_(test)”后缀，并且严格区分连接颜色标识，从源头上杜绝误操作。第二，Navicat的表设计器虽然好用，但修改表结构时注意——如果表里已经有数据，新增字段要给默认值或允许为空，否则会执行失败甚至锁表。

数据备份这个操作一定不能懒。我的策略是：每天凌晨自动用mysqldump全量备份一次，保留最近7天的备份文件。恢复时用source命令导入备份文件即可。别等到数据丢的时候再后悔没备份，这句话我说给所有做系统的朋友。

10. 项目扩展与维护规划

10.1 从“直售”到“审批流”的升级路径

当前版本的下单流程是“用户下单→管理员发货”，流程上省了审批环节。但实际企业采购场景里，审批是刚需。预算有限的时候，必须有人审批才能下单。我的扩展计划是在订单表上增加approval_status字段，状态从“提起申请→审批中→通过→已下单”流转，再加一张approval_record表记录审批链路上的每个人和意见。这个改动不影响现有表结构，只增加字段和业务流转逻辑，适合作为第二期迭代的核心功能。

10.2 私有化部署到内网服务器的注意事项

如果你的系统要部署到单位的内网服务器，有几个细节需要注意。第一，内网服务器一般不允许访问外网，Maven依赖和npm包在构建阶段需要提前准备好，或者搭建本地私服（如Nexus）。第二，内网域名或IP直接访问，SSL证书大概率是自签的，前端HTTPS调用后端时会报证书不被信任，此时可以在Axios实例里配置https代理忽略证书校验（仅限内网环境）。第三，服务器时间必须用NTP同步，否则JWT签发和校验的expiration时间对不上，用户会莫名其妙被登出。

10.3 系统上线后的数据监控建议

系统跑起来之后，建议维护几张监控SQL，定时查一下：订单量日趋势、商品库存低于安全值的商品列表、一周内零售商品清单、接口响应时间超过500ms的慢请求。这些数据不需要复杂的监控平台，写个定时任务往一张monitor_report表里插数据，做一个简单的监控看板页面即可。系统的价值不止在功能本身，更在于运营者能从数据里看懂业务趋势。

最后分享一个真实感受：做这种全栈项目，最大的阻碍往往不是技术本身，而是“什么都想做、什么都没做深”。我在这个项目里砍掉了很多华而不实的功能——比如在线客服、多商户入驻、短信通知——把一个直售系统该有的核心环节做扎实了。如果你也在做类似的项目，先想清楚哪些功能是核心闭环不可缺失的，哪些是锦上添花的，聚焦做完前者，你的项目就成功了一大半。