@rytass/wms-module-graphql 0.3.0 → 0.5.0

package/README.md

@@ -62,6 +62,57 @@ 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.
 
+## Authorization
+
+Every WMS root `@Query` / `@Mutation` is annotated with `@WmsOperation({ resource, action })` — a **host-neutral** permission requirement enforced by the library's own route-level `WmsAuthGuard`, which delegates the allow/deny decision to an `authChecker` **you** supply. The library never imports your auth system; you map WMS's `resource`/`action` onto whatever you use (Casbin, RBAC, JWT scopes…).
+
+> ⚠️ **Using a global guard (e.g. member-base's `CasbinGuard` as `APP_GUARD`)?** A deny-by-default global guard blankets *every* resolver in the schema, including WMS's, and rejects them all because they carry no host-specific metadata — "every WMS operation is forbidden". WMS fixes this by stamping each operation with a host-skip marker so your global guard **defers**, while `WmsAuthGuard` does the real enforcement. **You do not touch your global guard.**
+
+```ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  // optional — omit to stay fully permissive (local dev / demos)
+  authChecker: createMemberBaseWmsAuthChecker({
+    map: ({ resource, action }) => [[`wms:${resource}`, action]],
+  }),
+});
+```
+
+The member-base adapter reuses everything `CasbinGuard` already put on the request (verified `payload`, `enforcer`, your custom `casbinPermissionChecker`) so WMS enforces with the **exact same** policy engine as your own resolvers — with **zero** member-base import on the WMS side. For custom JWT/RBAC, pass your own `authChecker: (ctx, { resource, action }) => boolean`.
+
+➡️ **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).
+
+## 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`:
+
+- **`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.
+
+```ts
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+  beforeHooks: {
+    'ship-inventory-order.shipped': async ({ args }) => {
+      if (!allowed(args)) throw new ForbiddenException('blocked');
+    },
+  },
+  afterListeners: {
+    'stock.allocated': async ({ payload }) => { await erp.reserve(payload); },
+  },
+});
+```
+
+Post-commit delivery is guaranteed by an `AsyncLocalStorage` dispatch scope (events buffer during the request and flush only after commit). Prefer `@OnEvent`? Opt into the optional [`@nestjs/event-emitter`](https://docs.nestjs.com/techniques/events) bridge from `@rytass/wms-module-graphql/adapters/event-emitter` — every event also emits as `wms.<event>`. Nothing configured ⇒ no events, zero overhead.
+
+➡️ **Full design, the complete 56-event list & limitations: [`docs/events.md`](./docs/events.md)**.
+
 ## DataLoader context
 
 The module ships a `HelperModule` (auto-registered) that provides a singleton `LoaderService`. To avoid N+1 queries, the WMS resolvers expect a per-request DataLoader trio at `context.loaders`:
@@ -97,12 +148,16 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 | Document | Description |
 |---|---|
 | [`docs/integration-guide.md`](./docs/integration-guide.md) | Step-by-step wiring guide for NestJS + Next.js consumers |
+| [`docs/authorization.md`](./docs/authorization.md) | Complete resolver-authorization design & integration recipes (member-base / custom JWT / no-guard) |
+| [`docs/events.md`](./docs/events.md) | Mutation event/hook system — before-hooks (veto), post-commit after-listeners, complete event list, event-emitter bridge |
 | [`docs/api-reference.md`](./docs/api-reference.md) | Complete export catalog with signatures and usage examples |
 
 GitHub hosted links (always up-to-date):
 
 - [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
 - [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
+- [Authorization — design & recipes](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/authorization.md)
+- [Events & Hooks — design & event list](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/events.md)
 - [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/docs/api-reference.md#rytasswms-module-graphql)
 
 ## License

package/adapters/event-emitter.d.ts

@@ -0,0 +1,29 @@
+import type { Provider } from '@nestjs/common';
+/**
+ * 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) { ... }
+ * ```
+ */
+export declare const wmsEventEmitterBridgeProvider: Provider;

package/adapters/event-emitter.js

@@ -0,0 +1,41 @@
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import { WMS_EVENT_EMITTER_BRIDGE } from '@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: WMS_EVENT_EMITTER_BRIDGE,
+    useFactory: (emitter) => ({
+        forward: (event) => {
+            emitter.emit(`wms.${event.name}`, event.payload);
+        },
+    }),
+    inject: [EventEmitter2],
+};
+
+export { wmsEventEmitterBridgeProvider };

package/adapters/member-base.d.ts

@@ -0,0 +1,35 @@
+import type { WmsAuthChecker, WmsOperationRequirement } from '../lib/auth';
+/**
+ * A Casbin `[subject, action]` tuple, e.g. `['wms:material', 'read']`.
+ */
+export type CasbinAction = [string, string];
+export interface MemberBaseWmsAuthCheckerOptions {
+    /**
+     * Map a host-neutral WMS requirement onto one or more Casbin
+     * `[subject, action]` tuples. This is where your project's permission naming
+     * convention lives. Returning several tuples means "allow if *any* passes"
+     * (member-base's default checker is OR-based).
+     *
+     * @example
+     * ```ts
+     * map: ({ resource, action }) => [[`wms:${resource}`, action]]
+     * // material:read  ->  enforce(memberId, domain, 'wms:material', 'read')
+     * ```
+     */
+    readonly map: (requirement: WmsOperationRequirement) => CasbinAction[];
+}
+/**
+ * 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).
+ */
+export declare const createMemberBaseWmsAuthChecker: (options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker;

package/adapters/member-base.js

@@ -0,0 +1,47 @@
+import { GqlExecutionContext } from '@nestjs/graphql';
+
+const extractRequest = (context) => {
+    const gqlContext = 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,
+        });
+    };
+};
+
+export { createMemberBaseWmsAuthChecker };

package/docs/README.md

@@ -7,6 +7,8 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Document                                       | Description                                                                                       |
 |------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | [Integration Guide](./integration-guide.md)    | Step-by-step instructions for wiring the three packages into a new consumer project (NestJS + Next.js + PostgreSQL). Includes ready-to-paste `_app.tsx`, `app.module.ts`, `next.config.ts`, the 19 Pages Router shell pattern, AuthGuard stub, seed script template, deployment notes, and known issues. |
+| [Authorization](./authorization.md)            | Complete design of the resolver-level authorization protocol (`@WmsOperation` + `WmsAuthGuard` + `authChecker`). Explains the global deny-by-default guard pitfall, execution order, and integration recipes for member-base / Casbin, custom JWT / RBAC, and no-guard setups. Read this if any WMS query/mutation returns *forbidden*. |
+| [Events & Hooks](./events.md)                  | The mutation event/hook system — `beforeHooks` (veto before any DB work) and `afterListeners` (post-commit notify), the `AsyncLocalStorage` post-commit mechanism, the optional `@nestjs/event-emitter` bridge, and the complete list of 38 operation + 18 stock domain events with payloads. |
 | [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6`. |
 
 ## Quick links
@@ -23,6 +25,10 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Look up a specific export's signature                   | [API Reference](./api-reference.md)                                    |
 | Understand why the lib needs `transpilePackages`        | [Integration Guide section 5.3](./integration-guide.md#53-appsclientnextconfigts) |
 | Replace the `AuthGuard` stub with real auth             | [Integration Guide section 8.4](./integration-guide.md#84-real-auth-integration) |
+| Authorize WMS resolvers with member-base / Casbin / RBAC | [Authorization](./authorization.md)                                   |
+| Fix "every WMS query/mutation is forbidden"             | [Authorization section 1](./authorization.md#1-the-problem)            |
+| Hook into / get notified about mutations                | [Events & Hooks](./events.md)                                          |
+| See every event the system emits                        | [Events & Hooks section 5](./events.md#5-complete-event-list)          |
 | Decide between PostgreSQL and SQLite                    | [Integration Guide section 9](./integration-guide.md#9-database-support-matrix) |
 | Build a custom UI on top of the lib's GraphQL operations| [Integration Guide section 7.3](./integration-guide.md#73-graphql-operations--typed-hooks) |
 

package/docs/api-reference.md

@@ -301,17 +301,23 @@ enum ShipInventoryOrderStatus { PENDING, PARTIAL_SHIPPED, SHIPPED, REMOVED }
 **`forRootAsync(options): DynamicModule`** (since 0.3.0)
 ```ts
 static forRootAsync(
-  options: WmsModuleCoreModuleAsyncOptions,
+  options: WmsModuleGraphqlModuleAsyncOptions,
+  // = WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions
+  //
   // WMSBaseModuleAsyncOptions（Vault/DB 選項）
   // + WmsModuleCoreModuleOptions:
   //     defaultLoaderSerialId: string  — 庫存作業預設載具序號
   //     defaultLoaderTypeKey: string   — 預設載具類型 key
   //     defaultLocationKey: string     — 預設儲存位置 key
+  // + WmsAuthModuleOptions:
+  //     authChecker?: WmsAuthChecker   — 選填；resolver 授權委派函式（見 Authorization）
 ): 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).
 
+> **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)
 - 用途: 提供 DataLoader 工廠方法（`batchEntity()`、`batchEntities()`、`batchEntitiesWithPagination()`）。每次呼叫產生新的 DataLoader instance — 須在 GraphQL context factory **per request** 呼叫，**勿** 在 module scope 重用。
 - 來源: `lib/helpers/loader.service.ts`
@@ -390,6 +396,99 @@ material(
 
 ---
 
+## Authorization
+
+Host-neutral, opt-in resolver authorization. Every WMS root `@Query`/`@Mutation` carries `@WmsOperation({ resource, action })`; `WmsAuthGuard` enforces it by delegating to the consumer-supplied `authChecker`. Full design & recipes: [`docs/authorization.md`](./authorization.md).
+
+### Root exports (`@rytass/wms-module-graphql`)
+
+| Export | Kind | Signature / shape |
+|---|---|---|
+| `WmsOperation` | decorator | `(requirement: WmsOperationRequirement) => MethodDecorator` — already applied across the library; add it to any new root op. |
+| `WmsAuthGuard` | `@Injectable()` guard | route-level `CanActivate`; reads the requirement, calls `authChecker`. Auto-registered by `forRootAsync`. |
+| `WmsAuthChecker` | type | `(context: ExecutionContext, requirement: WmsOperationRequirement) => boolean \| Promise<boolean>` |
+| `WmsOperationRequirement` | type | `{ readonly resource: string; readonly action: string }` |
+| `WmsAuthModuleOptions` | type | `{ readonly authChecker?: WmsAuthChecker }` |
+| `WmsModuleGraphqlModuleAsyncOptions` | type | `WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions` (the `forRootAsync` arg) |
+| `WMS_AUTH_OPTIONS` | `symbol` | DI token holding the resolved auth options |
+| `WMS_OPERATION_METADATA` | `string` (`'wms:operation'`) | Reflector key carrying the requirement |
+| `HOST_SKIP_METADATA_KEY` | `string` (`'IS_ROUTE_PUBLIC'`) | host-skip metadata key stamped on each op so a global guard defers (default matches member-base) |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`)
+
+| Export | Kind | Signature / shape |
+|---|---|---|
+| `createMemberBaseWmsAuthChecker` | factory | `(options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker` |
+| `MemberBaseWmsAuthCheckerOptions` | type | `{ readonly map: (requirement: WmsOperationRequirement) => CasbinAction[] }` |
+| `CasbinAction` | type | `[string, string]` — a `[subject, action]` tuple |
+
+```ts
+// member-base / Casbin
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  authChecker: createMemberBaseWmsAuthChecker({
+    map: ({ resource, action }) => [[`wms:${resource}`, action]],
+  }),
+});
+
+// custom JWT / RBAC
+import type { WmsAuthChecker } from '@rytass/wms-module-graphql';
+
+const authChecker: WmsAuthChecker = (ctx, { resource, action }) => {
+  // read your session off ctx and decide
+  return true;
+};
+```
+
+The adapter imports nothing from member-base — it reads the `payload` / `enforcer` / `casbinPermissionChecker` that `CasbinGuard` attaches to the request at runtime. member-base is therefore **not** a dependency or peer dependency of this package.
+
+---
+
+## 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).
+
+### Root exports (`@rytass/wms-module-graphql`, re-exported from `@rytass/wms-module-core`)
+
+| Export | Kind | Signature / shape |
+|---|---|---|
+| `WmsMutationEvent` | decorator | `({ event: WmsOperationEventName, resolveId? }) => MethodDecorator` |
+| `WmsEventModuleOptions` | type | `{ beforeHooks?: WmsBeforeHookMap; afterListeners?: WmsAfterListenerMap }` — part of `forRootAsync` options |
+| `WmsBeforeHookMap` | type | `{ [N in WmsEventName]?: (ctx: WmsBeforeHookContext<N>) => void \| Promise<void> }` |
+| `WmsAfterListenerMap` | type | `{ [N in WmsEventName]?: (ctx: WmsAfterEventContext<N>) => void \| Promise<void> }` |
+| `WmsBeforeHookContext` | type | `{ event; args: Record<string, unknown>; executionContext: ExecutionContext }` |
+| `WmsAfterEventContext` | type | `{ event; payload: WmsEventPayloadMap[event] }` |
+| `WmsDomainEvent` | type | `{ name: WmsEventName; payload }` |
+| `WmsEventName` / `WmsOperationEventName` / `WmsStockEventName` | type | event-name unions (38 operation + 18 stock) |
+| `WmsEventPayloadMap` | type | event name → payload |
+| `WmsOperationEventPayload` | type | `{ id: string \| null; result: unknown }` |
+| `WmsStockEventPayload` | type | `{ orderId; itemId; quantityDelta; changeType: ChangeType \| null; inspectionResult? }` |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/event-emitter`)
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `wmsEventEmitterBridgeProvider` | `Provider` | Pass to `forRootAsync({ eventEmitterBridge })`; fans every event onto `EventEmitter2` as `wms.<event>` for `@OnEvent`. Requires `@nestjs/event-emitter` (optional peer) + `EventEmitterModule.forRoot()`. |
+
+```ts
+WmsModuleGraphqlModule.forRootAsync({
+  ...coreOptions,
+  beforeHooks: { 'ship-inventory-order.shipped': async ({ args }) => { if (!ok(args)) throw new ForbiddenException(); } },
+  afterListeners: { 'stock.allocated': async ({ payload }) => { await sync(payload); } },
+  // optional @OnEvent bridge:
+  // eventEmitterBridge: wmsEventEmitterBridgeProvider,
+});
+```
+
+`beforeHooks` / `afterListeners` are **not** part of the GraphQL schema — they are runtime hooks. With none configured the interceptor passes through with zero overhead.
+
+---
+
 ## Resolvers（`@Resolver()` decorator class）
 
 以下 Resolver 類別處理 GraphQL `@ResolveField`，解析關聯欄位（防止 N+1）：