Files

T

Joseph Doherty 26ff8d9b4f Initial commit: JDE Scoping Tool migration project

Set up repository with legacy .NET Framework 4.8 source (OLD/),
new .NET 10 Blazor solution (NEW/), OpenSpec specifications,
documentation, and project configuration.

2026-01-02 07:43:29 -05:00

5.2 KiB

Raw Blame History

Implement Web API

Summary

Implement the REST API layer and real-time SignalR hub for the JDE Scoping Tool, providing HTTP endpoints for search management, lookup operations, file upload/download, and authentication. This phase creates the web-facing interface that connects the Blazor WebAssembly client to the backend search processing and data access layers.

Scope

In Scope

AuthController with login, logout, and current user endpoints
SearchController with CRUD operations and result downloads
LookupController with autocomplete APIs for items, profit centers, work centers, and operators
FileController with Excel upload/download for bulk data import
StatusHub SignalR hub for real-time status and search updates
IAuthService interface with LDAP and fake authentication implementations
LdapAuthService using System.DirectoryServices.Protocols (cross-platform)
FakeAuthService for development mode authentication bypass
LdapOptions and AuthOptions configuration classes
UserInfo model (renamed from legacy LDAPEntry)
API model DTOs (LoginRequest, AuthResult, FileUploadResult<T>, etc.)
Cookie-based session management with ASP.NET Core authentication
Service registration extension methods (AddWebApi, AddAuthentication)
OpenAPI/Swagger documentation
Unit tests with xUnit, Shouldly, and NSubstitute

Out of Scope

Blazor WebAssembly client implementation (Phase 9)
Background worker service (Phase 5: implement-data-sync)
Search execution logic (Phase 6: implement-search-processing)
Excel export generation (Phase 7: implement-excel-export)
Database schema changes (Phase 1: migrate-database-schema)
Rate limiting and advanced security (future enhancement)

Motivation

The Web API layer is the bridge between the Blazor WebAssembly client and the backend services. This phase delivers:

REST API Endpoints: Standard HTTP APIs for search, lookup, and file operations
Real-Time Updates: SignalR hub for live status updates during search processing
Cross-Platform Authentication: LDAP authentication using System.DirectoryServices.Protocols (not the Windows-only System.DirectoryServices)
Development Mode Support: Fake authentication for local development without LDAP server
OpenAPI Documentation: Auto-generated API documentation for Blazor client development

Acceptance Criteria

AuthController implements login, logout, and current user endpoints
SearchController implements all CRUD operations with proper authorization
LookupController implements autocomplete APIs without authorization (public access)
FileController implements Excel upload/download with caching
StatusHub broadcasts status and search updates to all connected clients
LdapAuthService authenticates against LDAP with group membership verification
FakeAuthService accepts any credentials when AuthOptions.UseFakeAuth = true
Cookie authentication configured with proper timeout and no redirect on 401
All protected endpoints return HTTP 401 (not redirect) for Blazor WASM compatibility
SignalR hub maps to /hubs/status endpoint
OpenAPI documentation generated via Swagger
All services registered via AddWebApi() extension method
Unit tests achieve >80% code coverage for controllers and services
openspec validate implement-web-api --strict passes

Dependencies

Phase	Dependency	Type
Phase 4: implement-data-access	`ILotFinderRepository` for lookups and search storage	Required
Phase 5: implement-data-sync	Worker service publishes status updates (soft dependency)	Soft
Phase 6: implement-search-processing	Search execution produces results	Required
Phase 7: implement-excel-export	`IExcelExportService` for file downloads	Required

Note: Controllers can be implemented with interface dependencies, allowing parallel development with mock implementations for testing.

Risks

Risk	Likelihood	Impact	Mitigation
LDAP connectivity issues	Medium	High	Implement `FakeAuthService` for development; add connection retry logic
`System.DirectoryServices.Protocols` complexity	Medium	Medium	Follow Microsoft documentation; create comprehensive LDAP integration tests
SignalR connection management	Low	Medium	Use ASP.NET Core SignalR defaults; implement client reconnection in Blazor
Cookie authentication with Blazor WASM	Low	Medium	Configure `SuppressAuthenticationChallengeOnUnauthorized`; test cross-origin scenarios
File upload size limits	Low	Low	Configure `IFormFile` limits in `Program.cs`; document limits
Memory cache expiration for file downloads	Low	Low	Use 1-minute expiration matching legacy; remove after download

web-api-auth/spec.md - Base specification for Web API and authentication
domain-models/spec.md - Domain entities used by controllers
data-access/spec.md - Repository interfaces for data operations
search-processing/spec.md - Search processing service interfaces
excel-export/spec.md - Excel export service for result downloads

5.2 KiB Raw Blame History