# intelligent-wms

**Repository Path**: jinks_pang/intelligence-wms

## Basic Information

- **Project Name**: intelligent-wms
- **Description**: 一套完整的企业级仓库管理系统（Warehouse Management System），基于前后端分离架构，提供商品基础数据管理、仓库/库区/储位管理、入库/出库/调拨操作、实时库存监控与盘点、商品全链路溯源、用户与权限管控等核心功能。

- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# intelligent WMS —— 智能化仓储管理系统

> 基于 Spring Boot 3.2.5 + MyBatis-Plus 3.5.6 + Vue 3.5.13 + TypeScript 5.8.3 的现代仓储管理系统。
> 支持仓库/库区/库位管理、SKU/商品/条形码管理、出入库/调拨/盘点、库存变动流水、FIFO 先进先出、
> SN 序列号溯源、数据看板、角色权限菜单、操作日志、系统监控、定时任务调度等完整业务功能。

---

## 一、项目总览

### 1.1 目录结构

```
intelligent-wms/
+-- backend/                                 # Spring Boot 多模块后端
|   +-- pom.xml                              # 父 POM（统一依赖版本）
|   +-- wms-admin/                           # Web 启动模块（启动类 + 配置 + 资源）
|   |   +-- src/main/java/com/intelligent/wms/
|   |   |   +-- WmsApplication.java         # 启动类
|   |   |   +-- config/                     # CorsConfig / SecurityConfig / WebMvcConfig / OpenApiDocConfig / JacksonConfig
|   |   +-- src/main/resources/
|   |       +-- application.yml              # 基础配置（JWT / 存储 / 环境变量）
|   |       +-- application-dev.yml          # 开发环境（打印 SQL 日志）
|   |       +-- application-prod.yml         # 生产环境（关闭调试日志）
|   |       +-- logback-spring.xml           # 日志配置
|   |       +-- mapper/*.xml                 # MyBatis-Plus XML 映射
|   +-- wms-biz/                             # 核心业务模块（Controller/Service/Mapper/DTO/VO/Entity/Security/Config）
|   +-- wms-common/src/main/java/com/intelligent/wms/common/  # 公共模块（子目录：api/ / exception/ / annotation/ / aspect/ / utils/ / enums/ / event/）
|   +-- wms-storage/                         # 文件存储模块（Local / FTP / S3 策略模式）
|   +-- wms-quartz/                          # 定时任务模块（Quartz 调度 + 任务日志）
+-- frontend/                                # Vue 3 + TS 5.8 + Vite 6 前端
|   +-- src/
|   |   +-- api/                             # 接口请求封装（request.ts + 业务模块 ts）
|   |   +-- views/                           # 业务页面（kebab-case 目录 + Index.vue）
|   |   +-- components/common/               # 通用组件（BarcodeDisplay / IconSelect / StatusBadge）
|   |   +-- directives/                      # 自定义指令（permission.ts 权限控制）
|   |   +-- stores/                          # Pinia 状态管理（持久化 token / refreshToken / userInfo）
|   |   +-- types/                           # TS 类型定义（index.ts / jsbarcode.d.ts）
|   |   +-- router/                          # 路由 + 导航守卫
|   |   +-- utils/                           # 通用工具
|   |   +-- assets/icons/svg/                # SVG 图标集
|   |   +-- layout/                          # 后台布局
|   +-- vite.config.ts / tsconfig.json / package.json
+-- docs/                                    # 项目文档
|   +-- sql/                                 # 数据库初始化脚本（init.sql / qrtz_schema.sql / t_sys_job.sql）
|   +-- superpowers/specs/wms-design.md      # 架构设计说明
|   +-- images/                              # 系统截图（登录 / 看板 / 基础数据 / 仓库 / 用户 / 系统）
+-- scripts/                                 # 辅助脚本
+-- logs/                                    # 运行日志（wms.log / wms-error.log / wms-operation.log）
+-- README.md                                # 本文件
+-- AGENTS.md                                # AI Agent 协作文档
+-- rules.md                                 # 编码规范（SpringBoot3 + Vue3 + TS 强制规范）
```

### 1.2 技术栈与版本

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 17 | LTS 长期支持 |
| Spring Boot | 3.2.5 | 多模块分层架构 |
| Spring Security | 6.x | JWT 双令牌认证（access + refresh） |
| MyBatis-Plus | 3.5.6 | CRUD / 分页 / 逻辑删除 |
| Quartz | 2.x | 定时任务调度（持久化到 MySQL） |
| MySQL | 8.0 | InnoDB，字符集 utf8mb4 |
| Redis | 7.x | 缓存 / refreshToken 存储 / 热点数据 |
| Knife4j | 4.4.0 | OpenAPI 3 接口文档 |
| JJWT | 0.12.5 | JWT 令牌生成与解析 |
| Apache POI | 5.2.5 | Excel 读写 |
| Vue | 3.5.13 | Composition API |
| TypeScript | 5.8.3 | Strict 严格模式 |
| Vite | 6.3.5 | 构建工具 |
| Element Plus | 2.14.2 | UI 组件库 |
| Pinia | 3.0.4 | 状态管理 + 持久化 |
| Vue Router | 4.6.4 | 路由 + 动态菜单 |
| Axios | 1.18.1 | HTTP 客户端 |
| JSBarcode | 3.12.3 | 条形码渲染 |
| Sass | 1.101.0 | 样式预处理 |
| Maven | 3.9+ | 后端构建 |

---

## 二、核心业务模块

### 2.1 基础数据（base-data）

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 商品分类 | 多级分类树 | base_category | CategoryController | base-data/category |
| 商品管理 | 商品基本信息 | base_product | ProductController | base-data/product |
| SKU 规格 | 规格 + 条形码展示 | base_sku | SkuController | base-data/sku |
| SN 序列号 | 批量生成 / Excel 导出 / FIFO 先进先出 | base_sn_code | SnCodeController | base-data/sn-code |

### 2.2 仓库管理（warehouse）

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 仓库 | 仓库档案（名称 / 地址 / 状态） | wms_warehouse | WarehouseController | warehouse/list |
| 库区 | 仓库分区管理 | wms_area | AreaController | warehouse/area |
| 库位 | 库区下货架库位（货架号 + 行号 + 列号） | wms_location | LocationController | warehouse/location |

### 2.3 库存（stock）

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 实时库存 | 按 SKU / 仓库 / 库区 / 库位 统计 | wms_stock | StockController | warehouse/stock |
| 库存变动流水 | 所有库存变动记录（出入库 / 调拨 / 盘点） | wms_stock_record | StockController | warehouse/stock-record |
| SN 库存明细 | 序列号级库存追踪 | wms_stock_sn | StockController | - |

### 2.4 出入库与盘点

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 入库单 | 采购入库 / 其他入库，支持扫码 SN 入库 | wms_inbound | InboundController | warehouse/inbound |
| 出库单 | 销售出库 / 其他出库，FIFO 先进先出扣减 | wms_outbound | OutboundController | warehouse/outbound |
| 调拨单 | 仓库间 / 库位间 库存调拨 | wms_transfer | TransferController | warehouse/transfer |
| 盘点单 | 库存盘点（盘盈 / 盘亏调整） | wms_inventory | InventoryController | warehouse/inventory |

### 2.5 溯源与看板

| 模块 | 说明 | 后端 Controller | 前端页面 |
|------|------|-----------------|---------|
| 溯源查询 | 扫码 / 输入 SN 或 SKU，查询全生命周期（条形码展示） | TraceController | trace |
| 数据看板 | 仓库总览 / TOP10 商品 / 库存预警 / 出入库趋势 | DashboardController | dashboard |

### 2.6 系统与权限（system/user）

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 用户管理 | 用户 CRUD / 重置密码 / 修改状态 | sys_user | UserController | user/list |
| 个人中心 | 修改密码 / 更新个人信息 | - | AuthController | user/profile |
| 角色管理 | 角色 CRUD / 分配菜单权限 | sys_role / sys_role_menu | RoleController | system/role |
| 菜单权限 | 菜单 / 权限标识 树形管理 | sys_menu | MenuController | system/menu |
| 操作日志 | 记录关键操作（增删改） | sys_operation_log | OperationLogController | system/log |
| 系统监控 | JVM / 内存 / 磁盘 / Redis / 启动时间 | MonitorController | system/monitor |
| 登录认证 | JWT 双令牌（access + refresh） | - | AuthController | login |

### 2.7 定时任务调度（quartz）

| 模块 | 说明 | 对应表 | 后端 Controller | 前端页面 |
|------|------|--------|-----------------|---------|
| 任务管理 | 定时任务 CRUD / 启动 / 暂停 / 立即执行 / 修改 cron | sys_job | ScheduleController（wms-quartz） | system/schedule |
| 任务日志 | 定时任务执行日志记录（成功 / 失败 / 耗时 / 异常信息） | sys_job_log | ScheduleController（wms-quartz） | system/schedule-log |

> 定时任务模块基于 Quartz 实现，任务信息和执行日志持久化到 MySQL（qrtz_* 系统表 + sys_job / sys_job_log 业务表）。
> 通过 Spring Profile 分组机制（dev / prod 同时激活 quartz profile），启动时 ScheduleStartupListener 自动加载启用中的任务。

---

## 三、快速开始

### 3.1 环境要求

| 环境 | 版本要求 |
|------|---------|
| JDK | >= 17 |
| Maven | >= 3.9 |
| MySQL | >= 8.0 |
| Redis | >= 7.0 |
| Node.js | >= 20 |
| pnpm | >= 8 |

### 3.2 数据库初始化

按顺序执行以下 SQL 脚本（位于 docs/sql/）：

```bash
# 1. 核心业务表 + 系统表（sys_user / sys_role / sys_menu / wms_* / base_* / sys_operation_log）
mysql -u root -p < docs/sql/init.sql

# 2. Quartz 定时任务系统表（qrtz_job_details / qrtz_triggers 等 11 张表）
mysql -u root -p < docs/sql/qrtz_schema.sql

# 3. 定时任务业务表（sys_job / sys_job_log）
mysql -u root -p < docs/sql/t_sys_job.sql
```

### 3.3 后端启动

```bash
cd backend

# 编译全部模块（wms-common / wms-storage / wms-quartz / wms-biz / wms-admin）
mvn clean package -DskipTests

# 运行启动类
java -jar wms-admin/target/wms-admin-1.0.0.jar

# 或直接使用 Maven 插件启动
mvn -pl wms-admin spring-boot:run
```

### 3.4 前端启动

```bash
cd frontend

# 安装依赖
pnpm install

# 开发模式（默认 5173 端口，代理 /api -> 8080）
pnpm dev

# 生产构建
pnpm build
```

### 3.5 默认账号

- **管理员**：用户名 `admin` / 密码 `123456`

> 首次登录后请尽快修改默认密码。

---

## 四、接口文档（OpenAPI / Knife4j）

启动后端后访问：

```
http://localhost:8080/doc.html     # Knife4j UI
http://localhost:8080/v3/api-docs   # OpenAPI 3 JSON
```

### 4.1 核心接口总览

| 模块 | 基础路径 | 说明 |
|------|---------|------|
| 认证 | `/api/v1/auth/*` | login / refresh-token / logout / change-password |
| 用户 | `/api/v1/user/*` | CRUD / 重置密码 / 启用禁用 |
| 菜单 | `/api/v1/menu/*` | 树形 CRUD / 按用户查询菜单树 |
| 角色 | `/api/v1/role/*` | CRUD / 分配菜单权限 |
| 分类 | `/api/v1/base/category/*` | 分类树 CRUD |
| 商品 | `/api/v1/base/product/*` | 商品 CRUD |
| SKU | `/api/v1/base/sku/*` | SKU CRUD / 条形码展示 |
| SN 码 | `/api/v1/base/sn-code/*` | 生成 / 导入 / 导出 / FIFO 先进先出 |
| 仓库 | `/api/v1/warehouse/*` | 仓库 / 库区 / 库位 |
| 库存 | `/api/v1/stock/*` | 库存查询 / 变动流水 / SN 明细 |
| 入库 | `/api/v1/inbound/*` | 入库单 CRUD / 确认入库 |
| 出库 | `/api/v1/outbound/*` | 出库单 CRUD / 确认出库（FIFO） |
| 调拨 | `/api/v1/transfer/*` | 调拨单 CRUD / 确认调拨 |
| 盘点 | `/api/v1/inventory/*` | 盘点单 CRUD / 确认盘点 |
| 溯源 | `/api/v1/trace/*` | SN / SKU 全链路查询 |
| 看板 | `/api/v1/dashboard/*` | 数据统计 / TOP10 / 预警 |
| 操作日志 | `/api/v1/operation-log/*` | 日志查询 / 导出 |
| 监控 | `/api/v1/monitor/*` | 系统状态 / JVM / Redis |
| 定时任务 | `/api/v1/schedule/*` | 任务 CRUD / 暂停 / 启动 / 立即执行 / 执行日志 |

### 4.2 统一响应格式

所有接口响应统一为：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {},
  "timestamp": 1789800000000
}
```

状态码：
- `200` 成功
- `400` 参数错误 / 业务校验失败
- `401` 未登录 / Token 过期
- `403` 无权限
- `404` 资源不存在
- `500` 服务器内部错误
- `>= 1000` 业务自定义错误码

---

## 五、认证与安全

### 5.1 JWT 双令牌机制

| Token | 有效期 | 用途 | 存储位置 |
|-------|--------|------|---------|
| Access Token | 1 小时 | 调用业务接口，放在 `Authorization: Bearer <token>` | 前端内存 + Pinia |
| Refresh Token | 7 天 | 仅用于刷新 Access Token | 前端 Pinia（持久化） + 后端 Redis |

刷新流程：前端请求接口 -> 返回 401 -> 前端 request.ts 拦截器 -> 调用 /api/v1/auth/refresh-token -> 获取新 token -> 自动重试原请求。

### 5.2 权限控制

- **后端**：基于 Spring Security 6 的 `SecurityConfig`，核心业务接口使用 `@PreAuthorize("hasAuthority('xxx')")` 注解（ScheduleController 当前未启用权限注解，如需开启请在对应方法添加）。
- **前端**：基于 `directives/permission.ts` 中的 `v-permission` 指令 + 路由 meta 权限标识过滤。
- **菜单权限**：基于角色-菜单关联表 sys_role_menu，登录后动态生成菜单树。

### 5.3 敏感信息保护

- 密码使用 BCrypt 加密存储（SecurityUtils 统一处理）
- 手机号 / 邮箱在 VO 响应中脱敏展示（DesensitizeUtils）
- 敏感配置项通过 `${ENV_VAR:default}` 注入，禁止硬编码
- JWT 密钥通过 `${JWT_SECRET:tech-wms-jwt-secret-key-2026-secure-hmac-sha256-min-32-bytes}` 注入

### 5.4 文件上传安全

- 单文件大小限制：`10MB`（`FILE_MAX_SIZE` 环境变量覆盖）
- 单次请求大小限制：`50MB`（`FILE_MAX_REQUEST` 环境变量覆盖）
- 文件路径归一化处理，防 `../` 路径遍历
- 存储策略：Local（./uploads）/ FTP / S3（wms-storage 模块统一抽象）

### 5.5 跨域配置

CORS 全局配置由 `wms-admin/config/CorsConfig.java` 统一处理，禁止在单个 Controller 添加 `@CrossOrigin` 注解。

---

## 六、配置说明（application.yml）

```yaml
server:
  port: ${SERVER_PORT:8080}

spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
    group:
      dev: quartz       # 激活 dev 时同时激活 quartz profile
      prod: quartz      # 激活 prod 时同时激活 quartz profile
  servlet:
    multipart:
      max-file-size: ${FILE_MAX_SIZE:10MB}
      max-request-size: ${FILE_MAX_REQUEST:50MB}

jwt:
  secret: ${JWT_SECRET:tech-wms-jwt-secret-key-2026-secure-hmac-sha256-min-32-bytes}
  expiration: 3600000           # Access Token：1 小时
  refresh-expiration: 604800000 # Refresh Token：7 天

wms:
  storage:
    type: ${STORAGE_TYPE:local}       # local / ftp / s3
    local:
      base-path: ${STORAGE_LOCAL_PATH:./uploads}
      url-prefix: ${STORAGE_LOCAL_URL_PREFIX:/api/v1/upload}
  trace:
    url-prefix: ${TRACE_URL_PREFIX:http://localhost:5173/trace}
```

> 环境变量覆盖优先级：`SPRING_PROFILES_ACTIVE` > `JWT_SECRET` > `DB_URL` > `DB_USERNAME` > `DB_PASSWORD` > `REDIS_HOST` > `FILE_MAX_SIZE` > ...

---

## 七、架构设计与分层说明

### 7.1 模块分层

```
wms-admin (启动模块)   <- 聚合依赖所有业务模块，提供 Web 入口
    |
    +-- wms-biz         <- 核心业务：Controller / Service / Mapper / Entity / DTO / VO / Security
    +-- wms-quartz      <- 定时任务：Quartz 调度 + 任务日志（独立模块）
    +-- wms-storage     <- 文件存储：策略模式（LocalStorageService / FtpStorageService / S3StorageService）
    +-- wms-common      <- 公共基础：Result / BizException / ResultCode / Utils / Enums / Constants / Event
              |
              +-- 被其他所有模块共享（Base 层）
```

### 7.2 业务分层规范

| 层 | 职责 | 禁止 |
|----|-----|------|
| Controller | 接收参数 / 调用 Service / 返回 Result | 禁止直接调用 Mapper、禁止写业务逻辑 |
| Service | 业务编排 / 事务控制（@Transactional） / 权限校验 | 禁止直接暴露 Entity 到前端 |
| Mapper | 数据库 CRUD | 禁止业务判断、禁止事务 |
| Entity | 数据库持久化对象 | 禁止直接返回给前端 |
| DTO | 请求入参，带 `@Validated` 校验 | - |
| VO | 响应出参，统一序列化为驼峰 | - |

### 7.3 wms-quartz 模块详细结构

```
wms-quartz/src/main/java/com/intelligent/wms/quartz/
+-- config/
|   +-- QuartzConfig.java              # Quartz 调度器配置（持久化到 MySQL）
|   +-- ScheduleStartupListener.java   # 启动时加载启用中的任务
+-- controller/
|   +-- ScheduleController.java        # @RequestMapping("/api/v1/schedule")
+-- service/
|   +-- ScheduleService.java / impl/ScheduleServiceImpl.java
|   +-- ScheduleJobLogService.java / impl/ScheduleJobLogServiceImpl.java
+-- manager/
|   +-- ScheduleManager.java           # 调度器管理封装（暂停 / 恢复 / 立即执行）
+-- entity/
|   +-- SysJobEntity.java              # 任务定义表（cron / status / handler / params）
|   +-- SysJobLogEntity.java           # 任务执行日志（耗时 / 状态 / 异常堆栈）
+-- mapper/
|   +-- SysJobMapper.java / SysJobLogMapper.java
+-- task/
|   +-- ScheduleJobRunner.java         # 统一任务入口（反射调用目标 Bean 方法）
|   +-- SampleTask.java                # 示例任务（可扩展为业务任务）
+-- utils/
|   +-- ScheduleInvokeUtils.java       # Spring Bean 反射调用工具
+-- constants/
    +-- ScheduleConstants.java         # 任务常量（NORMAL / PAUSE / SUCCESS / FAIL）
```

### 7.4 ScheduleController 接口清单

| HTTP | 路径 | 说明 |
|------|-----|------|
| GET | `/api/v1/schedule/page` | 分页查询任务列表 |
| GET | `/api/v1/schedule/{id}` | 任务详情 |
| POST | `/api/v1/schedule` | 新增任务 |
| PUT | `/api/v1/schedule` | 修改任务 |
| DELETE | `/api/v1/schedule/{id}` | 删除任务 |
| POST | `/api/v1/schedule/{id}/pause` | 暂停任务 |
| POST | `/api/v1/schedule/{id}/resume` | 恢复任务 |
| POST | `/api/v1/schedule/{id}/run` | 立即执行一次 |
| GET | `/api/v1/schedule/log/page` | 分页查询任务执行日志 |
| DELETE | `/api/v1/schedule/log` | 清空任务执行日志 |

> 注意：ScheduleController 当前未添加 `@PreAuthorize` 权限注解，如需精细化权限控制请在对应方法添加。

### 7.5 前端文件总览

**API（src/api/）**：
- `request.ts` — Axios 全局拦截器、401 自动刷新 token、响应 code 统一处理
- `base.ts` / `warehouse.ts` / `stock.ts` / `inbound.ts` / `outbound.ts` / `transfer.ts` / `inventory.ts` — 核心业务
- `user.ts` / `role.ts` / `menu.ts` — 用户权限体系
- `schedule.ts` — 定时任务管理
- `system.ts` — 操作日志 / 系统监控
- `trace.ts` — 溯源查询
- `dashboard.ts` — 数据看板

**页面（src/views/）**：
- `dashboard/Index.vue` — 首页看板
- `base-data/{category,product,sku,sn-code}/Index.vue` — 基础数据
- `warehouse/{list,area,location,stock,stock-record,inbound,outbound,transfer,inventory}/Index.vue` — 仓库管理
- `trace/Index.vue` — 溯源查询
- `user/{list,profile}/Index.vue` — 用户管理
- `system/{role,menu,log,monitor,schedule,schedule-log}/Index.vue` — 系统管理
- `login/Index.vue` — 登录页

**组件（src/components/common/）**：
- `BarcodeDisplay.vue` — JSBarcode 条形码渲染（带 SN 展示）
- `IconSelect.vue` — 图标选择器
- `StatusBadge.vue` — 状态徽标（正常/禁用/成功/失败）

**指令（src/directives/）**：
- `permission.ts` — `v-permission="'schedule:add'"` 细粒度按钮级权限控制

---

## 八、部署说明

### 8.1 开发环境

- 前端：Vite 默认 5173 端口，`/api` 代理转发到后端 8080
- 后端：默认 8080 端口，Knife4j 文档 `/doc.html`，开发模式打印 SQL 日志
- MySQL：3306
- Redis：6379

### 8.2 生产环境

```bash
# 后端构建
cd backend
mvn clean package -DskipTests -Pprod
java -jar wms-admin/target/wms-admin-1.0.0.jar &

# 前端构建
cd frontend
pnpm build   # 产物：dist/

# Nginx 配置示例
# server { listen 80; root /var/www/wms/dist;
#   location / { try_files $uri $uri/ /index.html; }
#   location /api { proxy_pass http://127.0.0.1:8080; }
# }
```

生产环境建议通过环境变量覆盖敏感配置：

```bash
export SPRING_PROFILES_ACTIVE=prod
export DB_URL="jdbc:mysql://prod-db:3306/wms?..."
export DB_USERNAME="prod_user"
export DB_PASSWORD="prod_password"
export REDIS_HOST="prod-redis"
export JWT_SECRET="your-32-byte-or-longer-secret"
```

---

## 九、日志说明

日志文件统一输出到 `./logs/`（logback-spring.xml 配置）：

| 文件 | 用途 | 级别 |
|------|------|------|
| `wms.log` | 主业务日志 | INFO |
| `wms-error.log` | 错误日志单独记录 | ERROR |
| `wms-operation.log` | 操作审计日志（增删改） | INFO |

操作日志通过 `@OperationLog` 注解 + AOP 自动记录，持久化到 `sys_operation_log` 表。

---

## 十、Git 提交规范（Conventional Commits）

提交信息格式：`<type>(<scope>): <subject>`

**type**：`feat` 新功能 / `fix` 修复 / `docs` 文档 / `refactor` 重构 / `style` 格式 / `chore` 构建/CI/依赖

**scope 示例**：`backend` / `frontend` / `user` / `warehouse` / `schedule` / `security` / `api-docs`

```bash
# 正确示例
feat(schedule): 新增 wms-quartz 定时任务模块，支持任务 CRUD / 暂停恢复 / 执行日志
fix(security): 修复 access token 过期后 refresh token 无限刷新问题
docs(readme): 更新 README 与 AGENTS 文档，同步 qrtz_schema.sql 文件名与模块结构
refactor(stock): 重构库存变动流水逻辑，FIFO 先进先出支持批量
```

---

## 十一、系统截图

| 页面 | 说明 |
|------|------|
| 登录页 | ![登录页](docs/images/1.login.png) |
| 数据看板 | ![数据看板](docs/images/2.dashboard.png) |
| 基础数据 | ![基础数据](docs/images/3.base-data.png) |
| 仓库管理 | ![仓库管理](docs/images/4.warehouse.png) |
| 用户管理 | ![用户管理](docs/images/5.user.png) |
| 系统管理 | ![系统管理](docs/images/6.system.png) |

---

## 十二、文档索引

| 文件 | 说明 |
|------|------|
| `README.md` | 本文件，项目总览 |
| `AGENTS.md` | AI Agent 协作规范（角色 / 流程 / 指令模板） |
| `rules.md` | Spring Boot 3 + Vue 3 + TS 强制编码规范（分层 / 命名 / 安全 / 性能 / 工程化） |
| `docs/superpowers/specs/wms-design.md` | 架构设计文档（业务 / 技术 / 数据模型 / 安全 / 部署） |

---

## 十三、常见问题

1. **登录报错 401 或 403**：检查 JWT_SECRET 是否与启动时一致；检查用户 status=1（启用）。
2. **定时任务不触发**：确认 `qrtz_schema.sql` 已执行；确认 `ScheduleStartupListener` 正常加载；日志中搜索 `schedule`。
3. **条形码无法展示**：确认 SKU.barcode 不为空；前端 JSBarcode 依赖已正确安装（`pnpm add jsbarcode`）。
4. **上传文件失败**：检查 `FILE_MAX_SIZE` / `FILE_MAX_REQUEST`；检查上传目录权限（`./uploads`）。
5. **数据库连接失败**：确认 MySQL 8.0；确认 `init.sql` 已执行；检查 `DB_URL / DB_USERNAME / DB_PASSWORD`。

---

## 十四、许可证

MIT License — 可自由修改与二次分发。