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。

---

四、关联关系

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

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 或表字段有调整，请以仓库内源码与数据库为准同步更新本文档。