# CR-8 — Bookings module (bookings, customers, customer_docs) Status: **approved for implementation** · Author: BA/reviewer session 2026-08-31 Wireframes (design source of truth, vendored in `docs/wireframes-v12/`): `booking-management.html` (listing) · `new-booking.html` (create) · `edit-booking.html` (edit, tabbed) · `view-booking.html` (show) · `add-upload-document.html` (document upload screen). Recipe: `docs/adding-a-module.md` still governs **except where §0 below overrides it** — the client gave explicit instructions that deviate from house convention, and the client wins. ## 0. Client-mandated convention overrides (do NOT "fix" these back) These are the user's explicit instructions for THIS module. Each one contradicts the house recipe on purpose; note the override in the relevant file's docblock so a future reader doesn't "correct" it: 1. **No lang files.** All user-facing text — labels, placeholders, section titles, flash messages, validation attribute names, JS strings — is written directly in the controllers and blade views. Do not create `lang/en/bookings.php` or touch existing lang files (exception: nothing — the sidebar label `nav.bookings` already exists and is reused). 2. **No `routes/modules/bookings.php`.** All booking routes are declared directly inside the existing `Route::middleware('auth')->group()` in `routes/web.php` (after the module requires). 3. **ONE shared FormRequest for create and edit** (`BookingRequest`), because the required fields are identical. It serves both store and update. 4. **No Policy classes and no new tests.** Authorization still exists (see §7) but via bare permission checks (`Gate::authorize('bookings.view')`, `$this->user()->can('bookings.create')`, `@can('bookings.edit')`) — spatie registers permissions as gate abilities, and `Gate::before` still carries Super Admin. Do not create `app/Policies/BookingPolicy.php` or any `tests/Feature/Bookings/*`. The EXISTING suite must stay green, which requires minimally updating tests that pin things this CR changes (see §10). 5. **Separate create.blade.php and edit.blade.php** (house twin pattern anyway; they differ structurally here — edit is tabbed). ## 1. Scope **In scope:** `bookings`, `customers`, `customer_docs` tables; booking CRUD (listing + create + edit + show); cancel action (NOT delete — client decision); inquiry code format change to 5 digits; "Proceed to Booking" wiring; unit booking + inquiry `booking_confirm` writers (first in the app); customer document upload/list/download/delete scoped to the booking-type→doc-type mapping; sidebar Bookings entry goes live; permissions `bookings.*`. **Non-goals:** payment/financials anywhere (client: "financial not required" — no Payment Summary card, no Revenue stat card, no amount fields); PAN/Aadhaar fields (drawn on view-booking but captured nowhere — omit the rows); Tower/Floor/Unit Type/Built-up/Facing rows on the unit card (units have no such columns — render only Project, Unit No., Carpet Area); the `booking` option in the inquiries listing's Booking Action select STAYS inert (only the "Proceed to Booking" button is wired, per instruction); the "Customer Documents" and "Cancellation" sidebar sections stay preview-inert; registered/transferred statuses have no writer yet; no demo booking seeder; `tools/responsive-smoke.mjs` untouched. ## 2. Database ### 2.1 `bookings` | column | type | notes | |---|---|---| | id | id | | | code | string unique | `BK-YYYY-00000`; `Booking::nextCode()` cloned from `Inquiry::nextCode()` (same lockForUpdate + withTrashed scan + `RetryOnUniqueCollision::once()` around the whole transaction); not fillable, forceFill only | | booking_type_id | FK booking_types, restrictOnDelete | the "Booking Entity Type" | | booking_date | date | defaults to today in the form, not in the schema | | inquiry_id | FK inquiries, restrictOnDelete | required | | project_id | FK projects, restrictOnDelete | | | unit_id | FK units, restrictOnDelete | | | status | string default 'draft' | enum `BookingStatus`: draft, confirmed, registered, cancelled, transferred (only draft/confirmed/cancelled writable this CR; string column never SQL ENUM) | | through_name | string nullable | the "Through its …" name | | assigned_to | FK users nullable nullOnDelete | "Assigned Sales Person"; on create defaults to the inquiry's assignee | | contact_name / contact_mobile / contact_email | string nullable | Contact Person section | | contact_address | text nullable | | | special_conditions | text nullable | Remarks section | | created_by / updated_by | FK users nullable nullOnDelete | forceFill, not fillable | | timestamps, softDeletes | | | ### 2.2 `customers` One row per person on a booking; the main customer and every co-owner. | column | type | notes | |---|---|---| | id | id | | | booking_id | FK bookings, cascadeOnDelete | | | name | string | "Common Name" | | occupation | string nullable | value of the existing `Occupation` enum | | mobile_number | string | | | alternate_mobile | string nullable | | | email | string nullable | required for the main customer via request rules only | | address | text nullable | required for main via rules only | | **is_co_owner** | unsignedTinyInteger **default 0** | **client-specified**: 0 = main customer, 1 = co-owner; set to 1 whenever a co-owner row is saved | | created_by / updated_by | FK users nullable | | | timestamps, softDeletes | | | Exactly ONE `is_co_owner = 0` row per booking (invariant the service maintains; edits update-in-place / create / delete co-owner rows by comparing submitted rows against existing ones — carry each row's `id` as a hidden field). ### 2.3 `customer_docs` | column | type | notes | |---|---|---| | id | id | | | booking_id | FK bookings, cascadeOnDelete | | | customer_id | FK customers, cascadeOnDelete | whose document: the main customer, or a co-owner if the Co-Applicant select was used | | customer_doc_type_id | FK customer_doc_types, restrictOnDelete | | | file_path | string | server-named, see §6 | | original_name | string | client name, data only, truncated 255 | | remarks | text nullable | the upload screen's "Remark Notes", stored on each row of the batch | | created_by | FK users nullable | | | timestamps, softDeletes | | | ### 2.4 Inquiry code format change (client instruction) Format becomes **`INQ-YYYY-00000`** (5 digits). Two changes: - `Inquiry::CODE_DIGITS` 4 → 5 (generator + factory follow automatically). - A data migration re-pads every existing code: `INQ-2026-0142` → `INQ-2026-00142` (string surgery on the segment after the second dash; `withTrashed`; uniqueness is preserved because padding is injective). Header docblock explains the client instruction. - Sweep the existing suite for literal 4-digit code assertions and update them (that is fixing pins, not writing new tests). `Booking::CODE_DIGITS = 5` too (wireframe draws `BK-2026-0384`; one house style for generated codes wins — recorded deviation). ## 3. Behaviour ### 3.1 Statuses and side effects (client-confirmed decisions) - **Save as Draft** → `status = draft`. NO side effects: unit untouched, inquiry untouched. Two drafts may point at the same unit. - **Confirm Booking** → `status = confirmed`, and inside the SAME transaction: re-read the unit `lockForUpdate()`; it must still be `available` (else a validation error on `unit_id`, back to the form); set `units.status = booked`; set the inquiry `status = booking_confirm` via forceFill. (First writer of both in the app — say so in docblocks. Known, accepted quirk: a later interested follow-up moves the inquiry back to `follow_up`; documented in FollowUpRecorder.) - **Cancel** (replaces Delete everywhere — client decision): member action `POST /bookings/{booking}/cancel` with a JS confirm. Sets `status = cancelled`; if it was confirmed, in the same transaction free the unit (`booked` → `available`, lockForUpdate) and revert the inquiry to `follow_up`. A cancelled booking is view-only: no edit, no cancel button, no document upload/delete (downloads still allowed). There is NO destroy route and NO delete button anywhere in this module. - **Edit**: a draft's footer shows "Save as Draft" + "Confirm Booking" (its path to confirmation); a confirmed booking's footer shows only "Save Changes" (status stays confirmed) — matches edit-booking.html, which draws a confirmed booking. Changing the unit on a confirmed booking frees the old unit and books the new one (both under lock, one transaction). Changing the inquiry on a confirmed booking reverts the old inquiry to `follow_up` and sets the new one to `booking_confirm`. - Submit buttons: one form, `name="action"` value `draft|confirm|save`; validated against the allowed set for the booking's state. ### 3.2 Form field rules (both screens; one `BookingRequest`) Required: booking_type_id (exists, active-agnostic, non-deleted), booking_date (date), inquiry_id (exists non-deleted), project_id, unit_id (exists, belongs to project — tamper-checked; must be `available` OR the booking's own current unit on edit), main customer: name, occupation (in `Occupation` enum values), mobile_number, email (email rule), address. `through_name`: **required when** the selected booking type's name is one of the mapped six (see §3.3); otherwise forbidden-to-matter (nullable, ignored, cleared on save when unmapped). Optional: alternate_mobile, contact_* (email rule when present), special_conditions, assigned_to (exists users). Co-owners: `co_owners` array, each row: `name` **required** (client instruction: "Common name required for all Co-Owner"), `mobile_number` required, `occupation` nullable in-enum, `alternate_mobile`/`email`(email)/ `address` nullable, `id` nullable-integer belonging to THIS booking (tamper check — a foreign row id must fail validation). Max lengths 255 (text columns unlimited). Since it is one FormRequest for both verbs, `unique`-style rules don't apply (there are none on these tables). jsvalidation: bind like the inquiry form, with `clientRuleExclusions()` for the conditional/array rules proengsoft can't express. ### 3.3 The "Through its …" map Constant on the Booking model (name-keyed; booking types are dynamic rows and only these six get a block — any other type, including Individual, shows none): HUF → "Through its Karta"; Proprietorship → "Through its Proprietor"; LLP → "Through its Designated Partner / Authorized Person"; Partnership → "Through its Partner / Authorized Person"; Company → "Through its Director / Authorized Person"; Trust → "Through its Trustee / Authorized Signatory". Placeholders per wireframe ("Enter Karta name", …). One block in the DOM, retitled/shown by JS from a JSON map in a data attribute (rendered from the constant — single source). Server enforces the required-when rule from the same constant. ### 3.4 Dropdown population - **Inquiry select**: every non-deleted inquiry that does NOT already have a live booking (draft or confirmed; cancelled/soft-deleted bookings don't block), PLUS the booking's own inquiry on edit. Option label exactly: `INQ-2026-00145 - Rajesh Patel (3 BHK, Navratna Gulmohar Park)` — code, full_name, property_type label, project name; property_type/project parts omitted gracefully when null. Eager-load; no N+1. - **Project select**: all non-deleted projects. - **Unit select** ("Only available units shown"): units of the selected project with `status = available` ONLY (stricter than the inquiry module's rule — this is a purchase, not a preference), plus, on edit, the booking's own unit. Labels: `A-1201 (Available)` / own unit `A-1204 (Current)`. New JSON cascade endpoint `GET api/bookings/projects/{project}/units` (+ `?include_unit=` for edit) registered in web.php beside the other booking routes, authorized `Gate::authorize('bookings.view')` — do NOT widen the inquiries endpoint. JS mirrors nrems-inquiry-form.js's loadUnits (fetch, createElement, clear on failure). - **Assigned Sales Person** (edit-booking wireframe; also render on create for twin parity — deviation recorded): all active users, like the inquiry form's assigned_to. - **Occupation**: the existing `Occupation` enum options on BOTH screens and in co-owner rows (create-wireframe draws a free-text input; edit-wireframe and every co-owner row draw the select — the select wins for data sanity; recorded deviation). ### 3.5 Prefill from an inquiry ("Proceed to Booking") `GET /bookings/create?inquiry={id}` prefills (server-side, create only): inquiry_id selected; name ← full_name; mobile_number ← whatsapp_number; alternate_mobile, email, occupation, address ← current_address; project_id; unit_id ← tentative_unit_id (only if that unit is still available — else leave unit empty); assigned_to ← inquiry's assigned_to; booking_type left empty. Changing the inquiry select later does NOT rewrite typed fields (assumption, recorded). Booking date input defaults to today (`value` = today when no old input). **Wiring the button:** in `inquiries/show.blade.php`, `create.blade.php`, `edit.blade.php`, `follow-up.blade.php`, replace the disabled `.btn-booking` button with a live link `` — same icon and label, no `disabled`, no coming-soon title — **only where an $inquiry exists** (create.blade.php has none: keep it disabled there, since there is no inquiry to book yet). Gate the live link behind `@can('bookings.create')` (fall back to the disabled button without it). An inquiry already holding a live booking, or one whose status is `booking_confirm`: render the disabled button (title text inline, no lang: "Booking already exists"). ### 3.6 Customer documents (the "documents tab") - **Upload screen** `GET/POST /bookings/{booking}/documents` styled from `add-upload-document.html`: Reference section shows the booking's main customer as a fixed display control (not a free select — this flow is per-booking; deviation recorded) + optional "Co-Applicant" select of THIS booking's co-owners + the Booking Type chip (`fa-tag`, primary-light pill, exactly as drawn). Document rows (dashed dropzone-styled file input per wireframe, `accept=".pdf,.jpg,.jpeg,.png,.doc,.docx"`, hint "PDF, JPG, PNG, DOC — Max 5 MB"): Document Type select listing **ONLY the CustomerDocTypes mapped to the booking's booking type** (client instruction), + file. "Add More" clones a row from a `