Implement API security baseline (sys_user, JWT, audit fields, transactions, unique constraints) and Web real login with 401 handling. Document setup and development workflows in root, WmsLite.Api, and WmsLite.Web README files. Co-authored-by: Cursor <cursoragent@cursor.com>
112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# 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`**
|
||
- 最多打开 **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
|
||
```
|
||
|
||
## 相关源码索引
|
||
|
||
| 主题 | 路径 |
|
||
|------|------|
|
||
| 前端入口与布局、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 / 深层弹窗** 场景可能存在边界问题;若单页异常,可针对该路由关闭缓存或调整结构。
|