123 lines
4.7 KiB
Markdown
Raw Permalink 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.Web
Umi Max 4 + Ant Design 5 + ProComponents 前端,负责 WMS 主数据、库存、单据和作业工作台体验。后端见 [WmsLite.Api](../WmsLite.Api/README.md),仓库总览见 [../README.md](../README.md)。
## 技术栈
- React 18、TypeScript
- `@umijs/max` 4、Ant Design 5、ProComponents
- `react-activation` 多标签 Keep-Alive
## 路由与模块
| 路径 | 说明 |
|------|------|
| `/login` | 登录页,无业务 Layout |
| `/home` | 作业工作台,展示单据与库存入口 |
| `/base/*` | 仓库、库区、分区、库位、物料、容器 |
| `/inventory/*` | 库存余额、库存流水 |
| `/orders/*` | 入库单、出库单、移库单、盘点单 |
| `/templates` | 系统模板 |
路由配置在 `config/config.ts`,标签标题映射在 `src/constants/routeTabTitles.ts`。
## 认证与请求
- 登录接口:`POST /api/Auth/login`,成功后写入 `localStorage`:
- `wmslite-token`:JWT
- `wmslite-user`:用户摘要 JSON
- `services/api.ts` 和 `app.tsx` 会自动携带 `Authorization: Bearer <token>`。
- HTTP 401 会清除本地登录状态,并跳转到 `/login?redirect=...`。
- 前端不再向业务接口传 `tenantId` / `ownerCode`,租户和货主由后端从 JWT 解析。
- 全局字典由 `DictionaryProvider` 在已登录状态加载 `/api/SysDictionary/map`。
默认开发账号:`admin` / `admin123`。
## 布局与多标签
- 使用 ProLayout `mix` 布局:侧边菜单 + 顶部工作区标签。
- 标签栏由 `LayoutHeaderTabs` 渲染,采用浅色轨道 + 胶囊标签样式,和顶部 Header 融为一个整体。
- 首页标签固定显示 Home 图标,且不可关闭。
- 标签 key 使用归一化后的 `pathname + search`:
- `/` 会归一化为 `/home`,避免点击左上角图标后生成“页面”标签。
- 最多打开 12 个标签;超过上限时优先关闭最早的非首页标签。
- 右侧更多按钮提供:关闭当前、关闭其他、关闭全部。
- 关闭全部或关闭最后一个业务标签后,保留并跳转到 `/home`。
- 页面内容由 `LayoutKeepAliveOutlet` 包裹,尽量保留列表筛选、表单状态和滚动位置。
## 主要页面体验
- `Home`:作业工作台,展示入库、出库、移库、盘点统计卡片、作业优先级和常用入口。
- `OrderPage`:四类单据统一页面。
- 入库、出库支持先创建 Draft 单头,再在详情抽屉中追加明细。
- 出库物料明细无需填写单位,由物料主数据单位自动带出。
- 出库详情展示拣货任务,支持单任务确认拣货后再确认出库。
- 单据状态使用颜色标签,详情抽屉顶部展示单据概要。
- `CrudPage`:主数据通用 CRUD 页面。
## 本地开发
### 1. 启动后端
```powershell
cd ../WmsLite.Api
dotnet run --launch-profile http
```
后端默认地址:`http://localhost:9901`。
### 2. 启动前端
```powershell
cd WmsLite.Web
pnpm install
pnpm run dev
```
前端通常监听 `http://localhost:8000` 或 Umi 自动分配的下一个可用端口;`/api` 会代理到 `http://localhost:9901`。
### 3. 质量检查
```powershell
pnpm run typecheck
pnpm run build
pnpm run lint
```
当前项目约定不新增自动化测试任务,阶段验收以 `typecheck`、`build`、`lint` 和人工业务场景为主。
## 目录结构
```text
WmsLite.Web/
├── config/config.ts # Umi 配置、路由、代理
├── src/
│ ├── app.tsx # 布局、request、initialState、退出登录
│ ├── services/api.ts # HTTP 封装、401 处理、业务 API
│ ├── utils/auth.ts # Token / 用户本地存储
│ ├── contexts/ # 字典、多标签状态
│ ├── components/ # CrudPage、OrderPage、Layout*
│ ├── pages/ # 业务页面
│ └── types/ # 前端 DTO 类型
├── .eslintrc.js
└── .stylelintrc.js
```
## 关键源码
| 主题 | 文件 |
|------|------|
| 运行时布局与请求拦截 | `src/app.tsx` |
| 标签状态与关闭逻辑 | `src/contexts/TabLayoutContext.tsx` |
| 顶部标签栏 UI | `src/components/LayoutHeaderTabs.tsx` |
| Keep-Alive 内容容器 | `src/components/LayoutKeepAliveOutlet.tsx` |
| 单据页面 | `src/components/OrderPage.tsx` |
| HTTP 封装 | `src/services/api.ts` |
| 全局视觉样式 | `src/global.less` |
## 注意事项
- 若 API 未启动,前端代理会报 `ECONNREFUSED`,请先启动 `WmsLite.Api`。
- 同一路径如需打开多个实例,需要通过 query 增加实例标识,否则会复用同一个标签 key。
- `react-activation` 对深层弹窗或 Portal 场景可能存在边界问题;若单页异常,可针对该路由调整缓存策略。