@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.
Files changed (51) hide show
  1. package/README.md +44 -2
  2. package/docs/api-reference.md +37 -1
  3. package/docs/integration-guide.md +18 -17
  4. package/index.cjs.js +1160 -5
  5. package/index.js +7 -0
  6. package/lib/constants/index.d.ts +2 -0
  7. package/lib/constants/inventory-count-status.d.ts +19 -0
  8. package/lib/constants/inventory-count-status.js +22 -0
  9. package/lib/constants/operations.d.ts +34 -0
  10. package/lib/constants/operations.js +67 -0
  11. package/lib/constants/stock-status.d.ts +2 -0
  12. package/lib/constants/stock-status.js +4 -0
  13. package/lib/core.module.js +9 -1
  14. package/lib/events/index.d.ts +1 -0
  15. package/lib/events/inventory-count-lock.subscriber.d.ts +38 -0
  16. package/lib/events/inventory-count-lock.subscriber.js +98 -0
  17. package/lib/events/stock-change.subscriber.js +6 -0
  18. package/lib/events/wms-event.types.d.ts +2 -2
  19. package/lib/models/extensions/index.d.ts +3 -0
  20. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.d.ts +20 -0
  21. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.js +50 -0
  22. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.d.ts +48 -0
  23. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.js +175 -0
  24. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.d.ts +50 -0
  25. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.js +155 -0
  26. package/lib/models/models.module.js +7 -0
  27. package/lib/services/allocate-inventory-order.service.js +3 -0
  28. package/lib/services/batch.service.js +3 -0
  29. package/lib/services/hold-inventory-order.service.js +3 -0
  30. package/lib/services/index.d.ts +1 -0
  31. package/lib/services/inventory-count-order.service.d.ts +174 -0
  32. package/lib/services/inventory-count-order.service.js +641 -0
  33. package/lib/services/loader.service.js +3 -0
  34. package/lib/services/location.service.js +3 -0
  35. package/lib/services/material.service.js +3 -0
  36. package/lib/services/merge-batch-order.service.js +3 -0
  37. package/lib/services/quality-inspection-order.service.js +3 -0
  38. package/lib/services/receive-inventory-order.service.js +3 -0
  39. package/lib/services/reclassify-inventory-order.service.js +3 -0
  40. package/lib/services/scrape.service.js +3 -0
  41. package/lib/services/ship-inventory-order.service.js +3 -0
  42. package/lib/services/split-batch-order.service.js +3 -0
  43. package/lib/services/stock.service.js +27 -0
  44. package/lib/services/transfer-customer-order.service.js +3 -0
  45. package/lib/services/transfer-order.service.js +3 -0
  46. package/lib/services/transfer-vendor-order.service.js +3 -0
  47. package/lib/services/unit.service.js +3 -0
  48. package/lib/services/warehouse-map.service.d.ts +11 -1
  49. package/lib/services/warehouse-map.service.js +13 -4
  50. package/lib/typings/find-stock.input.d.ts +16 -0
  51. 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 rxjs reflect-metadata
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
 
@@ -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
- Tested combinations as of 0.1.2:
344
-
345
- | Package | Tested version | Notes |
346
- |----------------------------------|-------------------------|--------------------------------------------------------------------|
347
- | NestJS (`@nestjs/*`) | 11.x | 10.x untested; some Express-5-related APIs differ |
348
- | `@nestjs/graphql` | 13.x | Required for `@nestjs/apollo@13` |
349
- | `@nestjs/apollo` | 13.0.x – 13.1.x | 13.2+ requires @apollo/server@^5 which breaks lib's v4 plugin usage |
350
- | `@apollo/server` | 4.x | v5 is breaking; not supported |
351
- | `@as-integrations/express5` | 1.x | Required runtime peer |
352
- | TypeORM | 0.3.x | 0.2.x not supported (different DataSource API) |
353
- | PostgreSQL | 14+ | Native dialect |
354
- | `graphql` | 16.x | 15.x untested |
355
- | Node.js | 20 LTS or 22 | 18 deprecated, 24 untested |
356
- | Next.js | 15.x Pages Router | App Router unsupported (see §13.11) |
357
- | React | 19.x | 18.x likely works but untested |
358
- | `@mezzanine-ui/react` | 1.3.x | Earlier versions untested |
359
- | `nuqs` | 2.x (Pages adapter) | App Router adapter untested (see §13.11) |
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