docs: update documentation for extraction functions migration

- Add ExtractionFunctions.md reference document - Update database-schema spec with 11 extraction functions - Update data-access spec to document extraction function approach - Update search-processing spec with new query builder interface - Add Database.Tests to Testing.md architecture doc - Update DataFlow.md with extraction function flow
2026-01-06 14:54:10 -05:00
parent 35c1e6baf0
commit c6aeb20d9c
8 changed files with 602 additions and 345 deletions
@@ -1079,6 +1079,90 @@ var results = await context.WorkOrders

 ## Functions

+### Requirement: Search Criteria Extraction Functions
+
+The system SHALL provide SQL functions to extract search criteria values from the `Search.Criteria` JSON column.
+
+#### Scalar Functions
+
+| Function | Return Type | Description |
+|----------|-------------|-------------|
+| `fn_GetSearchMinimumDt(@SearchId INT)` | DATETIME2(7) | Extracts `$.MinimumDt` value |
+| `fn_GetSearchMaximumDt(@SearchId INT)` | DATETIME2(7) | Extracts `$.MaximumDt` value |
+| `fn_GetSearchExtractMisData(@SearchId INT)` | BIT | Extracts `$.ExtractMisData` value |
+
+#### Table-Valued Functions (Simple Arrays)
+
+| Function | Return Columns | Description |
+|----------|----------------|-------------|
+| `fn_GetSearchWorkOrders(@SearchId INT)` | WorkOrderNumber BIGINT | Extracts `$.WorkOrderNumbers` array |
+| `fn_GetSearchItemNumbers(@SearchId INT)` | ItemNumber VARCHAR(128) | Extracts `$.ItemNumbers` array |
+| `fn_GetSearchProfitCenters(@SearchId INT)` | Code VARCHAR(12) | Extracts `$.ProfitCenters` array |
+| `fn_GetSearchWorkCenters(@SearchId INT)` | Code VARCHAR(12) | Extracts `$.WorkCenters` array |
+| `fn_GetSearchOperatorIDs(@SearchId INT)` | OperatorID VARCHAR(128) | Extracts `$.OperatorIDs` array |
+
+#### Table-Valued Functions (Complex Objects)
+
+| Function | Return Columns | Description |
+|----------|----------------|-------------|
+| `fn_GetSearchComponentLots(@SearchId INT)` | LotNumber VARCHAR(30), ItemNumber VARCHAR(128) | Extracts `$.ComponentLotNumbers` array |
+| `fn_GetSearchPartOperations(@SearchId INT)` | ItemNumber VARCHAR(128), OperationNumber VARCHAR(10), MisNumber VARCHAR(10), MisRevision VARCHAR(10) | Extracts `$.PartOperations` array |
+
+#### Business Rules
+
+- Scalar functions return NULL if search not found, criteria is NULL, or JSON is invalid
+- Table-valued functions return empty result set if search not found, criteria is NULL, or JSON is invalid
+- TVFs use CTE pattern to pre-filter valid JSON before OPENJSON (prevents runtime errors)
+- TVFs use `OPENJSON...WITH` syntax for type-safe extraction
+
+#### Scenario: Extract work order filter values
+
+- **WHEN** Search ID 123 has Criteria containing `{"WorkOrderNumbers":[12345,67890]}`
+- **THEN** `SELECT * FROM dbo.fn_GetSearchWorkOrders(123)` returns two rows with WorkOrderNumber values 12345 and 67890
+
+#### Scenario: Handle invalid JSON gracefully
+
+- **WHEN** Search ID 456 has Criteria containing invalid JSON text
+- **THEN** extraction functions return NULL (scalar) or empty result set (TVF) without throwing errors
+
+---
+
+### Requirement: Validate Search Criteria Procedure
+
+The system SHALL provide a stored procedure for strict validation of search criteria with error reporting.
+
+#### Procedure Signature
+
+```sql
+CREATE PROCEDURE dbo.usp_ValidateSearchCriteria(@SearchId INT)
+```
+
+#### Error Codes
+
+| Error Code | Condition | Message Pattern |
+|------------|-----------|-----------------|
+| 50001 | Search ID not found | "Search ID {id} not found" |
+| 50002 | Criteria is NULL or empty | "Search ID {id} has no criteria" |
+| 50003 | Criteria is not valid JSON | "Search ID {id} has invalid JSON" |
+
+#### Business Rules
+
+- Procedure throws errors using `THROW` statement for calling code to handle
+- Procedure returns 0 (success) when validation passes
+- Used for pre-flight validation before query execution
+
+#### Scenario: Validate valid search
+
+- **WHEN** `usp_ValidateSearchCriteria` is called for a search with valid JSON criteria
+- **THEN** procedure returns 0 (success) without throwing
+
+#### Scenario: Validate missing search
+
+- **WHEN** `usp_ValidateSearchCriteria` is called for non-existent search ID 99999
+- **THEN** procedure throws error 50001 with message "Search ID 99999 not found"
+
+---
+
 ### Requirement: MatchMIS function

 The system SHALL provide a table-valued function to match work order steps to MIS data.