@rytass/wms-module-graphql 0.8.0 → 0.10.0

package/README.md

@@ -9,7 +9,7 @@ Pair with [`@rytass/wms-module-core`](https://www.npmjs.com/package/@rytass/wms-
 ```bash
 yarn add @rytass/wms-module-graphql @rytass/wms-module-core
 # peer deps
-yarn add @nestjs/common @nestjs/graphql @nestjs/apollo @apollo/server graphql dataloader reflect-metadata rxjs
+yarn add @nestjs/common @nestjs/graphql @nestjs/apollo @apollo/server @as-integrations/express5 graphql reflect-metadata rxjs @rytass/wms-base-nestjs-module
 ```
 
 ## Quick start
@@ -110,9 +110,99 @@ 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. Twelve operations
+(`inventory-count-order:{read,read-items,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.
+- **The sheet has its own query.** `inventoryCountOrderItems` paginates and filters the
+  lines (料號 / 物料說明 / 批號 / 儲位 / 載具 as ILIKE; 供應商 / 客戶 / 銷售訂單號碼 / 銷售訂單項次
+  exactly; plus `onlyVariance`). A field resolver cannot take a page or a filter, and a
+  count covering an aisle runs to thousands of lines.
+- **`startInventoryCount` snapshots eight attributes per line** — `held`, `inShipment`,
+  `inspectionResult`, `transferId`, `vendorId`, `customerId`, `saleId`, `saleSerialId` —
+  so the sheet keeps showing the world the variance is measured against, not today's.
+
+### ⚠️ 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/adapters/event-emitter.cjs.js

@@ -0,0 +1,43 @@
+'use strict';
+
+var eventEmitter = require('@nestjs/event-emitter');
+var wmsModuleCore = require('@rytass/wms-module-core');
+
+/**
+ * Bridges WMS domain events onto `@nestjs/event-emitter`'s `EventEmitter2`, so
+ * consumers can subscribe with `@OnEvent('wms.<event-name>')` instead of (or in
+ * addition to) the typed `afterListeners`.
+ *
+ * Pass this into `WmsModuleGraphqlModule.forRootAsync({ eventEmitterBridge })`.
+ * Importing this module is the only place `@nestjs/event-emitter` is referenced,
+ * keeping it an entirely optional peer dependency — the core graphql module
+ * never imports it.
+ *
+ * Prerequisite: register `EventEmitterModule.forRoot()` in your app so an
+ * `EventEmitter2` instance is available for injection.
+ *
+ * @example
+ * ```ts
+ * import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+ *
+ * WmsModuleGraphqlModule.forRootAsync({
+ *   ...coreOptions,
+ *   eventEmitterBridge: wmsEventEmitterBridgeProvider,
+ * });
+ *
+ * // elsewhere
+ * @OnEvent('wms.stock.allocated')
+ * handle(payload: WmsStockEventPayload) { ... }
+ * ```
+ */
+const wmsEventEmitterBridgeProvider = {
+    provide: wmsModuleCore.WMS_EVENT_EMITTER_BRIDGE,
+    useFactory: (emitter) => ({
+        forward: (event) => {
+            emitter.emit(`wms.${event.name}`, event.payload);
+        },
+    }),
+    inject: [eventEmitter.EventEmitter2],
+};
+
+exports.wmsEventEmitterBridgeProvider = wmsEventEmitterBridgeProvider;

package/adapters/member-base.cjs.js

@@ -0,0 +1,66 @@
+'use strict';
+
+var graphql = require('@nestjs/graphql');
+
+const extractRequest = (context) => {
+    const gqlContext = graphql.GqlExecutionContext.create(context).getContext();
+    return gqlContext?.req;
+};
+/**
+ * Builds a {@link WmsAuthChecker} that authorizes WMS operations against
+ * `@rytass/member-base-nestjs-module`'s Casbin setup.
+ *
+ * It reuses everything the host's global `CasbinGuard` already prepared on the
+ * request — the verified `payload`, the `enforcer`, and even the consumer's
+ * (possibly customized) `casbinPermissionChecker`. WMS therefore enforces with
+ * the *exact same* policy engine and rules as the host's own resolvers, with no
+ * member-base import on the WMS side.
+ *
+ * Prerequisite: register `MemberBaseModule` with its global guard enabled
+ * (the default), and expose the request on the GraphQL context as `req`
+ * (Apollo's default).
+ */
+const createMemberBaseWmsAuthChecker = (options) => {
+    return async (context, requirement) => {
+        const request = extractRequest(context);
+        // No verified member → unauthenticated. CasbinGuard sets `payload` to
+        // undefined when the token is missing or invalid.
+        if (!request?.payload) {
+            return false;
+        }
+        // The enforcer / checker are injected by CasbinGuard. Their absence means
+        // the host did not enable the global guard — fail closed rather than
+        // silently allowing everything.
+        if (!request.enforcer || !request.casbinPermissionChecker) {
+            return false;
+        }
+        const actions = options.map(requirement);
+        if (actions.length === 0) {
+            return false;
+        }
+        return request.casbinPermissionChecker({
+            enforcer: request.enforcer,
+            payload: request.payload,
+            actions,
+        });
+    };
+};
+/**
+ * A {@link WmsActorExtractor} for `@rytass/member-base-nestjs-module`. Reads the
+ * verified JWT payload that `CasbinGuard` attaches to the request and surfaces it
+ * as the event/hook `actor`. Returns `null` for unauthenticated requests.
+ *
+ * Pass to `WmsModuleGraphqlModule.forRootAsync({ actorExtractor })` so every
+ * operation event and before-hook carries `{ id, domain }`. Imports nothing from
+ * member-base — it only reads the runtime request fields.
+ */
+const memberBaseActorExtractor = (context) => {
+    const payload = extractRequest(context)?.payload;
+    if (!payload?.id) {
+        return null;
+    }
+    return { id: payload.id, domain: payload.domain, raw: payload };
+};
+
+exports.createMemberBaseWmsAuthChecker = createMemberBaseWmsAuthChecker;
+exports.memberBaseActorExtractor = memberBaseActorExtractor;

package/docs/api-reference.md

@@ -71,6 +71,14 @@ static forRootAsync(
 
 同樣每個都有 Symbol + EntityClass 雙匯出，共 37 個：
 
+**盤點單 (Inventory Count Order)**
+- `InventoryCountOrderEntity` / `InventoryCountOrderEntityClass` — 盤點單主檔（`countDate` 為盤差記帳基準日）
+- `InventoryCountOrderLocationEntity` / `InventoryCountOrderLocationEntityClass` — 盤點範圍，已展開至所有下層儲位（`isRoot` 標示使用者實際選的節點）
+- `InventoryCountOrderItemEntity` / `InventoryCountOrderItemEntityClass` — 盤點單身（`isAddition` 標示盤盈新增列）。
+  開始盤點時另外快照 8 個當下屬性：`held`、`inShipment`、`inspectionResult`、`transferId`、`vendorId`、`customerId`、`saleId`、`saleSerialId`
+- `InventoryCountOrderChangeEntity` / `InventoryCountOrderChangeEntityClass` — 盤差異動（正=盤盈、負=盤虧）
+- 來源: `lib/models/extensions/inventory-count-order/`
+
 **入庫訂單 (Receive Inventory Order)**
 - `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
 - `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
@@ -171,6 +179,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`, `findItems`, `create`, `update`, `start`, `count`, `addItem`, `removeItem`, `reset`, `cancel`, `settle` | 盤點單管理。`start` 會鎖定盤點範圍內的儲位，`settle` 是唯一會改動庫存的方法。`findItems` 是單身的分頁查詢 | `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 +271,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' | /* …59 項… */;
+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,6 +341,12 @@ 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.8.0（需 wms-base-nestjs-module >= 0.4.0）：
   //   WMSBaseModuleOptions 的六個 entity 選項（material / batch / location /
@@ -322,6 +358,8 @@ static forRootAsync(
 
 > **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 +493,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 +628,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`, `inventoryCountOrderItems` | `InventoryCountOrders`, `InventoryCountOrderDto`, `InventoryCountOrderItems` | `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 +647,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` |
@@ -660,6 +736,9 @@ WmsModuleGraphqlModule.forRootAsync({
 
 **庫存**
 - `FindStockArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-stock.args.ts`
+  - `materialKey` / `batchKey` / `locationKey` / `loaderKey` 為 ILIKE 模糊比對。
+  - `vendorId` / `customerId` / `saleId` / `saleSerialId` 取自批號，為**完全比對**：它們是上游系統的識別碼，
+    模糊比對會讓 `SO-1` 撈到 `SO-10`。四支 stock query（`stocks`、`stocksGroupedByMaterial`、`aggregatedStocks`、`changeLogs`）皆適用。
 - `DateRangeArgs` (`@InputType`) — 來源: `lib/inputs/date-range.args.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`,

package/docs/integration-guide.md

@@ -348,23 +348,37 @@ The `DEFAULT` location/loader/loaderType returned by the second query was seeded
 
 ### 4.6 Version compatibility matrix
 
-Tested combinations as of 0.1.2:
-
-| Package                          | Tested version          | Notes                                                              |
-|----------------------------------|-------------------------|--------------------------------------------------------------------|
-| NestJS (`@nestjs/*`)             | 11.x                    | 10.x untested; some Express-5-related APIs differ                  |
-| `@nestjs/graphql`                | 13.x                    | Required for `@nestjs/apollo@13`                                   |
-| `@nestjs/apollo`                 | 13.0.x – 13.1.x         | 13.2+ requires @apollo/server@^5 which breaks lib's v4 plugin usage |
-| `@apollo/server`                 | 4.x                     | v5 is breaking; not supported                                      |
-| `@as-integrations/express5`      | 1.x                     | Required runtime peer                                              |
-| TypeORM                          | 0.3.x                   | 0.2.x not supported (different DataSource API)                     |
-| PostgreSQL                       | 14+                     | Native dialect                                                     |
-| `graphql`                        | 16.x                    | 15.x untested                                                      |
-| Node.js                          | 20 LTS or 22            | 18 deprecated, 24 untested                                         |
-| Next.js                          | 15.x Pages Router       | App Router unsupported (see §13.11)                                |
-| React                            | 19.x                    | 18.x likely works but untested                                     |
-| `@mezzanine-ui/react`            | 1.3.x                   | Earlier versions untested                                          |
-| `nuqs`                           | 2.x (Pages adapter)     | App Router adapter untested (see §13.11)                           |
+Two different questions, so two columns. **Accepted** is what the published
+`peerDependencies` allow — a version outside it fails to install. **Tested** is the
+combination CI and the integration suite actually run against; anything else is
+accepted because nothing in the lib's use of that package is known to break, not
+because it was exercised.
+
+| Package                     | Accepted (peer range)     | Tested            | Notes                                                                       |
+|-----------------------------|---------------------------|-------------------|-----------------------------------------------------------------------------|
+| `@nestjs/common` / `core`   | 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 |
+| `@nestjs/graphql`           | 13.x                      | 13.4.5            | 14.x requires NestJS 12 (ESM-only)                                          |
+| `@nestjs/apollo`            | 13.x                      | 13.4.5            | The lib itself imports neither `@nestjs/apollo` nor `@apollo/server`; the peer records that a driver is required |
+| `@apollo/server`            | not a peer                | 5.5.1             | Chosen by your driver, not by this package                                   |
+| `@as-integrations/express5` | 1.x                       | 1.1.2             | Required runtime peer of the Express driver                                  |
+| `graphql`                   | 16.x                      | 16.12.0           | 17.x is blocked upstream — `@apollo/server@5` still peers `^16.11.0`         |
+| `rxjs`                      | 7.x                       | 7.8.x             | One import (the mutation interceptor)                                        |
+| `@nestjs/event-emitter`     | 2.x – 3.x (optional)      | 3.1.0             | The next release is 12.x, which is ESM-only                                  |
+| `@rytass/wms-base-nestjs-module` | 0.4.x                | 0.4.0             | Imported directly by this package (the warehouse-map mutation and the location resolver) and shared with `@rytass/wms-module-core`. Declared as a peer since 0.10.0 so both see the same copy |
+| TypeORM                     | 0.3.x                     | 0.3.28            | 0.2.x not supported (different DataSource API)                              |
+| PostgreSQL                  | —                         | 14+               | Native dialect                                                              |
+| Node.js                     | —                         | 20 LTS / 22       | 18 deprecated, 24 untested                                                  |
+| Next.js                     | 15.x – 16.x               | 15.5.x Pages      | Only `next/router` and `next/navigation` are used; App Router unsupported (see §13.11) |
+| React / React DOM           | 18.x – 19.x               | 19.2.x            | No React-19-only API is used, and `@mezzanine-ui/react` peers `>=18`        |
+| `@mezzanine-ui/react`       | 1.x                       | 1.4.1             | `@mezzanine-ui/system` is required — 45 of the lib's SCSS files `@use` it   |
+| `nuqs`                      | 2.x                       | 2.8.x             | Pages adapter; App Router adapter untested (see §13.11)                     |
+
+> **Why `@apollo/server` v5 is fine.** An earlier release pinned `@nestjs/apollo` to
+> `>=13.0.0 <13.2.0`, on the grounds that 13.2+ moved to `@apollo/server@^5` and "the lib
+> uses v4 plugin APIs". That was wrong: the only `ApolloServerPluginLandingPageLocalDefault`
+> usage lives in this repo's own `apps/api`, never in the published package, which imports
+> nothing from `@apollo/server` at all. The pin excluded the very combination the test suite
+> runs on, so it has been widened back to `^13.0.0`.
 
 ---