Task_Reporter/openspec/specs/chat-room/spec.md

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:

  {
    "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. 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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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

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