ianshaloom
8e4309892c
- Extend addVariant with dimension fields and SKU uniqueness check; expand updateVariant to full field set; update getByIdForAdmin to return all variants (active + inactive) - Add generateSku utility to @repo/utils; auto-generates SKU from brand, product name, attributes, and weight with manual-override support - Move ProductSearchSection to components/shared and fix nav link /variants → /variant - Variants page: product search, loading skeleton, variants table, toolbar with create button - VariantsTable: 8 columns, activate/deactivate toggle, delete with AlertDialog confirmation - VariantPreviewDialog: read-only full variant details with sections for pricing, inventory, shipping, attributes - VariantForm: zod schema with superRefine for dimension and on-sale validation, auto-SKU generation - CreateVariantDialog and EditVariantDialog wiring dollarsToCents on submit - Install sonner and add Toaster to root layout; install ShadCN Switch component Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
14 KiB
14 KiB
Admin Dashboard — Feature Checklist
Date: 2026-03-04 Audience: Senior software engineers, project stakeholders
How to Read This Document
Features are grouped into MVP (required for launch) and Post-MVP (phased rollout). Within each group, features are ordered by implementation priority.
Legend:
| Symbol | Meaning |
|---|---|
[ ] |
Not started |
[~] |
Backend exists, admin UI needed |
[x] |
Complete |
| BE | Backend work required (new Convex functions) |
| UI | Admin frontend work only |
| 3P | Third-party integration required |
MVP
1. Authentication & Authorization
| # | Feature | Status | Notes |
|---|---|---|---|
| 1.1 | Clerk sign-in page (branded, in-app) | [x] UI |
Replace hosted sign-in redirect |
| 1.2 | Admin user sync (Convex record on sign-in) | [x] UI |
Wire existing useStoreUserEffect hook |
| 1.3 | Role-based auth gate (block non-admin users) | [x] UI |
AdminAuthGate component, query users.current |
| 1.4 | Access denied page for customers | [x] UI |
Sign-out button + storefront link |
| 1.5 | Admin layout shell (header with UserButton) |
[x] UI |
Persistent header with session management |
| 1.6 | Route group structure ((auth) vs (dashboard)) |
[x] UI |
Separate sign-in from protected routes |
Full implementation plan: 05-admin-auth-implementation-plan.md
2. Navigation & Layout
| # | Feature | Status | Notes |
|---|---|---|---|
| 2.1 | Sidebar navigation | [x] UI |
Collapsible; links to all admin sections |
| 2.2 | Breadcrumbs | [x] UI |
Context-aware breadcrumb trail |
| 2.3 | Mobile-responsive admin shell | [x] UI |
Hamburger menu on mobile, full sidebar on lg: |
| 2.4 | Active route highlighting | [x] UI |
Visual indicator for current section |
3. Product Management (Inventory)
| # | Feature | Status | Notes |
|---|---|---|---|
| 3.1 | Product list page | [x] UI |
Backend: products.list (paginated, filterable by status/category). Build table with search, filters, pagination. |
| 3.2 | Create product form | [x] UI |
Backend: products.create. Form: name, slug, description, status, category, tags. |
| 3.3 | Edit product form | [x] UI |
Backend: products.update. Pre-populated form with all fields. |
| 3.4 | Archive/restore product | [x] UI |
Backend: products.archive. Confirmation dialog. Restore via edit status field. |
| 3.5 | Product image upload | [x] BE+UI |
Cloudinary server-side upload via Next.js API route (/api/upload-image). Background removal (Image Processing API) with dual upload: processed or original. Structured public_id + asset_folder per product. |
| 3.6 | Image gallery management | [x] UI |
Drag-and-drop reorder (@dnd-kit) with reorderImages mutation. Per-image delete with AlertDialog. "Add more" tile. Search-driven product selection with auto-clear. |
| 3.7 | Variant management | [x] UI |
Variants page with table, create/edit/preview dialogs, activate/deactivate, delete with AlertDialog. |
| 3.8 | Stock quantity editing | [x] UI |
stockQuantity editable in full variant edit dialog. |
| 3.9 | Price and compare-at-price editing | [x] UI |
price and compareAtPrice (behind On Sale toggle) editable in variant form. |
| 3.10 | Product SEO fields (title, description) | [x] UI |
seoTitle, seoDescription, canonicalSlug in collapsible Advanced/SEO section. |
| 3.11 | Product search within admin | [x] UI |
Debounced search bar on list page; switches between products.list and products.search. |
| 3.12 | Bulk status change (draft → active, etc.) | [ ] BE+UI |
New mutation: products.bulkUpdateStatus. Multi-select in table. |
4. Category Management
| # | Feature | Status | Notes |
|---|---|---|---|
| 4.1 | Category list / tree view | [~] UI |
Backend: categories.list (supports parentId). Show hierarchical tree. |
| 4.2 | Create category | [~] UI |
Backend: categories.create. Form: name, slug, parent, top-category slug, SEO. |
| 4.3 | Edit category | [~] UI |
Backend: categories.update. |
| 4.4 | Category image upload | [ ] BE+UI |
Schema has imageUrl. Need file upload flow. |
5. Order Processing
| # | Feature | Status | Notes |
|---|---|---|---|
| 5.1 | Order list page | [~] UI |
Backend: orders.listAll (paginated, filterable by status/paymentStatus). |
| 5.2 | Order detail page | [~] UI |
Backend: orders.getById (returns items, addresses, payment info). |
| 5.3 | Update order status | [~] UI |
Backend: orders.updateStatus. Dropdown or status stepper. |
| 5.4 | Cancel order (admin-initiated) | [ ] BE+UI |
New mutation: orders.adminCancel — cancel regardless of customer rules, update Stripe if paid, restore stock. |
| 5.5 | Create shipping label (Shippo) | [ ] BE+UI+3P |
New action: shippo.createLabel — calls Shippo Transactions API. Store trackingNumber, trackingUrl, labelUrl on order. |
| 5.6 | Print shipping label | [ ] UI+3P |
Fetch label PDF URL from Shippo, open in new tab / trigger print dialog. |
| 5.7 | Track shipment status | [ ] BE+3P |
New: Shippo tracking webhook → update order status and trackingUrl. Or poll Shippo Tracking Status API. |
| 5.8 | Refund order (full) | [ ] BE+UI+3P |
New action: stripe.refundPayment — calls Stripe Refunds API. Update paymentStatus to "refunded", status to "refunded". |
| 5.9 | Partial refund | [ ] BE+UI+3P |
Same Stripe Refunds API with amount parameter. |
| 5.10 | Return processing | [ ] BE+UI |
New: returns table or status sub-flow. Accept return request → inspect → refund or reject. |
| 5.11 | Send order update email | [ ] BE+3P |
New: email service integration (Resend or SendGrid). Triggered on status changes: confirmed, shipped (with tracking), delivered, cancelled, refunded. |
| 5.12 | Send order update SMS | [ ] BE+3P |
New: SMS integration (Twilio or similar). Triggered on key status changes: shipped, delivered. |
| 5.13 | Order notes (internal) | [~] UI |
Schema has notes field. Admin can add/edit internal notes. |
| 5.14 | Order search / filters | [ ] BE+UI |
Search by order number, customer email, date range. May need new indexes. |
| 5.15 | Batch label creation | [ ] BE+UI+3P |
Select multiple orders → create labels via Shippo Batches API. |
6. Customer Management (MVP-lite)
| # | Feature | Status | Notes |
|---|---|---|---|
| 6.1 | Customer list page | [~] UI |
Backend: users.listCustomers (paginated). |
| 6.2 | Customer detail page | [ ] BE+UI |
New query: users.getCustomerDetail — user + orders + addresses. |
| 6.3 | View customer orders | [ ] UI |
Link from customer detail to filtered order list. |
Post-MVP
7. Dashboard & Analytics
| # | Feature | Status | Notes |
|---|---|---|---|
| 7.1 | Dashboard home — key metrics | [ ] BE+UI |
New queries: total revenue, order count, new customers (time-windowed). DashboardStats type already exists in @repo/types. |
| 7.2 | Revenue chart (daily/weekly/monthly) | [ ] BE+UI |
New query: aggregated revenue by period. Chart library (Recharts or similar). |
| 7.3 | Orders chart | [ ] BE+UI |
Order volume over time. |
| 7.4 | Top-selling products | [ ] BE+UI |
New query: aggregate orderItems by product, sort by quantity. |
| 7.5 | Low stock alerts | [ ] BE+UI |
New query: variants where stockQuantity < threshold. Dashboard widget + notification badge. |
| 7.6 | Recent orders feed | [~] UI |
Backend: orders.listAll with limit. Real-time feed on dashboard. |
| 7.7 | Conversion funnel | [ ] BE+UI |
Track: visits → cart adds → checkouts → completed orders. Requires analytics events. |
8. Review Management
| # | Feature | Status | Notes |
|---|---|---|---|
| 8.1 | Review list page (all reviews) | [~] UI |
Backend: reviews.listForAdmin (filterable by approval status, product). |
| 8.2 | Approve review | [~] UI |
Backend: reviews.approve. |
| 8.3 | Delete review | [~] UI |
Backend: reviews.deleteReview. |
| 8.4 | Review detail / preview | [ ] UI |
Show full review content, images, linked product. |
| 8.5 | Bulk approve/delete | [ ] BE+UI |
New mutations for batch operations. |
9. Customer Communication
| # | Feature | Status | Notes |
|---|---|---|---|
| 9.1 | Contact form messages inbox | [ ] BE+UI |
New messages table. Storefront contact form → Convex. Admin reads/replies. |
| 9.2 | Reply to customer message | [ ] BE+UI+3P |
Send reply via email (Resend/SendGrid). Store thread in Convex. |
| 9.3 | Message status (unread/read/resolved) | [ ] BE+UI |
Status field on messages table. |
| 9.4 | Email templates | [ ] BE+3P |
Transactional email templates for order updates, review responses, etc. |
10. Newsletter & Marketing
| # | Feature | Status | Notes |
|---|---|---|---|
| 10.1 | Newsletter subscriber list | [ ] BE+UI |
New subscribers table. Storefront signup → Convex. Admin views list. |
| 10.2 | Export subscribers (CSV) | [ ] UI |
Client-side CSV generation from subscriber list. |
| 10.3 | Compose & send newsletter | [ ] BE+3P |
Integration with email provider (Resend/Mailchimp). Template editor. |
| 10.4 | Unsubscribe handling | [ ] BE |
Unsubscribe link in emails → Convex mutation. |
11. Promotions & Discounts
| # | Feature | Status | Notes |
|---|---|---|---|
| 11.1 | Coupon/discount code management | [ ] BE+UI+3P |
New coupons table or Stripe Coupons API (already available via MCP). CRUD UI for codes, percentage/fixed amount, expiry, usage limits. |
| 11.2 | Sale tag management | [~] UI |
Products already have tags[]. Admin can add/remove "sale" tag. Backend: products.update. |
| 11.3 | Compare-at-price (was/now pricing) | [~] UI |
Schema has compareAtPrice on variants. Editable in variant management. |
12. Admin User Management
| # | Feature | Status | Notes |
|---|---|---|---|
| 12.1 | Admin/staff list | [ ] BE+UI |
New query: users.listAdmins. |
| 12.2 | Promote user to admin | [ ] BE+UI |
New mutation: users.setRole (super_admin only). |
| 12.3 | Demote admin to customer | [ ] BE+UI |
Same users.setRole mutation. |
| 12.4 | Activity / audit log | [ ] BE+UI |
New auditLogs table. Log admin actions with userId, action, target, timestamp. |
13. Settings & Configuration
| # | Feature | Status | Notes |
|---|---|---|---|
| 13.1 | Store settings (name, logo, contact info) | [ ] BE+UI |
New storeSettings table (singleton). |
| 13.2 | Shipping configuration | [ ] BE+UI |
Default parcel dimensions, weight limits, carrier preferences. Currently hardcoded in model/shippo.ts. |
| 13.3 | Tax configuration | [ ] BE+UI |
Tax rates by region. Currently tax is passed manually on order creation. |
| 13.4 | Email notification preferences | [ ] BE+UI |
Which status changes trigger emails/SMS. |
| 13.5 | Payment settings (Stripe config) | [ ] UI |
Display Stripe connection status, webhook health. |
14. Data & Export
| # | Feature | Status | Notes |
|---|---|---|---|
| 14.1 | Export orders (CSV) | [ ] UI |
Client-side CSV from orders.listAll. |
| 14.2 | Export products (CSV) | [ ] UI |
Client-side CSV from products.listAll. |
| 14.3 | Export customers (CSV) | [ ] UI |
Client-side CSV from users.listCustomers. |
| 14.4 | Import products (CSV) | [ ] BE+UI |
Parse CSV → batch products.create calls. |
MVP Scope Summary
| Section | Features | New Backend Work | Third-Party |
|---|---|---|---|
| 1. Auth & Authorization | 6 | None | — |
| 2. Navigation & Layout | 4 | None | — |
| 3. Product Management | 12 | File upload, bulk status | — |
| 4. Category Management | 4 | File upload | — |
| 5. Order Processing | 15 | Cancel, refund, label, tracking, return, email, SMS, search, batch | Shippo, Stripe, Resend/SendGrid, Twilio |
| 6. Customer Management | 3 | Customer detail query | — |
| Total MVP | 44 |
Third-Party Integration Summary
| Service | Purpose | MVP? | Existing? |
|---|---|---|---|
| Clerk | Authentication | Yes | Yes — sign-in, JWT, webhooks |
| Convex | Backend, real-time DB | Yes | Yes — full schema + functions |
| Stripe | Payments, refunds | Yes | Partial — checkout exists, refunds needed |
| Shippo | Shipping labels, tracking | Yes | Partial — rates/validation exist, labels/tracking needed |
| Resend or SendGrid | Transactional email | Yes | No — not integrated |
| Twilio or SNS | SMS notifications | Yes | No — not integrated |
| Recharts or Chart.js | Dashboard charts | Post-MVP | No |
Recommended Implementation Order (MVP)
Phase 1 ─ Auth & Layout (1-2 days)
├─ 1.1–1.6 Authentication & authorization
└─ 2.1–2.4 Navigation & layout shell
Phase 2 ─ Product Management (3-4 days)
├─ 3.1–3.4 Product list, create, edit, archive
├─ 3.5–3.6 Image upload & gallery
├─ 3.7–3.9 Variant CRUD, stock, pricing
├─ 3.10–3.11 SEO fields, search
└─ 4.1–4.4 Category management
Phase 3 ─ Order Processing — Core (2-3 days)
├─ 5.1–5.3 Order list, detail, status update
├─ 5.4 Admin cancel
├─ 5.13–5.14 Order notes, search
Phase 4 ─ Shipping & Labels (2-3 days)
├─ 5.5–5.6 Create & print labels (Shippo)
├─ 5.7 Track shipments
└─ 5.15 Batch label creation
Phase 5 ─ Refunds & Returns (1-2 days)
├─ 5.8–5.9 Full & partial refund (Stripe)
└─ 5.10 Return processing
Phase 6 ─ Notifications (1-2 days)
├─ 5.11 Order update emails
└─ 5.12 Order update SMS
Phase 7 ─ Customer Management (1 day)
└─ 6.1–6.3 Customer list, detail, orders
Total estimated MVP effort: 11–17 days for a senior engineer.