docs: update specs and architecture docs with usp_/fn_ naming convention
This commit is contained in:
Joseph Doherty
@@ -1580,7 +1580,7 @@ Task<int> SubmitSearchAsync(Search search, CancellationToken ct = default)
|
||||
#### Stored Procedure
|
||||
|
||||
```sql
|
||||
EXEC dbo.SubmitSearch
|
||||
EXEC dbo.usp_SubmitSearch
|
||||
@p_UserName = ...,
|
||||
@p_Name = ...,
|
||||
@p_Criteria = ...,
|
||||
|
||||
@@ -91,11 +91,11 @@ The system SHALL store user search requests, criteria, status, and results.
|
||||
- Criteria stores JSON-serialized SearchCriteria object
|
||||
|
||||
#### Scenario: Insert new search request
|
||||
- **WHEN** a user "jdoe" submits a search named "Q4 Report" and the SubmitSearch stored procedure is called
|
||||
- **WHEN** a user "jdoe" submits a search named "Q4 Report" and the usp_SubmitSearch stored procedure is called
|
||||
- **THEN** a new row is inserted with Status = 1 (Submitted), SubmitDT is set to current timestamp, and ID is auto-generated
|
||||
|
||||
#### Scenario: Search completes successfully
|
||||
- **WHEN** a search with ID = 123 and Status = 2 (Started) exists and CompleteSearch is called with WasSuccessful = 1
|
||||
- **WHEN** a search with ID = 123 and Status = 2 (Started) exists and usp_CompleteSearch is called with WasSuccessful = 1
|
||||
- **THEN** Status is updated to 3 (Ended), Results contains the Excel binary data, and EndDT is set to current timestamp
|
||||
|
||||
#### Scenario: Query searches by user
|
||||
@@ -854,12 +854,12 @@ GROUP BY wos.WorkOrderNumber;
|
||||
|
||||
## Stored Procedures
|
||||
|
||||
### Requirement: SubmitSearch stored procedure
|
||||
### Requirement: usp_SubmitSearch stored procedure
|
||||
|
||||
The system SHALL insert a new search request with Status = Submitted (1).
|
||||
|
||||
```sql
|
||||
CREATE PROCEDURE [dbo].[SubmitSearch] (
|
||||
CREATE PROCEDURE [dbo].[usp_SubmitSearch] (
|
||||
@p_UserName VARCHAR(128),
|
||||
@p_Name VARCHAR(128),
|
||||
@p_Criteria VARCHAR(MAX),
|
||||
@@ -874,19 +874,19 @@ CREATE PROCEDURE [dbo].[SubmitSearch] (
|
||||
- Returns new ID via OUTPUT parameter
|
||||
|
||||
#### Scenario: Submit new search request
|
||||
- **WHEN** user "jdoe" submits criteria for Q4 analysis and SubmitSearch is called with UserName, Name, Criteria
|
||||
- **WHEN** user "jdoe" submits criteria for Q4 analysis and usp_SubmitSearch is called with UserName, Name, Criteria
|
||||
- **THEN** a new Search row is created with Status = 1 and @o_SearchID OUTPUT contains the new ID
|
||||
|
||||
#### .NET 10 Implementation Notes
|
||||
|
||||
**Decision**: Keep as stored procedure. This atomic insert-and-return-ID operation benefits from stored procedure encapsulation. The OUTPUT parameter pattern maps directly to Dapper's `Query<int>` with `@o_SearchID OUTPUT` or EF Core's `FromSqlRaw`.
|
||||
|
||||
### Requirement: StartSearch stored procedure
|
||||
### Requirement: usp_StartSearch stored procedure
|
||||
|
||||
The system SHALL mark a search as started.
|
||||
|
||||
```sql
|
||||
CREATE PROCEDURE [dbo].[StartSearch] (@p_SearchID INT)
|
||||
CREATE PROCEDURE [dbo].[usp_StartSearch] (@p_SearchID INT)
|
||||
```
|
||||
|
||||
#### Business Rules
|
||||
@@ -895,19 +895,19 @@ CREATE PROCEDURE [dbo].[StartSearch] (@p_SearchID INT)
|
||||
- Sets StartDT = GETDATE()
|
||||
|
||||
#### Scenario: Worker picks up queued search
|
||||
- **WHEN** search ID 123 with Status = 1 (Submitted) exists and StartSearch(123) is called
|
||||
- **WHEN** search ID 123 with Status = 1 (Submitted) exists and usp_StartSearch(123) is called
|
||||
- **THEN** Status = 2 (Started) and StartDT = current time
|
||||
|
||||
#### .NET 10 Implementation Notes
|
||||
|
||||
**Decision**: Candidate for C# service layer. Simple single-row UPDATE could be implemented as repository method for better testability. However, keeping as stored procedure is acceptable for consistency with other search lifecycle procedures.
|
||||
|
||||
### Requirement: CompleteSearch stored procedure
|
||||
### Requirement: usp_CompleteSearch stored procedure
|
||||
|
||||
The system SHALL mark a search as completed with results.
|
||||
|
||||
```sql
|
||||
CREATE PROCEDURE [dbo].[CompleteSearch] (
|
||||
CREATE PROCEDURE [dbo].[usp_CompleteSearch] (
|
||||
@p_SearchID INT,
|
||||
@p_WasSuccessful BIT,
|
||||
@p_Results VARBINARY(MAX)
|
||||
@@ -921,23 +921,23 @@ CREATE PROCEDURE [dbo].[CompleteSearch] (
|
||||
- Sets EndDT = GETDATE()
|
||||
|
||||
#### Scenario: Search completes successfully
|
||||
- **WHEN** search ID 123 with Status = 2 (Started) exists and CompleteSearch(123, 1, <excel bytes>) is called
|
||||
- **WHEN** search ID 123 with Status = 2 (Started) exists and usp_CompleteSearch(123, 1, <excel bytes>) is called
|
||||
- **THEN** Status = 3 (Ended), Results = <excel bytes>, EndDT = current time
|
||||
|
||||
#### Scenario: Search fails with error
|
||||
- **WHEN** search ID 456 with Status = 2 (Started) exists and CompleteSearch(456, 0, NULL) is called
|
||||
- **WHEN** search ID 456 with Status = 2 (Started) exists and usp_CompleteSearch(456, 0, NULL) is called
|
||||
- **THEN** Status = 4 (Error), Results = NULL, EndDT = current time
|
||||
|
||||
#### .NET 10 Implementation Notes
|
||||
|
||||
**Decision**: Keep as stored procedure. The conditional status logic (success vs error) and VARBINARY handling make this a good fit for stored procedure. When migrating to blob storage, this procedure would be modified to store a blob URL instead.
|
||||
|
||||
### Requirement: ResetPartialSearches stored procedure
|
||||
### Requirement: usp_ResetPartialSearches stored procedure
|
||||
|
||||
The system SHALL reset incomplete searches on application startup.
|
||||
|
||||
```sql
|
||||
CREATE PROCEDURE [dbo].[ResetPartialSearches]
|
||||
CREATE PROCEDURE [dbo].[usp_ResetPartialSearches]
|
||||
```
|
||||
|
||||
#### Business Rules
|
||||
@@ -947,11 +947,11 @@ CREATE PROCEDURE [dbo].[ResetPartialSearches]
|
||||
- Used on service startup to recover from crashes
|
||||
|
||||
#### Scenario: Recover from service crash
|
||||
- **WHEN** search ID 789 has Status = 2, StartDT = yesterday, EndDT = NULL and ResetPartialSearches is called on service startup
|
||||
- **WHEN** search ID 789 has Status = 2, StartDT = yesterday, EndDT = NULL and usp_ResetPartialSearches is called on service startup
|
||||
- **THEN** Status = 1 (Submitted), StartDT = NULL, and the search will be re-processed
|
||||
|
||||
#### Scenario: Ignore completed searches
|
||||
- **WHEN** search ID 111 has Status = 3, StartDT and EndDT both set and ResetPartialSearches is called
|
||||
- **WHEN** search ID 111 has Status = 3, StartDT and EndDT both set and usp_ResetPartialSearches is called
|
||||
- **THEN** search ID 111 is unchanged (EndDT is not NULL)
|
||||
|
||||
#### .NET 10 Implementation Notes
|
||||
@@ -1163,7 +1163,7 @@ CREATE PROCEDURE dbo.usp_ValidateSearchCriteria(@SearchId INT)
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MatchMIS function
|
||||
### Requirement: fn_MatchMIS function
|
||||
|
||||
The system SHALL provide a table-valued function to match work order steps to MIS data.
|
||||
|
||||
@@ -1222,11 +1222,11 @@ The system SHALL provide a table-valued function to match work order steps to MI
|
||||
8. Returns input parameters with NULL MIS fields if no matches at all
|
||||
|
||||
#### Scenario: Match via routing with current MIS
|
||||
- **WHEN** work order 12345, step 10 with function code "ASSY" is processed and MatchMIS finds a routing entry in F3112Z1 and MIS data exists with Status = 'Current'
|
||||
- **WHEN** work order 12345, step 10 with function code "ASSY" is processed and fn_MatchMIS finds a routing entry in F3112Z1 and MIS data exists with Status = 'Current'
|
||||
- **THEN** RoutingMatch = 1, MasterMatch = 0, MIS fields populated
|
||||
|
||||
#### Scenario: Fallback to master routing
|
||||
- **WHEN** work order 12345, step 10 with no routing entry is processed and MatchMIS finds match in F3003 RouteMaster
|
||||
- **WHEN** work order 12345, step 10 with no routing entry is processed and fn_MatchMIS finds match in F3003 RouteMaster
|
||||
- **THEN** RoutingMatch = 0, MasterMatch = 1, MatchedSequenceNumber from master
|
||||
|
||||
#### Scenario: Fallback to BackLevel MIS
|
||||
@@ -1234,7 +1234,7 @@ The system SHALL provide a table-valued function to match work order steps to MI
|
||||
- **THEN** Status = 'BackLevel' MIS data is returned
|
||||
|
||||
#### Scenario: No MIS data available
|
||||
- **WHEN** routing match found but no MIS data exists and MatchMIS completes
|
||||
- **WHEN** routing match found but no MIS data exists and fn_MatchMIS completes
|
||||
- **THEN** RoutingMatch/MasterMatch set, MIS fields = NULL
|
||||
|
||||
---
|
||||
@@ -1342,10 +1342,10 @@ Current implementation stores Excel results as `VARBINARY(MAX)` in the Search.Re
|
||||
|
||||
| Procedure | Decision | Rationale |
|
||||
|-----------|----------|-----------|
|
||||
| SubmitSearch | Keep | Atomic INSERT with OUTPUT parameter |
|
||||
| StartSearch | Keep (or migrate) | Simple UPDATE, but consistency with lifecycle |
|
||||
| CompleteSearch | Keep | Conditional logic, VARBINARY handling |
|
||||
| ResetPartialSearches | Keep | Bulk conditional UPDATE at startup |
|
||||
| usp_SubmitSearch | Keep | Atomic INSERT with OUTPUT parameter |
|
||||
| usp_StartSearch | Keep (or migrate) | Simple UPDATE, but consistency with lifecycle |
|
||||
| usp_CompleteSearch | Keep | Conditional logic, VARBINARY handling |
|
||||
| usp_ResetPartialSearches | Keep | Bulk conditional UPDATE at startup |
|
||||
|
||||
All procedures can be called from .NET 10 via Dapper or EF Core. Migration to C# service layer is optional and would primarily benefit unit testing (mockable repository interfaces).
|
||||
|
||||
|
||||
@@ -545,7 +545,7 @@ The system SHALL optionally extract Manufacturing Information System (MIS) data
|
||||
|
||||
- `ExtractMisData` flag from search criteria
|
||||
- `ItemOperationMisFilter` entries (when filtering by specific MIS)
|
||||
- Work order step data joined with MIS matching function `dbo.MatchMIS`
|
||||
- Work order step data joined with MIS matching function `dbo.fn_MatchMIS`
|
||||
|
||||
#### Outputs
|
||||
|
||||
@@ -562,7 +562,7 @@ The system SHALL optionally extract Manufacturing Information System (MIS) data
|
||||
#### Business Rules
|
||||
|
||||
- MIS extraction is only performed when `ExtractMisData = true`
|
||||
- The `MatchMIS` table-valued function handles MIS record matching logic
|
||||
- The `fn_MatchMIS` table-valued function handles MIS record matching logic
|
||||
- RoutingMatch indicates match to F3112Z1 (work order routing) records
|
||||
- MasterMatch indicates match to F3003 (item master routing) records
|
||||
- Non-match results include work orders where neither RoutingMatch nor MasterMatch is true, or MisNumber is null
|
||||
@@ -792,9 +792,9 @@ Circular references in work order relationships are **handled implicitly** by th
|
||||
|
||||
MIS non-match results are **always included** when `ExtractMisData = true`. The non-match data is valuable for quality investigations and should not be optional.
|
||||
|
||||
### Decision: MatchMIS function availability
|
||||
### Decision: fn_MatchMIS function availability
|
||||
|
||||
The `dbo.MatchMIS` table-valued function **must be recreated** in the migrated database. It is a custom SQL Server function that implements MIS record matching logic based on work order routing, master routing, and operation parameters.
|
||||
The `dbo.fn_MatchMIS` table-valued function **must be recreated** in the migrated database. It is a custom SQL Server function that implements MIS record matching logic based on work order routing, master routing, and operation parameters.
|
||||
|
||||
### Decision: Filter validation location
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ This specification documents stored procedures and functions that implement data
|
||||
|
||||
### Requirement: Submit search procedure
|
||||
|
||||
The system SHALL provide a SubmitSearch stored procedure that creates new search records in the database.
|
||||
The system SHALL provide a usp_SubmitSearch stored procedure that creates new search records in the database.
|
||||
|
||||
#### Inputs
|
||||
|
||||
@@ -39,7 +39,7 @@ The system SHALL provide a SubmitSearch stored procedure that creates new search
|
||||
|
||||
#### Scenario: Submit new search
|
||||
|
||||
- **WHEN** SubmitSearch is called with valid username, search name, and criteria
|
||||
- **WHEN** usp_SubmitSearch is called with valid username, search name, and criteria
|
||||
- **THEN** a new Search record is inserted with Status = 1 (Queued)
|
||||
- **AND** SubmitDT is set to the current timestamp
|
||||
- **AND** the new SearchId is returned via the @o_SearchID OUTPUT parameter
|
||||
@@ -54,7 +54,7 @@ The system SHALL provide a SubmitSearch stored procedure that creates new search
|
||||
|
||||
### Requirement: Start search procedure
|
||||
|
||||
The system SHALL provide a StartSearch stored procedure that marks a search as being actively processed.
|
||||
The system SHALL provide a usp_StartSearch stored procedure that marks a search as being actively processed.
|
||||
|
||||
#### Inputs
|
||||
|
||||
@@ -72,7 +72,7 @@ The system SHALL provide a StartSearch stored procedure that marks a search as b
|
||||
|
||||
#### Scenario: Start processing a queued search
|
||||
|
||||
- **WHEN** StartSearch is called with a valid SearchID
|
||||
- **WHEN** usp_StartSearch is called with a valid SearchID
|
||||
- **THEN** the search Status is updated to 2 (Processing)
|
||||
- **AND** StartDT is set to the current timestamp
|
||||
|
||||
@@ -80,7 +80,7 @@ The system SHALL provide a StartSearch stored procedure that marks a search as b
|
||||
|
||||
### Requirement: Complete search procedure
|
||||
|
||||
The system SHALL provide a CompleteSearch stored procedure that finalizes a search with results or failure status.
|
||||
The system SHALL provide a usp_CompleteSearch stored procedure that finalizes a search with results or failure status.
|
||||
|
||||
#### Inputs
|
||||
|
||||
@@ -101,14 +101,14 @@ The system SHALL provide a CompleteSearch stored procedure that finalizes a sear
|
||||
|
||||
#### Scenario: Complete successful search
|
||||
|
||||
- **WHEN** CompleteSearch is called with WasSuccessful = 1 and Excel binary data
|
||||
- **WHEN** usp_CompleteSearch is called with WasSuccessful = 1 and Excel binary data
|
||||
- **THEN** the search Status is updated to 3 (Complete)
|
||||
- **AND** the Results column contains the Excel binary
|
||||
- **AND** EndDT is set to the current timestamp
|
||||
|
||||
#### Scenario: Complete failed search
|
||||
|
||||
- **WHEN** CompleteSearch is called with WasSuccessful = 0
|
||||
- **WHEN** usp_CompleteSearch is called with WasSuccessful = 0
|
||||
- **THEN** the search Status is updated to 4 (Failed)
|
||||
- **AND** EndDT is set to the current timestamp
|
||||
|
||||
@@ -116,7 +116,7 @@ The system SHALL provide a CompleteSearch stored procedure that finalizes a sear
|
||||
|
||||
### Requirement: Reset partial searches procedure
|
||||
|
||||
The system SHALL provide a ResetPartialSearches stored procedure that recovers searches stuck in a processing state.
|
||||
The system SHALL provide a usp_ResetPartialSearches stored procedure that recovers searches stuck in a processing state.
|
||||
|
||||
#### Inputs
|
||||
|
||||
@@ -135,7 +135,7 @@ The system SHALL provide a ResetPartialSearches stored procedure that recovers s
|
||||
|
||||
#### Scenario: Service restart recovery
|
||||
|
||||
- **WHEN** the worker service starts and calls ResetPartialSearches
|
||||
- **WHEN** the worker service starts and calls usp_ResetPartialSearches
|
||||
- **THEN** all searches with StartDT set but EndDT NULL are reset
|
||||
- **AND** Status is changed back to 1 (Queued)
|
||||
- **AND** StartDT is cleared to NULL
|
||||
@@ -143,14 +143,14 @@ The system SHALL provide a ResetPartialSearches stored procedure that recovers s
|
||||
|
||||
#### Scenario: No stuck searches
|
||||
|
||||
- **WHEN** ResetPartialSearches is called with no searches in partial state
|
||||
- **WHEN** usp_ResetPartialSearches is called with no searches in partial state
|
||||
- **THEN** no records are modified
|
||||
|
||||
---
|
||||
|
||||
### Requirement: MIS matching function
|
||||
|
||||
The system SHALL provide a MatchMIS table-valued function that correlates work order operations with Manufacturing Information System (MIS) quality documents.
|
||||
The system SHALL provide a fn_MatchMIS table-valued function that correlates work order operations with Manufacturing Information System (MIS) quality documents.
|
||||
|
||||
#### Inputs
|
||||
|
||||
@@ -198,14 +198,14 @@ Returns a table with the following columns:
|
||||
|
||||
#### Scenario: Match via work order routing with current MIS
|
||||
|
||||
- **WHEN** MatchMIS is called for a work order with routing data
|
||||
- **WHEN** fn_MatchMIS is called for a work order with routing data
|
||||
- **AND** a current MIS document exists for the matched sequence
|
||||
- **THEN** results include RoutingMatch = 1 and full MIS details
|
||||
- **AND** MasterMatch indicates whether route master also matched
|
||||
|
||||
#### Scenario: Match via route master when no routing exists
|
||||
|
||||
- **WHEN** MatchMIS is called for a work order without specific routing
|
||||
- **WHEN** fn_MatchMIS is called for a work order without specific routing
|
||||
- **AND** a route master entry exists for the item/branch/work center
|
||||
- **THEN** results include MasterMatch = 1 and RoutingMatch = 0
|
||||
- **AND** MIS details are included if available
|
||||
@@ -244,7 +244,7 @@ Returns a table with the following columns:
|
||||
[New Search]
|
||||
|
|
||||
v
|
||||
SubmitSearch
|
||||
usp_SubmitSearch
|
||||
|
|
||||
v
|
||||
+-------+
|
||||
@@ -253,7 +253,7 @@ Returns a table with the following columns:
|
||||
+---+---+ |
|
||||
| |
|
||||
v |
|
||||
StartSearch ResetPartialSearches
|
||||
usp_StartSearch usp_ResetPartialSearches
|
||||
| |
|
||||
v |
|
||||
+----------+ |
|
||||
@@ -262,7 +262,7 @@ Returns a table with the following columns:
|
||||
+----+-----+
|
||||
|
|
||||
v
|
||||
CompleteSearch
|
||||
usp_CompleteSearch
|
||||
|
|
||||
+---------------+
|
||||
| |
|
||||
|
||||
Reference in New Issue
Block a user