feat: data model and services (M2)

[gdarko]

M2 of the Tasks and Projects module: the data model, the services that hold the business rules, and the unit tests that pin the invariants. No HTTP surface yet, that is M3.

Tables

Five reversible migrations, all prefixed tp_, all carrying company_id, none with a database-level foreign key. Host key widths are not uniform, so company_id, user_id, assignee_id, creator_id, currency_id, invoice_id, invoice_item_id and running_user_id are unsignedInteger, customer_id is unsignedBigInteger, and module-internal references are unsignedBigInteger.

Table	Notes
tp_projects	customer optional (null is an internal project), status ACTIVE / ARCHIVED, default_rate in minor units per hour
tp_project_members	unique on (project_id, user_id), optional per-member rate
tp_task_statuses	board columns per company, one default, a closed flag
tp_tasks	customer_id denormalised from the project, board_position decimal(20,10), unique on (company_id, number)
tp_time_entries	authoritative duration_minutes, frozen rate and amount, unique on (company_id, running_user_id)

Two of those indexes carry an invariant rather than just speed. (company_id, number) backs the per-company task sequence, and (company_id, running_user_id) enforces one running timer per user per company on MySQL, PostgreSQL and SQLite alike, since all three treat NULLs in a unique index as distinct: no partial index, no second table.

Task statuses are not seeded in a migration. A migration runs once per database while companies come and go, and the reversible-migration contract keeps data writes out of up(), so TaskStatusService::ensureDefaults() creates Backlog / In Progress / Review / Done the first time a company needs them.

Services

All of app/Application, constructor injection, no business logic in the models and no host Eloquent model anywhere.

• Rounding static roundMinutes
• RateResolver resolve
• TaskNumberSequence next
• BoardOrderingService positionFor, renormalise
• BoardQuery columns
• ProjectService listFor, findForCompany, create, update, archive, unarchive, delete, totals
• ProjectMemberService listFor, attach, detach
• TaskStatusService ensureDefaults, listFor, findForCompany, defaultFor, create, update, reorder, delete
• TaskService listFor, findForCompany, create, update, delete, move
• TimeEntryService create, update, delete, findForCompany, listFor, static amountFor
• TimerService running, start, stop, discard
• BillingService unbilled, prepare, confirm
• ReportService summary
• ModuleSettings defaultRate, roundingMinutes, weekStart, membersSeeAllTime

Invariants the tests pin

• Rounding happens at save, not at invoice time, so the timesheet and the invoice agree. Zero stays zero; anything above zero bills at least one increment.
• The rate is resolved once and frozen onto the entry. Changing a task, member, project or company rate afterwards never rewrites what was already logged, and a stamped entry never re-resolves at all.
• The board keeps fractional positions so a drag rewrites one row, and renormalises the column to whole steps when a gap stops being halvable. A neighbour from another company or another column is refused.
• One running timer per user per company. The read check raises TimerAlreadyRunning, and so does the unique-index violation for the race that slips past it; a test forces that race through a model event.
• Billing refuses a mixed selection, by customer or by currency, and refuses non-billable, still-running, already-invoiced and out-of-company entries. prepare returns the host invoice body with groups[i] aligned to items[i], hours to two decimals, price in minor units, and the blended rate when a line spans two rates. confirm is idempotent, so a half-finished round trip can be replayed, and refuses an entry stamped to a different invoice.
• An entry whose invoice no longer exists becomes unbilled again, checked through CompanyDataReader::existingInvoiceIds, because the module has no delete hook.
• Company isolation everywhere findForCompany exists, and time on an internal project never reaches the billing screen.
• Removing a member never destroys their time. Entries keep user_id and render as a removed member.
• Reports stay per currency and never convert.

Abilities

Thirteen abilities registered through Registry::registerAbility(), namespaced by the SDK as tasks-projects:{ability}, with the dependency graph from the spec's authorization table. Dependencies on host abilities, view-customer and create-invoice, stay un-namespaced.

Temporary SDK pin

registerAbility(), registerPage and the companyMembers / existingInvoiceIds readers are on the unreleased SDK branch feat/page-route-abilities-members, so composer.json pins invoiceshelf/modules to ^3.4.0 and satisfies it through an inline composer package repository pointing at commit fb7b629.

The obvious "dev-feat/... as 3.4.0" alias does not work here: validate-package requires a plain SemVer constraint and rejects an alias, so the pin has to look like a real version. When the SDK tags 3.4.0, replace the whole repositories block with the plain vcs entry and nothing else changes. That swap is noted in AGENTS.md.

One build fix that rode along

Tailwind v4 detects content automatically and explicit @source directives add to that detection rather than replacing it, so dist/style.css was being built from utility-looking words found anywhere in the repository. Adding backend files moved the compiled stylesheet and broke the CI check that dist is up to date, on a change that never touched the frontend. source(none) on the utilities import turns the automatic detection off, so only resources/js feeds the scanner.

Verification

vendor/bin/pint                       passed
composer run lint                     passed
composer run test                     OK (125 tests, 273 assertions)
invoiceshelf-module validate-module   Valid
invoiceshelf-module validate-package  Valid
pnpm run lint / tsc --noEmit / build  passed, dist stable

composer.lock is deliberately left untracked, matching the other official modules.

https://claude.ai/code/session_01DCf36XDKprZifej8dc2r1E

[gdarko]

Superseded by #14, which carries this stack consolidated into three commits on top of main.