jdescopingtool/docs/plans/2025-01-01-additional-specs-design.md

Additional OpenSpec Specifications Design

Overview

This document describes three new OpenSpec specifications to capture legacy SQL business logic and web UI, extending the existing 7 specs in the legacy-spec-capture-plan.

New Specifications

Session 8: sql-business-logic

Purpose: Capture business logic in stored procedures and functions.

Source Files:

• OLD/Database/StoredProcedures/SubmitSearch.sql
• OLD/Database/StoredProcedures/StartSearch.sql
• OLD/Database/StoredProcedures/CompleteSearch.sql
• OLD/Database/StoredProcedures/ResetPartialSearches.sql
• OLD/Database/Functions/MatchMis.sql

Requirements to Document:

Procedure/Function	Purpose	Key Business Logic
SubmitSearch	Create new search record	Inserts Search with Status=Queued, returns new ID via OUTPUT
StartSearch	Mark search as processing	Updates Status to Processing, sets StartDT
CompleteSearch	Finalize search with results	Updates Status to Complete/Failed, stores Excel binary, sets EndDT
ResetPartialSearches	Recovery on service restart	Resets stuck "Processing" searches back to "Queued"
MatchMis	Table-valued function for MIS matching	Complex matching logic against MIS data based on item/operation/routing

Dependencies: database-schema, domain-models

---

Session 9: sql-views-types

Purpose: Capture SQL views and table-valued parameter types.

Source Files:

• OLD/Database/Views/*.sql (7 files)
• OLD/Database/Types/*.sql (7 files)

Views to Document:

View	Purpose	Underlying Tables
LastDataUpdates	Latest successful sync per table/type	DataUpdate (aggregated)
WorkOrderTotalScrap	Aggregated scrap quantities	WorkOrderStep_Curr/Hist
WorkOrder	Union of _Curr and _Hist	WorkOrder_Curr, WorkOrder_Hist
WorkOrderTime	Union of _Curr and _Hist	WorkOrderTime_Curr, WorkOrderTime_Hist
WorkOrderStep	Union of _Curr and _Hist	WorkOrderStep_Curr, WorkOrderStep_Hist
WorkOrderComponent	Union of _Curr and _Hist	WorkOrderComponent_Curr, WorkOrderComponent_Hist
LotUsage	Union of _Curr and _Hist	LotUsage_Curr, LotUsage_Hist

Table-Valued Parameter Types to Document:

Type	Columns	Used By
WorkOrderFilterParameter	WorkOrderNumber (bigint)	Search query building
ItemNumberFilterParameter	ItemNumber (nvarchar)	Search query building
ProfitCenterFilterParameter	Code (nvarchar)	Search query building
WorkCenterFilterParameter	Code (nvarchar)	Search query building
OperatorFilterParameter	UserName (nvarchar)	Search query building
ComponentLotFilterParameter	LotNumber, ItemNumber	Search query building
ItemOperationMISFilterParameter	ItemNumber, Operation, MisNumber, MisRevision	MIS extraction

Dependencies: database-schema, domain-models

---

Session 10: web-ui

Purpose: Capture web UI pages, components, interactions, and map to Blazor/Radzen.

Source Files:

• OLD/WebInterface/Views/**/*.cshtml
• OLD/WebInterface/Scripts/*.js

Pages to Document:

Page	Legacy View	Purpose
Login	Account/Login.cshtml	LDAP authentication form
NotAuthorized	Account/NotAuthorized.cshtml	Access denied message
Search List	Search/Index.cshtml	User's searches with grid, status, download
Search Create/Edit	Search/Create.cshtml	Multi-filter search form with 8 filter types
Search Queue	Search/Queue.cshtml	Admin view of all queued searches
Refresh Status	RefreshStatus/Index.cshtml	Data sync status dashboard
Layout	Shared/_Layout.cshtml	Navigation, header, SignalR connection

For Each Page, Document:

1. Layout/Structure - Header, sections, footer
2. Components - Each UI control with legacy (Kendo) → new (Radzen) mapping
3. Data Binding - What data is displayed, how it's loaded
4. Interactions - Button clicks, form submissions, real-time updates
5. Validation - Client-side and server-side rules
6. Radzen Implementation - Component markup with properties and event handlers

Component Mapping Format:

UI Element	Legacy (Kendo)	Radzen Component	Key Properties
Data grid	kendoGrid	RadzenDataGrid<T>	AllowPaging, AllowSorting
Multi-select	kendoMultiSelect	RadzenDropDown	Multiple="true"
Date picker	kendoDatePicker	RadzenDatePicker	DateFormat
Button	Kendo button	RadzenButton	Icon, ButtonStyle

Radzen Implementation Example:

<RadzenDataGrid @ref="grid" Data="@searches" TItem="SearchViewModel"
                AllowPaging="true" PageSize="10" AllowSorting="true"
                IsLoading="@isLoading">
    <Columns>
        <RadzenDataGridColumn TItem="SearchViewModel" Property="Name" Title="Search Name" />
        <RadzenDataGridColumn TItem="SearchViewModel" Property="Status" Title="Status">
            <Template Context="search">
                <RadzenBadge BadgeStyle="@GetStatusStyle(search.Status)" Text="@search.Status.ToString()" />
            </Template>
        </RadzenDataGridColumn>
    </Columns>
</RadzenDataGrid>

Dependencies: All previous specs (full system context needed)

---

Session Workflow

Each session follows the established workflow:

1. SCOPE - List files to analyze
2. ANALYZE - Read legacy files, extract behaviors/rules
3. DRAFT - Write spec.md following OpenSpec format
4. REVIEW - Two-step validation:
   • Format: openspec validate --specs
   • Content: Codex MCP cross-reference against legacy source
5. COMMIT - Save to openspec/specs/<area>/spec.md
6. HANDOFF - Summary and open questions

Codex MCP Review Prompts

For sql-business-logic:

"Review sql-business-logic/spec.md against OLD/Database/StoredProcedures/.sql and OLD/Database/Functions/.sql. Verify all parameters, return values, error conditions, and business rules are accurately captured."

For sql-views-types:

"Review sql-views-types/spec.md against OLD/Database/Views/.sql and OLD/Database/Types/.sql. Verify column definitions, join logic, and TVP schemas are accurate."

For web-ui:

"Review web-ui/spec.md against OLD/WebInterface/Views/**/*.cshtml. Verify all UI elements, interactions, and data bindings are captured. Check that Radzen component mappings are appropriate."

OpenSpec Format Requirements

All specs MUST follow OpenSpec format:

• ## Purpose section (not Overview)
• ### Requirement: with SHALL/MUST language
• #### Scenario: with WHEN/THEN format
• Validate with openspec validate --specs before commit

Updates Required

Update PLANS/legacy-spec-capture-plan.md:

• Add Sessions 8, 9, 10 to execution order table
• Add session checklists for each new spec
• Update spec organization diagram