# chat-room Specification

## Purpose
TBD - created by archiving change add-chat-room-management. Update Purpose after archive.
## Requirements
### Requirement: System Administrator Role
The system SHALL recognize ymirliu@panjit.com.tw as a system administrator with super-user privileges across all chat rooms, including the ability to override access controls, manage any room, and perform administrative operations.

#### Scenario: Identify system administrator
- **WHEN** a user with email "ymirliu@panjit.com.tw" authenticates
- **THEN** the system SHALL flag this user as a system administrator
- **AND** grant elevated privileges for all room operations
- **AND** log all admin actions for audit purposes

#### Scenario: Admin bypass room restrictions
- **WHEN** a system administrator attempts any room operation
- **THEN** the system SHALL allow the operation regardless of:
  - Room membership status
  - Room status (active, resolved, archived)
  - Normal role restrictions
- **AND** record the admin override in audit log

### Requirement: Create Incident Room
The system SHALL allow authenticated users to create a new incident room with metadata including title, incident type, severity level, location, and description. Each room SHALL be assigned a unique identifier and timestamp upon creation.

#### Scenario: Create room for equipment failure incident
- **WHEN** an authenticated user sends `POST /api/rooms` with body:
  ```json
  {
    "title": "Line 3 Conveyor Belt Stopped",
    "incident_type": "equipment_failure",
    "severity": "high",
    "location": "Building A, Line 3",
    "description": "Conveyor belt motor overheating, production halted"
  }
  ```
- **THEN** the system SHALL create a new incident_rooms record with:
  - Unique room_id (UUID)
  - Provided metadata fields
  - Status set to "active"
  - created_by set to current user's ID
  - created_at timestamp
- **AND** automatically add the creator as a room member with "owner" role
- **AND** return status 201 with the room details including room_id

#### Scenario: Create room with missing required fields
- **WHEN** a user attempts to create a room without required fields (title, incident_type)
- **THEN** the system SHALL return status 400 with validation error details

#### Scenario: Create room without authentication
- **WHEN** an unauthenticated request is sent to `POST /api/rooms`
- **THEN** the system SHALL return status 401 with "Authentication required"

### Requirement: List and Filter Incident Rooms
The system SHALL provide endpoints to list incident rooms with filtering capabilities by status, incident type, severity, date range, and user membership.

#### Scenario: List all active rooms for current user
- **WHEN** an authenticated user sends `GET /api/rooms?status=active`
- **THEN** the system SHALL return all active rooms where the user is a member
- **AND** include room metadata (title, type, severity, member count, last activity)
- **AND** sort by last_activity_at descending (most recent first)

#### Scenario: Filter rooms by incident type and date range
- **WHEN** a user sends `GET /api/rooms?incident_type=quality_issue&created_after=2025-01-01&created_before=2025-01-31`
- **THEN** the system SHALL return rooms matching ALL filter criteria
- **AND** only include rooms where the user is a member

#### Scenario: Search rooms by title or description
- **WHEN** a user sends `GET /api/rooms?search=conveyor`
- **THEN** the system SHALL return rooms where title OR description contains "conveyor" (case-insensitive)
- **AND** highlight matching terms in the response

### Requirement: Manage Room Membership
The system SHALL allow room owners and members with appropriate permissions to add or remove members and assign roles (owner, editor, viewer). Room owners SHALL be able to transfer ownership to another member. System administrators SHALL have override capabilities for all membership operations.

#### Scenario: Add member to existing room
- **WHEN** a room owner sends `POST /api/rooms/{room_id}/members` with:
  ```json
  {
    "user_id": "user123",
    "role": "editor"
  }
  ```
- **THEN** the system SHALL create a room_members record with specified role
- **AND** update room's member_count
- **AND** record added_by and added_at timestamp
- **AND** return status 200 with updated member list

#### Scenario: Remove member from room
- **WHEN** a room owner sends `DELETE /api/rooms/{room_id}/members/{user_id}`
- **THEN** the system SHALL soft-delete the membership (set removed_at timestamp)
- **AND** update room's member_count
- **AND** return status 200

#### Scenario: Non-owner attempts to add member
- **WHEN** a room member without owner role attempts to add another member
- **THEN** the system SHALL return status 403 with "Insufficient permissions"
- **UNLESS** the user is a system administrator, in which case the operation succeeds

#### Scenario: Change member role
- **WHEN** a room owner sends `PATCH /api/rooms/{room_id}/members/{user_id}` with:
  ```json
  {
    "role": "viewer"
  }
  ```
- **THEN** the system SHALL update the member's role
- **AND** record the change in audit log

#### Scenario: Transfer room ownership
- **WHEN** a room owner sends `POST /api/rooms/{room_id}/transfer-ownership` with:
  ```json
  {
    "new_owner_id": "user456"
  }
  ```
- **THEN** the system SHALL verify the new owner is an existing room member
- **AND** update the new owner's role to "owner"
- **AND** change the previous owner's role to "editor"
- **AND** record the ownership transfer in audit log with timestamp
- **AND** return status 200 with updated member list

#### Scenario: Admin override - Add member to any room
- **WHEN** a system administrator (ymirliu@panjit.com.tw) adds a member to any room
- **THEN** the system SHALL allow the operation regardless of room membership
- **AND** record the admin action in audit log

### Requirement: Update Room Status and Metadata
The system SHALL allow room owners to update room metadata and transition room status through its lifecycle (active → resolved → archived).

#### Scenario: Mark room as resolved
- **WHEN** a room owner sends `PATCH /api/rooms/{room_id}` with:
  ```json
  {
    "status": "resolved",
    "resolution_notes": "Replaced motor, production resumed"
  }
  ```
- **THEN** the system SHALL update status to "resolved"
- **AND** set resolved_at timestamp
- **AND** store resolution_notes
- **AND** keep room accessible in read-only mode for members

#### Scenario: Update room metadata
- **WHEN** a room owner sends `PATCH /api/rooms/{room_id}` with:
  ```json
  {
    "severity": "critical",
    "description": "Updated: Fire hazard detected"
  }
  ```
- **THEN** the system SHALL update only the provided fields
- **AND** record the update in room_activity log
- **AND** set last_updated_at timestamp

#### Scenario: Archive resolved room
- **WHEN** a room owner sends `PATCH /api/rooms/{room_id}` with status "archived"
- **AND** the room is already in "resolved" status
- **THEN** the system SHALL update status to "archived"
- **AND** set archived_at timestamp
- **AND** make room read-only for all members

#### Scenario: Invalid status transition
- **WHEN** attempting to change status from "active" directly to "archived"
- **THEN** the system SHALL return status 400 with "Invalid status transition"

### Requirement: Room Access Control
The system SHALL enforce role-based access control for all room operations based on user membership and assigned roles. System administrators SHALL have full access to all rooms regardless of membership status.

#### Scenario: Access room details as member
- **WHEN** a room member sends `GET /api/rooms/{room_id}`
- **THEN** the system SHALL return full room details including:
  - Room metadata
  - Member list with roles
  - Activity summary
  - Current user's role and permissions

#### Scenario: Access room without membership
- **WHEN** a non-member sends `GET /api/rooms/{room_id}`
- **THEN** the system SHALL return status 403 with "Not a member of this room"
- **UNLESS** the user is a system administrator, in which case full access is granted

#### Scenario: List user's permissions in room
- **WHEN** a member sends `GET /api/rooms/{room_id}/permissions`
- **THEN** the system SHALL return their role and specific permissions:
  - Owner: all operations including ownership transfer
  - Editor: read, write messages, upload files
  - Viewer: read only
  - Admin: all operations plus system override capabilities

#### Scenario: Admin access to all rooms
- **WHEN** a system administrator (ymirliu@panjit.com.tw) sends `GET /api/rooms?all=true`
- **THEN** the system SHALL return ALL rooms in the system, not just rooms where admin is a member
- **AND** include an "is_admin_view" flag in the response

### Requirement: Room Templates
The system SHALL support predefined room templates for common incident types to streamline room creation with preset metadata and initial members.

#### Scenario: Create room from template
- **WHEN** a user sends `POST /api/rooms` with:
  ```json
  {
    "template": "equipment_failure",
    "title": "Molding Machine #5 Down",
    "location": "Building B"
  }
  ```
- **THEN** the system SHALL create room with:
  - Preset incident_type from template
  - Default severity level from template
  - Auto-assigned team members based on template configuration
  - Template-specific metadata fields

#### Scenario: List available templates
- **WHEN** a user sends `GET /api/room-templates`
- **THEN** the system SHALL return available templates with:
  - Template name and description
  - Default values for each template
  - Required additional fields