@rytass/wms-module-graphql 0.7.0 → 0.9.0

package/README.md

@@ -62,21 +62,27 @@ You register a **single** `GraphQLModule.forRootAsync(...)` of your own, mix you
 
 `WmsModuleGraphqlModule` internally wires `WmsModuleCoreModule.forRootAsync` so you do not need to import the core module separately when using this package.
 
-## Custom material entity
+## Custom entities
 
-`materialEntity` is an ordinary `WMSBaseModuleOptions` field that reaches all the way down, so a downstream project's own item master can *be* the WMS material master — every resolver's `material` DataLoader resolves against it too:
+Every entity option `WMSBaseModuleOptions` exposes reaches all the way down, so a downstream project's own tables can *be* the WMS tables — every resolver's DataLoader resolves against them too:
 
 ```ts
 WmsModuleGraphqlModule.forRootAsync({
-  // a @ChildEntity() of MaterialEntityClass
-  useFactory: async () => ({ materialEntity: ItemMasterEntity }),
+  useFactory: async () => ({
+    materialEntity: ItemMasterEntity, // a @ChildEntity() of MaterialEntityClass
+    batchEntity: LotEntity,
+    locationEntity: BinEntity,
+    stockEntity: LedgerEntryEntity,
+    orderEntity: MovementEntity,
+    warehouseMapEntity: FloorPlanEntity,
+  }),
   defaultLoaderSerialId: 'DEFAULT',
   defaultLoaderTypeKey: 'DEFAULT',
   defaultLocationKey: 'DEFAULT',
 });
 ```
 
-Register the entity with TypeORM yourself (`TypeOrmModule.forFeature([ItemMasterEntity])`); the module checks at startup and refuses to boot if it is missing. Requires `@rytass/wms-base-nestjs-module` >= 0.3.0. See [`@rytass/wms-module-core`'s custom-entities guide](https://github.com/Rytass/WMS-Module/blob/main/libs/core/docs/custom-entities.md) for the single-table-inheritance caveats and which other entity options are not honoured yet.
+Override as few or as many as you like. Register them with TypeORM yourself (`TypeOrmModule.forFeature([...])`); the module checks at startup and refuses to boot if any is missing. Requires `@rytass/wms-base-nestjs-module` >= 0.4.0. See [`@rytass/wms-module-core`'s custom-entities guide](https://github.com/Rytass/WMS-Module/blob/main/libs/core/docs/custom-entities.md) for the single-table-inheritance caveats.
 
 ## Authorization
 
@@ -104,9 +110,91 @@ The member-base adapter reuses everything `CasbinGuard` already put on the reque
 
 ➡️ **Full design & recipes: [`docs/authorization.md`](./docs/authorization.md)** (the problem, execution order, member-base / custom-JWT / no-guard recipes, the single coupling point, public API, FAQ).
 
+## Turning operations off per deployment
+
+`authChecker` **refuses** an operation; these options stop it being **registered at all**.
+The difference matters once someone reads the schema: a refused mutation still appears in
+introspection, in your frontend's codegen and in a security review, as a mutation that is
+guaranteed to fail.
+
+```ts
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+
+  // deny-list — these never enter the schema
+  disabledOperations: ['quality-inspection-order:inspect', 'material:create'],
+
+  // or an allow-list instead (the two are mutually exclusive; passing both throws)
+  // enabledOperations: ['material:read', 'stock:read'],
+
+  // escape hatch by GraphQL field name, for when a requirement is too coarse
+  disabledFields: ['availableLoaders'],
+});
+```
+
+Names are the same `` `${resource}:${action}` `` strings `@WmsOperation` declares and your
+`authChecker` receives, exported as the `WmsOperationName` union and the
+`WMS_OPERATION_NAMES` array so you can iterate or diff them.
+
+Two things to know before you use it:
+
+- **A name is not one field.** Several queries share a requirement — `loader:read` covers
+  6 fields, `stock:read` 5, `material:read` and `loader:create` 3 each. Disabling a name
+  disables every field carrying it; use `disabledFields` when you need one.
+- **Disabling a resolver does not disable the domain.** The services stay injectable, so a
+  host that owns that step of the workflow itself can still drive
+  `ReceiveInventoryOrderService` (or any other) directly. That is the intended pattern.
+
+Because the switches mutate process-global registration state, a process may register
+`WmsModuleGraphqlModule` **once**.
+
+## Inventory counting
+
+Compare the ledger against what is physically on the shelf, then adjust the ledger to
+match. Eleven operations (`inventory-count-order:{read,create,update,start,count,add-item,remove-item,reset,cancel,settle}`)
+back the flow:
+
+```
+建立盤點 ──▶ PENDING ──開始盤點──▶ COUNTING ──執行盤差──▶ COMPLETED
+                │                    │
+                └───── 取消盤點 ─────┴────────▶ CANCELLED
+```
+
+- **Scope is by location, expanded downwards.** Counting an aisle counts every shelf under
+  it; `createInventoryCountOrder` stores the expansion.
+- **Counting never moves stock between locations.** A line in the wrong place is a
+  transfer, not a count — `transfer-order:create` already does that. Counting only ever
+  adjusts quantity in place.
+- **Nothing touches stock until `settleInventoryCount`.** Counted quantities are working
+  notes; settlement runs in one transaction and writes the difference as `+`/`-` rows,
+  which surface as `stock.count-gained` / `stock.count-lost`.
+- **Uncounted lines are left alone.** "Not counted" is not "counted as zero".
+- **Surpluses may name a batch that does not exist yet**; it is created during settlement.
+- **`countDate` is the business date.** The variance is reported under the date the count
+  was created for, not the day settlement happened to run. `createdAt` keeps the real
+  wall-clock time.
+
+### ⚠️ Starting a count locks its locations
+
+This is the one part that changes the behaviour of operations you already use. While an
+order is `COUNTING`, **any** stock movement touching a location in its scope is refused
+with a `409 Conflict` naming the count:
+
+```
+Location <id> is locked by inventory count order IC2508300001;
+finish or cancel that count before moving this stock.
+```
+
+The check sits on the insert of every `*_order_change` row — the same choke point the
+stock events use — so it covers resolvers **and** direct service calls, including your own
+integration code. Without it the book snapshot the variance is measured against would go
+stale and settlement would silently write off somebody else's legitimate movement.
+
+Settling or cancelling the count releases the lock.
+
 ## Events & Hooks
 
-Intervene in and get notified about mutations. Every root mutation carries a typed **operation event** (`material.created`, `ship-inventory-order.shipped`, …) and fans out **stock domain events** (`stock.allocated`, `stock.shipped`, …) driven by the `ChangeType` state machine. Wire two opt-in hook points via `forRootAsync`:
+Intervene in and get notified about mutations. Every root mutation carries a typed **operation event** (`material.created`, `ship-inventory-order.shipped`, `inventory-count-order.settled`, …) and fans out **stock domain events** (`stock.allocated`, `stock.shipped`, `stock.count-gained`, …) driven by the `ChangeType` state machine. Wire two opt-in hook points via `forRootAsync`:
 
 - **`beforeHooks`** run before any DB work — **throw to veto** the mutation (zero side effects).
 - **`afterListeners`** run **after the outermost transaction commits** — never notified about rolled-back changes.

package/docs/api-reference.md

@@ -71,6 +71,13 @@ static forRootAsync(
 
 同樣每個都有 Symbol + EntityClass 雙匯出，共 37 個：
 
+**盤點單 (Inventory Count Order)**
+- `InventoryCountOrderEntity` / `InventoryCountOrderEntityClass` — 盤點單主檔（`countDate` 為盤差記帳基準日）
+- `InventoryCountOrderLocationEntity` / `InventoryCountOrderLocationEntityClass` — 盤點範圍，已展開至所有下層儲位（`isRoot` 標示使用者實際選的節點）
+- `InventoryCountOrderItemEntity` / `InventoryCountOrderItemEntityClass` — 盤點單身（`isAddition` 標示盤盈新增列）
+- `InventoryCountOrderChangeEntity` / `InventoryCountOrderChangeEntityClass` — 盤差異動（正=盤盈、負=盤虧）
+- 來源: `lib/models/extensions/inventory-count-order/`
+
 **入庫訂單 (Receive Inventory Order)**
 - `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
 - `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
@@ -171,6 +178,7 @@ static forRootAsync(
 | `MergeBatchOrderService<T>` | `merge` | 批號合併 | `lib/services/merge-batch-order.service.ts` |
 | `ReclassifyInventoryOrderService<T>` | `reclassify` | 庫存轉料號 | `lib/services/reclassify-inventory-order.service.ts` |
 | `ScrapeService<T>` | `scrape` | 庫存報廢 | `lib/services/scrape.service.ts` |
+| `InventoryCountOrderService<T>` | `findMany`, `findOne`, `create`, `update`, `start`, `count`, `addItem`, `removeItem`, `reset`, `cancel`, `settle` | 盤點單管理。`start` 會鎖定盤點範圍內的儲位，`settle` 是唯一會改動庫存的方法 | `lib/services/inventory-count-order.service.ts` |
 | `QualityInspectionOrderService<T>` | `inspect` | 品質檢驗 | `lib/services/quality-inspection-order.service.ts` |
 | `SaleOrderService` | （DataSource 直接操作） | 銷售訂單查詢 | `lib/services/sale-order.service.ts` |
 | `HelperService` | `getSeq` | 序號產生工具 | `lib/services/helper.service.ts` |
@@ -262,11 +270,32 @@ enum ChangeType {
   RECEIVED, IN_SHIPMENT, SHIPPED, IN_TRANSFER, TRANSFERRED,
   VENDOR_TRANSFERRED, VENDOR_RETURNED, HELD, RELEASED,
   CUSTOMER_HELD, CUSTOMER_RETURNED, SPLITTED, MERGED,
-  ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED
+  ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED,
+  COUNT_GAINED, COUNT_LOST
 }
 ```
 來源: `lib/constants/stock-status.ts`
 
+### `InventoryCountStatus` (enum)
+```ts
+enum InventoryCountStatus { PENDING, COUNTING, COMPLETED, CANCELLED }
+```
+盤點單狀態：尚未執行 / 盤點中 / 已完成 / 已取消。只有 `COUNTING` 接受盤點數量，也只有
+`COUNTING` 會鎖定範圍內儲位；`COMPLETED` 只能由執行盤差達成。
+來源: `lib/constants/inventory-count-status.ts`
+
+### `WmsOperationName` (type) / `WMS_OPERATION_NAMES` (const)
+```ts
+type WmsOperationName = 'material:read' | 'material:create' | /* …58 項… */;
+const WMS_OPERATION_NAMES: readonly WmsOperationName[];
+```
+本套件所有 root operation 的 `` `${resource}:${action}` `` 名稱。同一組字串有三個用途：
+`authChecker` 收到的 requirement、`@rytass/wms-module-graphql` 的
+`enabledOperations` / `disabledOperations`、以及
+`@rytass/wms-module-react` 的 `INVENTORY_ACTION_OPERATIONS` 對照表。
+**注意名稱不等於欄位**：多支 query 共用同一組 requirement（`loader:read` 對應 6 支）。
+來源: `lib/constants/operations.ts`
+
 ### `ReceiveInventoryOrderStatus` (enum)
 ```ts
 enum ReceiveInventoryOrderStatus { PENDING, PARTIAL_RECEIVED, RECEIVED, REMOVED }
@@ -311,17 +340,25 @@ static forRootAsync(
   //     defaultLocationKey: string     — 預設儲存位置 key
   // + WmsAuthModuleOptions:
   //     authChecker?: WmsAuthChecker   — 選填；resolver 授權委派函式（見 Authorization）
+  // + WmsOperationRegistrationOptions（since 0.9.0）:
+  //     enabledOperations?:  readonly WmsOperationName[]  — 白名單，只註冊列出的 operation
+  //     disabledOperations?: readonly WmsOperationName[]  — 黑名單；與白名單互斥，同時給會 throw
+  //     disabledFields?:     readonly string[]            — 以 GraphQL 欄位名精準停用單一欄位
+  //   被停用者「不會進 schema」（introspection 與 SDL 皆無），
+  //   但對應的 service 仍可注入 — 宿主可繼續直呼。詳見下方 Operation registration。
   //
-  // since 0.7.0（需 wms-base-nestjs-module >= 0.3.0）：
-  //   WMSBaseModuleOptions.materialEntity 會一路作用到所有 resolver 的
-  //   material DataLoader。傳入 MaterialEntityClass 的 @ChildEntity() 即可，
-  //   forRoot 與 async factory 皆支援；entity 需自行註冊給 TypeORM。
-  //   詳見 core 的 docs/custom-entities.md。
+  // since 0.8.0（需 wms-base-nestjs-module >= 0.4.0）：
+  //   WMSBaseModuleOptions 的六個 entity 選項（material / batch / location /
+  //   stock / order / warehouseMap）會一路作用到所有 resolver 的 DataLoader。
+  //   傳入對應 class 的 @ChildEntity() 即可，forRoot 與 async factory 皆支援；
+  //   entity 需自行註冊給 TypeORM。詳見 core 的 docs/custom-entities.md。
 ): DynamicModule
 ```
 
 > **Breaking from 0.2.x**: 0.2.0 took a second `gqlOptions` argument and started Apollo Server internally; 0.3.0 dropped it. Consumers now own `GraphQLModule.forRootAsync(...)` and the GraphQL context factory. Use `createWmsLoaders(loaderService)` inside `context` to provide the WMS DataLoader trio (see below).
 
+> **Operation registration (`enabledOperations` / `disabledOperations` / `disabledFields`)**: optional. Omit them and every operation is registered as before. They mutate process-global registration state, so a process may register `WmsModuleGraphqlModule` **once**.
+
 > **Authorization (`authChecker`)**: optional. Omit it and the module stays fully permissive. Supply it to authorize every WMS root op against your permission system — see the dedicated [**Authorization**](#authorization) section below and [`docs/authorization.md`](./authorization.md).
 
 ### `LoaderService` (`@Injectable()`, since 0.3.0 publicly exported)
@@ -455,6 +492,42 @@ The adapter imports nothing from member-base — it reads the `payload` / `enfor
 
 ---
 
+## Operation registration
+
+以部署為單位決定「哪些 operation 根本不進 schema」。`authChecker` 是**拒絕執行**，
+這組選項是**不註冊**——差別在於被拒絕的 mutation 仍會出現在 introspection、前端 codegen
+與安全稽核清單裡，看起來像一支保證會失敗的 API。
+
+### Root exports (`@rytass/wms-module-graphql`)
+
+| 匯出 | 種類 | 說明 |
+|---|---|---|
+| `WmsOperationRegistrationOptions` | type | `enabledOperations` / `disabledOperations` / `disabledFields` 三個選填欄位 |
+| `pruneDisabledOperations(resolverClasses, options)` | function | `forRootAsync` 內部使用；公開匯出供進階情境（自組 provider 清單）使用 |
+| `PrunedOperations` | type | `{ queries, mutations }` — 實際被移除的欄位名 |
+| `WmsOperationName` | type | 從 `@rytass/wms-module-core` 轉出 |
+| `WMS_OPERATION_NAMES` | const | 從 `@rytass/wms-module-core` 轉出 |
+
+### 語意
+
+- **名稱不等於欄位。** 多支 query 共用同一組 requirement（`loader:read` 6 支、
+  `stock:read` 5 支、`material:read` 與 `loader:create` 各 3 支），停用名稱會一次移除全部；
+  需要更細的粒度時用 `disabledFields`。
+- **停用 resolver 不會停用 domain。** service 照常可注入，這是刻意的：自有流程的宿主
+  仍能直呼 `ReceiveInventoryOrderService` 等服務。
+- **`@ResolveField` 不受影響**——它們只能透過已註冊的 root 欄位抵達。
+
+### 實作備註
+
+resolver metadata 在 `@nestjs/graphql` 是 **lazy** 的（`@Query()` 只登記 thunk，真正寫入
+要等 schema build），所以停用同時做兩件事：`forRootAsync` 當下刪掉 resolver prototype 上
+的方法（`ResolversExplorerService` 掃 prototype，且早於 metadata 載入），並包裝
+`TypeMetadataStorage.addQueryMetadata` / `addMutationMetadata` 擋掉該筆。兩者必須成對，
+否則 schema 會留下沒有 resolver 的死欄位，或 `makeExecutableSchema` 因 resolver 與
+typeDefs 不符而拒絕整份 schema。
+
+---
+
 ## Events & Hooks
 
 Opt-in `beforeHooks` (veto) and post-commit `afterListeners` for every mutation. Each root mutation carries `@WmsMutationEvent({ event })` (already applied); a per-mutation interceptor runs the before-hook, opens an `AsyncLocalStorage` dispatch scope, and flushes collected events after the transaction commits. Stock domain events are collected centrally by a TypeORM subscriber on `*_order_change` inserts. Full design & the complete event list: [`docs/events.md`](./events.md).
@@ -554,6 +627,7 @@ WmsModuleGraphqlModule.forRootAsync({
 | `MaterialQuery` | `material`, `materials` | `MaterialDto`, `Materials` | `lib/queries/material.query.ts` |
 | `StockQuery` | `stock`, `stocks`, `stocksGroupedByMaterial`, `aggregatedStocks`, `changeLogs` | `StockDto`, `Stocks`, `Materials`, `AggregatedStocks`, `ChangeLogs` | `lib/queries/stock.query.ts` |
 | `BatchQuery` | `batches` | `Batches` | `lib/queries/batch.query.ts` |
+| `InventoryCountOrderQuery` | `inventoryCountOrders`, `inventoryCountOrder` | `InventoryCountOrders`, `InventoryCountOrderDto` | `lib/queries/inventory-count-order.query.ts` |
 | `LocationQuery` | `location`, `locations` | `LocationDto`, `Locations` | `lib/queries/location.query.ts` |
 | `ReceiveInventoryOrderQuery` | `receiveInventoryOrder`, `receiveInventoryOrders` | `ReceiveInventoryOrderDto`, `ReceiveInventoryOrders` | `lib/queries/recieve-inventory-order.query.ts` |
 | `ShipInventoryOrderQuery` | `shipInventoryOrder`, `shipInventoryOrders` | `ShipInventoryOrderDto`, `ShipInventoryOrders` | `lib/queries/ship-inventory-order.query.ts` |
@@ -572,6 +646,7 @@ WmsModuleGraphqlModule.forRootAsync({
 | `LoaderMutation` | `createLoader`, `createBatchLoader`, `updateLoader`, `createLoaderType`（方法名未確認）, `updateLoaderType` | 載具與類型 | `lib/mutations/loader.mutation.ts` |
 | `LocationMutation` | `createLocation`, `updateLocation` | 庫位 | `lib/mutations/location.mutation.ts` |
 | `MaterialMutation` | `createMaterial`, `updateMaterial` | 料號 | `lib/mutations/material.mutation.ts` |
+| `InventoryCountOrderMutation` | `createInventoryCountOrder`, `updateInventoryCountOrder`, `startInventoryCount`, `countInventory`, `addInventoryCountItem`, `removeInventoryCountItem`, `resetInventoryCount`, `cancelInventoryCount`, `settleInventoryCount` | 盤點單。`startInventoryCount` 會鎖定範圍內儲位；`settleInventoryCount` 是唯一會改動庫存的一支 | `lib/mutations/inventory-count-order.mutation.ts` |
 | `ReceiveInventoryOrderMutation` | `createReceiveInventoryOrder`, `updateReceiveInventoryOrder`, `receive` | 入庫單 | `lib/mutations/receive-inventory-order.mutation.ts` |
 | `ShipInventoryOrderMutation` | `createShipInventoryOrder`, `updateShipInventoryOrder`, `ship`, `cancelShip` | 出庫單 | `lib/mutations/ship-inventory-order.mutation.ts` |
 | `TransferOrderMutation` | `createTransferOrder`, `updateTransferOrder`, `transfer`, `cancelTransfer` | 調撥單 | `lib/mutations/transfer-order.mutation.ts` |

package/docs/events.md

@@ -215,7 +215,7 @@ and the bridge can be used together — both fire.
 
 ## 5. Complete event list
 
-### Operation events (38) — `<domain>.<past-tense-action>`
+### Operation events (45) — `<domain>.<past-tense-action>`
 
 The **v2 `result` type** column shows the concrete type subscribers receive via
 `WmsOperationResultMap`. Events marked ⚠️ **boolean** are the 9 action mutations
@@ -269,24 +269,43 @@ events they fan out (see §3.1).
 > `quantityChanged`. So a mutation emits a stock event only on the code paths
 > that actually write a change row (e.g. an `update*` only when it adds items).
 >
+
+Inventory counting adds seven. Only `settled` moves stock; the rest record progress
+through the count, which is what makes them useful for an audit trail of who counted
+what and when.
+
+| Event                                | Mutation                   | v2 `result` type                     | Fans out to stock event                     |
+|--------------------------------------|----------------------------|--------------------------------------|---------------------------------------------|
+| `inventory-count-order.created`      | createInventoryCountOrder  | `InventoryCountOrderDto`             | —                                           |
+| `inventory-count-order.updated`      | updateInventoryCountOrder / addInventoryCountItem / removeInventoryCountItem | `InventoryCountOrderDto` \| `InventoryCountOrderItemDto` | —                        |
+| `inventory-count-order.started`      | startInventoryCount        | `InventoryCountOrderDto`             | — (snapshots the ledger, locks the scope)   |
+| `inventory-count-order.counted`      | countInventory             | `InventoryCountOrderDto`             | —                                           |
+| `inventory-count-order.reset`        | resetInventoryCount        | `InventoryCountOrderDto`             | —                                           |
+| `inventory-count-order.cancelled`    | cancelInventoryCount       | `InventoryCountOrderDto`             | — (releases the lock)                       |
+| `inventory-count-order.settled`      | settleInventoryCount       | `InventoryCountOrderDto`             | `stock.count-gained` / `stock.count-lost`   |
+
 > The "v2 `result` type" column refers to the typed overlay provided by
 > `WmsOperationResultMap` (exported from `@rytass/wms-module-graphql`). In v1
 > `result` is typed `unknown`; consumer code using the typed maps gets the
 > concrete DTO automatically.
 
-### Stock domain events (18) — `stock.<change-type>`
+### Stock domain events (20) — `stock.<change-type>`
 
 `stock.received`, `stock.in-shipment`, `stock.shipped`, `stock.in-transfer`,
 `stock.transferred`, `stock.vendor-transferred`, `stock.vendor-returned`,
 `stock.held`, `stock.released`, `stock.customer-held`,
 `stock.customer-returned`, `stock.splitted`, `stock.merged`, `stock.allocated`,
 `stock.deallocated`, `stock.reclassified`, `stock.scraped`,
-`stock.inspection-resolved`.
+`stock.count-gained`, `stock.count-lost`, `stock.inspection-resolved`.
 
-The first 17 map 1:1 to `ChangeType`. `stock.inspection-resolved` has no
+19 of them map 1:1 to `ChangeType`. `stock.inspection-resolved` has no
 `ChangeType` (quality inspection only flips the `inspectionResult` flag) and
 carries `changeType: null` plus `inspectionResult`.
 
+`stock.count-gained` / `stock.count-lost` are emitted only by
+`settleInventoryCount`, one per line whose counted quantity differed from the
+books — a line that matched writes no change row and therefore no event.
+
 A single operation can emit **several** stock events — one per `*_order_change`
 row written, i.e. one per affected item. Cancellations re-use the forward event
 with a negative `quantityDelta` (`cancelShip` -> `stock.shipped`,