Wf Laravel Create Api Endpoint Method

Preferred Deterministic Helper

• Use bash delphi-ai/tools/laravel_workflow_scaffold.sh --kind api-endpoint --name <endpoint_name> [--module <module>] [--output <path>] to scaffold the repeatable contract/route/security/test checklist before editing Laravel surfaces.
• Treat the helper as structure only; endpoint level selection, middleware/ability decisions, and contract design remain in this workflow.
• Use bash delphi-ai/tools/endpoint_performance_review_scaffold.sh --endpoint "<endpoint>" --pattern <exact-lookup|bounded-list|search|aggregation|mutation> [--lookup-key "<key>"] [--index "<index>"] [--output <path>] to make the query/access-path review explicit.
• Use bash delphi-ai/tools/exact_lookup_anti_pattern_audit.sh --path <touched-laravel-path> when exact-lookup or repository/controller lookup paths were changed.

Procedure

1. Profile alignment – select Operational / Coder with laravel scope, review the relevant project_constitution.md rules first, and note roadmap items only when strategic follow-up is in scope.
2. Define contract
   • Document request/response schema in foundation_documentation/domain_entities.md and the relevant module docs before coding.

• If the endpoint changes project-level inter-module rules, ownership boundaries, or systemic invariants, record the constitutional impact in the TODO and hand off to Strategic / CTO-Tech-Lead for the actual project_constitution.md update.
• For Cloudflare-fronted environments, define edge-vs-app responsibility explicitly:
  • Cloudflare: DDoS/WAF/bot/challenge/coarse IP controls.
  • Laravel: principal/account controls, tenant access, idempotency/replay, and deterministic API rejection contract.
• Classify endpoint protection level using the platform baseline:
  • L1 Core for low-risk/public/read-heavy routes.
  • L2 Balanced for most authenticated APIs and non-financial writes (default).
  • L3 High Protection for critical mutations (purchase|reservation|check-in|auth recovery|admin-sensitive writes).
• Record the level and security behavior in endpoint contracts (foundation_documentation/endpoints_mvp_contracts.md) and in the active tactical TODO decision/task gates.
• If the endpoint is a feed, confirm page-based pagination and decide whether an SSE /stream companion is required for deltas.
• Define deterministic machine-readable rejection/error mapping for security controls (rate_limited|soft_blocked|hard_blocked|idempotency_missing|idempotency_replayed|idempotency_expired|idempotency_malformed) plus transport metadata (retry_after, correlation_id, cf_ray_id when present).
• Enforce idempotency/replay policy by level:
  • L3: mandatory Idempotency-Key + replay-window validation on mutating requests.
  • L2: idempotency required for writes that can duplicate side effects.
  • L1: optional unless explicit route risk requires stricter protection.
• For partial updates (PATCH), default to direct resource-shaped payloads (object/list) and field-presence semantics; do not introduce envelope wrappers (for example paths) unless an explicit contract decision is documented.
• For Settings Kernel endpoints (/settings/values/{namespace}), nested fields must be sent as canonical dot-paths (example: default_origin.lat) unless a documented contract decision defines another format.
• Omitted fields remain unchanged.
• null is explicit clear only for nullable fields; null for non-nullable fields must return .

3. Route planning + domain matrix gate
   • Separate domain scope from auth scope (do not mix):
     • Domain decides which route sets are reachable (main domain → landlord; tenant domain → tenant + account).
     • Auth/abilities decide who may access a reachable endpoint (landlord user vs account user).
   • User access matrix (abilities still required):
     • Landlord users: landlord + tenant‑admin + tenant‑non‑admin + account routes.
     • Account users: tenant‑non‑admin + account routes only.
   • Choose the correct route file/group (tenant vs landlord vs account route files under routes/api/).
   • Tenant‑admin routes live under /admin/api/v1/... on tenant domains; tenant‑non‑admin remain /api/v1/....
   • Account routes stay under /api/v1/accounts/{account_slug}/... on tenant domains (already admin).
   • Apply middleware stacks (landlord, tenant, account) and ability requirements.
   • Ensure route-level anti-abuse/security middleware resolves to the approved L1|L2|L3 level and cannot downgrade below global minimum policy.
   • Ensure production origin path is Cloudflare-only (direct origin blocked by firewall/allowlist) and app-level trust-proxy configuration accepts forwarding headers only from trusted proxies.
   • If landlord and tenant share URI prefixes (example /admin/api/v1), enforce domain split explicitly and validate route registration with php artisan route:list.
   • If route groups use Route::domain('{...}'), controller signatures must include domain params before path params.
   • Public vs admin resource split (when applicable):
     • Public reads should live in tenant‑public routes; admin CRUD stays in tenant‑admin or account routes.
     • If tenant‑admin can create “on behalf of” an account/profile, ensure the owner is explicitly captured and that account‑admin views only their own records (no cross‑account bleed).
     • When public lists support account filtering, allow both account‑level and profile‑level filters if the domain uses 1:1 profiles.
4. Controller + service logic
   • Keep controllers lightweight (validation, request handling). Extract business rules into dedicated services/actions when logic grows.
   • Ensure validation rules enforce the documented bounds (P‑14).
5. Sanctum + policies

Outputs

• Updated routes, controllers, services, validation rules, and tests.
• Strategic roadmap follow-up entries only when the endpoint change alters broader sequencing or cross-stack planning.
• Strategic handoff recorded when project-level rules or invariants changed.
• Affected module docs reflecting the new endpoint and any touched legacy-scope canonicalization.

Validation

• Tests pass and manual endpoint checks succeed.
• The roadmap is updated only when strategic follow-up truly changed.
• Project-level contract implications are captured through strategic handoff to project_constitution.md when applicable.
• The affected module docs are the durable source of truth for the changed endpoint behavior.

• Update abilities/policies if new permissions are required. Document them in the affected module docs.
• Ability catalog sync gate: every newly introduced ability string must be registered in config/abilities.php when wildcard (*) permissions are expanded into explicit token abilities.