@tailor-platform/erp-kit 0.5.1 → 0.6.0

package/src/modules/manufacturing/docs/queries/ExplodeBillOfMaterial.md

@@ -0,0 +1,56 @@
+# ExplodeBillOfMaterial
+
+## Overview
+
+ExplodeBillOfMaterial expands one BOM version into recursive component requirements for planners and engineers who need to inspect multi-level demand on a specific effectivity date.
+
+## Business Rules
+
+- BOM reference is required.
+- Effectivity date is required so the query can resolve the root BOM semantics and any lower-level active child BOM versions consistently.
+- The explosion must apply the released BOM `bomType` semantics: `MANUFACTURE` preserves make-item boundaries while still showing lower-level demand, `PHANTOM` flattens child lines into the nearest non-phantom parent path, and `KIT` expands to issue-only component demand without routing or work-order context for the kit parent.
+- Recursive expansion may only use child BOM versions that are active and effective on the requested date within the same company and applicable site scope.
+- The response returns an exploded tree or list with component item references, cumulative required quantities, unit-of-measure context, explosion depth, and the source BOM path used to derive each requirement.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive BOM reference and effectivity date] --> B[Load root BOM version]
+    B --> C{BOM found and effective on date?}
+    C -->|No| D[Return BOM_NOT_FOUND or BOM_NOT_EFFECTIVE_ON_DATE]
+    C -->|Yes| E[Walk component lines recursively]
+    E --> F{Manufactured child requires lower-level BOM?}
+    F -->|Yes| G[Resolve active child BOM for date and scope]
+    G --> H[Apply MANUFACTURE PHANTOM or KIT explosion semantics]
+    F -->|No| H
+    H --> I[Accumulate exploded component requirements]
+    I --> J[Return exploded structure]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BOM_REFERENCE_REQUIRED**: BOM reference was not provided.
+- **EFFECTIVITY_DATE_REQUIRED**: Effectivity date was not provided.
+- **BOM_NOT_FOUND**: Requested BOM version does not exist.
+- **BOM_NOT_EFFECTIVE_ON_DATE**: The requested BOM version is not valid on the specified effectivity date.
+- **CHILD_BOM_NOT_RESOLVED**: A manufactured child item required recursive expansion but no active effective child BOM could be resolved.
+- **BOM_CIRCULAR_REFERENCE_DETECTED**: The explosion encountered a direct or indirect circular BOM reference.
+
+## Test Cases
+
+- explodes a multi-level manufacture BOM into recursive component requirements
+- flattens phantom subassemblies into the nearest non-phantom parent path
+- expands a kit BOM into component issue requirements without work-order context for the kit parent
+- resolves lower-level child BOM versions using the requested effectivity date
+- returns cumulative quantities and source BOM path metadata for exploded components
+- returns error when the BOM reference is missing
+- returns error when the effectivity date is missing
+- returns error when the root BOM is not found
+- returns error when the root BOM is not effective on the requested date
+- returns error when a required lower-level child BOM cannot be resolved
+- returns error when the explosion detects a circular BOM reference

package/src/modules/manufacturing/docs/queries/GetBillOfMaterial.md

@@ -0,0 +1,37 @@
+# GetBillOfMaterial
+
+## Overview
+
+GetBillOfMaterial returns one BOM version with its component lines, effectivity window, scope, and status so planners and engineers can inspect the exact production recipe.
+
+## Business Rules
+
+- BOM reference is required.
+- The query returns draft, active, or inactive versions.
+- Component lines are returned in their maintained sequence order.
+- The response includes `bomType`, scope, effectivity, and default-selection flags.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive BOM reference] --> B[Load BOM and component lines]
+    B --> C{BOM found?}
+    C -->|No| D[Return BOM_NOT_FOUND]
+    C -->|Yes| E[Return BOM detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BOM_NOT_FOUND**: Requested BOM version does not exist.
+
+## Test Cases
+
+- returns a BOM with component lines when found
+- returns draft BOM versions when requested
+- returns inactive BOM versions when requested
+- returns error when the BOM does not exist

package/src/modules/manufacturing/docs/queries/GetManufacturingCostSummary.md

@@ -0,0 +1,39 @@
+# GetManufacturingCostSummary
+
+## Overview
+
+GetManufacturingCostSummary returns one production order's cost baseline, actual accumulation, variance breakdown, and settlement-review status for supervisors or finance reviewers.
+
+## Business Rules
+
+- Cost-summary or production-order reference is required.
+- The query returns collecting, pending-review, reviewed, or settled summaries.
+- The response includes planned versus actual totals and variance lines by category.
+- Reviewed and settled summaries include reviewer or acknowledgment traceability.
+- Each variance line retains its mapped downstream variance-account reference.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive summary or production-order reference] --> B[Load cost summary and variance lines]
+    B --> C{Summary found?}
+    C -->|No| D[Return COST_SUMMARY_NOT_FOUND]
+    C -->|Yes| E[Return cost summary detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_SUMMARY_NOT_FOUND**: Requested cost summary does not exist.
+
+## Test Cases
+
+- returns a collecting cost summary with planned and actual totals
+- returns a reviewed cost summary with variance lines
+- returns a settled cost summary with acknowledgment traceability
+- returns variance lines with downstream account references
+- returns error when the cost summary does not exist

package/src/modules/manufacturing/docs/queries/GetProductionOrder.md

@@ -0,0 +1,37 @@
+# GetProductionOrder
+
+## Overview
+
+GetProductionOrder returns one production order with planning fields, release snapshots, work-progress rollup, and closeout status so planners and supervisors can inspect a single order end to end.
+
+## Business Rules
+
+- Production-order reference is required.
+- The query returns any lifecycle status.
+- The response includes selected or snapshotted BOM and routing context, quantity rollups, and linked cost-summary status.
+- Child work-order summary data may be embedded for execution visibility.
+- The returned snapshot should preserve the exact BOM type, routing revision, and production-state context that were in force for the order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive production-order reference] --> B[Load order, snapshots, and rollups]
+    B --> C{Order found?}
+    C -->|No| D[Return PRODUCTION_ORDER_NOT_FOUND]
+    C -->|Yes| E[Return production-order detail]
+```
+
+## External Dependencies
+
+- [GetManufacturingCostSummary](./GetManufacturingCostSummary.md) - Cost status may be embedded in the response.
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_NOT_FOUND**: Requested production order does not exist.
+
+## Test Cases
+
+- returns a production order with material requirements, work orders, and cost summary when found
+- returns a production order with no cost summary when none exists
+- returns error when the production order does not exist

package/src/modules/manufacturing/docs/queries/GetRouting.md

@@ -0,0 +1,39 @@
+# GetRouting
+
+## Overview
+
+GetRouting returns one routing revision with ordered operations, standard times, work-center assignments, and lifecycle status.
+
+## Business Rules
+
+- Routing reference is required.
+- Company scope is required when routing codes are only unique within a company.
+- The query returns draft, active, or inactive routings.
+- Operations are returned in sequence order with instruction and work-center context.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive routing reference and scope] --> B[Load routing and operations]
+    B --> C{Routing found?}
+    C -->|No| D[Return ROUTING_NOT_FOUND]
+    C -->|Yes| E[Return routing detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ROUTING_NOT_FOUND**: Requested routing does not exist.
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided when needed to resolve the routing.
+
+## Test Cases
+
+- returns a routing with ordered operations when found
+- returns inactive routing revisions when requested
+- returns routing data for the requested company scope
+- returns error when the routing does not exist
+- returns error when company scope is not provided

package/src/modules/manufacturing/docs/queries/GetWorkCenter.md

@@ -0,0 +1,35 @@
+# GetWorkCenter
+
+## Overview
+
+GetWorkCenter returns one work center with scope, capacity, calendar context, rate assumptions, overhead policy, and lifecycle status.
+
+## Business Rules
+
+- Work-center reference is required.
+- The query returns draft, active, or inactive work centers.
+- Capacity, rate, and overhead fields are returned exactly as currently configured.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive work-center reference] --> B[Load work-center detail]
+    B --> C{Work center found?}
+    C -->|No| D[Return WORK_CENTER_NOT_FOUND]
+    C -->|Yes| E[Return work-center detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_CENTER_NOT_FOUND**: Requested work center does not exist.
+
+## Test Cases
+
+- returns a work center when found
+- returns inactive work centers when requested
+- returns error when the work center does not exist

package/src/modules/manufacturing/docs/queries/GetWorkOrder.md

@@ -0,0 +1,38 @@
+# GetWorkOrder
+
+## Overview
+
+GetWorkOrder returns one work order with operation context, status, quantity rollups, actual time, pause history, and handoff evidence.
+
+## Business Rules
+
+- Work-order reference is required.
+- The query returns any lifecycle status.
+- Execution-event history may be returned in chronological order.
+- The response includes parent production-order reference and work-center context.
+- The response should preserve the routed operation sequence, current status, and recorded handoff evidence for the work order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive work-order reference] --> B[Load work order and execution events]
+    B --> C{Work order found?}
+    C -->|No| D[Return WORK_ORDER_NOT_FOUND]
+    C -->|Yes| E[Return work-order detail]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_ORDER_NOT_FOUND**: Requested work order does not exist.
+
+## Test Cases
+
+- returns a work order with execution history when found
+- returns paused work orders with prior pause data
+- returns a work order with handoff evidence and parent order context
+- returns error when the work order does not exist

package/src/modules/manufacturing/docs/queries/ListBillOfMaterialsByItem.md

@@ -0,0 +1,42 @@
+# ListBillOfMaterialsByItem
+
+## Overview
+
+ListBillOfMaterialsByItem lists BOM versions for one manufactured parent item and scope so planners can compare draft, active, and inactive recipe revisions.
+
+## Business Rules
+
+- Company scope and parent item reference are required.
+- Optional filters may restrict by site, status, effectivity date, or `bomType`.
+- Results include all statuses by default.
+- Results are ordered by effectivity start date and version identifier.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive company, item, and filters] --> B[Query BOM versions for item and scope]
+    B --> C[Apply optional status or date filters]
+    C --> D[Order versions]
+    D --> E[Return BOM list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+- **PARENT_ITEM_REQUIRED**: Parent item reference was not provided.
+
+## Test Cases
+
+- lists BOM versions for a manufactured item
+- filters BOM versions by site when provided
+- filters BOM versions by status when provided
+- filters BOM versions by bomType when provided
+- returns all statuses by default
+- returns an empty list when no BOM versions exist
+- returns error when the parent item reference is missing
+- returns error when company scope is missing

package/src/modules/manufacturing/docs/queries/ListManufacturingCostSummariesByStatus.md

@@ -0,0 +1,41 @@
+# ListManufacturingCostSummariesByStatus
+
+## Overview
+
+ListManufacturingCostSummariesByStatus lists manufacturing cost summaries by review or settlement lifecycle so supervisors and finance reviewers can work review queues.
+
+## Business Rules
+
+- Company scope and at least one summary status are required.
+- Optional filters may restrict by site, produced item, or production-order reference.
+- Results are ordered by production-order completion or review date.
+- The query returns summary-level cost and variance totals suitable for queue views, including production-order reference, site, item, and current cost-summary status.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive scope and status filters] --> B[Validate company and status filters]
+    B --> C[Query matching cost summaries]
+    C --> D[Apply optional site or order filters]
+    D --> E[Return summary list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STATUS_FILTER_REQUIRED**: At least one summary status was not provided.
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+
+## Test Cases
+
+- lists pending-review cost summaries for a company
+- lists reviewed cost summaries awaiting settlement
+- filters summaries by site when provided
+- filters summaries by production order when provided
+- returns summary rows with production-order and status context
+- returns error when no status filter is provided
+- returns error when company scope is missing

package/src/modules/manufacturing/docs/queries/ListProductionOrdersByStatus.md

@@ -0,0 +1,41 @@
+# ListProductionOrdersByStatus
+
+## Overview
+
+ListProductionOrdersByStatus lists production orders for planning, execution, or closeout queues by lifecycle state.
+
+## Business Rules
+
+- Company scope and at least one status value are required.
+- Optional filters may restrict by site, produced item, or planned date range.
+- Results are ordered by planned start date and priority.
+- The query returns summary-level fields suitable for operational worklists, including item, quantity, site, lifecycle state, and linked cost-summary state.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive status and scope filters] --> B[Validate company and status filters]
+    B --> C[Query matching production orders]
+    C --> D[Apply optional item or date filters]
+    D --> E[Return production-order summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STATUS_FILTER_REQUIRED**: At least one production-order status was not provided.
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+
+## Test Cases
+
+- lists released production orders for a company
+- lists in-progress production orders for a site
+- filters production orders by produced item when provided
+- filters production orders by planned date range when provided
+- returns summary fields with site and cost-summary status
+- returns error when no status filter is provided
+- returns error when company scope is missing

package/src/modules/manufacturing/docs/queries/ListRoutingsByItem.md

@@ -0,0 +1,42 @@
+# ListRoutingsByItem
+
+## Overview
+
+ListRoutingsByItem lists routing revisions available for one produced item and scope so planners can choose or compare executable process definitions.
+
+## Business Rules
+
+- Company scope and parent item reference are required.
+- Optional filters may restrict by site or status.
+- Results include all statuses by default.
+- Results are ordered by revision or effectivity precedence.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive company, item, and filters] --> B[Query routings for item and scope]
+    B --> C[Apply optional site and status filters]
+    C --> D[Order routing revisions]
+    D --> E[Return routing list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope was not provided.
+- **PARENT_ITEM_REQUIRED**: Parent item reference was not provided.
+
+## Test Cases
+
+- lists routing revisions for a produced item
+- filters routing revisions by site when provided
+- filters routing revisions by status when provided
+- returns all statuses by default
+- returns an empty list when no routings exist
+- returns routing revisions for the requested company scope
+- returns error when the parent item reference is missing
+- returns error when company scope is missing

package/src/modules/manufacturing/docs/queries/ListWorkCentersBySite.md

@@ -0,0 +1,38 @@
+# ListWorkCentersBySite
+
+## Overview
+
+ListWorkCentersBySite lists work centers available at one site or facility context for capacity review, routing maintenance, or scheduling decisions.
+
+## Business Rules
+
+- Company and site references are required.
+- Optional filters may restrict by status or work-center type.
+- Results include all statuses by default.
+- Results are ordered by work-center code or name.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive site and filters] --> B[Query work centers for site]
+    B --> C[Apply optional filters]
+    C --> D[Order results]
+    D --> E[Return work-center list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SITE_SCOPE_REQUIRED**: Company or site reference was not provided.
+
+## Test Cases
+
+- lists work centers for a site
+- filters work centers by status when provided
+- returns an empty list when the site has no work centers
+- returns error when company scope is missing
+- returns error when site scope is missing

package/src/modules/manufacturing/docs/queries/ListWorkOrdersByProductionOrder.md

@@ -0,0 +1,39 @@
+# ListWorkOrdersByProductionOrder
+
+## Overview
+
+ListWorkOrdersByProductionOrder lists the operation-level execution plan under one production order in sequence order for supervisors and execution UIs.
+
+## Business Rules
+
+- Production-order reference is required.
+- Results are ordered by routing sequence.
+- Optional filters may restrict by work-order status or assigned work center.
+- The query returns summary fields suitable for execution boards, including sequence, status, work-center context, and progress totals.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive production-order reference and filters] --> B[Query child work orders]
+    B --> C[Apply optional status or work-center filters]
+    C --> D[Order by sequence]
+    D --> E[Return work-order list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRODUCTION_ORDER_REFERENCE_REQUIRED**: Production-order reference was not provided.
+
+## Test Cases
+
+- lists work orders for a production order in sequence order
+- filters work orders by status when provided
+- filters work orders by work center when provided
+- returns summary fields with sequence and progress data
+- returns an empty list when no work orders exist
+- returns error when the production-order reference is missing

package/src/modules/manufacturing/docs/queries/ListWorkOrdersByWorkCenter.md

@@ -0,0 +1,43 @@
+# ListWorkOrdersByWorkCenter
+
+## Overview
+
+ListWorkOrdersByWorkCenter lists work orders queued or executing at one work center across multiple production orders so supervisors can review shared bottlenecks and dispatch work.
+
+## Business Rules
+
+- Work-center reference is required.
+- Optional filters may restrict by work-order status or planned execution date range.
+- Results may span multiple production orders, but every returned work order must belong to the requested work center only.
+- Results are ordered for execution review, prioritizing active bottleneck work by status and planned execution timing.
+- The query returns summary fields suitable for a dispatch or bottleneck board, including production-order reference, operation sequence, status, planned and completed quantities, and current execution timestamps.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive work-center reference and filters] --> B[Validate work-center input]
+    B --> C[Query work orders assigned to the work center]
+    C --> D[Apply optional status and date-range filters]
+    D --> E[Order for execution review]
+    E --> F[Return cross-order work-order list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **WORK_CENTER_REFERENCE_REQUIRED**: Work-center reference was not provided.
+- **WORK_CENTER_NOT_FOUND**: Requested work center does not exist.
+
+## Test Cases
+
+- lists pending and in-progress work orders for one work center across multiple production orders
+- filters work orders by status when provided
+- orders the result for bottleneck review by execution priority and planned timing
+- returns summary fields with production-order reference operation sequence and progress totals
+- returns an empty list when the work center has no assigned work orders
+- returns error when the work-center reference is missing
+- returns error when the work center does not exist