# ax_wms

**Repository Path**: evilwang/ax_wms

## Basic Information

- **Project Name**: ax_wms
- **Description**: 开源wms-saas系统
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AX WMS

WMS（仓储管理系统）后台与前端项目，面向 B2B 供应链场景，包含货品管理、入库、出库、库存、仓库与报表等模块。

---
## 项目展示
![仓库](./PrototypeDocs/imgs/1_0_仪表盘.png)
![仓库](./PrototypeDocs/imgs/1_1.png)
![出库订单](./PrototypeDocs/imgs/2_3_1.png)
![智能波次](./PrototypeDocs/imgs/2_3_2.png)
![二次分拣墙](./PrototypeDocs/imgs/2_4_2.png)
![包装复核](./PrototypeDocs/imgs/2_3_4.png)

## 项目结构

```
ax_wms/
├── wms-admin-frontend/     # 前端：Vue 3 + Vite + Element Plus
├── wms-admin-backend/     # 后端：Spring Boot 3 + MyBatis-Plus（多模块）
├── PrototypeDocs/         # 原型与需求文档（HTML / Markdown）
└── README.md
```

### 前端 (wms-admin-frontend)

| 目录/文件 | 说明 |
|-----------|------|
| `src/views/` | 页面：仪表盘、货品管理、入库/出库、二次分拣、库存、盘点管理、任务调度、仓库、报表、用户管理、系统设置等 |
| `src/api/` | 接口封装（request、goods、category、barcode、inbound、inventory、stocktaking、tasks、reports、users、settings 等） |
| `src/router/` | 路由配置 |
| `src/layout/` | 布局与侧栏 |
| `src/utils/` | 工具（如导出下载） |
| `wms-admin-frontend/docs/` | 前端 API 文档（如 InventoryAPI.md） |

技术栈：Vue 3、Vue Router、Element Plus、Vite 6、Sass、Chart.js（报表分析页图表）。

### 后端 (wms-admin-backend)

多模块 Maven 项目：

| 模块 | 说明 |
|------|------|
| `ax-common` | 通用：Result、DTO、异常、Excel 导出工具等 |
| `ax-mapper` | 数据层：Entity、Mapper 接口与 XML |
| `ax-core` | 业务层：Service、Manager、DTO、Convert |
| `ax-gateway` | 接口层：Controller（REST API） |
| `ax-app` | 启动模块：Spring Boot 主类与配置文件 |

接口路径规范：后台管理 `/api/admin/`；仪表盘 `/api/admin/dashboard/`（概览统计、7日订单趋势、库存分布、最新订单、任务汇总、库存预警）；货品 `/api/admin/products/goods/`；出库二次分拣 `/api/admin/outbound/secondary-sort/`（任务列表按 repick_status 筛选、进入分拣前 POST /task/generate 生成数据、分拣墙格口按 t_task_source 序号、扫描、完成分拣；定时 Job 每 5 分钟兜底生成未生成的二次分拣任务）；出库管理 `/api/admin/outbound/order/`、`/api/admin/outbound/wave/`、`/api/admin/outbound/picking/`、`/api/admin/outbound/review/`、`/api/admin/outbound/shipping/`（订单、波次、拣货、复核、发货交接）。

---

## 环境要求

- **前端**：Node.js 18+、npm
- **后端**：JDK 17+、Maven 3.6+
- **数据库**：MySQL 8（后端默认连接 `127.0.0.1:3306/axwms`）

---

## 启动方式

### 1. 后端

```bash
cd wms-admin-backend
mvn clean install -DskipTests
cd ax-app
mvn spring-boot:run
```

- 默认端口：**8080**
- 需先创建数据库 `axwms` 并执行建表/初始化脚本（若有）。
- 数据源配置：`ax-app/src/main/resources/application.properties`（可改 URL、用户名、密码）。

### 2. 前端

```bash
cd wms-admin-frontend
npm install
npm run dev
```

- 开发服务器：**http://localhost:3000**
- 开发环境下 `/api` 会代理到 `http://127.0.0.1:8080`，无需单独配置跨域。

### 3. 访问

浏览器打开 **http://localhost:3000**，即可使用后台。请先启动后端，否则接口请求会失败。

---

## 常用命令

| 说明 | 命令 |
|------|------|
| 前端开发 | `cd wms-admin-frontend && npm run dev` |
| 前端构建 | `cd wms-admin-frontend && npm run build` |
| 后端启动 | `cd wms-admin-backend/ax-app && mvn spring-boot:run` |
| 后端打包 | `cd wms-admin-backend && mvn clean package -DskipTests` |

---

## 文档与规范

- 需求与原型：`PrototypeDocs/docs/`、`PrototypeDocs/*.html`
- 货品管理等接口说明：`wms-admin-frontend/apiDoc/货品管理接口文档.md`
- 盘点管理接口说明：`PrototypeDocs/apiDoc/盘点管理_接口文档.md`
- 报表分析接口说明：`PrototypeDocs/apiDoc/报表分析_接口文档.md`
- 用户管理接口说明：`PrototypeDocs/apiDoc/用户管理_接口文档.md`
- 系统设置接口说明：`PrototypeDocs/apiDoc/系统设置_接口文档.md`
- 仪表盘接口说明：`PrototypeDocs/apiDoc/仪表盘_接口文档.md`
- 库存管理接口说明：`PrototypeDocs/apiDoc/库存管理_接口文档 .md`
- 出库管理接口说明：`PrototypeDocs/apiDoc/出库管理_接口文档.md`
- 任务调度接口说明：`PrototypeDocs/apiDoc/任务调度_接口文档.md`
- 后端开发规范：见项目内 `.cursor/rules/rules-backend/` 等规则文件。

---

## 更新说明

- **v0.0.16**（2026-02）：复核打包功能完善与联调。后端：query 仅返回待复核订单、items 仅含待扫明细，并返回 totalRequiredQty/totalScannedQty；scan 条码不属于当前订单时抛「该条码不属于当前订单」、返回仅待扫 items 及 totals；weightCheck 订单不存在抛错、无预估重量时按默认值并文案说明；ReviewQueryVO/ReviewScanResultVO 新增 totalRequiredQty、totalScannedQty；复核 DTO 支持前端 snake_case（order_id、weight_kg）入参。前端：复核明细与进度使用接口返回的 total 展示「已复核 X/共 Y 件」、称重结果字段与后端驼峰一致（actualKg、estimatedKg、diffPct、passed、message）。func.md 已同步 OutboundReviewService 与复核接口说明。

- **v0.0.15**（2026-02）：波次下发与状态完善。下发（release）后波次保持执行中，不再在此处置为已完成；新增 tryCompleteWaveByWaveCode（当波次内订单全部已发货时置波次为已完成）、syncExecutingWavesToCompleted（看板查询前同步）；看板执行中/已完成按订单状态汇总 phaseDetail、progress、actual、diff；WaveKanbanItemVO 增加 phaseDetail；stats 中 executingOrderCount 改为按执行中波次下订单数统计；DeliveryOrderMapper/Manager 新增 selectByWaveCodeIn/listByWaveCodeIn 批量按波次号查订单。

- **v0.0.14**（2026-02）：波次下发写入 t_task_source。OutboundWaveService.release 在生成 TTaskHeader、TTaskDetail 后，按波次内出库单批量写入 t_task_source（task_id、task_code、order_code=出库单号、order_type=OUTBOUND），供二次分拣与任务跟踪使用。200 单波次种子数据脚本头部补充执行顺序说明（① 出库管理_联调种子数据 ② 库存管理_种子数据 ③ 本脚本）。

- **v0.0.13**（2026-02）：波次运行逻辑完善与 200 单种子数据。集波（execute）新建波次时拣货区域 `zone_desc` 改为 `ZONE-A·ZONE-B`，与库存库区一致，保证下发时能正确分配货位并预占库存。种子数据：`wms-admin-backend/tables/出库管理_200单波次种子数据.sql`（200 条出库单为待波次 start_state=2、无 wave_code），用于「立即执行」集波 + 「下发」运行波次的联调；执行顺序为先执行出库管理_联调种子数据.sql、再执行库存管理_种子数据.sql，最后执行本脚本。

- **v0.0.12**（2026-02）：任务调度后端与联调。基于 t_task_header（主表）、t_task_detail、t_task_source 实现任务调度接口文档全部 8 个接口。后端：TaskScheduleTypeEnum（task_type 与 API 字符串/中文名映射）；TaskHeaderMapper 扩展分页条件查询、统计（今日完成/进行中/平均时长）、类型分布、绩效排名、当日任务号序号；TaskHeaderManager 对应方法；TaskScheduleService 实现 stats、typeBreakdown、list、detail、create、assign、assignees、performanceRanking；WmsAdminUserManager 新增 listNonDeleted。种子数据：`wms-admin-backend/tables/任务调度_种子数据.sql`（TSK 前缀任务，多状态多类型多人员）。前端任务调度页已对接 `/api/admin/tasks/*`，关闭 Mock 后直连后端即可联调。

- **v0.0.11**（2026-02）：盘点管理后端与联调。后端：新增 t_stocktaking、t_stocktaking_detail 表（见 `wms-admin-backend/tables/t_stocktaking.sql`、`t_stocktaking_detail.sql`）；StocktakingTypeEnum、StocktakingStatusEnum；StocktakingMapper、StocktakingDetailMapper 及 XML；StocktakingManager、StocktakingService、StocktakingController；接口 `/api/admin/stocktaking/*`（统计、列表、详情、创建、审批通过/驳回、删除、导出、差异汇总）。种子数据：`wms-admin-backend/tables/盘点管理_种子数据.sql`（依赖仓库/库区/库存管理数据）。前端盘点页已对接上述接口，关闭 Mock 后请求真实后端即可联调。表结构说明：`doc/盘点管理_表结构及说明.md`。

- **v0.0.10**（2026-02）：二次分拣 15 单任务种子数据。新增 `wms-admin-backend/tables/二次分拣_15单任务种子数据.sql`：在「二次分拣_关联出库单任务种子数据.sql」之后执行，生成 15 条二次分拣任务（PK-REPICK-OD03～OD17），每单 5 个订单、关联 OD20260226006～OD20260226080，t_task_header/t_task_source/t_task_detail 与出库单及 SKU 一致，可直接用于二次分拣操作。

- **v0.0.9**（2026-02）：二次分拣关联出库单任务种子数据。新增 `wms-admin-backend/tables/二次分拣_关联出库单任务种子数据.sql`：基于现有 t_delivery_order、t_delivery_order_detail 生成 t_task_header（state=4、repick_status=pending）、t_task_source（order_code=出库单号）、t_task_detail（source_order_code、item_code、item_count 与出库单明细一致），任务码 PK-REPICK-OD01/02，执行顺序在出库管理联调种子数据之后，可直接用于二次分拣（进入分拣后生成 t_repick_progress/t_repick_process）。

- **v0.0.8**（2026-02）：出库波次功能完善。波次状态：待处理(0)、执行中(1)、已完成(2)。后端：新增 WaveStatusEnum、TWave、WaveMapper、WaveManager；OutboundWaveService 的 execute 写入 t_wave 并更新订单 wave_code，release 生成拣货单（TTaskHeader+TTaskDetail）并将波次置为已完成、订单置为拣货中，stats/kanban 改为基于 t_wave；DeliveryOrderDetailManager 新增 listByDeliveryOrderNoIn 批量查询明细。文档：func.md、出库管理接口文档（波次状态说明）已同步。

- **v0.0.7**（2026-02）：出库管理接口对接与测试数据。后端：出库相关 Controller 路径与文档一致（订单/波次/拣货/复核/发货交接）。测试数据：`wms-admin-backend/tables/出库管理_联调种子数据.sql`（约 80 条出库单+明细、10 波次、15 拣货任务、3 条发货交接）。前端：新增 `src/api/outbound.js` 封装全部出库接口（订单 pipeline/list/detail/assign/merge/split/export，波次 stats/触发与策略/execute/kanban/release/edit，拣货 stats/task list/assign/detail/handleException，复核 query/scan/weight/confirm/三打印，发货 stats/carrier list/scanHandover/handover list）；出库主入口下 5 个子页（订单管理、智能波次、拣货执行、复核打包、发货交接）均改为请求上述接口，列表分页、详情弹窗、分配/合并/导出/拆分、波次看板与配置、拣货分配与异常处理、复核扫码称重确认打印、发货扫码交接与今日记录）已对接。

- **v0.0.6.1**（2026-02）：用户管理前后端对接。前端用户管理页默认请求真实后端（`useMock=false`），请求 `/api/admin/users/*`（stats、list、create、update、delete、reset-password）与 `/api/admin/roles/*`（list、create、update）；前端 `request.js` 已兼容后端统一响应 `{ code, data, message }`。

- **v0.0.6**（2026-02）：仪表盘模块。后端：DashboardService、DashboardController，接口 `/api/admin/dashboard/*`（stats、order-trend、inventory-distribution、latest-orders、task-summary、stock-alerts）；DeliveryOrderMapper 按日统计；t_item 安全库存阈值扩展见 `tables/仪表盘_库存预警阈值扩展.sql`。前端：仪表盘页、`src/api/dashboard.js` 及 Mock（见计划）。

- **v0.0.5**（2026-02）：库存管理模块后端与对接。后端：库存调整表 `t_inventory_adjust`、`t_inventory_adjust_detail`（见 `wms-admin-backend/tables/t_inventory_adjust.sql`、`t_inventory_adjust_detail.sql`）；InventoryController、InventoryService、InventoryManager、InventoryAdjustManager；InventoryMapper 分页/统计/预警查询，InventoryAdjustMapper、InventoryAdjustDetailMapper；接口 `/api/admin/inventory/*`（统计、列表、详情、导出、预警汇总/列表、调整记录列表/详情/新建）。种子数据：`doc/库存管理_表结构及说明.md`、`doc/库存管理_种子数据.sql`。前端库存页已对接上述接口，无需改 URL。

- **v0.0.4**（2026-02）：系统设置模块后端与 Mock。后端：表结构及初始化 `wms-admin-backend/tables/系统设置_表结构及初始化.sql`（基本/仓库/接口/打印/通知/备份配置及备份记录）；Entity、Mapper、Manager、SettingsService、SettingsController，接口 `/api/admin/settings/*`。前端：`src/api/mockManager.js` 及系统设置相关 Mock，开发环境可走 Mock 数据。

- **v0.0.3**（2026-02）：新增系统设置模块。前端：系统设置页（基本设置、仓库参数、接口配置、打印设置、通知设置、数据备份 6 个 Tab）、`src/api/settings.js`，对接获取/保存及测试连接等接口。文档：`PrototypeDocs/apiDoc/系统设置_接口文档.md`。

- **v0.0.2**（2026-02）：新增用户管理模块。前端：用户管理页（用户列表/角色管理 Tab、统计卡片、表格、分页、新增/编辑/改密/删除用户、角色卡片与新增/编辑角色）、`src/api/users.js` 及 Mock 数据。后端：`t_wms_role`、`t_wms_admin_user` 表，WmsRoleMapper/WmsAdminUserMapper、UserManageService、RoleService、UserManageController、RoleController；接口路径 `/api/admin/users/*`、`/api/admin/roles/*`。文档：`PrototypeDocs/apiDoc/用户管理_接口文档.md`、`doc/用户管理_表结构及初始化.sql`。

---

## License

Private / 内部使用。