jdescopingtool/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **migration project** to convert a legacy .NET Framework 4.8 application ("LotFinder" / JDE Scoping Tool) to .NET 10.

### Folder Structure
```
JdeScopingTool/
├── OLD/            # Legacy .NET Framework 4.8 source code (read-only reference)
├── NEW/            # New .NET 10 solution (build here)
│   └── JdeScoping.slnx   # Solution file (.slnx format)
├── openspec/       # OpenSpec specifications and design documents
├── PLANS/          # Design plans, implementation plans, and task lists
└── DOCUMENTATION/  # Project documentation
```

### Build Commands
The solution uses the `.slnx` format (XML-based solution file):
```bash
# Build entire solution
dotnet build NEW/JdeScoping.slnx

# Run all tests
dotnet test NEW/JdeScoping.slnx

# Build specific project
dotnet build NEW/src/JdeScoping.Host/JdeScoping.Host.csproj
```

### Legacy System Purpose
A manufacturing/ERP search tool that:
- Caches data from JDE (JD Edwards - Oracle) and CMS (Sybase) enterprise systems into SQL Server
- Allows users to create complex searches across work orders, lots, items, operators, and work centers
- Processes searches asynchronously and exports results to Excel
- Provides real-time status updates via SignalR

### Migration Target
- **Single .NET 10 service** (combines the legacy web app + worker service)
- **Blazor WebAssembly UI** (replaces ASP.NET MVC + Razor views)

## Legacy Architecture (OLD/)

### Solution Structure
```
OLD/LotFinder.sln
├── WebInterface/       # ASP.NET MVC 5 web application
├── WorkerService/      # Windows Service (Topshelf) - search processor + data refresher
├── DataModel/          # Shared library (Commons.csproj) - models, DB access, helpers
├── Database/           # SQL Server database project (.sqlproj)
└── TestApp/            # Console test application
```

### Key Components

**WebInterface** - ASP.NET MVC with SignalR
- Controllers: `SearchController` (main), `LookupController` (autocomplete APIs), `AccountController` (LDAP auth)
- SignalR Hub: `StatusHub` for real-time search status updates
- Uses Forms auth with LDAP backend

**WorkerService** - Background processor (Topshelf service)
- `WorkProcessor`: Main work loop - checks for pending data updates, then processes queued searches
- `UpdateProcessor`: Syncs data from JDE/CMS to local SQL Server cache (mass/daily/hourly schedules)
- `ExcelWriter`: Generates Excel output using EPPlus
- Data source configs in `dsconfig/*.json` files

**DataModel (Commons)** - Shared library
- `Process/LotFinderDB*.cs`: SQL Server cache database access (Dapper)
- `Process/JDE*.cs`: Oracle JDE queries
- `Process/CMS*.cs`: Sybase CMS queries
- `Models/`: Domain models (WorkOrder, Lot, Item, Search, etc.)
- `ViewModels/`: DTOs for API responses
- `Config.cs`: Connection strings (encrypted passwords)

### Data Flow
1. User submits search via web UI -> stored in `Search` table with status=Queued
2. WorkerService polls for queued searches
3. Service executes search against local cache, generates Excel
4. Results stored in `Search.Results` (VARBINARY), status updated
5. SignalR pushes status updates to connected clients

### Key Database Tables
- `Search`: User search requests and results
- `DataUpdate`: Tracks cache refresh timestamps per table
- `WorkOrder_Curr/Hist`, `LotUsage_Curr/Hist`, etc.: Cached JDE data (current + historical)
- `Lot`, `Item`, `ProfitCenter`, `WorkCenter`, `JdeUser`: Reference data

### External Dependencies
- **DDTek.Oracle**: Progress DataDirect Oracle driver
- **Sybase.AdoNet4.AseClient**: Sybase database driver
- **Dapper**: Micro-ORM for SQL queries
- **EPPlus**: Excel generation
- **Topshelf**: Windows service hosting
- **SignalR**: Real-time web communication

## Migration Considerations

### What to Preserve
- Search criteria model (`SearchCriteria`, `SearchCriteriaViewModel`)
- JDE/CMS query logic (files in `DataModel/Process/JDE*.cs`, `CMS*.cs`)
- Excel generation logic (`WorkerService/Process/ExcelWriter.cs`)
- Data sync scheduling patterns (mass/daily/hourly from dsconfig)
- Query templates (`WorkerService/Templates/QueryTemplate.cs`)

### What Changes
- Topshelf -> .NET hosted service with BackgroundService
- SignalR (legacy) -> modern ASP.NET Core SignalR
- ASP.NET MVC -> Blazor WebAssembly
- Forms auth -> ASP.NET Core Identity with LDAP
- `System.Data.SqlClient` -> `Microsoft.Data.SqlClient`

### Authentication Pattern
Legacy uses LDAP authentication with group membership check. Config values:
- `LDAPUrl`: Directory server URL(s)
- `LDAPGroup`: Required group membership

## OpenSpec Workflow

This project uses OpenSpec for change management. Specifications are stored in the `openspec/` directory using the standard OpenSpec layout.

### Directory Structure
```
openspec/
├── project.md          # Project overview and spec organization
├── AGENTS.md           # Agent guidelines and templates
├── specs/              # Specification files by functional area
│   ├── domain-models/
│   ├── database-schema/
│   ├── data-access/
│   ├── data-sync/
│   ├── search-processing/
│   ├── excel-export/
│   └── web-api-auth/
└── changes/            # Change proposals
```

### Spec Formatting Rules

Specs MUST follow OpenSpec format for validation to pass:

1. **Purpose section**: Use `## Purpose` (not `## Overview`)

2. **Requirements**: Use SHALL/MUST language
   ```markdown
   ### Requirement: Search entity
   The system SHALL store user search requests containing filter criteria.
   ```

3. **Scenarios**: Use WHEN/THEN format (not Given/When/Then)
   ```markdown
   #### Scenario: Submit new search
   - **WHEN** a user creates a search with name and criteria
   - **THEN** a new Search record is created with Status = New
   ```

### Validation

Validate specs with the OpenSpec CLI:
```bash
openspec validate --specs        # Validate all specs
openspec list --specs            # List specs with requirement counts
```

### Change Workflows

See `.claude/commands/openspec/` for proposal, apply, and archive workflows. Key principles:
- Favor minimal implementations
- Keep changes tightly scoped
- Create design docs before implementation

## Documentation Guidelines

When writing or updating documentation, consult the `DOCUMENTATION/Instructions/` folder:

- **[GeneratingDocs.md](DOCUMENTATION/Instructions/GeneratingDocs.md)** - How to create new documentation
- **[UpdatingDocs.md](DOCUMENTATION/Instructions/UpdatingDocs.md)** - When and how to update existing docs
- **[StyleGuide.md](DOCUMENTATION/Instructions/StyleGuide.md)** - Writing conventions and formatting rules
- **[ComponentMap.md](DOCUMENTATION/Instructions/ComponentMap.md)** - Maps source code to documentation folders

Key principles:
- Read source code before documenting
- Use code snippets from actual codebase (never invent examples)
- Follow the component mapping for file organization
- Update documentation when code changes

## Plans and Task Lists

Store design plans, implementation plans, and task list files in the `PLANS/` folder:

- **Design plans** - Architecture decisions, component designs
- **Implementation plans** - Step-by-step implementation guides
- **Task lists** - Tracked work items and checklists

This keeps planning artifacts organized and separate from specifications (SPECS/) and documentation (DOCUMENTATION/).

## Local Development Database

The **[db_info.md](db_info.md)** file contains connection information for the local SQL Server development database:

- Docker container details (`scopingtool-sqlserver` on port 1434)
- SA credentials (admin access)
- Application credentials (`scopingapp` user with read/write/execute/truncate permissions)
- Connection strings for .NET configuration

**Note:** This file contains plain-text credentials for local development only. Do not commit to source control or use in production.

## Coding Guidelines

### DTOs and Models: Use Classes, Not Records

This project uses **classes** (not C# records) for all DTOs, ViewModels, and model types. This convention provides:

- **Consistency** - All model types follow the same pattern
- **Explicit mutability** - Properties use `{ get; set; }` for clear intent
- **Serialization compatibility** - Better compatibility with JSON serializers and Dapper
- **Debugging ease** - Standard class behavior in debuggers and test assertions

```csharp
// Preferred: class with explicit properties
public class WorkOrderViewModel
{
    public string OrderNumber { get; set; } = string.Empty;
    public DateTime? CompletionDate { get; set; }
}

// Avoid: record types for DTOs
public record WorkOrderViewModel(string OrderNumber, DateTime? CompletionDate);
```