# Meeting-Driven Implementation Plan

## Purpose

Capture the June 4 review requests as an execution-ready plan for the VSR catalog and product experience.

This plan separates:

- direct application work that can be implemented now
- presentation/layout work that depends on existing data already in the system
- follow-up items that require upstream source-data confirmation or business clarification

## Working assumptions

1. The single bottom submit behavior applies only to New Releases.
2. All other catalog views keep per-item Add to Cart behavior.
3. "Units percent" is a real business request, but its authoritative source field is still unknown.
4. "Email me when available" and "Ships when available" should keep their current behavior until business intent is confirmed.
5. Existing `priceCode` mapping from `red_price_cd` is already correct and should not be reworked.

## Desired outcomes

1. The New Releases sidebar shows counts next to each street date.
2. The sidebar search field does not overflow on smaller widths.
3. Product quantity inputs do not default to `1` visually.
4. Stock and restock messaging sits in the purchase area instead of cluttering the metadata area.
5. New Releases supports entering multiple quantities and submitting them from one bottom action.
6. Existing product fields remain correctly surfaced: configuration full name, label, genre, street date, UPC, price code, carton factor, and returnable status.
7. Unresolved data or business-rule gaps are explicitly documented rather than guessed.

## Workstreams

### 1. Scope and request mapping

1. Read the meeting notes and extract every concrete requested change.
2. Group each request into one of three buckets:
   - implement now
   - implement now with validation risk
   - follow-up only
3. Confirm which requests are presentation-only versus schema/data changes.
4. Confirm whether the current system already supports each requested field.
5. Preserve the plan assumptions in the document until clarified.

### 2. Sidebar and catalog navigation improvements

Target files:

- [CatalogPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/CatalogPage.tsx)
- [vsr-theme.scss](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/styles/vsr-theme.scss)

Small material steps:

1. Inspect how genre, deal, and format counts are currently derived.
2. Reuse that same count pattern for New Releases street dates.
3. Aggregate product counts by `inStoreDt` for the current New Releases sidebar data set.
4. Render those counts next to each street-date sidebar item.
5. Keep the street-date list sorted in descending date order.
6. Verify the active sidebar state still follows the selected category.
7. Inspect the sidebar width and input sizing rules.
8. Add container-safe sizing so the search field cannot exceed the sidebar width.
9. Preserve the current search form behavior and query parameter handling.
10. Verify that search still works with and without a query string.

### 3. Product metadata cleanup

Target files:

- [ProductRow.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/ProductRow.tsx)
- [ProductDetailPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/ProductDetailPage.tsx)

Small material steps:

1. Review the current metadata order in the catalog row.
2. Review the current metadata order in the detail page.
3. Keep `configurationName` as the visible format label.
4. Do not replace the full format name with `configurationCode`.
5. Ensure `genreName` remains visible when present.
6. Ensure `labelName` remains visible when present.
7. Ensure `inStoreDt` is still surfaced as street date.
8. Ensure `alternateCatalogId` remains visible as Catalog #.
9. Ensure `upcCd` remains visible.
10. Ensure `priceCode` remains visible when present.
11. Ensure `bulkFactor` remains visible when present.
12. Ensure `returnsAllowed` remains visible and clearly labeled.
13. Keep the row and detail experiences visually consistent where practical.

### 4. Quantity behavior updates

Target files:

- [ProductRow.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/ProductRow.tsx)
- [ProductDetailPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/ProductDetailPage.tsx)

Small material steps:

1. Identify where quantity input state is initialized in the row component.
2. Identify where quantity input state is initialized in the detail component.
3. Change the default visible state from `1` to blank.
4. Preserve numeric input semantics.
5. Allow the user to temporarily leave the field blank.
6. Convert blank or invalid values to `1` only when the add-to-cart action runs.
7. Keep mutation input valid and integer-based.
8. Verify that direct row add-to-cart still works in non-New-Releases views.
9. Verify that product detail add-to-cart still works.

### 5. Stock and restock message placement

Target files:

- [ProductRow.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/ProductRow.tsx)
- [ProductDetailPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/ProductDetailPage.tsx)
- [StockBadge.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/StockBadge.tsx)
- [vsr-theme.scss](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/styles/vsr-theme.scss)

Small material steps:

1. Identify where the stock badge is rendered in the catalog row.
2. Identify where the stock badge is rendered in the detail page.
3. Identify where the restock button is rendered in both places.
4. Move the stock badge into the purchase/order card area.
5. Move the restock action into the purchase/order card area.
6. Keep the current stock-status wording centralized in `StockBadge.tsx`.
7. Preserve the out-of-stock note behavior for items that are currently not available.
8. Adjust spacing so the stock block reads as part of the purchase stack.
9. Verify that future-dated New Releases still suppress stock messaging through the existing `showStock` gate.

### 6. New Releases bottom-submit flow

Target files:

- [CatalogPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/CatalogPage.tsx)
- [ProductRow.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/ProductRow.tsx)
- [cartOrderMutations.ts](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/apollo/mutations/cartOrderMutations.ts)

Small material steps:

1. Confirm the existing row component owns its own quantity state.
2. Add an alternate mode so the row can accept externally controlled quantity state.
3. Keep the row’s current per-item add-to-cart mode for other catalog views.
4. Add page-level quantity state in `CatalogPage.tsx` for New Releases only.
5. Hide the per-row add button in New Releases mode.
6. Preserve the per-row quantity input in New Releases mode.
7. Collect all rows with a quantity greater than zero.
8. Add a single bottom call-to-action for New Releases.
9. Reuse the existing `ADD_TO_CART` mutation instead of creating a new GraphQL contract immediately.
10. Submit selected rows sequentially through the existing mutation.
11. Redirect to the cart after the page-level submission completes.
12. Keep the rest of the catalog flows unchanged.
13. Treat a true batch server mutation as a second-step optimization only if this path proves inadequate.

### 7. Preserve correct data-field behavior

Target files:

- [productResolvers.ts](/Users/lvona/src/virtual-sales-rep/packages/vsr-graphql-server/src/resolvers/productResolvers.ts)
- [productQueries.ts](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/apollo/queries/productQueries.ts)
- [product.graphql](/Users/lvona/src/virtual-sales-rep/packages/vsr-graphql-server/src/schema/product.graphql)

Small material steps:

1. Verify that `priceCode` still maps from `red_price_cd`.
2. Verify that `configurationCode` remains distinct from `priceCode`.
3. Verify that the frontend continues requesting `configurationName`.
4. Verify that `labelName` stays in the product query.
5. Verify that `genreName` stays in the product query.
6. Verify that `returnsAllowed` stays in the product query.
7. Avoid adding speculative fields to the schema.
8. Only widen schema work if a real, confirmed source field is identified.

### 8. Follow-up documentation for blocked items

Target files:

- [FOLLOW_UP_TICKETS.md](/Users/lvona/src/virtual-sales-rep/docs/FOLLOW_UP_TICKETS.md)
- [DECISION_LOG.md](/Users/lvona/src/virtual-sales-rep/research/DECISION_LOG.md)

Small material steps:

1. Capture the unresolved "units percent" requirement as a source-data follow-up.
2. Capture the pending business rule for restock warning visibility.
3. Capture the genre metadata accuracy issue if it remains upstream.
4. Include evidence for each note.
5. Include next-step recommendations for each note.
6. Only add an ADR if a durable product or architecture decision is made, not for a simple styling change.

## Relevant implementation files

- [CatalogPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/CatalogPage.tsx)
- [ProductRow.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/ProductRow.tsx)
- [ProductDetailPage.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/pages/ProductDetailPage.tsx)
- [StockBadge.tsx](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/components/StockBadge.tsx)
- [vsr-theme.scss](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/styles/vsr-theme.scss)
- [productQueries.ts](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/apollo/queries/productQueries.ts)
- [cartOrderMutations.ts](/Users/lvona/src/virtual-sales-rep/apps/vsr/src/apollo/mutations/cartOrderMutations.ts)
- [productResolvers.ts](/Users/lvona/src/virtual-sales-rep/packages/vsr-graphql-server/src/resolvers/productResolvers.ts)
- [product.graphql](/Users/lvona/src/virtual-sales-rep/packages/vsr-graphql-server/src/schema/product.graphql)
- [mockData.ts](/Users/lvona/src/virtual-sales-rep/tools/vsr-graphql-stub/src/mockData.ts)
- [FOLLOW_UP_TICKETS.md](/Users/lvona/src/virtual-sales-rep/docs/FOLLOW_UP_TICKETS.md)
- [CHANGELOG.md](/Users/lvona/src/virtual-sales-rep/docs/CHANGELOG.md)

## Validation plan

1. Validate the New Releases sidebar counts visually.
2. Validate the sidebar search field on narrower widths.
3. Validate blank quantity defaults in catalog rows.
4. Validate blank quantity defaults on product detail.
5. Validate that blank quantity still submits as `1` when appropriate.
6. Validate that non-New-Releases views still support per-item add-to-cart.
7. Validate the New Releases bottom-submit flow with multiple products.
8. Validate future-dated New Releases suppress stock messaging.
9. Validate that stock/restock messaging now appears in the purchase area.
10. Validate that `priceCode` remains distinct from configuration code.
11. Run focused diagnostics or tests for touched files.
12. Record unresolved business or data questions in follow-up notes instead of inventing behavior.

## Explicit blockers

1. "Units percent" cannot be implemented safely until the source field and business meaning are confirmed.
2. Final visibility rules for the restock warning require business confirmation.
3. Genre accuracy may require an upstream data correction rather than further frontend changes.

## Optional second-step work

1. Add narrow component tests around row quantity behavior and New Releases batch add.
2. Add a dedicated batch cart mutation only if the sequential client-side approach proves too brittle.
3. Refine metadata presentation further if the old site needs to be matched more literally.