@rytass/wms-module-graphql 0.1.1 → 0.1.3

package/docs/api-reference.md

@@ -0,0 +1,957 @@
+# API Reference — @rytass/wms-module-*
+
+Complete export catalog for the three publishable libraries:
+
+- `@rytass/wms-module-core` — NestJS module, TypeORM entities, services, DI tokens
+- `@rytass/wms-module-graphql` — GraphQL resolvers, DTOs, DataLoader helpers
+- `@rytass/wms-module-react` — React components, hooks, Apollo client, GraphQL operations
+
+Current versions: **0.1.2** (all three packages).
+
+This document mirrors the actual `src/index.ts` barrel exports and is generated by static analysis of the lib sources. For runtime behavior changes between versions, see each package's `CHANGELOG.md`.
+
+> Companion document — **[Integration Guide](./integration-guide.md)** — step-by-step instructions for wiring the three packages into a new consumer project.
+
+---
+
+
+# @rytass/wms-module-core
+
+## NestJS Modules
+
+### `WmsModuleCoreModule`
+- 用途: WMS 核心 NestJS 動態模組，整合 TypeORM 實體、服務與 Vault 認證；透過 `forRoot` / `forRootAsync` 初始化整個核心功能。
+- 來源: `lib/core.module.ts`
+
+**`forRoot(options, coreOptions): DynamicModule`**
+```ts
+static forRoot(
+  options: WMSBaseModuleOptions,          // @rytass/wms-base-nestjs-module 選項（DB 連線等）
+  coreOptions: WmsModuleCoreModuleOptions, // defaultLoaderSerialId / defaultLoaderTypeKey / defaultLocationKey
+): DynamicModule
+```
+
+**`forRootAsync(options): DynamicModule`**
+```ts
+static forRootAsync(
+  options: WmsModuleCoreModuleAsyncOptions, // WMSBaseModuleAsyncOptions + WmsModuleCoreModuleOptions
+): DynamicModule
+```
+
+### `ModelsModule`
+- 用途: 內部模組，向 TypeORM 註冊所有 WMS 實體（via DI token 形式），並透過 `ResolvedEntitiesProviders` 提供 DI。**消費端不直接 import**；它由 `WmsModuleCoreModule.forRoot` 自動引入並 re-export。
+- 來源: `lib/models/models.module.ts`
+
+---
+
+## TypeORM Entities（Metadata — 基礎主檔）
+
+每個實體都同時匯出一個 **`Symbol` DI token** 和一個 **`EntityClass`**：
+
+| Symbol (DI token) | EntityClass | 說明 | 來源 |
+|---|---|---|---|
+| `UnitEntity` | `UnitEntityClass` | 單位主檔（kg / pcs 等） | `lib/models/metadata/unit.entity.ts` |
+| `MaterialEntity` | `MaterialEntityClass` | 料號主檔，繼承 `BaseMaterialEntity` | `lib/models/metadata/material.entity.ts` |
+| `MaterialUnitEntity` | `MaterialUnitEntityClass` | 料號換算單位（含換算係數） | `lib/models/metadata/material-unit.entity.ts` |
+| `BatchEntity` | `BatchEntityClass` | 批號主檔，繼承 `BaseBatchEntity` | `lib/models/metadata/batch.entity.ts` |
+| `BatchGroupEntity` | `BatchGroupEntityClass` | 批號群組，支援多批合併情境 | `lib/models/metadata/batch-group.entity.ts` |
+| `LoadersEntity` | `LoadersEntityClass` | 載具主檔（托板/棧板等），含尺寸欄位 | `lib/models/metadata/loader.entity.ts` |
+| `LoaderTypeEntity` | `LoaderTypeEntityClass` | 載具類型 | `lib/models/metadata/loader-type.entity.ts` |
+| `LoaderUnitEntity` | `LoaderUnitEntityClass` | 載具與單位的對應關係 | `lib/models/metadata/loader-unit.entity.ts` |
+| `LocationEntity` | `LocationEntityClass` | 儲存位置，繼承 `BaseLocationEntity` | `lib/models/metadata/location.entity.ts` |
+| `WarehouseMapEntity` | — | 倉庫地圖（Symbol，class 來自 base module） | `lib/models/metadata/location.entity.ts` |
+| `StockEntity` | `StockEntityClass` | 庫存記錄，繼承 `BaseStockEntity` | `lib/models/metadata/stock.entity.ts` |
+| `SaleOrderEntity` | `SaleOrderEntityClass` | 銷售訂單主檔 | `lib/models/metadata/sale-order.entity.ts` |
+
+---
+
+## TypeORM Entities（Extensions — 訂單與作業）
+
+同樣每個都有 Symbol + EntityClass 雙匯出，共 37 個：
+
+**入庫訂單 (Receive Inventory Order)**
+- `ReceiveInventoryOrderEntity` / `ReceiveInventoryOrderEntityClass` — 入庫單主檔
+- `ReceiveInventoryOrderItemEntity` / `ReceiveInventoryOrderItemEntityClass` — 入庫單明細
+- `ReceiveInventoryOrderChangeEntity` / `ReceiveInventoryOrderChangeEntityClass` — 入庫異動紀錄
+- 來源: `lib/models/extensions/receive-inventory-order/`
+
+**出庫訂單 (Ship Inventory Order)**
+- `ShipInventoryOrderEntity` / `ShipInventoryOrderEntityClass` — 出庫單主檔
+- `ShipInventoryOrderItemEntity` / `ShipInventoryOrderItemEntityClass` — 出庫單明細
+- `ShipInventoryOrderReferenceEntity` / `ShipInventoryOrderReferenceEntityClass` — 出庫單參考（連結銷售單）
+- `ShipInventoryOrderChangeEntity` / `ShipInventoryOrderChangeEntityClass` — 出庫異動紀錄
+- 來源: `lib/models/extensions/ship-inventory-order/`
+
+**調撥訂單 (Transfer Order)**
+- `TransferOrderEntity` / `TransferOrderEntityClass`
+- `TransferOrderItemEntity` / `TransferOrderItemEntityClass`
+- `TransferOrderChangeEntity` / `TransferOrderChangeEntityClass`
+- 來源: `lib/models/extensions/transfer-order/`
+
+**客戶調撥訂單 (Transfer Customer Order)**
+- `TransferCustomerOrderEntity` / `TransferCustomerOrderEntityClass`
+- `TransferCustomerOrderItemEntity` / `TransferCustomerOrderItemEntityClass`
+- `TransferCustomerOrderChangeEntity` / `TransferCustomerOrderChangeEntityClass`
+- 來源: `lib/models/extensions/transfer-customer-order/`
+
+**供應商調撥訂單 (Transfer Vendor Order)**
+- `TransferVendorOrderEntity` / `TransferVendorOrderEntityClass`
+- `TransferVendorOrderItemEntity` / `TransferVendorOrderItemEntityClass`
+- `TransferVendorOrderChangeEntity` / `TransferVendorOrderChangeEntityClass`
+- 來源: `lib/models/extensions/transfer-vendor-order/`
+
+**凍結庫存訂單 (Hold Inventory Order)**
+- `HoldInventoryOrderEntity` / `HoldInventoryOrderEntityClass`
+- `HoldInventoryOrderItemEntity` / `HoldInventoryOrderItemEntityClass`
+- `HoldInventoryOrderChangeEntity` / `HoldInventoryOrderChangeEntityClass`
+- 來源: `lib/models/extensions/hold-inventory-order/`
+
+**分配庫存訂單 (Allocate Inventory Order)**
+- `AllocateInventoryOrderEntity` / `AllocateInventoryOrderEntityClass`
+- `AllocateInventoryOrderItemEntity` / `AllocateInventoryOrderItemEntityClass`
+- `AllocateInventoryOrderChangeEntity` / `AllocateInventoryOrderChangeEntityClass`
+- 來源: `lib/models/extensions/allocate-inventory-order/`
+
+**拆批訂單 (Split Batch Order)**
+- `SplitBatchOrderEntity` / `SplitBatchOrderEntityClass`
+- `SplitBatchOrderItemEntity` / `SplitBatchOrderItemEntityClass`
+- `SplitBatchOrderChangeEntity` / `SplitBatchOrderChangeEntityClass`
+- 來源: `lib/models/extensions/split-batch-order/`
+
+**併批訂單 (Merge Batch Order)**
+- `MergeBatchOrderEntity` / `MergeBatchOrderEntityClass`
+- `MergeBatchOrderItemEntity` / `MergeBatchOrderItemEntityClass`
+- `MergeBatchOrderChangeEntity` / `MergeBatchOrderChangeEntityClass`
+- 來源: `lib/models/extensions/merge-batch-order/`
+
+**轉料號訂單 (Reclassify Inventory Order)**
+- `ReclassifyInventoryOrderEntity` / `ReclassifyInventoryOrderEntityClass`
+- `ReclassifyInventoryOrderItemEntity` / `ReclassifyInventoryOrderItemEntityClass`
+- `ReclassifyInventoryOrderChangeEntity` / `ReclassifyInventoryOrderChangeEntityClass`
+- 來源: `lib/models/extensions/reclassify-inventory-order/`
+
+**品質檢驗訂單 (Quality Inspection Order)**
+- `QualityInspectionOrderEntity` / `QualityInspectionOrderEntityClass`
+- `QualityInspectionOrderItemEntity` / `QualityInspectionOrderItemEntityClass`
+- `QualityInspectionOrderChangeEntity` / `QualityInspectionOrderChangeEntityClass`
+- 來源: `lib/models/extensions/quality-inspection-order/`
+
+**報廢訂單 (Scrape Order)**
+- `ScrapeOrderEntity` / `ScrapeOrderEntityClass`
+- `ScrapeOrderItemEntity` / `ScrapeOrderItemEntityClass`
+- `ScrapeOrderChangeEntity` / `ScrapeOrderChangeEntityClass`
+- 來源: `lib/models/extensions/scrape-order/`
+
+**另有輔助 provider**
+- `ResolvedEntitiesProviders: Provider[]` — 由 `ModelsModule` 內部使用，把所有 [Symbol, EntityClass] pair 轉為 NestJS DI providers，供服務注入實體 class。
+- 來源: `lib/models/models.module.ts`
+
+---
+
+## Services（`@Injectable()`）
+
+| Class | 主要方法 | 說明 | 來源 |
+|---|---|---|---|
+| `MaterialService<T>` | `createMaterial`, `updateMaterial`, `findMany`, `getConversionFactor` | 料號 CRUD | `lib/services/material.service.ts` |
+| `UnitService` | （DataSource 直接操作） | 單位查詢 | `lib/services/unit.service.ts` |
+| `BatchService<T>` | `getBatch`, `splitBatch`, `findMany` | 批號管理 | `lib/services/batch.service.ts` |
+| `LoaderService<T, K>` | `createLoader`, `createBatchLoaders`, `updateLoader`, `createLoaderType`, `updateLoaderType`, `getSeq`, `findManyLoaders`, `findManyLoaderTypes` | 載具與類型 CRUD | `lib/services/loader.service.ts` |
+| `LocationService<T>` | `createLocation`, `updateLocation`, `findMany` | 庫位 CRUD | `lib/services/location.service.ts` |
+| `StockService<T>` | `findMany`, `findManyGroupedByMaterialId`, `findAggregatedStock`, `validateStockAvailability`, `findAggregatedStocks`, `findChangeLogs`, `resolveLoaderId`, `resolveLocationId` | 庫存查詢與聚合 | `lib/services/stock.service.ts` |
+| `ReceiveInventoryOrderService<T>` | `createReceiveInventoryOrder`, `updateReceiveInventoryOrder`, `removeReceiveInventoryOrder`, `findMany`, `receive` | 入庫單管理 | `lib/services/receive-inventory-order.service.ts` |
+| `ShipInventoryOrderService<T>` | `createShipInventoryOrder`, `updateShipInventoryOrder`, `removeShipInventoryOrder`, `findMany`, `addShipInventoryOrderItems`, `ship`, `cancelShip` | 出庫單管理 | `lib/services/ship-inventory-order.service.ts` |
+| `TransferOrderService<T>` | `createTransferOrder`, `updateTransferOrder`, `findMany`, `transfer`, `cancelTransfer`, `removeTransferOrder` | 調撥單管理 | `lib/services/transfer-order.service.ts` |
+| `TransferCustomerOrderService<T>` | `createTransferCustomerOrder`, `updateTransferCustomerOrder`, `returnTransferCustomerOrder` | 客戶調撥管理 | `lib/services/transfer-customer-order.service.ts` |
+| `TransferVendorOrderService<T>` | `createTransferVendorOrder`, `updateTransferVendorOrder`, `returnTransferVendorOrder` | 供應商調撥管理 | `lib/services/transfer-vendor-order.service.ts` |
+| `HoldInventoryOrderService<T>` | `createHoldInventoryOrder`, `updateHoldInventoryOrder`, `findMany`, `release` | 凍結庫存管理 | `lib/services/hold-inventory-order.service.ts` |
+| `AllocateInventoryOrderService<T>` | `createAllocateInventoryOrder`, `updateAllocateInventoryOrder`, `deallocate`, `findMany` | 分配庫存管理 | `lib/services/allocate-inventory-order.service.ts` |
+| `SplitBatchOrderService<T>` | `split` | 批號拆分 | `lib/services/split-batch-order.service.ts` |
+| `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` |
+| `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` |
+| `WarehouseMapDataService` | `onApplicationBootstrap` | 倉庫地圖資料初始化，implements `OnApplicationBootstrap` | `lib/services/warehouse-map.service.ts` |
+
+---
+
+## Interfaces / Types
+
+### 模組選項
+- `WmsModuleCoreModuleOptions` — `{ defaultLoaderSerialId: string; defaultLoaderTypeKey: string; defaultLocationKey: string; }`
+- `WmsModuleCoreModuleAsyncOptions` — `WMSBaseModuleAsyncOptions & WmsModuleCoreModuleOptions`
+- 來源: `lib/typings/core-module-options.ts`
+
+### 服務輸入 (Service Input Types)
+
+**載具**
+- `CreateLoaderInput`, `UpdateLoaderInput` — 來源: `lib/typings/create-loader.input.ts`
+- `CreateLoaderTypeInput`, `UpdateLoaderTypeInput` — 來源: `lib/typings/create-loader-type.input.ts`
+- `FindLoaderInput<U>`, `FindLoaderTypeInput<U>` (extends `PaginationInput`) — 來源: `lib/typings/find-loader.input.ts`
+
+**料號**
+- `CreateMaterialInput`, `UpdateMaterialInput` — 來源: `lib/typings/create-material.input.ts`
+- `CreateMaterialUnitInput` — 來源: `lib/typings/create-material-unit.input.ts`
+- `FindMaterialInput<U>` (extends `PaginationInput`) — 來源: `lib/typings/find-material.input.ts`
+
+**庫位**
+- `CreateLocationInput`, `UpdateLocationInput` — 來源: `lib/typings/create-location.input.ts`
+- `FindLocationInput<U extends object>` (extends `PaginationInput`) — 來源: `lib/typings/find-location.input.ts`
+
+**庫存**
+- `FindStockInput<U extends object>` (extends `PaginationInput`) — 來源: `lib/typings/find-stock.input.ts`
+- `AggregatedStock`, `ValidateStockDeductionParams`, `ChangeLog` — 來源: `lib/typings/aggregated-stock.ts`
+
+**批號**
+- `SplitBatchInput`, `GetBatchInput` — 來源: `lib/typings/get-batch.input.ts`
+- `MergeBatchInput` — 來源: `lib/typings/merge-batch.input.ts`
+- `FindBatchInput<U extends object>` (extends `PaginationInput`) — 來源: `lib/typings/find-batch.input.ts`
+
+**入庫單**
+- `CreateReceiveInventoryOrderInput`, `CreateReceiveInventoryOrderItemInput`, `UpdateReceiveInventoryOrderInput`, `UpdateReceiveInventoryOrderItemInput` — 來源: `lib/typings/create-receive-inventory-order.input.ts`
+- `FindReceiveInventoryOrderInput<T>` (extends `PaginationInput`) — 來源: `lib/typings/find-receive-inventory-order.input.ts`
+- `ReceiveInventoryOrderInput` — 來源: `lib/typings/receive-inventory-order.input.ts`
+
+**出庫單**
+- `CreateShipInventoryOrderInput`, `CreateShipInventoryOrderItemInput`, `CreateShipInventoryOrderReferenceInput`, `CreateShipInventoryOrderItemsInput`, `UpdateShipInventoryOrderInput`, `UpdateShipInventoryOrderItemInput`, `UpdateShipInventoryOrderReferenceInput` — 來源: `lib/typings/create-ship-inventory-order.input.ts`
+- `FindShipInventoryOrderInput<T>` (extends `PaginationInput`) — 來源: `lib/typings/find-ship-inventory-order.input.ts`
+- `ShipInventoryOrderInput` — 來源: `lib/typings/ship-inventory-order.input.ts`
+- `CancelShipInventoryOrderInput` — 來源: `lib/typings/cancel-ship-inventory-order.input.ts`
+
+**調撥**
+- `CreateTransferOrderInput`, `CreateTransferOrderItemInput`, `UpdateTransferOrderInput`, `UpdateTransferOrderItemInput` — 來源: `lib/typings/create-transfer-order.input.ts`
+- `FindTransferOrderInput` (extends `PaginationInput`) — 來源: `lib/typings/find-transfer-order.input.ts`
+- `TransferOrderInput` — 來源: `lib/typings/transfer-order.input.ts`
+- `CancelTransferOrderInput` — 來源: `lib/typings/cancel-transfer-order.input.ts`
+- `CreateTransferCustomerOrderInput`, `CreateTransferCustomerOrderItemInput`, `UpdateTransferCustomerOrderInput`, `UpdateTransferCustomerOrderItemInput` — 來源: `lib/typings/create-transfer-customer-order.input.ts`
+- `CreateTransferVendorOrderInput`, `CreateTransferVendorOrderItemInput`, `UpdateTransferVendorOrderInput`, `UpdateTransferVendorOrderItemInput` — 來源: `lib/typings/create-transfer-vendor-order.input.ts`
+
+**凍結/分配**
+- `CreateHoldInventoryOrderInput`, `CreateHoldInventoryOrderItemInput`, `UpdateHoldInventoryOrderInput`, `UpdateHoldInventoryOrderItemInput` — 來源: `lib/typings/create-hold-inventory-order.input.ts`
+- `FindHoldInventoryOrderInput` (extends `PaginationInput`) — 來源: `lib/typings/find-hold-inventory-order.input.ts`
+- `ReleaseInventoryOrderItemInput` — 來源: `lib/typings/release-inventory-order.input.ts`
+- `CreateAllocateInventoryOrderInput`, `CreateAllocateInventoryOrderItemInput`, `UpdateAllocateInventoryOrderInput`, `UpdateAllocateInventoryOrderItemInput` — 來源: `lib/typings/create-allocate-inventory-order.input.ts`
+- `FindAllocateInventoryOrderInput` (extends `PaginationInput`) — 來源: `lib/typings/find-allocate-inventory-order.input.ts`
+- `DeallocateInventoryOrderItemInput` — 來源: `lib/typings/deallocate-inventory-order.ts`
+
+**其他**
+- `ReclassifyInventoryOrderInput` — 來源: `lib/typings/reclassify-inventory-order.input.ts`
+- `ScrapeInput` — 來源: `lib/typings/scrape.input.ts`
+- `CreateInspectionOrderInput`, `CreateInspectionOrderItemInput` — 來源: `lib/typings/create-inspection-order.input.ts`
+- `PaginationInput = { offset?: number; limit?: number; }` — 來源: `lib/typings/paginations.ts`
+
+---
+
+## Enums / Constants
+
+### `StockStatus` (enum)
+```ts
+enum StockStatus {
+  PENDING_INSPECTION, INSPECTION_FAILED, HELD, IN_TRANSFER,
+  IN_SHIPMENT, ALLOCATED, VENDOR_INVENTORY, CUSTOMER_INVENTORY, FREE
+}
+```
+來源: `lib/constants/stock-status.ts`
+
+### `ChangeType` (enum)
+```ts
+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
+}
+```
+來源: `lib/constants/stock-status.ts`
+
+### `ReceiveInventoryOrderStatus` (enum)
+```ts
+enum ReceiveInventoryOrderStatus { PENDING, PARTIAL_RECEIVED, RECEIVED, REMOVED }
+```
+來源: `lib/typings/find-receive-inventory-order.input.ts`
+
+### `ShipInventoryOrderStatus` (enum)
+```ts
+enum ShipInventoryOrderStatus { PENDING, PARTIAL_SHIPPED, SHIPPED, REMOVED }
+```
+來源: `lib/typings/find-ship-inventory-order.input.ts`
+
+---
+
+## Symbols / DI Tokens
+
+- `WMS_CORE_MODULE_OPTIONS` (`Symbol`) — 提供 `WmsModuleCoreModuleOptions` 給服務注入 — 來源: `lib/typings/core-module-options.ts`
+- 所有 Entity Symbols（`UnitEntity`, `MaterialEntity`, `BatchEntity` 等，上方 Entity 表格中已列出） — 用於在自訂服務中注入對應的 TypeORM Entity class。
+
+---
+
+---
+
+# @rytass/wms-module-graphql
+
+## NestJS Modules
+
+### `WmsModuleGraphqlModule`
+- 用途: WMS GraphQL NestJS 動態模組，整合 Apollo GraphQL、DataLoader 與所有 Resolver/Query/Mutation。是消費端 `apps/api` 唯一需要 `imports: [...]` 的 WMS 模組。
+- 來源: `lib/graphql.module.ts`
+
+**`forRootAsync(options, gqlOptions): DynamicModule`**
+```ts
+static forRootAsync(
+  options: WmsModuleCoreModuleAsyncOptions,
+  // WMSBaseModuleAsyncOptions（Vault/DB 選項）
+  // + WmsModuleCoreModuleOptions:
+  //     defaultLoaderSerialId: string  — 庫存作業預設載具序號
+  //     defaultLoaderTypeKey: string   — 預設載具類型 key
+  //     defaultLocationKey: string     — 預設儲存位置 key
+  gqlOptions: GqlModuleAsyncOptions,
+  // 標準 @nestjs/graphql GqlModuleAsyncOptions，
+  // 例如 autoSchemaFile、context factory 等
+  // 注意：此方法會自動在 context 中注入 loaders（DataLoader instances）:
+  //   loaders.batchSingle — DataLoader<LoaderOptions<T>, T>
+  //   loaders.batchMany   — DataLoader<LoaderOptions<T>, T[]>
+  //   loaders.batchManyWithPagination — DataLoader<LoaderOptionsWithPagination<T>, { items: T[]; total: number }>
+): DynamicModule
+```
+
+---
+
+## Resolvers（`@Resolver()` decorator class）
+
+以下 Resolver 類別處理 GraphQL `@ResolveField`，解析關聯欄位（防止 N+1）：
+
+| Class | 功能 | 來源 |
+|---|---|---|
+| `LoaderResolver` | 解析 loader.type、loader.location、loader.totalQuantity | `lib/resolvers/loader.resolver.ts` |
+| `LoaderTypeResolver` | 解析 loaderType.referencedQuantity | `lib/resolvers/loader-type.resolver.ts` |
+| `LocationResolver` | 解析 location.mapData、location.parent、location.children | `lib/resolvers/location.resolver.ts` |
+| `MaterialResolver` | 解析 material.aggregatedStock、material.materialUnits、material.baseUnit | `lib/resolvers/material.resolver.ts` |
+| `StockResolver` | 解析 stock.material、stock.location、stock.batch | `lib/resolvers/stock.resolver.ts` |
+| `AggregatedStockResolver` | 解析 aggregatedStock.id、.material、.batch、.location、.loader | `lib/resolvers/aggregated-stock.resolver.ts` |
+| `ChangeLogResolver` | 解析 changeLog.material、.location、.batch | `lib/resolvers/change-log.resolver.ts` |
+| `ReceiveInventoryOrderResolver` | 解析 order.items | `lib/resolvers/receive-inventory-order.resolver.ts` |
+| `ReceiveInventoryOrderItemResolver` | 解析 item.material、.batch、.location、.loader、.receivedQuantity | `lib/resolvers/receive-inventory-order.resolver.ts` |
+| `ShipInventoryOrderResolver` | 解析 order.items、order.references | `lib/resolvers/ship-inventory-order.resolver.ts` |
+| `ShipInventoryOrderItemResolver` | 解析 item.material、.batch、.saleId、.saleSerialId、.location、.loader、.shippedQuantity | `lib/resolvers/ship-inventory-order.resolver.ts` |
+| `ShipInventoryOrderReferenceResolver` | 解析 reference 關聯欄位 | `lib/resolvers/ship-inventory-order.resolver.ts` |
+| `TransferOrderResolver` | 解析 order.items、.targetLocation、.targetLoader | `lib/resolvers/transfer-order.resolver.ts` |
+| `TransferOrderItemResolver` | 解析 item.material、.batch、.location、.loader、.saleId、.saleSerialId | `lib/resolvers/transfer-order.resolver.ts` |
+| `HoldInventoryOrderResolver` | 解析 order.items | `lib/resolvers/hold-inventory-order.resolver.ts` |
+| `AllocateInventoryOrderResolver` | 解析 order.items | `lib/resolvers/allocate-inventory-order.resolver.ts` |
+| `TransferCustomerOrderResolver` | 解析 order.items | `lib/resolvers/transfer-customer-order.resolver.ts` |
+| `TransferVendorOrderResolver` | 解析 order.items | `lib/resolvers/transfer-vendor-order.resolver.ts` |
+| `SplitBatchResolver` | 解析 order.items | `lib/resolvers/split-batch.resolver.ts` |
+| `MergeBatchOrderResolver` | 解析 order.items | `lib/resolvers/merge-batch.resolver.ts` |
+| `MapRangeUnionResolver` | 解析 mapRange.location | `lib/resolvers/warehouse-map.resolver.ts` |
+
+---
+
+## Queries（`@Query()` methods，放在 Query class 內）
+
+| Class | GraphQL Query 欄位 | 回傳型別 | 來源 |
+|---|---|---|---|
+| `UnitQuery` | `units` | `[UnitDto]` | `lib/queries/unit.query.ts` |
+| `LoaderQuery` | `loader`, `loaders`, `loaderType`, `loaderTypes`, `loaderUnits`, `availableLoaders` | `LoaderDto`, `Loaders`, `LoaderTypeDto`, `LoaderTypes`, `[LoaderUnitDto]`, `[LoaderDto]` | `lib/queries/loader.query.ts` |
+| `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` |
+| `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` |
+| `TransferOrderQuery` | `transferOrders`, `transferOrder` | `TransferOrders`, `TransferOrderDto` | `lib/queries/transfer-order.query.ts` |
+| `HoldInventoryOrderQuery` | `holdInventoryOrders` | `HoldInventoryOrders` | `lib/queries/hold-inventory-order.query.ts` |
+| `AllocateInventoryOrderQuery` | `allocateInventoryOrders` | `AllocateInventoryOrders` | `lib/queries/allocate-inventory-order.query.ts` |
+| `SaleOrderQuery` | `saleOrderDistinctIds`, `saleOrders` | `[String]` | `lib/queries/sale-order.query.ts` |
+| `WarehouseMapDataQuery` | `mapData` | `MapDataDto` | `lib/queries/warehouse-map.query.ts` |
+
+---
+
+## Mutations（`@Mutation()` methods）
+
+| Class | Mutation 方法 | 說明 | 來源 |
+|---|---|---|---|
+| `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` |
+| `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` |
+| `HoldInventoryOrderMutation` | `createHoldInventoryOrder`, `updateHoldInventoryOrder`, `release` | 凍結庫存 | `lib/mutations/hold-inventory-order.mutation.ts` |
+| `AllocateInventoryOrderMutation` | `createAllocateInventoryOrder`, `updateAllocateInventoryOrder`, `deallocate` | 分配庫存 | `lib/mutations/allocate-inventory-order.mutation.ts` |
+| `TransferCustomerOrderMutation` | `createTransferCustomerOrder`, `updateTransferCustomerOrder`, `returnTransferCustomerOrder` | 客戶調撥 | `lib/mutations/transfer-customer-order.mutation.ts` |
+| `TransferVendorOrderMutation` | `createTransferVendorOrder`, `updateTransferVendorOrder`, `returnTransferVendorOrder` | 供應商調撥 | `lib/mutations/transfer-vendor-order.mutation.ts` |
+| `SplitBatchMutation` | `splitBatch` | 拆批 | `lib/mutations/split-batch.mutation.ts` |
+| `MergeBatchMutation` | `mergeBatch` | 併批 | `lib/mutations/merge-batch.mutation.ts` |
+| `ReclassifyInventoryOrderMutation` | `reclassifyInventoryOrder` | 轉料號 | `lib/mutations/reclassify-inventory-order.mutation.ts` |
+| `ScrapeMutation` | `scrapeMaterials` | 報廢 | `lib/mutations/scrape-order.mutation.ts` |
+| `QualityInspectionOrderMutation` | `inspectMaterials` | 品質檢驗 | `lib/mutations/quality-inspection-order.mutation.ts` |
+| `WarehouseMapMutation` | `updateWarehouseMap` | 倉庫地圖 | `lib/mutations/warehouse-map.mutation.ts` |
+
+---
+
+## GraphQL DTOs（`@ObjectType()` class）
+
+### 主檔 DTOs
+| Class | Paginated Wrapper | 說明 | 來源 |
+|---|---|---|---|
+| `UnitDto` | — | 單位 | `lib/dto/unit.dto.ts` |
+| `LoaderDto` | `Loaders` | 載具 | `lib/dto/loader.dto.ts` |
+| `LoaderTypeDto` | `LoaderTypes` | 載具類型 | `lib/dto/loader-type.dto.ts` |
+| `LoaderUnitDto` | — | 載具單位 | `lib/dto/loader-unit.dto.ts` |
+| `MaterialDto` | `Materials` | 料號 | `lib/dto/material.dto.ts` |
+| `MaterialUnitDto` | `MaterialUnits` | 料號換算單位 | `lib/dto/material-unit.dto.ts` |
+| `LocationDto` | `Locations` | 庫位 | `lib/dto/location.dto.ts` |
+| `StockDto` | `Stocks` | 庫存 | `lib/dto/stock.dto.ts` |
+| `SaleOrderDto` | — | 銷售訂單 | `lib/dto/sale-order.dto.ts` |
+| `BatchDto` | `Batches` | 批號 | `lib/dto/batch.dto.ts` |
+
+### 訂單 DTOs
+| Class | Paginated Wrapper | 說明 | 來源 |
+|---|---|---|---|
+| `ReceiveInventoryOrderDto` | `ReceiveInventoryOrders` | 入庫單 | `lib/dto/receive-inventory-order.dto.ts` |
+| `ReceiveInventoryOrderItemDto` | `ReceiveInventoryOrderItems` | 入庫單明細 | `lib/dto/receive-inventory-order-item.dto.ts` |
+| `ShipInventoryOrderDto` | `ShipInventoryOrders` | 出庫單 | `lib/dto/ship-inventory-order.dto.ts` |
+| `ShipInventoryOrderItemDto` | `ShipInventoryOrderItems` | 出庫單明細 | `lib/dto/ship-inventory-order-item.dto.ts` |
+| `ShipInventoryOrderReferenceDto` | — | 出庫單參考 | `lib/dto/ship-inventory-order-reference.dto.ts` |
+| `TransferOrderDto` | `TransferOrders` | 調撥單 | `lib/dto/transfer-order.dto.ts` |
+| `TransferOrderItemDto` | `TransferOrderItems` | 調撥單明細 | `lib/dto/transfer-order-item.dto.ts` |
+| `TransferCustomerOrderDto` | `TransferCustomerOrders` | 客戶調撥單 | `lib/dto/transfer-customer-order.dto.ts` |
+| `TransferCustomerOrderItemDto` | `TransferCustomerOrderItems` | 客戶調撥單明細 | `lib/dto/transfer-customer-order-item.dto.ts` |
+| `TransferVendorOrderDto` | `TransferVendorOrders` | 供應商調撥單 | `lib/dto/transfer-vendor-order.dto.ts` |
+| `TransferVendorOrderItemDto` | `TransferVendorOrderItems` | 供應商調撥單明細 | `lib/dto/transfer-vendor-order-item.dto.ts` |
+| `HoldInventoryOrderDto` | `HoldInventoryOrders` | 凍結庫存單 | `lib/dto/hold-inventory-order.dto.ts` |
+| `HoldInventoryOrderItemDto` | `HoldInventoryOrderItems` | 凍結庫存單明細 | `lib/dto/hold-inventory-order-item.dto.ts` |
+| `AllocateInventoryOrderDto` | `AllocateInventoryOrders` | 分配庫存單 | `lib/dto/allocate-inventory-order.dto.ts` |
+| `AllocateInventoryOrderItemDto` | — | 分配庫存單明細 | `lib/dto/allocate-inventory-order-item.dto.ts` |
+| `SplitBatchOrderDto` | — | 拆批單 | `lib/dto/split-batch-order.dto.ts` |
+| `SplitBatchOrderItemDto` | — | 拆批單明細 | `lib/dto/split-batch-order.dto.ts` |
+| `MergeBatchOrderDto` | — | 併批單 | `lib/dto/merge-batch-order.dto.ts` |
+| `MergeBatchOrderItemDto` | — | 併批單明細 | `lib/dto/merge-batch-order.dto.ts` |
+| `ReclassifyInventoryOrderDto` | — | 轉料號單 | `lib/dto/reclassify-inventory-order.dto.ts` |
+| `ReclassifyInventoryOrderItemDto` | — | 轉料號單明細 | `lib/dto/reclassify-inventory-order.dto.ts` |
+| `QualityInspectionOrderDto` | `QualityInspectionOrders` | 品質檢驗單 | `lib/dto/quality-inspection-order.dto.ts` |
+| `QualityInspectionOrderItemDto` | — | 品質檢驗單明細 | `lib/dto/quality-inspection-order-item.dto.ts` |
+| `ScrapeOrderDto` | `ScrapeOrders` | 報廢單 | `lib/dto/scrape-order.dto.ts` |
+| `ScrapeOrderItemDto` | `ScrapeOrderItems` | 報廢單明細 | `lib/dto/scrape-order-item.dto.ts` |
+| `MapPolygonRangePointDto` | — | 地圖多邊形頂點 | `lib/dto/warehouse-map.dto.ts` |
+| `MapBackgroundDto` | — | 地圖背景圖層 | `lib/dto/warehouse-map.dto.ts` |
+
+---
+
+## Input Types（`@InputType()` / `@ArgsType()` class）
+
+位於 `lib/inputs/`，共 70+ 個。以下列出主要類別：
+
+**Pagination**
+- `PaginationArgs` (`@ArgsType`) — `{ offset?, limit? }` — 來源: `lib/inputs/pagination.args.ts`
+
+**載具**
+- `CreateLoaderArgs`, `UpdateLoaderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-loader.args.ts`
+- `CreateLoaderTypeArgs`, `UpdateLoaderTypeArgs` (`@ArgsType`) — 來源: `lib/inputs/create-loader-type.args.ts`
+- `FindLoaderArgs`, `FindLoaderTypeArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-loader.args.ts`, `find-loader-type.args.ts`
+
+**料號**
+- `CreateMaterialArgs`, `UpdateMaterialArgs` (`@ArgsType`) — 來源: `lib/inputs/create-material.args.ts`
+- `CreateMaterialUnitArgs` (`@InputType`) — 來源: `lib/inputs/create-material-unit.args.ts`
+- `FindMaterialArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-material.args.ts`
+
+**庫位**
+- `CreateLocationArgs`, `UpdateLocationArgs` (`@ArgsType`) — 來源: `lib/inputs/create-location.args.ts`
+- `FindLocationArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-location.args.ts`
+
+**庫存**
+- `FindStockArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-stock.args.ts`
+- `DateRangeArgs` (`@InputType`) — 來源: `lib/inputs/date-range.args.ts`
+
+**批號**
+- `FindBatchArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-batch.args.ts`
+- `SplitBatchArgs`, `SplitBatchItemInput` — 來源: `lib/inputs/split-batch.args.ts`
+- `MergeBatchArgs`, `MergeBatchItemInput` — 來源: `lib/inputs/merge-batch.args.ts`
+
+**入庫單**
+- `CreateReceiveInventoryOrderArgs`, `UpdateReceiveInventoryOrderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-receive-inventory-order.args.ts`
+- `CreateReceiveInventoryOrderItemArgs`, `UpdateReceiveInventoryOrderItemArgs` (`@InputType`) — 來源: `lib/inputs/create-receive-inventory-order-item.args.ts`
+- `FindReceiveInventoryOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-receive-inventory-order.args.ts`
+- `ReceiveOrderArgs` (`@InputType`) — 來源: `lib/inputs/receive-order.args.ts`
+
+**出庫單**
+- `CreateShipInventoryOrderArgs`, `UpdateShipInventoryOrderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-ship-inventory-order.args.ts`
+- `CreateShipInventoryOrderItemArgs`, `UpdateShipInventoryOrderItemArgs` (`@InputType`) — 來源: `lib/inputs/create-ship-inventory-order-item.args.ts`
+- `CreateShipInventoryOrderReferenceArgs`, `UpdateShipInventoryOrderReferenceArgs` (`@InputType`) — 來源: `lib/inputs/create-ship-inventory-order-reference.args.ts`
+- `FindShipInventoryOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-ship-inventory-order.args.ts`
+- `ShipOrderArgs` (`@InputType`) — 來源: `lib/inputs/ship-order.args.ts`
+- `CancelShipOrderArgs` (`@InputType`) — 來源: `lib/inputs/cancel-ship-order.args.ts`
+
+**調撥**
+- `CreateTransferOrderArgs`, `UpdateTransferOrderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-transfer-order.args.ts`
+- `CreateTransferOrderItemArgs`, `UpdateTransferOrderItemArgs` (`@InputType`) — 來源: `lib/inputs/create-transfer-order-item.args.ts`
+- `FindTransferOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-transfer-order.args.ts`
+- `TransferOrderArgs` (`@InputType`) — 來源: `lib/inputs/transfer-order.args.ts`
+- `CancelTransferOrderArgs` (`@InputType`) — 來源: `lib/inputs/cancel-transfer-order.args.ts`
+- `CreateTransferCustomerOrderArgs`, `UpdateTransferCustomerOrderArgs`, `CreateTransferCustomerOrderItemArgs`, `UpdateTransferCustomerOrderItemArgs` — 來源: `lib/inputs/create-transfer-customer-order*.args.ts`
+- `CreateTransferVendorOrderArgs`, `UpdateTransferVendorOrderArgs`, `CreateTransferVendorOrderItemArgs`, `UpdateTransferVendorOrderItemArgs` — 來源: `lib/inputs/create-transfer-vendor-order*.args.ts`
+- `ReturnTransferCustomerOrderArgs`, `ReturnTransferVendorOrderArgs` — 來源: `lib/inputs/return-transfer-*-order.args.ts`
+
+**凍結/分配**
+- `CreateHoldInventoryOrderArgs`, `UpdateHoldInventoryOrderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-hold-inventory-order.args.ts`
+- `CreateHoldInventoryOrderItemArgs`, `UpdateHoldInventoryOrderItemArgs` (`@InputType`) — 來源: `lib/inputs/create-hold-inventory-order-item.args.ts`
+- `FindHoldInventoryOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-hold-inventory-order.args.ts`
+- `ReleaseOrderArgs` (`@InputType`) — 來源: `lib/inputs/release-order.args.ts`
+- `CreateAllocateInventoryOrderArgs`, `UpdateAllocateInventoryOrderArgs` (`@ArgsType`) — 來源: `lib/inputs/create-allocate-inventory-order.args.ts`
+- `CreateAllocateInventoryOrderItemArgs`, `UpdateAllocateInventoryOrderItemArgs` (`@InputType`) — 來源: `lib/inputs/create-allocate-inventory-order-item.args.ts`
+- `FindAllocateInventoryOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-allocate-inventory-order.args.ts`
+- `DeallocateOrderArgs` (`@InputType`) — 來源: `lib/inputs/deallocate-order.args.ts`
+
+**其他**
+- `ReclassifyInventoryOrderArgs`, `ReclassifyInventoryOrderItemInput` — 來源: `lib/inputs/reclassify-inventory-order.args.ts`
+- `ScrapeOrderArgs`, `ScrapeOrderItemInput` — 來源: `lib/inputs/scrape-order.args.ts`
+- `CreateQualityInspectionOrderArgs`, `CreateQualityInspectionOrderItemArgs` — 來源: `lib/inputs/create-quality-inspection-order.args.ts`
+- `FindSaleOrderArgs` (extends `PaginationArgs`) — 來源: `lib/inputs/find-sale-order.args.ts`
+- `MapBackgroundInput`, `MapPolygonRangePointInput`, `MapRangeInput` — 來源: `lib/inputs/update-warehouse-map.args.ts`
+
+---
+
+## DataLoader Helpers
+
+### `LoaderService` (`@Injectable()`)
+- 用途: LRU 快取 DataLoader 工廠，防止 GraphQL N+1 查詢。
+- 來源: `lib/helpers/loader.service.ts`
+
+```ts
+class LoaderService {
+  batchEntity<T>(): DataLoader<LoaderOptions<T>, T>
+  batchEntities<T>(): DataLoader<LoaderOptions<T>, T[]>
+  batchEntitiesWithPagination<T>(): DataLoader<LoaderOptionsWithPagination<T>, { items: T[]; total: number }>
+}
+```
+
+### `LoaderOptions<K>` (interface)
+```ts
+interface LoaderOptions<K> {
+  __entity: ObjectLiteral;         // TypeORM entity class
+  __from: FindOptionsWhere<K>;     // 查詢條件（主鍵）
+  __conditions?: (qb: SelectQueryBuilder) => SelectQueryBuilder; // 可選 query builder hook
+  __seed?: string;                 // cache key 用的額外 seed
+  __pagination?: { offset: number; limit: number };
+}
+```
+來源: `lib/helpers/loader.service.ts`
+
+### `LoaderOptionsWithPagination<K>` (interface)
+- 繼承 `LoaderOptions<K>`，`__pagination` 為必填。
+- 來源: `lib/helpers/loader.service.ts`
+
+### `LoaderType<T>` (interface)
+```ts
+interface LoaderType<T> {
+  loaders: {
+    batchMany: DataLoader<LoaderOptions<T>, T[]>;
+    batchSingle: DataLoader<LoaderOptions<T>, T>;
+    batchManyWithPagination: DataLoader<LoaderOptionsWithPagination<T>, { items: T[]; total: number }>;
+  };
+}
+```
+- 用途: 定義 GraphQL context 中 `loaders` 欄位的型別。
+- 來源: `lib/helpers/dataloader.type.ts`
+
+### `HelperModule`
+- 用途: `@Global()` NestJS 模組，提供 `LoaderService`；由 `WmsModuleGraphqlModule.forRootAsync` 自動 import。
+- 來源: `lib/helpers/helper.module.ts`
+
+### `QueryPath`
+- 用途: NestJS param decorator，從 GraphQL ExecutionContext 萃取目前 resolver 路徑字串（如 `"materials/aggregatedStock"`）。
+- 來源: `lib/helpers/query-path.ts`
+
+---
+
+---
+
+# @rytass/wms-module-react
+
+> **Public API vs Library Internals**: this package exposes a curated public barrel
+> (`src/index.ts`). Only the symbols listed under **Public API (in barrel)** below can be
+> imported directly from `@rytass/wms-module-react`. Everything listed under
+> **Library Internals** exists in the source tree but is **not** barrel-exported; attempting to
+> import those symbols will result in a module-not-found / tree-shaker error.
+
+---
+
+## Public API (in barrel)
+
+### Apollo Client
+
+#### `createApolloClient(): ApolloClient<NormalizedCacheObject>`
+- Purpose: Factory function that creates an Apollo client with error link, auth link (extensible for Authorization headers), and HttpLink pointing at `/graphql`.
+- Source: `apollo/index.ts`
+
+```ts
+export const createApolloClient: () => ApolloClient<NormalizedCacheObject>
+```
+
+As of 0.1.2, this factory takes **no parameters** and returns a fresh instance with `/graphql`
+as the endpoint URI (the same as the default singleton). A URL/header override parameter is
+planned for 0.2.0 (semver minor, non-breaking addition).
+
+#### `ApolloClient` (named export — singleton instance)
+- Purpose: The pre-built Apollo client singleton created by `createApolloClient()`. Re-exported
+  as a **named** export (`export { ..., default as ApolloClient }`), so consumers must use a
+  **named import**.
+- Source: `apollo/index.ts`
+
+```ts
+// Correct — named import:
+import { ApolloClient, createApolloClient } from '@rytass/wms-module-react';
+<ApolloProvider client={ApolloClient}>...</ApolloProvider>
+
+// Wrong — default import (will be undefined):
+// import ApolloClient from '@rytass/wms-module-react';
+```
+
+---
+
+### Providers (Context Providers)
+
+#### `DialogProvider`
+- Purpose: Global confirmation dialog Context Provider. Pair with `useDialog()` (internal) to
+  open modal confirmation dialogs from any descendant component.
+- Source: `components/dialog/DialogProvider.tsx`
+
+```tsx
+import { DialogProvider } from '@rytass/wms-module-react';
+<DialogProvider><App /></DialogProvider>
+```
+
+#### `ModalProvider`
+- Purpose: Global programmable Modal Context Provider.
+- Source: `components/modal/ModalProvider.tsx`
+
+```tsx
+import { ModalProvider } from '@rytass/wms-module-react';
+<ModalProvider><App /></ModalProvider>
+```
+
+#### `InventoryActionsProvider`
+- Purpose: Global context for managing the list of selected inventory items and the current
+  operation type. Required by all inventory action flows.
+- Source: `components/inventoryActions/InventoryActionsProvider.tsx`
+
+```tsx
+import { InventoryActionsProvider } from '@rytass/wms-module-react';
+<InventoryActionsProvider><App /></InventoryActionsProvider>
+```
+
+---
+
+### Page-level Components (for Next.js Pages-Router shells)
+
+All 11 page components take no props (fully self-contained) and are default-exported from their
+source file, re-exported as named exports from the barrel.
+
+| Named Export              | Route                       |
+|---------------------------|-----------------------------|
+| `ChangeHistory`           | `/change-history`           |
+| `InventoryCount`          | `/inventory-count`          |
+| `InventoryList`           | `/inventory-list`           |
+| `InventoryMovement`       | `/inventory-movement`       |
+| `LabelSearch`             | `/label-search`             |
+| `LoadersManagement`       | `/loaders-management`       |
+| `LocationsManagement`     | `/locations-management`     |
+| `Maps`                    | `/maps`                     |
+| `MaterialsManagement`     | `/materials-management`     |
+| `ReceiveInventoryOrders`  | `/receive-inventory-orders` |
+| `ShipInventoryOrders`     | `/ship-inventory-orders`    |
+
+```tsx
+import { MaterialsManagement } from '@rytass/wms-module-react';
+export default function Page() { return <MaterialsManagement />; }
+```
+
+---
+
+### Sub-page Components (for dynamic route shells)
+
+| Named Export                 | Dynamic Route                                    |
+|------------------------------|--------------------------------------------------|
+| `CreateLoader`               | `/loaders-management/create`                     |
+| `EditReceiveInventoryOrder`  | `/receive-inventory-orders/[id]/edit`            |
+| `ViewReceiveInventoryOrder`  | `/receive-inventory-orders/[id]/view`            |
+| `EditShipInventoryOrder`     | `/ship-inventory-orders/[id]/edit`               |
+| `ViewShipInventoryOrder`     | `/ship-inventory-orders/[id]/view`               |
+| `EditTransferOrder`          | `/inventory-movement/transfer-order/[id]`        |
+
+---
+
+### Generic Hooks
+
+#### `useRoutes()`
+- Source: `hooks/useRoutes.ts`
+```ts
+useRoutes(): Array<{
+  title: string;
+  icon: IconDefinition;
+  href?: NextPath;
+  children?: Array<{ title: string; href: NextPath }>;
+}>
+```
+Returns the full WMS sidebar navigation tree. Titles are hardcoded zh-TW strings; there is
+no i18n mechanism in 0.1.x (see §13.9 in the integration guide for workarounds).
+
+#### `useTablePageState(usePageQs?: boolean)`
+- Source: `hooks/useTablePagination.ts`
+```ts
+useTablePageState(usePageQs?: boolean): {
+  page: number;
+  setPage: (p: number) => void;
+  limit: number;
+  setLimit: (limit: number) => void;
+  offset: number; // (page - 1) * limit
+}
+```
+
+#### `useTablePageTotal(params)`
+- Source: `hooks/useTablePagination.ts`
+```ts
+useTablePageTotal(params: {
+  total?: number;
+  page: number;
+  setPage: (p: number) => void;
+  filterValues: unknown[];
+}): { pageTotal: number | undefined }
+```
+
+#### `useFormCancel(params)`
+- Source: `hooks/useFormCancel.ts`
+```ts
+useFormCancel(params: { onCancel?: () => void }): () => Promise<void>
+```
+
+#### `useFetchMoreOptions<T>(params)`
+- Source: `hooks/useSelectorOptions.ts`
+```ts
+useFetchMoreOptions<T>(params: {
+  fetchData: LazyQueryExecFunction;
+  getNewOptions: (data: T | undefined) => SelectValue[];
+  otherArgs?: Record<string, unknown>;
+  searchByDescription?: boolean;
+}): {
+  currentOptions: SelectValue[];
+  setOptions: Dispatch<SetStateAction<SelectValue[]>>;
+  onVisibilityChange: (open: boolean) => void;
+  onSearch: (input: string) => void;
+  onClear: () => void;
+  onReachBottom: () => void;
+}
+```
+
+#### `useInsertOption(setOptions)`
+- Source: `hooks/useSelectorOptions.ts`
+```ts
+useInsertOption(
+  setOptions: Dispatch<SetStateAction<SelectValue<string>[]>>
+): (text: string, currentOptions: SelectValue[]) => SelectValue[]
+```
+
+#### `useSortTable()`
+- Source: `hooks/useSortTable.ts`
+```ts
+useSortTable(): {
+  sortOrder: { key: string; sortOrder: SortOrder } | null;
+  setSortOrder: Dispatch;
+  getCurrentSortOrder: (key: string) => SortOrder | undefined;
+  onSort: (key: string, order: SortOrder) => void;
+}
+```
+
+#### `useColumnWidthPersistence<T>(tableKey, columns)`
+- Source: `hooks/useColumnWidthPersistence.ts`
+```ts
+useColumnWidthPersistence<T extends TableDataSource>(
+  tableKey: string,
+  columns: TableColumn<T>[]
+): {
+  containerRef: RefObject<HTMLDivElement>;
+  columnsWithWidths: TableColumn<T>[];
+}
+```
+
+#### `usePreviousValue<T>(value: T): T`
+- Source: `hooks/usePreviousValue.ts`
+
+---
+
+### Route Utilities
+
+#### `NextPath` (enum)
+- Source: `utils/nextpath.ts`
+- Generated by `yarn pages` from the `apps/client/src/pages` tree. **Renaming or removing
+  existing enum values is a breaking change** for downstream consumers.
+
+```ts
+enum NextPath {
+  CHANGEHISTORY                       = "/change-history",
+  INVENTORYCOUNT                      = "/inventory-count",
+  INVENTORYLIST                       = "/inventory-list",
+  INVENTORYMOVEMENT                   = "/inventory-movement",
+  INVENTORYMOVEMENT_TRANSFERORDER_ID  = "/inventory-movement/transfer-order/[id]",
+  LABELSEARCH                         = "/label-search",
+  LOADERSMANAGEMENT                   = "/loaders-management",
+  LOADERSMANAGEMENT_CREATE            = "/loaders-management/create",
+  LOCATIONSMANAGEMENT                 = "/locations-management",
+  MAPS                                = "/maps",
+  MATERIALSMANAGEMENT                 = "/materials-management",
+  RECEIVEINVENTORYORDERS              = "/receive-inventory-orders",
+  RECEIVEINVENTORYORDERS_ID_EDIT      = "/receive-inventory-orders/[id]/edit",
+  RECEIVEINVENTORYORDERS_ID_VIEW      = "/receive-inventory-orders/[id]/view",
+  SHIPINVENTORYORDERS                 = "/ship-inventory-orders",
+  SHIPINVENTORYORDERS_ID_EDIT         = "/ship-inventory-orders/[id]/edit",
+  SHIPINVENTORYORDERS_ID_VIEW         = "/ship-inventory-orders/[id]/view",
+}
+```
+
+#### `nextDynamicPath(nextPath, replaceDynamicPaths)`
+- Source: `utils/path.ts`
+```ts
+nextDynamicPath(
+  nextPath: NextPath,
+  replaceDynamicPaths: Record<string, string>
+): string
+// e.g. nextDynamicPath(NextPath.RECEIVEINVENTORYORDERS_ID_VIEW, { '[id]': 'abc' })
+//      => "/receive-inventory-orders/abc/view"
+```
+
+---
+
+### Icons (re-export)
+
+`export * from './icons'` — re-exports all custom WMS icon components:
+`UnlinkIcon`, `CarIcon`, `SplitIcon`, `MergeIcon`, `UpRightIcon`, `TransferIcon`, `WaitIcon`.
+
+---
+
+### Generated GraphQL Operations (`graphql/generated/.graphql`)
+
+`export * from './graphql/generated/.graphql'` — re-exports everything from the
+generated file (committed, shipped with the package). Consumers do **not** need to run
+codegen themselves.
+
+The generated file exports four categories of symbols:
+
+#### 1. DocumentNode Constants
+
+Used as the first argument to `useQuery` / `useMutation` from `@apollo/client/react`.
+
+**Queries (41)**:
+`AggregatedStocksDocument`, `AggregatedStocksForInventoryActionsDocument`, `AllocateInventoryOrdersDocument`, `AvailableLoadersDocument`, `BatchesDocument`, `BatchOptionsDocument`, `ChangeLogsDocument`, `FullReceiveInventoryOrdersDocument`, `FullShipInventoryOrdersDocument`, `HoldInventoryOrdersDocument`, `LoaderDocument`, `LoaderOptionsDocument`, `LoadersDocument`, `LoaderTypeDocument`, `LoaderTypeOptionsDocument`, `LoaderTypesDocument`, `LoaderUnitsDocument`, `LocationDocument`, `LocationOptionsDocument`, `LocationsDocument`, `MapDataDocument`, `MaterialDocument`, `MaterialOptionsDocument`, `MaterialsDocument`, `ReceiveInventoryOrderDocument`, `ReceiveInventoryOrderOptionsDocument`, `ReceiveInventoryOrderPendingOptionsDocument`, `ReceiveInventoryOrdersDocument`, `SaleOrderDistinctIdsDocument`, `SaleOrdersDocument`, `ShipInventoryOrderDocument`, `ShipInventoryOrderOptionsDocument`, `ShipInventoryOrderPendingOptionsDocument`, `ShipInventoryOrdersDocument`, `StockDocument`, `StocksDocument`, `StocksGroupedByMaterialDocument`, `TransferOrderDocument`, `TransferOrderOptionsDocument`, `TransferOrdersDocument`, `UnitsDocument`
+
+**Mutations (34)**:
+`CancelShipDocument`, `CancelTransferDocument`, `CreateAllocateInventoryOrderDocument`, `CreateBatchLoaderDocument`, `CreateHoldInventoryOrderDocument`, `CreateLoaderTypeDocument`, `CreateLocationDocument`, `CreateMaterialDocument`, `CreateReceiveInventoryOrderDocument`, `CreateShipInventoryOrderDocument`, `CreateTransferCustomerOrderDocument`, `CreateTransferOrderDocument`, `CreateTransferVendorOrderDocument`, `DeallocateDocument`, `InspectMaterialsDocument`, `MergeBatchDocument`, `ReceiveDocument`, `ReclassifyInventoryOrderDocument`, `ReleaseDocument`, `ReturnTransferCustomerOrderDocument`, `ReturnTransferVendorOrderDocument`, `ScrapeMaterialsDocument`, `ShipDocument`, `SplitBatchDocument`, `TransferDocument`, `UpdateHoldInventoryOrderDocument`, `UpdateLoaderDocument`, `UpdateLoaderTypeDocument`, `UpdateLocationDocument`, `UpdateMaterialDocument`, `UpdateReceiveInventoryOrderDocument`, `UpdateShipInventoryOrderDocument`, `UpdateTransferOrderDocument`, `UpdateWarehouseMapDocument`
+
+#### 2. Fragment Types
+
+42 fragment types named `<Domain>Fragment`, used for prop type annotations in custom components:
+
+`AggregatedStockFragment`, `AllocateInventoryOrderFragment`, `AllocateInventoryOrderItemFragment`, `BatchFragment`, `ChangeLogFragment`, `HoldInventoryOrderFragment`, `HoldInventoryOrderItemFragment`, `LoaderFragment`, `LoaderTypeFragment`, `LoaderWithTotalFragment`, `LocationFragment`, `SimpleLocationFragment`, `MapDataFragment`, `MaterialFragment`, `SimpleMaterialFragment`, `MaterialWithAggregatedStockFragment`, `MaterialUnitFragment`, `MergeBatchOrderItemFragment`, `QualityInspectionOrderFragment`, `QualityInspectionOrderItemFragment`, `ReceiveInventoryOrderFragment`, `ReceiveInventoryOrderItemFragment`, `SimpleReceiveInventoryOrderFragment`, `ReclassifyInventoryOrderItemFragment`, `ScrapeOrderFragment`, `ScrapeOrderItemFragment`, `ShipInventoryOrderFragment`, `ShipInventoryOrderItemFragment`, `ShipInventoryOrderReferenceFragment`, `SimpleShipInventoryOrderFragment`, `SimpleStockFragment`, `StockFragment`, `StockInActionsFragment`, `SplitBatchOrderItemFragment`, `SimplerAllocateInventoryOrderFragment`, `SimpleTransferOrderFragment`, `TransferCustomerOrderFragment`, `TransferCustomerOrderItemFragment`, `TransferOrderFragment`, `TransferOrderItemFragment`, `TransferVendorOrderFragment`, `TransferVendorOrderItemFragment`, `UnitFragment`
+
+#### 3. Query/Mutation Type Pairs
+
+Each DocumentNode constant has paired TypeScript types (75 pairs total, 150 types):
+- `LoadersQuery` + `LoadersQueryVariables`
+- `CreateMaterialMutation` + `CreateMaterialMutationVariables`
+- etc.
+
+#### 4. Schema Types and Enums
+
+All GraphQL schema DTO types and enums are re-exported:
+
+Schema types: `AggregatedStockDto`, `AllocateInventoryOrderDto`, `BatchDto`, `ChangeLogDto`, `HoldInventoryOrderDto`, `LoaderDto`, `LoaderTypeDto`, `LoaderUnitDto`, `Loaders`, `LocationDto`, `Locations`, `MapDataDto`, `MaterialDto`, `Materials`, `ReceiveInventoryOrderDto`, `ReceiveInventoryOrders`, `ShipInventoryOrderDto`, `ShipInventoryOrders`, `StockDto`, `Stocks`, `TransferOrderDto`, and many more.
+
+Enums: `ChangeType`, `LoaderUnit`, `MapRangeType`, `ReceiveInventoryOrderStatus`, `ShipInventoryOrderStatus`, `StockStatus`
+
+---
+
+## Library Internals (NOT exported from barrel)
+
+> **Warning**: The following symbols **exist in the source tree** of `@rytass/wms-module-react`
+> but are **not exported from the package barrel** (`src/index.ts`). Attempting to import them
+> directly from `@rytass/wms-module-react` will fail with `Module not found` or
+> `is not exported from module`.
+>
+> They are listed here for reference — developers inspecting the source or planning to fork/patch
+> the lib may find this useful. Some may be promoted to public exports via subpath exports or in
+> a future 0.2.0 release.
+
+### Internal Form Field Components (`components/fields/`)
+
+These field components are used internally by the page components but are not barrel-exported.
+A consumer cannot import `{ InputField }` from `@rytass/wms-module-react`.
+
+| Component                    | Description                                      |
+|------------------------------|--------------------------------------------------|
+| `BaseField`                  | Generic form field wrapper (label + error)       |
+| `InputField`                 | Text input field                                 |
+| `NumberInputField`           | Numeric input field                              |
+| `DateField`                  | Date picker field (Dayjs)                        |
+| `RadioField`                 | Radio button field                               |
+| `SelectInputField`           | Searchable select field                          |
+| `SingleSelectField`          | Single-select field                              |
+| `SingleSelectByIdField`      | Single-select by ID                              |
+| `SingleAutoCompleteField`    | Auto-complete single select                      |
+| `SingleAutoCompleteByIdField`| Auto-complete by ID                              |
+| `YesNoField`                 | Yes/No toggle field                              |
+| `MaterialsField`             | Material picker (with fetch/search)              |
+| `UnitsField`                 | Unit picker                                      |
+| `BatchesField`               | Batch picker                                     |
+| `LoadersField`               | Loader picker                                    |
+| `LoaderTypesField`           | Loader type picker                               |
+| `LoaderUnitsField`           | Loader unit picker                               |
+| `LocationsField`             | Location picker                                  |
+| `AvailableLoadersField`      | Available loader picker (for inventory actions)  |
+| `ReceiveInventoryOrdersField`| Receive order picker                             |
+| `ShipInventoryOrdersField`   | Ship order picker                                |
+| `TransferOrdersField`        | Transfer order picker                            |
+| `SaleOrdersField`            | Sale order picker                                |
+| `SaleOrderIdsField`          | Sale order ID picker                             |
+| `MembersField`               | Member picker                                    |
+
+### Internal Form Wrappers
+
+`FormWrapper`, `FormModalWrapper`, `FormDrawerWrapper` — React Hook Form wrappers used
+internally by page components.
+
+### Internal Layout Wrappers
+
+`PageWrapper`, `SectionWrapper`, `TableWrapper`, `FilterWrapper` — layout containers used
+internally. WMS pages expect full-viewport rendering via these wrappers; embedding a page
+in a smaller container is not officially supported (see §13.10 in the integration guide).
+
+### Internal UI Components
+
+`PageTabs`, `FormActionButtons`, `Loading`, `InventoryActionDrawers`
+
+### Internal Hooks (not in barrel)
+
+The following hooks exist in source but are internal implementation details:
+
+- `useInventoryActions()` — reads `InventoryActionsContext`; used by page components internally
+- `useAddInventories()` — inventory selection logic
+- `useInventorySignature()` — per-inventory-item signature reader
+- `useDialog()` — opens the global confirmation dialog (requires `DialogProvider`)
+- `useModal()` — opens the global modal (requires `ModalProvider`)
+
+### Internal Constants and Utilities (not in barrel)
+
+`BASE_UNIT`, `DEFAULT_MAP_DATA_KEY`, `DEFAULT_MAP_DATA_NAME`, `YesOrNo` (enum),
+`UnitOptionsType`, `yesNoName`, `yesNoOptions`, `formatKeyName`, `changeTypeName`,
+`shipInventoryOrderStatusName`, `shipInventoryOrderStatusOptions`,
+`receiveInventoryOrderStatusName`, `receiveInventoryOrderStatusOptions`,
+`uploadFile`, `aggregatedStockColumns`
+
+---
+
+以上為三個 lib 的完整 export API 名單。
+
+**關鍵路徑摘要：**
+- `/Users/fantasyatelier/Repositories/WMS-Module/libs/core/src/index.ts`
+- `/Users/fantasyatelier/Repositories/WMS-Module/libs/graphql/src/index.ts`
+- `/Users/fantasyatelier/Repositories/WMS-Module/libs/react/src/index.ts`