@rytass/wms-module-graphql 0.11.0 → 0.12.0

package/README.md

@@ -181,6 +181,14 @@ back the flow:
 - **`startInventoryCount` snapshots eight attributes per line** — `held`, `inShipment`,
   `inspectionResult`, `transferId`, `vendorId`, `customerId`, `saleId`, `saleSerialId` —
   so the sheet keeps showing the world the variance is measured against, not today's.
+- **`createInventoryCountOrder` takes an optional `createdBy`**, like the other order
+  families; it is what the list shows as 建立者 and what its `createdBy` filter matches.
+- **Every count mutation is one transaction.** Creating, updating, starting, counting,
+  adding or removing a line, resetting, cancelling and settling each commit or roll back
+  as a whole, and each accepts an `EntityManager` to join a transaction you already hold.
+- **`settleInventoryCount` re-checks the snapshot first.** If a scoped line's
+  `bookQuantity` no longer matches the ledger — something wrote around the lock — it
+  refuses with a `409 Conflict` instead of posting a variance against stale books.
 
 ### ⚠️ Starting a count locks its locations
 
@@ -198,8 +206,17 @@ stock events use — so it covers resolvers **and** direct service calls, includ
 integration code. Without it the book snapshot the variance is measured against would go
 stale and settlement would silently write off somebody else's legitimate movement.
 
+Both ends of a movement count. A transfer item names a source and a destination, and the
+lock refuses a change on either, so a transfer **into** a counted location is refused as
+well — at reservation, completion and cancellation alike, because a change row cannot tell
+those apart.
+
 Settling or cancelling the count releases the lock.
 
+➡️ **Per-operation usage (繁體中文): [`docs/inventory-count.md`](./docs/inventory-count.md)** —
+every query and mutation with arguments, preconditions, errors and examples.
+
+
 ## Events & Hooks
 
 Intervene in and get notified about mutations. Every root mutation carries a typed **operation event** (`material.created`, `ship-inventory-order.shipped`, `inventory-count-order.settled`, …) and fans out **stock domain events** (`stock.allocated`, `stock.shipped`, `stock.count-gained`, …) driven by the `ChangeType` state machine. Wire two opt-in hook points via `forRootAsync`:
@@ -288,6 +305,8 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 | [`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/inventory-count.md`](./docs/inventory-count.md) | 盤點 API 使用說明（繁體中文）— 3 支 query、9 支 mutation 的參數、前置狀態、錯誤與範例 |
+
 | [`docs/api-reference.md`](./docs/api-reference.md) | Complete export catalog with signatures and usage examples |
 
 GitHub hosted links (always up-to-date):

package/docs/README.md

@@ -9,7 +9,8 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | [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`. |
+| [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 the three packages. |
+| [盤點 API 使用說明](./inventory-count.md)       | Inventory counting, operation by operation (繁體中文): the 3 queries and 9 mutations with arguments, status preconditions, errors, examples, the location lock and the events each one emits. |
 
 ## Quick links
 
@@ -29,11 +30,13 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | 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)          |
+| Drive an inventory count (盤點) end to end              | [盤點 API 使用說明](./inventory-count.md)                              |
+
 | 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) |
 
 ## Versioning
 
-These documents track the **latest published versions** — `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6` as of this writing. Anything in `main` that has not yet been released is marked clearly inline; otherwise assume the documented signature matches the current npm-published library.
+These documents track the **latest published versions** of the three packages. Anything in `main` that has not yet been released is marked clearly inline; otherwise assume the documented signature matches the current npm-published library.
 
 `@rytass/wms-module-graphql@0.3.0` introduced **breaking changes** to `WmsModuleGraphqlModule.forRootAsync` (single argument; consumer now registers their own `GraphQLModule.forRootAsync`). The integration guide and API reference reflect the post-0.3.0 surface — see each package's `CHANGELOG.md` for the full breaking change list when upgrading.

package/docs/api-reference.md

@@ -6,7 +6,7 @@ Complete export catalog for the three publishable libraries:
 - `@rytass/wms-module-graphql` — GraphQL resolvers, DTOs, DataLoader helpers
 - `@rytass/wms-module-react` — React components, hooks, Apollo client, GraphQL operations
 
-Current versions: **0.3.0** (`@rytass/wms-module-graphql`), **0.1.6** (`@rytass/wms-module-core`, `@rytass/wms-module-react`).
+本文件不另記版本號；各 package 的現行版本以其 `package.json` 與 `CHANGELOG.md` 為準。
 
 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`.
 
@@ -69,7 +69,7 @@ static forRootAsync(
 
 ## TypeORM Entities（Extensions — 訂單與作業）
 
-同樣每個都有 Symbol + EntityClass 雙匯出，共 37 個：
+同樣每個都有 Symbol + EntityClass 雙匯出（依領域列出，並非逐一窮舉；完整清單見 core 的 `lib/models/extensions/index.ts`）：
 
 **盤點單 (Inventory Count Order)**
 - `InventoryCountOrderEntity` / `InventoryCountOrderEntityClass` — 盤點單主檔（`countDate` 為盤差記帳基準日）
@@ -272,7 +272,7 @@ enum ChangeType {
   VENDOR_TRANSFERRED, VENDOR_RETURNED, HELD, RELEASED,
   CUSTOMER_HELD, CUSTOMER_RETURNED, SPLITTED, MERGED,
   ALLOCATED, DEALLOCATED, RECLASSIFIED, SCRAPED,
-  COUNT_GAINED, COUNT_LOST
+  COUNT_GAINED, COUNT_LOST, ISSUED, RETURNED, CONSUMED
 }
 ```
 來源: `lib/constants/stock-status.ts`
@@ -287,7 +287,7 @@ enum InventoryCountStatus { PENDING, COUNTING, COMPLETED, CANCELLED }
 
 ### `WmsOperationName` (type) / `WMS_OPERATION_NAMES` (const)
 ```ts
-type WmsOperationName = 'material:read' | 'material:create' | /* …59 項… */;
+type WmsOperationName = 'material:read' | 'material:create' | /* …68 項… */;
 const WMS_OPERATION_NAMES: readonly WmsOperationName[];
 ```
 本套件所有 root operation 的 `` `${resource}:${action}` `` 名稱。同一組字串有三個用途：
@@ -339,6 +339,10 @@ static forRootAsync(
   //     defaultLoaderSerialId: string  — 庫存作業預設載具序號
   //     defaultLoaderTypeKey: string   — 預設載具類型 key
   //     defaultLocationKey: string     — 預設儲存位置 key
+  //     選填：tablePrefix、sequenceStorage（'sequence' | 'table'）、seedDefaults、
+  //     enrichStockEvents、customChangeTables、事件接線（beforeHooks / afterListeners /
+  //     actorExtractor / eventEmitterBridge）— 完整說明見 core 的 docs/api-reference.md
+  //     「WmsModuleCoreModuleOptions」
   // + WmsAuthModuleOptions:
   //     authChecker?: WmsAuthChecker   — 選填；resolver 授權委派函式（見 Authorization）
   // + WmsOperationRegistrationOptions（since 0.9.0）:
@@ -866,9 +870,7 @@ interface LoaderType<T> {
 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).
+目前此工廠**不接受參數**，回傳一個新實例，endpoint 為 `/graphql`（與預設單例相同）。URL / header 覆寫參數尚未提供。
 
 #### `ApolloClient` (named export — singleton instance)
 - Purpose: The pre-built Apollo client singleton created by `createApolloClient()`. Re-exported
@@ -972,7 +974,7 @@ useRoutes(): Array<{
 }>
 ```
 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).
+no i18n mechanism (see §13.9 in the integration guide for workarounds).
 
 #### `useTablePageState(usePageQs?: boolean)`
 - Source: `hooks/useTablePagination.ts`

package/docs/integration-guide.md

@@ -13,6 +13,7 @@ Target audience: engineers integrating WMS into a new product who want a working
 3. [Quick start (60 seconds)](#3-quick-start-60-seconds)
 4. [Backend setup (NestJS + GraphQL + TypeORM)](#4-backend-setup-nestjs--graphql--typeorm)
    - [4.6 Version compatibility matrix](#46-version-compatibility-matrix)
+   - [4.7 Module format: CommonJS only](#47-module-format-commonjs-only)
 5. [Frontend setup (Next.js Pages Router)](#5-frontend-setup-nextjs-pages-router)
 6. [Pages Router shell pattern (the 19 thin shells)](#6-pages-router-shell-pattern-the-19-thin-shells)
 7. [Apollo client wiring](#7-apollo-client-wiring)
@@ -296,8 +297,8 @@ WMS_DB_SCHEMA=wms_demo
     "@nestjs/graphql": "^13.0.0",
     "@nestjs/platform-express": "^11.0.0",
     "@nestjs/typeorm": "^11.0.0",
-    "@rytass/wms-module-core": "^0.1.2",
-    "@rytass/wms-module-graphql": "^0.1.2",
+    "@rytass/wms-module-core": "^0.9.1",
+    "@rytass/wms-module-graphql": "^0.11.1",
     "graphql": "^16.0.0",
     "pg": "^8.0.0",
     "reflect-metadata": "^0.2.0",
@@ -356,7 +357,7 @@ because it was exercised.
 
 | Package                     | Accepted (peer range)     | Tested            | Notes                                                                       |
 |-----------------------------|---------------------------|-------------------|-----------------------------------------------------------------------------|
-| `@nestjs/common` / `core`   | 10.x – 11.x               | 11.1.x            | **12.x is not accepted**: the whole NestJS 12 line is ESM-only, which this package (dual CJS+ESM) and a webpack-bundled host cannot consume yet |
+| `@nestjs/common` / `core`   | 10.x – 11.x               | 11.1.x            | **12.x is not accepted**: the NestJS 12 line is ESM-only, and this package ships CommonJS only and has not been tested against it (see §4.7) |
 | `@nestjs/graphql`           | 13.x                      | 13.4.5            | 14.x requires NestJS 12 (ESM-only)                                          |
 | `@nestjs/apollo`            | 13.x                      | 13.4.5            | The lib itself imports neither `@nestjs/apollo` nor `@apollo/server`; the peer records that a driver is required |
 | `@apollo/server`            | not a peer                | 5.5.1             | Chosen by your driver, not by this package                                   |
@@ -382,6 +383,19 @@ because it was exercised.
 
 ---
 
+### 4.7 Module format: CommonJS only
+
+`@rytass/wms-module-graphql` ships one CommonJS file (`index.cjs.js`), and every condition in its
+`exports` points at it. There is no ESM build, on purpose. The package exports DI tokens
+(`Symbol`s) and entity classes, and both are identities: if one process loads it through two
+module records, it gets two copies of each, and a provider registered under one copy's token is
+invisible to a lookup holding the other. The same reasoning applies to `@rytass/wms-module-core`
+(see its integration guide §4.7), which owns the tokens and entities this package consumes.
+
+ESM consumers lose nothing. Node reads named exports out of CommonJS through `cjs-module-lexer`,
+so named `import` statements work as written. The NestJS 12 line is ESM-only; it is outside the
+accepted peer range (see §4.6).
+
 ## 5. Frontend setup (Next.js Pages Router)
 
 The frontend package targets **Next.js Pages Router**, not App Router. The pre-built page bodies use SSR-incompatible providers and must be loaded on the client.
@@ -522,7 +536,7 @@ be listed in `transpilePackages`. Install it as a regular production dependency:
 pnpm add @rytass/wms-map-react-components
 ```
 
-Current published version: `^0.1.0`. Registry: `https://registry.npmjs.org/`.
+Check the latest published version with `npm view @rytass/wms-map-react-components version`. Registry: `https://registry.npmjs.org/`.
 
 ### 5.4 `apps/client/package.json` essentials
 
@@ -542,8 +556,8 @@ Current published version: `^0.1.0`. Registry: `https://registry.npmjs.org/`.
     "@mezzanine-ui/icons": "^1.0.0",
     "@mezzanine-ui/react": "^1.0.0",
     "@mezzanine-ui/system": "^1.0.0",
-    "@rytass/wms-map-react-components": "^0.1.0",
-    "@rytass/wms-module-react": "^0.1.2",
+    "@rytass/wms-map-react-components": "^0.1.10",
+    "@rytass/wms-module-react": "^0.5.1",
     "@xyflow/react": "^12.0.0",
     "graphql": "^16.0.0",
     "lodash": "^4.17.0",
@@ -670,10 +684,10 @@ import { createApolloClient } from '@rytass/wms-module-react';
 const client = createApolloClient();
 ```
 
-As of **0.1.2**, `createApolloClient()` takes **no parameters** and returns a fresh
+`createApolloClient()` takes **no parameters** and returns a fresh
 `ApolloClient<NormalizedCacheObject>` instance configured with the same `/graphql` URI as
-the default singleton. A URL/header override parameter is planned for **0.2.0** (will be a
-non-breaking addition). See [API Reference - createApolloClient](./api-reference.md).
+the default singleton. A URL/header override parameter is planned as a
+non-breaking addition, and is not available yet. See [API Reference - createApolloClient](./api-reference.md).
 
 ### 7.3 GraphQL operations & DocumentNode constants
 
@@ -1005,7 +1019,10 @@ The entities are designed for PostgreSQL:
 
 - `timestamptz` columns map to native `timestamp with time zone`
 - `bool` maps to PG `boolean`
-- Sequence-based serial IDs (e.g. loader.serialId) use PG `CURRVAL`
+- Serial IDs (order keys, loader serials) come from `WmsSequenceService`; `CURRVAL` is not used. `sequenceStorage` selects one of two modes:
+  - `'sequence'` (default): one PostgreSQL sequence per counter. The first use of a counter in a process runs `CREATE SEQUENCE IF NOT EXISTS` on a separate connection in autocommit, so a rollback cannot drop it and other callers are not blocked. Consecutive runs (loader serials) hold a transaction-scoped advisory lock on the counter.
+  - `'table'`: one row per counter in the `sequences` table, advanced by a single `INSERT … ON CONFLICT … RETURNING` statement. No DDL is run.
+  - In both modes a `maxValue` bound refuses a reservation before the counter moves.
 - `synchronize: true` works for dev/demo; use proper migrations in production
 
 This is the only database where the lib runs without any consumer-side workaround.
@@ -1023,7 +1040,7 @@ If you must run against SQLite (e.g. for local prototyping without a PG server):
 
    At the disk layer SQLite is liberal — it accepts any column type string and gives it NUMERIC affinity — so once the validator is past, schema creation works.
 
-2. **`CURRVAL(seq_name)` PostgreSQL function** — used internally to compute loader serial IDs. SQLite has no equivalent. All `createLoader` mutations will fail with `no such function: CURRVAL`. There is no clean consumer-side workaround; running real loader creation flows on SQLite is not supported as of 0.1.2.
+2. **Sequence reservation** — order keys and loader serials come from `WmsSequenceService`, which emits PostgreSQL-specific SQL in both storage modes. `sequenceStorage: 'sequence'` (default) uses `CREATE SEQUENCE`, `nextval` / `setval`, `to_regclass` and `pg_advisory_xact_lock`; `sequenceStorage: 'table'` avoids DDL but still uses the PostgreSQL `::bigint` cast. Neither mode runs on SQLite, so running `createLoader` or any order-creation flow on SQLite is not supported.
 
 3. **DateTime serialize round-trip** — SQLite returns datetime strings in `YYYY-MM-DD HH:MM:SS` format. The GraphQL DateTime scalar may emit `null` for some columns; the consumer-visible effect is blank `createdAt` fields in some payloads.
 
@@ -1545,7 +1562,7 @@ the navigation chrome with your own.
 
 ### 13.9 i18n: Current Limitations and Workarounds
 
-**Status**: No i18n support in 0.1.x. All user-visible strings in the lib are hardcoded
+**Status**: No i18n support. All user-visible strings in the lib are hardcoded
 Traditional Chinese (zh-TW).
 
 Affected areas:
@@ -1596,13 +1613,13 @@ WMS page components (`MaterialsManagement`, `InventoryList`, etc.) are designed
 **full-viewport rendering**. They use `PageWrapper` and `SectionWrapper` internally which
 set `width: 100%` and `height: 100%` of the viewport.
 
-**Embedding in a tab, panel, or drawer is not officially supported in 0.1.x.** Known issues
+**Embedding in a tab, panel, or drawer is not officially supported.** Known issues
 when embedded in a constrained container:
 - Mezzanine Table column-width calculations use the viewport width
 - Modal/dialog portals render at document body, not relative to the container
 - React Flow (used by Maps and LocationsManagement map tab) requires a fixed-height container
 
-There is no clean workaround in 0.1.x. If you need sectional embedding, fork the lib and
+There is no clean workaround. If you need sectional embedding, fork the lib and
 modify the `PageWrapper`/`SectionWrapper` styles to be container-relative.
 
 ---
@@ -1734,7 +1751,7 @@ export default defineConfig({
 4. `@mezzanine-ui/react` imports `lodash/compact` without a `.js` extension, which may
    require `resolve.alias` configuration in Vite.
 
-No official Vite setup guide exists for 0.1.x.
+No official Vite setup guide exists.
 
 ---
 
@@ -1788,7 +1805,7 @@ same `@nestjs/*` major version. Options:
    ```yaml
    # pnpm-workspace.yaml
    overrides:
-     '@rytass/wms-module-core': '0.1.4'
+     '@rytass/wms-module-core': '0.9.1'
    ```
 
 3. Apply `public-hoist-pattern[]` for `@rytass/wms-module-*` in `.npmrc`
@@ -1817,7 +1834,7 @@ There is no name-prefixing or namespace configuration in the lib's DTOs. This co
 affects **all** GraphQL types in the WMS schema: ObjectTypes, InputTypes, Enums, and any
 union types.
 
-The viable options are the same as those described in §13.1:
+The viable options are:
 
 1. **Run WMS as a separate NestJS process** (recommended) — isolates schemas entirely;
    no type name collisions possible.

package/docs/inventory-count.md

@@ -0,0 +1,372 @@
+# 盤點（Inventory Count）API 使用說明
+
+> 對象：串接 `@rytass/wms-module-graphql` 的前後端開發者。本文逐一說明盤點的
+> 3 支 query 與 9 支 mutation 的用途、參數、前置狀態、錯誤與範例；鎖定與事件的設計理由
+> 請另見 [`README.md`「Inventory counting」](../README.md#inventory-counting) 與
+> [`events.md`](./events.md)。
+
+## 1. 概觀
+
+盤點是「拿帳面對照現場、再把帳面修正成現場」的流程。三個前提決定了所有 API 的行為：
+
+- **盤點不搬貨。** 只在原位調整數量，位置錯了是調撥（`createTransferOrder`）的事。
+- **執行盤差之前都不動庫存。** 盤點數量只是暫存的對帳資料；唯一會寫庫存的是
+  `settleInventoryCount`，而且在單一 transaction 內完成。
+- **開始盤點即鎖定範圍。** `startInventoryCount` 快照帳面並鎖住範圍內（含所有下層）
+  儲位；期間任何碰到這些儲位的庫存異動（含調撥**進入**該儲位）都會被 `409 Conflict`
+  擋下，直到結算或取消。
+
+### 1.1 狀態機
+
+```
+createInventoryCountOrder ──▶ PENDING（尚未執行）
+        │ updateInventoryCountOrder（僅此狀態可改 Info）
+        ▼ startInventoryCount
+   COUNTING（盤點中）── countInventory / addInventoryCountItem /
+        │              removeInventoryCountItem / resetInventoryCount
+        ├── settleInventoryCount ──▶ COMPLETED（已完成）
+        └── cancelInventoryCount ──▶ CANCELLED（已取消）  ◀── 也可從 PENDING 取消
+```
+
+`COMPLETED` 與 `CANCELLED` 是終態，任何 mutation 都會回 `400`。
+
+### 1.2 每支 mutation 都是一個 transaction
+
+建立／更新／開始／暫存／新增列／移除列／清空／取消／結算各自整體成功或整體回滾，
+不會留下半張單。宿主直接呼叫 `InventoryCountOrderService` 時，每個方法最後一個參數
+都可傳入自己的 `EntityManager` 以併入既有 transaction（見 §6）。
+
+### 1.3 權限名稱與部署開關
+
+每支操作都掛 `@WmsOperation`，名稱即 `authChecker` 收到的字串，也是
+`forRootAsync({ enabledOperations / disabledOperations })` 可開關的單位：
+
+| 操作 | 名稱 |
+| --- | --- |
+| `inventoryCountOrders`、`inventoryCountOrder` | `inventory-count-order:read` |
+| `inventoryCountOrderItems` | `inventory-count-order:read-items` |
+| `createInventoryCountOrder` | `inventory-count-order:create` |
+| `updateInventoryCountOrder` | `inventory-count-order:update` |
+| `startInventoryCount` | `inventory-count-order:start` |
+| `countInventory` | `inventory-count-order:count` |
+| `addInventoryCountItem` | `inventory-count-order:add-item` |
+| `removeInventoryCountItem` | `inventory-count-order:remove-item` |
+| `resetInventoryCount` | `inventory-count-order:reset` |
+| `cancelInventoryCount` | `inventory-count-order:cancel` |
+| `settleInventoryCount` | `inventory-count-order:settle` |
+
+## 2. 型別
+
+### `InventoryCountOrderDto`（盤點單）
+
+| 欄位 | 型別 | 說明 |
+| --- | --- | --- |
+| `id` | `ID!` | |
+| `key` | `String!` | 盤點單號（系統流水號） |
+| `name` | `String!` | 名稱 |
+| `countDate` | `String!` | 盤點日期 `YYYY-MM-DD`，是**基準日**：盤差對外以此日期呈現，`createdAt` 保留真實建立時間 |
+| `status` | `InventoryCountStatus!` | `PENDING` 尚未執行／`COUNTING` 盤點中／`COMPLETED` 已完成／`CANCELLED` 已取消 |
+| `createdBy` | `String` | 建立者；由 `createInventoryCountOrder` 的 `createdBy` 寫入 |
+| `startedAt` `settledAt` `cancelledAt` | `DateTime` | 對應狀態轉換的時間 |
+| `createdAt` | `DateTime!` | |
+| `locations` | `[LocationDto!]!` | 使用者**選的根儲位**；下層展開不在此欄（但會被鎖定） |
+| `items` | `[InventoryCountOrderItemDto!]!` | **整張**盤點清單，不分頁。表格請改用 `inventoryCountOrderItems`；只有需要全量（匯出、上傳比對）時才選這個欄位 |
+
+### `InventoryCountOrderItemDto`（盤點清單的一列）
+
+| 欄位 | 型別 | 說明 |
+| --- | --- | --- |
+| `id` `orderId` `materialId` `batchId` | `ID!` | |
+| `locationId` `loaderId` | `ID` | 位置；`loaderId` 為 null 代表預設載具 |
+| `unitId` | `ID` | 盤點數量使用的單位，是 **`MaterialUnitDto.id`**；null 代表基本單位 |
+| `bookQuantity` | `Float!` | 帳面數量，**基本單位**，開始盤點時凍結 |
+| `countedQuantity` | `Float` | 盤點數量，以 `unitId` 的單位計；null 代表尚未盤 |
+| `isAddition` | `Boolean!` | `true` 為盤點中手動新增的盤盈列（`bookQuantity` 必為 0，且是唯一可刪的列） |
+| `held` `inShipment` `inspectionResult` `requiresInspection` `transferId` | 旗標 | 開始盤點當下從 batch **快照**而來：凍結／出貨中／檢驗結果／是否需檢驗／調撥中。開始前為 null |
+| `vendorId` `customerId` `saleId` `saleSerialId` | `String` | 同上，供應商／客戶／銷售訂單號碼／項次的快照 |
+| `material` `batch` `location` `loader` | 關聯 | DataLoader 解析；`material.materialUnits` 可用來組單位下拉與換算 |
+
+> 為什麼快照而不是即時解析：batch 在盤點結束後仍會變動，若即時解析，已完成的盤點單
+> 會在幾個月後自己改寫。盤點中儲位已鎖，快照與即時值必然相同。
+
+### 分頁型別
+
+`InventoryCountOrders` 與 `InventoryCountOrderItems` 都是 `{ id, items, total }`。
+
+## 3. Query
+
+### 3.1 `inventoryCountOrders` — 盤點列表
+
+```graphql
+query {
+  inventoryCountOrders(
+    offset: 0
+    limit: 10
+    name: "例行盤點"                # ILIKE 模糊比對
+    statuses: [PENDING, COUNTING]
+    createdBy: "Mark Wu"            # 完全比對
+    countDateFrom: "2025-01-01"     # 含
+    countDateTo: "2025-12-31"       # 含
+    locationIds: ["<locationId>"]   # 比對「展開後」的範圍：篩某層架會找到盤整條走道的單
+  ) {
+    total
+    items { id key name countDate status createdBy locations { id key } }
+  }
+}
+```
+
+- 排序固定 `countDate DESC, createdAt DESC`。
+- 全部參數可省略；`offset < 0` 或 `limit <= 0` 視為不分頁。
+
+### 3.2 `inventoryCountOrder` — 單張盤點單
+
+```graphql
+query {
+  inventoryCountOrder(id: "<orderId>") {
+    id key name countDate status createdBy startedAt settledAt cancelledAt
+    locations { id key }
+    # items { ... }   ← 只有匯出／上傳比對需要整張清單時才選
+  }
+}
+```
+
+- 查無此單回 `404 NotFoundException`。
+
+### 3.3 `inventoryCountOrderItems` — 盤點清單（分頁＋篩選）
+
+```graphql
+query {
+  inventoryCountOrderItems(
+    id: "<orderId>"
+    offset: 0
+    limit: 20
+    materialKey: "WATER"           # 以下五個為 ILIKE 模糊比對
+    materialDescription: "礦泉水"
+    batchKey: "2510"
+    locationKey: "1000A1B"
+    loaderSerialId: "BY00"
+    vendorId: "V001"               # 以下四個為完全比對（比對列上的快照值）
+    customerId: "C001"
+    saleId: "SO240596827"
+    saleSerialId: "00100043"
+    onlyVariance: true             # 只回「已暫存的盤點量 ≠ 帳面」的列
+  ) {
+    total
+    items {
+      id bookQuantity countedQuantity unitId isAddition
+      held inShipment inspectionResult requiresInspection transferId
+      vendorId customerId saleId saleSerialId
+      material { id key description baseUnit { id key } materialUnits { id unit conversionFactor } }
+      batch { id key }
+      location { id key }
+      loader { id serialId }
+    }
+  }
+}
+```
+
+- 排序：新增的盤盈列優先，其後依料號、批號、id，分頁不會重複或漏列。
+- `onlyVariance` 的比較會先把 `countedQuantity` 以 `unitId` 的換算係數換成基本單位，
+  與結算用的是同一套換算；**只看已暫存（`countInventory`）的值**，前端尚未送出的輸入
+  不在其中，切換前請先暫存。
+- 需要整張清單（例如下載盤點清單）時，請用 `inventoryCountOrder.items`，不要用大
+  `limit` 翻頁拼湊。
+
+## 4. Mutation
+
+共通規則：
+
+- 單據不存在 → `404`；狀態不符 → `400`，訊息指出目前狀態與要求的狀態。
+- 每支都在一個 transaction 內；失敗即整體回滾。
+- 每支都會發出對應的操作事件（§5），`beforeHooks` 丟出例外即可否決。
+
+### 4.1 `createInventoryCountOrder` — 建立盤點
+
+```graphql
+mutation {
+  createInventoryCountOrder(
+    name: "2025-上半年度例行盤點"
+    countDate: "2025-12-25"
+    locationIds: ["<rootLocationId>", "..."]   # 必填、至少一個；下層全部自動納入
+    createdBy: "Mark Wu"                        # 選填；列表「建立者」與其篩選即讀此欄
+  ) { id key status }
+}
+```
+
+- 事件：`inventory-count-order.created`。
+- 建立時就把範圍展開落地，並依目前帳面產生第一版清單（`PENDING` 狀態下可重算）。
+- `locationIds` 為空 → `400`。
+
+### 4.2 `updateInventoryCountOrder` — 修改 Info（僅尚未執行）
+
+```graphql
+mutation {
+  updateInventoryCountOrder(
+    id: "<orderId>"
+    name: "新名稱"            # 以下三個皆選填
+    countDate: "2025-12-26"
+    locationIds: ["<rootLocationId>"]
+  ) { id name countDate locations { key } }
+}
+```
+
+- 事件：`inventory-count-order.updated`。
+- 僅 `PENDING`；開始盤點後 Info 唯讀。
+- 傳了 `locationIds` 會重新展開範圍並**重建清單**（帳面列會依新範圍增減，盤盈列不動）；
+  傳空陣列 → `400`。
+
+### 4.3 `startInventoryCount` — 開始盤點
+
+```graphql
+mutation { startInventoryCount(id: "<orderId>") { id status startedAt } }
+```
+
+- 事件：`inventory-count-order.started`。
+- `PENDING → COUNTING`。做兩件事，且在同一個 transaction 內：
+  1. **快照**：重算每列 `bookQuantity`，並把 batch 的九個旗標寫到列上；
+  2. **鎖定**：範圍內（含下層）儲位自此拒絕所有庫存異動，直到結算或取消。
+- 建議前端先跳確認框（「系統將鎖定盤點範圍的庫存禁止異動行為…」），因為鎖定會影響
+  其他正在作業的人。
+
+### 4.4 `countInventory` — 暫存結果
+
+```graphql
+mutation {
+  countInventory(
+    id: "<orderId>"
+    items: [
+      { itemId: "<itemId>", countedQuantity: 94 }                        # 基本單位
+      { itemId: "<itemId>", countedQuantity: 8, unitId: "<materialUnitId>" }  # 指定單位
+      { itemId: "<itemId>", countedQuantity: null }                      # 清空，回到「尚未盤」
+    ]
+  ) { id }
+}
+```
+
+- 事件：`inventory-count-order.counted`。
+- 僅 `COUNTING`。**不動庫存**，只把數量與單位存到列上，可分多次、多人呼叫。
+- `countedQuantity`：省略或 `null` 清空；負數或非數字 → `400`。
+- `unitId`：省略＝維持原單位；`null`＝基本單位；給值＝該料號的 `MaterialUnitDto.id`。
+- `itemId` 不屬於此單 → `404`。空陣列為 no-op。
+
+### 4.5 `addInventoryCountItem` — 新增庫存（盤盈列）
+
+```graphql
+mutation {
+  addInventoryCountItem(
+    id: "<orderId>"
+    materialId: "<materialId>"
+    batchKey: "2510310042"        # 既有批號或新批號；不存在會立即建立
+    locationId: "<locationId>"    # 必須在盤點範圍內
+    loaderId: "<loaderId>"        # 選填；null 代表預設載具
+    countedQuantity: 100          # 必須 > 0
+    unitId: "<materialUnitId>"    # 選填；null 代表基本單位
+  ) { id isAddition bookQuantity countedQuantity batch { key } }
+}
+```
+
+- 事件：`inventory-count-order.updated`（回傳的是**該列** `InventoryCountOrderItemDto`）。
+- 僅 `COUNTING`。新列 `bookQuantity = 0`、`isAddition = true`，旗標從它的 batch 快照
+  （全新批號即預設值：未凍結、未調撥、未檢驗）。
+- 錯誤（皆 `400`）：`countedQuantity <= 0`；`locationId` 不在範圍內；該 position
+  （料號＋批號＋儲位＋載具，載具以解析後的值比對）已經在清單上——請直接在那一列填數量，
+  否則結算會對同一批庫存調整兩次。
+
+### 4.6 `removeInventoryCountItem` — 刪除盤盈列
+
+```graphql
+mutation { removeInventoryCountItem(id: "<orderId>", itemId: "<itemId>") { id } }
+```
+
+- 事件：`inventory-count-order.updated`。
+- 僅 `COUNTING`，且只能刪 `isAddition = true` 的列；帳面列一律鎖定 → `400`。
+
+### 4.7 `resetInventoryCount` — 清空重填
+
+```graphql
+mutation { resetInventoryCount(id: "<orderId>") { id status } }
+```
+
+- 事件：`inventory-count-order.reset`。
+- 僅 `COUNTING`。清空所有列的 `countedQuantity` 與 `unitId`，並刪除所有盤盈列；
+  **狀態維持 `COUNTING`、鎖定不解除、帳面快照不重取**（儲位鎖著，帳面本來就沒變）。
+- 會丟掉現場已填資料，前端應加確認框。
+
+### 4.8 `cancelInventoryCount` — 取消盤點
+
+```graphql
+mutation { cancelInventoryCount(id: "<orderId>") { id status cancelledAt } }
+```
+
+- 事件：`inventory-count-order.cancelled`。
+- `PENDING` 或 `COUNTING → CANCELLED`，**解除鎖定**；暫存的數量留在列上供查閱，但不會
+  寫入庫存。
+
+### 4.9 `settleInventoryCount` — 執行盤差
+
+```graphql
+mutation { settleInventoryCount(id: "<orderId>") { id status settledAt } }
+```
+
+- 事件：`inventory-count-order.settled`；每一列有差異者另發 `stock.count-gained`
+  （盤盈）或 `stock.count-lost`（盤虧）。
+- 僅 `COUNTING → COMPLETED`，單一 transaction，順序如下：
+  1. **重驗快照**：每一帳面列的 `bookQuantity` 必須仍等於當下帳面。不等代表有東西繞過
+     鎖寫了庫存（例如直接寫 `stocks`），此時回 `409 Conflict`、不寫任何東西；請取消後重盤。
+  2. 逐列計算 `delta = countedQuantity × 換算係數 − bookQuantity`：
+     - `countedQuantity` 為 null（沒盤）→ **跳過，不當作 0**；
+     - `delta = 0` → 不寫；
+     - 否則寫一列 `inventory_count_order_changes` 與一列 `stocks`（`+` 盤盈／`−` 盤虧），
+       位置為該列的儲位與載具（null 載具解析為預設載具）。
+  3. 更新狀態與 `settledAt`，鎖定隨之解除。
+- 前端送出前請先 `countInventory` 把畫面上的輸入全部暫存，結算只看已存的值；結算期間
+  建議鎖住整頁（不可離開／取消）。
+
+## 5. 事件
+
+| 事件 | 觸發 | `result` 型別 |
+| --- | --- | --- |
+| `inventory-count-order.created` | create | `InventoryCountOrderDto` |
+| `inventory-count-order.updated` | update／add-item／remove-item | `InventoryCountOrderDto` 或 `InventoryCountOrderItemDto`（add-item） |
+| `inventory-count-order.started` | start | `InventoryCountOrderDto` |
+| `inventory-count-order.counted` | count | `InventoryCountOrderDto` |
+| `inventory-count-order.reset` | reset | `InventoryCountOrderDto` |
+| `inventory-count-order.cancelled` | cancel | `InventoryCountOrderDto` |
+| `inventory-count-order.settled` | settle | `InventoryCountOrderDto`；另有 `stock.count-gained` / `stock.count-lost` |
+
+事件在最外層 transaction commit **之後**才送出；`beforeHooks` 在任何寫入之前執行，丟出
+例外即否決。詳見 [`events.md`](./events.md)。
+
+## 6. 從宿主程式直接呼叫
+
+GraphQL 之外，宿主也可注入 `InventoryCountOrderService`（`@rytass/wms-module-core`）：
+方法與 mutation 一一對應，最後一個參數可傳 `EntityManager` 併入既有 transaction。
+
+```ts
+await dataSource.transaction(async (manager) => {
+  const order = await counts.create(
+    { name: '夜間盤點', countDate: '2026-01-31', locationIds: [aisleId], createdBy: 'batch-job' },
+    manager,
+  );
+  await counts.start(order.id, manager);
+});
+
+await counts.count(order.id, [{ itemId, countedQuantity: 94 }]);
+await counts.settle(order.id); // 自己開 transaction
+```
+
+直接呼叫一樣受鎖定保護（鎖在 `*_order_change` 的 insert 上，不在 resolver），事件也一樣
+會發出（`WmsOperationRunner`）。
+
+## 7. 被鎖定時會看到什麼
+
+盤點中，對範圍內儲位的任何庫存異動——出貨、調撥（來源**或目的**在範圍內）、報廢、
+凍結、拆併批……——都會收到：
+
+```
+409 Conflict
+Location <locationId> is locked by inventory count order <key>;
+finish or cancel that count before moving this stock.
+```
+
+訊息指名單號，現場即可找到該單去結算或取消。