Projects and work orders
A project is the shared business context for a customer outcome. It connects commercial proposals, accepted work, planning, delivery, dialogue and financial settlement. A work order gives concrete instructions for part of that project’s work. Each keeps its own status and evidence; completing a booking or publishing instructions does not complete the project.
A project can exist before a quote is accepted. Its existence, title or imported source link does not establish commercial authority. Its customer and contacts are references within the project’s company, not a copy of the company’s entire customer relationship.
Responsibilities and records
Section titled “Responsibilities and records”The record model traces identity, source references and projections across this project boundary and the financial records.
| Subject | Owning record | Responsibility |
|---|---|---|
| Opportunity | opportunities |
Enquiry, qualification, follow-up and preparation of a possible job. It can precede a project. |
| Project | projects |
Company, customer context, responsible person, work site, overall dates/status and links to commercial/execution records. |
| Offered or accepted terms | Quote versions, acceptance evidence, contracts and project_billing_basis_lines |
Version-specific scope and commercial authority. A project link does not replace their acceptance checks. |
| Concrete work | work_orders, line items and checklists |
Instructions, quantities, planned window, manual estimate and delivery progress for one project. |
| Personal assignment | project_assignments, work_order_assignments |
Who is assigned at project or exact order scope, with independent assignment/withdrawal state. |
| Calendar booking | project_schedules |
A person’s dated pass or absence, optional order/phase and commitment reference, plus publication state. |
| Subcontractor responsibility | commitments and request/award records |
Principal/executor company, agreed scope and independent commitment lifecycle. |
| Performed work and review | Time reports, daily logs, checklist progress and UE submissions | Execution claims, evidence and review. Planned hours and assignment are not approved actual time. |
flowchart TD T[Company] -->|owns 0..many| P[Project] P -->|optional customer| C[Customer party] P -->|optional source reference| S[Source quote] P -->|optional accepted billing quote| Q[Accepted quote version] P -->|0..many| B[Accepted billing-basis rows] P -->|0..many; each order has one project| W[Work orders] W -->|0..many| L[Instruction lines and checklists] L -->|optional accepted source reference| B P -->|0..many| A[Direct project assignments] W -->|0..many| WA[Exact order assignments] P -->|0..many| D[Bookings and execution evidence] D -->|optional exact order| W P -->|0..many| K[Subcontractor commitments]
The diagram describes record ownership, not an all-purpose access grant. The assignment reference establishes how assignment, company and publication affect worker and subcontractor access.
Project creation and commercial sources
Section titled “Project creation and commercial sources”Manual project creation allocates a company project number and inserts an
unplanned project by default. The browser helper permits missing customer and
quote references; it does not manufacture an accepted agreement. Number allocation
and the insert are separate requests, so an unsuccessful insert can leave a
number gap. A project number identifies a record; consecutive numbers are not
evidence that every earlier project still exists.
Quote-backed handoff uses the API and create_project_from_accepted_quote.
The transaction locks and validates the company’s quote, verifies accepted state,
copies the selected billing basis and reuses an existing active project on retry.
The unique active company/quote index prevents two live projects with the same
fk_quote. Commit-time completeness checks require the selected source rows.
This is stronger than simply inserting a project with a quote ID.
Acceptance evidence can trigger creation of an unplanned project. Imported historical acceptance can explicitly suppress that trigger through its evidence metadata. Consequently neither “every acceptance always creates a new project” nor “every project comes from acceptance” describes all paths. The quote acceptance workflow follows preparation, responses and the accepted-project handoff.
fk_source_quote records the originating offer, including a draft or sent source
offer. fk_quote is the accepted billing-quote relationship. Their different
authority must survive imports and displays. fk_parent_project relates a
change-order child project to its base project; it does not merge their identities.
The current opportunity/quote creation path locks the opportunity and rejects
creation when an active linked project or quote already exists. This is a
transaction rule, not a universal one-to-one cardinality for historical records.
Customer, contact and work-site scope
Section titled “Customer, contact and work-site scope”The project reference trigger requires a non-null customer to have an
is_customer relationship in the project’s company. It checks optional manager,
creator, opportunity, contract and parent references against that company. A
project contact must have a local contact profile or people row. That check
alone does not establish active customer membership or portal access.
For an accepted billing quote, the trigger binds the project’s customer, contact, opportunity, currency and work site to the quote snapshot. The work-site rule has a bounded exception for confirming a missing site; an existing accepted site cannot be silently replaced through that exception. Tenant-owned properties are supported, along with identified shared Lantmäteriet properties. These reference checks supplement operation and resource authorization.
The customer’s postal address and the work site are different facts. Before a site is stored, an unreleased draft can resolve the current customer address. First quote send and project/planning releases can capture a separate property. A project that has already been released or has execution/terminal-state evidence cannot silently reconstruct its historical site from today’s customer address. Publication requires a complete confirmed address. Moving the customer does not move an existing stored job site. See publication for the boundary between current records and an audience’s released version.
Work instructions and accepted-source allocation
Section titled “Work instructions and accepted-source allocation”Every work order has a non-null project reference. The ordinary creation RPC
checks the active company and work_orders:write, a live project, active status,
optional phase belonging to that project, valid dates and non-negative estimate.
Selected workers must be distinct active, non-deleted workers in the same
company. Creation, assignments and copied source lines commit together.
These are checks in the named transaction; a scalar foreign key alone does not
establish every company/parent invariant for arbitrary table writes.
An order can contain manually prepared work, accepted quote rows or both. Accepted rows are selected by billing-basis ID. The RPC accepts eligible rows from its project and qualifying accepted change-order child projects. Unaccepted and unselected optional rows are refused. It copies source description, quantity, unit and room/surface references into instruction lines and keeps the source IDs. It does not make customer prices worker instructions.
Source allocation is whole-line. A transaction advisory lock and allocation trigger
prevent the same basis row being allocated to another non-deleted order.
fk_source_basis_line, source_quoted_hours and source_is_hourly preserve the
creation-time source. Once established, their update is rejected. The basis ID
is deliberately a historical UUID reference without a foreign key; later basis
reconciliation must not rewrite issued work. A quote-line-only insert is resolved
through the same eligible-source and allocation rules.
Quoted source hours, an order’s manual estimated_hours, booked person-time and
reported/approved time describe different quantities. Historical hourly rows
with no creation-time hour snapshot remain unknown. A material quantity is not
missing labour time. Allocating work does not itself consume the
invoice billing basis.
Assignment, booking and completion
Section titled “Assignment, booking and completion”The subcontractor request and award workflow explains how an executor response becomes a project-linked commitment.
A direct project assignment and an exact order assignment are independent rows. An order assignment can derive effective project scope, but a direct project assignment does not grant all order instructions. The current assignment RPC reuses or reactivates the unique order/person row and checks active same-company worker identity. Withdrawal timestamps that relationship; it does not erase it. Read the access reference for the different API, browser and RLS decisions.
Bookings refer to the project and optionally an order/phase or subcontractor commitment. The schedule guard checks compatible company and project scope; absence is a separate booking kind. A booking’s confirmation and publication are not a person’s work submission. Execution and review retain their own statuses.
The project-completion action reads non-deleted orders, pending own/principal time, pending UE submissions and commitments. Open orders, pending reviews and unfinished commitments block completion. It does not establish that every invoice has been paid or that a financial settlement is complete. Completed orders alone are insufficient if another reviewed source still blocks the action.
The browser’s delete action soft-deletes an order. Non-deleted-order source allocation and completion queries then stop counting it, although its historical line and evidence rows can remain. Cancelling an order is different: the allocation trigger tests deletion, so a cancelled but non-deleted order still holds its source row. This review does not certify arbitrary restoration/reparenting, hard deletion or a concurrency-safe project-close transaction. Those paths need targeted evidence before stronger lifecycle guarantees are documented.
Example
Section titled “Example”Example Company opens a project for Household Example before pricing is settled. An accepted quote later provides ten quoted labour hours. One work order uses that whole source row; a second cannot allocate the same row while the first remains non-deleted. A nine-hour calendar plan and an approved 1.5-hour report remain separate measurements. A second manual work order can exist without an accepted source row, but its existence does not authorize additional billing.
Verification scope
Section titled “Verification scope”The focused frontend selection covers the atomic RPC call, assignment retries, contact/recipient editing and failures, with substituted clients. Focused backend source-evidence and completion tests exercise synthetic records and substituted database/authentication services. Their exact counts and candidate are recorded in the delivery PR; they do not execute the database function bodies.
The listed database tests cover atomic handoff, rollback, cross-company denial, concurrent source allocation and child change-order eligibility in their scenarios. They were inspected with the active migration replacements, not run for this review. In particular, the older atomic-assignment test fixture installs an older function signature; it must not be cited as executing today’s complete creation contract. Documentation status describes the source-reviewed explanation and does not establish independent shared-environment business acceptance.