Chapter 4 - Use Cases and Acceptance Criteria

UC-AUTH-001 — User Login

• Actors: Any user.
• Preconditions: Account exists; user may be suspended check via middleware.
• Trigger: User visits login route.
• Main success: email/password → session cookie set → redirect to dashboard.
• Alt: failed → errors.
• Acceptance Criteria:
• When entering valid credentials → user navigates to /dashboard (or first available page).
• When invalid → form shows Laravel validation errors and no session is created. Code evidence: AuthenticatedSessionController.

UC-WS-001 — Create Workspace

• Actors: Admin/company.
• Main success: create name/description → new workspace row + default tasks stages + bug statuses.
• ACCEPT:
• Given no workspace exists for user, creating works within plan limit in SaaS.
• Workspace must appear in switcher.
• Deleting workspace sets owner's current_workspace_id to null. Evidence: WorkspaceService:174.

UC-PROJECT-001 — Project Task Management Kanban

• Actors: Manager/Member.
• Main success: move a task across board stages; audit/TaskEvent updated to assigned/submitted/returned/approved state depending on stage name.
• Acceptance:
• Moving task from Review to Completed logs "approved" when stage name contains "approved"/"completed".
• Movable by assigned user/manager. Evidence: TaskObserver event-type name-match.

UC-EMAIL-001 — Inbound Email → AI triage → Task

sequenceDiagram
  U->>Gmail: incoming mail
  Cron->>EmailListenerService: sync-all minute
  EmailListenerService->>Workspace: filter
  alt filter passes
  EmailListenerService->>Project: case_ref / domain match
  alt no project but auto create enabled
  EmailListenerService->>Project: create project + manager/lawyer assignment
  end
  EmailListenerService->>DB: create EmailMessage
  EmailListenerService->>AI: EmailAIAssignmentService.analyzeAndAssign (if AIEnabled)
  alt AI returns success
  AI->>DB: create Task/Bug/Project + assignment
  AI->>Events: TaskAssigned/ProjectMemberAssigned
  Events->>Slack/Telegram/WhatsApp/Email: notification
  else AI fails
  AI->>DB: Fallback EmailAutomationService rules
  end
  EmailListenerService->>Gmail: mark Seen
  end

• Acceptance:
• When email from whitelisted domain only, an email record + at least 1 task created when enabled.
• When email not allowed, no records written; email gets marked seen.
• AI failures must not cause unprocessed email; rules-based branch populates DB.

UC-INVOICE-001 — Invoice lifecycle & payment

• Main flow: Create invoice → save items/tax → mark paid OR send token link → public page receives enabled gateways → user pays via gateway → callback updates payment & invoice → success page.
• ACCEPT:
• Public link /invoices/payment/{token} shows status + gateway list.
• Callback records a payments row and updates paid_amount + status where success.
• When callback not configured in application (stub route), developer attention needed.

UC-TS-001 — Approve timesheet

• ACCEPT:
• Pending timesheet can be approved by manager.
• Total hours recomputed.

UC-AI-001 — Workspace in-app AI chat ability

• Main flow: Open agent → ask question → response cites workspace context → persisted.
• ACCEPT:
• Provides response from Gemini.
• Exceeds 30 messages/hour → blocked.
• Exceeds monthly cost limit → blocked & banner warning.

UC-EVAL-001 — Performance firm evaluation

• Main flow: Load /evaluations → aggregate performance analytics across active users and projects.
• ACCEPT:
• Users with no performance_metrics data render fallback modules. No depredations occur.

UC-EXPENSE-001 — Expense approval chain

• Main flow: create expense → approver approves → message board → notifications via Slack/TG → budget summary updates.
• ACCEPT:
• status approved.
• expense attaches workflow entry and approval audit.