# Sprint 1 · Completion report

## Status: Ready for UAT

All Sprint 1 features are implemented per the frozen architecture. This document
is the final hand-off from engineering to QA / Product.

## Scope delivered

### 1. Authentication
- Session-based login with Remember Me
- Rate limiting: 5 attempts per email+IP window (configurable)
- Forgot password + Reset password with generic success responses (no user
  enumeration)
- Force change password flow when `must_change_password = 1`
- CSRF and XSS protection on every form
- Login history: LOGIN, LOGOUT, FAILED, LOCKED, PASSWORD_RESET_REQUESTED,
  PASSWORD_RESET, PASSWORD_CHANGED, PROFILE_UPDATED events
- Last login IP + timestamp recorded on the user

### 2. Roles & Permissions
- Five default roles seeded: Admin, Manager, Store Keeper, Salesman, Accountant
- Sprint 1 permissions registered dynamically via
  `UserPermissionService::registerBatch()`
- Admin bypass via `Gate::before`
- System roles cannot be deleted or renamed
- Roles page lists all roles with counts + inline edit

### 3. Company Setup Wizard
- Six steps: Identity → Address → Branding → Preferences → Financial → Admin
- Validation at every step, including GSTIN regex and password strength
- Idempotent (re-run blocked once complete)
- Auto-logs in the newly created admin

### 4. Dashboard Foundation
- 10 widgets rendered with zero values: Today's Sales, Purchase, Profit,
  Credit, Pending Collection, Stock Value, Low Stock, Out of Stock, Dead Stock,
  Business Health Score
- 7-day sales trend chart (ApexCharts) with zeroed series
- Refresh endpoint returning JSON envelope
- Quick actions card with "Coming Sprint N" placeholders
- System health card

### 5. UI Framework
- Design tokens in CSS custom properties
- Light + Dark modes × Comfortable + Compact densities
- Full component library:
  UI: button, badge, card, stat, table, empty, skeleton, toast, modal,
      pagination, dropdown, alert, spinner, avatar, kbd, confirm-modal
  Form: input, select, textarea, checkbox, radio, file, money, qty, password,
        error
  Layout: page-header, section, sticky-save, tabs, divider

### 6. Global Layout
- Sidebar (Dashboard + Settings enabled; other modules disabled with badges)
- Topbar with Ctrl+K search hint, theme toggle, notification bell, profile menu
- Breadcrumb (opt-in per page via `@section('breadcrumb')`)
- Mobile bottom nav (< 768 px)
- Command palette (Ctrl+K / Cmd+K)
- Flash messages, error pages (403, 404, 419), footer

### 7. Theme Engine
- Runtime CSS variables injected as `<style id="theme-vars">`
- Two persistence scopes: per-user and per-company
- Quick toggle from topbar with optimistic UI + server sync

### 8. Settings Foundation
- Landing page with tiles + tabbed navigation
- Company details form (identity, contact, address, branding)
- Preferences form (regional, financial year, documents)
- Theme form (personal + company scope)
- Printer form (default size + header/footer + toggles)
- Security form (password policy + session policy)
- Roles list + create/edit form with grouped permissions

### 9. Profile
- Profile edit (name, email, phone, avatar, locale, timezone, theme)
- Password change with current-password verification and other-session logout
- Login history table with pagination

### 10. Global
- Uniform JSON envelope
- ForceJsonForAjax middleware normalizes redirects for AJAX callers
- EnsureCompanySetup middleware protects the app before first-run
- EnforcePasswordChange middleware forces password change when required
- Global search shell + notifications shell (stable JSON contract)

## Test coverage

Feature tests (`php artisan test`):
- `Auth\LoginTest`
- `Auth\PasswordResetTest`
- `WizardTest`
- `DashboardTest`
- `Settings\CompanySettingsTest`
- `ProfileTest`
- `PermissionsTest`

Unit tests:
- `Domain\UserRoleTest`
- `Support\FormatHelpersTest`

## Explicit non-scope

Products, Inventory, Purchase, Sales/Billing, Credit management, Reports,
Barcode, Excel Import, Backup, and Audit UI are gated by
`config/decent.feature_flags.*` and rendered as disabled modules in the sidebar.

## Verification

Run through `docs/uat/sprint-1.md`. All items must pass before Sprint 2 begins.

## Hand-off checklist

- [x] Migrations run clean on empty DB
- [x] Seeders idempotent (safe to re-run)
- [x] Vite build succeeds without warnings
- [x] `php artisan route:list` shows no orphan routes
- [x] No hardcoded strings for role names outside `UserRole` enum
- [x] All controllers use `authorize(...)` or middleware — never manual checks
- [x] Audit log fires for User/Company/Role/Setting mutations
- [x] Login history recorded for all LoginEvent cases
- [x] AJAX endpoints return JSON envelope
- [x] All future modules stubbed in sidebar with "Coming Sprint N" badges