@rytass/wms-module-core 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -2
- package/docs/api-reference.md +37 -1
- package/docs/integration-guide.md +18 -17
- package/index.cjs.js +1160 -5
- package/index.js +7 -0
- package/lib/constants/index.d.ts +2 -0
- package/lib/constants/inventory-count-status.d.ts +19 -0
- package/lib/constants/inventory-count-status.js +22 -0
- package/lib/constants/operations.d.ts +34 -0
- package/lib/constants/operations.js +67 -0
- package/lib/constants/stock-status.d.ts +2 -0
- package/lib/constants/stock-status.js +4 -0
- package/lib/core.module.js +9 -1
- package/lib/events/index.d.ts +1 -0
- package/lib/events/inventory-count-lock.subscriber.d.ts +38 -0
- package/lib/events/inventory-count-lock.subscriber.js +98 -0
- package/lib/events/stock-change.subscriber.js +6 -0
- package/lib/events/wms-event.types.d.ts +2 -2
- package/lib/models/extensions/index.d.ts +3 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.d.ts +20 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.js +50 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.d.ts +48 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.js +175 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.d.ts +50 -0
- package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.js +155 -0
- package/lib/models/models.module.js +7 -0
- package/lib/services/allocate-inventory-order.service.js +3 -0
- package/lib/services/batch.service.js +3 -0
- package/lib/services/hold-inventory-order.service.js +3 -0
- package/lib/services/index.d.ts +1 -0
- package/lib/services/inventory-count-order.service.d.ts +174 -0
- package/lib/services/inventory-count-order.service.js +641 -0
- package/lib/services/loader.service.js +3 -0
- package/lib/services/location.service.js +3 -0
- package/lib/services/material.service.js +3 -0
- package/lib/services/merge-batch-order.service.js +3 -0
- package/lib/services/quality-inspection-order.service.js +3 -0
- package/lib/services/receive-inventory-order.service.js +3 -0
- package/lib/services/reclassify-inventory-order.service.js +3 -0
- package/lib/services/scrape.service.js +3 -0
- package/lib/services/ship-inventory-order.service.js +3 -0
- package/lib/services/split-batch-order.service.js +3 -0
- package/lib/services/stock.service.js +27 -0
- package/lib/services/transfer-customer-order.service.js +3 -0
- package/lib/services/transfer-order.service.js +3 -0
- package/lib/services/transfer-vendor-order.service.js +3 -0
- package/lib/services/unit.service.js +3 -0
- package/lib/services/warehouse-map.service.d.ts +11 -1
- package/lib/services/warehouse-map.service.js +13 -4
- package/lib/typings/find-stock.input.d.ts +16 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ This package only provides the data and service layer. Pair it with [`@rytass/wm
|
|
|
9
9
|
```bash
|
|
10
10
|
yarn add @rytass/wms-module-core
|
|
11
11
|
# peer deps
|
|
12
|
-
yarn add @nestjs/common @nestjs/typeorm typeorm
|
|
12
|
+
yarn add @nestjs/common @nestjs/typeorm typeorm reflect-metadata @rytass/wms-base-nestjs-module
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
## Quick start
|
|
@@ -65,7 +65,49 @@ export class MyService {
|
|
|
65
65
|
}
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
Exported services include `LoaderService`, `MaterialService`, `BatchService`, `StockService`, `LocationService`, `UnitService`, `HelperService`, `WarehouseMapDataService`, `ReceiveInventoryOrderService`, `ShipInventoryOrderService`, `HoldInventoryOrderService`, `AllocateInventoryOrderService`, `TransferOrderService`, `TransferCustomerOrderService`, `TransferVendorOrderService`, `SaleOrderService`, `SplitBatchOrderService`, `MergeBatchOrderService`, `ReclassifyInventoryOrderService`, `ScrapeService`, `QualityInspectionOrderService`.
|
|
68
|
+
Exported services include `LoaderService`, `MaterialService`, `BatchService`, `StockService`, `LocationService`, `UnitService`, `HelperService`, `WarehouseMapDataService`, `ReceiveInventoryOrderService`, `ShipInventoryOrderService`, `HoldInventoryOrderService`, `AllocateInventoryOrderService`, `TransferOrderService`, `TransferCustomerOrderService`, `TransferVendorOrderService`, `SaleOrderService`, `SplitBatchOrderService`, `MergeBatchOrderService`, `ReclassifyInventoryOrderService`, `ScrapeService`, `QualityInspectionOrderService`, `InventoryCountOrderService`.
|
|
69
|
+
|
|
70
|
+
## Inventory counting
|
|
71
|
+
|
|
72
|
+
`InventoryCountOrderService` implements counting: create an order over a set of locations
|
|
73
|
+
(expanded to every descendant), start it, record what was found, then settle the variance
|
|
74
|
+
into stock.
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const order = await counts.create({
|
|
78
|
+
name: '2026 上半年度例行盤點',
|
|
79
|
+
countDate: '2026-06-30', // the business date the variance is reported under
|
|
80
|
+
locationIds: [aisleId], // every shelf underneath is pulled in
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
await counts.start(order.id); // snapshots the ledger AND locks the scope
|
|
84
|
+
await counts.count(order.id, [{ itemId, countedQuantity: 94 }]);
|
|
85
|
+
await counts.settle(order.id); // the only call that changes stock
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Counting adjusts quantity **in place** — it never moves stock between locations; that is
|
|
89
|
+
what `TransferOrderService` is for. Uncounted lines are left alone rather than zeroed, and
|
|
90
|
+
a surplus may name a batch that does not exist yet (it is created during settlement).
|
|
91
|
+
|
|
92
|
+
> ⚠️ **`start()` locks the counted locations.** Until the order settles or is cancelled,
|
|
93
|
+
> any stock movement touching a location in its scope is refused with a `ConflictException`
|
|
94
|
+
> naming the count — including movements your own code makes by calling a service
|
|
95
|
+
> directly. The check sits on the insert of every `*_order_change` row, so it covers every
|
|
96
|
+
> path without any service needing to know about it. This is what keeps the book snapshot
|
|
97
|
+
> the variance is measured against from going stale.
|
|
98
|
+
|
|
99
|
+
## Operation names
|
|
100
|
+
|
|
101
|
+
Every root operation this package family exposes is named `` `${resource}:${action}` ``.
|
|
102
|
+
The union and its runtime counterpart are exported so a host can iterate them, diff them
|
|
103
|
+
against its own permission list, or drive
|
|
104
|
+
`@rytass/wms-module-graphql`'s `disabledOperations`:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { WMS_OPERATION_NAMES, type WmsOperationName } from '@rytass/wms-module-core';
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
These are the same strings your `authChecker` receives as `{ resource, action }`.
|
|
69
111
|
|
|
70
112
|
## Extending entities
|
|
71
113
|
|
package/docs/api-reference.md
CHANGED
|
@@ -106,6 +106,15 @@ WmsModuleCoreModule.forRootAsync({
|
|
|
106
106
|
|
|
107
107
|
同樣每個都有 Symbol + EntityClass 雙匯出,共 37 個:
|
|
108
108
|
|
|
109
|
+
**盤點單 (Inventory Count Order)**
|
|
110
|
+
- `InventoryCountOrderEntity` / `InventoryCountOrderEntityClass` — 盤點單主檔(`countDate` 為盤差記帳基準日)
|
|
111
|
+
- `InventoryCountOrderLocationEntity` / `InventoryCountOrderLocationEntityClass` — 盤點範圍,已展開至所有下層儲位(`isRoot` 標示使用者實際選的節點)
|
|
112
|
+
- `InventoryCountOrderItemEntity` / `InventoryCountOrderItemEntityClass` — 盤點單身(`isAddition` 標示盤盈新增列)。
|
|
113
|
+
開始盤點時另外快照 8 個當下屬性,供檢視頁顯示與篩選,之後不再隨庫存變動:
|
|
114
|
+
`held`、`inShipment`、`inspectionResult`、`transferId`、`vendorId`、`customerId`、`saleId`、`saleSerialId`
|
|
115
|
+
- `InventoryCountOrderChangeEntity` / `InventoryCountOrderChangeEntityClass` — 盤差異動(正=盤盈、負=盤虧)
|
|
116
|
+
- 來源: `lib/models/extensions/inventory-count-order/`
|
|
117
|
+
|
|
109
118
|
**入庫訂單 (Receive Inventory Order)**
|
|
110
119
|
- `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
|
|
111
120
|
- `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
|
|
@@ -206,6 +215,7 @@ WmsModuleCoreModule.forRootAsync({
|
|
|
206
215
|
| `MergeBatchOrderService<T>` | `merge` | 批號合併 | `lib/services/merge-batch-order.service.ts` |
|
|
207
216
|
| `ReclassifyInventoryOrderService<T>` | `reclassify` | 庫存轉料號 | `lib/services/reclassify-inventory-order.service.ts` |
|
|
208
217
|
| `ScrapeService<T>` | `scrape` | 庫存報廢 | `lib/services/scrape.service.ts` |
|
|
218
|
+
| `InventoryCountOrderService<T>` | `findMany`, `findOne`, `findItems`, `create`, `update`, `start`, `count`, `addItem`, `removeItem`, `reset`, `cancel`, `settle` | 盤點單管理。`start` 會鎖定盤點範圍內的儲位,`settle` 是唯一會改動庫存的方法。`findItems` 是單身的分頁查詢,支援 9 個欄位篩選與「只看盤差」 | `lib/services/inventory-count-order.service.ts` |
|
|
209
219
|
| `QualityInspectionOrderService<T>` | `inspect` | 品質檢驗 | `lib/services/quality-inspection-order.service.ts` |
|
|
210
220
|
| `SaleOrderService` | (DataSource 直接操作) | 銷售訂單查詢 | `lib/services/sale-order.service.ts` |
|
|
211
221
|
| `HelperService` | `getSeq` | 序號產生工具 | `lib/services/helper.service.ts` |
|
|
@@ -238,6 +248,9 @@ WmsModuleCoreModule.forRootAsync({
|
|
|
238
248
|
|
|
239
249
|
**庫存**
|
|
240
250
|
- `FindStockInput<U extends object>` (extends `PaginationInput`) — 來源: `lib/typings/find-stock.input.ts`
|
|
251
|
+
- 除了 `materialKey` / `batchKey` / `locationKey` / `loaderKey`(皆為 ILIKE 模糊比對),另可用批號上的四個商業屬性
|
|
252
|
+
`vendorId` / `customerId` / `saleId` / `saleSerialId` 篩選。這四個是**完全比對**,不是模糊比對——它們是上游系統的識別碼,
|
|
253
|
+
模糊比對會讓 `SO-1` 撈到 `SO-10`。傳 `null` 等同不篩選。
|
|
241
254
|
- `AggregatedStock`, `ValidateStockDeductionParams`, `ChangeLog` — 來源: `lib/typings/aggregated-stock.ts`
|
|
242
255
|
|
|
243
256
|
**批號**
|
|
@@ -297,11 +310,32 @@ enum ChangeType {
|
|
|
297
310
|
RECEIVED, IN_SHIPMENT, SHIPPED, IN_TRANSFER, TRANSFERRED,
|
|
298
311
|
VENDOR_TRANSFERRED, VENDOR_RETURNED, HELD, RELEASED,
|
|
299
312
|
CUSTOMER_HELD, CUSTOMER_RETURNED, SPLITTED, MERGED,
|
|
300
|
-
ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED
|
|
313
|
+
ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED,
|
|
314
|
+
COUNT_GAINED, COUNT_LOST
|
|
301
315
|
}
|
|
302
316
|
```
|
|
303
317
|
來源: `lib/constants/stock-status.ts`
|
|
304
318
|
|
|
319
|
+
### `InventoryCountStatus` (enum)
|
|
320
|
+
```ts
|
|
321
|
+
enum InventoryCountStatus { PENDING, COUNTING, COMPLETED, CANCELLED }
|
|
322
|
+
```
|
|
323
|
+
盤點單狀態:尚未執行 / 盤點中 / 已完成 / 已取消。只有 `COUNTING` 接受盤點數量,也只有
|
|
324
|
+
`COUNTING` 會鎖定範圍內儲位;`COMPLETED` 只能由執行盤差達成。
|
|
325
|
+
來源: `lib/constants/inventory-count-status.ts`
|
|
326
|
+
|
|
327
|
+
### `WmsOperationName` (type) / `WMS_OPERATION_NAMES` (const)
|
|
328
|
+
```ts
|
|
329
|
+
type WmsOperationName = 'material:read' | 'material:create' | /* …59 項… */;
|
|
330
|
+
const WMS_OPERATION_NAMES: readonly WmsOperationName[];
|
|
331
|
+
```
|
|
332
|
+
本套件所有 root operation 的 `` `${resource}:${action}` `` 名稱。同一組字串有三個用途:
|
|
333
|
+
`authChecker` 收到的 requirement、`@rytass/wms-module-graphql` 的
|
|
334
|
+
`enabledOperations` / `disabledOperations`、以及
|
|
335
|
+
`@rytass/wms-module-react` 的 `INVENTORY_ACTION_OPERATIONS` 對照表。
|
|
336
|
+
**注意名稱不等於欄位**:多支 query 共用同一組 requirement(`loader:read` 對應 6 支)。
|
|
337
|
+
來源: `lib/constants/operations.ts`
|
|
338
|
+
|
|
305
339
|
### `ReceiveInventoryOrderStatus` (enum)
|
|
306
340
|
```ts
|
|
307
341
|
enum ReceiveInventoryOrderStatus { PENDING, PARTIAL_RECEIVED, RECEIVED, REMOVED }
|
|
@@ -393,6 +427,7 @@ static forRootAsync(
|
|
|
393
427
|
| `MaterialQuery` | `material`, `materials` | `MaterialDto`, `Materials` | `lib/queries/material.query.ts` |
|
|
394
428
|
| `StockQuery` | `stock`, `stocks`, `stocksGroupedByMaterial`, `aggregatedStocks`, `changeLogs` | `StockDto`, `Stocks`, `Materials`, `AggregatedStocks`, `ChangeLogs` | `lib/queries/stock.query.ts` |
|
|
395
429
|
| `BatchQuery` | `batches` | `Batches` | `lib/queries/batch.query.ts` |
|
|
430
|
+
| `InventoryCountOrderQuery` | `inventoryCountOrders`, `inventoryCountOrder` | `InventoryCountOrders`, `InventoryCountOrderDto` | `lib/queries/inventory-count-order.query.ts` |
|
|
396
431
|
| `LocationQuery` | `location`, `locations` | `LocationDto`, `Locations` | `lib/queries/location.query.ts` |
|
|
397
432
|
| `ReceiveInventoryOrderQuery` | `receiveInventoryOrder`, `receiveInventoryOrders` | `ReceiveInventoryOrderDto`, `ReceiveInventoryOrders` | `lib/queries/recieve-inventory-order.query.ts` |
|
|
398
433
|
| `ShipInventoryOrderQuery` | `shipInventoryOrder`, `shipInventoryOrders` | `ShipInventoryOrderDto`, `ShipInventoryOrders` | `lib/queries/ship-inventory-order.query.ts` |
|
|
@@ -411,6 +446,7 @@ static forRootAsync(
|
|
|
411
446
|
| `LoaderMutation` | `createLoader`, `createBatchLoader`, `updateLoader`, `createLoaderType`(方法名未確認), `updateLoaderType` | 載具與類型 | `lib/mutations/loader.mutation.ts` |
|
|
412
447
|
| `LocationMutation` | `createLocation`, `updateLocation` | 庫位 | `lib/mutations/location.mutation.ts` |
|
|
413
448
|
| `MaterialMutation` | `createMaterial`, `updateMaterial` | 料號 | `lib/mutations/material.mutation.ts` |
|
|
449
|
+
| `InventoryCountOrderMutation` | `createInventoryCountOrder`, `updateInventoryCountOrder`, `startInventoryCount`, `countInventory`, `addInventoryCountItem`, `removeInventoryCountItem`, `resetInventoryCount`, `cancelInventoryCount`, `settleInventoryCount` | 盤點單。`startInventoryCount` 會鎖定範圍內儲位;`settleInventoryCount` 是唯一會改動庫存的一支 | `lib/mutations/inventory-count-order.mutation.ts` |
|
|
414
450
|
| `ReceiveInventoryOrderMutation` | `createReceiveInventoryOrder`, `updateReceiveInventoryOrder`, `receive` | 入庫單 | `lib/mutations/receive-inventory-order.mutation.ts` |
|
|
415
451
|
| `ShipInventoryOrderMutation` | `createShipInventoryOrder`, `updateShipInventoryOrder`, `ship`, `cancelShip` | 出庫單 | `lib/mutations/ship-inventory-order.mutation.ts` |
|
|
416
452
|
| `TransferOrderMutation` | `createTransferOrder`, `updateTransferOrder`, `transfer`, `cancelTransfer` | 調撥單 | `lib/mutations/transfer-order.mutation.ts` |
|
|
@@ -340,23 +340,24 @@ The `DEFAULT` location/loader/loaderType returned by the second query was seeded
|
|
|
340
340
|
|
|
341
341
|
### 4.6 Version compatibility matrix
|
|
342
342
|
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
|
348
|
-
|
|
349
|
-
| `@nestjs/
|
|
350
|
-
| `@
|
|
351
|
-
|
|
|
352
|
-
|
|
|
353
|
-
|
|
|
354
|
-
| `
|
|
355
|
-
|
|
|
356
|
-
|
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
343
|
+
Two different questions, so two columns. **Accepted** is what the published
|
|
344
|
+
`peerDependencies` allow — a version outside it fails to install. **Tested** is the
|
|
345
|
+
combination the integration suite actually runs against.
|
|
346
|
+
|
|
347
|
+
| Package | Accepted (peer range) | Tested | Notes |
|
|
348
|
+
|--------------------------|------------------------|--------------|-----------------------------------------------------------------------------|
|
|
349
|
+
| `@nestjs/common` | 10.x – 11.x | 11.1.x | **12.x is not accepted**: the whole NestJS 12 line is ESM-only, which this package (dual CJS+ESM) and a webpack-bundled host cannot consume yet |
|
|
350
|
+
| `@nestjs/typeorm` | 10.x – 11.x | 11.0.x | Three import sites (`InjectDataSource`, `forFeature`), stable across both |
|
|
351
|
+
| TypeORM | 0.3.x | 0.3.28 | 0.2.x not supported (different DataSource API) |
|
|
352
|
+
| `reflect-metadata` | 0.1.13+ / 0.2.x | 0.1.x | Ambient requirement of the decorators |
|
|
353
|
+
| `rxjs` | not a peer | — | Never imported by this package; `@nestjs/common` peers it for you |
|
|
354
|
+
| `@rytass/wms-base-nestjs-module` | 0.4.x | 0.4.0 | **A peer since 0.7.0**, not a bundled dependency. It was pinned exactly under `dependencies`, which cannot prevent a second copy — it *causes* one as soon as you ask for any other 0.4.x. Two copies means two sets of entity classes and DI Symbols, the split-brain this package's Symbol discipline exists to avoid. Install it yourself so there is one |
|
|
355
|
+
| PostgreSQL | — | 14+ | Native dialect |
|
|
356
|
+
| Node.js | — | 20 LTS / 22 | 18 deprecated, 24 untested |
|
|
357
|
+
|
|
358
|
+
The GraphQL-side packages (`@nestjs/graphql`, `@nestjs/apollo`, `@apollo/server`,
|
|
359
|
+
`@as-integrations/express5`) are not peers of this package — see
|
|
360
|
+
[`@rytass/wms-module-graphql`](https://www.npmjs.com/package/@rytass/wms-module-graphql) §4.6.
|
|
360
361
|
|
|
361
362
|
---
|
|
362
363
|
|