[codex] Add eShopOnWeb feature comparison plans

docs/plans/0000-feature-comparison.md

@@ -0,0 +1,62 @@
+# FShopOnWeb vs eShopOnWeb Feature Comparison
+
+Date: 2026-04-13
+
+This comparison is based on the current `FShopOnWeb` repository and the current `main` branch of `NimblePros/eShopOnWeb`.
+
+## Status Legend
+
+- `Implemented`: present and functionally established in the repository.
+- `Partial`: some visible pieces exist, but the full workflow or supporting infrastructure is incomplete.
+- `Missing`: no meaningful implementation found.
+
+## Feature Matrix
+
+| Feature | eShopOnWeb (C#) | FShopOnWeb (F#) | Notes | Plan |
+| --- | --- | --- | --- | --- |
+| Catalog browsing, brand/type filtering, pagination | Implemented | Partial | F# home page renders catalog items and filter UI, but filtering and paging are not wired to query handling. | [0001-storefront-parity.md](./0001-storefront-parity.md) |
+| Basket workflow | Implemented | Partial | F# supports viewing, add, and remove, but not quantity editing, cookie/user basket ownership, or checkout integration. | [0001-storefront-parity.md](./0001-storefront-parity.md) |
+| Authentication and account flows | Implemented | Partial | F# has a rendered login page, but no working sign-in, logout, registration, or user store. | [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md) |
+| GitHub single sign-on | Implemented | Missing | Present in C# via OAuth configuration and identity pages. | [0003-github-sso.md](./0003-github-sso.md) |
+| Checkout and order history | Implemented | Missing | C# has checkout, order creation, My Orders, and order detail flows; none found in F#. | [0004-checkout-and-orders.md](./0004-checkout-and-orders.md) |
+| Admin catalog management | Implemented | Missing | C# has admin catalog pages plus supporting API; F# has no admin area. | [0005-admin-catalog-management.md](./0005-admin-catalog-management.md) |
+| User management | Implemented | Missing | C# admin supports user listing, create/update/delete, and role assignment safeguards. | [0006-user-and-role-administration.md](./0006-user-and-role-administration.md) |
+| Role management and role membership | Implemented | Missing | C# exposes role CRUD and membership management; F# has none. | [0006-user-and-role-administration.md](./0006-user-and-role-administration.md) |
+| Public API and token auth | Implemented | Missing | C# ships a dedicated `PublicApi` app with JWT auth and catalog/admin endpoints. | [0007-public-api.md](./0007-public-api.md) |
+| Database architecture, migrations, identity persistence | Implemented | Partial | F# uses a single SQLite context recreated on startup; no migrations, identity schema, or production-style persistence story. | [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md) |
+| Health checks and operational plumbing | Implemented | Missing | C# includes health checks, troubleshooting middleware, and richer hosting configuration. | [0009-operability-and-observability.md](./0009-operability-and-observability.md) |
+| Automated testing breadth | Implemented | Partial | F# has limited basket tests; C# has unit, integration, functional, and API integration suites. | [0010-test-strategy.md](./0010-test-strategy.md) |
+
+## Evidence Summary
+
+### FShopOnWeb
+
+- Storefront entry points: `src/Microsoft.eShopWeb.Web/Program.fs`, `src/Microsoft.eShopWeb.Web/Home/Home.Page.fs`
+- Basket support: `src/Microsoft.eShopWeb.Web/Basket/Basket.Page.fs`, `src/Microsoft.eShopWeb.Web/Basket/Basket.Domain.fs`
+- Account UI only: `src/Microsoft.eShopWeb.Web/Account/Login/Login.Page.fs`
+- Current persistence shape: `src/Microsoft.eShopWeb.Web/Domain.fs`, `src/Microsoft.eShopWeb.Web/Persistence.fs`
+- Current test surface: `tests/Basket/RemoveFromBasket.fs`
+
+### eShopOnWeb
+
+- Storefront and checkout: `src/Web/Pages/Index.cshtml.cs`, `src/Web/Pages/Basket/Checkout.cshtml.cs`
+- Orders: `src/Web/Controllers/OrderController.cs`, `src/ApplicationCore/Services/OrderService.cs`
+- Identity and GitHub auth: `src/Web/Program.cs`, `src/Web/Areas/Identity/Pages/Account/*`, `docs/features/sso-with-github.md`
+- Admin portal: `src/BlazorAdmin/Pages/**/*`
+- Public API: `src/PublicApi/**/*`
+- User and role management: `docs/features/user-management.md`, `docs/features/role-management.md`, `docs/features/role-membership.md`
+- Health checks: `src/Web/HealthChecks/*`
+- Test breadth: `tests/UnitTests`, `tests/IntegrationTests`, `tests/FunctionalTests`, `tests/PublicApiIntegrationTests`
+
+## Recommended Delivery Order
+
+1. [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+2. [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+3. [0001-storefront-parity.md](./0001-storefront-parity.md)
+4. [0004-checkout-and-orders.md](./0004-checkout-and-orders.md)
+5. [0003-github-sso.md](./0003-github-sso.md)
+6. [0006-user-and-role-administration.md](./0006-user-and-role-administration.md)
+7. [0007-public-api.md](./0007-public-api.md)
+8. [0005-admin-catalog-management.md](./0005-admin-catalog-management.md)
+9. [0009-operability-and-observability.md](./0009-operability-and-observability.md)
+10. [0010-test-strategy.md](./0010-test-strategy.md)

docs/plans/0001-storefront-parity.md

@@ -0,0 +1,49 @@
+# 0001 Storefront Parity
+
+## Goal
+
+Close the gap between the current F# storefront and the C# storefront for catalog browsing and basket management.
+
+## Current Gap
+
+- Catalog filters render in F# but do not drive query-based filtering.
+- Pagination UI renders, but paging is not implemented.
+- Basket supports add/remove only.
+- Basket ownership is effectively "first basket in the database", not tied to a cookie or authenticated buyer.
+- Basket quantity updates and basket summary parity are incomplete.
+
+## Scope
+
+- Add query-driven catalog filtering by brand and type.
+- Implement real pagination with page index and page size.
+- Introduce basket ownership via cookie for anonymous users.
+- Support quantity updates in the basket page.
+- Add basket summary calculations consistent with the current UI.
+- Preserve current Falco-based page structure.
+
+## Dependencies
+
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md) for a durable persistence model.
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md) if baskets should merge or associate with signed-in users.
+
+## Implementation Plan
+
+1. Add explicit query models for home page filtering and paging.
+2. Move catalog queries into a dedicated service module instead of assembling page state inline.
+3. Add persisted basket identity using a long-lived cookie.
+4. Refactor basket mutations to operate on the current basket, not the first basket found.
+5. Extend the basket page with quantity update actions and recalculated totals.
+6. Add tests for filtering, paging, and basket update behavior.
+
+## Acceptance Criteria
+
+- Brand and type selections affect the catalog result set.
+- Pagination changes the catalog result set and page controls.
+- Anonymous users retain a basket across requests.
+- Basket quantities can be updated without breaking add/remove.
+- Tests cover the new storefront workflows.
+
+## Risks
+
+- Current `emptyBasket` and first-record lookup behavior will cause correctness bugs if not replaced early.
+- UI parity may expose persistence shortcomings before migrations are added.

docs/plans/0002-authentication-and-account-flows.md

@@ -0,0 +1,45 @@
+# 0002 Authentication and Account Flows
+
+## Goal
+
+Replace the static F# login page with working authentication and baseline account flows comparable to the C# application.
+
+## Current Gap
+
+- The F# repository renders a login form only.
+- No sign-in handler, user persistence, registration, logout, password management, or authorization model is present.
+- No protected pages depend on a real user identity yet.
+
+## Scope
+
+- Introduce ASP.NET Core Identity or an equivalent supported identity stack for F#.
+- Implement working login and logout.
+- Implement registration and basic account confirmation flow.
+- Add authorization guards for authenticated-only routes such as checkout and order history.
+- Seed the demo users expected by eShopOnWeb.
+
+## Dependencies
+
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+
+## Implementation Plan
+
+1. Choose the identity integration approach that fits Falco hosting without fighting middleware expectations.
+2. Add identity entities, stores, cookie auth, and service registration.
+3. Replace the static login page with bound GET/POST handlers and validation.
+4. Add logout and registration routes with matching UI.
+5. Seed `demouser@microsoft.com`, `productmgr@microsoft.com`, and `admin@microsoft.com`.
+6. Protect future authenticated features behind route-level or handler-level authorization.
+
+## Acceptance Criteria
+
+- Login succeeds for seeded demo users.
+- Logout clears the authenticated session.
+- Registration creates a new user record.
+- Protected pages redirect unauthenticated users to login.
+- Identity data persists across restarts.
+
+## Risks
+
+- Falco route handling and ASP.NET Identity UI conventions may not align directly.
+- Taking a shortcut with ad hoc auth will make later role and admin work harder.

docs/plans/0003-github-sso.md

@@ -0,0 +1,39 @@
+# 0003 GitHub SSO
+
+## Goal
+
+Add GitHub OAuth sign-in to FShopOnWeb after baseline local identity is established.
+
+## Current Gap
+
+- eShopOnWeb supports GitHub OAuth.
+- FShopOnWeb has no external login providers.
+
+## Scope
+
+- Add GitHub OAuth configuration and callback handling.
+- Surface "Sign in with GitHub" in the account UI.
+- Map GitHub claims into the local user profile and local sign-in session.
+- Document required local secrets and callback URLs.
+
+## Dependencies
+
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+
+## Implementation Plan
+
+1. Wire GitHub OAuth into the host authentication pipeline.
+2. Add an external login button and callback endpoint.
+3. Create or link local users for external identities.
+4. Normalize email and claim handling so later role assignment remains deterministic.
+5. Add configuration and setup documentation for local development.
+
+## Acceptance Criteria
+
+- A user can sign in with GitHub from the login page.
+- Returning users reuse the same local account.
+- Missing configuration disables the feature cleanly instead of breaking login.
+
+## Risks
+
+- External identity linking rules can create duplicate users if email and provider keys are not handled carefully.

docs/plans/0004-checkout-and-orders.md

@@ -0,0 +1,45 @@
+# 0004 Checkout and Orders
+
+## Goal
+
+Implement the purchase flow that turns a basket into an order and lets users review their order history.
+
+## Current Gap
+
+- FShopOnWeb has no checkout page.
+- No order aggregate, address model, order service, or order history pages exist.
+- Basket items are not connected to an authenticated buyer journey.
+
+## Scope
+
+- Add order domain types and persistence.
+- Add checkout page and submit workflow.
+- Create order from basket contents.
+- Clear or archive the basket after successful checkout.
+- Add "My Orders" and order detail pages for authenticated users.
+
+## Dependencies
+
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+- [0001-storefront-parity.md](./0001-storefront-parity.md)
+
+## Implementation Plan
+
+1. Introduce order aggregate entities and tables.
+2. Add checkout handlers and UI for shipping address capture.
+3. Implement an order service that validates basket state and creates order items from catalog snapshots.
+4. Delete or reset the basket after a successful checkout.
+5. Build authenticated order history and order details pages.
+6. Add tests for empty-basket checkout, successful checkout, and order retrieval authorization.
+
+## Acceptance Criteria
+
+- An authenticated user can check out a non-empty basket.
+- Checkout creates a persisted order with item snapshots and totals.
+- The basket is no longer active after checkout.
+- Users can view only their own orders.
+
+## Risks
+
+- Without buyer identity and stable basket ownership, checkout will produce incorrect associations.

docs/plans/0005-admin-catalog-management.md

@@ -0,0 +1,42 @@
+# 0005 Admin Catalog Management
+
+## Goal
+
+Add an administrative surface for catalog item creation, editing, and deletion.
+
+## Current Gap
+
+- eShopOnWeb exposes admin catalog management through a dedicated admin UI and supporting API.
+- FShopOnWeb has no admin routes, authorization policy, or product management workflow.
+
+## Scope
+
+- Add an admin area or equivalent route group in the F# app.
+- Support list, create, edit, and delete for catalog items.
+- Support brand/type lookup and image URI editing.
+- Restrict access to product manager or administrator roles.
+
+## Dependencies
+
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+- [0006-user-and-role-administration.md](./0006-user-and-role-administration.md)
+- [0007-public-api.md](./0007-public-api.md) if the admin UI is split from the web app like the C# version.
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+
+## Implementation Plan
+
+1. Decide whether admin lives in the same F# web app or as a separate client.
+2. Add role-protected catalog management endpoints.
+3. Add server-side validation for catalog item fields.
+4. Add brand/type management support needed by catalog item editing.
+5. Add tests for authorized and unauthorized product management actions.
+
+## Acceptance Criteria
+
+- Product managers can create, edit, and delete catalog items.
+- Unauthorized users cannot access admin operations.
+- Catalog changes appear correctly in the storefront.
+
+## Risks
+
+- Building admin UI before stable auth, roles, and persistence will create rework.

docs/plans/0006-user-and-role-administration.md

@@ -0,0 +1,44 @@
+# 0006 User and Role Administration
+
+## Goal
+
+Add administrator features for users, roles, and role membership.
+
+## Current Gap
+
+- eShopOnWeb provides admin workflows and APIs for user CRUD, role CRUD, membership listing, and membership updates.
+- FShopOnWeb has no role model, no admin screens, and no management endpoints.
+
+## Scope
+
+- Add role definitions and seeded assignments.
+- Add admin workflows for listing users and roles.
+- Support creating, editing, and deleting roles.
+- Support creating, editing, and deleting users within the constraints used by eShopOnWeb.
+- Support adding and removing role memberships.
+
+## Dependencies
+
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+- [0007-public-api.md](./0007-public-api.md) if management is API-backed.
+
+## Implementation Plan
+
+1. Introduce role seeding for `Product Managers` and `Administrators`.
+2. Add authorization policies for administrator-only management actions.
+3. Add role management handlers and validation, including safe delete checks for assigned roles.
+4. Add user management handlers, including protected demo-account behavior if parity is desired.
+5. Add membership management workflows from both the user and role perspectives.
+6. Add tests for permission boundaries and destructive-action safeguards.
+
+## Acceptance Criteria
+
+- Administrators can manage users and roles.
+- Product managers and shoppers cannot access these tools.
+- Assigned roles cannot be deleted without removal of memberships first.
+- Demo bootstrap users and roles are seeded consistently.
+
+## Risks
+
+- Mixing role management rules into ad hoc logic instead of explicit policies will become hard to maintain.

docs/plans/0007-public-api.md

@@ -0,0 +1,43 @@
+# 0007 Public API
+
+## Goal
+
+Introduce an API surface comparable to eShopOnWeb's `PublicApi` application.
+
+## Current Gap
+
+- FShopOnWeb is currently a server-rendered web app only.
+- No JSON API, token auth, or external admin/client integration surface exists.
+
+## Scope
+
+- Decide whether the API should live in the existing F# host or a separate F# project.
+- Expose catalog item, brand, and type endpoints.
+- Expose authentication/token issuance if external clients are required.
+- Expose admin-oriented endpoints for catalog, users, roles, and memberships as needed.
+- Add OpenAPI or equivalent discoverability.
+
+## Dependencies
+
+- [0008-database-migrations-and-seeding.md](./0008-database-migrations-and-seeding.md)
+- [0002-authentication-and-account-flows.md](./0002-authentication-and-account-flows.md)
+- [0006-user-and-role-administration.md](./0006-user-and-role-administration.md) for admin API parity
+
+## Implementation Plan
+
+1. Choose API architecture: separate service for parity, or route group within the current app for simplicity.
+2. Define DTOs and mapping for catalog resources.
+3. Add authentication strategy for API callers.
+4. Add admin endpoints only after role and user rules are explicit.
+5. Add API integration tests around auth, validation, and authorization.
+
+## Acceptance Criteria
+
+- Catalog resources are queryable over JSON.
+- Protected API routes reject unauthorized callers.
+- Admin routes enforce role requirements.
+- API behavior is covered by integration tests.
+
+## Risks
+
+- Shipping an API before domain boundaries are cleaned up will leak page-model assumptions into the contract.