WMSlite/README.md

117 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# WmsLite
轻量级仓储管理(WMS)示例项目:**ASP.NET Core API** + **Umi Max / Ant Design Pro 风格前端**,覆盖主数据、库位、库存与出入库/移库/盘点等业务单据。
## 仓库结构
| 目录 | 说明 |
|------|------|
| [WmsLite.Api](WmsLite.Api) | 后端 Web API — 详见 [WmsLite.Api/README.md](WmsLite.Api/README.md) |
| [WmsLite.Web](WmsLite.Web) | 前端 SPA — 详见 [WmsLite.Web/README.md](WmsLite.Web/README.md) |
## 技术栈
- **后端**:.NET、SqlSugar、REST `/api/...`
- **前端**:React 18、Umi Max 4、Ant Design 5、ProComponents、`react-activation`(标签页缓存)
## 后端功能概览
- **主数据**:仓库(Warehouse)、**库区**(Area)、**分区**(Zone)、库位(Location)、物料(Material)、容器(Container)
- **库位**:分页查询、增删改;支持**批量生成**(伸位/排列层模板等,见前端库位页)
- **库存**:库存余额、库存流水/事务(Inventory / InventoryTransaction)
- **单据**:入库、出库、移库、盘点(对应 `OrderControllers` 与各 `*OrderService`)
- **系统**:系统字典(SysDictionary)、单据/打印等模板(SysTemplate)、健康检查(Health)
认证与租户上下文由 **JWT** 提供:`tenantId`、`ownerCode`、`userId` 从 Token 解析,业务层不再信任前端传入的租户字段。
## 认证与本地配置
概要如下,**配置细节与 API 列表见 [WmsLite.Api/README.md](WmsLite.Api/README.md)**;**前端登录与 401 行为见 [WmsLite.Web/README.md](WmsLite.Web/README.md)**。
- **登录**:`POST /api/Auth/login`;默认种子用户 `admin` / `admin123`
- **JWT**:租户 / 货主 / 用户 ID 从 Token 解析,前端不再传 `tenantId` / `ownerCode`
- **数据库**:Development 使用占位密码;复制 `WmsLite.Api/appsettings.Development.local.json.example` 或配置 user-secrets
- 未登录访问业务 API → **401**;`/api/Health` 与登录接口匿名
## 前端功能概览
### 路由与模块
- **默认落地页**:`/home` 主页(欢迎与常用入口);`/` 重定向至 `/home`
- **基础数据**(`/base/*`):仓库、库区、分区、库位、物料、容器
- **库存**(`/inventory/*`):余额、流水
- **订单**(`/orders/*`):入库、出库、移库、盘点
- **模板**(`/templates`):系统模板维护
- **登录**:`/login`(本地 token:`localStorage` `wmslite-token`)
### 布局与多标签页
- **侧边菜单 + 顶部混合布局(mix)**:Pro Layout。
- **工作区标签栏**:位于 `ant-layout-header` 区域内,采用浅色轨道 + 胶囊标签样式。
- **Keep-Alive**:切换标签尽可能保留表格筛选、表单与滚动位置(`react-activation`)。
- **标签规则**:
- 单个标签标识为归一化后的 **`pathname + search`**。
- `/` 会归一为 `/home`,避免点击左上角图标后新增“页面”标签。
- 首页标签固定显示 Home 图标且不可关闭。
- 最多打开 **12** 个标签,超出时优先关闭最早的非首页标签。
- 关闭全部或最后一个业务标签后,回到 **首页**(`/home`),并保留「首页」标签。
- **批量关闭**:标签栏右侧更多图标提供 **关闭当前**、**关闭其他**、**关闭全部**。
### UI 共性
- 大量列表页基于通用 **[CrudPage](WmsLite.Web/src/components/CrudPage.tsx)**:`/api/{Controller}/paged-list`、新增/编辑弹窗、字典下拉等
- **库位**等页可使用 **`searchMode="explicit"`**:筛选字段由页面配置显式声明
- **订单类**页面使用 **[OrderPage](WmsLite.Web/src/components/OrderPage.tsx)** 等与单据相关的封装
- **全局字典**:`DictionaryProvider` + `/api/SysDictionary/map`
- **请求**:`/api` 开发代理;`Authorization: Bearer` 携带登录 Token;401 自动跳转登录页
路由与标签标题配置见:[WmsLite.Web/config/config.ts](WmsLite.Web/config/config.ts)、[WmsLite.Web/src/constants/routeTabTitles.ts](WmsLite.Web/src/constants/routeTabTitles.ts)。
## 本地运行
### 1. 启动 API
```powershell
cd WmsLite.Api
dotnet run --launch-profile http
```
默认监听 **http://localhost:9901**(见 `WmsLite.Api/Properties/launchSettings.json` 中 `http` 配置)。
### 2. 启动 Web
```powershell
cd WmsLite.Web
pnpm install
pnpm run dev
```
开发环境下,前端将 **`/api` 代理到 `http://localhost:9901`**(见 `WmsLite.Web/config/config.ts`)。若后端端口不同,请同步修改代理。
### 3. 质量检查(前端)
```powershell
cd WmsLite.Web
pnpm run lint
pnpm run typecheck
pnpm run build
```
当前项目约定不安排自动化测试建设,阶段验收以 `dotnet build`、`pnpm run typecheck`、`pnpm run build`、`pnpm run lint` 和人工业务场景为主。
## 相关源码索引
| 主题 | 路径 |
|------|------|
| 前端入口与布局、Alive 根节点 | `WmsLite.Web/src/app.tsx` |
| 标签状态与批量关闭逻辑 | `WmsLite.Web/src/contexts/TabLayoutContext.tsx` |
| 顶部标签 UI | `WmsLite.Web/src/components/LayoutHeaderTabs.tsx` |
| 主内容 KeepAlive | `WmsLite.Web/src/components/LayoutKeepAliveOutlet.tsx` |
| HTTP 封装与认证 | `WmsLite.Web/src/services/api.ts`、`WmsLite.Web/src/utils/auth.ts` |
| 后端认证与迁移 | `WmsLite.Api/Infrastructure/Auth/`、`WmsLite.Api/Database/migrations/` |
## 说明与限制
- 同一完整 URL **无法拆成两条独立标签**(若需「同路径多实例」,需另行扩展标签 key,例如 query 中增加实例标识)。
- `react-activation` 对部分 **Portal / 深层弹窗** 场景可能存在边界问题;若单页异常,可针对该路由关闭缓存或调整结构。