# SYNC_FINANCE Development TODO

This TODO tracks the development process for SYNC_FINANCE, an office finance and document management web application. The current visual direction is based on `create_quotation.html`; the technical direction is based on `STACK_SPECIFICATION.md` and `ARCHITECTURE_GUIDE.md`.

## Progress Legend

- `[x]` Done
- `[~]` In progress
- `[ ]` Not started

---

## 1. Project Foundation

- [x] Define target stack: PHP 8.3+, Composer, FastRoute, Twig, Dompdf, MariaDB, HTMX, Alpine.js, Tailwind CSS.
- [x] Define architecture rules and folder responsibilities.
- [x] Provide sample quotation UI in `create_quotation.html`.
- [x] Initialize Composer project.
- [x] Configure PSR-4 autoloading.
- [x] Create base folder structure:
  - `app/Actions`
  - `app/Controllers`
  - `app/DTOs`
  - `app/Middleware`
  - `app/Models`
  - `app/Repositories`
  - `app/Services`
  - `app/Components`
  - `app/Helpers`
  - `app/Policies`
  - `app/ViewModels`
  - `config`
  - `public`
  - `resources/views`
  - `resources/layouts`
  - `resources/components`
  - `resources/pdf`
  - `routes`
  - `storage`
- [x] Add front controller at `public/index.php`.
- [x] Add environment configuration loading.
- [x] Add application bootstrap file.
- [x] Add basic error handling and exception rendering.

## 2. Routing And Request Flow

- [x] Install and configure FastRoute.
- [x] Create route registration file.
- [x] Implement controller dispatching.
- [x] Add middleware pipeline support.
- [x] Add route groups for:
  - Dashboard
  - Quotations
  - Invoices
  - Delivery Notes
  - Receipts
  - Vouchers
  - Customers
  - Products / Services
  - Reports
  - Settings
- [x] Detect HTMX requests and return partial templates where needed.

## 3. Layout And Design System

- [~] Convert `create_quotation.html` into reusable Twig layout and components.
- [x] Create base app shell:
  - Sidebar
  - Topbar
  - Search box
  - User menu
  - Notification button
  - Responsive mobile sidebar
- [ ] Create reusable components:
  - Button
  - Form field
  - Textarea
  - Select
  - Data table
  - Modal
  - Status badge
  - Summary panel
  - Empty state
  - Pagination
- [x] Replace corrupted icon characters in the sample UI with a consistent icon strategy.
- [x] Extract shared CSS or Tailwind configuration from the sample design.
- [~] Confirm responsive behavior for desktop, tablet, and mobile.

## 4. Authentication And Users

- [x] Create users table.
- [x] Implement login page.
- [x] Implement logout.
- [x] Add password hashing.
- [x] Add authentication middleware.
- [x] Add current user context.
- [x] Add profile/user menu placeholder.
- [x] Add administrator-managed user creation and user list.
- [x] Add password reset workflow.

## 5. Companies And Settings

- [x] Create companies table.
- [x] Add `company_id` support to business entities.
- [x] Create company settings page.
- [x] Store company profile:
  - Name
  - Address
  - Phone
  - Email
  - Logo
  - Tax settings
  - Default currency
- [x] Add document numbering settings.
- [x] Add default payment terms and quotation validity settings.

## 6. Permissions

- [x] Create roles table.
- [x] Create permissions table.
- [x] Create role_permissions table.
- [x] Create user_roles table.
- [x] Add policy-based authorization structure.
- [x] Protect document actions by permission:
  - View
  - Create
  - Edit
  - Delete
  - Approve
  - Send
  - Export PDF

## 7. Document Engine

- [x] Create generic document tables:
  - `documents`
  - `document_items`
  - `document_types`
- [x] Seed document types:
  - Quotation
  - Invoice
  - Delivery Note
  - Receipt
  - Voucher
  - Purchase Order
  - Credit Note
  - Debit Note
- [x] Create document number generator action.
- [x] Create totals calculator action:
  - Subtotal
  - Discount
  - Tax
  - Grand total
- [x] Add document statuses:
  - Draft
  - Sent
  - Accepted
  - Rejected
  - Converted
  - Cancelled
- [x] Add document audit fields.
- [x] Add soft delete support where appropriate.

## 8. Quotations

- [x] Create quotation list page.
- [x] Create quotation create page based on `create_quotation.html`.
- [x] Create quotation edit page.
- [x] Create quotation detail/preview page.
- [x] Implement quotation save draft.
- [x] Implement quotation send workflow.
- [x] Implement quotation PDF export.
- [x] Implement convert quotation to invoice.
- [x] Add quotation search and filtering.
- [x] Add quotation pagination.
- [x] Add item row add/remove behavior with HTMX or Alpine.js.
- [x] Recalculate totals when quantity, price, discount, or tax changes.

## 9. Invoices

- [x] Create invoice list page.
- [x] Create invoice create page.
- [x] Create invoice edit page.
- [x] Create invoice detail/preview page.
- [x] Implement invoice PDF export.
- [x] Implement invoice payment status tracking.
- [x] Link invoices to quotations when converted.
- [x] Add invoice search, filtering, and pagination.

## 10. Receipts, Delivery Notes, And Vouchers

- [x] Create receipt workflow.
- [x] Create delivery note workflow.
- [x] Create voucher workflow.
- [x] Create PDF templates for each document type.
- [x] Link receipts to invoices.
- [x] Link delivery notes to invoices or quotations where appropriate.

## 11. Customers

- [x] Create customers table.
- [~] Create customer repository, model, DTO, service, and controller.
- [x] Create customer list page.
- [x] Create customer create/edit forms.
- [x] Add customer search/autocomplete for document forms.
- [x] Track customer contact details:
  - Name
  - Company
  - Email
  - Phone
  - Billing address
  - Tax PIN / VAT number
- [x] Add customer document history.

## 12. Products And Services

- [x] Create products/services table.
- [~] Create product repository, model, DTO, service, and controller.
- [x] Create product/service list page.
- [x] Create product/service create/edit forms.
- [x] Add product/service search/autocomplete for document item rows.
- [x] Store:
  - Name
  - Description
  - Unit price
  - Tax category
  - Active status

## 13. Reports

- [x] Create sales report page.
- [x] Create tax report page.
- [x] Create outstanding invoices report.
- [x] Create customer statement report.
- [x] Add date range filters.
- [x] Add PDF export for reports.
- [x] Add CSV export where useful.

## 14. PDF Generation

- [x] Install and configure Dompdf.
- [x] Create reusable PDF layout.
- [x] Create quotation PDF template.
- [x] Create invoice PDF template.
- [x] Create receipt PDF template.
- [x] Create delivery note PDF template.
- [x] Create voucher PDF template.
- [ ] Ensure PDF output matches the application design closely enough for business use.
- [ ] Store generated PDFs or regenerate on demand.
- [x] Add browser print / Save as PDF views for quotations and invoices.
- [x] Add server-generated PDF downloads for quotations and invoices.

## 15. HTMX And Alpine.js Enhancements

- [x] Add HTMX partial rendering conventions.
- [x] Add dynamic document item rows.
- [x] Add customer autocomplete.
- [x] Add product/service autocomplete.
- [x] Add inline table filtering.
- [x] Add modal forms.
- [x] Add optimistic UI where low risk.
- [x] Add loading and validation states.

## 16. Validation And Errors

- [x] Create validation helper or service.
- [x] Add form validation errors to Twig components.
- [x] Add CSRF protection.
- [x] Add domain exceptions.
- [x] Add centralized error pages:
  - 400
  - 403
  - 404
  - 500
- [x] Add user-friendly flash messages.

## 17. Database And Migrations

- [x] Decide migration tooling.
- [x] Create initial schema migrations.
- [x] Add seeders for default document types, roles, and settings.
- [x] Add database connection configuration.
- [x] Add repository base conventions.
- [x] Add indexes for common queries.
- [x] Add foreign keys for document/customer/company relationships.

## 18. Testing And Quality

- [x] Add PHPUnit or lightweight test setup.
- [x] Add tests for document total calculations.
- [x] Add tests for document number generation.
- [x] Add tests for quotation creation workflow.
- [x] Add tests for authorization policies.
- [x] Add basic controller/request tests if practical.
- [ ] Add coding standard checks.
- [ ] Add manual QA checklist for core document flows.

## 19. Deployment

- [ ] Confirm cPanel-compatible folder layout.
- [x] Keep web root limited to `public`.
- [x] Add `.env.example`.
- [ ] Add production configuration notes.
- [ ] Add storage permissions notes.
- [ ] Add database setup instructions.
- [ ] Add backup guidance for database and uploaded files.

## 20. Documentation

- [ ] Keep `STACK_SPECIFICATION.md` updated as decisions change.
- [ ] Keep `ARCHITECTURE_GUIDE.md` updated as conventions mature.
- [x] Add setup instructions in `README.md`.
- [ ] Add developer workflow notes.
- [ ] Add module creation guidelines.
- [ ] Document document status lifecycle.
- [ ] Document permission names and meanings.

---

## Immediate Next Milestone

Build the minimum working application shell:

- [x] Composer project initialized.
- [x] FastRoute request flow working.
- [x] Twig rendering working.
- [~] Base layout converted from `create_quotation.html`.
- [x] Dashboard placeholder route working.
- [x] Quotation create route rendering a Twig version of the sample UI.
- [x] Basic responsive sidebar behavior preserved.

## Completed Milestone

Persist quotation drafts:

- [x] Create `CustomerRepository`.
- [x] Create `DocumentRepository`.
- [x] Create `CreateQuotationService`.
- [x] Add POST route for quotation draft saving.
- [x] Validate quotation form input.
- [x] Save customer, document, and document item records.
- [x] Use totals calculator before persistence.
- [x] Redirect to quotation preview/detail page after save.

## Next Milestone

Improve quotation and invoice workflow:

- [x] Create quotation list page.
- [x] Add edit route and form hydration from saved quotation data.
- [x] Add dynamic item row add/remove behavior.
- [x] Recalculate totals in the browser before save.
- [x] Replace placeholder item selection with product/service lookup.
- [x] Add user-friendly validation state beside each field.
- [x] Add CSRF protection before broader form usage.
- [x] Convert accepted quotations into draft invoices.
- [x] Preserve quotation-to-invoice source links.
- [x] Add print-ready quotation and invoice views inspired by the supplied sample printout.
- [x] Replace dashboard placeholders with live document, customer, and outstanding-value metrics.
- [x] Add recent quotation and invoice activity to the dashboard.
- [x] Add company profile settings with CSRF protection and validation.
- [x] Apply the configured default currency to new quotations and invoices.
- [x] Add customer profile pages with quotation and invoice history.
- [x] Add CSRF-protected quotation and invoice status transitions.
- [x] Record when documents are first marked as sent.
- [x] Add date-filtered sales and outstanding-invoice reports.
- [x] Add tax-rate and invoice-level tax reporting.
- [x] Add date-aware CSV exports for sales, tax, and outstanding invoices.
- [x] Add customer statement reporting with CSV export.
- [x] Add branded landscape PDF exports for all completed reports.
- [x] Add invoice-linked receipts with payment balance tracking.
- [x] Add invoice-linked delivery notes with quantity-only print and PDF output.
- [x] Add outgoing payment vouchers with payee, expense items, totals, print, and PDF output.
- [x] Add configurable document prefixes, quotation validity, invoice due days, and default terms.
- [x] Add one-time administrator setup and session-based authentication.
- [x] Restrict user management to administrator accounts.
- [x] Add document permission checks for view, create, edit, status, conversion, and PDF/print export actions.