# 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, description, and optional LOT batch numbers. Each room SHALL be assigned a unique identifier and timestamp upon creation.

#### Scenario: Create room with LOT numbers
- **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",
    "lots": ["LOT-2024-001"]
  }
  ```
- **THEN** the system SHALL create a new incident_rooms record with:
  - Unique room_id (UUID)
  - Provided metadata fields including lots
  - 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 and lots

### 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. The system SHALL automatically exclude rooms with ARCHIVED status from listing results for non-admin users, ensuring archived rooms are only visible to system administrators.

#### 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
- **AND** include room metadata (title, type, severity, member count, last activity)
- **AND** sort by last_activity_at descending (most recent first)

#### Scenario: Non-admin user lists rooms without status filter
- **WHEN** a non-admin user sends `GET /api/rooms` without status parameter
- **THEN** the system SHALL return rooms with status "active" or "resolved" only
- **AND** automatically exclude archived rooms from results

### 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 and editors to update room metadata including LOT batch numbers, and allow owners to transition room status through its lifecycle (active -> resolved -> archived).

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

### 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: Admin Permanent Room Deletion
The system SHALL provide system administrators with the ability to permanently delete rooms, including all associated data (members, messages, files, reports). This operation is irreversible and restricted to system administrators only.

#### Scenario: Admin permanently deletes a room
- **WHEN** a system administrator sends `DELETE /api/rooms/{room_id}/permanent`
- **THEN** the system SHALL verify the user is ymirliu@panjit.com.tw
- **AND** hard delete the room record from incident_rooms table
- **AND** cascade delete all room_members records
- **AND** cascade delete all messages and related reactions/edit_history
- **AND** cascade delete all room_files records
- **AND** delete associated files from MinIO storage
- **AND** cascade delete all generated_reports records
- **AND** delete associated report files from MinIO storage
- **AND** broadcast disconnect event to any active WebSocket connections in the room
- **AND** return status 200 with `{"message": "Room permanently deleted"}`

#### Scenario: Non-admin attempts permanent deletion
- **WHEN** a non-admin user sends `DELETE /api/rooms/{room_id}/permanent`
- **THEN** the system SHALL return status 403 with "Only system administrators can permanently delete rooms"

#### Scenario: Permanent delete non-existent room
- **WHEN** a system administrator sends `DELETE /api/rooms/{room_id}/permanent` for a non-existent room
- **THEN** the system SHALL return status 404 with "Room not found"

### Requirement: Hide Archived Rooms from Non-Admin Users
The system SHALL hide rooms with ARCHIVED status from non-admin users in all listing operations, ensuring historical/archived data is only visible to system administrators.

#### Scenario: Non-admin lists rooms with any filter
- **WHEN** a non-admin user sends `GET /api/rooms` with any status filter (including no filter)
- **THEN** the system SHALL exclude all rooms with status "archived" from the response
- **AND** only return rooms with status "active" or "resolved"

#### Scenario: Non-admin explicitly requests archived rooms
- **WHEN** a non-admin user sends `GET /api/rooms?status=archived`
- **THEN** the system SHALL return an empty list
- **AND** return total count of 0

#### Scenario: Admin can view archived rooms
- **WHEN** a system administrator sends `GET /api/rooms?status=archived`
- **THEN** the system SHALL return all archived rooms
- **AND** include full room details

#### Scenario: Admin views all rooms including archived
- **WHEN** a system administrator sends `GET /api/rooms` without status filter
- **THEN** the system SHALL return all rooms regardless of status
- **AND** include archived rooms in the response

### Requirement: LOT Batch Number Tracking
The system SHALL support tracking multiple LOT (batch numbers) associated with each incident room. LOT information helps identify affected product batches for quality traceability and recall purposes.

#### Scenario: Create room with LOT numbers
- **WHEN** an authenticated user sends `POST /api/rooms` with body:
  ```json
  {
    "title": "Quality Issue on Line 3",
    "incident_type": "quality_issue",
    "severity": "high",
    "location": "Building A",
    "lots": ["LOT-2024-001", "LOT-2024-002"]
  }
  ```
- **THEN** the system SHALL create the room with the provided LOT numbers
- **AND** store lots as a JSON array in the database
- **AND** return the room details including the lots array

#### Scenario: Create room without LOT numbers
- **WHEN** an authenticated user creates a room without specifying lots
- **THEN** the system SHALL create the room with an empty lots array
- **AND** allow lots to be added later via update

#### Scenario: Update room LOT numbers
- **WHEN** an authenticated user with editor or owner role sends `PATCH /api/rooms/{room_id}` with:
  ```json
  {
    "lots": ["LOT-2024-001", "LOT-2024-002", "LOT-2024-003"]
  }
  ```
- **THEN** the system SHALL replace the existing lots with the new array
- **AND** update last_updated_at timestamp
- **AND** return the updated room details

#### Scenario: Add single LOT to existing room
- **WHEN** an authenticated user with editor or owner role sends `POST /api/rooms/{room_id}/lots` with:
  ```json
  {
    "lot": "LOT-2024-004"
  }
  ```
- **THEN** the system SHALL append the LOT to the existing lots array
- **AND** prevent duplicate LOT entries
- **AND** return the updated lots array

#### Scenario: Remove single LOT from room
- **WHEN** an authenticated user with editor or owner role sends `DELETE /api/rooms/{room_id}/lots/{lot_id}`
- **THEN** the system SHALL remove the specified LOT from the array
- **AND** return the updated lots array

#### Scenario: Viewer cannot modify LOT numbers
- **WHEN** a user with viewer role attempts to update LOT numbers
- **THEN** the system SHALL return status 403 with "Insufficient permissions"

#### Scenario: LOT numbers displayed in room details
- **WHEN** a user sends `GET /api/rooms/{room_id}`
- **THEN** the response SHALL include the lots array
- **AND** lots SHALL be returned in the order they were added

---

### Requirement: Action Bar Layout
The chat room interface SHALL provide an action bar near the message input area for quick access to common operations.

#### Scenario: Action bar displays common actions
- **WHEN** user views a chat room
- **THEN** an action bar is displayed above or beside the message input
- **AND** the action bar includes: upload file, generate report, add member buttons

#### Scenario: Action bar toggle on mobile
- **WHEN** user is on a mobile device
- **THEN** the action bar buttons can be collapsed/expanded
- **AND** a single toggle button reveals the full action options

### Requirement: Message Copy Action
Users SHALL be able to copy individual message content to clipboard.

#### Scenario: Copy message content
- **WHEN** user hovers over a message
- **THEN** a copy button appears
- **AND** clicking the button copies the message content to clipboard
- **AND** a success toast notification is shown

### Requirement: Notification Settings
Users SHALL be able to configure notification preferences for the chat room.

#### Scenario: Configure notification settings
- **WHEN** user accesses notification settings
- **THEN** user can enable/disable sound notifications
- **AND** user can enable/disable browser push notifications
- **AND** user can enable/disable vibration (on supported devices)