39294-vm/05_IMPLEMENTATION_PLAN.md

# Implementation Plan — Swish Auto Care GMS
## For Claude Opus Agent — Build Order & Phase Structure

---

## Overview

Build this system in **6 phases**, one at a time. Each phase is self-contained and delivers working, testable functionality before moving to the next. Do NOT start the next phase until the current phase is fully working.

---

## Pre-Build Checklist (Do First)

Before writing any code, verify the environment:

```bash
# Required installed:
node --version    # 18+ required
mysql --version   # 8.x
npm --version     # 9+

# Create project structure:
mkdir swish-gms && cd swish-gms
mkdir backend frontend
```

---

## Phase 1 — Foundation (Build First)

**Goal:** Database up, backend server running, admin can login, frontend shell renders.

### Backend Tasks:
1. `cd backend && npm init -y`
2. Install: `npm install express mysql2 jsonwebtoken bcryptjs dotenv cors`
3. Install dev: `npm install -D nodemon`
4. Create `.env`:
   ```
   PORT=5000
   DB_HOST=localhost
   DB_USER=root
   DB_PASS=your_mysql_password
   DB_NAME=swish_gms
   JWT_SECRET=swishgms_secret_key_2026
   ```
5. Create `src/config/db.js` — MySQL connection pool using `mysql2/promise`
6. Run the full schema SQL from `01_DATABASE_SCHEMA.md` in MySQL
7. Create `src/middleware/auth.js` — JWT verify middleware
8. Create `src/routes/auth.js` — POST /login, GET /me
9. Create `src/server.js` — Express app with CORS, JSON body parser, routes
10. Create seed script — hash password, insert admin user, insert sample staff and parts
11. Test: `POST http://localhost:5000/api/auth/login` with Postman/curl

### Frontend Tasks:
1. `cd frontend && npm create vite@latest . -- --template react-ts`
2. Install: `npm install react-router-dom axios`
3. Create `src/api/axios.ts` — Axios instance with base URL and JWT interceptors
4. Create `src/context/AuthContext.tsx` — Auth state, login/logout functions
5. Create `src/pages/Login.tsx` — Login form
6. Create `src/components/Layout/` — Sidebar, TopBar, Layout wrapper
7. Create `src/App.tsx` — Router setup with ProtectedRoute wrapper
8. Create placeholder page components for all 14 routes (just `<div>Page Name</div>`)
9. Test: Open http://localhost:5173, login page shows, login works, redirects to dashboard placeholder

### Phase 1 Done When:
- [ ] MySQL schema created, all 8 tables exist
- [ ] Admin can login via API and get JWT
- [ ] Frontend shows login page at /
- [ ] After login, sidebar shows with all nav items
- [ ] Logout works and returns to login page

---

## Phase 2 — Job Cards & Status Board

**Goal:** Admin can create, view, and close job cards. Status board works.

### Backend Tasks:
1. Create `src/routes/jobCards.js` with all routes from `02_API_REFERENCE.md`
2. Implement job number generation (SAC-YYYYMMDD-001)
3. Implement GET with filters (status, date, reg_no, pagination)
4. Implement POST (create full and quick wash)
5. Implement PUT (edit while active)
6. Implement POST /:id/close (mark done with validation)
7. Create `src/routes/dashboard.js` — GET /today (needs job data)

### Frontend Tasks:
1. Build `src/pages/JobCards.tsx` — table with search, filter, actions
2. Build `src/pages/JobCardNew.tsx` — dual-form (Full / Quick Wash toggle)
3. Build close job modal (inline in JobCards.tsx)
4. Build `src/pages/StatusBoard.tsx` — two-column Active/Done view
5. Build `src/pages/Dashboard.tsx` — 6 widget cards, quick actions
6. Build shared `<Badge>` component
7. Build shared `<Modal>` component

### Phase 2 Done When:
- [ ] AC-02: Can create Full and Quick Wash job cards
- [ ] AC-03: Jobs show as Active, can be marked Done with amount + payment
- [ ] AC-01 (partial): Dashboard loads with active/done job counts and revenue
- [ ] Status board shows two columns

---

## Phase 3 — Staff, Attendance & Salary

**Goal:** Staff management, daily attendance marking, and salary logging all work.

### Backend Tasks:
1. Create `src/routes/staff.js` — CRUD, toggle active
2. Create `src/routes/attendance.js` — GET by date, bulk POST, monthly summary
3. Create `src/routes/salary.js` — list, create payment, GET calculate endpoint
4. Update `src/routes/dashboard.js` — add staff_present count
5. Add staff count to dashboard API

### Frontend Tasks:
1. Build `src/pages/Staff.tsx` — table, add/edit modal, toggle active
2. Build `src/pages/Attendance.tsx` — bulk attendance marking grid with date picker
3. Build `src/pages/Salary.tsx` — payment form with auto-calculate + history table

### Phase 3 Done When:
- [ ] AC-04: Admin can mark daily attendance for all staff
- [ ] AC-05: Admin can log salary/advance, view history
- [ ] Dashboard shows staff_present count correctly
- [ ] New job card dropdown shows active staff list

---

## Phase 4 — Parts, Sales & Cash Ledger

**Goal:** Inventory, POS-style parts sales, and manual cash entries all work.

### Backend Tasks:
1. Create `src/routes/parts.js` — CRUD, stock adjustment
2. Create `src/routes/partsSales.js` — list, create sale (with stock deduction)
3. Create `src/routes/cashLedger.js` — list, create entry
4. Add parts_revenue to dashboard totals

### Frontend Tasks:
1. Build `src/pages/Parts.tsx` — parts table with low stock badge, restock modal
2. Build `src/pages/PartsSales.tsx` — sales table, new sale modal with stock check
3. Build `src/pages/CashLedger.tsx` — ledger table, cash in/out modal

### Phase 4 Done When:
- [ ] AC-06: Admin can record parts sale, stock quantity decreases
- [ ] AC-07: Admin can enter cash in/out with reasons
- [ ] Dashboard today_revenue now includes parts_revenue

---

## Phase 5 — Accounts, Reports & Exports

**Goal:** Accounts consolidation, daily report download, and all 4 Excel exports work.

### Backend Tasks:
1. Create `src/routes/accounts.js` — summary (aggregate query), transactions list
2. Create `src/routes/reports.js` — daily report JSON + Excel download
3. Create `src/routes/exports.js` — 4 separate Excel export endpoints
4. Install SheetJS: `npm install xlsx`
5. Create `src/utils/excel.js` — helper for creating Excel files (see 04_BUSINESS_LOGIC.md)

### Frontend Tasks:
1. Build `src/pages/Accounts.tsx` — summary cards, income/expense breakdown, transactions
2. Build `src/pages/DailyReport.tsx` — date picker, on-screen preview tables, download button
3. Build `src/pages/Exports.tsx` — 4 export cards with date pickers and download buttons
4. Handle file download in frontend (trigger blob download from axios response)

### Excel Download Pattern (Frontend):
```ts
const downloadExcel = async (url: string, filename: string, params?: object) => {
  const response = await api.get(url, { params, responseType: 'blob' });
  const blob = new Blob([response.data], {
    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  });
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = filename;
  link.click();
  URL.revokeObjectURL(link.href);
};
```

### Phase 5 Done When:
- [ ] AC-08: Accounts shows today's income, expenses, balance
- [ ] AC-09: Daily report downloads as formatted Excel
- [ ] AC-10: All 4 export buttons produce correct .xlsx files

---

## Phase 6 — Polish, Testing & Seed Data

**Goal:** Everything looks good, works reliably, has realistic demo data.

### Tasks:
1. Run through all 10 AC acceptance criteria manually
2. Fix any bugs found
3. Create comprehensive seed data:
   - 5-10 job cards (mix of active and done, various dates)
   - 30 days of attendance for all 4 staff
   - 3-4 salary payment records
   - 10-15 parts sales
   - 15-20 cash ledger entries (mix in/out)
4. UI polish:
   - Loading states (skeleton loaders or spinner) on all data tables
   - Error states when API calls fail
   - Empty states ("No job cards yet" with create button)
   - Toast notifications for all create/update actions
   - Confirm dialog before marking job done
5. Update Dashboard `today_revenue` to include ALL income sources
6. Verify all date formatting is DD/MM/YYYY
7. Verify all currency shows ₹ with Indian comma formatting
8. Final test: full demo walkthrough

### Phase 6 Done When:
- [ ] All 10 ACs pass
- [ ] Demo data loaded and looks realistic
- [ ] No console errors in browser
- [ ] No server errors in terminal
- [ ] Admin password works: username=admin, password=swish@2024

---

## Dependency Install Summary

### Backend
```bash
cd backend
npm install express mysql2 jsonwebtoken bcryptjs dotenv cors xlsx
npm install -D nodemon
```

### package.json scripts (backend):
```json
{
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "seed": "node src/config/seed.js"
  }
}
```

### Frontend
```bash
cd frontend
npm install react-router-dom axios
```

---

## Environment Variables (.env — Backend)

```
PORT=5000
DB_HOST=localhost
DB_USER=root
DB_PASS=your_mysql_root_password
DB_NAME=swish_gms
JWT_SECRET=swishgms_jwt_secret_2026_local
NODE_ENV=development
```

---

## Running the App

```bash
# Terminal 1 — Backend
cd backend && npm run dev

# Terminal 2 — Frontend
cd frontend && npm run dev

# Browser
http://localhost:5173
Login: admin / swish@2024
```

---

## Common Mistakes to Avoid

1. **Don't use `mysql` package** — use `mysql2/promise` for async/await support
2. **Don't forget CORS** — frontend on :5173, backend on :5000 — need CORS middleware
3. **Don't store plain passwords** — always bcrypt.hash before insert
4. **Don't skip the ON DUPLICATE KEY for attendance** — must upsert, not insert
5. **Don't forget stock validation** — check stock before inserting parts sale
6. **Don't use DELETE** — business rule says no deletion, only voiding (not needed in demo but don't implement delete routes)
7. **Excel download needs responseType: 'blob'** in frontend axios call
8. **JWT_SECRET must match** between sign and verify — both use same env var