# intelligence-wms **Repository Path**: jinks_pang/intelligence-wms ## Basic Information - **Project Name**: intelligence-wms - **Description**: 一套完整的企业级仓库管理系统（Warehouse Management System），基于前后端分离架构，提供商品基础数据管理、仓库/库区/储位管理、入库/出库/调拨操作、实时库存监控与盘点、商品全链路溯源、用户与权限管控等核心功能。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-12 - **Last Updated**: 2026-07-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WMS 仓库管理系统 [![Java](https://img.shields.io/badge/Java-17-orange)](https://openjdk.java.net/) [![SpringBoot](https://img.shields.io/badge/SpringBoot-3.2.5-brightgreen)](https://spring.io/projects/spring-boot) [![Vue](https://img.shields.io/badge/Vue-3.5.13-teal)](https://vuejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](https://www.typescriptlang.org/) [![MySQL](https://img.shields.io/badge/MySQL-8.0-blue)](https://www.mysql.com/) [![Redis](https://img.shields.io/badge/Redis-latest-red)](https://redis.io/) 一套完整的企业级仓库管理系统（Warehouse Management System），基于前后端分离架构，提供商品基础数据管理、仓库/库区/储位管理、入库/出库/调拨操作、实时库存监控与盘点、商品全链路溯源、用户与权限管控等核心功能。 --- ## 目录 - [一、功能特性](#一功能特性) - [二、系统截图](#二系统截图) - [三、技术栈](#三技术栈) - [四、项目结构](#四项目结构) - [五、核心模块说明](#五核心模块说明) - [六、快速开始](#六快速开始) - [七、接口约定](#七接口约定) - [八、数据库设计](#八数据库设计) - [九、核心代码清单](#九核心代码清单) - [十、部署与构建](#十部署与构建) - [十一、开发规范](#十一开发规范) - [十二、AI Agent 协作](#十二ai-agent-协作) - [十三、许可协议](#十三许可协议) --- ## 一、功能特性 | 模块 | 功能 | |------|------| | 🏭 基础数据 | 商品分类管理、商品档案管理、SKU 规格管理、条码（SN）批量生成与打印、条码扫码入库 | | 📦 仓库管理 | 多仓库、多级库区、储位管理、树状层级展示 | | 📥 入库管理 | 入库单创建、审核、收货确认，数量核对，SKU 明细记录 | | 📤 出库管理 | 出库单创建、审核、发货确认，数量扣减，出库记录追踪 | | 🔄 调拨管理 | 仓库间、库区间商品调拨，调拨流程管理 | | 📊 库存管理 | 实时库存数量、SKU 库存分布、库区 TOP10、储位库存查询、库存变动流水 | | ✅ 盘点管理 | 盘点任务、账实差异对比、盘盈盘亏处理、历史记录 | | 📈 数据看板 | 库存分布柱状图、SKU 排行榜、告警列表、库区 TOP10、动态刷新 | | 🔍 溯源查询 | 通过 SN 码 / SKU 码查询商品全链路出入库历史，支持二维码生成（ZXing） | | 👤 用户权限 | 多用户登录、角色权限、菜单权限、操作日志、敏感数据脱敏；JWT Access Token（1 小时）+ Refresh Token（7 天）双令牌 | | 📁 文件服务 | 文件上传/下载、路径安全校验、支持 **本地 / FTP / S3** 三种存储策略 | | 📊 系统监控 | 服务健康检查、系统参数、JVM 状态 | | 📋 操作日志 | AOP 切面自动记录操作日志，异步线程池写入，不阻塞主流程 | | 🏷️ 条码打印 | JSBarcode 前端条码展示，支持 SN 码打印模板 | --- ## 二、系统截图 > 可在此处放置登录页、仪表盘、库存管理、溯源查询等页面的截图。 --- ## 三、技术栈 ### 3.1 后端（Spring Boot 3.2.5 + Java 17） | 技术 | 版本 | 说明 | |------|------|------| | Spring Boot | 3.2.5 | 应用框架 | | Spring Security | 6.x | 认证与权限控制 | | MyBatis-Plus | 3.5.6 | ORM 框架（Spring Boot 3 Starter） | | MySQL | 8.0 | 关系型数据库（InnoDB 引擎） | | Redis | 7.x | 缓存 / 存储 refreshToken / 限流 | | JWT (jjwt) | 0.12.5 | Token 签发与校验（双令牌：access + refresh） | | Knife4j | 4.4.0 | API 文档（OpenAPI 3 + Jakarta） | | Apache POI | 5.2.5 | Excel 导入导出（SN 码批量下载） | | ZXing | 3.5.2 | 二维码生成（溯源码） | | AWS SDK S3 | 2.25.0 | S3 存储策略 | | Apache Commons Net | 3.11.0 | FTP 存储策略 | | Maven | 3.9+ | 构建工具 | ### 3.2 前端（Vue 3.5.13 + TypeScript 5.8.3） | 技术 | 版本 | 说明 | |------|------|------| | Vue | 3.5.13 | 渐进式前端框架 | | TypeScript | 5.8.3 | 类型安全 | | Vite | 6.3.5 | 构建工具与开发服务器 | | Element Plus | 2.14.2 | UI 组件库 | | Pinia | 3.0.4 | 状态管理（持久化 token / userInfo） | | Axios | 1.18.1 | HTTP 请求（401 自动 refresh-token 并重放请求） | | Vue Router | 4.6.4 | 前端路由 | | JSBarcode | 3.12.3 | 条码渲染（SN 码展示） | | SCSS | 1.101.0 | 样式预处理 | --- ## 四、项目结构 ``` intelligence-wms/ ├── backend/ # Spring Boot 后端 │ ├── src/main/java/com/intelligence/wms/ │ │ ├── common/ │ │ │ ├── api/ # 统一响应 Result + ErrorCode │ │ │ ├── exception/ # BizException + 全局异常处理器 │ │ │ ├── annotation/ # @OperationLog（操作日志注解） │ │ │ ├── aspect/ # OperationLogAspect（AOP 切面） │ │ │ ├── event/ # OperationLogEvent + 监听器 │ │ │ ├── enums/ # BizTypeEnum / RoleTypeEnum / SnStatusEnum 等 │ │ │ └── utils/ # JwtUtils、SecurityUtils、IdUtils、DesensitizeUtils、SnCodeValidator │ │ ├── config/ # SecurityConfig、CorsConfig、WebMvcConfig、JacksonConfig │ │ │ # MyBatisPlusConfig、MyMetaObjectHandler、RedisConfig、StorageConfig │ │ │ # PasswordInitializer（默认密码初始化） │ │ ├── controller/ # 按业务分包 │ │ │ ├── base/ # Category/Product/Sku/SnCode │ │ │ ├── warehouse/ # Warehouse/Area/Location │ │ │ ├── stock/ # Stock（库存） │ │ │ ├── inbound/ # InboundController │ │ │ ├── outbound/ # OutboundController │ │ │ ├── transfer/ # TransferController │ │ │ ├── inventory/ # InventoryController │ │ │ ├── trace/ # TraceController（溯源查询，免登录） │ │ │ ├── dashboard/ # DashboardController │ │ │ ├── user/ # UserController + AuthController │ │ │ ├── role/ # RoleController │ │ │ ├── menu/ # MenuController │ │ │ ├── system/ # OperationLogController + MonitorController │ │ │ └── upload/ # UploadController │ │ ├── dto/ # 请求入参（按业务分包） │ │ ├── vo/ # 响应出参 │ │ ├── entity/ # 数据库 PO 实体（全部继承 BaseEntity） │ │ ├── mapper/ # MyBatis Mapper 接口 │ │ ├── service/ # Service 接口 + 实现（事务边界在此） │ │ │ ├── base/ # Category/Product/Sku/SnCode │ │ │ ├── warehouse/ # Warehouse/Area/Location │ │ │ ├── stock/ # Stock │ │ │ ├── inbound/ # Inbound │ │ │ ├── outbound/ # Outbound │ │ │ ├── transfer/ # Transfer │ │ │ ├── inventory/ # Inventory │ │ │ ├── trace/ # Trace │ │ │ ├── dashboard/ # Dashboard │ │ │ ├── user/ # User + Auth（双令牌认证） │ │ │ ├── role/ # Role │ │ │ ├── menu/ # Menu │ │ │ └── system/ # OperationLog + Monitor │ │ ├── security/ # JwtAuthenticationFilter + UserDetailsServiceImpl │ │ └── infra/ │ │ └── storage/ # 第三方服务集成（文件存储策略） │ │ ├── StorageStrategy.java # 策略接口 │ │ ├── StorageService.java # 门面服务 │ │ ├── StorageServiceImpl.java # 服务实现 │ │ ├── LocalStorageStrategy.java # 本地存储 │ │ ├── FtpStorageStrategy.java # FTP 存储 │ │ └── S3StorageStrategy.java # S3 兼容存储（AWS / MinIO 等） │ └── src/main/resources/ │ ├── application.yml # 主配置文件 │ ├── application-dev.yml # 开发环境配置 │ ├── application-prod.yml # 生产环境配置 │ ├── logback-spring.xml # 日志配置 │ └── mapper/*.xml # MyBatis XML 映射文件 ├── frontend/ # Vue 3 前端 │ ├── src/ │ │ ├── api/ # 业务接口（user/trace/stock/warehouse/base/dashboard/menu/role/system） │ │ │ └── request.ts # Axios 全局拦截器（401 自动 refresh-token） │ │ ├── assets/ # 静态资源、全局样式、SVG 图标集 │ │ ├── components/ # 通用组件 │ │ │ └── common/ # BarcodeDisplay / IconSelect / StatusBadge │ │ ├── directives/ # v-permission 权限指令 │ │ ├── layout/ # 布局组件 │ │ ├── views/ # 页面（kebab-case 文件夹 + Index.vue） │ │ │ ├── dashboard/ # 数据看板 │ │ │ ├── base-data/ # category / product / sku / sn-code │ │ │ ├── warehouse/ # list / area / location / stock / stock-record │ │ │ │ # inbound / outbound / transfer / inventory │ │ │ ├── trace/ # 溯源查询（扫码或手动输入 SN/SKU） │ │ │ ├── user/ # list / profile │ │ │ ├── system/ # menu / role / log / monitor │ │ │ └── login/ # 登录 │ │ ├── router/ # Vue Router 路由配置 │ │ ├── stores/ # Pinia 状态管理（user.ts 持久化 token/refreshToken） │ │ ├── types/ # TypeScript 类型定义（index.ts） │ │ ├── utils/ # 工具函数（权限校验等） │ │ ├── App.vue │ │ ├── main.ts │ │ └── style.css │ └── package.json ├── docs/ │ └── sql/init.sql # 数据库初始化脚本 └── README.md ``` --- ## 五、核心模块说明 ### 5.1 认证与安全（双令牌机制） **后端实现**： - `JwtUtils`：提供 `generateAccessToken()`、`generateRefreshToken()`、`parseAndValidateRefreshToken()`、`getTokenTypeFromToken()` 方法，通过 `claims.tokenType` 区分 Access Token 和 Refresh Token，防止 Refresh Token 被当作 Access Token 使用。 - `AuthService` / `AuthServiceImpl`：提供 `login()` 和 `refreshToken()` 方法，登录时签发双令牌，refreshToken 保存到 Redis（key = `auth:refreshToken:{userId}`，TTL = 7 天）。 - `AuthController`：`POST /api/v1/auth/login`（登录）、`POST /api/v1/auth/refresh-token`（刷新 accessToken）。 - `JwtAuthenticationFilter`：Spring Security 过滤器，校验请求中的 Bearer Token，仅接受 `tokenType == "access"` 的令牌。 - `LoginResponseVO`：包含 `token`（accessToken）、`refreshToken`、`userInfo` 三个字段。 - `PasswordInitializer`：启动时检查并初始化默认管理员账号（admin / 123456），BCrypt 加密存储。 - `PermissionChecker`：权限校验工具类，配合 `@PreAuthorize` 使用。 **Token 有效期**（配置在 `application.yml`）： - `jwt.expiration`：3600000（1 小时，Access Token） - `jwt.refresh-expiration`：604800000（7 天，Refresh Token） **前端实现**： - `api/user.ts`：`login()`、`refreshToken()` 接口调用。 - `stores/user.ts`：Pinia Store，持久化 `token` 和 `refreshToken` 到 localStorage，提供 `refresh()` 方法刷新令牌。 - `api/request.ts`：Axios 全局拦截器，401 时自动调用 refresh-token 接口并重放原请求，非 200 统一提示错误。 - `directives/permission.ts`：`v-permission` 自定义指令，控制按钮/操作的显示权限。 ### 5.2 溯源查询（免登录 + 二维码） **后端接口**（3 个独立接口，路径变量风格）： - `GET /api/v1/trace/sn/{snCode}`：按 SN 码查询溯源信息，返回商品信息 + 出入库历史记录。 - `GET /api/v1/trace/sku/{skuCode}`：按 SKU 码查询商品基础信息。 - `GET /api/v1/trace/qr/{code}`：生成溯源二维码（PNG Base64 字符串），使用 ZXing 库渲染。 **后端 Service**： - `TraceService`：`getTraceInfo()`、`getTraceBySkuCode()`、`generateQrCode()`。 - `TraceServiceImpl`：通过 SKU 关联查询商品信息，通过库存变动记录构建溯源历史，批量查询仓库/库区/储位/操作员名称避免 N+1。 **前端实现**： - `api/trace.ts`：提供统一 `getTrace(type, code)` 方法，以及别名 `getTraceBySn()`、`getTraceBySku()`、`generateQrCode()`。 - `views/trace/Index.vue`：溯源查询页面，二维码图片展示，SN 码条码（JSBarcode）渲染。 ### 5.3 操作日志（AOP + 异步事件） **核心设计**： - `@OperationLog` 注解：标注在 Controller 方法上，声明操作类型、业务类型、模块名。 - `OperationLogAspect`：AOP 切面拦截，记录请求参数、IP、用户、耗时，发布 `OperationLogEvent` 事件。 - `OperationLogEventListener`：异步监听事件（`@Async("operationLogExecutor")`），写入数据库不阻塞主流程。 - `operationLogExecutor`：`WmsApplication` 中配置的专用线程池（核心 2，最大 8，队列 256）。 ### 5.4 文件服务（策略模式：本地 / FTP / S3） **后端实现**： - `StorageStrategy` 接口：定义 `upload()`、`download()`、`delete()` 方法。 - `StorageService` + `StorageServiceImpl`：门面服务，根据 `wms.storage.type` 配置动态选择策略。 - `LocalStorageStrategy`：本地文件系统存储，路径归一化防止 `../` 遍历。 - `FtpStorageStrategy`：基于 Apache Commons Net 的 FTP 上传下载。 - `S3StorageStrategy`：基于 AWS SDK v2 的 S3 兼容存储（支持 AWS S3 / MinIO / Aliyun OSS 等）。 - `StorageConfig`：根据类型注册对应的 Strategy Bean。 - `UploadController`：文件上传/下载接口，限制文件大小 10MB，请求大小 50MB。 **配置项**（`application.yml`）： ```yaml wms: storage: type: local # local / ftp / s3 local: base-path: ./uploads url-prefix: /api/upload ftp: host: localhost port: 21 username: ftpuser password: ftppassword s3: bucket: wms-bucket region: us-east-1 ``` ### 5.5 SN 码管理（批量生成 + Excel 下载 + FIFO 出库） **后端实现**： - `SnCodeService.generateSnCodes()`：按 SKU + 数量批量生成唯一 SN 码（`IdUtils` 雪花算法 + 自定义校验位）。 - `SnCodeService.downloadSnCodes()`：通过 Apache POI 生成 Excel 文件，批量下载 SN 码。 - `SnCodeService.getFifoSnCodes()`：按入库时间 FIFO 排序，推荐出库 SN 码列表。 - `SnCodeService.batchInbound()`：批量扫码入库，更新 SN 码状态与库存。 - `SnCodeValidator`：SN 码格式校验工具类。 **前端实现**： - `components/common/BarcodeDisplay.vue`：基于 JSBarcode 的条码渲染组件。 - `views/base-data/sn-code/Index.vue`：SN 码管理页面，支持批量生成、扫码入库、Excel 下载、条码预览。 ### 5.6 基础数据与仓库业务 - **仓库/库区/储位**：多层级树状结构，按仓库分组管理。 - **库存/出入库/调拨/盘点**：完整的库存操作流程，支持 SN 码粒度的一物一码追踪，库存变动流水记录。 --- ## 六、快速开始 ### 6.1 后端启动 ```bash # 1. 初始化数据库（MySQL 8.0） # 导入 docs/sql/init.sql # 2. 修改 application-dev.yml 配置 # - 数据库连接地址、账号、密码 # - Redis 连接 # - JWT secret（生产环境通过环境变量注入） # - 存储策略（local / ftp / s3） # 3. 启动后端服务 cd backend mvn spring-boot:run -Pdev # 服务地址: http://localhost:8080 # API 文档: http://localhost:8080/doc.html # 默认账号: admin / 123456（首次启动自动初始化） ``` ### 6.2 前端启动 ```bash cd frontend # 1. 安装依赖 pnpm install # 2. 开发模式（Vite 代理 /api -> 8080） pnpm dev # 访问: http://localhost:5173 # 默认账号: admin / 123456 ``` ### 6.3 环境变量 | 变量 | 说明 | 默认值 | |------|------|--------| | `jwt.secret` | JWT 签名密钥（建议至少 32 字节） | *必须配置* | | `jwt.expiration` | Access Token 有效期（毫秒） | 3600000 | | `jwt.refresh-expiration` | Refresh Token 有效期（毫秒） | 604800000 | | `FILE_MAX_SIZE` | 单文件上传上限 | 10MB | | `FILE_MAX_REQUEST` | 请求体上限 | 50MB | --- ## 七、接口约定 ### 7.1 统一响应体 ```json { "code": 200, "msg": "操作成功", "data": {}, "timestamp": 1789800000000 } ``` - **200**：成功 - **400**：参数错误 - **401**：未登录 / Token 过期 - **403**：无权限 - **404**：资源不存在 - **500**：服务器内部错误 - **≥1000**：业务自定义错误码 ### 7.2 认证接口 | 方法 | 路径 | 说明 | 鉴权 | |------|------|------|------| | POST | `/api/v1/auth/login` | 用户名密码登录，返回 `{ token, refreshToken, userInfo }` | ❌ | | POST | `/api/v1/auth/refresh-token` | 使用 refreshToken 换取新的 accessToken | ❌ | **注意**： - 后续接口需携带 Header: `Authorization: Bearer ` - Token 过期（401）时，前端 `request.ts` 自动调用 refresh-token 接口并重放请求 - Refresh Token 存储在 Redis，支持吊销（用户禁用、修改密码时删除） ### 7.3 溯源查询接口（免登录） | 方法 | 路径 | 说明 | 鉴权 | |------|------|------|------| | GET | `/api/v1/trace/sn/{snCode}` | 按 SN 码查询溯源信息（含出入库历史） | ❌ | | GET | `/api/v1/trace/sku/{skuCode}` | 按 SKU 码查询商品信息 | ❌ | | GET | `/api/v1/trace/qr/{code}` | 生成溯源二维码（返回 Base64 PNG 字符串） | ❌ | ### 7.4 用户管理接口 | 方法 | 路径 | 说明 | 鉴权 | |------|------|------|------| | GET | `/api/v1/user/page?pageNum=1&pageSize=10` | 分页查询用户列表 | ✅ 需写权限 | | GET | `/api/v1/user/{id}` | 根据 ID 查询用户详情 | ✅ 需写权限 | | POST | `/api/v1/user` | 创建用户 | ✅ 需写权限 | | PUT | `/api/v1/user/{id}` | 更新用户信息 | ✅ 需写权限 | | DELETE | `/api/v1/user/{id}` | 删除用户 | ✅ 需写权限 | | PUT | `/api/v1/user/{id}/reset-password` | 重置用户密码 | ✅ 需写权限 | | PUT | `/api/v1/user/password` | 当前用户修改密码 | ✅ | | PUT | `/api/v1/user/profile` | 更新当前用户信息 | ✅ | ### 7.5 SN 码管理接口 | 方法 | 路径 | 说明 | 鉴权 | |------|------|------|------| | POST | `/api/v1/base/sn/generate` | 批量生成 SN 码 | ✅ 需写权限 | | GET | `/api/v1/base/sn/page` | 分页查询 SN 码列表 | ✅ | | GET | `/api/v1/base/sn/list/{skuCode}` | 按 SKU 查询其所有 SN 码 | ✅ | | GET | `/api/v1/base/sn/{snCode}` | 查询单个 SN 码详情 | ✅ | | POST | `/api/v1/base/sn/batch-inbound` | 批量扫码入库 | ✅ 需写权限 | | POST | `/api/v1/base/sn/download` | 批量下载 SN 码 Excel（请求体: `{ snCodes: [...] }`） | ✅ | | POST | `/api/v1/base/sn/print` | 批量打印 SN 码 | ✅ | | GET | `/api/v1/base/sn/history/{snCode}` | 查询单个 SN 码出入库历史 | ✅ | | GET | `/api/v1/base/sn/fifo?skuCode=&warehouseCode=&limit=10` | 获取 FIFO 出库推荐 SN 码 | ✅ | ### 7.6 文件上传接口 | 方法 | 路径 | 说明 | 鉴权 | |------|------|------|------| | POST | `/api/upload` | 上传文件（multipart/form-data，字段名 file） | ✅ | | GET | `/api/upload/{filename}` | 下载文件（通过 StorageStrategy 读取） | ❌（部分策略需鉴权） | ### 7.7 分页参数约定 所有列表接口统一使用： - `pageNum`：页码，默认 1 - `pageSize`：每页条数，默认 10 --- ## 八、数据库设计 ### 8.1 核心表 | 表名 | 说明 | 关键字段 | |-----------------------|------|---------| | `sys_user` | 用户表 | id, username, password(BCrypt), real_name, phone, email, role_type, warehouse_code, status | | `sys_role` | 角色表 | id, role_code, role_name, status, remark | | `sys_menu` | 菜单/权限表 | id, parent_id, menu_name, path, component, permission, sort, icon, type | | `sys_role_menu` | 角色-菜单关联 | id, role_id, menu_id | | `sys_operation_log` | 操作日志 | id, user_id, username, module, operation, biz_type, request_path, ip, method, params, result, cost_time, create_time | | `base_category` | 商品分类 | id, category_code, category_name, parent_id, sort, barcode_rule | | `base_product` | 商品主档 | id, product_code, product_name, category_code, description, image_url | | `base_sku` | SKU 规格 | id, sku_code, sku_name, product_code, unit_price, sku_image, specs | | `base_sn_code` | SN 条码 | id, sn_code(UNIQUE), sku_code, category_code, generate_time, status, inbound_time, outbound_time | | `wms_warehouse` | 仓库 | id, warehouse_code(UNIQUE), warehouse_name, address, manager, phone, status | | `wms_area` | 库区 | id, warehouse_code, area_code, area_name, sort, status | | `wms_location` | 储位 | id, warehouse_code, area_code, location_code, location_name, sort, status | | `wms_stock` | 库存汇总 | id, warehouse_code, area_code, location_code, sku_code, quantity | | `wms_stock_sn` | 库存-SN 明细 | id, stock_id, sn_code | | `wms_stock_record` | 库存变动流水 | id, biz_type, biz_no, warehouse_code, area_code, location_code, sku_code, sn_code, quantity, operator_id, operator_name, remark, create_time | | `wms_inbound` | 入库单 | id, inbound_no(UNIQUE), warehouse_code, status, sku_code, quantity, operator_id, remark | | `wms_outbound` | 出库单 | id, outbound_no(UNIQUE), warehouse_code, status, sku_code, quantity, operator_id, remark | | `wms_transfer` | 调拨单 | id, transfer_no(UNIQUE), from_warehouse_code, to_warehouse_code, status, sku_code, quantity, operator_id | | `wms_inventory` | 盘点单 | id, inventory_no(UNIQUE), warehouse_code, status, operator_id, remark | **说明**： - 所有表均包含 `id`、`create_time`、`update_time` 字段 - 业务编码字段（`warehouse_code`、`sku_code`、`sn_code` 等）加 UNIQUE 约束 - 常用查询条件加复合索引，避免全表扫描 - 全部实体继承 `BaseEntity` - 建表 SQL 见 `docs/sql/init.sql` --- ## 九、核心代码清单 ### 9.1 后端 Controller（按业务分包） - `controller/dashboard/DashboardController` — 数据看板 - `controller/base/CategoryController` — 商品分类 - `controller/base/ProductController` — 商品主档 - `controller/base/SkuController` — SKU 规格 - `controller/base/SnCodeController` — SN 条码（生成、查询、Excel 下载、FIFO 推荐、批量入库） - `controller/warehouse/WarehouseController` — 仓库 - `controller/warehouse/AreaController` — 库区 - `controller/warehouse/LocationController` — 储位 - `controller/stock/StockController` — 实时库存 - `controller/inbound/InboundController` — 入库单 - `controller/outbound/OutboundController` — 出库单 - `controller/transfer/TransferController` — 调拨单 - `controller/inventory/InventoryController` — 盘点 - `controller/trace/TraceController` — 溯源查询（免登录，ZXing 生成二维码） - `controller/upload/UploadController` — 文件上传/下载（策略模式 Local/FTP/S3） - `controller/user/UserController` — 用户管理 - `controller/user/AuthController` — 认证（登录 / refresh-token，双令牌） - `controller/role/RoleController` — 角色 / 角色菜单分配 - `controller/menu/MenuController` — 菜单权限 - `controller/system/OperationLogController` — 操作日志 - `controller/system/MonitorController` — 系统监控 ### 9.2 后端 Service（按业务分包） | Service 接口 | 实现 | 说明 | |--------------|------|------| | `user/AuthService` | `AuthServiceImpl` | 登录 / 刷新 Token（双令牌 + Redis 校验） | | `user/UserService` | `UserServiceImpl` | 用户管理与脱敏 | | `base/CategoryService` | `CategoryServiceImpl` | 分类 CRUD | | `base/ProductService` | `ProductServiceImpl` | 商品管理 | | `base/SkuService` | `SkuServiceImpl` | SKU 管理 | | `base/SnCodeService` | `SnCodeServiceImpl` | SN 生成 / Excel 下载（POI） / FIFO 推荐 | | `warehouse/WarehouseService` | `WarehouseServiceImpl` | 仓库管理 | | `warehouse/AreaService` | `AreaServiceImpl` | 库区管理 | | `warehouse/LocationService` | `LocationServiceImpl` | 储位管理 | | `stock/StockService` | `StockServiceImpl` | 库存查询与变动（含 SN 明细） | | `inbound/InboundService` | `InboundServiceImpl` | 入库确认与库存增加 | | `outbound/OutboundService` | `OutboundServiceImpl` | 出库确认与库存扣减 | | `transfer/TransferService` | `TransferServiceImpl` | 调拨流程处理 | | `inventory/InventoryService` | `InventoryServiceImpl` | 盘点差异处理 | | `trace/TraceService` | `TraceServiceImpl` | `getTraceInfo` / `getTraceBySkuCode` / `generateQrCode`（ZXing） | | `dashboard/DashboardService` | `DashboardServiceImpl` | 数据聚合、库区 TOP10 计算 | | `menu/MenuService` | `MenuServiceImpl` | 菜单权限 | | `role/RoleService` | `RoleServiceImpl` | 角色管理 / 角色菜单分配 | | `system/OperationLogService` | `OperationLogServiceImpl` | 操作日志（AOP + 异步事件） | | `system/MonitorService` | `MonitorServiceImpl` | 系统监控 / JVM | ### 9.3 核心 Entity **系统（sys_*）**：`SysUserEntity`、`SysRoleEntity`、`SysRoleMenuEntity`、`SysMenuEntity`、`SysOperationLogEntity` **基础数据（base_*）**：`BaseCategoryEntity`、`BaseProductEntity`、`BaseSkuEntity`、`BaseSnCodeEntity` **仓库业务（wms_*）**：`WmsWarehouseEntity`、`WmsAreaEntity`、`WmsLocationEntity`、`WmsStockEntity`、`WmsStockSnEntity`、`WmsStockRecordEntity`、`WmsInboundEntity`、`WmsOutboundEntity`、`WmsTransferEntity`、`WmsInventoryEntity` > 全部实体继承 `BaseEntity`（含 `id / createTime / updateTime`），通过 `MyMetaObjectHandler` 自动填充时间字段。 ### 9.4 配置与安全类 - `common/api/Result` + `ErrorCode` — 统一响应与错误码 - `common/exception/BizException` + `GlobalExceptionHandler` — 业务异常与全局捕获 - `common/utils/JwtUtils` — 双令牌生成/解析/校验；`generateAccessToken` / `generateRefreshToken` / `parseAndValidateRefreshToken` / `getTokenTypeFromToken` - `common/utils/IdUtils` — 雪花算法 ID 生成器 - `common/utils/SnCodeValidator` — SN 码格式校验 - `common/annotation/OperationLog` + `aspect/OperationLogAspect` — 操作日志注解与 AOP 切面 - `common/event/OperationLogEvent` + `OperationLogEventListener` — 异步事件监听，线程池写入日志 - `common/enums/BizTypeEnum` + `RoleTypeEnum` + `SnStatusEnum` + `MenuTypeEnum` — 业务枚举 - `config/SecurityConfig` + `security/JwtAuthenticationFilter` — 认证 + 权限拦截（JWT 过滤器校验 `tokenType == "access"`） - `config/CorsConfig` — 跨域配置 - `config/WebMvcConfig` — 静态资源与上传路径映射 - `config/JacksonConfig` — 日期格式 `yyyy-MM-dd HH:mm:ss` - `config/MyBatisPlusConfig` — 分页插件 - `config/MyMetaObjectHandler` — 自动填充 createTime / updateTime - `config/PasswordInitializer` — 启动时初始化默认管理员账号（BCrypt） - `config/RedisConfig` — Redis 序列化配置 - `config/StorageConfig` — 文件存储策略动态配置 - `infra/storage/*` — 文件存储策略（Local / FTP / S3） - `common/utils/SecurityUtils` — 安全工具（敏感字段脱敏、密码加密、获取当前登录用户） ### 9.5 前端页面 ``` views/ ├── dashboard/Index.vue # 数据看板（柱状图 / TOP10 / 告警） ├── base-data/ │ ├── category/Index.vue # 商品分类管理 │ ├── product/Index.vue # 商品管理 │ ├── sku/Index.vue # SKU 规格管理 │ └── sn-code/Index.vue # 条码 SN 批量生成、Excel 下载、条码展示 ├── warehouse/ │ ├── list/Index.vue # 仓库列表 │ ├── area/Index.vue # 库区管理 │ ├── location/Index.vue # 储位管理 │ ├── stock/Index.vue # 实时库存 │ ├── stock-record/Index.vue # 库存变动流水 │ ├── inbound/Index.vue # 入库单 │ ├── outbound/Index.vue # 出库单 │ ├── transfer/Index.vue # 调拨单 │ └── inventory/Index.vue # 盘点 ├── trace/Index.vue # 溯源查询（扫码或手动输入 SN/SKU，二维码展示） ├── user/ │ ├── list/Index.vue # 用户列表 │ └── profile/Index.vue # 个人中心 ├── system/ │ ├── menu/Index.vue # 菜单权限 │ ├── role/Index.vue # 角色 / 角色菜单分配 │ ├── log/Index.vue # 操作日志 │ └── monitor/Index.vue # 系统监控 └── login/Index.vue # 登录 ``` ### 9.6 前端 API 文件 ``` api/ ├── request.ts # Axios 全局拦截器；401 自动 refresh-token 并重放请求 ├── user.ts # 登录 / 登出 / refreshToken / 用户 CRUD / 修改密码 ├── trace.ts # getTrace(type, code) / getTraceBySn / getTraceBySku / generateQrCode ├── stock.ts # 库存 / 出入库 / 调拨 / 盘点 ├── warehouse.ts # 仓库 / 库区 / 储位 ├── base.ts # 分类 / 商品 / SKU / SN ├── dashboard.ts # 看板数据 ├── menu.ts / role.ts # 菜单 / 角色 └── system.ts # 日志 / 监控 ``` ### 9.7 前端组件与工具 ``` components/common/ ├── BarcodeDisplay.vue # JSBarcode 条码渲染组件 ├── IconSelect.vue # SVG 图标选择器 └── StatusBadge.vue # 状态徽章组件 directives/ └── permission.ts # v-permission 权限指令 stores/ └── user.ts # Pinia：持久化 token / refreshToken / userInfo types/ ├── index.ts # 全局 TS 类型定义（与后端 VO 驼峰对齐） └── jsbarcode.d.ts # JSBarcode 类型声明 assets/icons/svg/ # 完整 SVG 图标集（40+ 图标） ``` --- ## 十、部署与构建 ### 10.1 后端 Jar 打包 ```bash cd backend mvn clean package -DskipTests -Pprod # 运行 java -jar -Dspring.profiles.active=prod target/intelligence-wms-1.0.0.jar ``` ### 10.2 前端部署 ```bash cd frontend pnpm build # 产物 -> dist/ # 方案 A：Nginx 托管 # location / { root /opt/wms/dist; try_files $uri $uri/ /index.html; } # location /api { proxy_pass http://127.0.0.1:8080; } # 方案 B：Jar 整合（dist 放入 SpringBoot static 目录） ``` ### 10.3 生产安全 - 关闭 `SQL` 日志与 `debug` 级别（生产环境 `mybatis-plus.configuration.log-impl` 改为 `org.apache.ibatis.logging.nologging.NoLoggingImpl`） - 全站 HTTPS，Cookie 启用 `Secure` - 上传接口开启文件大小限制（默认 `10MB`，请求 `50MB`） - JWT `secret`、`expiration`、`refresh-expiration` 通过环境变量注入，不硬编码 - Redis 中保存 refreshToken，可随时吊销（用户禁用/修改密码） - 文件存储策略（Local/FTP/S3）通过 `wms.storage.type` 配置切换，代码零改动 - 操作日志异步写入，线程池隔离，不影响主流程性能 --- ## 十一、开发规范 ### 11.1 分层原则（强制） | 层 | 职责 | 跨层限制 | |----|------|---------| | `controller` | 仅接收参数、调用 Service、返回 `Result` | 禁止直接调用 Mapper / 写业务逻辑 | | `service` | 业务编排、事务边界（写操作 `@Transactional(rollbackFor = Exception.class)`） | 禁止暴露 HTTP 对象 | | `mapper` | CRUD，无业务判断 | 禁止调用 Service | | `entity` | 与表一一对应，不直接返回前端 | 通过 VO 转换 | ### 11.2 对象命名约定 | 对象 | 命名示例 | |------|---------| | 表 | `wms_stock`、`sys_user`、`sys_role`、`sys_role_menu`（省略 `t_` 前缀，直接用 `wms_` / `sys_` / `base_`） | | 实体 | `WmsStockEntity`、`BaseProductEntity`、`SysUserEntity`、`SysRoleEntity` | | Controller | `StockController`、`DashboardController`、`RoleController`、`AuthController`、`TraceController` | | Service | `StockService` / `StockServiceImpl`（接口与实现分在同包下） | | DTO | `SnDownloadDTO`、`SnGenerateDTO`、`SnBatchInboundDTO`、`ProductQueryDTO`、`RoleMenuAssignDTO`、`RefreshTokenRequestDTO`、`UserChangePasswordDTO` | | VO | `StockInfoVO`、`DashboardVO`、`AlertInfoVO`、`RoleInfoVO`、`LoginResponseVO`（带 `refreshToken`）、`TraceVO` | | 接口路径 | `/api/v1/stock`、`/api/v1/base/sn`、`/api/v1/role`、`/api/v1/auth/login`、`/api/v1/trace/sn/{code}`（小写 + 横杠 + 单数） | ### 11.3 前端规范 | 约定 | 说明 | |------|------| | 组合式 API | 仅使用 `