# WMS Base NestJS Module (车载管理模组) ## 概述 `@rytass/wms-base-nestjs-module` 提供 NestJS 钱包管理系统的基础模组，支持储位树状结构、库存管理、库存异动追踪、订单管理及仓库地图功能。 ## 快速入门 ### 安装 npm install @rytass/wms-base-nestjs-module **对等依赖性：** * `@nestjs/common` ^9.0.0 || ^10.0.0 * `@nestjs/typeorm` ^9.0.0 || ^10.0.0 * `类型` ^0.3.0 ### 基本设置从'@nestjs/common'导入{模块}；从'@nestjs/typeorm'导入{TypeOrmModule}；从'@rytass/wms-base-nestjs-module'导入{WMSBaseModule}； @模块({ 进口：[ TypeOrmModule.forRoot({ 类型：'postgres'， // ... 数据库配置 }), WMSBaseModule.forRoot({ allowedNegativeStock: false, // 默认: false, 禁止负库存 }), ], }) 导出类 AppModule {} ###非同步设置从 '@rytass/wms-base-nestjs-module' 导入 { WMSBaseModule, WMSBaseModuleAsyncOptions }; 从'@nestjs/config'导入{ConfigService}； @模块({ 进口：[ // 使用工厂方式 WMSBaseModule.forRootAsync({ 注入：[ConfigService]， useFactory: (配置: ConfigService) => ({ allowedNegativeStock: config.get('WMS_ALLOW_NEGATIVE_STOCK', false), }), }), // 或 useClass 方式（使用自订工厂） // WMSBaseModule.forRootAsync({ // useClass: WMSConfigFactory, // }), // 或 useExisting 方式（重用现有工厂） // WMSBaseModule.forRootAsync({ // useExisting: ExistingWMSConfigFactory, // }), ], }) 导出类 AppModule {} ## 核心实体模组提供以下基础实体，皆可跨越继承扩展： ### LocationEntity (储位) 从'@rytass/wms-base-nestjs-module'导入{LocationEntity}； // 基础结构 - 表：'locations' @Entity('位置') @TableInheritance({ 列: { 类型: 'varchar', 名称: 'entityName' } }) @Tree('物化路径') 类位置实体{ @PrimaryColumn({ 类型: 'varchar' }) id：字符串； @TreeChildren() 子级：LocationEntity[]； @TreeParent() 父级：LocationEntity； @CreateDateColumn() 创建于：日期； @UpdateDateColumn() 更新时间：日期； @DeleteDateColumn() 删除时间：日期 |无效的; // 软删除 } > 使用 TypeORM `@Tree('materialized-path')` 实作树状结构 ### 材质实体（已提交）从'@rytass/wms-base-nestjs-module'导入{MaterialEntity}； // 表：'材料' @Entity('材料') @TableInheritance({ 列: { 类型: 'varchar', 名称: 'entityName' } }) 类材质实体{ @PrimaryColumn({ 类型: 'varchar' }) id：字符串； @CreateDateColumn() 创建于：日期； @UpdateDateColumn() 更新时间：日期； @DeleteDateColumn() 删除时间：日期 |无效的; // 软删除 @OneToMany(() => BatchEntity, 批次 => batch.material) 批次：Relation； @OneToMany(() => StockEntity, stock => stock.material) 股票：Relation； } ### BatchEntity (批次) 从'@rytass/wms-base-nestjs-module'导入{BatchEntity}； // 表：'批次' // 复合主键: id + MaterialId @Entity('批次') 类 BatchEntity { @PrimaryColumn('varchar') id：字符串； @PrimaryColumn('varchar') 材料ID：字符串； @ManyToOne(() => MaterialEntity, 材料 => 材料.批次) @JoinColumn({ name: 'materialId', referencedColumnName: 'id' }) 材质：Relation； @OneToMany(() => StockEntity, stock => stock.batch) 股票：Relation； } ### StockEntity (库存异动) 从'@rytass/wms-base-nestjs-module'导入{StockEntity}； // 表：'股票' @Entity('股票') @TableInheritance({ 列: { 类型: 'varchar', 名称: 'entityName' } }) 类 StockEntity { @PrimaryGenerateColumn('uuid') id：字符串； @Column({ 类型: 'varchar' }) 材料ID：字符串； @Column({ 类型: 'varchar' }) 批处理ID：字符串； @Column({ 类型: 'varchar' }) 位置ID：字符串； @Column({ 类型: 'varchar' }) 订单ID：字符串； @Column({ 类型: '数字' }) 数量：数量； // 正数为入库，负数为出库 @ManyToOne(() => MaterialEntity, 材料 => 材料.stocks) @JoinColumn({ name: 'materialId', referencedColumnName: 'id' }) 材质：Relation； @ManyToOne(() => BatchEntity, 批次 => batch.stocks) @JoinColumn([ { name: 'materialId', referencedColumnName: 'materialId' }, { name: 'batchId', referencedColumnName: 'id' }, ]）批处理：Relation； @ManyToOne(() => OrderEntity, order => order.stocks) @JoinColumn({ name: 'orderId', referencedColumnName: 'id' }) 订单：Relation； @CreateDateColumn() 创建于：日期； } ### 订单实体（订单）从'@rytass/wms-base-nestjs-module'导入{OrderEntity}； // 表：'订单' @Entity('订单') @TableInheritance({ 列: { 类型: 'varchar', 名称: 'entityName' } }) 订单实体类 { @PrimaryGenerateColumn('uuid') id：字符串； @OneToMany(() => StockEntity, stock => stock.order) 股票：Relation[]； } ### WarehouseMapEntity（仓库地图） > **注意：** `WarehouseMapService` 有从index.ts导出，可直接导入。但`WarehouseMapEntity`、`MapRangeType`、`MapRangeColor`、`MapData`等类型目前未从index.ts导出，需直接从原始码路径导入或自行定义。 // WarehouseMapService可以直接导入从 '@rytass/wms-base-nestjs-module' 导入 { WarehouseMapService }； // WarehouseMapEntity 需从原始码路径 import（若需要） // 表：'warehouse_maps' @Entity('warehouse_maps') 类 WarehouseMapEntity { @PrimaryColumn('varchar') // 回复 locationId id：字符串； @Column({ 类型: 'jsonb' }) 地图数据：地图数据； @CreateDateColumn() 创建于：日期； @UpdateDateColumn() 更新时间：日期； } ## 服务 ### LocationService（储位服务）从'@rytass/wms-base-nestjs-module'导入{LocationService，LocationEntity}； @Injectable() 导出类 WarehouseService { 构造函数（私有只读locationService：LocationService）{} // 建立储位异步创建位置（）{ // 建立根储位 const 仓库 = 等待 this.locationService.create({ id: '仓库-A', }); // 建立子储位 const zone = 等待 this.locationService.create({ id: '区域-A1', ParentId: '仓库-A', }); 返回区； } // 封存储位（软删除） // 注意: 只有库存为 0 的储位才能封存异步存档位置（id：字符串）{ 等待 this.locationService.archive(id); // 会覆盖所有子储位一起封存 } // 解除封存异步unArchiveLocation（id：字符串）{ const location = wait this.locationService.unArchive(id); 返回地点； } } ### MaterialService（提交服务）从'@rytass/wms-base-nestjs-module'导入{MaterialService，MaterialEntity}； @Injectable() 导出类 ProductService { 构造函数（私有只读materialService：MaterialService）{} // 建立库存异步创建材质() { const Material = 等待 this.materialService.create({ id: 'SKU-001', }); 退回材料； } } ### StockService（库存服务）导入{ 库存服务，库存查找Dto，库存查找全部Dto，库存分拣机，来自“@rytass/wms-base-nestjs-module”； @Injectable() 导出类 InventoryService { 构造函数（私有只读 stockService：StockService）{} // 查询库存数量 (回传加总数量) // find() 任选确定管理器参数供交易使用 async getStockQuantity(locationId: string,materialId: string): Promise { 返回 this.stockService.find({ 位置 ID：[位置 ID]，材料 ID：[材料 ID]， exactLocationMatch: true, // 只查询该储位，不包含子储位 }); } // 查询储位树下的总库存（包含所有子储位） async getTotalStock(locationId: string): Promise { 返回 this.stockService.find({ 位置 ID：[位置 ID]， // exactLocationMatch: false (默认) - 包含所有子储位 }); } //查询库存异动记录异步 getTransactionLogs（选项：StockFindAllDto）{ 返回 this.stockService.findTransactions({ locationIds: ['仓库-A'], 材料 ID：['SKU-001']，批次 ID：['BATCH-001']，偏移量：0， limit: 20, // 最大 100 排序器：StockSorter.CREATED_AT_DESC， }); // 回传: StockCollectionDto { transactionLogs, Total, Offset, limit } } } **StockFindDto 参数：** 参数 | 类型 | 说明 ---|---|--- `locationIds` | `字符串[]` | 储位ID列表 `materialIds` | `字符串[]` | 库存ID列表 `batchIds` | `字符串[]` | 批次 ID 列表 `精确位置匹配` | `布尔值` | `true`: 只查询指定储位；`false` (默认): 包含子储位 **StockFindAllDto 附加参数：** 参数 | 类型 | 预设值 | 说明 ---|---|---|--- `偏移` | `数字` | `0` | 分页偏移 `限制` | `数字` | `20` | 每页笔数（最大100） `分拣机` | `库存分类器` | `CREATED_AT_DESC` | 排序方式 **StockCollectionDto 回传结构:** 接口 StockCollectionDto { 交易日志：StockTransactionLogDto[]；总计：数量；偏移量：数字；限制：数量； } // 泛型版本，排除关联栏位类型 StockTransactionLogDto = 省略< 库存， '材料' | '批次' | '位置' | ‘订单’ >; //实际包含栏位（以预设StockEntity为例）: // { id、materialId、batchId、locationId、orderId、数量、createdAt } // 注意: 原始码省略了 'location'，但 StockEntity 注明没有位置关系 // （只有locationId栏位），这是防御性设计 ### OrderService（订单服务）导入{ 订单服务，订单实体，订单创建Dto，批量创建Dto, 来自“@rytass/wms-base-nestjs-module”；从'typeorm'导入{实体，列}； // 扩展订单实体 @Entity('自定义订单') 导出类 CustomOrderEntity 扩展 OrderEntity { @Column() 订单号：字符串； @Column() 类型：'入站' | “出站”； } @Injectable() 导出类 OrderManagementService { 构造函数（私有只读 orderService：OrderService）{} // 建立入库订单异步 createInboundOrder() { const order = wait this.orderService.createOrder(CustomOrderEntity, { 订单：{ 订单号：'IN-2024-001'，类型：'入境'， }, 批次：[ { id: '批次-001', 材料 ID：'SKU-001'， locationId: 'ZONE-A1', number: 100, // 正数: 入库 }, ], }); 退货订单； } // 建立出库订单异步 createOutboundOrder() { const order = wait this.orderService.createOrder(CustomOrderEntity, { 订单：{ 订单号: 'OUT-2024-001', 类型：'出站'， }, 批次：[ { id: '批次-001', 材料 ID：'SKU-001'， locationId: 'ZONE-A1', 数量: -50, // 负数: 出库 }, ], }); 退货订单； // 若allowNegativeStock: false 且库存不足，会抛出StockQuantityNotEnoughError } // 检查是否可建立库存异动异步 canCreateStock(batch: BatchCreateDto): Promise { 返回 this.orderService.canCreateStock(batch); } } **批量创建Dto：** 接口 BatchCreateDto { id：字符串；材料ID：字符串；位置ID：字符串；数量：数量； } **订单创建D至：** type OrderDto = DeepPartial>; 类型 OrderCreateDto = { 订单：OrderDto；批次：BatchCreateDto[]； }; ### WarehouseMapService（仓库地图服务） > **注意：** `WarehouseMapService` 有从index.ts导出，可直接导入。但`MapRangeType`和`MapRangeColor`目前未从index.ts导出，需自行定义或直接使用字串值。从 '@rytass/wms-base-nestjs-module' 导入 { WarehouseMapService }； // MapRangeType/MapRangeColor 可直接使用字符串值或手机定义枚举 // 可自行定义 enum 或使用字串常用枚举 MapRangeType { 矩形 = '矩形', 多边形='多边形'， } 枚举 MapRangeColor { 红色='红色'，黄色='黄色'，绿色='绿色'，蓝色='蓝色'，黑色=“黑色”， } @Injectable() 导出类MapService { 构造函数（私有只读warehouseMapService：WarehouseMapService）{} // 更新仓库地图异步 updateMap(locationId: string) { const map = 等待 this.warehouseMapService.updateMap( 位置 ID, // backgrounds: 背景图片 [ { id: 'bg-1', 文件名：'仓库地板.png', x：0， y：0，宽度：1000，高度：800， }, ], // 范围：区域标记 [ // 区域规划 { id: '区域-a1', 类型：MapRangeType.RECTANGLE，颜色：MapRangeColor.GREEN， x：100， y：100，宽度：200，身高：150， }, // 区域作业 { id: '区域特殊', 类型：MapRangeType.POLYGON，颜色：MapRangeColor.YELLOW，点：[ { x：400，y：100 }， { x：500，y：100 }， { x：550，y：200 }， { x：400，y：200 }， ], }, ], ）；返回地图； } // 获取地图资料异步 getMap(locationId: string) { 返回 this.warehouseMapService.getMapById(locationId); // 若不存在回传: { id, backgrounds: [], Ranges: [] } } // 删除地图异步deleteMap(locationId: string) { 等待 this.warehouseMapService.deleteMapById(locationId); } } ## 自定义实体（扩展实体）通过 `forRoot` 或 `forRootAsync` 确定自订实体：导入{ WMS基础模块，位置实体，材质实体，股票实体，批处理实体，订单实体，来自“@rytass/wms-base-nestjs-module”；从'typeorm'导入{实体，列}； // 扩展储位 @Entity('自定义位置') 导出类 CustomLocationEntity 扩展 LocationEntity { @Column() 名称：字符串； @Column({ 可空: true }) 描述：字符串； } // 扩展报价 @Entity('自定义材料') 导出类 CustomMaterialEntity 扩展 MaterialEntity { @Column() 名称：字符串； @Column() sku：字符串； } // 设定模组 @模块({ 进口：[ WMSBaseModule.forRoot({ 位置实体：自定义位置实体，材质实体：自定义材质实体， stockEntity: StockEntity, // 使用默认值 batchEntity: BatchEntity, // 使用默认值 orderEntity: OrderEntity, // 使用默认值允许负库存：假， }), ], }) 导出类 AppModule {} ## 数据类型 ### 地图数据接口地图数据{ id：字符串；背景：MapBackground[]；范围：(MapRectangleRange | MapPolygonRange)[]; } 接口地图背景{ id：字符串；文件名：字符串； x：数字； y：数字；高度：数字；宽度：数量； } 接口地图范围{ id：字符串；类型：地图范围类型；颜色: 字符串; } 接口 MapRectangleRange 扩展 MapRange { x：数字； y：数字；宽度：数量；高度：数字； } 接口 MapPolygonRange 扩展 MapRange { 点：MapPolygonRangePoint[]； } 接口MapPolygonRangePoint { x：数字； y：数字； } ### 枚举枚举 MapRangeType { 矩形 = '矩形', 多边形='多边形'， } 枚举 MapRangeColor { 红色='红色'，黄色='黄色'，绿色='绿色'，蓝色='蓝色'，黑色=“黑色”， } 枚举库存分类器 { CREATED_AT_DESC = 'CREATED_AT_DESC', CREATED_AT_ASC = 'CREATED_AT_ASC', } ## 错误处理导入{ 位置未找到错误，位置无法存档错误，位置已存在错误，库存数量不够错误，来自“@rytass/wms-base-nestjs-module”； **错误代码表：** 代码|错误|描述 ---|---|--- 100 | 100位置未找到错误 | 储位不存在 101 | 101位置无法存档错误 | 储位无法封存 (库存不为0) 102 | 102位置已存在错误 | 储位已存在 200 | 200库存数量不够错误 | 库存数量不足 @Injectable() 导出类 SafeLocationService { 构造函数（私有只读locationService：LocationService）{} 异步安全存档（id：字符串）{ 尝试{ 等待 this.locationService.archive(id); } 捕获（错误）{ if (LocationCannotArchiveError 错误实例) { throw new Error('无法封库位置，请先清空库存'); } if (LocationNotFoundError 错误实例) { throw new Error('储位不存在'); } 抛出错误； } } } ## 配置选项接口 WMSBaseModuleOptions { // 自订实体 (皆为选填) stockEntity?: new () => StockEntity; locationEntity?: new () => LocationEntity; MaterialEntity?: new () => MaterialEntity; BatchEntity?: new () => BatchEntity; orderEntity?: new () => OrderEntity; WarehouseMapEntity?: new () => WarehouseMapEntity; // 选项允许负库存？：布尔值； // 默认: false } // 异步选项接口 WMSBaseModuleAsyncOptions { 导入？：ModuleMetadata['导入']; 注入？：InjectionToken[]； useFactory?: (...args: any[]) => Promise | WMSBaseModuleOptions； useClass?: 类型; useExisting?: 类型; } // 选项工厂接口接口 WMSBaseModuleOptionsFactory { createWMSBaseModuleOptions(): Promise | WMSBaseModuleOptions； } ## 符号代币可用于依赖注入的Symbol Tokens：导入{ // 存储库令牌 RESOLVED_TREE_LOCATION_REPO, // TreeRepository RESOLVED_MATERIAL_REPO, // 存储库 RESOLVED_BATCH_REPO, // 存储库 RESOLVED_ORDER_REPO, // 存储库 RESOLVED_STOCK_REPO, // 存储库 RESOLVED_WAREHOUSE_MAP_REPO, // 存储库 // 实体提供者令牌 PROVIDE_LOCATION_ENTITY，提供_材料_实体， PROVIDE_BATCH_ENTITY，提供_订单_实体，提供_STOCK_ENTITY， PROVIDE_WAREHOUSE_MAP_ENTITY， // 期权代币 WMS_MODULE_OPTIONS, // WMSBaseModuleOptions ALLOW_NEGATIVE_STOCK, // 布尔值来自“@rytass/wms-base-nestjs-module”； // 使用示例 @Injectable() 导出类 CustomService { 构造函数（ @Inject(RESOLVED_TREE_LOCATION_REPO) 私有只读 locationRepo: TreeRepository, @Inject(RESOLVED_STOCK_REPO) 私有只读 stockRepo: Repository, @Inject(ALLOW_NEGATIVE_STOCK) 私有只读allowNegativeStock：布尔值，）{} } ## 完整示例从'@nestjs/common'导入{模块，可注入}；从'@nestjs/typeorm'导入{TypeOrmModule}；导入{ WMS基础模块，定位服务，材料服务，库存服务，订单服务，订单实体，库存分拣机，来自“@rytass/wms-base-nestjs-module”；从'typeorm'导入{实体，列}； // 自定义订单 @Entity('仓库订单') 导出类 WarehouseOrderEntity 扩展 OrderEntity { @Column() 订单号：字符串； @Column() 类型：'入站' | '出境' | '转移'; @Column({ 可空: true }) 注意：字符串； } // 以太坊服务 @Injectable() 导出类 WarehouseManagementService { 构造函数（私有只读位置服务：LocationService，私有只读材料服务：MaterialService，私有只读stockService：StockService，私有只读 orderService：OrderService，）{} // 初始化仓库结构异步初始化仓库() { const 仓库=await this.locationService.create({ id: 'WH-001' }); const zoneA = wait this.locationService.create({ id: 'WH-001-A', ParentId: 'WH-001' }); const zoneB = wait this.locationService.create({ id: 'WH-001-B', ParentId: 'WH-001' }); 返回 { 仓库, zoneA, zoneB }; } // 入库作业异步入站（materialId：字符串，locationId：字符串，数量：数字，batchId：字符串）{ // 确认供应存在等待 this.materialService.create({ id:materialId }); // 建立入库订单 const order = wait this.orderService.createOrder(WarehouseOrderEntity, { 订单：{ orderNumber: `IN-${Date.now()}`, 类型：'入境'， }, 批次：[{ id：批次ID，材料ID, 位置 ID, amount, // 正数 }], }); 退货订单； } // 出库作业异步出站（materialId：字符串，locationId：字符串，数量：数字，batchId：字符串）{ //查询库存 const stock = 等待 this.stockService.find({ 位置 ID：[位置 ID]，材料 ID：[材料 ID]，批次 ID：[批次 ID]，精确位置匹配：正确， }); if (库存 < 数量) { throw new Error(`库存不足：现有 ${stock}，需要 ${quantity}`); } // 建立出库订单 const order = wait this.orderService.createOrder(WarehouseOrderEntity, { 订单：{ orderNumber: `OUT-${Date.now()}`, 类型：'出站'， }, 批次：[{ id：批次ID，材料ID, 位置 ID, amount: -quantity, // 负数 }], }); 退货订单； } // 查询库存异步 getInventory(locationId: string) { const Total = wait this.stockService.find({ locationIds: [locationId] }); const 日志 = 等待 this.stockService.findTransactions({ 位置 ID：[位置 ID]，限制：10，排序器：StockSorter.CREATED_AT_DESC， }); 返回 { 总计，最近的日志：logs.transactionLogs }; } } // 模组 @模块({ 进口：[ TypeOrmModule.forRoot({ 类型：'postgres'，主机：'本地主机'，数据库：'wms'，实体：[WarehouseOrderEntity]，同步：真， }), WMSBaseModule.forRoot({ orderEntity: WarehouseOrderEntity, 允许负库存：假， }), ], 提供商：[仓库管理服务]， }) 导出类 WarehouseModule {} ## 故障排除 ### 负库存错误如果`allowNegativeStock: false`，出库数量超过库存会触发`StockQuantityNotEnoughError`。优先查询库存再执行出库操作。 ### 交易失败 `createOrder` 使用数据库交易，任何批次失败都会回滚整个订单。确保所有批次数据正确再提交。 ###仓位无法封存當嘗試封存一個仍有庫存的倉位時，會拋出 `LocationCannotArchiveError`。需先將庫存移出（出庫或調撥）後才能封存倉位。 ### 倉位已存在錯誤建立儲位時，若 ID 已存在（含已封存的），會拋出 `LocationAlreadyExistedError`。可以先解除封存 (`unArchive`) 或使用不同的 ID。

仓库管理系统模块

包含技能