billing-portal-ui-tasks.org

#+TITLE: Billing Portal — UI Implementation Tasks (Next.js)

#+AUTHOR: Apollo (Next.js Guru & Modern Web Advisor)

* TODO Task 1: Add bills table to Drizzle schema

Update ~lib/db/schema.ts~ (existing)

- Follow: existing invoices table pattern (same structure, same column types)

- Fields: billNumber, customer info, amounts (subtotal, taxRate, taxAmount, discount, totalAmount), dueDate

- Status: draft, sent, paid, overdue, cancelled

- Payment: paidAt, paymentMethod, paymentReference

- Reminders: reminderCount (default 0), lastReminderDate (nullable)

- Value: Foundation — all pages and API routes depend on this schema

* TODO Task 2: Create bills API routes

Create ~app/api/bills/route.ts~

Create ~app/api/bills/[id]/route.ts~

- Follow: existing invoices API routes (GET list, POST create, GET/PUT/DELETE by id)

- Features: search by billNumber/customerName, ordering, pagination

- Value: Data layer — all pages consume these endpoints

* TODO Task 3: Create admin bills pages

Create ~app/(admin)/admin/bills/page.tsx~

Create ~app/(admin)/admin/bills/new/page.tsx~

Create ~app/(admin)/admin/bills/[id]/page.tsx~

Create ~app/(admin)/admin/bills/[id]/edit/page.tsx~

- Follow: admin/invoices/ pages — same shadcn Table, Badge, forms, detail view

- List: shadcn Table with search, status Badges (paid=emerald, overdue=amber, draft=slate), actions

- Detail: status banner, amounts breakdown, payment info, “Pay Now” button

- Value: Admin can manage bills from the dashboard

* TODO Task 4: Create portal bills pages

Create ~app/(main)/bills/page.tsx~

Create ~app/(main)/bills/[id]/page.tsx~

- List: Tailwind card grid with status badges, “Pay Now” buttons (match Athena’s bills-list mockup)

- Detail: bill info with payment status (match Athena’s bill-detail mockup)

- Pattern: Server Components for data fetching, Client Components for interactive elements

- Value: Customer-facing portal — the billing homepage

* TODO Task 5: Create BillPayment component

Create ~components/payments/BillPayment.tsx~

- Follow: InvoicePayment.tsx pattern — Dialog + Stripe/PayPal toggle

- Stripe: StripeCheckoutForm inside StripeProvider (already exists)

- PayPal: PayPalCheckout inside PayPalProvider (already exists)

- Value: Reusable payment dialog — works on admin detail and portal detail

* TODO Task 6: Wire payment API for bills

Create ~app/api/payments/stripe/create-bill-intent/route.ts~

Create ~app/api/payments/stripe/confirm-bill/route.ts~

Create ~app/api/payments/paypal/create-bill-order/route.ts~

Create ~app/api/payments/paypal/capture-bill-order/route.ts~

- Follow: existing invoice payment routes — same Stripe/PayPal flow, operating on bills table

- Value: Full payment pipeline — Stripe + PayPal working for bills

* TODO Task 7: Navigation & routing

Update ~components/admin/AdminSidebar.tsx~ (existing)

Update ~components/layout/Navbar.tsx~ (existing)

- Add: “Bills” link to AdminSidebar (admin panel)

- Add: “My Bills” link to Navbar (portal)

- Value: Bills are discoverable from both admin and portal navigation

* TODO Task 8: Smoke test & cleanup

- Add bills to seed.ts (10 sample bills with Faker.js, matching invoices seed pattern)

- Verify: admin pages (list, create, edit, detail), portal pages (list, detail), payment flow

- Cleanup: remove inherited Invoice/Payslip sample code we no longer need

- Value: Confidence — everything works end-to-end before shipping