qhmes/docs/MES-XSL-客户到仓库-当前实现说明.md

# MES XSL「客户到仓库」当前实现说明

本文档只描述**当前设计与实现**：数据表、字段含义、后端与前端逻辑、实体间关系、约束与使用方式，不涉及历史变更过程。

---

## 一、涉及的数据表

| 表名 | 作用 |
|------|------|
| `mes_xsl_customer` | 客户主数据 |
| `mes_xsl_warehouse` | 仓库主数据（通过分类 + 客户/供应商字段实现「客户库 / 供应商库」） |
| `mes_xsl_supplier` | 供应商主数据 |
| `mes_xsl_unit` | 单位主数据（分类挂在系统分类字典上） |
| `sys_category` | 系统「分类字典」：仓库分类树根编码 `XSLMES_WH`，单位分类树根编码 `XSLMES_UNIT` |

---

## 二、字段说明

### 2.1 `mes_xsl_customer`

| 字段 | 说明 |
|------|------|
| `id` | 主键 |
| `customer_code` | 客户编码 |
| `customer_name` | 客户名称 |
| `customer_short_name` | 客户简称 |
| `customer_region` | 区域，数据字典 `xslmes_customer_region` |
| `erp_code` | ERP 编码 |
| `status` | 业务状态，字典 `xslmes_customer_status` |
| `del_flag` | 逻辑删除（0 正常 1 已删除） |
| `customer_desc` | 描述 |
| `iz_enable` | 是否启用（与状态等业务规则配合） |
| `create_by` / `create_time` / `update_by` / `update_time` | 审计字段（继承 Jeecg 基类） |
| `tenant_id` | 租户 ID |

### 2.2 `mes_xsl_warehouse`（客户 / 供应商与仓库的衔接点）

| 字段 | 说明 |
|------|------|
| `id` | 主键 |
| `warehouse_code` | 仓库编码 |
| `warehouse_name` | 仓库名称 |
| `warehouse_category` | **仓库分类**：存储 **`sys_category.id`**；该分类必须属于根编码 **`XSLMES_WH`** 下的子树 |
| `erp_code` | ERP 编码 |
| `status` | 启用/停用，字典 **`xslmes_unit_status`** |
| `customer_id` | 客户主键；**仅当**分类节点 `code = XSLMES_WH_F2_KH`（客户库）时必填且有意义 |
| `customer_short_name` | 客户简称（展示/冗余） |
| `supplier_id` | 供应商主键；**仅当**分类节点 `code = XSLMES_WH_F2_GYS`（供应商库）时必填且有意义 |
| `supplier_short_name` | 供应商简称（展示/冗余） |
| `del_flag` | 逻辑删除 |
| 审计字段、`tenant_id` | 同 Jeecg 惯例 |

**索引：** `warehouse_code`、`warehouse_category`。

### 2.3 `sys_category`（与仓库、单位相关的用法）

- **仓库**：根节点 `code = XSLMES_WH`（常量 `MesXslWarehouseCategory.ROOT_CODE`）。`mes_xsl_warehouse.warehouse_category` 存任意该树下的 **`id`**（通常选叶子节点）。
- **单位**：根节点 `code = XSLMES_UNIT`。`mes_xsl_unit.category_id` 存对应 **`id`**。

**与仓库校验相关的分类编码（后端写死）：**

| `sys_category.code` | 含义 | 业务规则 |
|---------------------|------|----------|
| `XSLMES_WH_F2_KH` | 客户库 | 保存仓库时 **必须** 有 `customer_id` |
| `XSLMES_WH_F2_GYS` | 供应商库 | 保存仓库时 **必须** 有 `supplier_id` |

当前种子树结构为：**根 `XSLMES_WH` → 一楼库 / 二楼仓库 → 各叶子**（成品库、待检库、客户库、供应商库等）；运维可在该根下扩展子节点（需具备分类维护权限）。

### 2.4 `mes_xsl_supplier`

| 字段 | 说明 |
|------|------|
| `id` | 主键 |
| `supplier_code` | 编码 |
| `supplier_name` | 名称 |
| `supplier_short_name` | 简称 |
| `erp_code` | ERP 编码 |
| `remark` | 备注 |
| `status` | 状态，字典 `xslmes_supplier_status` |
| `del_flag` | 逻辑删除 |
| 审计字段、`tenant_id` | 同 Jeecg 惯例 |

### 2.5 `mes_xsl_unit`

| 字段 | 说明 |
|------|------|
| `id` | 主键 |
| `unit_code` / `unit_name` | 单位编码、名称 |
| `erp_code` | ERP 编码 |
| `category_id` | **所属分类**：`sys_category.id`，且属于根 **`XSLMES_UNIT`** 子树 |
| `unit_desc` | 描述 |
| `status` | 字典 `xslmes_unit_status` |
| `del_flag` | 逻辑删除 |
| 审计字段、`tenant_id` | 同 Jeecg 惯例 |

---

## 三、实现逻辑

### 3.1 仓库保存与更新（后端）

实现类：`MesXslWarehouseServiceImpl`，在 `save` / `updateById` 时统一处理。

1. **按分类清理客户 / 供应商（`normalizePartners`）**  
   - 未选分类：清空 `customer_id`、`customer_short_name`、`supplier_id`、`supplier_short_name`。  
   - 已选分类：根据 `warehouse_category` 查询 `sys_category.code`。  
     - 若不是 **客户库**（`XSLMES_WH_F2_KH`）：清空客户相关两字段。  
     - 若不是 **供应商库**（`XSLMES_WH_F2_GYS`）：清空供应商相关两字段。  
   - 目的：切换仓库类型后不留错误的客户或供应商数据。

2. **按分类校验（`validatePartners`）**  
   - **客户库**：`customer_id` 为空则抛出业务异常：「仓库分类为客户库时，请选择客户」。  
   - **供应商库**：`supplier_id` 为空则抛出类似提示。

3. **分类编码查询**  
   - `MesXslWarehouseMapper.queryCategoryCodeById`：`SELECT code FROM sys_category WHERE id = ?`。

### 3.2 字典与展示

- `MesXslWarehouse.warehouse_category` 使用 `@Dict(dictTable = "sys_category", dicText = "name", dicCode = "id")`，列表/详情按 **分类名称** 展示。
- `MesXslUnit.category_id` 同样指向 `sys_category`。

### 3.3 前端（仓库）

- 菜单路由：`/xslmes/mesXslWarehouse`，列表组件：`MesXslWarehouseList`。  
- 左侧分类树：加载根编码 **`XSLMES_WH`** 的分类树（系统分类字典接口，与 `JCategorySelect` 的 `pcode` 一致）。  
- 列表筛选与查询参数需与后端 `QueryGenerator` 约定一致（如 `warehouseCategory`、多选场景下的 `warehouseCategory_MultiString` 等）。  
- 侧栏 **新增 / 编辑 / 删除分类**：调用 `/sys/category` 下标准增删改接口；按钮权限为 `xslmes:mes_xsl_warehouse_category:add|edit|delete`。

### 3.4 前端（单位）

- 分类选择：`JCategorySelect`，`pcode: XSLMES_UNIT`。  
- 按左侧分类筛选列表时，后端通过 **递归查询子分类 id**（`MesXslUnitService.listDescendantCategoryIds` / `MesXslUnitMapper`）过滤数据；依赖 **MySQL 8** 递归 CTE。

### 3.5 接口前缀（REST）

| 模块 | 路径前缀 |
|------|----------|
| 客户 | `/xslmes/mesXslCustomer` |
| 仓库 | `/xslmes/mesXslWarehouse` |
| 供应商 | `/xslmes/mesXslSupplier` |
| 单位 | `/xslmes/mesXslUnit` |

具体方法为 Jeecg 标准 CRUD（如列表、新增、编辑、删除、导入导出等），见各 `Controller`。

---

## 四、关联关系

数据库层**不强制外键**时，由应用与数据约定保证引用有效。

```mermaid
erDiagram
  sys_category_WH["sys_category（根 XSLMES_WH）"] ||--o{ mes_xsl_warehouse : "warehouse_category = id"
  mes_xsl_customer ||--o{ mes_xsl_warehouse : "customer_id = id（客户库）"
  mes_xsl_supplier ||--o{ mes_xsl_warehouse : "supplier_id = id（供应商库）"
  sys_category_UNIT["sys_category（根 XSLMES_UNIT）"] ||--o{ mes_xsl_unit : "category_id = id"
```

**语义说明：**

- 一条仓库记录对应 **一个** `warehouse_category`（`sys_category` 的一行）。  
- **客户库**：该仓库在业务上绑定 **一个** 客户（`customer_id` → `mes_xsl_customer.id`）。  
- **供应商库**：绑定 **一个** 供应商（`supplier_id` → `mes_xsl_supplier.id`）。  
- 其它分类：客户、供应商字段应在保存时被清空，不参与当前分类下的业务含义。

---

## 五、功能限制与注意点

1. **`warehouse_category` 必须是有效的 `sys_category.id`**，且业务上应选用 `XSLMES_WH` 树下节点；若 id 不存在或 `code` 查询不到，客户库/供应商库校验可能无法按预期触发。  
2. **客户库与供应商库互斥**：非客户库会自动清空客户字段，非供应商库会自动清空供应商字段；不应依赖「改分类后仍保留另一侧 ID」。  
3. **每条仓库仅一个客户、一个供应商字段**：与车辆等业务里「多客户 id 逗号拼接」等模型不同，仓库行是单值引用。  
4. **多租户**：若启用 SaaS 租户隔离，`mes_xsl_*` 等表需在 MyBatis 租户配置中注册，否则会出现串租或查不到数据。  
5. **单位分类树筛选**：依赖 MySQL 8 递归语法；低于 8.0 的环境需调整实现。  
6. **前端联调**：`VITE_GLOB_API_URL` 必须与后端 `context-path`（如 `/jeecg-boot`）一致，否则接口路径错误。

---

## 六、使用方法

### 6.1 环境

- 后端：`jeecg-system-start` 启动，数据库脚本由项目 **Flyway** 随应用升级自动执行，保证上述表与 `sys_category` 种子存在。  
- 浏览器访问前端，使用已配置 **MES XSL** 菜单及仓库、客户、供应商、单位等权限的账号。

### 6.2 维护主数据

1. **客户**：菜单「客户管理」，维护 `mes_xsl_customer`。  
2. **供应商**：菜单「供应商管理」，维护 `mes_xsl_supplier`。  
3. **单位**：菜单「单位管理」，分类从 **`XSLMES_UNIT`** 树选择；可在侧栏维护分类（与仓库侧栏模式类似，权限依项目配置）。

### 6.3 维护仓库分类树

1. 打开 **仓库管理**。  
2. 在左侧分类区域使用新增/编辑/删除（需 `xslmes:mes_xsl_warehouse_category:*` 权限）。  
3. 新建分类应挂在 **`XSLMES_WH`** 根之下，避免与其它业务根混淆。

### 6.4 新建「客户库」仓库

1. 新增仓库，**仓库分类** 选择 **客户库**（`code` 为 `XSLMES_WH_F2_KH` 的节点）。  
2. **必须** 选择客户并保存。  
3. 若之后改为非客户库分类，保存后客户相关字段会被后端清空。

### 6.5 新建「供应商库」仓库

将分类选为 **供应商库**（`XSLMES_WH_F2_GYS`），**必须** 选择供应商；改为其它分类时供应商字段会被清空。

### 6.6 权限说明（仓库相关示例）

- 仓库 CRUD 等：`xslmes:mes_xsl_warehouse:add`、`edit`、`delete`、`deleteBatch`、`exportXls`、`importExcel`、`updateStatus` 等。  
- 仓库分类维护：`xslmes:mes_xsl_warehouse_category:add`、`edit`、`delete`。  

实际以系统「菜单管理 / 角色授权」中配置为准。

---

*文档描述与当前代码、表结构一致；若常量 `MesXslWarehouseCategory` 或表字段有调整，请以仓库内源码与数据库为准同步更新本文档。*