evidencija-rezija/web-app/docs/sprints/sprint-01-barcode-print.md

📑 Sprint Playbook: Barcode Print Support

0. Sprint Status

Status: ✅ completed

---

1. Sprint Metadata

• Sprint ID: 01
• Start Date: 2025-01-14
• End Date: 2025-01-16
• Sprint Goal: Add capability to print a table containing all 2D barcode images for a given month
• Team/Agent Responsible: AI-Agent (Claude Sonnet 4)
• Branch Name (Git): feature/sprint-01

---

2. Current State of Software

(Snapshot of the project before Sprint work begins)

• Main Features Available:

  • Multi-user utility bills tracking system
  • Monthly billing periods with expandable MonthCard UI components
  • Location and bill management with CRUD operations
  • 2D barcode scanning and storage (bills already have barcodeImage field)
  • PDF processing capabilities with @zxing/library and pdfjs-dist
  • Internationalization support (Croatian/English)

• Known Limitations / Issues:

  • No print functionality for barcode overview
  • Barcode images stored as base64 strings but not displayed in bulk format
  • No print-optimized styling or layout

• Relevant Files / Modules:

  • app/ui/MonthCard.tsx - Monthly accordion components
  • app/ui/MonthLocationList.tsx - Main month listing container
  • app/lib/db-types.ts - Bill interface with barcodeImage field
  • app/lib/actions/locationActions.ts - Data fetching for locations/bills
  • Package dependencies: @zxing/library, @zxing/browser, pdfjs-dist

• Environment / Dependencies:

  • Node.js >=18.17.0
  • Next.js 14 with App Router and TypeScript
  • Tailwind CSS 3.4.0 with DaisyUI 4.5.0
  • MongoDB 6.3.0 for data persistence

---

3. Desired State of Software

(Target state after Sprint is complete)

• New Features:

  • Print 2D codes button in each MonthCard
  • Print preview page with barcode table layout
  • Print-optimized styling with 58mm barcode width specification
  • Fixed print icon for triggering native print dialog

• Modified Features:

  • MonthCard component enhanced with print button
  • New print route and page component added to Next.js routing

• Expected Behavior Changes:

  • Users can access print functionality from month view
  • Print preview opens in new tab/window
  • Barcode table displays with row index, bill info, and barcode image
  • Print layout optimized for A4 paper in B&W

• External Dependencies / Integrations:

  • Native browser print dialog integration
  • CSS print media queries for optimized print output

---

4. User Stories

Story ID	Title	Description	Acceptance Criteria	Definition of Done	Assignee	Status
US-1	Add Print Button	Add print 2D codes button to MonthCard component	Button appears next to "Add a new realestate", has printer icon, tooltips in EN/HR, opens print preview on click	Button implemented, styled with DaisyUI, tooltips working, click handler implemented, user testing completed	AI-Agent	✅ done
US-2	Create Print Route	Implement Next.js route for print preview	Route /print/[year]/[month] exists and loads barcode data	Route created, data fetching implemented, proper error handling, user testing completed	AI-Agent	✅ done
US-3	Build Print Layout	Create print preview page with barcode table	Table has 3 columns: row index, bill info (yyyy-mm, realestate name, bill name), 2D barcode image	Print page component created, table layout implemented, data properly displayed, user testing completed	AI-Agent	✅ done
US-4	Print Optimization	Apply print-specific CSS styling	58mm barcode width, A4 paper size, B&W print, fixed print icon (hidden in print)	CSS print media queries added, barcode sizing correct, print icon positioned and hidden from print, user testing completed	AI-Agent	✅ done

Status options: 🔲 todo, 🚧 in progress, 🚫 blocked, ✅ done

---

5. Technical Instructions

(Guidance to help AI converge quickly on the correct solution)

• Code Snippets / Patterns:

  // Print button component pattern (integrate into MonthCard.tsx)
  import { PrinterIcon } from '@heroicons/react/24/outline';
  
  const handlePrintClick = () => {
    window.open(`/print/${yearMonth.year}/${yearMonth.month}`, '_blank');
  };
  
  <button 
    className="btn btn-ghost btn-sm" 
    onClick={handlePrintClick}
    title={t("print-codes-tooltip")}
  >
    <PrinterIcon className="h-4 w-4" />
    {t("print-codes-label")}
  </button>
  

  // Print page route structure: app/[locale]/print/[year]/[month]/page.tsx
  interface PrintPageProps {
    params: { year: string; month: string; locale: string };
  }
  
  export default async function PrintPage({ params }: PrintPageProps) {
    const locations = await fetchAllLocations(parseInt(params.year));
    // Filter for specific month and extract bills with barcodes
  }
  

  /* Print-specific CSS */
  @media print {
    .no-print { display: none !important; }
    .barcode-cell img { width: 58mm; height: auto; }
    @page { size: A4; margin: 1in; }
  }
  

• Architecture Guidelines:

  • Follow existing Next.js App Router patterns with [locale] prefix
  • Use server components for data fetching, client components only when needed
  • Apply existing withUser HOF pattern for authenticated data access
  • Maintain separation between UI components (app/ui/) and business logic

• Coding Style Conventions:

  • Use TypeScript with existing interface patterns from db-types.ts
  • Follow DaisyUI component classes and Tailwind utilities
  • Use existing translation pattern with useTranslations() hook
  • Maintain existing file naming conventions (PascalCase for components)

• Testing Strategy:

  • AI agent implements feature and stops at testing checkpoint
  • AI provides specific test instructions with expected behavior to user
  • User performs manual testing and reports results (pass/fail with details)
  • AI iterates on failures until user confirms all tests pass
  • Process repeats for each user story until sprint completion

---

6. Risks and Dependencies

• Risks:

  • Browser print dialog compatibility across different browsers
  • Barcode image quality in print output
  • CSS print media query support variations
  • Large number of barcodes may cause performance issues in print preview

• Dependencies:

  • Existing barcode data in Bill.barcodeImage field
  • @heroicons/react for printer icon
  • Tailwind CSS print utilities
  • Next.js routing and internationalization setup

---

7. Sprint Definition of Done (DoD)

The Sprint is complete when:

AI-Responsible Items (AI agent can verify and tick):

• Print button added to MonthCard with proper styling and tooltips
• Print route /[locale]/print/[year]/[month] implemented and functional
• Print preview page displays barcode table with correct layout
• CSS print media queries applied with 69.6mm barcode width specification
• Print icon positioned fixed and hidden from print output
• All user stories meet their individual Definition of Done
• Code compiles and passes automated tests (npm run build)
• Code formatting validated (npm run prettier:check)
• Code is committed and pushed on branch feature/adding-ai-framework
• Sprint status updated to ✅ done

User-Only Items (Only user can verify and tick):

• Branch is merged into main
• Print functionality tested across target browsers
• Print output quality validated on physical printer

---