# API Reference (v1)

This document lists the application's API v1 endpoints, the parameters they accept, validation rules, authentication/authorization and brief response notes.

Base path: /api/v1

Authentication: uses Laravel Sanctum (bearer token). Endpoints marked with "Auth required" must be called with an authenticated user token.

## Authentication

### POST /auth/login
- Description: Authenticate user and return a bearer token.
- Public: yes
- Request body:
  - email: string, required, valid email
  - password: string, required
- Response (200):
  - token: string (plain-text token)
  - user: object ({ id, name, email })
  - roles: array of role names

### POST /auth/logout
- Description: Revoke current token (log out)
- Auth required: yes (auth:sanctum)
- Request body: none
- Response (200): { message: 'logged out' }

### GET /auth/me
- Description: Return the current authenticated user and related franchises
- Auth required: yes
- Response: user object including `franchises` relationship

## Templates

Templates are read-only via the public API endpoints.

### GET /templates
- Description: List all audit templates and their questions
- Auth required: yes
- Response: array of AuditTemplate objects (with questions)

### GET /templates/{template}
- Description: Show a single template grouped by sections
- Auth required: yes
- Path parameters:
  - template: numeric template id
- Response: object with fields: id, name, description, sections
  - sections: object where keys are section names and values are arrays of question objects
    - question object: { id, question, type, weight, options }

## Audits

These endpoints are role-aware. The controller scopes results according to the current user's role:
- admin: full view/list and scheduling
- auditor: assigned audits and responses
- franchise: only audits for the user's franchise(s)

### GET /audits
- Description: List audits (paginated). Results are scoped to the caller's role.
- Auth required: yes
- Response: paginated list of Audit resources (with relations). The controller eager loads relevant relations.

### GET /audits/assigned
- Description: Return audits assigned to the currently authenticated auditor (upcoming/pending)
- Auth required: yes (auditor role)
- Response: array of audits with status scheduled or in_progress

### POST /audits
- Description: Admins can schedule audits for a franchise using a template.
- Auth required: yes (admin via ScheduleAuditRequest)
- Request body (ScheduleAuditRequest validation rules):
  - franchise_id: required, integer, exists:franchises,id
  - template_id: required, integer, exists:audit_templates,id
  - auditor_id: nullable, integer, exists:users,id
  - scheduled_at: nullable, date
  - notes: nullable, string
- Response (201): created Audit object

### GET /audits/{audit}
- Description: Get a single audit with template.questions, responses. Authorization enforced via policy.
- Auth required: yes (view permission required)
- Path parameter:
  - audit: numeric audit id
- Response: Audit object with related template.questions, responses. (See controller to confirm included relations)

### POST /audits/{audit}/start
- Description: Mark an audit as in_progress and set the auditor (auditor-specific action)
- Auth required: yes (auditor must be authorized via policy)
- Path parameter: audit id
- Request body: none
- Response: { message: 'started', audit: <fresh object> }

### POST /audits/{audit}/responses
- Description: Save or update responses for an audit (auditor or admin)
- Auth required: yes (auditor or admin via SaveResponsesRequest)
- Path parameter: audit id
- Request body (SaveResponsesRequest validation rules):
  - responses: required, array, min:1
  - responses.*.question_id: required, integer, exists:audit_template_questions,id
  - responses.*.answer: nullable, string
  - responses.*.meta: nullable, array
  - responses.*.notes: nullable, string
  - responses.*.attachment_id: nullable, exists:attachments,id
- Behavior: each response record is created or updated (updateOrCreate by audit_id & question_id)

### POST /audits/{audit}/complete
- Description: Mark an audit complete, compute score and update status via AuditScoringService
- Auth required: yes (policy 'complete' required)
- Path parameter: audit id
- Request body: none
- Response: { message: 'completed', score, audit }

## Uploads

### POST /uploads/presign
- Description: Generate a presigned upload URL (S3) or a server-side path fallback
- Auth required: yes
- Request body:
  - filename: required
  - mime: required
  - size: nullable|integer
- Response: { path: string, url: string | null }

### POST /uploads/register
- Description: Register an uploaded file after client upload
- Auth required: yes
- Request body:
  - path: required
  - filename: required
  - mime: required
  - size: nullable|integer
- Behavior: creates an Attachment record with `uploaded_by` set to authenticated user
- Response: { attachment: <Attachment object> }

## Notes and Recommendations
- Authorization: Most endpoints require authentication (via Sanctum). Important admin/auditor checks are enforced by FormRequest `authorize()` methods and policies.
- Validation: For several endpoints, validation rules are implemented via FormRequest classes under `app/Http/Requests/Api/V1`.
- If you want, I can extend this document with example curl requests and example JSON responses for each endpoint.