Production Acceptance Criteria

📄 General
← Back to Documentation
# Production Acceptance Criteria This document defines the automated acceptance gates for the non-Filament company-admin backend and the HTTP endpoints consumed by the mobile applications. A release is not production-ready unless every required test below passes in CI against the production-equivalent test database and configuration. ## Contract Status and Ownership This document is the acceptance contract between the backend team and the mobile development team. It becomes an approved production contract only after both teams complete the sign-off record at the end of this document. The backend team owns endpoint behavior, authentication, authorization, tenant isolation, validation, response schemas, error schemas, documentation, OpenAPI definitions, test fixtures, and backend CI results. The mobile team owns client integration verification on every supported mobile platform, including request construction, token handling, response decoding, error-state handling, retry behavior, backward compatibility, and release-candidate smoke testing. Neither a successful backend test run nor a successful mobile build is sufficient on its own. Production acceptance requires evidence from both teams. ## Release Gate Run the complete acceptance gate with: ```bash php artisan test \ tests/Feature/CompanyAdmin/CompanyAdminModuleAcceptanceTest.php \ tests/Feature/Mobile/MobileEndpointAcceptanceTest.php \ tests/Feature/ReceptionAcceptanceTest.php ``` The release passes only when: - PHPUnit exits with code `0`. - No tests are failed, errored, risky, skipped, or incomplete without a documented release exception. - The test database is isolated from development and production data. - Every new, renamed, or removed module is intentionally reflected in the module inventories. - Every API change is reflected in `MOBILE_APP_API_DOCUMENTATION.md`, `MOBILE_APP_PAGES_ENDPOINTS_REFERENCE.md`, `public/openapi.yaml`, and `docs/openapi.yaml`. - Both OpenAPI YAML files validate and remain synchronized, and every local schema reference resolves. ## Mobile Team Acceptance Gate Before accepting this contract, the mobile development team must verify the release candidate against a production-equivalent API environment and record evidence for each item below. - The mobile client uses only endpoints represented in the synchronized OpenAPI contract. - Authentication, token refresh, logout, expired-token, revoked-token, and unauthenticated flows behave as documented. - Every protected endpoint returns JSON errors; no API request redirects to an HTML login page. - The client correctly handles `400`, `401`, `403`, `404`, `409`, `422`, `429`, and `5xx` responses. - B2C users cannot access company-admin data or actions. - Company users cannot access data belonging to another company, venue, workspace, booking, guest, invoice, document, payment, or operational record. - Capability-restricted screens and actions are hidden or disabled in the client and remain rejected by the backend when called directly. - Pagination, filtering, sorting, dates, time zones, currencies, decimal amounts, nullable properties, and localized strings decode correctly. - Uploads, downloads, QR operations, payments, fiscal operations, and other binary or external-service flows are verified on supported devices where applicable. - The client handles duplicate submissions, slow responses, loss of connectivity, retryable failures, and rate limiting without creating duplicate business operations. - The release candidate has no unresolved contract parsing errors, undocumented response variants, or endpoint workarounds. - iOS, Android, and any other supported client pass the agreed smoke-test matrix. Mobile acceptance evidence must include: - Mobile application version and build number. - Backend API/OpenAPI version tested. - Environment and test date. - Supported platform and OS versions tested. - Automated test report or CI link. - Manual smoke-test report for device-dependent workflows. - A list of accepted limitations, if any, with owner and target resolution release. ## Non-Filament Company-Admin Backend Automated suite: `tests/Feature/CompanyAdmin/CompanyAdminModuleAcceptanceTest.php` ### Required module coverage The following 62 backend modules must remain registered and covered: | | | | |---|---|---| | AI copilot | Attendance | B2B invoices | | Bookings | Business-date close | Cancellation policies | | Cancellation settings | Cashier shifts | Check-out folio review | | Clients | Deals | Departments | | Documents | Employee time | ESTI | | Facilities | Financials | Fiscal | | Fiscal receipts | Front desk | Gantt chart | | Guest messaging | Guest service | Guests | | Housekeeping | Housekeeping staff | Inspections | | Integrations | Inventory | Invoices | | Message templates | Messaging | Notification preferences | | Packages | Payment | Payments | | POS | Pre-check-in | Products | | Profile | Rates | Reception | | Reporting | Reports | Role permissions | | Roles | Room assignments | Services | | Settings | Settlements | Special workflows | | Statistics | Stay modifications | Stays | | Subscriptions | Company switching | Department switching | | Workspace switching | Users | Venue objects | | Venues | Widgets | | ### Automated criteria #### Backend module inventory - Every supported module has at least one named `company-admin.*` route. - Adding or removing a module fails the test until the inventory is deliberately updated. - The testing-only `company-admin.test-force-500` route is excluded from the production module inventory. #### Backend security boundary Every company-admin route must include all of the following middleware: - `auth` - `company.admin` - `company.admin.permission` - `company.admin.department` - `EnforceCompanySubscription` #### Backend controller contract - Every non-closure route resolves to an existing controller class. - Every routed controller method exists and is public. - Company-admin routes must not resolve to Filament controllers. #### Backend anonymous-access rejection - Every endpoint from every module is requested without authentication. - Every request must redirect to the login route. - No company-admin module may return protected content to an anonymous caller. - Every HTTP method and URI combination must be unique. ## Reception Workflow Acceptance Automated suite and implementation guideline: `tests/Feature/ReceptionAcceptanceTest.php` The suite must prove the following business workflows against the database: 1. Tenant separation between companies and venues. 2. Availability enforcement and double-booking prevention. 3. Booking creation. 4. Guest check-in. 5. Room assignment and room changes. 6. Guest registration. 7. Payments and deposits. 8. Folio charges and total recalculation. 9. Guest checkout. 10. Housekeeping handoff. 11. Room-key custody. 12. Cashier-shift closure. 13. Business-date closure. 14. No-show processing. 15. B2B invoice routing. 16. Guest-service workflows. Every new module-specific workflow suite should follow this pattern and include successful workflows, validation failures, authorization failures, tenant isolation, invalid identifiers, forbidden state transitions, and persisted side effects. ## Mobile Endpoint Acceptance Automated suite: `tests/Feature/Mobile/MobileEndpointAcceptanceTest.php` ### Required mobile route-family coverage The following 20 route families must remain registered and covered: | Client and shared API | Company and operational API | |---|---| | Authentication | Company management | | User account | Company-admin API | | Bonus points | Bookings | | Categories | Documents | | Deals | ESTI | | Geocoding | Fiscal receipts | | Location | MyPOS | | Locations | Venue translations | | Locations by country | Venues | | Places by location | Time zones | The internal Channex webhook and testing-only `/api/test` endpoint are explicitly outside the mobile endpoint inventory. ### Automated criteria #### Mobile module inventory - Every supported route family has at least one `/api/...` route. - Adding or removing a route family fails the test until the inventory is deliberately updated. #### Mobile controller contract - Every non-closure endpoint resolves to an existing controller class. - Every routed action exists and is public. - A single failure reports every broken controller binding found during the run. #### Mobile authentication contract - Every endpoint from every Sanctum-protected route family is requested anonymously. - Protected endpoints must return HTTP `401`. - The response content type must be JSON containing `{"message":"Unauthenticated."}`. - Protected endpoints must not redirect mobile clients to an HTML login screen. - Every HTTP method and URI combination must be unique. - Every operation published in `public/openapi.yaml` must resolve to a Laravel mobile route. - `public/openapi.yaml` and `docs/openapi.yaml` must be byte-for-byte synchronized. - The OpenAPI document must parse as valid YAML and every local `#/components/schemas/...` reference must resolve. #### Company-admin mobile tenant boundary - Every `/api/company-admin/...` endpoint must use `auth:sanctum`. - Every `/api/company-admin/...` endpoint must enforce the active company subscription scope. - Endpoint-specific capability tests must additionally cover read, write, finance, QR, check-in, check-out, user-management, and workspace-management permissions where applicable. ## Current Blocking Acceptance Failures The mobile controller-contract test currently identifies these pre-existing invalid route bindings: | Endpoint | Missing action | |---|---| | `POST /api/mypos/payments/confirm` | `MyPOS\\OnlinePayments\\MyPosController@confirmPayment` | | `POST /api/mypos/payments/void` | `MyPOS\\OnlinePayments\\MyPosController@voidPayment` | | `POST /api/mypos/payments/refund` | `MyPOS\\OnlinePayments\\MyPosController@refundPayment` | | `POST /api/mypos/payments/cancel` | `MyPOS\\OnlinePayments\\MyPosController@cancelPayment` | | `POST /api/mypos/cash-register/init` | `MyPOS\\InPersonPayments\\CashRegisterController@init` | | `POST /api/mypos/cash-register/get-transaction` | `MyPOS\\InPersonPayments\\CashRegisterController@getTransaction` | | `POST /api/mypos/cash-register/get-transaction-history` | `MyPOS\\InPersonPayments\\CashRegisterController@getTransactionHistory` | | `GET /api/timezones` | `CompanyRegistrationController@getTimezones` | These failures must be resolved by implementing the documented behavior or intentionally removing the endpoint and updating all four API documentation artifacts. They must not be suppressed or excluded from the acceptance suite. The OpenAPI route-resolution scenario also currently reports published operations that have no matching Laravel route or use a different HTTP method. Those discrepancies are release blockers: each operation must either be implemented exactly as published or removed/versioned through the documented compatibility process. ## Definition of Done for New Endpoint Tests An endpoint is production-ready only when its tests cover, where applicable: - Correct HTTP method, path, status code, and response schema. - Anonymous access and insufficient-permission behavior. - Cross-company and cross-venue resource isolation. - Valid create, read, update, delete, and workflow transitions. - Required fields, malformed values, boundary values, and invalid identifiers. - Idempotency or duplicate-submission behavior for payments and workflow actions. - Database changes, emitted events, queued jobs, notifications, and file side effects. - External-service failures without performing live network calls in CI. - Stable error responses that do not disclose stack traces, credentials, or internal paths. - Matching mobile documentation and OpenAPI definitions. ## Compatibility and Change Control After mobile-team acceptance, the accepted OpenAPI version is the source of truth for request and response compatibility. - Removing or renaming an endpoint, field, enum value, or supported workflow is a breaking change. - Changing a field's type, nullability, meaning, default, validation rule, status code, or error shape is a breaking change unless explicitly demonstrated to be backward-compatible. - Adding an optional response field is backward-compatible only when mobile clients ignore unknown fields. - Adding a required request field is a breaking change. - Authentication, authorization, tenant scope, pagination, throttling, and idempotency changes require mobile-team review even when the URL remains unchanged. - Breaking changes require a new API version or an agreed migration window during which old and new contracts are supported concurrently. - Every API contract change must update both mobile Markdown references and both synchronized OpenAPI files in the same change. - The backend team must provide the updated contract and a deployable test environment before requesting mobile acceptance. - The mobile team must not rely on undocumented fields or behavior. Any required undocumented behavior must be added to the contract before acceptance. ## Acceptance Sign-Off The contract is **not accepted** while any mandatory automated test is failing, any blocking acceptance failure remains open, or any required evidence below is missing. ### Backend team - [ ] All backend and mobile endpoint acceptance suites pass. - [ ] Both OpenAPI YAML files validate and are synchronized. - [ ] Mobile API documentation matches deployed behavior. - [ ] Production-equivalent test environment is available. - [ ] Known limitations and migration requirements are documented. - Backend API/OpenAPI version: ____________________ - Backend release/commit: ____________________ - Accepted by: ____________________ - Role: ____________________ - Date: ____________________ ### Mobile development team - [ ] Contract review completed. - [ ] Generated or handwritten API client validated against the accepted OpenAPI version. - [ ] Automated integration tests pass. - [ ] Supported-platform smoke tests pass. - [ ] Authentication, error, offline, retry, and permission states are verified. - [ ] No blocking contract discrepancies remain. - Mobile application version/build: ____________________ - Platforms tested: ____________________ - Test evidence/CI reference: ____________________ - Accepted by: ____________________ - Role: ____________________ - Date: ____________________ ### Final release decision - [ ] Backend team accepted. - [ ] Mobile development team accepted. - [ ] Product/release owner approved any explicitly documented non-blocking limitations. - Decision: **Accepted / Rejected** - Release identifier: ____________________ - Approved by: ____________________ - Date: ____________________ ## Full Automated Scenario Checklist This checklist is the authoritative automation backlog. Every item is mandatory unless it is marked not applicable through the exception process below. Checkbox meaning: - `[ ]` means the scenario is missing, incomplete, failing, or has not been mapped to a passing CI test. - `[x]` may be used only when an executable automated test exists, runs in CI, and passes against the production-equivalent test environment. - A route-presence or middleware-reflection assertion does not satisfy a business-workflow scenario. - Manual testing may supplement these scenarios but cannot replace them. - Each automated test should reference the applicable scenario ID in its PHPDoc, test name, data-provider label, or CI mapping report. ### Company-admin module coverage audit Audit date: 2026-09-14. This audit compares all 62 routed company-admin modules with the executable tests currently present. `Structural only` means route registration, controller binding, middleware, and anonymous rejection are checked, but business behavior is not. `Partial workflow` means one or more business paths are tested, but the full module checklist is not. `Full` requires every applicable baseline and module-specific scenario to pass in CI; no module currently meets that standard. | Module | Routed actions | Current status | Existing automated evidence | Principal missing coverage | |---|---:|---|---|---| | AI copilot | 4 | Structural only | Global company-admin contract | Overview tenant scope, chat validation/provider failures, confirmation ownership/expiry/single use, confirmed side effects. | | Attendance | 6 | Partial workflow | `AttendanceManagerTenantIsolationTest`, `EmployeeAttendanceTest` | Route permission matrix, expiry/replay of QR, device metadata, concurrency, full validation/error schemas. | | B2B invoices | 9 | Partial workflow | `B2BBillingLifecycleTest`, reception invoice scenario | Complete endpoint CRUD/state matrix, validation responses, PDF ownership, list filters/pagination, every permission level. | | Bookings | 22 | Partial workflow | `ReceptionAcceptanceTest`, `CheckInWorkflowTest`, `CheckOutWorkflowTest`, booking policy tests | Full CRUD HTTP contracts, all validation boundaries, concurrent API writes, bulk actions, exports/share/QR and complete authorization matrix. | | Business-date close | 11 | Partial workflow | `BusinessDateCloseTest`, reception close scenario | Every routed action response, invalid identifiers, route permissions, concurrency/locking, controller-level tenant probes. | | Cancellation policies | 7 | Structural only | Global contract and booking-policy service tests | HTTP CRUD, validation, default uniqueness, in-use deletion, tenant isolation and policy application end to end. | | Cancellation settings | 2 | Structural only | Global contract and API route contract | Read/update behavior, defaults, invalid values, tenant isolation and booking cancellation integration. | | Cashier shifts | 6 | Partial workflow | `CashierShiftTest`, reception shift scenario | Complete controller routes, permission failures, invalid IDs/payloads, concurrency and HTTP response contracts. | | Check-out folio review | 3 | Partial workflow | Checkout and deep-link suites | Discrepancy variants, approve/finalize permissions and idempotency, override audit, all validation responses. | | Clients | 9 | Structural only | Global backend/mobile contracts | CRUD behavior, duplicates, filters/pagination, booking relationships, protected deletion and tenant isolation. | | Deals | 9 | Structural only | Deal route-contract suites | CRUD behavior, item/date/price validation, image lifecycle, publishing visibility, tenant isolation and permissions. | | Departments | 6 | Partial workflow | `DepartmentAccessTest` | Department HTTP CRUD, assignment validation, cross-company membership, deletion safeguards and immediate permission effects. | | Documents | 12 | Structural only | Route/capability contract | Upload/download/delete, type/size/path validation, access grants, expiry/logging, storage cleanup and tenant isolation. | | Employee time | 8 | Structural only | Global contract | Shift/day-off CRUD, overlaps, occupancy calculations, employee/venue/company scope and permissions. | | ESTI | 2 | Structural only | Global contract; related fiscal tests do not cover these actions | Export contents/encoding, filters, invalid data, tenant scope and failure behavior. | | Facilities | 8 | Structural only | Global contract | CRUD, validation, venue ownership, duplicates, referenced deletion and tenant isolation. | | Financials | 5 | Structural only | Billing/fiscal tests cover underlying pieces only | Dashboard/revenue/expenses/P&L/reports endpoints, exact aggregates, date/currency filters, exports and permissions. | | Fiscal | 10 | Partial workflow | `CompanyFiscalApiTest`, billing lifecycle tests | Every web action response, throttling, all invalid transitions, provider timeout/malformed response and complete permissions. | | Fiscal receipts | 4 | Partial workflow | Fiscal API tests | Web list/show/download/receipt behavior, missing files, permissions, tenant isolation and stable error contracts. | | Front desk | 16 | Partial workflow | Check-in/out and deep-link suites | Remaining operation, room-block and night-audit routes; full validation, permissions, tenant scope and concurrency. | | Gantt chart | 4 | Structural only | Global contract | Date/venue filters, overlapping occupancy, timezone boundaries, tenant isolation, exports/data schema and empty state. | | Guest messaging | 9 | Structural only | Notification tests do not exercise these routes | Conversation CRUD, send/read, attachments, participants, unread state, authorization, tenant isolation and dispatch. | | Guest service | 15 | Partial workflow | `GuestServiceTest`, reception guest-service scenario | All routed package/handover/workboard actions, complete permission matrix, invalid transitions and response schemas. | | Guests | 6 | Partial workflow | `GuestRegistrationTest` | Full guest HTTP CRUD, duplicates, sensitive fields, documents, search/pagination, tenant isolation and deletion rules. | | Housekeeping | 36 | Partial workflow | `HousekeepingDashboardTest`, `HousekeepingTasksVenueScopeTest`, reception handoff | Schedule CRUD, optimization, inspections/checklists/lost-found/maintenance/QR/staff actions, transitions and permission matrix. | | Housekeeping staff | 10 | Structural only | Some housekeeping assignment tests only | Every staff action, status/workload calculations, venue and department scope, invalid assignment and permissions. | | Inspections | 9 | Structural only | Global contract | CRUD/lifecycle, checklist scoring, evidence, follow-up tasks, immutable completion, room/company scope. | | Integrations | 21 | Partial workflow | Channex unit/staging/webhook suites | Full controller endpoints, subscription/permission failures, registration and lifecycle actions, retries/throttling and remote errors. | | Inventory | 15 | Structural only | API route contract | CRUD, adjustments, insufficient/low stock, history/analytics, concurrency, venue/company scope and validation. | | Invoices | 11 | Partial workflow | Folio, fiscal and B2B billing tests cover related logic | Full invoice HTTP lifecycle, line validation/totals, PDF/send, immutable issued state, filters, permissions and tenant isolation. | | Message templates | 9 | Structural only | Notification rendering tests cover consumers only | Template CRUD, variables/locales/escaping, preview, protected defaults, validation and tenant isolation. | | Messaging | 10 | Structural only | Global contract | Conversation/participant lifecycle, send/read, unread counts, attachments, participant authorization and tenant isolation. | | Notification preferences | 5 | Structural only | Notification delivery tests do not cover preference routes | Defaults, channel toggles, quiet hours/timezone, toggle/reset/test operations and user/company isolation. | | Packages | 8 | Structural only | Global contract | CRUD/bulk delete, included items, pricing/duration, rate-plan ownership, availability, referenced deletion and tenant isolation. | | Payment | 1 | Partial workflow | Billing, fiscal and notification tests cover related flows | In-person route behavior, authorization, exact amount/currency, provider failure and duplicate submission. | | Payments | 7 | Partial workflow | Fiscal/billing/reception payment scenarios | Full list/show/PDF/delete behavior, refund/void states, permissions, tenant isolation and duplicate references. | | POS | 2 | Structural only | POS API route contract | Web catalog/order success, totals/tax/inventory/payment effects, validation, idempotency and tenant/venue scope. | | Pre-check-in | 4 | Structural only | Global contract | Eligibility, link lifecycle, guest submission, validation, duplicate completion, cancelled/foreign booking rejection. | | Products | 8 | Structural only | API route contract | CRUD/bulk delete, associations, price/stock/image validation, availability, deletion rules and tenant isolation. | | Profile | 3 | Structural only | Global contract | View/update/password success and validation, wrong password, uniqueness, session effects and mass assignment. | | Rates | 10 | Structural only | Global contract | CRUD/calendar/duplicate/calculate, date overlap, precision/currency, occupancy behavior and tenant/venue/object scope. | | Reception | 7 | Partial workflow | Reception, check-in/out and deep-link suites | Complete HTTP route/capability matrix, payload validation, concurrency and all controller side effects. | | Reporting | 7 | Structural only | Global contract | Aggregates, filters, empty data, exact totals, exports, tenant isolation and permissions. | | Reports | 4 | Structural only | Global contract | Builder fields/operators, scoped query, injection rejection, pagination/sorting, exports and large results. | | Role permissions | 4 | Partial workflow | `DepartmentAccessTest` covers permission evaluation | Controller CRUD, invalid permissions, protected/last-manager safeguards, tenant isolation and immediate effects. | | Roles | 7 | Partial workflow | Permission helper/department tests cover underlying access | Role HTTP CRUD, uniqueness, assignment/removal, protected deletion, tenant scope and member access changes. | | Room assignments | 4 | Partial workflow | Reception room-change and check-in tests | All route actions, invalid/out-of-service/conflicting rooms, assignment history, tenant scope and concurrency. | | Services | 8 | Structural only | Global contract | CRUD/bulk delete, category/price/duration, rate plan, booking requirements, deletion rules and tenant isolation. | | Settings | 2 | Partial workflow | Financial form and settings API route tests | Full web read/update behavior, every settings group, validation/defaults, secret protection and tenant/permission scope. | | Settlements | 3 | Structural only | Billing tests cover source transactions only | Generate/detail, exact inclusion/totals, duplicate generation, immutability, date filters and finance/tenant scope. | | Special workflows | 15 | Partial workflow | `SpecialWorkflowTest`, reception scenarios | Every controller action and response, invalid identifiers/payloads, permissions, repeated actions and complete audit assertions. | | Statistics | 8 | Structural only | Global contract | All aggregates, filters, empty state, date/timezone boundaries, exact totals, PDF/CSV and tenant scope. | | Stay modifications | 6 | Partial workflow | Reception room/date scenarios cover underlying behavior | All modification routes, availability/rate recalculation, invalid/checked-out cases, history/audit and tenant isolation. | | Stays | 12 | Partial workflow | Reception, check-in/out and deep-link suites | Full CRUD and bulk-delete HTTP contracts, protected deletion, guest/export operations, permissions and validation matrix. | | Subscriptions | 11 | Partial workflow | `B2BBillingLifecycleTest` | Every controller route/status/schema, payment-method endpoints, invalid plan/module inputs, throttling and permission matrix. | | Company switching | 1 | Structural only | Global contract | Valid membership switch, session/default workspace, foreign/nonexistent rejection and refreshed authorization context. | | Department switching | 1 | Structural only | Global contract | Assigned/unassigned/foreign/nonexistent department behavior, session state and refreshed permissions. | | Workspace switching | 1 | Structural only | Global contract | Ownership, valid switch, foreign/nonexistent rejection and dependent context refresh. | | Users | 8 | Structural only | API route and department-access tests | Web CRUD/invite/message/bulk delete, role/department validation, duplicate email, safeguards, delivery and tenant isolation. | | Venue objects | 9 | Partial workflow | Venue-object scoping unit tests and reception workflows | Full web CRUD/bulk delete/dashboard, validation, reference safeguards, status and cross-company controller requests. | | Venues | 8 | Partial workflow | Public venue tests cover different surface; scoping appears in reception | Company-admin CRUD/status/bulk delete, validation, workspace ownership, media/geolocation, active-booking deletion and permissions. | | Widgets | 1 | Partial workflow | Housekeeping widget preferences | General dashboard widget allowlist/order/defaults, invalid input and complete per-user/company isolation. | Audit conclusion: - **Full business-logic coverage:** 0 of 62 modules. - **Partial workflow coverage:** 29 of 62 modules. - **Structural-only coverage:** 33 of 62 modules. - Structural assertions currently pass, but database-backed suites cannot be certified in this environment until fresh migrations and the production-equivalent test database are operational. - Runtime line and branch coverage cannot currently be measured because neither Xdebug coverage nor PCOV is installed. CI must add a coverage driver before any quantitative coverage threshold is claimed. ### AC-CROSS — Cross-cutting release and test infrastructure - [ ] **AC-CROSS-001** Fresh test database migrates successfully from an empty database. - [ ] **AC-CROSS-002** Tests never connect to development or production databases. - [ ] **AC-CROSS-003** Factories create the minimum valid tenant, user, role, venue, and subscription state. - [ ] **AC-CROSS-004** Time-dependent tests use a frozen clock and do not depend on the current wall-clock time. - [ ] **AC-CROSS-005** External HTTP, email, SMS, storage, payment, fiscal, and channel-manager calls are faked in CI. - [ ] **AC-CROSS-006** Every acceptance test is deterministic and passes independently and in the full suite. - [ ] **AC-CROSS-007** Parallel execution does not cause shared-state, cache, file, or database collisions. - [ ] **AC-CROSS-008** Failed jobs, emitted events, notifications, and audit entries are asserted where applicable. - [ ] **AC-CROSS-009** Logs and error responses never expose passwords, tokens, secrets, certificates, SQL, stack traces, or local paths. - [ ] **AC-CROSS-010** Production configuration disables debug output while preserving stable HTML and JSON error contracts. - [ ] **AC-CROSS-011** All tests, assertions, failures, errors, skips, and risky tests are published as CI evidence. - [ ] **AC-CROSS-012** No required acceptance scenario is muted with `skip`, incomplete markers, exclusions, or unconditional early returns. ### AC-BE-BASE — Every non-Filament backend module Each scenario below must run for every company-admin module listed in the module matrix. - [ ] **AC-BE-BASE-001** Module has at least one intentional named route. - [ ] **AC-BE-BASE-002** Every route resolves to an existing public non-Filament controller action or an explicitly approved closure. - [ ] **AC-BE-BASE-003** Every method and URI combination is unique and static routes are not shadowed by dynamic parameters. - [ ] **AC-BE-BASE-004** Anonymous requests are rejected before controller execution. - [ ] **AC-BE-BASE-005** Authenticated non-company users are forbidden. - [ ] **AC-BE-BASE-006** Users without the route permission are forbidden. - [ ] **AC-BE-BASE-007** Users outside the required department scope are forbidden. - [ ] **AC-BE-BASE-008** Inactive, expired, suspended, or missing subscriptions are rejected as specified. - [ ] **AC-BE-BASE-009** Authorized company owners and permitted employees can reach the module. - [ ] **AC-BE-BASE-010** Valid list requests return only active-company records. - [ ] **AC-BE-BASE-011** Search, filter, sort, and pagination preserve tenant scope. - [ ] **AC-BE-BASE-012** Same-company identifiers can be read while foreign-company and nonexistent identifiers return the agreed non-disclosing response. - [ ] **AC-BE-BASE-013** Valid create requests persist only fields owned by the active company. - [ ] **AC-BE-BASE-014** Invalid create requests return validation errors and persist nothing. - [ ] **AC-BE-BASE-015** Valid updates change the intended record and cannot reassign tenant ownership. - [ ] **AC-BE-BASE-016** Invalid updates preserve the original record. - [ ] **AC-BE-BASE-017** Delete and bulk-delete affect only active-company records. - [ ] **AC-BE-BASE-018** Protected or referenced records cannot be deleted when business rules prohibit it. - [ ] **AC-BE-BASE-019** Duplicate submissions and repeated workflow actions are idempotent or return the documented conflict. - [ ] **AC-BE-BASE-020** Audit-sensitive mutations record actor, company, action, target, and timestamp. ### AC-BE-MOD — Backend module-specific scenarios | ID | Module | Mandatory automated scenarios | |---|---|---| | AC-BE-MOD-001 | AI copilot | Tenant-scoped overview; prompt validation; unauthorized tool/action rejection; confirmation token ownership, expiry, single-use behavior; no action before confirmation; provider timeout and malformed response handling. | | AC-BE-MOD-002 | Attendance | Valid clock-in/out; duplicate clock-in; clock-out without active attendance; invalid/expired QR; cross-company QR and venue-object rejection; manager visibility; timestamp and device metadata. | | AC-BE-MOD-003 | B2B invoices | Draft creation; exact totals/tax/currency; update restrictions; send-once delivery; mark-paid; cancellation; immutable issued values; cross-company access; PDF ownership. | | AC-BE-MOD-004 | Bookings | Create/read/update/cancel; availability conflict; invalid dates and guest counts; foreign venue/client/room rejection; totals; status transitions; repeated cancellation; concurrent booking protection. | | AC-BE-MOD-005 | Business-date close | Initialize; checklist; open-shift blocker; exception approval/resolution; completion; duplicate close; reversal/rerun; immutable audit summary; tenant isolation. | | AC-BE-MOD-006 | Cancellation policies | CRUD; default-policy uniqueness; invalid windows/percentages; foreign-company access; prevention of deleting an in-use policy; booking policy application. | | AC-BE-MOD-007 | Cancellation settings | Read/update; validation; defaults; tenant isolation; policy selection belongs to company; booking cancellation uses saved settings. | | AC-BE-MOD-008 | Cashier shifts | Open; prevent second active shift; cash-in/out; closed-shift mutation rejection; exact and variance close; handover; device/user/company isolation; immutable summary. | | AC-BE-MOD-009 | Check-out folio review | View tenant-owned stay; discrepancy calculation; block unpaid/invalid folio; approve override permissions; finalize once; foreign and invalid stay handling. | | AC-BE-MOD-010 | Clients | CRUD; email/phone validation; duplicate handling; company isolation; booking relationships; protected deletion; search and pagination. | | AC-BE-MOD-011 | Deals | CRUD; item validation; date and price rules; image upload validation/storage cleanup; publish toggle; catalog visibility; foreign resource references; tenant isolation. | | AC-BE-MOD-012 | Departments | CRUD; permission assignment; member assignment; wildcard intersection; removal effects; cross-company member/permission rejection; protected deletion. | | AC-BE-MOD-013 | Documents | Upload/type/size validation; list/show/download; access level; grants and revocation; expiry; access logging; storage cleanup; foreign-company and path-traversal rejection. | | AC-BE-MOD-014 | Employee time | Shift creation; overlap detection; day-off creation; invalid ranges; occupancy calculation; company/venue/employee scope; permission enforcement. | | AC-BE-MOD-015 | ESTI | Booking validation; CSV export encoding/content; configuration absence; RegiX insert/update/cancel; duplicate delivery; provider failure; tenant scope; secrets excluded. | | AC-BE-MOD-016 | Facilities | CRUD; venue ownership; duplicate rules; validation; foreign-company rejection; protected deletion; list filters. | | AC-BE-MOD-017 | Financials | Revenue, expense, and profit/loss totals; date/venue/currency filters; refunds and voids; tenant scope; finance permission; exact decimal calculations; exports. | | AC-BE-MOD-018 | Fiscal | Settings redaction; manager-only access; payment obligation creation; claim locking; completion idempotency; uncertain/reconcile flows; overpayment rejection; tenant isolation; provider failure. | | AC-BE-MOD-019 | Fiscal receipts | List/show/download; pending/status transitions; processing/printed/failed rules; retry behavior; linked payment/invoice; tenant and finance capability scope. | | AC-BE-MOD-020 | Front desk | Arrivals/departures/operations queues; filters and ordering; check-in/out readiness; room status; invalid transitions; tenant isolation; deep-link hardening. | | AC-BE-MOD-021 | Gantt chart | Date-range validation; occupancy placement; overlapping bookings; room/venue filters; timezone boundaries; tenant scope; empty result. | | AC-BE-MOD-022 | Guest messaging | Conversation creation; participants; send/read; unread counts; attachment validation; participant authorization; tenant scope; notification dispatch. | | AC-BE-MOD-023 | Guest service | Request CRUD; assignment; status transitions; packages; handover notes; priority/order; foreign stay/guest rejection; notifications; tenant isolation. | | AC-BE-MOD-024 | Guests | CRUD; identity/document validation; booking/stay association; duplicate matching; sensitive-field authorization; foreign-company rejection; export rules. | | AC-BE-MOD-025 | Housekeeping | Task and schedule CRUD; assign/start/complete transitions; invalid assignee/room; generated tasks; optimization; dashboard widgets; tenant/venue scope. | | AC-BE-MOD-026 | Housekeeping staff | Staff list; availability/status; assignment workload; foreign employee exclusion; venue/department scope; empty state. | | AC-BE-MOD-027 | Inspections | Create/assign/complete; checklist validation; score calculation; evidence upload; failed-item follow-up; room/company scope; immutable completion. | | AC-BE-MOD-028 | Integrations | Module entitlement; connection validation; prepare/sync/retry; rate limiting; webhook registration; approval/activation/pause/disconnect; environment separation; tenant scope; remote failures. | | AC-BE-MOD-029 | Inventory | CRUD; stock increase/decrease; insufficient stock; low-stock threshold; adjustment history; concurrent update protection; tenant/venue scope; analytics totals. | | AC-BE-MOD-030 | Invoices | CRUD; line/tax/total calculations; issue/send/paid/cancel states; overpayment; immutable issued invoice; PDF/download; tenant scope; idempotent delivery. | | AC-BE-MOD-031 | Message templates | CRUD; required variables; locale fallback; rendering/escaping; invalid placeholders; protected defaults; tenant scope; preview without delivery. | | AC-BE-MOD-032 | Messaging | Conversation/participant lifecycle; send/read; unread counts; participant-only access; cross-company rejection; duplicate participant; deletion rules. | | AC-BE-MOD-033 | Notification preferences | Defaults; channel toggles; quiet hours; invalid timezone/range; toggle-all/reset; test notification; user/company isolation. | | AC-BE-MOD-034 | Packages | CRUD; included item validation; price/duration rules; rate-plan ownership; availability; bulk delete; protected deletion; tenant/venue scope. | | AC-BE-MOD-035 | Payment | Initiation; success/cancel/notify callbacks; signature verification; exact amount/currency; duplicate callback idempotency; foreign booking rejection; provider timeout. | | AC-BE-MOD-036 | Payments | List/show; create/record; refunds/voids; receipt; status transitions; amount validation; cashier shift linkage; tenant/finance scope; duplicate provider reference. | | AC-BE-MOD-037 | POS | Catalog scope; order validation; line totals/tax; inventory effect; payment linkage; duplicate submission; closed order immutability; tenant/venue scope. | | AC-BE-MOD-038 | Pre-check-in | Eligible booking view; link generation/expiry; guest data submission; required fields; duplicate completion; cancelled/foreign booking rejection; status persistence. | | AC-BE-MOD-039 | Products | CRUD; type/company association; price/stock validation; image handling; availability; bulk delete; foreign association rejection; protected deletion. | | AC-BE-MOD-040 | Profile | View/update; email uniqueness; locale/timezone validation; password verification/change; wrong password; session/security effects; mass-assignment rejection. | | AC-BE-MOD-041 | Rates | CRUD; calendar; date ranges; occupancy rules; price calculation; duplicate plan; overlapping overrides; currency/precision; tenant/venue/object scope. | | AC-BE-MOD-042 | Reception | All AC-REC scenarios plus endpoint authorization, validation, invalid IDs, tenant isolation, and persisted side effects. | | AC-BE-MOD-043 | Reporting | Dashboard aggregates; date/venue filters; empty datasets; exact totals; tenant scope; permission checks; export content and encoding. | | AC-BE-MOD-044 | Reports | Custom report validation; allowed fields/operators; tenant-scoped query; sorting/pagination; export; injection rejection; large-result handling. | | AC-BE-MOD-045 | Role permissions | Role CRUD; permission assignment; wildcard behavior; protected roles; last-manager safeguard; cross-company rejection; immediate access effect. | | AC-BE-MOD-046 | Roles | CRUD; unique name per company; assignment/removal; invalid permissions; protected deletion; company isolation; member access changes. | | AC-BE-MOD-047 | Room assignments | Eligible-room list; assign/change/unassign; occupancy conflict; dirty/out-of-service room rejection; history; tenant/venue scope; concurrent assignment. | | AC-BE-MOD-048 | Services | CRUD; category/price/duration validation; rate-plan ownership; availability/booking requirement; bulk delete; tenant/venue scope. | | AC-BE-MOD-049 | Settings | Read/update each group; validation and defaults; secrets redacted/encrypted; venue/company ownership; cancellation/regional/ESTI settings; unauthorized update. | | AC-BE-MOD-050 | Settlements | Generate; exact included transactions/totals; date filters; duplicate generation; detail; immutable finalized batch; tenant/finance scope. | | AC-BE-MOD-051 | Special workflows | Walk-in; no-show; room move; group reservation; wake-up call; package handling; valid/invalid transitions; tenant isolation; audit trail. | | AC-BE-MOD-052 | Statistics | Booking/client/financial/occupancy aggregates; filters; empty state; timezone/date boundaries; exact calculations; PDF/CSV exports; tenant scope. | | AC-BE-MOD-053 | Stay modifications | View history; extend/shorten dates; availability; room/rate recalculation; invalid dates; checked-out stay rejection; audit history; tenant scope. | | AC-BE-MOD-054 | Stays | CRUD where allowed; guest association; room assignment; status transitions; checkout; ESTI export; bulk delete; protected deletion; tenant isolation. | | AC-BE-MOD-055 | Subscriptions | Plans/current/usage/modules; subscribe/upgrade/cancel; proration; renewal; grace/suspension; payment method setup/revoke; idempotency; company scope. | | AC-BE-MOD-056 | Company switching | Membership authorization; active company/session update; default workspace; foreign/nonexistent company rejection; permission context refresh. | | AC-BE-MOD-057 | Department switching | Membership authorization; active department update; permission context refresh; foreign/unassigned/nonexistent department rejection. | | AC-BE-MOD-058 | Workspace switching | Company ownership; active workspace update; foreign/nonexistent workspace rejection; dependent venue/context refresh. | | AC-BE-MOD-059 | Users | CRUD/invite; validation; roles/departments; duplicate email; self/last-manager safeguards; cross-company rejection; bulk delete; notification delivery. | | AC-BE-MOD-060 | Venue objects | CRUD; type/venue ownership; status/availability; bulk delete; booking/reference safeguards; cross-company rejection; dashboard counts. | | AC-BE-MOD-061 | Venues | CRUD; validation; status transitions; workspace/company ownership; bulk delete; active-booking safeguard; geolocation/media; tenant isolation. | | AC-BE-MOD-062 | Widgets | Allowed widget validation; ordering/visibility persistence; per-user/company isolation; unknown widget rejection; defaults. | ### AC-REC — Reception workflow scenarios - [ ] **AC-REC-001** Tenant separation prevents cross-company room and booking access. - [ ] **AC-REC-002** Availability prevents overlapping and concurrent double bookings. - [ ] **AC-REC-003** Booking creation persists correct company, venue, guest, room, dates, status, nights, and totals. - [ ] **AC-REC-004** Check-in activates the stay and occupies the assigned clean room. - [ ] **AC-REC-005** Check-in rejects early arrival without override, dirty room, missing registration, unpaid deposit, and cancelled booking. - [ ] **AC-REC-006** Room assignment/change validates availability, venue ownership, room status, and records history. - [ ] **AC-REC-007** Guest registration validates identity data and associates guests with the correct stay. - [ ] **AC-REC-008** Payments/deposits validate amount, currency, method, cashier shift, and duplicate reference. - [ ] **AC-REC-009** Folio charges, tax, payments, refunds, splits, and balance totals remain exact. - [ ] **AC-REC-010** Checkout requires a valid active stay and settled folio unless an authorized override is recorded. - [ ] **AC-REC-011** Checkout is idempotent and changes the room to the configured housekeeping status. - [ ] **AC-REC-012** Housekeeping handoff creates the correctly scoped task and assignment. - [ ] **AC-REC-013** Room-key issue, return, loss, and reassignment preserve custody history. - [ ] **AC-REC-014** Cashier-shift close calculates expected/actual totals and immutable variance. - [ ] **AC-REC-015** Business-date close blocks unresolved exceptions and duplicate closure. - [ ] **AC-REC-016** No-show processing releases inventory, applies charges, and cannot execute twice. - [ ] **AC-REC-017** B2B invoice routing uses the correct company, recipient, currency, and immutable totals. - [ ] **AC-REC-018** Guest-service requests support assignment, status transitions, handover, and tenant isolation. - [ ] **AC-REC-019** Arrival/departure queues return only scoped records in operational priority order. - [ ] **AC-REC-020** Invalid, injected, nonexistent, and foreign identifiers return non-disclosing errors. ### AC-MOB-BASE — Every mobile endpoint Each scenario below applies to every published mobile endpoint unless its OpenAPI operation explicitly documents a different contract. - [ ] **AC-MOB-BASE-001** Method and path resolve to one controller action without route shadowing. - [ ] **AC-MOB-BASE-002** Controller class and public action exist. - [ ] **AC-MOB-BASE-003** Operation exists in both synchronized OpenAPI files and both mobile Markdown references. - [ ] **AC-MOB-BASE-004** OpenAPI request and response schema references resolve. - [ ] **AC-MOB-BASE-005** Public endpoints work without a token; protected endpoints reject missing tokens with JSON `401`. - [ ] **AC-MOB-BASE-006** Invalid, expired, revoked, and malformed tokens return the documented JSON authentication error. - [ ] **AC-MOB-BASE-007** Insufficient role/capability returns the documented JSON `403` without data disclosure. - [ ] **AC-MOB-BASE-008** Nonexistent and foreign resource identifiers return the documented non-disclosing `404`/`403` behavior. - [ ] **AC-MOB-BASE-009** Valid request returns the documented status, content type, envelope, fields, types, formats, enums, and nullability. - [ ] **AC-MOB-BASE-010** Missing required fields and malformed values return JSON `422` with stable field errors. - [ ] **AC-MOB-BASE-011** Boundary values for length, quantity, amount, date, timezone, and enum rules are tested. - [ ] **AC-MOB-BASE-012** Unknown or non-fillable fields cannot overwrite ownership, roles, status, totals, or protected data. - [ ] **AC-MOB-BASE-013** List endpoints test empty, single-page, multi-page, filtered, sorted, and out-of-range results. - [ ] **AC-MOB-BASE-014** Mutations assert database state plus events, jobs, notifications, files, and external calls. - [ ] **AC-MOB-BASE-015** Repeated mutations are idempotent or return documented `409` behavior. - [ ] **AC-MOB-BASE-016** Throttled endpoints return JSON `429` with retry information. - [ ] **AC-MOB-BASE-017** Unexpected failures return stable JSON `5xx` without debug or secret leakage. - [ ] **AC-MOB-BASE-018** External timeouts, connection failures, invalid signatures, and malformed provider responses are handled without partial state. - [ ] **AC-MOB-BASE-019** Dates use documented ISO-8601 formats and correct timezone boundaries. - [ ] **AC-MOB-BASE-020** Money uses documented currency and precision without floating-point drift. ### AC-MOB-FAM — Mobile route-family scenarios | ID | Route family | Mandatory automated scenarios | |---|---|---| | AC-MOB-FAM-001 | Authentication | B2C/B2B registration; login; invalid credentials; verification; forgot/reset password; Google/Apple failures; 2FA enable/verify/disable; refresh rotation; logout/revocation; role switch; navigation permissions. | | AC-MOB-FAM-002 | Bonus points | Balance/statistics/history; earn/spend; insufficient balance; invalid amount; duplicate spend; user isolation; exact totals and pagination. | | AC-MOB-FAM-003 | Bookings | List/show/create/update/cancel/refund; QR lookup; check-in/out; availability conflict; validation; invalid transitions; duplicate operations; tenant/user authorization. | | AC-MOB-FAM-004 | Categories | List; booking-type filter; active/translated ordering; unknown booking type; empty state; stable schema. | | AC-MOB-FAM-005 | Company | Registration completion; profile; workspaces; bookings; users/invites/removal; invoices; venue/object creation; subscription and company scope; capability failures. | | AC-MOB-FAM-006 | Company admin | Every documented CRUD and workflow operation; company/venue scope; capability matrix; subscription enforcement; list filters/pagination; status and validation contracts. | | AC-MOB-FAM-007 | Deals | Public catalog/detail; unpublished/expired visibility; company CRUD/publish/image; item schema; tenant isolation; pagination and filters. | | AC-MOB-FAM-008 | Documents | Authenticated list/upload/show/download/delete; file/type/size validation; ownership/access level; missing file; storage cleanup; tenant isolation. | | AC-MOB-FAM-009 | ESTI | CSV exports; validation; RegiX operations; configuration status; encoding; tenant scope; duplicate request; provider timeout/error. | | AC-MOB-FAM-010 | Fiscal receipts | Pending/status; processing/printed/failed transitions; finance capability; tenant scope; idempotency; invalid transition and provider error. | | AC-MOB-FAM-011 | Geocode | Address, reverse, and coordinate validation; invalid/missing coordinates; no results; provider timeout; rate limit; normalized response. | | AC-MOB-FAM-012 | Location | Location detail; nonexistent identifier; localized response; stable hierarchy and schema. | | AC-MOB-FAM-013 | Locations | Suggest/search/advanced criteria; favorite toggle; query validation; filters; ordering; pagination; empty result; authenticated ownership. | | AC-MOB-FAM-014 | Locations by country | Required country; valid hierarchy; unknown country; active records only; localization and stable ordering. | | AC-MOB-FAM-015 | MyPOS | Online create/confirm/void/refund/cancel; cash-register lifecycle; signature verification; amount/currency; device ownership; duplicate callbacks; timeout/failure; no live CI calls. | | AC-MOB-FAM-016 | Places by location | Required location; valid hierarchy; foreign/unknown location; active records; localization; ordering and empty result. | | AC-MOB-FAM-017 | Time zones | Successful list; canonical identifiers; stable ordering; no duplicates; expected UTC-offset representation. | | AC-MOB-FAM-018 | Translations | Supported locale; fallback locale; missing key; resource scope; stable key/value schema; invalid locale rejection. | | AC-MOB-FAM-019 | User | Profile/preferences/password; favorites; bookings; notifications/preferences; reviews; transactions/invoices; security/2FA; location; feedback; device tokens; ownership and validation. | | AC-MOB-FAM-020 | Venues | List/search/detail/recommended/popular; availability; reviews; rooms/spots; favorite/review mutations; fiscal receipts; filters/pagination; unpublished visibility; capability and tenant scope. | ### AC-MOB-CLIENT — Mobile-client automated acceptance These scenarios run in the mobile repositories or a shared end-to-end harness and are required for mobile-team sign-off. - [ ] **AC-MOB-CLIENT-001** Generated/handwritten client compiles against the accepted OpenAPI version. - [ ] **AC-MOB-CLIENT-002** Unknown optional response fields do not break decoding. - [ ] **AC-MOB-CLIENT-003** Required fields, enums, nullable fields, dates, decimals, and pagination decode correctly. - [ ] **AC-MOB-CLIENT-004** Tokens are stored securely and attached only to intended API requests. - [ ] **AC-MOB-CLIENT-005** Concurrent expired-token requests perform one refresh and safely retry eligible requests. - [ ] **AC-MOB-CLIENT-006** Refresh failure clears credentials and returns the user to authentication. - [ ] **AC-MOB-CLIENT-007** `401`, `403`, `404`, `409`, `422`, `429`, and `5xx` responses render the agreed user state. - [ ] **AC-MOB-CLIENT-008** Offline startup, request interruption, reconnection, and retry preserve consistent UI and server state. - [ ] **AC-MOB-CLIENT-009** Mutation retry cannot duplicate bookings, payments, refunds, check-ins, check-outs, or fiscal operations. - [ ] **AC-MOB-CLIENT-010** Capability and subscription changes refresh navigation and disable unavailable actions. - [ ] **AC-MOB-CLIENT-011** File upload/download, QR scan, deep links, push tokens, and notification navigation work on supported platforms. - [ ] **AC-MOB-CLIENT-012** Locale, timezone, currency, accessibility, and empty/loading/error states are covered by UI automation. - [ ] **AC-MOB-CLIENT-013** Contract tests run against the production-equivalent environment for every release candidate. - [ ] **AC-MOB-CLIENT-014** iOS and Android smoke suites publish versioned reports linked from the sign-off record. ### Exception process An item may be declared not applicable only when all of the following are recorded in the release sign-off: - Scenario ID and technical reason. - Backend and mobile-team agreement. - Product/release-owner approval. - Confirmation that the exclusion does not weaken authentication, authorization, tenant isolation, payment integrity, fiscal compliance, or data protection. - A target release and owner when the exclusion is temporary. ## CI Evidence The CI job must retain the PHPUnit report and clearly identify which acceptance gate failed. Database connection failures are infrastructure failures and do not count as accepted, skipped, or passing tests.