From 4e3e1c9df37d1436c1492c7ff3656222fa02663f Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 6 Jan 2026 15:47:17 -0500 Subject: [PATCH] docs: add SQL naming convention implementation plan --- ...06-sql-naming-convention-implementation.md | 591 ++++++++++++++++++ 1 file changed, 591 insertions(+) create mode 100644 PLANS/2026-01-06-sql-naming-convention-implementation.md diff --git a/PLANS/2026-01-06-sql-naming-convention-implementation.md b/PLANS/2026-01-06-sql-naming-convention-implementation.md new file mode 100644 index 0000000..967f500 --- /dev/null +++ b/PLANS/2026-01-06-sql-naming-convention-implementation.md @@ -0,0 +1,591 @@ +# SQL Object Naming Convention Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Rename stored procedures to use `usp_` prefix and functions to use `fn_` prefix for SQL Server best practice compliance. + +**Architecture:** Modify existing DbUp SQL scripts, update C# code to use centralized constants, manually sync Docker database since DbUp won't re-run already-executed scripts. + +**Tech Stack:** SQL Server, DbUp migrations, Dapper, SqlKata + +--- + +## Task 1: Update SubmitSearch Procedure Script + +**Files:** +- Modify: `src/JdeScoping.Database/Scripts/040_CreateSubmitSearchProcedure.sql` + +**Step 1: Read current script** + +Read the file to understand current content. + +**Step 2: Update procedure name** + +Change `[dbo].[SubmitSearch]` to `[dbo].[usp_SubmitSearch]` in the CREATE OR ALTER statement. + +```sql +-- Migration: 040_CreateSubmitSearchProcedure +-- Source: OLD/Database/StoredProcedures/SubmitSearch.sql +-- Creates a new search record with status=1 (Submitted) + +CREATE OR ALTER PROCEDURE [dbo].[usp_SubmitSearch] +( + @p_UserName VARCHAR(128), + @p_Name VARCHAR(128), + @p_Criteria VARCHAR(MAX), + @o_SearchID INT OUTPUT +) +AS +BEGIN + -- Insert new search record + INSERT INTO dbo.Search + ( + UserName, + Name, + Status, + SubmitDT, + Criteria + ) + VALUES + ( + @p_UserName, + @p_Name, + 1, + GETDATE(), + @p_Criteria + ); + + -- Get assigned auto-ID + SET @o_SearchID = SCOPE_IDENTITY(); +END +GO +``` + +**Step 3: Commit** + +```bash +git add src/JdeScoping.Database/Scripts/040_CreateSubmitSearchProcedure.sql +git commit -m "refactor(db): rename SubmitSearch to usp_SubmitSearch" +``` + +--- + +## Task 2: Update StartSearch Procedure Script + +**Files:** +- Modify: `src/JdeScoping.Database/Scripts/041_CreateStartSearchProcedure.sql` + +**Step 1: Update procedure name** + +Change `[dbo].[StartSearch]` to `[dbo].[usp_StartSearch]`: + +```sql +-- Migration: 041_CreateStartSearchProcedure +-- Source: OLD/Database/StoredProcedures/StartSearch.sql +-- Updates search status to 2 (Started) and sets start timestamp + +CREATE OR ALTER PROCEDURE [dbo].[usp_StartSearch] +( + @p_SearchID INT +) +AS +BEGIN + -- Update search status and start timestamp + UPDATE dbo.Search + SET Status = 2, + StartDT = GETDATE() + WHERE ID = @p_SearchID; +END +GO +``` + +**Step 2: Commit** + +```bash +git add src/JdeScoping.Database/Scripts/041_CreateStartSearchProcedure.sql +git commit -m "refactor(db): rename StartSearch to usp_StartSearch" +``` + +--- + +## Task 3: Update CompleteSearch Procedure Script + +**Files:** +- Modify: `src/JdeScoping.Database/Scripts/042_CreateCompleteSearchProcedure.sql` + +**Step 1: Update procedure name** + +Change `[dbo].[CompleteSearch]` to `[dbo].[usp_CompleteSearch]`: + +```sql +-- Migration: 042_CreateCompleteSearchProcedure +-- Source: OLD/Database/StoredProcedures/CompleteSearch.sql +-- Completes search with status 3 (Success) or 4 (Error) and stores results + +CREATE OR ALTER PROCEDURE [dbo].[usp_CompleteSearch] +( + @p_SearchID INT, + @p_WasSuccessful BIT, + @p_Results VARBINARY(MAX) +) +AS +BEGIN + DECLARE @v_Status INT; + + -- Determine status code + SET @v_Status = CASE @p_WasSuccessful + WHEN 1 THEN 3 + ELSE 4 + END; + + -- Update search status and results + UPDATE dbo.Search + SET Status = @v_Status, + Results = @p_Results, + EndDT = GETDATE() + WHERE ID = @p_SearchID; +END +GO +``` + +**Step 2: Commit** + +```bash +git add src/JdeScoping.Database/Scripts/042_CreateCompleteSearchProcedure.sql +git commit -m "refactor(db): rename CompleteSearch to usp_CompleteSearch" +``` + +--- + +## Task 4: Update ResetPartialSearches Procedure Script + +**Files:** +- Modify: `src/JdeScoping.Database/Scripts/043_CreateResetPartialSearchesProcedure.sql` + +**Step 1: Update procedure name** + +Change `[dbo].[ResetPartialSearches]` to `[dbo].[usp_ResetPartialSearches]`: + +```sql +-- Migration: 043_CreateResetPartialSearchesProcedure +-- Source: OLD/Database/StoredProcedures/ResetPartialSearches.sql +-- Resets searches that were started but not completed (cleanup after crash) + +CREATE OR ALTER PROCEDURE [dbo].[usp_ResetPartialSearches] +AS +BEGIN + -- Reset status and start timestamp for searches begun but not finished + UPDATE dbo.Search + SET Status = 1, + StartDT = NULL + WHERE StartDT IS NOT NULL + AND EndDT IS NULL; +END +GO +``` + +**Step 2: Commit** + +```bash +git add src/JdeScoping.Database/Scripts/043_CreateResetPartialSearchesProcedure.sql +git commit -m "refactor(db): rename ResetPartialSearches to usp_ResetPartialSearches" +``` + +--- + +## Task 5: Update MatchMIS Function Script + +**Files:** +- Modify: `src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql` + +**Step 1: Update function name** + +Change `[dbo].[MatchMIS]` to `[dbo].[fn_MatchMIS]` in the CREATE OR ALTER statement (line 7). + +**Step 2: Commit** + +```bash +git add src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql +git commit -m "refactor(db): rename MatchMIS to fn_MatchMIS" +``` + +--- + +## Task 6: Create SqlObjects Constants Class + +**Files:** +- Create: `src/JdeScoping.DataAccess/SqlObjects.cs` + +**Step 1: Create constants file** + +```csharp +namespace JdeScoping.DataAccess; + +/// +/// Constants for SQL stored procedure and function names. +/// +public static class SqlObjects +{ + // Stored Procedures + public const string SubmitSearch = "usp_SubmitSearch"; + public const string StartSearch = "usp_StartSearch"; + public const string CompleteSearch = "usp_CompleteSearch"; + public const string ResetPartialSearches = "usp_ResetPartialSearches"; + public const string ValidateSearchCriteria = "usp_ValidateSearchCriteria"; + + // Functions + public const string MatchMis = "fn_MatchMIS"; +} +``` + +**Step 2: Commit** + +```bash +git add src/JdeScoping.DataAccess/SqlObjects.cs +git commit -m "feat(data-access): add SqlObjects constants for SP/function names" +``` + +--- + +## Task 7: Update LotFinderRepository to Use SqlObjects + +**Files:** +- Modify: `src/JdeScoping.DataAccess/Repositories/LotFinderRepository.SearchManagement.cs` + +**Step 1: Update SubmitSearchAsync method** + +Find line 125 with `new SqlCommand("SubmitSearch", connection)` and change to use constant: + +```csharp +await using var command = new SqlCommand(SqlObjects.SubmitSearch, connection) +``` + +Also update the LogAndThrow call on line 150 to use the constant: + +```csharp +LogAndThrow(ex, operation, SqlObjects.SubmitSearch); +``` + +**Step 2: Build to verify** + +```bash +dotnet build src/JdeScoping.DataAccess +``` + +Expected: Build succeeds. + +**Step 3: Commit** + +```bash +git add src/JdeScoping.DataAccess/Repositories/LotFinderRepository.SearchManagement.cs +git commit -m "refactor(data-access): use SqlObjects constant for SubmitSearch" +``` + +--- + +## Task 8: Update MisQueryBuilder to Use SqlObjects + +**Files:** +- Modify: `src/JdeScoping.DataAccess/QueryBuilders/MisQueryBuilder.cs` + +**Step 1: Update MatchMIS reference** + +Find line 162 with `dbo.MatchMIS(` and change to use the new name: + +```csharp +dbo.fn_MatchMIS(c.WorkOrderNumber, c.ItemNumber, c.BranchCode, c.RoutingType, +``` + +Note: Since this is raw SQL embedded in a string, we change directly to `fn_MatchMIS` rather than interpolating the constant. The constant exists for documentation/discoverability. + +**Step 2: Build to verify** + +```bash +dotnet build src/JdeScoping.DataAccess +``` + +Expected: Build succeeds. + +**Step 3: Commit** + +```bash +git add src/JdeScoping.DataAccess/QueryBuilders/MisQueryBuilder.cs +git commit -m "refactor(data-access): rename MatchMIS to fn_MatchMIS in MisQueryBuilder" +``` + +--- + +## Task 9: Update Docker Database - Drop Old Objects + +**Step 1: Drop old procedures and function** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +DROP PROCEDURE IF EXISTS dbo.SubmitSearch; +DROP PROCEDURE IF EXISTS dbo.StartSearch; +DROP PROCEDURE IF EXISTS dbo.CompleteSearch; +DROP PROCEDURE IF EXISTS dbo.ResetPartialSearches; +DROP FUNCTION IF EXISTS dbo.MatchMIS; +" +``` + +**Step 2: Verify objects dropped** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +SELECT name, type_desc FROM sys.objects +WHERE type IN ('P', 'FN', 'TF', 'IF') +AND name IN ('SubmitSearch', 'StartSearch', 'CompleteSearch', 'ResetPartialSearches', 'MatchMIS') +" +``` + +Expected: 0 rows returned. + +--- + +## Task 10: Update Docker Database - Create New Procedures + +**Step 1: Create usp_SubmitSearch** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +CREATE OR ALTER PROCEDURE [dbo].[usp_SubmitSearch] +( + @p_UserName VARCHAR(128), + @p_Name VARCHAR(128), + @p_Criteria VARCHAR(MAX), + @o_SearchID INT OUTPUT +) +AS +BEGIN + INSERT INTO dbo.Search (UserName, Name, Status, SubmitDT, Criteria) + VALUES (@p_UserName, @p_Name, 1, GETDATE(), @p_Criteria); + SET @o_SearchID = SCOPE_IDENTITY(); +END +" +``` + +**Step 2: Create usp_StartSearch** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +CREATE OR ALTER PROCEDURE [dbo].[usp_StartSearch] (@p_SearchID INT) +AS +BEGIN + UPDATE dbo.Search SET Status = 2, StartDT = GETDATE() WHERE ID = @p_SearchID; +END +" +``` + +**Step 3: Create usp_CompleteSearch** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +CREATE OR ALTER PROCEDURE [dbo].[usp_CompleteSearch] +( + @p_SearchID INT, + @p_WasSuccessful BIT, + @p_Results VARBINARY(MAX) +) +AS +BEGIN + DECLARE @v_Status INT = CASE @p_WasSuccessful WHEN 1 THEN 3 ELSE 4 END; + UPDATE dbo.Search SET Status = @v_Status, Results = @p_Results, EndDT = GETDATE() WHERE ID = @p_SearchID; +END +" +``` + +**Step 4: Create usp_ResetPartialSearches** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +CREATE OR ALTER PROCEDURE [dbo].[usp_ResetPartialSearches] +AS +BEGIN + UPDATE dbo.Search SET Status = 1, StartDT = NULL WHERE StartDT IS NOT NULL AND EndDT IS NULL; +END +" +``` + +--- + +## Task 11: Update Docker Database - Create fn_MatchMIS + +**Step 1: Copy script content and execute** + +The MatchMIS function is too large for inline execution. Read the updated script file and execute via sqlcmd with input redirection or copy the content. + +```bash +# Copy the SQL file to Docker container and execute +docker cp src/JdeScoping.Database/Scripts/044_CreateMatchMisFunction.sql scopingtool-sqlserver:/tmp/ +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -i /tmp/044_CreateMatchMisFunction.sql +``` + +**Step 2: Verify all new objects exist** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +SELECT name, type_desc FROM sys.objects +WHERE type IN ('P', 'FN', 'TF', 'IF') +ORDER BY type_desc, name +" +``` + +Expected: All procedures show `usp_` prefix, all functions show `fn_` prefix. + +--- + +## Task 12: Run Full Test Suite + +**Step 1: Build entire solution** + +```bash +dotnet build +``` + +Expected: Build succeeds. + +**Step 2: Run all tests** + +```bash +dotnet test +``` + +Expected: All tests pass (including database tests that use the renamed objects). + +**Step 3: Commit verification** + +No commit needed - verification only. + +--- + +## Task 13: Update OpenSpec sql-business-logic Spec + +**Files:** +- Modify: `openspec/specs/sql-business-logic/spec.md` + +**Step 1: Update all procedure/function references** + +Replace: +- `SubmitSearch` with `usp_SubmitSearch` +- `StartSearch` with `usp_StartSearch` +- `CompleteSearch` with `usp_CompleteSearch` +- `ResetPartialSearches` with `usp_ResetPartialSearches` +- `MatchMIS` with `fn_MatchMIS` (but keep descriptive references like "MatchMIS function" as-is for readability) + +**Step 2: Commit** + +```bash +git add openspec/specs/sql-business-logic/spec.md +git commit -m "docs(openspec): update sql-business-logic with usp_/fn_ prefixes" +``` + +--- + +## Task 14: Update OpenSpec database-schema Spec + +**Files:** +- Modify: `openspec/specs/database-schema/spec.md` + +**Step 1: Update all procedure/function references** + +Same replacements as Task 13. + +**Step 2: Commit** + +```bash +git add openspec/specs/database-schema/spec.md +git commit -m "docs(openspec): update database-schema with usp_/fn_ prefixes" +``` + +--- + +## Task 15: Update OpenSpec data-access Spec + +**Files:** +- Modify: `openspec/specs/data-access/spec.md` + +**Step 1: Update procedure references** + +Replace `EXEC dbo.SubmitSearch` with `EXEC dbo.usp_SubmitSearch` and similar. + +**Step 2: Commit** + +```bash +git add openspec/specs/data-access/spec.md +git commit -m "docs(openspec): update data-access with usp_ prefix" +``` + +--- + +## Task 16: Update OpenSpec search-processing Spec + +**Files:** +- Modify: `openspec/specs/search-processing/spec.md` + +**Step 1: Update MatchMIS references** + +Replace `dbo.MatchMIS` with `dbo.fn_MatchMIS`. + +**Step 2: Commit** + +```bash +git add openspec/specs/search-processing/spec.md +git commit -m "docs(openspec): update search-processing with fn_MatchMIS" +``` + +--- + +## Task 17: Update Architecture Documentation + +**Files:** +- Modify: `DOCUMENTATION/Architecture/Testing.md` +- Modify: `DOCUMENTATION/Architecture/Database.md` + +**Step 1: Update Testing.md** + +Search for `SubmitSearch` and update any references. + +**Step 2: Update Database.md** + +Search for stored procedure references and update with `usp_` prefix. + +**Step 3: Commit** + +```bash +git add DOCUMENTATION/Architecture/Testing.md DOCUMENTATION/Architecture/Database.md +git commit -m "docs: update architecture docs with usp_/fn_ prefixes" +``` + +--- + +## Task 18: Final Verification + +**Step 1: Verify Docker database naming** + +```bash +docker exec scopingtool-sqlserver /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P 'ScopingTool_SA_2024Dev' -C -d ScopingTool -Q " +SELECT 'Procedures' as Type, name FROM sys.procedures WHERE schema_id = SCHEMA_ID('dbo') ORDER BY name; +SELECT 'Functions' as Type, name FROM sys.objects WHERE type IN ('FN', 'TF', 'IF') AND schema_id = SCHEMA_ID('dbo') ORDER BY name; +" +``` + +Expected: +- All procedures start with `usp_` +- All functions start with `fn_` + +**Step 2: Run full test suite one more time** + +```bash +dotnet test +``` + +Expected: All tests pass. + +**Step 3: Final commit (if any uncommitted changes)** + +```bash +git status +``` + +If clean, no action needed.