admin/the-pet-loft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(admin): implement product management — list, create, edit, archive (Plan 03)

Browse Source 
Covers checklist items 3.1–3.4, 3.10–3.11 (product list, create, edit,
archive/restore, SEO fields, admin search).

Backend (convex/products.ts):
- Extended create/update with shortDescription, brand, attributes,
  seoTitle, seoDescription, canonicalSlug
- Both mutations now set createdAt/updatedAt timestamps
- Added getByIdForAdmin (admin-only, returns full product with relations)

UI — new pages:
- products/page.tsx: table with debounced search, column visibility
  dropdown, client-side sort, 10-row skeleton, load-more pagination,
  row preview dialog, per-row actions menu
- products/new/page.tsx: create product page
- products/[id]/edit/page.tsx: pre-populated edit page with archive button

UI — new components:
- ProductForm: shared form (create + edit); zod + react-hook-form,
  auto-slug, collapsible Attributes + SEO sections, submit spinner
- ProductPreviewDialog: read-only full-product dialog
- ProductActionsMenu: kebab menu (Edit link + Archive AlertDialog)

ShadCN components installed: table, badge, alert-dialog, dialog,
scroll-area, form, select, label, checkbox, textarea

Also:
- Updated CLAUDE.md: form submit buttons must use inline SVG spinner
  with data-icon="inline-start"; link-styled buttons use buttonVariants
  on <Link> (Button render prop not in TS types)
- Updated docs: checklist and plan marked complete

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ianshaloom
2026-03-05 17:38:13 +03:00
parent 2dc8878db7
commit 5168553bae
39 changed files with 5209 additions and 498 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
apps/admin/docs/00-admin-dashboard-feature-checklist.md Normal file
View File

@@ -0,0 +1,273 @@
# 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](./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 | `[ ]` BE+UI | Need Convex file storage upload flow → `products.addImage`. Currently `addImage` takes a URL; need `generateUploadUrl` + upload action. |
| 3.6 | Image gallery management | `[~]` UI | Backend: `addImage`, `deleteImage`, `reorderImages`. Drag-and-drop reorder UI. |
| 3.7 | Variant management | `[~]` UI | Backend: `addVariant`, `updateVariant`, `deleteVariant`. Inline table or modal for CRUD. |
| 3.8 | Stock quantity editing | `[~]` UI | Backend: `updateVariant` accepts `stockQuantity`. Inline edit in variant table. |
| 3.9 | Price and compare-at-price editing | `[~]` UI | Backend: `updateVariant` accepts `price`, `compareAtPrice`. |
| 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.