# 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;

/// <summary>
/// Constants for SQL stored procedure and function names.
/// </summary>
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.