@rytass/wms-module-core 0.5.0 → 0.6.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 (49) hide show
  1. package/README.md +43 -1
  2. package/docs/api-reference.md +32 -1
  3. package/index.cjs.js +963 -5
  4. package/index.js +7 -0
  5. package/lib/constants/index.d.ts +2 -0
  6. package/lib/constants/inventory-count-status.d.ts +19 -0
  7. package/lib/constants/inventory-count-status.js +22 -0
  8. package/lib/constants/operations.d.ts +34 -0
  9. package/lib/constants/operations.js +66 -0
  10. package/lib/constants/stock-status.d.ts +2 -0
  11. package/lib/constants/stock-status.js +4 -0
  12. package/lib/core.module.js +9 -1
  13. package/lib/events/index.d.ts +1 -0
  14. package/lib/events/inventory-count-lock.subscriber.d.ts +38 -0
  15. package/lib/events/inventory-count-lock.subscriber.js +98 -0
  16. package/lib/events/stock-change.subscriber.js +6 -0
  17. package/lib/events/wms-event.types.d.ts +2 -2
  18. package/lib/models/extensions/index.d.ts +3 -0
  19. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.d.ts +20 -0
  20. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.js +50 -0
  21. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.d.ts +39 -0
  22. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.js +123 -0
  23. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.d.ts +50 -0
  24. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.js +155 -0
  25. package/lib/models/models.module.js +7 -0
  26. package/lib/services/allocate-inventory-order.service.js +3 -0
  27. package/lib/services/batch.service.js +3 -0
  28. package/lib/services/hold-inventory-order.service.js +3 -0
  29. package/lib/services/index.d.ts +1 -0
  30. package/lib/services/inventory-count-order.service.d.ts +143 -0
  31. package/lib/services/inventory-count-order.service.js +521 -0
  32. package/lib/services/loader.service.js +3 -0
  33. package/lib/services/location.service.js +3 -0
  34. package/lib/services/material.service.js +3 -0
  35. package/lib/services/merge-batch-order.service.js +3 -0
  36. package/lib/services/quality-inspection-order.service.js +3 -0
  37. package/lib/services/receive-inventory-order.service.js +3 -0
  38. package/lib/services/reclassify-inventory-order.service.js +3 -0
  39. package/lib/services/scrape.service.js +3 -0
  40. package/lib/services/ship-inventory-order.service.js +3 -0
  41. package/lib/services/split-batch-order.service.js +3 -0
  42. package/lib/services/stock.service.js +3 -0
  43. package/lib/services/transfer-customer-order.service.js +3 -0
  44. package/lib/services/transfer-order.service.js +3 -0
  45. package/lib/services/transfer-vendor-order.service.js +3 -0
  46. package/lib/services/unit.service.js +3 -0
  47. package/lib/services/warehouse-map.service.d.ts +11 -1
  48. package/lib/services/warehouse-map.service.js +13 -4
  49. package/package.json +1 -1
package/README.md CHANGED
@@ -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,13 @@ 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
+ - `InventoryCountOrderChangeEntity` / `InventoryCountOrderChangeEntityClass` — 盤差異動(正=盤盈、負=盤虧)
114
+ - 來源: `lib/models/extensions/inventory-count-order/`
115
+
109
116
  **入庫訂單 (Receive Inventory Order)**
110
117
  - `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
111
118
  - `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
@@ -206,6 +213,7 @@ WmsModuleCoreModule.forRootAsync({
206
213
  | `MergeBatchOrderService<T>` | `merge` | 批號合併 | `lib/services/merge-batch-order.service.ts` |
207
214
  | `ReclassifyInventoryOrderService<T>` | `reclassify` | 庫存轉料號 | `lib/services/reclassify-inventory-order.service.ts` |
208
215
  | `ScrapeService<T>` | `scrape` | 庫存報廢 | `lib/services/scrape.service.ts` |
216
+ | `InventoryCountOrderService<T>` | `findMany`, `findOne`, `create`, `update`, `start`, `count`, `addItem`, `removeItem`, `reset`, `cancel`, `settle` | 盤點單管理。`start` 會鎖定盤點範圍內的儲位,`settle` 是唯一會改動庫存的方法 | `lib/services/inventory-count-order.service.ts` |
209
217
  | `QualityInspectionOrderService<T>` | `inspect` | 品質檢驗 | `lib/services/quality-inspection-order.service.ts` |
210
218
  | `SaleOrderService` | (DataSource 直接操作) | 銷售訂單查詢 | `lib/services/sale-order.service.ts` |
211
219
  | `HelperService` | `getSeq` | 序號產生工具 | `lib/services/helper.service.ts` |
@@ -297,11 +305,32 @@ enum ChangeType {
297
305
  RECEIVED, IN_SHIPMENT, SHIPPED, IN_TRANSFER, TRANSFERRED,
298
306
  VENDOR_TRANSFERRED, VENDOR_RETURNED, HELD, RELEASED,
299
307
  CUSTOMER_HELD, CUSTOMER_RETURNED, SPLITTED, MERGED,
300
- ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED
308
+ ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED,
309
+ COUNT_GAINED, COUNT_LOST
301
310
  }
302
311
  ```
303
312
  來源: `lib/constants/stock-status.ts`
304
313
 
314
+ ### `InventoryCountStatus` (enum)
315
+ ```ts
316
+ enum InventoryCountStatus { PENDING, COUNTING, COMPLETED, CANCELLED }
317
+ ```
318
+ 盤點單狀態:尚未執行 / 盤點中 / 已完成 / 已取消。只有 `COUNTING` 接受盤點數量,也只有
319
+ `COUNTING` 會鎖定範圍內儲位;`COMPLETED` 只能由執行盤差達成。
320
+ 來源: `lib/constants/inventory-count-status.ts`
321
+
322
+ ### `WmsOperationName` (type) / `WMS_OPERATION_NAMES` (const)
323
+ ```ts
324
+ type WmsOperationName = 'material:read' | 'material:create' | /* …58 項… */;
325
+ const WMS_OPERATION_NAMES: readonly WmsOperationName[];
326
+ ```
327
+ 本套件所有 root operation 的 `` `${resource}:${action}` `` 名稱。同一組字串有三個用途:
328
+ `authChecker` 收到的 requirement、`@rytass/wms-module-graphql` 的
329
+ `enabledOperations` / `disabledOperations`、以及
330
+ `@rytass/wms-module-react` 的 `INVENTORY_ACTION_OPERATIONS` 對照表。
331
+ **注意名稱不等於欄位**:多支 query 共用同一組 requirement(`loader:read` 對應 6 支)。
332
+ 來源: `lib/constants/operations.ts`
333
+
305
334
  ### `ReceiveInventoryOrderStatus` (enum)
306
335
  ```ts
307
336
  enum ReceiveInventoryOrderStatus { PENDING, PARTIAL_RECEIVED, RECEIVED, REMOVED }
@@ -393,6 +422,7 @@ static forRootAsync(
393
422
  | `MaterialQuery` | `material`, `materials` | `MaterialDto`, `Materials` | `lib/queries/material.query.ts` |
394
423
  | `StockQuery` | `stock`, `stocks`, `stocksGroupedByMaterial`, `aggregatedStocks`, `changeLogs` | `StockDto`, `Stocks`, `Materials`, `AggregatedStocks`, `ChangeLogs` | `lib/queries/stock.query.ts` |
395
424
  | `BatchQuery` | `batches` | `Batches` | `lib/queries/batch.query.ts` |
425
+ | `InventoryCountOrderQuery` | `inventoryCountOrders`, `inventoryCountOrder` | `InventoryCountOrders`, `InventoryCountOrderDto` | `lib/queries/inventory-count-order.query.ts` |
396
426
  | `LocationQuery` | `location`, `locations` | `LocationDto`, `Locations` | `lib/queries/location.query.ts` |
397
427
  | `ReceiveInventoryOrderQuery` | `receiveInventoryOrder`, `receiveInventoryOrders` | `ReceiveInventoryOrderDto`, `ReceiveInventoryOrders` | `lib/queries/recieve-inventory-order.query.ts` |
398
428
  | `ShipInventoryOrderQuery` | `shipInventoryOrder`, `shipInventoryOrders` | `ShipInventoryOrderDto`, `ShipInventoryOrders` | `lib/queries/ship-inventory-order.query.ts` |
@@ -411,6 +441,7 @@ static forRootAsync(
411
441
  | `LoaderMutation` | `createLoader`, `createBatchLoader`, `updateLoader`, `createLoaderType`(方法名未確認), `updateLoaderType` | 載具與類型 | `lib/mutations/loader.mutation.ts` |
412
442
  | `LocationMutation` | `createLocation`, `updateLocation` | 庫位 | `lib/mutations/location.mutation.ts` |
413
443
  | `MaterialMutation` | `createMaterial`, `updateMaterial` | 料號 | `lib/mutations/material.mutation.ts` |
444
+ | `InventoryCountOrderMutation` | `createInventoryCountOrder`, `updateInventoryCountOrder`, `startInventoryCount`, `countInventory`, `addInventoryCountItem`, `removeInventoryCountItem`, `resetInventoryCount`, `cancelInventoryCount`, `settleInventoryCount` | 盤點單。`startInventoryCount` 會鎖定範圍內儲位;`settleInventoryCount` 是唯一會改動庫存的一支 | `lib/mutations/inventory-count-order.mutation.ts` |
414
445
  | `ReceiveInventoryOrderMutation` | `createReceiveInventoryOrder`, `updateReceiveInventoryOrder`, `receive` | 入庫單 | `lib/mutations/receive-inventory-order.mutation.ts` |
415
446
  | `ShipInventoryOrderMutation` | `createShipInventoryOrder`, `updateShipInventoryOrder`, `ship`, `cancelShip` | 出庫單 | `lib/mutations/ship-inventory-order.mutation.ts` |
416
447
  | `TransferOrderMutation` | `createTransferOrder`, `updateTransferOrder`, `transfer`, `cancelTransfer` | 調撥單 | `lib/mutations/transfer-order.mutation.ts` |