@rytass/wms-module-core 0.4.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 (80) hide show
  1. package/README.md +69 -7
  2. package/docs/api-reference.md +58 -10
  3. package/docs/custom-entities.md +105 -68
  4. package/index.cjs.js +1263 -151
  5. package/index.js +10 -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 +66 -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 +91 -30
  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/allocate-inventory-order/allocate-inventory-order-item.entity.js +1 -0
  20. package/lib/models/extensions/hold-inventory-order/hold-inventory-order-item.entity.js +1 -0
  21. package/lib/models/extensions/index.d.ts +3 -0
  22. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.d.ts +20 -0
  23. package/lib/models/extensions/inventory-count-order/inventory-count-order-change.entity.js +50 -0
  24. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.d.ts +39 -0
  25. package/lib/models/extensions/inventory-count-order/inventory-count-order-item.entity.js +123 -0
  26. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.d.ts +50 -0
  27. package/lib/models/extensions/inventory-count-order/inventory-count-order.entity.js +155 -0
  28. package/lib/models/extensions/merge-batch-order/merge-batch-order-item.entity.js +1 -0
  29. package/lib/models/extensions/quality-inspection-order/quality-inspection-order-item.entity.js +1 -0
  30. package/lib/models/extensions/reclassify-inventory-order/reclassify-inventory-order-item.entity.js +1 -0
  31. package/lib/models/extensions/scrape-order/scrape-order-item.entity.js +1 -0
  32. package/lib/models/extensions/split-batch-order/split-batch-order-item.entity.js +1 -0
  33. package/lib/models/extensions/transfer-customer-order/transfer-customer-order-item.entity.js +1 -0
  34. package/lib/models/extensions/transfer-order/transfer-order-item.entity.js +1 -0
  35. package/lib/models/extensions/transfer-vendor-order/transfer-vendor-order-item.entity.js +1 -0
  36. package/lib/models/index.d.ts +1 -0
  37. package/lib/models/metadata/index.d.ts +1 -0
  38. package/lib/models/metadata/order.entity.d.ts +9 -0
  39. package/lib/models/metadata/order.entity.js +5 -0
  40. package/lib/models/models.module.js +22 -8
  41. package/lib/models/wms-entities.d.ts +45 -0
  42. package/lib/models/wms-entities.js +82 -0
  43. package/lib/services/allocate-inventory-order.service.d.ts +3 -1
  44. package/lib/services/allocate-inventory-order.service.js +13 -6
  45. package/lib/services/batch.service.js +8 -3
  46. package/lib/services/hold-inventory-order.service.d.ts +3 -1
  47. package/lib/services/hold-inventory-order.service.js +13 -6
  48. package/lib/services/index.d.ts +1 -0
  49. package/lib/services/inventory-count-order.service.d.ts +143 -0
  50. package/lib/services/inventory-count-order.service.js +521 -0
  51. package/lib/services/loader.service.js +5 -0
  52. package/lib/services/location.service.js +5 -0
  53. package/lib/services/material.service.d.ts +1 -15
  54. package/lib/services/material.service.js +5 -20
  55. package/lib/services/merge-batch-order.service.d.ts +3 -1
  56. package/lib/services/merge-batch-order.service.js +16 -9
  57. package/lib/services/quality-inspection-order.service.d.ts +3 -1
  58. package/lib/services/quality-inspection-order.service.js +15 -8
  59. package/lib/services/receive-inventory-order.service.d.ts +3 -1
  60. package/lib/services/receive-inventory-order.service.js +18 -11
  61. package/lib/services/reclassify-inventory-order.service.d.ts +3 -1
  62. package/lib/services/reclassify-inventory-order.service.js +16 -9
  63. package/lib/services/scrape.service.d.ts +3 -1
  64. package/lib/services/scrape.service.js +12 -5
  65. package/lib/services/ship-inventory-order.service.d.ts +3 -1
  66. package/lib/services/ship-inventory-order.service.js +21 -14
  67. package/lib/services/split-batch-order.service.d.ts +3 -1
  68. package/lib/services/split-batch-order.service.js +16 -9
  69. package/lib/services/stock.service.d.ts +3 -1
  70. package/lib/services/stock.service.js +17 -10
  71. package/lib/services/transfer-customer-order.service.d.ts +3 -1
  72. package/lib/services/transfer-customer-order.service.js +15 -8
  73. package/lib/services/transfer-order.service.d.ts +3 -1
  74. package/lib/services/transfer-order.service.js +14 -7
  75. package/lib/services/transfer-vendor-order.service.d.ts +3 -1
  76. package/lib/services/transfer-vendor-order.service.js +15 -8
  77. package/lib/services/unit.service.js +5 -0
  78. package/lib/services/warehouse-map.service.d.ts +14 -2
  79. package/lib/services/warehouse-map.service.js +21 -9
  80. package/package.json +2 -2
package/README.md CHANGED
@@ -65,17 +65,63 @@ 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
 
72
114
  Each entity is exported in two forms — `MaterialEntity` (a `Symbol` DI token) and `MaterialEntityClass` (the entity class the token is bound to). Everything inside the module resolves entities through the token, so rebinding the token swaps the entity everywhere at once.
73
115
 
74
- `materialEntity` is the override that is wired all the way through today. Give it a `@ChildEntity()` of `MaterialEntityClass` and your own table *is* the WMS material master — no second table, no double writes:
116
+ All six entity options `WMSBaseModuleOptions` exposes — `materialEntity`, `batchEntity`, `locationEntity`, `stockEntity`, `orderEntity`, `warehouseMapEntity` — are wired all the way through. Give one a `@ChildEntity()` of the class it replaces and your own table *is* the WMS table — no second table, no double writes:
75
117
 
76
118
  ```ts
77
119
  import { ChildEntity, Column } from 'typeorm';
78
- import { MaterialEntityClass, WmsModuleCoreModule } from '@rytass/wms-module-core';
120
+ import {
121
+ BatchEntityClass,
122
+ MaterialEntityClass,
123
+ WmsModuleCoreModule,
124
+ } from '@rytass/wms-module-core';
79
125
 
80
126
  @ChildEntity()
81
127
  export class ItemMasterEntity extends MaterialEntityClass {
@@ -83,19 +129,35 @@ export class ItemMasterEntity extends MaterialEntityClass {
83
129
  erpCode!: string | null;
84
130
  }
85
131
 
132
+ @ChildEntity()
133
+ export class LotEntity extends BatchEntityClass {
134
+ @Column({ type: 'date', nullable: true })
135
+ expiresOn!: Date | null;
136
+ }
137
+
86
138
  WmsModuleCoreModule.forRootAsync({
87
- useFactory: async () => ({ materialEntity: ItemMasterEntity }),
139
+ useFactory: async () => ({
140
+ materialEntity: ItemMasterEntity,
141
+ batchEntity: LotEntity,
142
+ }),
88
143
  defaultLoaderSerialId: 'DEFAULT',
89
144
  defaultLoaderTypeKey: 'DEFAULT',
90
145
  defaultLocationKey: 'DEFAULT',
91
146
  });
92
147
  ```
93
148
 
94
- It is an ordinary `WMSBaseModuleOptions` field, so `forRoot` and the async factory both work. The base module resolves its repository from it and this package binds its `MaterialEntity` Symbol from the same `PROVIDE_MATERIAL_ENTITY` token at injection time — one option, two consumers, no way for them to drift. This needs `@rytass/wms-base-nestjs-module` >= 0.3.0, the release that exports those tokens.
149
+ They are ordinary `WMSBaseModuleOptions` fields, so `forRoot` and the async factory both work, and you can override as few or as many as you like. The base module resolves its repositories from them and this package binds its entity Symbols from the same `PROVIDE_*_ENTITY` tokens at injection time — one option, two consumers, no way for them to drift. Needs `@rytass/wms-base-nestjs-module` >= 0.4.0.
150
+
151
+ `WmsEntities` is exported for consumers who need the resolved classes themselves:
152
+
153
+ ```ts
154
+ constructor(private readonly entities: WmsEntities) {}
155
+ // this.entities.material / .batch / .location / .stock / .order / .warehouseMap
156
+ ```
95
157
 
96
- **You register the entity with TypeORM yourself** (`TypeOrmModule.forFeature([ItemMasterEntity])`, or the DataSource's `entities`). The module cannot: `forFeature()` runs while Nest assembles the module graph, before the options resolve. Forgetting it almost works — TypeORM still creates your columns in `materials` — so the module checks at startup and refuses to boot with a message telling you what to add.
158
+ **You register the entities with TypeORM yourself** (`TypeOrmModule.forFeature([...])`, or the DataSource's `entities`). The module cannot: `forFeature()` runs while Nest assembles the module graph, before the options resolve. Forgetting almost works — TypeORM still creates your columns in the parent table — so the module checks at startup and refuses to boot with a message naming what to add.
97
159
 
98
- The remaining entity options on `WMSBaseModuleOptions` (`batchEntity`, `locationEntity`, `stockEntity`, `orderEntity`, `warehouseMapEntity`) still resolve only a base-module repository this package does not read — setting them has no effect above the base layer. [`docs/custom-entities.md`](./docs/custom-entities.md) has the full picture, the single-table-inheritance caveats for pre-existing rows, and the per-option audit.
160
+ [`docs/custom-entities.md`](./docs/custom-entities.md) has the full picture, including what single-table inheritance means for rows written before the override existed.
99
161
 
100
162
  ## Module options token
101
163
 
@@ -38,28 +38,44 @@ static forRootAsync(
38
38
  ): DynamicModule
39
39
  ```
40
40
 
41
- **Entity override(since 0.4.0,需 `@rytass/wms-base-nestjs-module` >= 0.3.0)**
41
+ **Entity override(since 0.5.0,需 `@rytass/wms-base-nestjs-module` >= 0.4.0)**
42
42
 
43
- `WMSBaseModuleOptions.materialEntity` 現在會一路作用到 core 與 graphql。傳入的 class 必須是 `MaterialEntityClass` 的 `@ChildEntity()`:
43
+ `WMSBaseModuleOptions` 的六個 entity 選項現在會一路作用到 core 與 graphql。每個都必須是它所取代的 class 的 `@ChildEntity()`:
44
+
45
+ | 選項 | 資料表 | 取代 |
46
+ |---|---|---|
47
+ | `materialEntity` | `materials` | `MaterialEntityClass` |
48
+ | `batchEntity` | `batches` | `BatchEntityClass` |
49
+ | `locationEntity` | `locations` | `LocationEntityClass` |
50
+ | `stockEntity` | `stocks` | `StockEntityClass` |
51
+ | `orderEntity` | `orders` | `OrderEntityClass` |
52
+ | `warehouseMapEntity` | `warehouse_maps` | `WarehouseMapEntity`(基座) |
44
53
 
45
54
  ```ts
46
55
  WmsModuleCoreModule.forRootAsync({
47
- useFactory: async () => ({ materialEntity: ItemMasterEntity }),
56
+ useFactory: async () => ({
57
+ materialEntity: ItemMasterEntity,
58
+ batchEntity: LotEntity,
59
+ }),
48
60
  defaultLoaderSerialId: 'DEFAULT',
49
61
  defaultLoaderTypeKey: 'DEFAULT',
50
62
  defaultLocationKey: 'DEFAULT',
51
63
  });
52
64
  ```
53
65
 
54
- - `forRoot` 與 async factory 皆可,因為 `MaterialEntity` Symbol 是在 **DI 時**由基座 export 的 `PROVIDE_MATERIAL_ENTITY` 綁定,不是在 module graph 組裝時。
55
- - 基座的 `RESOLVED_MATERIAL_REPO` 與 core 的 `MaterialEntity` 由**同一個 option** 推導,結構上不可能不一致。
56
- - **entity 需自行註冊給 TypeORM**(`TypeOrmModule.forFeature([ItemMasterEntity])` 或 DataSource `entities`);模組無法代勞,漏掉時會在啟動階段丟出明確錯誤。
57
- - 非 `MaterialEntityClass` 子類會在啟動時被拒絕(TypeScript 結構型別擋不住兄弟類別)。
58
- - 其餘 entity 選項(`batchEntity` / `locationEntity` / `stockEntity` / `orderEntity` / `warehouseMapEntity`)目前仍只作用於 base module。詳見 [`custom-entities.md`](./custom-entities.md)。
66
+ - `forRoot` 與 async factory 皆可,因為各 Symbol 是在 **DI 時**由基座 export 的 `PROVIDE_*_ENTITY` 綁定,不是在 module graph 組裝時。
67
+ - 基座的 `RESOLVED_*_REPO` 與 core 的 Symbol 由**同一個 option** 推導,結構上不可能不一致。
68
+ - **entity 需自行註冊給 TypeORM**(`TypeOrmModule.forFeature([...])` 或 DataSource `entities`);模組無法代勞,漏掉時會在啟動階段列出缺哪幾個。
69
+ - 未繼承正確 class 者會在啟動時被拒絕(TypeScript 結構型別擋不住兄弟類別)。
70
+ - 可只覆寫其中幾個,其餘沿用內建 class。詳見 [`custom-entities.md`](./custom-entities.md)。
71
+
72
+ ### `WmsEntities`
73
+ - 用途: 套用覆寫後**實際**被讀寫的 entity class 集合。`material` / `batch` / `location` / `stock` / `order` / `warehouseMap` 六個唯讀屬性。消費端需要同一份答案時可直接注入。建構時會驗證每個 entity 都已註冊給 TypeORM。
74
+ - 來源: `lib/models/wms-entities.ts`
59
75
 
60
76
  ### `ModelsModule`
61
77
  - 用途: 內部模組,向 TypeORM 註冊所有 WMS 實體(via DI token 形式),並透過 `ResolvedEntitiesProviders` 提供 DI。**消費端不直接 import**;它由 `WmsModuleCoreModule.forRoot` 自動引入並 re-export。
62
- - `MaterialEntity` Symbol **不由此模組綁定**:它在 `WmsModuleCoreModule` 內由 `PROVIDE_MATERIAL_ENTITY` 推導,避免同一個 token 出現兩個繫結。`MaterialEntityClass` 仍註冊進 `forFeature()`(它是單表繼承的根)。
78
+ - 六個可覆寫的 Symbol **不由此模組綁定**:它們在 `WmsModuleCoreModule` 內由對應的 `PROVIDE_*_ENTITY` 推導,避免同一個 token 出現兩個繫結。內建 class 仍註冊進 `forFeature()`(它們是各自單表繼承的根)。
63
79
  - 來源: `lib/models/models.module.ts`
64
80
 
65
81
  ---
@@ -72,6 +88,7 @@ WmsModuleCoreModule.forRootAsync({
72
88
  |---|---|---|---|
73
89
  | `UnitEntity` | `UnitEntityClass` | 單位主檔(kg / pcs 等) | `lib/models/metadata/unit.entity.ts` |
74
90
  | `MaterialEntity` | `MaterialEntityClass` | 料號主檔,繼承 `BaseMaterialEntity` | `lib/models/metadata/material.entity.ts` |
91
+ | `OrderEntity` | `OrderEntityClass` | 訂單基底(本套件未加欄位,`OrderEntityClass` 即基座 class) | `lib/models/metadata/order.entity.ts` |
75
92
  | `MaterialUnitEntity` | `MaterialUnitEntityClass` | 料號換算單位(含換算係數) | `lib/models/metadata/material-unit.entity.ts` |
76
93
  | `BatchEntity` | `BatchEntityClass` | 批號主檔,繼承 `BaseBatchEntity` | `lib/models/metadata/batch.entity.ts` |
77
94
  | `BatchGroupEntity` | `BatchGroupEntityClass` | 批號群組,支援多批合併情境 | `lib/models/metadata/batch-group.entity.ts` |
@@ -89,6 +106,13 @@ WmsModuleCoreModule.forRootAsync({
89
106
 
90
107
  同樣每個都有 Symbol + EntityClass 雙匯出,共 37 個:
91
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
+
92
116
  **入庫訂單 (Receive Inventory Order)**
93
117
  - `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
94
118
  - `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
@@ -189,6 +213,7 @@ WmsModuleCoreModule.forRootAsync({
189
213
  | `MergeBatchOrderService<T>` | `merge` | 批號合併 | `lib/services/merge-batch-order.service.ts` |
190
214
  | `ReclassifyInventoryOrderService<T>` | `reclassify` | 庫存轉料號 | `lib/services/reclassify-inventory-order.service.ts` |
191
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` |
192
217
  | `QualityInspectionOrderService<T>` | `inspect` | 品質檢驗 | `lib/services/quality-inspection-order.service.ts` |
193
218
  | `SaleOrderService` | (DataSource 直接操作) | 銷售訂單查詢 | `lib/services/sale-order.service.ts` |
194
219
  | `HelperService` | `getSeq` | 序號產生工具 | `lib/services/helper.service.ts` |
@@ -280,11 +305,32 @@ enum ChangeType {
280
305
  RECEIVED, IN_SHIPMENT, SHIPPED, IN_TRANSFER, TRANSFERRED,
281
306
  VENDOR_TRANSFERRED, VENDOR_RETURNED, HELD, RELEASED,
282
307
  CUSTOMER_HELD, CUSTOMER_RETURNED, SPLITTED, MERGED,
283
- ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED
308
+ ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED,
309
+ COUNT_GAINED, COUNT_LOST
284
310
  }
285
311
  ```
286
312
  來源: `lib/constants/stock-status.ts`
287
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
+
288
334
  ### `ReceiveInventoryOrderStatus` (enum)
289
335
  ```ts
290
336
  enum ReceiveInventoryOrderStatus { PENDING, PARTIAL_RECEIVED, RECEIVED, REMOVED }
@@ -376,6 +422,7 @@ static forRootAsync(
376
422
  | `MaterialQuery` | `material`, `materials` | `MaterialDto`, `Materials` | `lib/queries/material.query.ts` |
377
423
  | `StockQuery` | `stock`, `stocks`, `stocksGroupedByMaterial`, `aggregatedStocks`, `changeLogs` | `StockDto`, `Stocks`, `Materials`, `AggregatedStocks`, `ChangeLogs` | `lib/queries/stock.query.ts` |
378
424
  | `BatchQuery` | `batches` | `Batches` | `lib/queries/batch.query.ts` |
425
+ | `InventoryCountOrderQuery` | `inventoryCountOrders`, `inventoryCountOrder` | `InventoryCountOrders`, `InventoryCountOrderDto` | `lib/queries/inventory-count-order.query.ts` |
379
426
  | `LocationQuery` | `location`, `locations` | `LocationDto`, `Locations` | `lib/queries/location.query.ts` |
380
427
  | `ReceiveInventoryOrderQuery` | `receiveInventoryOrder`, `receiveInventoryOrders` | `ReceiveInventoryOrderDto`, `ReceiveInventoryOrders` | `lib/queries/recieve-inventory-order.query.ts` |
381
428
  | `ShipInventoryOrderQuery` | `shipInventoryOrder`, `shipInventoryOrders` | `ShipInventoryOrderDto`, `ShipInventoryOrders` | `lib/queries/ship-inventory-order.query.ts` |
@@ -394,6 +441,7 @@ static forRootAsync(
394
441
  | `LoaderMutation` | `createLoader`, `createBatchLoader`, `updateLoader`, `createLoaderType`(方法名未確認), `updateLoaderType` | 載具與類型 | `lib/mutations/loader.mutation.ts` |
395
442
  | `LocationMutation` | `createLocation`, `updateLocation` | 庫位 | `lib/mutations/location.mutation.ts` |
396
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` |
397
445
  | `ReceiveInventoryOrderMutation` | `createReceiveInventoryOrder`, `updateReceiveInventoryOrder`, `receive` | 入庫單 | `lib/mutations/receive-inventory-order.mutation.ts` |
398
446
  | `ShipInventoryOrderMutation` | `createShipInventoryOrder`, `updateShipInventoryOrder`, `ship`, `cancelShip` | 出庫單 | `lib/mutations/ship-inventory-order.mutation.ts` |
399
447
  | `TransferOrderMutation` | `createTransferOrder`, `updateTransferOrder`, `transfer`, `cancelTransfer` | 調撥單 | `lib/mutations/transfer-order.mutation.ts` |
@@ -4,11 +4,8 @@ How to make a downstream project's own table the WMS's table, instead of keeping
4
4
  a second one in sync.
5
5
 
6
6
  > Applies to `@rytass/wms-module-core` and `@rytass/wms-module-graphql`.
7
- > Currently supported for **materials**; see the [audit](#6-audit-of-the-remaining-entity-options)
8
- > for where the other entities stand.
9
- >
10
- > Requires `@rytass/wms-base-nestjs-module` >= 0.3.0, which is the release that
11
- > exports the resolved entity tokens this depends on.
7
+ > All six entities `WMSBaseModuleOptions` exposes are supported. Requires
8
+ > `@rytass/wms-base-nestjs-module` >= 0.4.0.
12
9
 
13
10
  ## Table of Contents
14
11
 
@@ -17,67 +14,103 @@ a second one in sync.
17
14
  3. [Passing it to the module](#3-passing-it-to-the-module)
18
15
  4. [Registering the entity with TypeORM](#4-registering-the-entity-with-typeorm)
19
16
  5. [What single-table inheritance means for your data](#5-what-single-table-inheritance-means-for-your-data)
20
- 6. [Audit of the remaining entity options](#6-audit-of-the-remaining-entity-options)
17
+ 6. [Overriding more than one](#6-overriding-more-than-one)
21
18
 
22
19
  ---
23
20
 
24
21
  ## 1. What the option does
25
22
 
26
- `@rytass/wms-base-nestjs-module` has always accepted a `materialEntity` in
27
- `WMSBaseModuleOptions`, but it kept the resolved entity to itself: the token was
28
- never exported, so `@rytass/wms-module-core` could not read it and bound its
29
- `MaterialEntity` Symbol to the built-in `MaterialEntityClass` unconditionally.
30
- The option therefore changed nothing above the base layer.
31
-
32
- `wms-base` 0.3.0 exports `PROVIDE_MATERIAL_ENTITY` and `RESOLVED_MATERIAL_REPO`
33
- (the same shape `@rytass/member-base-nestjs-module` has always used for
34
- `memberEntity`), and the core module now binds its Symbol from that token at
35
- injection time.
36
-
37
- Passing `materialEntity` now rebinds every place the module reads or writes
38
- materials:
39
-
40
- | Consumer of the material entity | Where it lives |
41
- |--------------------------------------------------------|-----------------------------------------------------------|
42
- | `MaterialEntity` Symbol (and its TypeORM registration) | `libs/core/src/lib/models/models.module.ts` |
43
- | `MaterialService` (create / update / find) | `libs/core/src/lib/services/material.service.ts` |
44
- | Receive order item resolution | `libs/core/src/lib/services/receive-inventory-order.service.ts` |
45
- | Ship order reference resolution (create and update) | `libs/core/src/lib/services/ship-inventory-order.service.ts` |
46
- | Reclassify target resolution | `libs/core/src/lib/services/reclassify-inventory-order.service.ts` |
47
- | `materialKey` stock filter and material grouping | `libs/core/src/lib/services/stock.service.ts` |
48
- | Every GraphQL `material` DataLoader | `libs/graphql/src/lib/resolvers/*.resolver.ts` |
49
- | `RESOLVED_MATERIAL_REPO` in the base module | resolved from the same option — cannot drift |
23
+ `@rytass/wms-base-nestjs-module` has always accepted entity overrides in
24
+ `WMSBaseModuleOptions`, but it kept the resolved entities to itself: the tokens
25
+ were never exported, so `@rytass/wms-module-core` could not read them and bound
26
+ its own entity Symbols to the built-in classes unconditionally. The options
27
+ therefore changed nothing above the base layer.
28
+
29
+ `wms-base` 0.3.0 exports `PROVIDE_*_ENTITY` and `RESOLVED_*_REPO` (the same
30
+ shape `@rytass/member-base-nestjs-module` has always used for `memberEntity`),
31
+ and the core module binds its Symbols from those tokens at injection time.
32
+
33
+ | Option | Table | Replaces | Also reached by |
34
+ |----------------------|------------------|------------------------|------------------------------------------------------------|
35
+ | `materialEntity` | `materials` | `MaterialEntityClass` | `MaterialService`, receive / ship / reclassify, stock filters |
36
+ | `batchEntity` | `batches` | `BatchEntityClass` | `BatchService`, split / merge / reclassify |
37
+ | `locationEntity` | `locations` | `LocationEntityClass` | `LocationService`, receive, transfers, startup seeding |
38
+ | `stockEntity` | `stocks` | `StockEntityClass` | `StockService` and every path that moves stock |
39
+ | `orderEntity` | `orders` | `OrderEntityClass` | every order service — one row per stock movement |
40
+ | `warehouseMapEntity` | `warehouse_maps` | `WarehouseMapEntity` | `WarehouseMapDataService` and the map mutation |
41
+
42
+ Nothing in either package imports these classes as values any more. Every
43
+ service, DataLoader and query reaches them through a `Symbol`, so rebinding one
44
+ swaps that entity everywhere at once — including the GraphQL DataLoaders, which
45
+ would otherwise resolve `null` for an override and fail their non-nullable
46
+ fields.
47
+
48
+ `WmsEntities` is the injectable holding the resolved classes, exported for
49
+ consumers who need the same answer:
50
+
51
+ ```ts
52
+ import { WmsEntities } from '@rytass/wms-module-core';
53
+
54
+ @Injectable()
55
+ export class MyService {
56
+ constructor(private readonly entities: WmsEntities) {}
57
+
58
+ find(): Promise<unknown[]> {
59
+ return this.dataSource.getRepository(this.entities.material).find();
60
+ }
61
+ }
62
+ ```
50
63
 
51
64
  ## 2. Writing the entity
52
65
 
53
- The entity must be a TypeORM `@ChildEntity()` extending `MaterialEntityClass`.
54
- It joins the existing `materials` table through single-table inheritance; it does
55
- not move the data anywhere.
66
+ Each override must be a TypeORM `@ChildEntity()` extending the class it replaces.
67
+ It joins the existing table through single-table inheritance; it does not move
68
+ the data anywhere.
56
69
 
57
70
  ```ts
58
71
  import { ChildEntity, Column, Index } from 'typeorm';
59
- import { MaterialEntityClass } from '@rytass/wms-module-core';
72
+ import {
73
+ BatchEntityClass,
74
+ LocationEntityClass,
75
+ MaterialEntityClass,
76
+ } from '@rytass/wms-module-core';
60
77
 
61
78
  @ChildEntity()
62
79
  export class ItemMasterEntity extends MaterialEntityClass {
63
80
  @Column({ type: 'varchar', nullable: true })
64
81
  @Index()
65
82
  erpCode!: string | null;
83
+ }
66
84
 
85
+ @ChildEntity()
86
+ export class LotEntity extends BatchEntityClass {
87
+ @Column({ type: 'date', nullable: true })
88
+ expiresOn!: Date | null;
89
+ }
90
+
91
+ @ChildEntity()
92
+ export class BinEntity extends LocationEntityClass {
67
93
  @Column({ type: 'varchar', nullable: true })
68
- vendorPartNumber!: string | null;
94
+ zone!: string | null;
69
95
  }
70
96
  ```
71
97
 
72
98
  Rules:
73
99
 
74
- - **Extend `MaterialEntityClass`, not the base `MaterialEntity`.** The module's
75
- services and the `MaterialDto` GraphQL type read `description`, `baseUnit` and
76
- `isActive`, which `MaterialEntityClass` declares.
100
+ - **Extend the class this package exports, not the base one.** `MaterialEntityClass`,
101
+ `BatchEntityClass`, `LocationEntityClass` and `StockEntityClass` add the columns
102
+ the services and DTOs read; the base classes do not declare them. `OrderEntityClass`
103
+ and the warehouse map entity are the base classes — this package adds nothing to
104
+ those two — and are re-exported so every override reads the same way.
77
105
  - **New columns must be nullable or have a default.** Rows written before the
78
106
  override existed carry the old discriminator and have no value for them.
79
107
  - **Do not re-declare `@Entity()` or `@TableInheritance()`.** Both belong to the
80
- base `MaterialEntity`; `@ChildEntity()` is the whole decoration you need.
108
+ class you are extending; `@ChildEntity()` is the whole decoration you need. The
109
+ same goes for `@Tree()` on a location override — inherit it, do not repeat it.
110
+ - The module refuses to boot if an override does not extend the right class.
111
+ `WMSBaseModuleOptions` only asks for a child of the *base* entity, and
112
+ TypeScript's structural typing will happily accept a sibling that never
113
+ declares the columns this package reads.
81
114
 
82
115
  ## 3. Passing it to the module
83
116
 
@@ -93,6 +126,8 @@ WmsModuleGraphqlModule.forRootAsync({
93
126
  useFactory: async (vault: VaultService) => ({
94
127
  allowNegativeStock: await vault.get<boolean>('ALLOW_NEGATIVE_STOCK'),
95
128
  materialEntity: ItemMasterEntity,
129
+ batchEntity: LotEntity,
130
+ locationEntity: BinEntity,
96
131
  }),
97
132
 
98
133
  defaultLoaderSerialId: 'DEFAULT',
@@ -101,11 +136,14 @@ WmsModuleGraphqlModule.forRootAsync({
101
136
  });
102
137
  ```
103
138
 
139
+ Override as few or as many as you like; anything left out keeps its built-in
140
+ class.
141
+
104
142
  ### `forRoot`
105
143
 
106
144
  ```ts
107
145
  WmsModuleCoreModule.forRoot(
108
- { materialEntity: ItemMasterEntity },
146
+ { materialEntity: ItemMasterEntity, batchEntity: LotEntity },
109
147
  {
110
148
  defaultLoaderSerialId: 'DEFAULT',
111
149
  defaultLoaderTypeKey: 'DEFAULT',
@@ -118,8 +156,8 @@ You pass it once. The base module resolves its repository from it and the core
118
156
  module binds its `MaterialEntity` Symbol from it; both read the same option, so
119
157
  there is no forwarding step that could get them out of step.
120
158
 
121
- If the class does not extend `MaterialEntityClass`, the module refuses to boot —
122
- `WMSBaseModuleOptions` only asks for a child of the *base* `MaterialEntity`, and
159
+ If a class does not extend the one it replaces, the module refuses to boot —
160
+ `WMSBaseModuleOptions` only asks for a child of the *base* entity, and
123
161
  TypeScript's structural typing will not catch a sibling that happens to look
124
162
  right.
125
163
 
@@ -133,7 +171,7 @@ options resolve.
133
171
  @Module({
134
172
  imports: [
135
173
  TypeOrmModule.forRoot({ /* ... */ autoLoadEntities: true }),
136
- TypeOrmModule.forFeature([ItemMasterEntity]),
174
+ TypeOrmModule.forFeature([ItemMasterEntity, LotEntity, BinEntity]),
137
175
  WmsModuleGraphqlModule.forRootAsync({ /* ... */ }),
138
176
  ],
139
177
  })
@@ -149,10 +187,10 @@ module checks for it at startup and refuses to boot rather than letting an
149
187
  `EntityMetadataNotFoundError` surface later from inside a resolver:
150
188
 
151
189
  ```
152
- WmsModuleCoreModule: the configured materialEntity "ItemMasterEntity" is not
153
- registered with TypeORM. Add it to your DataSource "entities", or import
154
- TypeOrmModule.forFeature([ItemMasterEntity]) somewhere in your app when using
155
- autoLoadEntities.
190
+ WmsModuleCoreModule: configured entities are not registered with TypeORM
191
+ (materialEntity: ItemMasterEntity, batchEntity: LotEntity). Add them to your
192
+ DataSource "entities", or import TypeOrmModule.forFeature([ItemMasterEntity,
193
+ LotEntity]) somewhere in your app when using autoLoadEntities.
156
194
  ```
157
195
 
158
196
  ## 5. What single-table inheritance means for your data
@@ -169,24 +207,23 @@ class wrote each one.
169
207
  - Reading through `MaterialEntityClass` still returns your rows, because your
170
208
  class is a descendant of it. The asymmetry only bites in the other direction.
171
209
 
172
- ## 6. Audit of the remaining entity options
173
-
174
- `WMSBaseModuleOptions` exposes six entity overrides. Only `materialEntity` is
175
- honoured above the base layer today. The rest resolve a base-module repository
176
- that `@rytass/wms-module-core` never reads, so setting them has no effect on core
177
- or graphql:
178
-
179
- | Option | Base token | Core Symbol | Status | Hard-coded call sites remaining |
180
- |-----------------------|-------------------------------|---------------------|--------|------------------------------------------------------------------|
181
- | `materialEntity` | `RESOLVED_MATERIAL_REPO` | `MaterialEntity` | supported | 0 |
182
- | `batchEntity` | `RESOLVED_BATCH_REPO` | `BatchEntity` | not supported | 5 `getRepository(BatchEntityClass)` in core, 11 resolver `__entity` |
183
- | `locationEntity` | `RESOLVED_TREE_LOCATION_REPO` | `LocationEntity` | not supported | 5 in core, 12 resolver `__entity` |
184
- | `stockEntity` | `RESOLVED_STOCK_REPO` | `StockEntity` | not supported | 8 in core (services inject the Symbol *and* hard-code the class) |
185
- | `orderEntity` | `RESOLVED_ORDER_REPO` | none | not supported | 17 `getRepository(OrderEntity)` on the base class directly |
186
- | `warehouseMapEntity` | `RESOLVED_WAREHOUSE_MAP_REPO` | `WarehouseMapEntity`| not supported | `WarehouseMapDataService` resolves the base class directly |
187
-
188
- All six tokens are exported by `wms-base` 0.3.0, so extending support to another
189
- entity no longer needs a base-module change: bind its Symbol from the matching
190
- `PROVIDE_*_ENTITY` in `WmsModuleCoreModule` the way `MaterialEntity` is bound,
191
- then sweep the call sites listed above. `orderEntity` is the largest job and the
192
- only one with no core Symbol at all.
210
+ ## 6. Overriding more than one
211
+
212
+ The overrides are independent — take one, take all six, mix and match. They are
213
+ resolved from the same options object and validated together at startup, so a
214
+ partial configuration is a normal state rather than a special case.
215
+
216
+ One caveat worth knowing when overriding `warehouseMapEntity`: its table gained
217
+ its `entityName` discriminator column in `wms-base` 0.4.0, and it is **nullable**
218
+ precisely so existing rows survive the upgrade. A single-table root is queried
219
+ without a discriminator filter, so rows written before the upgrade stay readable
220
+ through the built-in class. They are *not* visible to an override, for the same
221
+ reason described in section 5 — backfill them if you need them:
222
+
223
+ ```sql
224
+ UPDATE warehouse_maps SET "entityName" = 'YourMapEntity' WHERE "entityName" IS NULL;
225
+ ```
226
+
227
+ The other five tables have carried a discriminator since long before this
228
+ feature, so only `warehouse_maps` needs the column added. If you run migrations
229
+ rather than `synchronize`, generate one for it.