GuyStore - Stage 2 Build Conversation

Building all 9 extension points in 10 tracked tasks:

1. ✓ Done Stock deduction on order placement + out-of-stock guard
2. ✓ Done Pagination (product list, order list, shop, my orders)
3. ✓ Done User self-service password change from Profile page
4. ✓ Done Third theme (Forest Green) + CSS variable customization panel
5. ✓ Done Email notifications (SMTP, graceful no-op when unconfigured)
6. ✓ Done Two-way SignalR support chat (user ↔ admin)
7. ✓ Done Invoice PDF generation (QuestPDF)
8. ✓ Done Fine-grained permissions (Viewer + SalesRep roles)
9. ✓ Done Stage 2 test suite (Unit · Integration · E2E)
10. ✓ Done stage2_conversation.html documentation

Note on product images: The Product model already has ImageData byte[] and ImageMimeType fields from Stage 1, and ProductsController.ApplyImageAsync already stores binary in SQL Server. ShopController.Image(id) serves them with a 1-hour response cache. Stage 2 confirms and tests this path - no wwwroot/uploads/ storage is used.

Component	Location	Detail
Model	Models/Product.cs	byte[]? ImageData + string? ImageMimeType + string? ImageUrl (external fallback)
DB column	Data/ApplicationDbContext.cs	HasColumnType("varbinary(max)")
Upload handler	Areas/Admin/Controllers/ProductsController.ApplyImageAsync	Validates MIME type (JPEG/PNG/GIF/WebP), max 5 MB, stores raw bytes
Serve endpoint	Controllers/ShopController.Image(int id)	Returns File(ImageData, ImageMimeType) with [ResponseCache(Duration=3600)]
Views	Shop/Index, Shop/Detail, Admin/Products/Index	Prefer DB image; fall back to ImageUrl; fall back to placeholder

Seeded products use ImageUrl pointing to picsum.photos. Uploaded products use binary storage. The two paths coexist gracefully.

Before saving the order, all cart items are checked against current StockQuantity. Any shortfall adds a model error and returns the checkout view without placing the order. On success, stock is decremented atomically in the same SaveChangesAsync call as the order insert.

// Stock availability check before committing anything
var products = await _db.Products.Where(p => productIds.Contains(p.Id)).ToListAsync();
foreach (var item in items)
{
    var product = products.FirstOrDefault(p => p.Id == item.ProductId);
    if (product is null || product.StockQuantity < item.Quantity)
        ModelState.AddModelError("", $"'{item.ProductName}' has insufficient stock (available: {product?.StockQuantity ?? 0}).");
}
if (!ModelState.IsValid) return View(model);

// ... build order ...

// Deduct stock atomically with the order save
foreach (var item in items)
    products.First(p => p.Id == item.ProductId).StockQuantity -= item.Quantity;

_db.Orders.Add(order);
await _db.SaveChangesAsync();

Page	Route	Page size
Public shop	GET /Shop?page=N&search=&category=	12 cards
Admin products	GET /Admin/Products?page=N	12 rows
Admin orders	GET /Admin/Orders?page=N&status=	15 rows
My Orders	GET /Cart/MyOrders?page=N	10 rows

Helper: Models/PaginatedList.cs - uses EF async when the provider supports it, falls back to synchronous LINQ (enables unit testing without EF).

Partial view: Views/Shared/_Pagination.cshtml - renders a Bootstrap pagination nav that preserves all current query string parameters (search, category, status) when changing pages.

Component	Detail
Models/ViewModels/AccountViewModels.SelfChangePasswordViewModel	CurrentPassword, NewPassword (min 6), ConfirmPassword with [Compare]
AccountController.ChangePassword POST	Calls UserManager.ChangePasswordAsync (requires correct current password), then RefreshSignInAsync to keep session alive
Views/Account/Profile.cshtml	Side-by-side card layout: Account Details (left) + Change Password form (right)

The admin-side force reset (no current password required) remains in Admin/Accounts/ChangePassword and uses GeneratePasswordResetTokenAsync.

Theme	File	Primary Color	Feel
Corporate Blue	themes/corporate.css	#1a56db	Professional, light - default
Dark Slate	themes/dark.css	#6366f1	Modern dark, indigo accents
Forest Green	themes/forest.css	#16a34a	Fresh, green, nature feel

Customization panel at GET /Theme/Customize: live color pickers for Primary Color, Navbar/Sidebar, and Page Background. Changes preview instantly via CSS variable injection. On save, POST /Theme/ApplyCustom stores a JSON blob in the SiteCustom cookie (1-year expiry). Both layouts inject an inline <style> block that overrides the base theme's CSS variables.

POST /Theme/ResetCustom clears the override cookie and returns to the base theme's defaults.

To add a fourth theme: create wwwroot/css/themes/yourtheme.css, add the name to ThemeController.ValidThemes, and add the button to both layout dropdowns.

File	Purpose
Services/IEmailService.cs	Interface: SendAsync(to, subject, htmlBody)
Services/SmtpEmailService.cs	Reads Smtp:* config, sends via System.Net.Mail.SmtpClient. Logs and no-ops silently when Smtp:Host is blank.

Triggers:

• Account approval - Admin/Accounts/Approve sends a welcome email to the approved user
• Order confirmation - CartController.Checkout POST sends an itemised HTML receipt

SMTP configuration in appsettings.json (leave Host blank to skip all email in development):

"Smtp": {
  "Host": "",          // e.g. smtp.sendgrid.net
  "Port": 587,
  "EnableSsl": true,
  "UserName": "",
  "Password": "",
  "FromAddress": "[email protected]",
  "FromName": "GuyStore"
}

To use SendGrid: set Host to smtp.sendgrid.net, UserName to apikey, Password to your API key.

Component	File	Notes
Hub	Hubs/SupportHub.cs	In-memory session store (resets on restart). Groups: "admins" and "user_{userId}"
Model	Models/ChatMessage.cs	Record: From, Text, SentAt, IsAdmin
Client widget	wwwroot/js/support-chat.js	Floating 💬 button bottom-left; chat panel with history replay; unread badge
Admin inbox	Areas/Admin/Controllers/SupportController.cs + Views/Support/Index.cshtml	Session list (left) + live chat panel (right); admin can reply to any session

Hub methods:

// Client → hub
UserSend(text)           // logged-in user sends message
AdminReply(userId, text) // admin replies to a specific session

// Hub → client
ReceiveMessage(msg)      // message delivered to correct party
UserMessage(uid, name, msg)  // admin inbox receives new user message
AdminReplySent(uid, msg)     // admin's own UI echo
SessionList(list)        // session summary on admin connect
History(messages)        // replay for user on reconnect

The chat widget is only injected for authenticated non-admin users. Admins have the dedicated Support Inbox page in the admin panel.

Root cause: The browser parses and executes <script> tags synchronously, in document order - each one must finish before the next one starts. In the original _Layout.cshtml, support-chat.js was placed before signalr.min.js:

<!-- WRONG ORDER (before fix) -->
@if (authenticated && !isAdmin)
{
    <script>window.__supportChatEnabled = true;</script>
    <script src="~/js/support-chat.js"></script>   <!-- signalR is still undefined here! -->
}
...
<script src="~/lib/microsoft/signalr/.../signalr.min.js"></script>

When support-chat.js executed, signalR had not yet been defined. The line:

const connection = new signalR.HubConnectionBuilder()...

threw a ReferenceError: signalR is not defined. Because the error occurred inside an IIFE, it was swallowed silently - no crash visible, no console error surfaced in a way that was obvious. The connection was never established and no event listeners were ever wired up, so clicking the chat button did nothing.

Fix 1 - _Layout.cshtml: move the script tag to after SignalR

The widget HTML (DOM elements) stays in place, but the <script> tag for support-chat.js is moved to the bottom of the body, after signalr.min.js is loaded:

<!-- Widget HTML stays here - DOM elements only, no script -->
@if (authenticated && !isAdmin)
{
    <div id="supportChatWidget">...</div>
}

<script src="~/lib/jquery/dist/jquery.min.js"></script>
<script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
<script src="~/lib/microsoft/signalr/.../signalr.min.js"></script>
<script src="~/js/notifications.js"></script>
@if (authenticated && !isAdmin)
{
    <!-- support-chat.js AFTER signalr.min.js -->
    <script src="~/js/support-chat.js"></script>
}

Fix 2 - support-chat.js: replace global flag guard with DOM presence check

The original guard relied on a window.__supportChatEnabled = true flag set by an inline <script> tag that ran immediately before the IIFE. This created a two-part dependency chain with the same ordering fragility. The flag was removed and replaced with a self-contained DOM check:

// Before:
(function () {
    if (!window.__supportChatEnabled) return;
    const connection = new signalR.HubConnectionBuilder()...
    // ...
    const toggle = document.getElementById('supportChatToggle');  // duplicate declaration

// After:
(function () {
    const toggle = document.getElementById('supportChatToggle');
    if (!toggle) return;  // widget not in DOM - script exits cleanly
    const connection = new signalR.HubConnectionBuilder()...

The DOM check is better for two reasons: (1) it is entirely self-contained - the script decides for itself whether it should run based on what is actually in the page, with no dependency on a separately-injected global; (2) it also removes the duplicate const toggle declaration that would have caused a SyntaxError in strict mode.

Why the fix works: By the time support-chat.js executes, signalr.min.js has already run and the signalR global is fully defined. new signalR.HubConnectionBuilder() succeeds, connection.start() is called, and all event listeners are registered. The chat button responds immediately on click.

Component	File/Route
Service	Services/InvoiceService.cs - generates A4 PDF with header, bill-to, PO details, line-item table, totals, footer
User endpoint	GET /Cart/Invoice/{id} - returns PDF only for orders belonging to the current user
Admin endpoint	GET /Admin/Orders/Invoice/{id} - admin can download invoice for any order
My Orders link	PDF column added to Views/Cart/MyOrders.cshtml
Admin detail	⬇ Download Invoice button on Areas/Admin/Views/Orders/Detail.cshtml

PDF uses the GuyStore corporate blue (#1a56db) for header, alternating row backgrounds, and a page-number footer. QuestPDF community license is declared in the static constructor.

Role	Can do	Cannot do
Administrator	Everything	-
AccountManagement	User approval, password reset, account lock/unlock	Products, orders, notifications
Registered	Shop browsing, cart, checkout, my orders	Admin panel
SalesRep	Same as Registered - shop, cart, checkout, my orders	Admin panel
Viewer	Browse shop, view product details	Cart, checkout (Viewer accounts cannot add items to cart message shown)

Role assignment UI: Admins see a Roles button on each user row in Admin/Accounts/Index. Clicking it opens a Bootstrap modal with checkboxes for all 5 assignable roles. POST /Admin/Accounts/UpdateRoles handles the update.

Seeding: DataSeeder now seeds all 5 roles on startup.

Project	Type	Total tests	New in Stage 2
GuyStore.Tests.Unit	Unit (xUnit)	38	+5 (PaginatedList ×3, EmailService ×1, InvoiceService ×1)
GuyStore.Tests.Integration	Integration (HTTP)	60	+17 (pagination, password change, theme, invoice, roles, chat, stock)
GuyStore.Tests.E2E	E2E (Playwright)	29	+8 (forest theme, customize, profile form, shop count, support widget, inbox, roles, invoice 404)
wwwroot/js/support-chat.test.js	JS unit (Jest + jsdom)	12	+12 (guard, toggle, ReceiveMessage, History, send - all widget behaviours)

New Unit Tests

• PaginatedListTests - first page slice, last page flags, empty source
• EmailServiceTests - SendAsync with unconfigured SMTP is a no-op (no throw)
• InvoiceServiceTests - Generate returns valid PDF bytes (magic bytes %PDF check)
• support-chat.test.js (Jest + jsdom) - 12 tests covering all widget behaviours: guard, toggle open/close, ReceiveMessage alignment + badge logic, History replay, send flow, blank-input guard, Enter key, other-key non-trigger. Run with npm run test:js

New Integration Tests (Stage2IntegrationTests.cs)

• Pagination - ShopIndex returns paginated products; page=2 returns 200; Admin Products, Orders, and MyOrders all accept ?page= parameter
• Password change - Profile page shows Change Password form with CurrentPassword field; wrong current password stays on profile with error
• Forest theme - POST to /Theme/Switch sets SiteTheme cookie to "forest"; /Theme/Customize returns 200 and contains theme names
• Email (no-op) - Approve account endpoint reachable without SMTP configured (no exception thrown)
• Invoice - /Admin/Orders/Invoice/99999 returns 404; /Cart/Invoice/99999 returns 404
• Roles UI - Accounts page shows Roles button for admin; modal contains Viewer and SalesRep options
• Support chat - Support Inbox accessible to admin; redirects/forbids for AccountManagement user
• Stock deduction - Checkout GET succeeds after adding item to cart

New E2E Tests (Stage2Tests.cs)

• ThemeTests - Forest theme switch sets SiteTheme cookie; /Theme/Customize page is accessible
• ProfileTests - Profile page shows Change Password form
• ShopTests - Shop page renders product content
• SupportChatTests - Admin user does NOT see the support chat widget; admin can access Support Inbox page
• RolesTests - Accounts page shows Viewer and SalesRep role options
• InvoiceTests - /Cart/Invoice/99999 returns 404

How to Run the Tests

All C# test suites use an InMemory EF database - no SQL Server or external services required.

1 - Unit tests (xUnit)

cd "C:\Guy\Notes\Claud Projects\Guy"
dotnet test GuyStore.Tests.Unit\GuyStore.Tests.Unit.csproj

2 - Integration tests (xUnit + WebApplicationFactory)

dotnet test GuyStore.Tests.Integration\GuyStore.Tests.Integration.csproj

No separate server needed. GuyStoreWebApplicationFactory hosts the app in-process with an InMemory EF database.

3 - E2E tests (Playwright + headless Chromium)

One-time browser install - run once after the first build:

cd "C:\Guy\Notes\Claud Projects\Guy"
dotnet build GuyStore.Tests.E2E\GuyStore.Tests.E2E.csproj
pwsh GuyStore.Tests.E2E\bin\Debug\net9.0\playwright.ps1 install chromium

On Windows PowerShell (not pwsh) use powershell instead of pwsh. This step is only needed once per machine.

Then run the suite:

dotnet test GuyStore.Tests.E2E\GuyStore.Tests.E2E.csproj

No separate server needed. PlaywrightFixture starts a real Kestrel instance on a free port with an InMemory database and tears it down after the suite finishes.

4 - JS unit tests (Jest + jsdom)

One-time install (from the GuyStore project root, not the solution root):

cd "C:\Guy\Notes\Claud Projects\Guy\GuyStore"
npm install

Then run:

npm run test:js

Run all C# suites in one pass

cd "C:\Guy\Notes\Claud Projects\Guy"
dotnet test GuyStore.sln

This discovers and runs Unit + Integration + E2E together. JS tests must still be run separately with npm run test:js.

Run a single test by name

# Works for any project
dotnet test GuyStore.Tests.Unit\GuyStore.Tests.Unit.csproj --filter "PaginatedList_FirstPage_ReturnsCorrectSlice"
dotnet test GuyStore.Tests.Integration\GuyStore.Tests.Integration.csproj --filter "ShopIndex_ReturnsPaginatedProducts"
dotnet test GuyStore.Tests.E2E\GuyStore.Tests.E2E.csproj --filter "SwitchToForest_SetsCookie"

Key Technical Decisions (Stage 2)

PaginatedList EF/LINQ dual-path

PaginatedList<T>.CreateAsync detects whether the source is backed by EF Core's IAsyncQueryProvider at runtime. If yes, it uses EF async extensions (CountAsync, ToListAsync). If no (e.g., plain LINQ in unit tests), it falls back to synchronous equivalents. This avoids the "provider doesn't implement IAsyncQueryProvider" error in unit tests without needing a full EF InMemory context.

QuestPDF community license

QuestPDF.Settings.License = LicenseType.Community is set in the InvoiceService static constructor. This satisfies QuestPDF's requirement to declare the license before generating any documents. The community license is free for non-commercial use; set LicenseType.Professional for commercial deployment.

Support chat is in-memory only

SupportHub._sessions is a static dictionary - sessions survive for the lifetime of the server process but reset on restart. For production persistence, replace with a DbSet<ChatMessage> or a Redis-backed store.

The widget is a browser-side IIFE with no module system, so the test harness uses Jest with jsdom rather than the existing xUnit C# suites. Two new files:

File	Purpose
package.json (project root)	Jest 29 + jest-environment-jsdom dev dependencies; npm run test:js script
wwwroot/js/support-chat.test.js	12 Jest tests covering all widget behaviours

Test harness design

Three helpers set up every test:

// 1. Rebuild the six widget DOM elements the IIFE queries
function buildDOM() {
  document.body.innerHTML = `
    <button id="supportChatToggle"></button>
    <span   id="supportChatBadge"   class="d-none"></span>
    <div    id="supportChatPanel"   class="d-none"></div>
    <div    id="supportChatMessages"></div>
    <input  id="supportChatInput"   type="text" />
    <button id="supportChatSend"></button>
  `;
}

// 2. Mock the SignalR library on the global scope and return the connection mock
function buildConnectionMock() {
  const handlers = {};
  const connection = {
    on:     jest.fn((event, handler) => { handlers[event] = handler; }),
    invoke: jest.fn(() => Promise.resolve()),
    start:  jest.fn(() => Promise.resolve()),
    _handlers: handlers,
  };
  global.signalR = {
    HubConnectionBuilder: jest.fn(() => ({
      withUrl: jest.fn().mockReturnThis(),
      withAutomaticReconnect: jest.fn().mockReturnThis(),
      build: jest.fn(() => connection),
    })),
  };
  return connection;
}

// 3. Execute the IIFE in Jest's jsdom global scope
function runScript() { new Function(scriptSrc)(); }

afterEach(() => {
  document.body.innerHTML = '';
  delete global.signalR;
  jest.clearAllMocks();
});

new Function(scriptSrc)() is the key technique: it executes the IIFE as if it were running in the browser's global scope. Inside Jest+jsdom that global scope has a real document, so all getElementById calls resolve to jsdom elements. signalR is visible because it is set on global before the script runs. The connection._handlers map lets tests fire SignalR server callbacks directly without needing a real hub.

The 12 tests

Group	Test	What it verifies
Guard	Widget absent → clean exit	connection.start never called when #supportChatToggle is not in DOM
Toggle	Click opens panel and hides badge	Panel loses d-none; badge gains d-none
	Double-click closes panel	Panel regains d-none on second click
ReceiveMessage	Admin message → text-start	isAdmin=true renders with left-aligned class and correct text
	User message → text-end	isAdmin=false renders with right-aligned class
	Badge shown when panel hidden	Unread badge appears when new message arrives while panel is closed
	Badge not shown when panel open	No badge change when panel is already visible
History	Clears stale, replays all	Pre-existing DOM cleared; both history messages appear; stale content gone
Send	Full send flow	Calls invoke('UserSend', text), appends own message, clears input
	Blank input ignored	invoke not called; messages list stays empty
	Enter key triggers send	KeyboardEvent('keydown', { key: 'Enter' }) fires send
	Other keys do not	KeyboardEvent('keydown', { key: 'a' }) leaves invoke uncalled

Run with: npm run test:js (requires npm install once from the GuyStore project root).

Run commands were scattered or missing. Added a dedicated How to Run the Tests subsection in the Stage 2 Test Suite section. Summary:

Suite	Command	Notes
Unit (xUnit)	dotnet test GuyStore.Tests.Unit	Run from solution root (C:\Guy\Notes\Claud Projects\Guy)
Integration (xUnit + WebApplicationFactory)	dotnet test GuyStore.Tests.Integration	No server needed - app runs in-process with InMemory EF
E2E (Playwright + Chromium)	dotnet test GuyStore.Tests.E2E	First-time only: pwsh bin\Debug\net9.0\playwright.ps1 install from E2E project dir. No server needed - PlaywrightFixture starts Kestrel on a free port.
JS unit (Jest + jsdom)	npm run test:js	First-time only: npm install from GuyStore\ project root. Run from same directory.
All C# suites at once	dotnet test	Run from solution root - discovers Unit + Integration + E2E in one pass

• Persist support chat messages to database (currently in-memory only)
• Product reviews and ratings by registered users
• Discount codes / coupon system
• Product variants (size, colour) with separate stock per variant
• Bulk order import via CSV/Excel
• Sales report dashboard (revenue by date, top products, order trends)
• Two-factor authentication (TOTP / SMS)
• Shipping address book (save multiple addresses per user)
• Real-time inventory alerts (SignalR push when stock drops below threshold)
• External OAuth login (Google, Microsoft)

See CLAUDE.md in the project root and the memory files in C:\Users\gwang\.claude\projects\C--Users-gwang\memory\ for the full extension guide.