@rytass/wms-module-graphql 0.3.0 → 0.5.0

package/docs/authorization.md

@@ -0,0 +1,349 @@
+# Authorization
+
+How `@rytass/wms-module-graphql` lets **you** authorize its resolvers with **your**
+permission system — without the library knowing anything about it, and without
+your global auth guard rejecting every WMS operation.
+
+- [1. The problem](#1-the-problem)
+- [2. The design](#2-the-design)
+- [3. Execution order — why it composes](#3-execution-order--why-it-composes)
+- [4. Recipe A — member-base / Casbin](#4-recipe-a--member-base--casbin)
+- [5. Recipe B — your own JWT / RBAC](#5-recipe-b--your-own-jwt--rbac)
+- [6. Recipe C — no global guard / fully open](#6-recipe-c--no-global-guard--fully-open)
+- [7. The single coupling point](#7-the-single-coupling-point)
+- [8. Public API](#8-public-api)
+- [9. FAQ & gotchas](#9-faq--gotchas)
+
+---
+
+## 1. The problem
+
+The library exposes ~66 root `@Query` / `@Mutation` operations. Like any
+publishable NestJS GraphQL module, it cannot know how *your* application
+authorizes requests — RBAC? ABAC? Casbin? JWT scopes? a custom session table?
+So historically its resolvers were **bare** (`@Query()` with no guard metadata).
+
+That collides badly with a **globally registered, deny-by-default guard**. The
+canonical example is the `CasbinGuard` that `@rytass/member-base-nestjs-module`
+registers as `APP_GUARD`:
+
+```
+Host App
+  APP_GUARD = CasbinGuard          <- one net over EVERY resolver in the schema
+        |
+        v
+  +------------------------------+
+  | compiled GraphQL schema      |
+  |  - your resolvers            |  carry @AllowActions -> authorized OK
+  |  - WMS resolvers (bare)      |  no metadata -> guard returns false -> ALL denied
+  +------------------------------+
+```
+
+`CasbinGuard` is white-list: a handler with no `@AllowActions` / `@Authenticated`
+/ `@IsPublic` metadata is **rejected**. WMS resolvers had none, so every WMS
+query and mutation came back *forbidden*. You could not fix it from the consumer
+side either — you do not own the WMS resolver classes, so you cannot decorate
+them.
+
+**Conclusion:** the library itself must participate in authorization, while
+staying ignorant of which auth system you use.
+
+---
+
+## 2. The design
+
+A host-neutral, opt-in authorization protocol with three moving parts, all
+shipped by the library:
+
+| Part | What it is | Who supplies it |
+|------|------------|-----------------|
+| `@WmsOperation({ resource, action })` | Method decorator on every WMS root op. Declares a **neutral** permission requirement (just two strings) and wires the guard. | Library (already applied) |
+| `WmsAuthGuard` | Route-level guard (NOT global) that reads the requirement and delegates the decision. | Library |
+| `authChecker` | Your function `(ctx, { resource, action }) => boolean`. Maps WMS's neutral requirement onto your real permission system. | **You**, via `forRootAsync` |
+
+```
+WMS resolver
+  |
+  +- @WmsOperation({ resource: 'material', action: 'read' })
+  |     |
+  |     +- stamps neutral metadata  ............ read by WmsAuthGuard
+  |     +- stamps a host-skip marker ........... tells your global guard to defer
+  |     +- @UseGuards(WmsAuthGuard) ............ the guard that actually enforces
+  |
+  v
+WmsAuthGuard.canActivate(ctx)
+  |
+  +- reads { resource, action } from the handler
+  +- calls YOUR authChecker(ctx, { resource, action })
+        |
+        v
+   true -> resolve   /   false -> ForbiddenError
+```
+
+Key properties:
+
+- **The library never imports your auth system.** It only knows two strings.
+- **`authChecker` is optional.** Omit it and the module stays fully permissive
+  (handy for local dev / demos) — identical to the pre-auth releases.
+- **`resource` / `action` are internal metadata**, not part of the GraphQL
+  schema. Refining them later is *not* a breaking change for GraphQL consumers.
+- The host-skip marker is what lets WMS coexist with your global guard — see §3.
+
+---
+
+## 3. Execution order — why it composes
+
+NestJS runs guards in the order **global -> controller -> route**. So a global
+`APP_GUARD` (your `CasbinGuard`) runs *before* WMS's route-level `WmsAuthGuard`.
+That is exactly why `@WmsOperation` stamps a host-skip marker: it makes the
+global guard *defer* on WMS operations so it never blanket-rejects them.
+
+```
+request
+  |
+  v  [1] APP_GUARD = CasbinGuard (global, runs first)
+  |        - verifies token, attaches payload/enforcer to the request
+  |        - sees host-skip marker (IS_ROUTE_PUBLIC) -> returns true (defers)
+  |
+  v  [2] @UseGuards(WmsAuthGuard) (route-level, runs next)
+  |        - reads { resource, action }
+  |        - calls your authChecker -> real allow/deny decision
+  |
+  v  resolver executes
+```
+
+With member-base specifically there is a bonus: before `CasbinGuard` defers on
+the skip marker, it has *already* attached the verified `payload`, the Casbin
+`enforcer`, and your `casbinPermissionChecker` to the request. The member-base
+adapter (§4) reuses those — so WMS enforces with the **exact same** policy
+engine and rules as your own resolvers.
+
+> Your global guard configuration does **not** change. You do not whitelist WMS
+> routes, you do not enumerate operations, you do not weaken your default-deny
+> posture. WMS makes itself transparent to the global guard and self-enforces.
+
+---
+
+## 4. Recipe A — member-base / Casbin
+
+The common case: you use `@rytass/member-base-nestjs-module` with its global
+`CasbinGuard`. Use the ready-made adapter from the dedicated subpath.
+
+```ts
+// app.module.ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+@Module({
+  imports: [
+    // ...MemberBaseModule.forRoot({ ... }) with its global guard enabled (default)...
+    WmsModuleGraphqlModule.forRootAsync({
+      // existing core options:
+      useFactory: async () => ({}),
+      defaultLoaderSerialId: 'DEFAULT',
+      defaultLoaderTypeKey: 'DEFAULT',
+      defaultLocationKey: 'DEFAULT',
+
+      // authorization:
+      authChecker: createMemberBaseWmsAuthChecker({
+        // Map WMS resource/action onto YOUR Casbin [subject, action] tuples.
+        // This is the one place your permission naming convention lives.
+        // Return several tuples to mean "allow if ANY passes" (OR semantics).
+        map: ({ resource, action }) => [[`wms:${resource}`, action]],
+        //   material + read -> enforce(memberId, domain, 'wms:material', 'read')
+      }),
+    }),
+    // ...your own GraphQLModule.forRootAsync (must expose `req` on context)...
+  ],
+})
+export class AppModule {}
+```
+
+What the adapter does, step by step:
+
+1. Pulls the request off the GraphQL `ExecutionContext`
+   (`GqlExecutionContext.create(ctx).getContext().req` — member-base's own
+   convention).
+2. Reads `request.payload` (the JWT member, attached by `CasbinGuard`). Missing
+   payload -> **deny** (unauthenticated).
+3. Reads `request.enforcer` and `request.casbinPermissionChecker` (also attached
+   by `CasbinGuard`). Missing -> **deny** (fail closed: the global guard was not
+   actually enabled).
+4. Runs `your map({ resource, action })` to get the Casbin tuples.
+5. Calls the **consumer's own** `casbinPermissionChecker({ enforcer, payload,
+   actions })` and returns its verdict.
+
+The adapter imports **nothing** from member-base — it relies only on the runtime
+contract `CasbinGuard` already established on the request. So member-base is not
+even a dependency of `@rytass/wms-module-graphql`.
+
+**Prerequisites**
+
+- Keep member-base's global guard enabled (`enableGlobalGuard: true`, the
+  default).
+- Your `GraphQLModule` context must expose the request as `req` (Apollo's
+  default): `context: ({ req }) => ({ ...createWmsLoaders(loaderService), req })`.
+
+**Permission grants.** Make sure your Casbin policy grants the mapped subjects.
+With the example `map` above, a warehouse operator role might be granted
+`wms:material:read`, `wms:receive-inventory-order:create`, etc. The full list of
+`resource` values mirrors the WMS domains (`material`, `loader`, `stock`,
+`location`, `unit`, `batch`, `warehouse-map`, `transfer-order`,
+`receive-inventory-order`, `ship-inventory-order`, `allocate-inventory-order`,
+`hold-inventory-order`, `reclassify-inventory-order`, `transfer-customer-order`,
+`transfer-vendor-order`, `sale-order`, `scrape-order`,
+`quality-inspection-order`). `action` is `read` for queries, and the leading
+verb (`create` / `update` / `delete` / `ship` / `hold` / `allocate` / `split` /
+`merge` / `transfer` / ...) for mutations.
+
+---
+
+## 5. Recipe B — your own JWT / RBAC
+
+`authChecker` is a plain function — you do not need Casbin or member-base. Read
+whatever you need off the `ExecutionContext` and decide.
+
+```ts
+import { GqlExecutionContext } from '@nestjs/graphql';
+import type { WmsAuthChecker } from '@rytass/wms-module-graphql';
+
+const myWmsAuthChecker: WmsAuthChecker = (ctx, { resource, action }) => {
+  const { req } = GqlExecutionContext.create(ctx).getContext<{ req: { user?: { scopes: string[] } } }>();
+  const user = req.user;
+
+  if (!user) return false;                                  // unauthenticated -> deny
+
+  // your own convention; e.g. scopes like "wms:material:read" or "wms:*"
+  return user.scopes.includes('wms:*')
+    || user.scopes.includes(`wms:${resource}:${action}`)
+    || user.scopes.includes(`wms:${resource}:*`);
+};
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  authChecker: myWmsAuthChecker,
+});
+```
+
+`authChecker` may be sync or async (return `Promise<boolean>`). Throwing also
+works — the exception propagates exactly like any guard rejection (use a
+`ForbiddenException` if you want a clean 403-style GraphQL error).
+
+If you *also* run a global deny-by-default guard that is **not** member-base, you
+must make it skip WMS routes too — see §7 to change the host-skip key.
+
+---
+
+## 6. Recipe C — no global guard / fully open
+
+- **No `authChecker`.** The module is permissive: `WmsAuthGuard` lets every
+  operation through. The host-skip marker is inert. Good for local dev, internal
+  tooling, or demos.
+
+  ```ts
+  WmsModuleGraphqlModule.forRootAsync({
+    useFactory: async () => ({}),
+    defaultLoaderSerialId: 'DEFAULT',
+    defaultLoaderTypeKey: 'DEFAULT',
+    defaultLocationKey: 'DEFAULT',
+    // no authChecker -> open
+  });
+  ```
+
+- **You guard your own resolvers explicitly** (`@UseGuards(...)` per resolver
+  instead of a global `APP_GUARD`). Then there is no net over WMS at all; the
+  skip marker does nothing and WMS still self-enforces through your
+  `authChecker` if you supply one.
+
+---
+
+## 7. The single coupling point
+
+`@WmsOperation` stamps a host-skip metadata key so your global guard defers. A
+global guard reads its skip key *statically* (at decoration time), so the key
+must be a fixed value baked into the decorator. The default matches
+member-base's:
+
+```ts
+// libs/graphql/src/lib/auth/host-skip.constant.ts
+export const HOST_SKIP_METADATA_KEY = 'IS_ROUTE_PUBLIC';
+```
+
+This is the **only** place WMS assumes anything about a specific host guard. If
+your global guard uses a different "public / skip" metadata key, change this one
+constant (when building from source) — nothing else moves. If you do not run a
+global guard, it is irrelevant.
+
+---
+
+## 8. Public API
+
+Exported from the package root (`@rytass/wms-module-graphql`):
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `WmsOperation(requirement)` | decorator | Annotate a WMS root op (already applied across the library). |
+| `WmsAuthGuard` | class | Route-level guard that delegates to `authChecker`. |
+| `WmsAuthChecker` | type | `(ctx: ExecutionContext, req: WmsOperationRequirement) => boolean \| Promise<boolean>` |
+| `WmsOperationRequirement` | type | `{ readonly resource: string; readonly action: string }` |
+| `WmsAuthModuleOptions` | type | `{ readonly authChecker?: WmsAuthChecker }` |
+| `WmsModuleGraphqlModuleAsyncOptions` | type | Core async options **+** `WmsAuthModuleOptions`. |
+| `WMS_AUTH_OPTIONS` | symbol | DI token holding the resolved auth options. |
+| `WMS_OPERATION_METADATA` | string | Reflector key carrying the requirement. |
+| `HOST_SKIP_METADATA_KEY` | string | The host-skip metadata key (default `'IS_ROUTE_PUBLIC'`). |
+
+Exported from the adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`):
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `createMemberBaseWmsAuthChecker(options)` | factory | Builds a `WmsAuthChecker` for member-base / Casbin. |
+| `MemberBaseWmsAuthCheckerOptions` | type | `{ readonly map: (req: WmsOperationRequirement) => CasbinAction[] }` |
+| `CasbinAction` | type | `[string, string]` — a `[subject, action]` tuple. |
+
+`forRootAsync` accepts the optional `authChecker` on its single options object:
+
+```ts
+static forRootAsync(options: WmsModuleGraphqlModuleAsyncOptions): DynamicModule;
+```
+
+---
+
+## 9. FAQ & gotchas
+
+**"Every WMS query/mutation is forbidden after I added member-base."**
+Your global `CasbinGuard` is rejecting bare resolvers. Upgrade to a WMS version
+that ships `@WmsOperation` (this protocol) and wire an `authChecker` per §4. You
+do not need to touch the global guard.
+
+**Does the GraphQL context need anything special?**
+Yes — expose the request as `req` on the context (Apollo's default). Both the
+member-base adapter and most custom checkers read `GqlExecutionContext.create(ctx).getContext().req`.
+
+**Is member-base a dependency now?**
+No. The adapter reads runtime fields the host's guard attaches to the request;
+it imports nothing from member-base. member-base is not in this package's
+`dependencies` or `peerDependencies`.
+
+**What about `@ResolveField` resolvers?**
+They are intentionally *not* annotated. A field resolver is only ever reached
+through a root `@Query`/`@Mutation` that already passed `WmsAuthGuard`, so
+authorizing the root op authorizes the whole selection. `WmsAuthGuard` returns
+`true` for any handler without a requirement.
+
+**Fail-open or fail-closed?**
+The library is permissive only when *you* opt out (no `authChecker`). When an
+`authChecker` is configured, missing identity / missing enforcer -> **deny**. The
+member-base adapter fails closed.
+
+**Can I change `resource`/`action` strings?**
+Yes, freely — they are internal metadata, never exposed in the GraphQL schema.
+Changing them only affects your `authChecker` / `map`, never your GraphQL
+clients.
+
+---
+
+See also: [Integration Guide §8.5](./integration-guide.md#85-backend-authorization-resolver-level)
+· [API Reference](./api-reference.md#rytasswms-module-graphql)

package/docs/events.md

@@ -0,0 +1,304 @@
+# Events & Hooks
+
+How a consumer **intervenes in** (vetoes) and **gets notified about** WMS
+mutations, with a host-neutral, opt-in API that mirrors the
+[authorization](./authorization.md) layer's wiring.
+
+- [1. What you get](#1-what-you-get)
+- [2. Architecture — post-commit guarantee](#2-architecture--post-commit-guarantee)
+- [3. Integration](#3-integration)
+- [4. The `@nestjs/event-emitter` bridge](#4-the-nestjsevent-emitter-bridge)
+- [5. Complete event list](#5-complete-event-list)
+- [6. Payloads](#6-payloads)
+- [7. Guarantees & limitations](#7-guarantees--limitations)
+- [8. Public API](#8-public-api)
+
+---
+
+## 1. What you get
+
+Two tiers of events, both opt-in:
+
+- **Operation events** — exactly one per root mutation (`material.created`,
+  `ship-inventory-order.shipped`, …). 38 in total.
+- **Stock domain events** — driven by the `ChangeType` state machine
+  (`stock.allocated`, `stock.shipped`, …), emitted once per stock movement, so a
+  single operation can fan out several. 18 in total.
+
+Two hook points per event:
+
+- **`beforeHooks`** run *before* any DB work. Throwing **vetoes** the whole
+  mutation — nothing is written, no after-listener fires. Use for custom
+  authorization, validation, quota enforcement.
+- **`afterListeners`** run *after the outermost transaction commits*. Use for
+  audit logging, ERP/webhook sync, cache invalidation, notifications.
+
+Everything is optional. With nothing configured the module behaves exactly as
+before — no events, zero overhead.
+
+---
+
+## 2. Architecture — post-commit guarantee
+
+The hard requirement is that an after-listener must **never** be told about a
+change that was rolled back. WMS guarantees this with an `AsyncLocalStorage`
+dispatch scope opened by a per-mutation interceptor:
+
+```
+GraphQL Mutation (@WmsMutationEvent)
+   |
+   v
+WmsMutationInterceptor
+   1. beforeHook(event, args)   --throw--> VETO (no transaction, clean error)
+   2. als.run(scope, async () => {
+        result = await handler()         // services open tx, write *_order_change rows
+      })                                 //   -> StockChangeSubscriber.afterInsert
+   |                                     //      collects stock.* events into the scope
+   |  handler resolved == transaction committed
+   v
+   3. flush(scope.buffer)
+        afterListener(event)  (isolated; one failure never blocks others)
+        emitterBridge.forward(event)  --> EventEmitter2 (optional)
+```
+
+Why it is post-commit: TypeORM's `dataSource.transaction(cb)` resolves only
+*after* `COMMIT`. The interceptor awaits the whole handler before flushing, so
+the buffer is dispatched strictly after commit. If the transaction rolls back
+the handler rejects, the interceptor never flushes, and the buffered events are
+discarded.
+
+Stock events are collected centrally by a single TypeORM subscriber
+(`StockChangeSubscriber`) that listens to every `*_order_change` insert and
+derives the `ChangeType` from the table name and the sign of `quantityChanged`.
+The 12 domain services are untouched, and any future code path that writes a
+change row is covered automatically.
+
+---
+
+## 3. Integration
+
+`beforeHooks` / `afterListeners` are typed maps keyed by event name; the payload
+is inferred from the key.
+
+```ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { ForbiddenException } from '@nestjs/common';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+
+  // intervene — runs before any DB work; throw to veto
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args, executionContext }) => {
+      if (!(await canShip(args, executionContext))) {
+        throw new ForbiddenException('shipment blocked');
+      }
+    },
+  },
+
+  // notify — runs after commit
+  afterListeners: {
+    'ship-inventory-order.shipped': async ({ payload }) => {
+      await erp.markShipped(payload.id, payload.result);
+    },
+    'stock.allocated': async ({ payload }) => {
+      await erp.reserve(payload.orderId, payload.itemId, payload.quantityDelta);
+    },
+  },
+});
+```
+
+- A `beforeHook` receives `{ event, args, executionContext }` — the mutation
+  **intent** (raw GraphQL args), since no result exists yet. Throw (e.g. a
+  `ForbiddenException`) to abort with zero side effects.
+- An `afterListener` receives `{ event, payload }` — the committed result (see
+  [§6](#6-payloads)). It may be async; a thrown error is logged and isolated, it
+  never affects the committed mutation or other listeners.
+
+---
+
+## 4. The `@nestjs/event-emitter` bridge
+
+Prefer decoupled `@OnEvent` subscribers? Opt into the bridge. It is the only
+thing that imports `@nestjs/event-emitter` (an **optional** peer dependency), so
+the core module never depends on it.
+
+```ts
+import { EventEmitterModule } from '@nestjs/event-emitter';
+import { wmsEventEmitterBridgeProvider } from '@rytass/wms-module-graphql/adapters/event-emitter';
+
+@Module({
+  imports: [
+    EventEmitterModule.forRoot(),
+    WmsModuleGraphqlModule.forRootAsync({
+      ...coreOptions,
+      eventEmitterBridge: wmsEventEmitterBridgeProvider,
+    }),
+  ],
+})
+export class AppModule {}
+
+// anywhere
+@Injectable()
+class StockSync {
+  @OnEvent('wms.stock.allocated')
+  handle(payload: WmsStockEventPayload) { /* ... */ }
+}
+```
+
+Every event is emitted as `wms.<event-name>` with its payload. `afterListeners`
+and the bridge can be used together — both fire.
+
+---
+
+## 5. Complete event list
+
+### Operation events (38) — `<domain>.<past-tense-action>`
+
+| Event | Mutation | Fans out to stock event |
+|---|---|---|
+| `receive-inventory-order.created` | createReceiveInventoryOrder | — |
+| `receive-inventory-order.updated` | updateReceiveInventoryOrder | — |
+| `receive-inventory-order.received` | receive | `stock.received` |
+| `ship-inventory-order.created` | createShipInventoryOrder | — |
+| `ship-inventory-order.updated` | updateShipInventoryOrder | `stock.in-shipment` |
+| `ship-inventory-order.shipped` | ship | `stock.shipped` |
+| `ship-inventory-order.ship-cancelled` | cancelShip | `stock.shipped` (negative) |
+| `transfer-order.created` | createTransferOrder | `stock.in-transfer` |
+| `transfer-order.updated` | updateTransferOrder | `stock.in-transfer` |
+| `transfer-order.transferred` | transfer | `stock.transferred` |
+| `transfer-order.transfer-cancelled` | cancelTransfer | `stock.in-transfer` (reversal) |
+| `hold-inventory-order.created` | createHoldInventoryOrder | `stock.held` |
+| `hold-inventory-order.updated` | updateHoldInventoryOrder | `stock.held` |
+| `hold-inventory-order.released` | release | `stock.released` |
+| `allocate-inventory-order.created` | createAllocateInventoryOrder | `stock.allocated` |
+| `allocate-inventory-order.updated` | updateAllocateInventoryOrder | `stock.allocated` |
+| `allocate-inventory-order.deallocated` | deallocate | `stock.deallocated` |
+| `transfer-vendor-order.created` | createTransferVendorOrder | `stock.vendor-transferred` |
+| `transfer-vendor-order.updated` | updateTransferVendorOrder | `stock.vendor-transferred` |
+| `transfer-vendor-order.returned` | returnTransferVendorOrder | `stock.vendor-returned` |
+| `transfer-customer-order.created` | createTransferCustomerOrder | `stock.customer-held` |
+| `transfer-customer-order.updated` | updateTransferCustomerOrder | `stock.customer-held` |
+| `transfer-customer-order.returned` | returnTransferCustomerOrder | `stock.customer-returned` |
+| `quality-inspection-order.inspected` | inspectMaterials | `stock.inspection-resolved` |
+| `scrape-order.scraped` | scrapeMaterials | `stock.scraped` |
+| `reclassify-inventory-order.reclassified` | reclassifyInventoryOrder | `stock.reclassified` |
+| `batch.merged` | mergeBatch | `stock.merged` |
+| `batch.splitted` | splitBatch | `stock.splitted` |
+| `material.created` | createMaterial | — |
+| `material.updated` | updateMaterial | — |
+| `loader.created` | createLoader | — |
+| `loader.batch-created` | createBatchLoader | — |
+| `loader.updated` | updateLoader | — |
+| `loader.type-created` | createLoaderType | — |
+| `loader.type-updated` | updateLoaderType | — |
+| `location.created` | createLocation | — |
+| `location.updated` | updateLocation | — |
+| `warehouse-map.updated` | updateWarehouseMap | — |
+
+> The "Fans out to stock event" column is **indicative**, not a hard binding. A
+> mutation never names a stock event directly — `StockChangeSubscriber` derives
+> it from the `*_order_change` table that was written and the sign of
+> `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).
+
+### Stock domain events (18) — `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`.
+
+The first 17 map 1:1 to `ChangeType`. `stock.inspection-resolved` has no
+`ChangeType` (quality inspection only flips the `inspectionResult` flag) and
+carries `changeType: null` plus `inspectionResult`.
+
+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`,
+`cancelTransfer` -> `stock.in-transfer`); branch on the sign, not the name only.
+
+---
+
+## 6. Payloads
+
+**Operation event** — `WmsOperationEventPayload`:
+
+```ts
+{ id: string | null;   // primary id of the operation's order/entity
+  result: unknown }     // the mutation's return value (DTO, or boolean for actions)
+```
+
+**Stock event** — `WmsStockEventPayload`:
+
+```ts
+{ orderId: string;            // = change.id; correlation id with the operation event
+  itemId: string;             // = change.itemId
+  quantityDelta: number;      // = change.quantityChanged (sign = direction)
+  changeType: ChangeType | null;          // null only for stock.inspection-resolved
+  inspectionResult?: boolean | null }     // present only on stock.inspection-resolved
+```
+
+`orderId` is the same on the operation event (`payload.id`) and the stock events
+it fans out to, so listeners can correlate the two tiers. For richer
+batch/material/location details, look them up by `orderId` / `itemId` inside the
+after-listener — the data is committed by then.
+
+---
+
+## 7. Guarantees & limitations
+
+- **Post-commit, in-order.** After-listeners fire strictly after commit, in
+  collection order, with the operation event last.
+- **Veto is side-effect-free.** A throwing before-hook runs before any
+  transaction; nothing is written.
+- **Listener isolation.** A throwing after-listener is logged and skipped; it
+  never rolls back the (already committed) mutation or blocks other listeners.
+- **In-process, not persistent.** If the process crashes after commit but before
+  flush, those events are lost. This is an in-process event bus, not an
+  at-least-once outbox. If you need durable delivery, persist inside your
+  after-listener is *not* enough — use an external CDC/outbox.
+- **"Handler resolve = post-commit" invariant.** Relies on every mutation
+  resolver `await`-ing all its writes (it does today). Never fire-and-forget an
+  un-awaited DB write inside a mutation.
+- **Uneven transaction boundaries.** `receive*` wrap the transaction at the
+  resolver, `ship/transfer/cancel*/reclassify/merge/split` at the service, and
+  the `create/update` series have no explicit transaction (multiple awaits).
+  Events for the no-transaction operations fire after the writes complete, but
+  those operations were never atomic to begin with.
+
+---
+
+## 8. Public API
+
+From the package root (`@rytass/wms-module-graphql`, re-exported from
+`@rytass/wms-module-core`):
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `WmsMutationEvent({ event })` | decorator | Annotates a mutation (already applied across the library). |
+| `WmsBeforeHookMap` / `WmsAfterListenerMap` | type | The `beforeHooks` / `afterListeners` option shapes. |
+| `WmsEventModuleOptions` | type | `{ beforeHooks?, afterListeners? }` (part of `forRootAsync`). |
+| `WmsBeforeHookContext` / `WmsAfterEventContext` | type | Hook/listener argument shapes. |
+| `WmsDomainEvent` | type | `{ name, payload }`. |
+| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName` | type | Event-name unions. |
+| `WmsEventPayloadMap` | type | Event name -> payload mapping. |
+| `WmsOperationEventPayload` / `WmsStockEventPayload` | type | Payload shapes. |
+
+From the adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`):
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `wmsEventEmitterBridgeProvider` | provider | Pass to `forRootAsync({ eventEmitterBridge })` to fan events onto `@nestjs/event-emitter`. |
+
+`forRootAsync` accepts `beforeHooks`, `afterListeners` and `eventEmitterBridge`
+on its single options object — all optional.
+
+---
+
+See also: [Authorization](./authorization.md) · [API Reference](./api-reference.md) · [Integration Guide](./integration-guide.md)