Task_Reporter/openspec/changes/archive/2025-12-08-improve-file-display-and-timezone/specs/realtime-messaging/spec.md

MODIFIED Requirements

Requirement: Message Types and Formatting

The system SHALL support various message types including text, image references, file references, and structured data for production incidents, with inline display of file attachments in the chat view.

Scenario: Text message with mentions

• WHEN a user sends a message with @mentions

  {
    "content": "@maintenance_team Please check Line 3 immediately",
    "mentions": ["maintenance_team@panjit.com.tw"]
  }
  

• THEN the system SHALL parse and store mentions
• AND potentially trigger notifications to mentioned users

Scenario: Image reference message display

• WHEN a message with message_type=image_ref is rendered in the chat
• THEN the client SHALL display:
  • A thumbnail of the image (max 300px width)
  • The message content/caption below the image
  • Sender name and timestamp
  • A click-to-expand functionality
• AND clicking the thumbnail SHALL open a full-size preview lightbox

Scenario: File reference message display

• WHEN a message with message_type=file_ref is rendered in the chat
• THEN the client SHALL display:
  • A file type icon (PDF, document, log, etc.)
  • The filename
  • File size in human-readable format
  • A download button/link
  • The message content/caption
  • Sender name and timestamp

Scenario: Structured incident data

• WHEN reporting specific incident metrics

  {
    "type": "message",
    "message_type": "incident_data",
    "content": {
      "temperature": 85,
      "pressure": 120,
      "production_rate": 450,
      "timestamp": "2025-11-17T10:15:00Z"
    }
  }
  

• THEN the system SHALL store structured data as JSON
• AND enable querying/filtering by specific fields later

Requirement: GMT+8 Timezone Display

The frontend SHALL display all timestamps in GMT+8 (Asia/Taipei) timezone for consistent user experience across all browsers and all parts of the application.

Scenario: Message timestamp in GMT+8

• WHEN a message is displayed in the chat room
• THEN the timestamp SHALL be formatted in GMT+8 timezone
• AND use format "HH:mm" for today's messages
• AND use format "MM/DD HH:mm" for older messages

Scenario: Room list timestamps in GMT+8

• WHEN the room list is displayed
• THEN the "last updated" time SHALL be formatted in GMT+8 timezone

Scenario: File upload timestamp in GMT+8

• WHEN a file is displayed in chat or file drawer
• THEN the upload timestamp SHALL be formatted in GMT+8 timezone

Scenario: Report generation timestamp in GMT+8

• WHEN report metadata is displayed
• THEN the "generated at" timestamp SHALL be formatted in GMT+8 timezone

ADDED Requirements

Requirement: Image Preview Lightbox

The frontend SHALL provide a lightbox component for viewing full-size images from chat messages.

Scenario: Open image lightbox

• WHEN user clicks on an image thumbnail in the chat
• THEN a modal overlay SHALL appear
• AND the full-size image SHALL be displayed centered
• AND a loading indicator SHALL show while image loads
• AND the image SHALL be constrained to fit the viewport

Scenario: Close image lightbox

• WHEN the lightbox is open
• THEN user can close it by:
  • Clicking the X button
  • Pressing the ESC key
  • Clicking outside the image
• AND focus SHALL return to the chat

Scenario: Image lightbox with download

• WHEN the lightbox is open
• THEN a download button SHALL be visible
• AND clicking it SHALL download the original file

Requirement: File Type Icons

The frontend SHALL display appropriate icons for different file types in chat messages and file drawer.

Scenario: PDF file icon

• WHEN a PDF file is displayed
• THEN a PDF icon (red/document style) SHALL be shown

Scenario: Log/text file icon

• WHEN a .log or .txt file is displayed
• THEN a text file icon SHALL be shown

Scenario: Excel file icon

• WHEN an Excel file (.xlsx, .xls) is displayed
• THEN a spreadsheet icon (green) SHALL be shown

Scenario: Generic file icon

• WHEN a file with unknown type is displayed
• THEN a generic document icon SHALL be shown

Requirement: Upload Preview

The frontend SHALL show a preview of the file being uploaded before the message is sent.

Scenario: Image upload preview

• WHEN user selects an image file for upload
• THEN a preview thumbnail SHALL be displayed in the input area
• AND user can add a caption/description
• AND user can cancel the upload before sending
• AND a send button confirms the upload

Scenario: File upload preview

• WHEN user selects a non-image file for upload
• THEN file info (name, size, type icon) SHALL be displayed
• AND user can add a description
• AND user can cancel or confirm